Rendering Obsidian Canvas (.canvas)

The critical parser gap: geometry is dropped

The current Node struct (canvas.go:13-20) keeps only
id/type/text/file/url/color. The .canvas JSON carries x/y/width/height on
every node and fromSide/toSide/color on every edge — encoding/json silently
discards them because there are no struct fields. The Telegram bot never needed
geometry (it renders a linear menu), but a spatial board cannot exist without it.
This is the single most important prerequisite. See §5.1 (Step Zero).

The stub today

{# views.html:527-541 #}
{% func UnsupportedFile(ctx *Ctx) %}
  ...
  {% if ctx.UnsupportedFileExt == ".canvas" %}
  <p>Canvas files are not supported yet.</p>
  ...
{% endfunc %}

Reached from endpoint.go:96-103:

if ext := unsupportedFileExt(resp.Note.Path); ext != "" {
    dtCtx := buildDefaultTemplateCtx(req, layoutParams, resp, env)
    dtCtx.UnsupportedFileExt = ext
    defaulttemplate.WriteRender(ctx, dtCtx)
    return nil, nil
}

Data flow

.canvas file (synced)
   │  loader.go:registerRawFile → obsidiancanvas.Parse (geometry now kept)
   ▼
model.NoteView.Canvas  ── x/y/w/h, sides, colors
   │
   ▼  rendernotepage.Resolve  (RE-APPLY Free / CanReadNote — see §8)
   │
   ▼  endpoint.go  (replace the short-circuit branch)
   │     canvasdata.Build(canvas, nvs, env)   ← NEW: pre-resolve file nodes
   │       • text  → render markdown to HTML
   │       • file  → GetByPath(node.File) → note.HTML  (access-checked)
   │              or image → AssetReplaces[...].URL  (/_assets/)
   │       • link  → url passthrough
   ▼
views.html  CanvasBoard(ctx)  →  <div data-canvas> + JSON island + <noscript>
   │  + buildDefaultTemplateCtx appends /assets/canvas.js when note.HasCanvas()
   ▼
browser:  assets/canvas/src/index.ts
   │  parse island → position nodes → draw edges → pan/zoom/fit
   ▼
spatial board (theme-aware via window.trip2g_theme_listeners)

Why this approach. It matches an existing, documented seam, keeps SSR HTML
crawlable, makes the heavy interactivity progressive enhancement, and reuses the
proven embed/asset machinery for file nodes. The visual board only needs the
client when geometry-driven layout is wanted; the <noscript> ordered list still
conveys the content.

5.1 Step Zero — extend the parser (additive, non-breaking)

internal/obsidiancanvas/canvas.go — add geometry fields. Additive only, so
the Telegram consumer (handletgcanvasupdate) keeps compiling unchanged:

type Node struct {
    ID     string `json:"id"`
    Type   string `json:"type"`
    Text   string `json:"text,omitempty"`
    File   string `json:"file,omitempty"`
    URL    string `json:"url,omitempty"`
    Color  string `json:"color,omitempty"`
    // NEW — JSON Canvas geometry, currently dropped:
    X      int    `json:"x"`
    Y      int    `json:"y"`
    Width  int    `json:"width"`
    Height int    `json:"height"`
    Label  string `json:"label,omitempty"` // for type="group"
    Subpath string `json:"subpath,omitempty"` // file#heading anchor
}

type Edge struct {
    ID       string `json:"id"`
    FromNode string `json:"fromNode"`
    ToNode   string `json:"toNode"`
    Label    string `json:"label,omitempty"`
    // NEW:
    FromSide string `json:"fromSide,omitempty"` // top|right|bottom|left
    ToSide   string `json:"toSide,omitempty"`
    Color    string `json:"color,omitempty"`
}

No change to Parse, the index maps, or any existing method — pure data
widening. Verify the bot still builds (go test ./internal/case/handletgcanvasupdate/...).

5.2 New package: internal/canvasview (build the data island)

A pure builder (like templateviews, no IO state) that turns a parsed
*obsidiancanvas.Canvas + the note set into a serializable island. Pre-resolving
file nodes here mirrors the bot's renderFileNode (render.go:41-57):

package canvasview

type Node struct {
    ID, Type           string
    X, Y, Width, Height int
    Color              string `json:",omitempty"`
    Text               string `json:",omitempty"` // rendered HTML for text nodes
    HTML               string `json:",omitempty"` // resolved note HTML for file nodes
    URL                string `json:",omitempty"` // permalink (file→note) or external (link)
    Img                string `json:",omitempty"` // /_assets/ URL for image file nodes
    Label              string `json:",omitempty"` // group label
}

// Build resolves file nodes to permalink + rendered HTML (or image URL),
// renders text nodes' markdown, and serializes geometry + edges.
// canRead gates embedded note content (access control, §8).
func Build(c *obsidiancanvas.Canvas, nvs *model.NoteViews,
           canRead func(*model.NoteView) bool, renderMD func(string) string) Board

File-node resolution reuses the existing seam exactly:

• nvs.GetByPath(node.File) (the same lookup renderEmbed uses,
  link_renderer.go:219); fall back to a PathMap suffix match like the bot's
  findNoteByFile (render.go:59-73) for vault-prefix paths.
• If the target is a note: take note.Permalink + note.HTML (already rendered
  in memory — same as renderEmbed wrapping note.HTML, link_renderer.go:245).
  Gate on canRead: if the embedded note is paywalled and the viewer can't
  read it, emit only its title/permalink, not the HTML.
• If the target is an image (image.IsMediaExtension): use
  note.AssetReplaces[node.File].URL (the /_assets/ or S3 URL,
  model.NoteAssetReplace.URL, note.go:46-54).

Text-node markdown: render via the shared markdown→HTML path so **bold**,
links, etc. work. (v1 may ship plain-escaped text and upgrade to full markdown in
v1.1 — see phasing.)

5.3 Wire the render hook (endpoint.go)

Replace the unconditional placeholder branch (endpoint.go:96-103) so .canvas
renders the board while .base/.excalidraw keep the stub:

if resp != nil && resp.Note != nil {
    if ext := unsupportedFileExt(resp.Note.Path); ext != "" {
        // RE-APPLY access control here — the short-circuit ran before paywall (§8).
        dtCtx := buildDefaultTemplateCtx(req, layoutParams, resp, env)
        if ext == ".canvas" && resp.Note.Canvas != nil {
            dtCtx.Canvas = canvasview.Build(resp.Note.Canvas, resp.Notes.Unwrap(),
                                            env.canReadFn(...), env.renderMD)
        } else {
            dtCtx.UnsupportedFileExt = ext // .base / .excalidraw stub
        }
        defaulttemplate.WriteRender(ctx, dtCtx)
        return nil, nil
    }
}

5.4 Accessor + Ctx field

• internal/templateviews/note.go — add a narrow accessor next to HasCharts()
  (note.go:169) / HasCodeLanguage() (:176):

  // HasCanvas reports whether the note is a parsed .canvas board.
  func (n *Note) HasCanvas() bool { return n.nv.Canvas != nil }
  

  Use this in buildDefaultTemplateCtx to conditionally append canvas.js
  (§6 / mirrors mermaid wiring at endpoint.go:505-515). Do not Unwrap()
  the raw *model.NoteView into template code.

• internal/defaulttemplate/template.go — add Canvas *canvasview.Board to the
  Ctx struct (alongside UnsupportedFileExt, template.go:71).

5.5 Template func (views.html)

Add a CanvasBoard(ctx *Ctx) quicktemplate func and branch to it where the
UnsupportedFile branch lives (views.html:92-93). It emits the container, the
JSON island, and the <noscript> SSR fallback (an ordered list of node
text/links — see §3). Quicktemplate is {%s %}/{%= %}, not Go templates —
after editing, run go generate ./internal/defaulttemplate/... and commit the
regenerated views.html.go (the generated StreamUnsupportedFile lives at
views.html.go:2314-2348; the new func will sit next to it).

6.1 Glue bundle assets/canvas/ (mirror assets/mermaid/)

• src/index.ts → assets/canvas.js — the only bundle (no heavy lib, so no
  lib.ts/canvas.min.js split). Responsibilities:
  1. Find [data-canvas] and its sibling script.canvas-board__data; bail if
     absent (cheap no-op on non-canvas pages — same guard as mermaid's
     if (blocks.length === 0) return).
  2. Compute the bounding box of all node geometries; create a transform layer.
  3. For each node, create an absolutely-positioned <div> at x/y/width/height,
     inject text/html (sanitized server-side already), apply the canvas
     color palette class.
  4. Draw edges as SVG <path>s between node sides (fromSide/toSide), with
     optional label and color.
  5. Hand-rolled pan/zoom (pointer drag to pan, wheel/pinch to zoom, a
     "fit-to-screen" button). No external dependency — keep the bundle tiny.
  6. Theme: register a window.trip2g_theme_listeners callback (exactly like
     assets/mermaid/src/index.ts:56-61) to recolor on light/dark toggle.

6.2 Build wiring

• assets/canvas/esbuild.browser.mjs — copy assets/mermaid/esbuild.browser.mjs
  (IIFE, target: es2020, minify), but one output (canvas.js).

• package.json — add a per-widget script next to the others
  ("mermaid"/"chart"/"codeblock", package.json:18-20):

  "canvas": "node assets/canvas/esbuild.browser.mjs"
  

  Not npm run build (that's tsc + vite for the $mol admin app).

• assets/embed.go — add canvas.js to the //go:embed list
  (embed.go:8, alongside mermaid.js). The built canvas.js is a committed
  artifact, like chart.js/mermaid.js.

• buildDefaultTemplateCtx (endpoint.go:505-515) — append the glue per note:

  if note.HasCanvas() {
      jsURLs = append(jsURLs, env.AssetURL("/assets/canvas.js"))
  }
  

  AssetURL adds the content-hash cache-bust (cmd/server/assets.go:128-160,
  ?h=<sha256[:8]>).

6.3 CSS

Canvas board styles go in assets/defaulttemplate/src/index.scss (the board
container, node cards, the color palette, edge SVG, controls). Compile with
npm run defaulttemplate-css (package.json:15). Keep node colors mapped from
the JSON Canvas 1–6 palette to CSS custom properties so the theme listener can
swap them.

How permalinks are derived and looked up today

• Raw files (registerRawFile, loader.go:270-299) set
  Permalink = "/" + src.Path with the extension (loader.go:296) — so today a
  canvas lands at /board.canvas.
• Markdown notes strip .md and transliterate via
  NoteView.PreparePermalink (note.go:439-493): it removes the .md suffix
  (:450-452), normalizes each path segment (normalizeURLPart), sets
  Permalink/PermalinkOriginal, and records AlternatePermalinks (other
  transliteration variants) for 301 redirects.
• Registration (NoteViews.RegisterNote, note.go:1338-1362) writes the note
  into nv.Map under Permalink, PermalinkOriginal, and each
  AlternatePermalinks value. nv.Map is last-writer-wins (the existing
  alternate-collision comment at :1344-1351 confirms it). PathMap is keyed by
  note.Path.
• Lookup at request time: resolveNote (resolve.go:507-527) tries
  GetByRoute (custom-domain / alias routes) and then falls back to
  GetByPath(path) — which, despite its name, reads nv.Map[path] (the permalink
  map, note.go:1315-1322). So a URL resolves to a note iff that exact string is a
  key in nv.Map.

The change

For .canvas, derive the permalink the same way markdown notes do instead of the
raw "/" + path:

1. Strip .canvas and transliterate. Extend PreparePermalink's extension-strip
   (note.go:450-452, currently .md-only) to also strip .canvas, then have
   registerRawFile call PreparePermalink(...) for canvas files (reusing the
   markdown derivation) rather than setting Permalink = "/" + src.Path. Result:
   board.canvas → Permalink = /board.
2. Register the extension URL as an alias. Keep /board.canvas reachable by also
   registering it in nv.Map (an extra alias key, alongside the derived /board), so
   existing links to the extension URL still resolve. Both URLs work; canonical is the
   pretty URL.

This is an alias, not the existing AlternatePermalinks 301 mechanism: an
AlternatePermalinks entry triggers a 301 to the canonical URL (endpoint.go:69-77),
whereas here both URLs should serve. (A canonical-link or optional 301 from the
extension URL to /board can be layered on later if desired.)

Collision rule (deterministic, non-clobbering)

If a markdown note and a canvas derive the same pretty permalink — board.md and
board.canvas both → /board — the markdown/content note wins the pretty URL; the
canvas stays reachable only at /board.canvas; emit a load-time warning.

This falls out of the existing registration order and nv.Map semantics — no special
casing of the lookup is required:

• Raw files register first (Step 1a, loader.go:145-154), markdown notes register
  later (Step 3, loader.go:214-231), both through RegisterNote.
• nv.Map is last-writer-wins, so the later board.md registration overwrites
  nv.Map["/board"] — the markdown note ends up owning /board, exactly the
  desired precedence.
• The canvas's separately-registered alias nv.Map["/board.canvas"] is not
  touched by the markdown note, so the canvas remains reachable there.

To make this robust rather than incidental, registerRawFile (or the load step) should
detect the collision explicitly — check whether the derived pretty permalink already
maps to a content note (or is claimed later) — and, on collision, not register the
pretty key for the canvas (only the .canvas alias), plus emit a warning via
ldr.log.Warn (same pattern as the existing "canvas parse failed" warning,
loader.go:289) or page.AddWarning (loader.go:222). Do not rely solely on
registration order for correctness; treat last-writer-wins as the tiebreaker, the
explicit check as the guarantee.