feat(nav): on-demand graph overlay (replaces graph pane)

Author: ontehfritz

internal/adapter/inbound/web/graph.go

@@ -36,7 +36,7 @@ func (h *ReadingHandler) GraphPage(c *echo.Context) error {
 	p := "/" + c.Param("*")
 	n := h.reading.Neighborhood(world, p)
 	// Single-pane permalink: nodes link to /w/ document permalinks.
-	svg := graphSVG(n, func(r domain.Ref) string { return docRoute(r.World, r.Path) })
+	svg := graphSVG(n, func(r domain.Ref) string { return docRoute(r.World, r.Path) }, nil)
 	vm := page{
 		Title:         "Graph: " + p,
 		Host:          world,
@@ -75,15 +75,15 @@ func (h *ReadingHandler) graphPaneView(t trail, i int, addr paneAddr) paneVM {
 	n := h.reading.Neighborhood(addr.World, addr.Value)
 	vm.Content = graphSVG(n, func(r domain.Ref) string {
 		return trailURL(trailAfterClick(t, i, paneAddr{Kind: paneDoc, World: r.World, Value: r.Path}))
-	})
+	}, trailDocRefs(t))
 	return vm
 }
 
 // graphSVG lays out the neighborhood deterministically (server-side, no client
 // physics): the center document in the middle, its neighbors on a ring —
 // backlinks on the left arc, outbound links on the right — each joined to the
 // center by an edge. urlFor turns each ref into its navigation target.
