@geml/geml 1.1.1 → 1.3.2

package/dist/render.js

@@ -15,21 +15,37 @@ const PALETTE = ["#2563eb", "#dc2626", "#059669", "#d97706", "#7c3aed", "#db2777
 // ---------------------------------------------------------------------------
 // Escaping
 // ---------------------------------------------------------------------------
-function esc(s) {
+export function esc(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-function escAttr(s) {
+export function escAttr(s) {
     return esc(s).replace(/"/g, "&quot;");
 }
+// Build a `class="…"` value from document-author-controlled tokens. Class names
+// are dropped to the HTML token charset ([A-Za-z0-9_-]) so a crafted `.class`
+// (e.g. `.x" onmouseover="alert(1)`) cannot break out of the attribute, then the
+// joined result is escAttr'd as well (defense-in-depth). §4.
+function classAttr(tokens) {
+    const safe = tokens
+        .map((t) => t.replace(/[^A-Za-z0-9_-]/g, ""))
+        .filter((t) => t !== "");
+    return escAttr(safe.join(" "));
+}
+// Maximum block-nesting depth the renderer will descend before bailing out with
+// a diagnostic instead of overflowing the call stack (block()↔list()↔typed() are
+// mutually recursive). 256 is far past any legitimate document yet well under the
+// few-thousand-frame native stack limit. Kept in step with the parser's cap.
+const MAX_NESTING = 256;
 // ---------------------------------------------------------------------------
 // Render context
 // ---------------------------------------------------------------------------
-class RenderCtx {
+export class RenderCtx {
     doc;
     opts;
     usedMath = false;
     usedMermaid = false;
     usedCodeGraph = false;
+    renderDepth = 0;
     labels = new Map(); // id -> link label for [[#id]] auto-refs
     constructor(doc, opts = {}) {
         this.doc = doc;
@@ -121,6 +137,20 @@ class RenderCtx {
     }
     // ----- blocks -----
     block(b) {
+        // Guard the block()↔list()↔typed() mutual recursion so a pathologically
+        // nested document degrades to a diagnostic rather than a RangeError.
+        if (this.renderDepth >= MAX_NESTING) {
+            return `<div class="render-error">block nesting too deep (max ${MAX_NESTING})</div>`;
+        }
+        this.renderDepth++;
+        try {
+            return this.blockInner(b);
+        }
+        finally {
+            this.renderDepth--;
+        }
+    }
+    blockInner(b) {
         switch (b.kind) {
             case "hidden": return "";
             case "heading": {
@@ -172,10 +202,17 @@ class RenderCtx {
                 this.usedMath = true;
                 return `<div class="math-block"${idAttr}>\\[${esc(raw)}\\]</div>`;
             case "note": {
-                const classes = ["callout", b.type, ...b.classes].join(" ");
+                const classes = classAttr(["callout", b.type, ...b.classes]);
                 const inner = (b.children ?? []).map((c) => this.block(c)).filter((s) => s).join("\n");
                 return `<aside class="${classes}"${idAttr}>\n${inner}\n</aside>`;
             }
+            case "text": {
+                // Addressable prose (§3): flow children in a NEUTRAL container — the
+                // block exists for its id/attrs, not for callout chrome (that's note).
+                const inner = (b.children ?? []).map((c) => this.block(c)).filter((s) => s).join("\n");
+                const classes = classAttr(["text", ...b.classes]);
+                return `<div class="${classes}"${idAttr}>\n${inner}\n</div>`;
+            }
             case "table":
                 return b.table ? this.table(b.table, b.id, caption) : `<p class="render-error">table failed to parse</p>`;
             case "diagram":
@@ -243,7 +280,10 @@ class RenderCtx {
         // model keeps every row: charts, computed summaries and the code-graph
         // never read the HTML). Codemap edge tables additionally fold shut —
         // they are machine data; elsewhere the table is content and stays open.
-        const maxRows = this.opts.tableRows ?? 500;
+        // The codemap index's #modules table IS the page's content — the module
+        // inventory people scan and filter — so it renders in full. Edge tables
+        // (#calls / #called-by) stay previewed+folded: machine data at scale.
+        const maxRows = this.isCodemapDoc && id === "modules" ? Infinity : (this.opts.tableRows ?? 500);
         const allRows = t.rows;
         const rows = allRows.length > maxRows ? allRows.slice(0, maxRows) : allRows;
         // Coverage grid for declared spans, so cells a span covers are not emitted.
@@ -251,8 +291,12 @@ class RenderCtx {
         rows.forEach((row, r) => row.forEach((cell, c) => {
             if (!cell.span)
                 return;
-            for (let dr = 0; dr < cell.span.rows; dr++)
-                for (let dc = 0; dc < cell.span.cols; dc++) {
+            // Bound the sweep to the rendered grid regardless of the declared span, so
+            // an oversized span can never drive an O(hugerows×hugecols) loop (DoS).
+            const spanRows = Math.min(cell.span.rows, rows.length - r);
+            const spanCols = Math.min(cell.span.cols, row.length - c);
+            for (let dr = 0; dr < spanRows; dr++)
+                for (let dc = 0; dc < spanCols; dc++) {
                     if (dr === 0 && dc === 0)
                         continue;
                     const rr = r + dr, cc = c + dc;
@@ -313,7 +357,7 @@ function niceMax(v) {
 // depth-limited; the layered LAYOUT happens in the page runtime (draw time).
 // ---------------------------------------------------------------------------
 // Hard payload ceiling only — the VIEW paces itself: the runtime draws the
-// first 400 by BFS order and offers "+400"/"all" to walk deeper. The data in
+// first 600 by BFS order and offers "+600"/"all" to walk deeper. The data in
 // the codemap documents is always complete regardless.
 const CG_MAX_NODES = 4000;
 // Tiny posix-path helpers (no node:path dependency in the renderer).
@@ -399,6 +443,13 @@ function buildCodeGraph(startRel, opts, view) {
                         entryDocs.push(d);
                 }
             }
+            // …plus documents whose app entry is FILE-level (app-entry-docs meta:
+            // top-level bootstrap code with no function symbol, e.g. a Nuxt app.vue).
+            for (const t of String(meta0["app-entry-docs"] ?? "").split(/\s+/).filter(Boolean)) {
+                const d = cgJoin(cgDir(start), t);
+                if (!entryDocs.includes(d))
+                    entryDocs.push(d);
+            }
             return { data: { start, depth: 99, roots: [], nodes: {}, edges: [], mode: "modules", mods: list, medges: em, entryDocs } };
         }
     }
@@ -494,6 +545,8 @@ function buildCodeGraph(startRel, opts, view) {
                         node.test = true;
                     if (b.classes.includes("accessor"))
                         node.acc = true;
+                    if (b.classes.includes("app-entry"))
+                        node.entry = true;
                     idx.set(b.id, node);
                 }
             cache.set(docRel, idx);
@@ -835,7 +888,7 @@ function trunc(s, n) {
 // ---------------------------------------------------------------------------
 // Page shell, inline CSS, inline interactivity JS
 // ---------------------------------------------------------------------------
-const CSS = `
+export const CSS = `
 :root { --fg:#1f2328; --muted:#656d76; --bd:#d0d7de; --bg:#fff; --accent:#2563eb; --code-bg:#f6f8fa; }
 * { box-sizing: border-box; }
 body { margin:0; color:var(--fg); background:#fafbfc; font:16px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,"PingFang SC","Microsoft Yahei",sans-serif; }
@@ -885,8 +938,16 @@ sup.fn a { font-size:.75em; }
 .geml-footer code { font-size:.95em; }
 .code-graph { margin:1.4em 0; }
 .cg-mount { border:1px solid var(--bd); border-radius:8px; padding:10px 12px; background:var(--bg); }
-.cg-scroll { overflow:auto; max-height:72vh; }
+.cg-scroll { overflow:auto; min-height:52vh; max-height:72vh; }
 .cg-svg { display:block; }
+.cg-search-wrap { position:relative; display:inline-block; }
+.cg-search { font:12px/1.4 inherit; padding:2px 7px; border:1px solid var(--bd); border-radius:4px; background:var(--bg); color:var(--fg); min-width:13ch; }
+.cg-search-menu { position:absolute; z-index:30; top:calc(100% + 2px); left:0; min-width:24ch; max-width:52ch; max-height:52vh; overflow:auto; background:var(--bg); border:1px solid var(--bd); border-radius:6px; box-shadow:0 6px 20px rgba(0,0,0,.18); }
+.cg-search-row { display:block; width:100%; text-align:left; padding:4px 9px 4px 18px; border:0; background:none; color:var(--fg); cursor:pointer; font:12px/1.4 inherit; }
+.cg-search-row:hover { background:var(--bd); }
+.cg-search-count { position:sticky; top:0; padding:4px 9px; font-size:11px; opacity:.65; background:var(--bg); border-bottom:1px solid var(--bd); }
+.cg-search-grp { padding:6px 9px 2px; font-size:11px; font-weight:600; opacity:.7; border-top:1px solid var(--bd); }
+.cg-search-grp:first-of-type { border-top:0; }
 .cg-stage { display:flex; gap:10px; align-items:flex-start; }
 .cg-stage .cg-scroll { flex:1 1 auto; min-width:0; }
 .cg-src { flex:0 0 42%; max-width:46%; display:flex; flex-direction:column; border:1px solid var(--bd); border-radius:6px; overflow:hidden; background:var(--bg); }
@@ -927,7 +988,7 @@ sup.fn a { font-size:.75em; }
 .cg-svg.hl .cg-n.hl { opacity:1; }
 .cg-svg.hl .cg-e.hl { opacity:1; stroke-width:1.6; }
 `;
-const JS = `
+export const JS = `
 (function () {
   function cmp(a, b) {
     var na = a.dataset.sort, nb = b.dataset.sort;
@@ -984,7 +1045,7 @@ export function codeGraphRuntime(root) {
     // Arrow-marker ids must be unique per drawn svg — several mounts share one
     // document, and duplicate ids would make every graph point at the first.
     var arrowSeq = 0;
-    function boot(mount, data0) {
+    function boot(mount, data0, gpath) {
         var data, out;
         function setData(d) {
             data = d;
@@ -1076,8 +1137,14 @@ export function codeGraphRuntime(root) {
                 if (!p)
                     return;
                 var kk = keyOf(p);
-                if (kk && kk.indexOf("x:") !== 0 && roots.indexOf(kk) < 0)
-                    roots.push(kk);
+                if (kk && kk.indexOf("x:") !== 0) {
+                    if (roots.indexOf(kk) < 0)
+                        roots.push(kk);
+                    // Badge the module (or the group holding it): this is where the
+                    // program starts — the ▶ the label renderer prepends.
+                    if (nodes[kk])
+                        nodes[kk].appEntry = 1;
+                }
             });
             var hasIn = {};
             edges.forEach(function (e) { hasIn[e[1]] = 1; });
@@ -1092,10 +1159,10 @@ export function codeGraphRuntime(root) {
         function homeData() {
             return data0.mode === "modules" && data0.mods ? deriveView([]) : data0;
         }
-        setData(homeData());
+        setData(data0.mode === "modules" && data0.mods && gpath && gpath.length ? deriveView(gpath) : homeData());
         // scale null = fit-to-width on first draw. Left-right is the default —
         // call flow reads with the text; the toggle persists per reader.
-        var state = { roots: data.roots.slice(), trail: [], scale: null, dir: "LR", frame: null, cap: 400, showAcc: false };
+        var state = { roots: data.roots.slice(), trail: [], scale: null, dir: "LR", frame: null, cap: 600, showAcc: false };
         // Direction survives module -> container navigation (each page is a fresh
         // document); best-effort only — file:// or the DOM stub may lack storage.
         try {
@@ -1276,7 +1343,9 @@ export function codeGraphRuntime(root) {
             // width no longer reserves room for it.
             function label(k) {
                 var n = data.nodes[k];
-                var full = n.n + (n.more ? " ›" : "");
+                // ▶ = this module (or group) holds an app entry — where the program
+                // starts, from index meta entry= / app-entry-docs.
+                var full = (n.appEntry || n.entry ? "▶ " : "") + n.n + (n.more ? " ›" : "");
                 if (full.length <= 32)
                     return full;
                 return data.mode === "modules" ? "…" + full.slice(full.length - 31) : full.slice(0, 31) + "…";
@@ -1552,7 +1621,7 @@ export function codeGraphRuntime(root) {
                 }
                 catch (e) { /* stub */ }
             }
-            function openDoc(rel) {
+            function openDoc(rel, gpath) {
                 var lv = live();
                 if (lv) {
                     Promise.resolve(lv({ doc: rel })).then(function (nd) {
@@ -1565,7 +1634,7 @@ export function codeGraphRuntime(root) {
                         // payload so its grouping tree derives; pushView alone would draw
                         // the empty raw payload (nodes come out {}).
                         if (nd.mode === "modules" && nd.mods)
-                            boot(mount, nd);
+                            boot(mount, nd, gpath);
                         else
                             pushView(nd);
                     }, function () { flash("cannot load " + rel); });
@@ -1646,9 +1715,12 @@ export function codeGraphRuntime(root) {
                 seg("modules", function () { openDoc(navBase + "index.geml"); });
                 sepEl();
                 var modName = String(data.module || String(data.start || "").replace(/^.*\//, "").replace(/\.geml$/, "") || "container");
+                // The middle crumb reads as the OVERVIEW level ("modules / <module>"),
+                // so clicking it goes THERE — the module tier listing this container's
+                // siblings — not a reload of the page you are already on.
                 seg(modName, function () {
                     if (live())
-                        openDoc(String(data.start));
+                        openDoc(navBase + "index.geml", [modName.split("/")[0]]);
                     else {
                         state.trail = [];
                         setData(homeData());
@@ -1659,8 +1731,12 @@ export function codeGraphRuntime(root) {
                 sepEl();
                 seg(data.dir === "up"
                     ? "callers of " + (data.nodes[data.focus] ? data.nodes[data.focus].n : "") + (data.partial ? " (in-slice)" : "") + (Object.keys(data.nodes).length <= 1 ? " — none recorded" : "")
-                    : state.trail.length ? "root: " + state.roots.map(function (k) { return data.nodes[k].n; }).join(", ")
-                        : "roots: entry", null);
+                    : state.trail.length && state.roots.length === 1 ? "root: " + (data.nodes[state.roots[0]] || {}).n
+                        // Many roots = this IS the module's own view (its whole entry
+                        // list) — the methods are already on the graph; naming them all
+                        // here just makes a paragraph-long crumb.
+                        : state.trail.length ? "roots: entry"
+                            : "roots: entry", null);
             }
             bar.appendChild(crumb);
             var scroller = document.createElement("div");
@@ -1753,8 +1829,8 @@ export function codeGraphRuntime(root) {
                 capInfo.textContent = "showing " + (s.total - s.capped) + " of " + s.total + " reachable";
                 bar.appendChild(capInfo);
                 var moreBtn = document.createElement("button");
-                moreBtn.textContent = "+400";
-                moreBtn.onclick = function () { state.cap += 400; draw(); };
+                moreBtn.textContent = "+600";
+                moreBtn.onclick = function () { state.cap += 600; draw(); };
                 bar.appendChild(moreBtn);
                 var allBtn = document.createElement("button");
                 allBtn.textContent = "all";
@@ -1771,6 +1847,152 @@ export function codeGraphRuntime(root) {
                 resetBtn.onclick = function () { state.trail = []; setData(homeData()); state.roots = data.roots.slice(); draw(); };
                 bar.appendChild(resetBtn);
             }
+            // Find a method by name -> jump to its node. Data source: a served page
+            // (http) queries the /_search endpoint (top matches only — a huge index
+            // never ships); a static page (file://) lazy-loads the compact
+            // _index/search-index.js via <script> (fetch is CORS-blocked on file://,
+            // a script tag is not). Picking a hit opens its FOCUSED call graph (B)
+            // in place on a served page; on a static page (no live loader) it
+            // navigates to the node's document (A). Alt-click always just locates.
+            if (typeof location !== "undefined") { // browser only — skipped in the fake-DOM runtime test
+                var searchWrap = document.createElement("span");
+                searchWrap.className = "cg-search-wrap";
+                var searchBox = document.createElement("input");
+                searchBox.type = "search";
+                searchBox.className = "cg-search";
+                searchBox.placeholder = "find a method…";
+                searchBox.setAttribute("aria-label", "Find a method by name");
+                var searchMenu = document.createElement("div");
+                searchMenu.className = "cg-search-menu";
+                searchMenu.hidden = true;
+                searchWrap.appendChild(searchBox);
+                searchWrap.appendChild(searchMenu);
+                bar.appendChild(searchWrap);
+                var srvSearch = /^https?:$/.test(location.protocol);
+                function withIndex(cb) {
+                    if (window.__gemlSearch)
+                        return cb(window.__gemlSearch);
+                    var s = document.createElement("script");
+                    s.src = navBase + "_index/search-index.js";
+                    s.onload = function () { cb(window.__gemlSearch || []); };
+                    s.onerror = function () { cb([]); };
+                    document.head.appendChild(s);
+                }
+                // Rank exactly like serve's /_search (exact > prefix > qualified-tail
+                // prefix > substring), so both data paths order hits the same way.
+                function hitScore(n, q) {
+                    if (n === q)
+                        return 0;
+                    if (n.indexOf(q) === 0)
+                        return 1;
+                    var c2 = n.lastIndexOf("::"), d = n.lastIndexOf(".");
+                    var cut = Math.max(c2 >= 0 ? c2 + 2 : 0, d >= 0 ? d + 1 : 0);
+                    if (cut > 0 && n.slice(cut).indexOf(q) === 0)
+                        return 2;
+                    return n.indexOf(q) >= 0 ? 3 : -1;
+                }
+                function candidates(q, cb) {
+                    q = q.trim().toLowerCase();
+                    if (q.length < 2)
+                        return cb({ total: 0, hits: [] });
+                    if (srvSearch) {
+                        fetch("/_search?q=" + encodeURIComponent(q))
+                            .then(function (r) { return r.ok ? r.json() : { total: 0, hits: [] }; })
+                            .then(function (a) { cb(a && a.hits ? a : { total: 0, hits: [] }); })
+                            .catch(function () { cb({ total: 0, hits: [] }); });
+                    }
+                    else {
+                        withIndex(function (rows) {
+                            var ranked = [];
+                            for (var i = 0; i < rows.length; i++) {
+                                var s = hitScore(String(rows[i][0]).toLowerCase(), q);
+                                if (s >= 0)
+                                    ranked.push({ s: s, name: rows[i][0], doc: rows[i][1], id: rows[i][2] });
+                            }
+                            ranked.sort(function (a, b) { return a.s - b.s || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0); });
+                            // The lookup aliases bare member names to the same node — dedupe
+                            // on doc#id, keeping the best-ranked row.
+                            var seen = {}, hits = [];
+                            for (var j = 0; j < ranked.length; j++) {
+                                var rj = ranked[j];
+                                var k = rj.doc + "#" + rj.id;
+                                if (seen[k])
+                                    continue;
+                                seen[k] = 1;
+                                hits.push(rj);
+                            }
+                            cb({ total: hits.length, hits: hits.slice(0, 100) });
+                        });
+                    }
+                }
+                function gotoHit(doc, id, locate) {
+                    searchMenu.hidden = true;
+                    if (live() && !locate) {
+                        showCallees(doc + "#" + id);
+                        return;
+                    }
+                    location.href = navBase + doc.replace(/\.geml$/, ".html") + "#" + encodeURIComponent(id);
+                }
+                var searchSeq = 0, searchTop = null; // best-ranked hit — Enter opens it
+                searchBox.addEventListener("input", function () {
+                    var my = ++searchSeq, qv = searchBox.value;
+                    candidates(qv, function (res) {
+                        if (my !== searchSeq)
+                            return; // a newer keystroke already fired
+                        searchMenu.replaceChildren();
+                        var hits = res.hits || [];
+                        searchTop = hits.length ? hits[0] : null;
+                        if (!hits.length) {
+                            searchMenu.hidden = true;
+                            return;
+                        }
+                        // Honest count first — a capped list must say so.
+                        var count = document.createElement("div");
+                        count.className = "cg-search-count";
+                        count.textContent = (res.total > hits.length ? "showing " + hits.length + " of " + res.total + " matches" : res.total + (res.total === 1 ? " match" : " matches")) + " · Enter opens the first";
+                        searchMenu.appendChild(count);
+                        // Group by module (document), groups in best-hit order — hits arrive
+                        // globally ranked, so first appearance = the group's best rank.
+                        var order = [], byDoc = {};
+                        hits.forEach(function (c) {
+                            if (!byDoc[c.doc]) {
+                                byDoc[c.doc] = [];
+                                order.push(c.doc);
+                            }
+                            byDoc[c.doc].push(c);
+                        });
+                        order.forEach(function (doc) {
+                            var hd = document.createElement("div");
+                            hd.className = "cg-search-grp";
+                            hd.textContent = String(doc).replace(/\.geml$/, "").replace(/--/g, "/");
+                            searchMenu.appendChild(hd);
+                            byDoc[doc].forEach(function (c) {
+                                var row = document.createElement("button");
+                                row.className = "cg-search-row";
+                                row.type = "button";
+                                var nm = document.createElement("b");
+                                nm.textContent = c.name;
+                                row.appendChild(nm);
+                                row.onclick = function (ev) { gotoHit(c.doc, c.id, !!ev.altKey); };
+                                searchMenu.appendChild(row);
+                            });
+                        });
+                        searchMenu.hidden = false;
+                    });
+                });
+                searchBox.addEventListener("keydown", function (ev) {
+                    if (ev.key === "Escape") {
+                        searchMenu.hidden = true;
+                        searchBox.blur();
+                    }
+                    else if (ev.key === "Enter" && searchTop) {
+                        ev.preventDefault();
+                        gotoHit(searchTop.doc, searchTop.id, !!ev.altKey);
+                    }
+                });
+                document.addEventListener("click", function (ev) { if (!searchWrap.contains(ev.target))
+                    searchMenu.hidden = true; });
+            } // end browser-only search box
             mount.appendChild(bar);
             mount.appendChild(stage);
             if (state.scale === null)
@@ -1784,6 +2006,33 @@ export function codeGraphRuntime(root) {
                 else
                     scroller.scrollTop = 1e6;
             }
+            // Centre the CROSS axis (the fit-to-pane one): the tree fans out around
+            // its midline, so a big graph clamped to the 2/3 scale floor would
+            // otherwise open on an empty top/left corner with every node off-screen.
+            // Reading the scroll extent forces the post-applyScale reflow; when the
+            // cross axis already fits, the delta is ≤0 and this is a no-op. The
+            // reading axis is untouched (root start, or far-end for callers above).
+            // If the view holds an app entry (▶), aim the midline at the FIRST one
+            // (roots first, then any node) instead of the geometric centre — the
+            // reader lands where the program starts.
+            var entryK = null;
+            state.roots.concat(Object.keys(data.nodes)).some(function (ek) {
+                var en = data.nodes[ek];
+                if (en && (en.appEntry || en.entry) && pos[ek]) {
+                    entryK = ek;
+                    return true;
+                }
+                return false;
+            });
+            var aim = function (full, pane, at) { return Math.max(0, Math.min(full - pane, at - pane / 2)); };
+            if (LR)
+                scroller.scrollTop = entryK
+                    ? aim(scroller.scrollHeight, scroller.clientHeight, (pos[entryK].y + NH / 2) * state.scale)
+                    : Math.max(0, (scroller.scrollHeight - scroller.clientHeight) / 2);
+            else
+                scroller.scrollLeft = entryK
+                    ? aim(scroller.scrollWidth, scroller.clientWidth, (pos[entryK].x + pos[entryK].w / 2) * state.scale)
+                    : Math.max(0, (scroller.scrollWidth - scroller.clientWidth) / 2);
             // Footer: live facts, not a static cheat-sheet (navigation lives in
             // the breadcrumb above).
             var footer = document.createElement("div");
@@ -1823,16 +2072,35 @@ export function codeGraphRuntime(root) {
             // document loader (mount._cgView, attached by the upgrade step); a
             // static CLI page reverses its in-slice edges — partial but honest,
             // and labelled as such in the crumb.
+            // No recorded callers (an app/framework entry, or dead code): "up" from
+            // a METHOD is its CONTAINER — one level, never the whole-repo overview
+            // two levels up. From a focused/derived view that means the method's own
+            // container page (the view its module node opens); already sitting on
+            // that default view, say why and stay put — the "don't jump, say why"
+            // contract.
+            function noCallers(k) {
+                var docRel = k.slice(0, k.lastIndexOf("#"));
+                if (docRel !== data0.start) {
+                    openDoc(navBase + docRel);
+                    return;
+                }
+                if (state.trail.length) {
+                    state.trail = [];
+                    setData(homeData());
+                    state.roots = data.roots.slice();
+                    draw();
+                    return;
+                }
+                flash("no recorded callers — an app/framework entry point");
+            }
             function showCallers(k) {
                 var lv = live();
                 if (lv) {
                     Promise.resolve(lv({ dir: "up", node: k })).then(function (nd) {
-                        // In-degree-zero entry (agent/AOP hook, app top): it has no callers,
-                        // so "up" means the module page — not an empty caller view.
                         if (nd && Object.keys(nd.nodes).length > 1)
                             pushView(nd);
                         else
-                            openDoc(navBase + "index.geml");
+                            noCallers(k);
                     });
                     return;
                 }
@@ -1849,9 +2117,9 @@ export function codeGraphRuntime(root) {
                     } });
                 }
                 if (Object.keys(keep).length <= 1) {
-                    openDoc(navBase + "index.geml");
+                    noCallers(k);
                     return;
-                } // no callers -> module page
+                }
                 var nodes = {}, edges = [];
                 for (var nk in keep)
                     nodes[nk] = data0.nodes[nk];
@@ -1941,16 +2209,22 @@ export function codeGraphRuntime(root) {
                 var ub = tgt && tgt.closest ? tgt.closest(".cg-upbtn") : null;
                 if (ub) {
                     if (ub.getAttribute("data-act") === "down") {
-                        // The mirrored handle flips back to the callee chain — the up
-                        // view was pushed from there, so this is exactly one step back.
-                        if (state.trail.length) {
+                        // "Back to its callee chain" must LAND on the callee chain: pop
+                        // the trail only when the view underneath IS this method's own
+                        // focused view (the search/chain path that opened these callers).
+                        // Arriving from anywhere wider — the module page — popping would
+                        // land there instead, so build the method's chain fresh.
+                        var k0 = ub.getAttribute("data-k");
+                        var top0 = state.trail[state.trail.length - 1];
+                        var ownChain = top0 && top0.data && top0.data.dir !== "up" && top0.roots && top0.roots.length === 1 && top0.roots[0] === k0;
+                        if (ownChain) {
                             var tr0 = state.trail.pop();
                             setData(tr0.data);
                             state.roots = tr0.roots;
                             draw();
                         }
                         else
-                            showCallees(ub.getAttribute("data-k"));
+                            showCallees(k0);
                     }
                     else
                         showCallers(ub.getAttribute("data-k"));
@@ -2048,7 +2322,7 @@ export function codeGraphRuntime(root) {
     });
 }
 // CLI inlining: the compiled runtime function, verbatim, run against document.
-const CODE_GRAPH_JS = `(${codeGraphRuntime.toString()})(document);`;
+export const CODE_GRAPH_JS = `(${codeGraphRuntime.toString()})(document);`;
 // Browser-side wave builder: the slice builder is synchronous with a
 // synchronous loader, but a browser fetches documents asynchronously — so
 // run the build in WAVES: every pass records the documents it needed but did
@@ -2094,89 +2368,7 @@ export function codeGraphWaves(fetchDoc, parseFn) {
         },
     };
 }
-function page(title, body, ctx, source) {
-    const mathHead = ctx.usedMath
-        ? `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css">\n` +
-            `<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js"></script>\n` +
-            `<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" onload="renderMathInElement(document.body,{delimiters:[{left:'\\\\[',right:'\\\\]',display:true},{left:'\\\\(',right:'\\\\)',display:false}]})"></script>\n`
-        : "";
-    const mermaidHead = ctx.usedMermaid
-        ? `<script type="module">import m from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";m.initialize({startOnLoad:true});</script>\n`
-        : "";
-    const footer = source
-        ? `<footer class="geml-footer">Rendered from <code>${esc(source)}</code> by the GEML runtime. Tables are sortable and filterable; the chart is inline SVG drawn from its bound table.</footer>`
-        : "";
-    // Live enhancement for served pages: attach _cgView loaders after the
-    // static bootstrap has drawn. The runtime reads the hook lazily, so late
-    // binding works with no redraw; if this module never loads (offline copy,
-    // old browser), the page simply stays static. The parser dist imports
-    // node:* for its CLI paths — an import map points those at the served stub
-    // (same trick as the viewer's esbuild alias), and the process shim must be
-    // in place BEFORE the modules evaluate, hence the dynamic import().
-    const wantLive = ctx.usedCodeGraph && !!ctx.opts.liveGraph;
-    const lg = wantLive ? escAttr(ctx.opts.liveGraph) : "";
-    const importMap = wantLive
-        ? `<script type="importmap">{"imports":{"node:fs":"${lg}_node-stub.js","node:path":"${lg}_node-stub.js","node:crypto":"${lg}_node-stub.js","node:url":"${lg}_node-stub.js","node:child_process":"${lg}_node-stub.js"}}</script>\n`
-        : "";
-    const liveJs = wantLive
-        ? `<script type="module">
-globalThis.process ??= { argv: [], env: {} };
-const { parse } = await import("${lg}geml.js");
-const { codeGraphWaves } = await import("${lg}render.js");
-const w = codeGraphWaves(async (rel) => {
-  try { const r = await fetch(rel, { cache: "no-cache" }); return r.ok ? await r.text() : null; } catch { return null; }
-}, parse);
-for (const m of document.querySelectorAll(".cg-mount[data-start]")) {
-  const start = m.getAttribute("data-start");
-  m._cgView = async (view) => {
-    // A directed view builds from the node's OWN document (its meta names the
-    // module and graph-depth); {doc} opens that document; else the mount's.
-    const src = view && view.doc ? view.doc
-      : view && view.node ? view.node.slice(0, view.node.lastIndexOf("#"))
-      : start;
-    const r = await w.build(src, view && view.doc ? undefined : view);
-    return r.error !== undefined ? null : r.data;
-  };
-}
-</script>\n`
-        : "";
-    return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${esc(title)}</title>
-<style>${CSS}</style>
-${importMap}${mathHead}${mermaidHead}</head>
-<body>
-<main>
-${body}
-</main>
-${footer}
-<script>${JS}</script>
-${ctx.usedCodeGraph ? `<script>${CODE_GRAPH_JS}</script>\n` : ""}${liveJs}</body>
-</html>
-`;
-}
 // ---------------------------------------------------------------------------
 // Public entry
 // ---------------------------------------------------------------------------
 export { buildCodeGraph };
-export function renderHtml(doc, opts = {}) {
-    const ctx = new RenderCtx(doc, opts);
-    let body = doc.children.map((b) => ctx.block(b)).filter((s) => s !== "").join("\n");
-    // Codemap scenario ① (GEP-0003): a codemap document (meta declares module=
-    // or container=, plus an entry surface) IS the graph data — offer the layered
-    // method-flow view at the top, an implicit self-embed.
-    const meta = doc.children.find((b) => b.kind === "block" && b.type === "meta" && b.data);
-    const md = meta?.data ?? {};
-    if ((md["module"] !== undefined || md["container"] !== undefined)
-        && opts.loadDoc && opts.parseDoc && opts.source) {
-        const cap = md["entry"] !== undefined || md["container"] !== undefined
-            ? `layered method flow — roots from this document's <code>entry</code>`
-            : `layered method flow — roots: in-degree-zero methods (no <code>entry</code> declared)`;
-        body = ctx.codeGraphFigure(opts.source, "", `<figcaption>${cap}</figcaption>`) + "\n" + body;
-    }
-    const title = opts.title ?? ctx.docTitle() ?? "GEML document";
-    return page(title, body, ctx, opts.source);
-}