-func graphSVG(n domain.Neighborhood, urlFor func(domain.Ref) string) template.HTML {
+func graphSVG(n domain.Neighborhood, urlFor func(domain.Ref) string, onTrail map[domain.Ref]bool) template.HTML {
 	if len(n.In) == 0 && len(n.Out) == 0 {
 		return template.HTML(`<p class="graph-empty">No links observed yet — the neighborhood fills in as connected documents are read.</p>`) //nolint:gosec // static markup
 	}
@@ -111,8 +111,12 @@ func graphSVG(n domain.Neighborhood, urlFor func(domain.Ref) string) template.HT
 		if !pn.inbound {
 			dir = "out"
 		}
-		fmt.Fprintf(&b, `<a href="%s"><circle class="graph-node graph-%s" cx="%d" cy="%d" r="%d"/>`,
-			html.EscapeString(urlFor(pn.ref)), dir, pn.x, pn.y, graphNodeR)
+		cls := "graph-node graph-" + dir
+		if onTrail[pn.ref] {
+			cls += " graph-walked" // a neighbor already on your trail
+		}
+		fmt.Fprintf(&b, `<a href="%s"><circle class="%s" cx="%d" cy="%d" r="%d"/>`,
+			html.EscapeString(urlFor(pn.ref)), html.EscapeString(cls), pn.x, pn.y, graphNodeR)
 		anchor := "middle"
 		if pn.x < cx {
 			anchor = "end"
@@ -160,6 +164,18 @@ func arcNodes(refs []domain.Ref, cx, cy int, inbound bool) []placedNode {
 	return out
 }
 
+// trailDocRefs is the set of document refs on the trail — the graph overlay
+// marks these neighbors as already-walked (ADR 0006 §4).
+func trailDocRefs(t trail) map[domain.Ref]bool {
+	refs := map[domain.Ref]bool{}
+	for _, p := range t.Panes {
+		if p.Kind == paneDoc && !domain.IsListingPath(p.Value) {
+			refs[domain.Ref{World: p.World, Path: p.Value}] = true
+		}
+	}
+	return refs
+}
+
 func trimGraphLabel(s string) string {
 	runes := []rune(s)
 	if len(runes) <= graphLabel {

internal/adapter/inbound/web/graph_test.go

@@ -14,7 +14,7 @@ func TestGraphSVGRendersNeighborhood(t *testing.T) {
 		Out:    []domain.Ref{{World: "soul", Path: "/out.md"}},
 		In:     []domain.Ref{{World: "soul", Path: "/in.md"}},
 	}
-	svg := string(graphSVG(n, func(r domain.Ref) string { return docRoute(r.World, r.Path) }))
+	svg := string(graphSVG(n, func(r domain.Ref) string { return docRoute(r.World, r.Path) }, nil))
 
 	if !strings.Contains(svg, "<svg class=\"graph\"") {
 		t.Errorf("not an svg: %s", svg)
@@ -32,7 +32,7 @@ func TestGraphSVGRendersNeighborhood(t *testing.T) {
 
 func TestGraphSVGEmptyNeighborhood(t *testing.T) {
 	n := domain.Neighborhood{Center: domain.Ref{World: "soul", Path: "/lonely.md"}}
-	svg := string(graphSVG(n, func(_ domain.Ref) string { return "" }))
+	svg := string(graphSVG(n, func(_ domain.Ref) string { return "" }, nil))
 	if !strings.Contains(svg, "graph-empty") {
 		t.Errorf("empty neighborhood should render the honest empty state: %s", svg)
 	}
@@ -76,6 +76,45 @@ func TestTrailGraphPaneContinuesTrail(t *testing.T) {
 	}
 }
 
+func TestGraphOverlayForFocusedDoc(t *testing.T) {
+	svc := &fakeReading{
+		docs: map[string]domain.Document{"/x.md": {Title: "X", Path: "/x.md", HTML: "<p>x</p>"}},
+		neighbor: map[string]domain.Neighborhood{
+			"/x.md": {Center: domain.Ref{World: "w.io", Path: "/x.md"},
+				Out: []domain.Ref{{World: "w.io", Path: "/y.md"}}},
+		},
+	}
+	body := get(readingApp(t, svc), "/t/w.io/d/x.md").Body.String()
+
+	// The focused doc's graph overlay is embedded (summoned by `g`), not a pane.
+	if !strings.Contains(body, `id="graph-overlay"`) {
+		t.Errorf("graph overlay missing for focused doc: %s", body)
+	}
+	// A node click is a trail jump from the focus (navigating dismisses the overlay).
+	if !strings.Contains(body, `href="/t/w.io/d/x.md/~/w.io/d/y.md"`) {
+		t.Errorf("graph overlay node should jump the trail: %s", body)
+	}
+}
+
+func TestGraphOverlayMarksWalkedNeighbors(t *testing.T) {
+	// Trail y → x (focus x); x links to y, and y is on the trail, so y renders
+	// as a walked node in x's overlay.
+	svc := &fakeReading{
+		docs: map[string]domain.Document{
+			"/x.md": {Title: "X", Path: "/x.md", HTML: "<p>x</p>"},
+			"/y.md": {Title: "Y", Path: "/y.md", HTML: "<p>y</p>"},
+		},
+		neighbor: map[string]domain.Neighborhood{
+			"/x.md": {Center: domain.Ref{World: "w.io", Path: "/x.md"},
+				Out: []domain.Ref{{World: "w.io", Path: "/y.md"}}},
+		},
+	}
+	body := get(readingApp(t, svc), "/t/w.io/d/y.md/~/w.io/d/x.md").Body.String()
+	if !strings.Contains(body, "graph-walked") {
+		t.Errorf("neighbor on the trail should render as walked: %s", body)
+	}
+}
+
 func TestDocMarginOffersGraphAndBacklinks(t *testing.T) {
 	svc := &fakeReading{
 		docs: map[string]domain.Document{
@@ -87,8 +126,9 @@ func TestDocMarginOffersGraphAndBacklinks(t *testing.T) {
 	}
 	body := get(readingApp(t, svc), "/t/w.io/d/x.md").Body.String()
 
-	// The margin's graph affordance opens this doc's graph pane on the trail.
-	if !strings.Contains(body, `href="/t/w.io/d/x.md/~/w.io/g/x.md"`) {
+	// The margin's graph affordance opens the graph overlay (ADR 0006 §4): a /g/
+	// permalink (degrade) that islands.js intercepts on the canvas.
+	if !strings.Contains(body, `href="/w/w.io/g/x.md" class="graph-open"`) {
 		t.Errorf("margin graph affordance missing: %s", body)
 	}
 	// The backlinks block lists the referrer with a hover-preview link.

internal/adapter/inbound/web/reading_handlers_test.go

@@ -319,8 +319,8 @@ func TestDocRendersMargin(t *testing.T) {
 		"mark://soul.demarkus.io/adr/0007.md",
 		`href="/w/soul.demarkus.io/raw/adr/0007.md"`,
 		`href="/w/soul.demarkus.io/versions/adr/0007.md"`,
-		`href="/w/soul.demarkus.io/g/adr/0007.md">graph`,
-		`href="/w/soul.demarkus.io/u">map`,
+		`href="/w/soul.demarkus.io/g/adr/0007.md" class="graph-open">graph`,
+		`href="/w/soul.demarkus.io/u" class="map-open">map`,
 	} {
 		if !strings.Contains(body, want) {
 			t.Errorf("doc page missing %q", want)

internal/adapter/inbound/web/static/islands.js

@@ -207,6 +207,60 @@
     }
   });
 
+  // --- graph overlay (g) — ADR 0006 §4 ----------------------------------
+  // The overlay is server-rendered (templates/graph-overlay); this is the
+  // summon/dismiss glue ADR 0003 sanctions. Node clicks are plain trail links,
+  // so navigating dismisses it. Degrades: the margin "graph" link is a real /g/
+  // permalink; we only intercept it on the canvas (where the overlay exists).
+  function graphOverlay() { return document.getElementById("graph-overlay"); }
+  function openGraph() { var g = graphOverlay(); if (g) g.hidden = false; }
+  function closeGraph() { var g = graphOverlay(); if (g) g.hidden = true; }
+  document.addEventListener("click", function (e) {
+    var link = e.target.closest && e.target.closest("a.graph-open");
+    if (link && graphOverlay()) { e.preventDefault(); openGraph(); return; }
+    if (e.target.id === "graph-overlay") closeGraph(); // click outside the panel
+  });
+  document.addEventListener("keydown", function (e) {
+    var g = graphOverlay();
+    if (e.key === "Escape" && g && !g.hidden) { e.preventDefault(); closeGraph(); return; }
+    if (e.key !== "g" || e.ctrlKey || e.metaKey || e.altKey) return;
+    var tag = (e.target.tagName || "").toLowerCase();
+    if (tag === "input" || tag === "textarea" || e.target.isContentEditable) return;
+    var p = palette();
+    if ((p && !p.hidden) || !g) return; // not while the palette is open / no graph here
+    e.preventDefault();
+    g.hidden ? openGraph() : closeGraph();
+  });
+
+  // --- world-map overlay (m) — ADR 0006 §5 ------------------------------
+  // Same overlay chrome as the graph, but lazy: the SVG is htmx-loaded into
+  // #map-canvas on summon (the map needs a catalog read, so an unopened map
+  // costs nothing). Node clicks are trail links → navigating dismisses it.
+  function mapOverlay() { return document.getElementById("map-overlay"); }
+  function openMap() {
+    var m = mapOverlay();
+    if (!m) return;
+    m.hidden = false;
+    if (window.htmx) window.htmx.ajax("GET", m.dataset.mapUrl, "#map-canvas");
+  }
+  function closeMap() { var m = mapOverlay(); if (m) m.hidden = true; }
+  document.addEventListener("click", function (e) {
+    var link = e.target.closest && e.target.closest("a.map-open");
+    if (link && mapOverlay()) { e.preventDefault(); openMap(); return; }
+    if (e.target.id === "map-overlay") closeMap(); // click outside the panel
+  });
+  document.addEventListener("keydown", function (e) {
+    var m = mapOverlay();
+    if (e.key === "Escape" && m && !m.hidden) { e.preventDefault(); closeMap(); return; }
+    if (e.key !== "m" || e.ctrlKey || e.metaKey || e.altKey) return;
+    var tag = (e.target.tagName || "").toLowerCase();
+    if (tag === "input" || tag === "textarea" || e.target.isContentEditable) return;
+    var p = palette();
+    if ((p && !p.hidden) || !m) return;
+    e.preventDefault();
+    m.hidden ? openMap() : closeMap();
+  });
+
   document.addEventListener("DOMContentLoaded", function () {
     scan(document.body);
     showFocusedPane();

internal/adapter/inbound/web/templates/canvas.html

@@ -37,10 +37,43 @@ <h1>{{ .Title }}</h1>
   {{template "reader" .}}
   {{- end }}
   {{template "dock" .Dock}}
+  {{template "graph-overlay" .Graph}}
+  {{template "map-overlay" .}}
   {{template "palette" .}}
 </body>
 </html>{{end}}
 
+{{/* The graph overlay (ADR 0006 §4): an on-demand pull-up of the focused doc's
+     reference neighborhood, summoned by `g` (islands.js) and closed by Esc /
+     click-outside. Server-rendered SVG, hidden until summoned; node clicks are
+     plain trail links, so a click jumps and the navigation dismisses it. It
+     replaces the in-trail graph pane. */}}
+{{define "graph-overlay"}}
+{{- if .Has}}
+<div id="graph-overlay" class="graph-backdrop" hidden>
+  <div class="graph-panel" role="dialog" aria-modal="true" aria-label="Document graph">
+    <div class="graph-head"><span class="graph-title">{{ .Title }}</span><span class="graph-hint">g · esc</span></div>
+    <div class="graph-canvas">{{ .Content }}</div>
+  </div>
+</div>
+{{- end}}
+{{end}}
+
+{{/* The world-map overlay (ADR 0006 §5): on-demand discovery pull-up, like the
+     graph. Lazy — the SVG is htmx-loaded into #map-canvas on summon (`m` / the
+     margin "map" link, islands.js), so an unopened map costs no catalog read.
+     Nodes extend the trail; navigating dismisses it. Reuses the overlay chrome. */}}
+{{define "map-overlay"}}
+{{- if .MapHas}}
+<div id="map-overlay" class="graph-backdrop" hidden data-map-url="/w/{{ .MapWorldPath }}/u?overlay=1">
+  <div class="graph-panel">
+    <div class="graph-head"><span class="graph-title">Map: {{ .MapWorld }}</span><span class="graph-hint">m · esc</span></div>
+    <div id="map-canvas" class="graph-canvas"></div>
+  </div>
+</div>
+{{- end}}
+{{end}}
+
 {{/* The trail dock (ADR 0006 §2): the bottom orientation strip. A <details>
      gives zero-JS minimize — closed shows just the header, freeing vertical
      space. Entries rewind on click; connectors show walk (solid) vs jump

internal/adapter/inbound/web/templates/content.html

@@ -36,8 +36,8 @@
         <a href="/w/{{ .WorldPath }}/raw{{ .Path }}">source</a>
         · <a href="/w/{{ .WorldPath }}/versions{{ .Path }}">editions</a>
         {{- if .ReaderURL }} · <a href="{{ .ReaderURL }}">reader</a>{{ end }}
-        {{- if .GraphURL }} · <a href="{{ .GraphURL }}">graph</a>{{ end }}
-        {{- if .MapURL }} · <a href="{{ .MapURL }}">map</a>{{ end }}
+        {{- if .GraphURL }} · <a href="{{ .GraphURL }}" class="graph-open">graph</a>{{ end }}
+        {{- if .MapURL }} · <a href="{{ .MapURL }}" class="map-open">map</a>{{ end }}
         {{- if .EditURL }} · <a href="{{ .EditURL }}" hx-boost="false" class="edit-link">edit</a>{{ end }}
         {{- if .NewURL }} · <a href="{{ .NewURL }}" hx-boost="false" class="edit-link">new</a>{{ end }}
         {{- if .AppendURL }} · <a href="{{ .AppendURL }}" hx-boost="false" class="edit-link">append</a>{{ end }}

internal/adapter/inbound/web/templates/page.html

@@ -215,6 +215,9 @@
     .graph-node { fill: var(--paper); stroke: var(--muted); stroke-width: 1.5; }
     .graph-node.graph-in  { stroke: light-dark(#0969da, #4493f8); }
     .graph-node.graph-out { stroke: light-dark(#1a7f37, #3fb950); }
+    /* A neighbor already on your trail (ADR 0006 §4): filled green = walked. */
+    .graph-node.graph-walked { fill: light-dark(#1a7f37, #3fb950);
+            stroke: light-dark(#1a7f37, #3fb950); stroke-width: 3; }
     .graph-node-label { font-size: 11px; }
     svg.graph a:hover circle { stroke-width: 3; }
     .graph-empty { color: var(--muted); font-style: italic; }
@@ -324,6 +327,24 @@
                   font-size: .7rem; color: var(--muted); }
     @media (max-width: 640px) { .palette-loc { display: none; } }
 
+    /* ── Graph overlay (ADR 0006 §4): on-demand pull-up of the focused doc's
+          reference neighborhood. Hidden until summoned by `g`. ───────────── */
+    .graph-backdrop { position: fixed; inset: 0; z-index: 90;
+            background: light-dark(#11111155, #00000099);
+            display: flex; justify-content: center; align-items: center;
+            padding: 4vh 2vw; }
+    .graph-backdrop[hidden] { display: none; }
+    .graph-panel { background: var(--paper); color: var(--ink);
+            border: 1px solid var(--faint); border-radius: 10px;
+            box-shadow: 0 12px 48px #00000066; max-width: 95vw; max-height: 90vh;
+            overflow: auto; display: flex; flex-direction: column; }
+    .graph-head { display: flex; justify-content: space-between; align-items: baseline;
+            gap: 1rem; padding: .5rem .9rem; border-bottom: 1px solid var(--faint);
+            font-family: system-ui, sans-serif; }
+    .graph-title { font-weight: 600; font-size: .9rem; }
+    .graph-hint { font-size: .68rem; color: var(--muted); }
+    .graph-canvas { padding: .5rem; }
+
     /* ── World index (ADR 0006 §5): the universe lists worlds as doors, never
           loose documents. A card carries door affordances (glyph, chevron) a
           document row never has; federated worlds read as a remote server. ── */

internal/adapter/inbound/web/trail_handlers.go

@@ -23,9 +23,25 @@ type canvasVM struct {
 	Authenticated bool
 	User          string // signed-in identity's email for the nav (empty ⇒ not shown)
 	Panes         []paneVM
-	Reader        *paneVM // the reader overlay (R4); nil when closed
-	CloseURL      string  // ✕ / backdrop / Esc target: the bare trail (no overlay)
-	Dock          dockVM  // the bottom orientation strip (ADR 0006 §2)
+	Reader        *paneVM        // the reader overlay (R4); nil when closed
+	CloseURL      string         // ✕ / backdrop / Esc target: the bare trail (no overlay)
+	Dock          dockVM         // the bottom orientation strip (ADR 0006 §2)
+	Graph         graphOverlayVM // the on-demand graph overlay (ADR 0006 §4)
+
+	// The world-map overlay shell (ADR 0006 §5, on-demand discovery): empty
+	// until summoned, then htmx-loaded lazily so an unopened map costs no read.
+	MapHas       bool
+	MapWorld     string
+	MapWorldPath string
+}
+
+// graphOverlayVM is the focused doc's graph overlay (ADR 0006 §4): summoned by
+// `g`, it replaces the in-trail graph pane. Has is false when the focused pane
+// is not a document (then `g` has nothing to show).
+type graphOverlayVM struct {
+	Has     bool
+	Title   string
+	Content template.HTML
 }
 
 // paneVM is one pane on the canvas. The margin fields mirror the page VM so
@@ -138,11 +154,33 @@ func (h *ReadingHandler) Trail(c *echo.Context) error {
 	vm.Title = focusedPane.Title
 	vm.World = focusedPane.World
 
+	// The world-map overlay is available whenever the focus sits in a world (a
+	// doc, listing, tag, or world-map pane) — the bare universe floor has none.
+	if fw := t.Panes[t.Focus].World; fw != "" {
+		vm.MapHas = true
+		vm.MapWorld = fw
+		vm.MapWorldPath = url.PathEscape(fw)
+	}
+
 	// The dock is built after the pane loop so the focused doc's links are
 	// already observed (RecordLinks ran during render), giving the walk/jump
 	// connectors and "from here →" chips a graph to read.
 	vm.Dock = h.buildDock(t)
 
+	// The graph overlay (ADR 0006 §4): the focused doc's reference neighborhood,
+	// summoned by `g`. Built here (links observed), embedded hidden — it replaces
+	// the in-trail graph pane. Node clicks are trail jumps from the focus.
+	if fa := t.Panes[t.Focus]; fa.Kind == paneDoc && !domain.IsListingPath(fa.Value) {
+		n := h.reading.Neighborhood(fa.World, fa.Value)
+		vm.Graph = graphOverlayVM{
+			Has:   true,
+			Title: refTitle(n.Center),
+			Content: graphSVG(n, func(r domain.Ref) string {
+				return trailURL(trailAfterClick(t, t.Focus, paneAddr{Kind: paneDoc, World: r.World, Value: r.Path}))
+			}, trailDocRefs(t)),
+		}
+	}
+
 	// The reader overlay reuses the addressed pane's already-fetched document —
 	// no extra world read (the overlay is pure presentation), and focus is
 	// untouched so the canvas behind is unchanged. Body links persist the
@@ -290,8 +328,15 @@ func (h *ReadingHandler) paneView(ctx context.Context, t trail, i int, addr pane
 		// Graph/map open non-prose panes, so they exit the overlay (plain
 		// trail URLs) even in reader mode; backlinks point at docs, so they
 		// persist the overlay like any other prose link.
-		vm.GraphURL = trailURL(trailAfterClick(t, i, paneAddr{Kind: paneGraph, World: addr.World, Value: addr.Value}))
-		vm.MapURL = trailURL(trailAfterClick(t, i, paneAddr{Kind: paneFloor, World: addr.World}))
+		// The "graph" affordance opens the graph overlay (ADR 0006 §4); the href
+		// is the /g/ permalink so it degrades to the standalone graph page when
+		// JS is off (islands.js intercepts it on the canvas, where the overlay
+		// exists). The graph is no longer docked as a trail pane.
+		vm.GraphURL = "/w/" + url.PathEscape(addr.World) + "/g" + addr.Value
+		// "map" opens the world-map overlay (ADR 0006 §5); the href is the /u
+		// permalink so it degrades to the standalone map page without JS. The
+		// map is no longer docked as a trail pane.
+		vm.MapURL = "/w/" + url.PathEscape(addr.World) + "/u"
 		// Edit leaves the canvas into the dedicated editor page (a focused-pane
 		// mode, not a trail chunk); only behind the turnstile.
 		if authed {