@geml/geml 1.4.6 → 1.5.0

package/dist/inline.d.ts

@@ -36,6 +36,10 @@ export type Inline = {
     type: "autoref";
     anchor: string;
     doc?: string;
+} | {
+    type: "project";
+    anchor: string;
+    doc?: string;
 } | {
     type: "footnote";
     ref: string;
@@ -48,6 +52,22 @@ export interface Ref {
 }
 export interface RefSink {
     refs: Ref[];
+    embeds?: {
+        doc: string;
+        anchor?: string;
+        line: number;
+    }[];
+    mediaDocTargets?: {
+        src: string;
+        line: number;
+    }[];
+    projections?: {
+        doc?: string;
+        anchor: string;
+        line: number;
+    }[];
 }
 export declare const META_REF_SRC = "\\{\\{\\s*([A-Za-z_][A-Za-z0-9_-]*)\\s*\\}\\}";
+export declare function schemeOf(url: string): string | null;
+export declare function isSafeUrl(url: string, allowDataImage?: boolean): boolean;
 export declare function parseInline(s: string, line: number, sink: RefSink, depth?: number): Inline[];

package/dist/inline.js

@@ -20,7 +20,7 @@ export const META_REF_SRC = "\\{\\{\\s*([A-Za-z_][A-Za-z0-9_-]*)\\s*\\}\\}";
 const SAFE_SCHEMES = new Set(["http", "https", "mailto", "tel"]);
 // The leading `scheme:` (RFC-3986 grammar), lowercased — or null when the
 // destination has none (a relative path, `#anchor`, or cross-document ref).
-function schemeOf(url) {
+export function schemeOf(url) {
     // Browsers strip leading/embedded C0 controls and spaces before acting on a
     // URL, so `java\tscript:` and `\x01javascript:` execute as javascript:. Strip
     // every [\x00-\x20] before detecting the scheme so the allowlist can't be
@@ -31,7 +31,7 @@ function schemeOf(url) {
 // A destination is safe to emit when it has no scheme (relative / anchor /
 // cross-doc), or names an allowlisted scheme. `data:` is permitted only for
 // media and only for `image/*` payloads (never `data:text/html`, which scripts).
-function isSafeUrl(url, allowDataImage = false) {
+export function isSafeUrl(url, allowDataImage = false) {
     const scheme = schemeOf(url);
     if (scheme === null)
         return true;
@@ -182,6 +182,29 @@ function scanAtoms(s, line, sink, depth = 0) {
             continue;
         }
         // §5.3(2): image ![alt](src){…}.
+        // §5.3 precedence: inline projection `![[…]]` is tried BEFORE the image atom.
+        // Otherwise `![[#x]]` reads as an image whose label happens to be `[#x]`, and
+        // `![[#x]](y)` would be claimed whole — the parenthesis run has to stay
+        // literal text, which is what this ordering pins.
+        if (c === "!" && s[i + 1] === "[" && s[i + 2] === "[") {
+            const inner = readBracket(s, i + 2); // the inner [...] after `![`
+            if (inner && s[inner.end] === "]") {
+                const { doc, anchor } = classifyDest(inner.content.trim());
+                if (anchor) {
+                    flush();
+                    const node = { type: "project", anchor };
+                    if (doc)
+                        node.doc = doc;
+                    out.push(node);
+                    // Validated by the same §8 resolver as any reference; the target's TYPE
+                    // is checked separately, since only inline content can be projected.
+                    sink.refs.push({ kind: doc ? "cross" : "autoref", doc, anchor, line });
+                    (sink.projections ??= []).push(doc === undefined ? { anchor, line } : { doc, anchor, line });
+                    i = inner.end + 1;
+                    continue;
+                }
+            }
+        }
         if (c === "!" && s[i + 1] === "[") {
             const label = readBracket(s, i + 1);
             const paren = label ? readParen(s, label.end) : null;
@@ -194,6 +217,10 @@ function scanAtoms(s, line, sink, depth = 0) {
                 // image/* data URIs pass through.
                 const rawSrc = paren.content.trim();
                 const src = isSafeUrl(rawSrc, true) ? rawSrc : "";
+                // A GEML target here means the author wanted a transclusion, which is a
+                // block: `=== embed`. Recorded for the caller to report.
+                if (/\.geml(#|$)/i.test(src))
+                    (sink.mediaDocTargets ??= []).push({ src, line });
                 const node = {
                     type: "image", alt: label.content, src, attrs: attrObj.attrs,
                 };

package/dist/mcp.js

@@ -163,7 +163,7 @@ function applyWrite(spec) {
     const before = readFileSync(real, "utf8");
     const root = realpathSync(OPTS.root);
     const errorKey = (d) => `${d.code}:${d.message}`;
-    const preexisting = new Set(parse(before, { resolveDoc: docResolver(root) }).diagnostics
+    const preexisting = new Set(parse(before, { resolveDoc: docResolver(root, real) }).diagnostics
         .filter((d) => d.severity === "error")
         .map(errorKey));
     // 1. Produce the mutated document WITHOUT touching the file. `--json` makes
@@ -190,7 +190,7 @@ function applyWrite(spec) {
     }
     // 2. Validate the RESULT independently of the CLI. This is what catches the
     //    tools the CLI lets through — deleting a referenced block, above all.
-    const diags = parse(after, { resolveDoc: docResolver(root) }).diagnostics;
+    const diags = parse(after, { resolveDoc: docResolver(root, real) }).diagnostics;
     let blocking = diags.filter((d) => d.severity === "error" && !preexisting.has(errorKey(d)));
     if (spec.danglingIsWarning) {
         blocking = blocking.filter((d) => d.code !== "unresolved-reference" && d.code !== "unresolved-footnote");
@@ -221,10 +221,18 @@ function snapshot(realPath, summary) {
         return undefined;
     }
 }
-function docResolver(root) {
+// A cross-document reference resolves FROM THE DOCUMENT'S OWN DIRECTORY, which is
+// what the CLI resolver and the renderer both do. Resolving from the server root
+// instead made the validator inspect a different file than the renderer expands:
+// for `sub/a.geml` naming `b.geml`, it validated `<root>/b.geml` while the render
+// pulled in `<root>/sub/b.geml` — phantom errors in one direction, and in the other
+// a write signed off against a file that was never the target. The root stays the
+// confinement boundary.
+function docResolver(root, fromFile) {
+    const base = dirname(fromFile);
     return (doc) => {
         try {
-            const target = realpathSync(resolve(root, doc));
+            const target = realpathSync(resolve(base, doc));
             if (target !== root && !target.startsWith(root + sep))
                 return null;
             return readFileSync(target, "utf8");
@@ -283,7 +291,7 @@ export const TOOLS = [
         run: (args) => {
             const real = resolveInRoot(args.file);
             const root = resolveRoot(args.root);
-            const doc = parse(readFileSync(real, "utf8"), { resolveDoc: docResolver(root) });
+            const doc = parse(readFileSync(real, "utf8"), { resolveDoc: docResolver(root, real) });
             const errors = doc.diagnostics.filter((d) => d.severity === "error").length;
             return {
                 ok: errors === 0,

package/dist/render.d.ts

@@ -18,6 +18,13 @@ export declare class RenderCtx {
     usedMermaid: boolean;
     usedCodeGraph: boolean;
     private renderDepth;
+    private embedStack;
+    private embedDocs;
+    private embedCount;
+    private embedBytes;
+    private embedCache;
+    private budgetExhausted;
+    private loadChildren;
     labels: Map<string, string>;
     constructor(doc: Document, opts?: RenderOptions);
     get isCodemapDoc(): boolean;
@@ -25,6 +32,18 @@ export declare class RenderCtx {
     docTitle(): string | undefined;
     inlines(ns: Inline[]): string;
     private inline;
+    private transclude;
+    private projectInline;
+    private projectFallback;
+    private get currentDocRel();
+    private get currentDocChildren();
+    private currentLabels;
+    private idAttr;
+    private remoteLabels;
+    private remoteLabel;
+    private fragmentHref;
+    private transclusionWrap;
+    private transclusionFallback;
     private media;
     private link;
     block(b: Block): string;

package/dist/render.js

@@ -11,12 +11,19 @@
 // exception. They load from a CDN, and only when the document actually uses them,
 // so a document of prose, tables and charts is fully self-contained with zero
 // network. Bundling those two engines offline is the next step (roadmap P0 #6).
+import { projectableInlines } from "./geml.js";
+import { isSafeUrl } from "./inline.js";
 const PALETTE = ["#2563eb", "#dc2626", "#059669", "#d97706", "#7c3aed", "#db2777", "#0891b2", "#ea580c"];
 // ---------------------------------------------------------------------------
 // Escaping
 // ---------------------------------------------------------------------------
 export function esc(s) {
-    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    // C0 controls other than tab/LF/CR are not valid in HTML text and, passed
+    // through verbatim, can desynchronize a downstream sanitizer, proxy or log
+    // pipeline. §0.4 only normalizes NUL; a document can still carry the rest, and a
+    // transclusion of a `.geml`-named binary carries a lot of them.
+    return s.replace(/[\x01-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "�")
+        .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 export function escAttr(s) {
     return esc(s).replace(/"/g, "&quot;");
@@ -39,6 +46,97 @@ const MAX_NESTING = 256;
 // ---------------------------------------------------------------------------
 // Render context
 // ---------------------------------------------------------------------------
+// S5: how deep transclusions may nest before the renderer stops expanding and
+// degrades to the reference link instead.
+const EMBED_DEPTH_CAP = 8;
+// Depth and cycle detection bound the SHAPE of a transclusion graph, never its
+// total. A diamond is not a cycle, and the cycle key is `path#fragment`, so eight
+// sections each embedding the next N times is eight distinct keys and N^8
+// expansions: 1.5KB of input reached 402MB of output, and one step further died on
+// an uncaught RangeError from string concatenation. These are the global budgets
+// that actually bound it, checked before every expansion.
+const EMBED_TOTAL_CAP = 1000; // expansions per render
+const EMBED_BYTES_CAP = 8 * 1024 * 1024; // expanded bytes per render
+const EMBED_DOC_BYTES_CAP = 4 * 1024 * 1024; // a single loaded document
+// §9.5 requires a class token to be REDUCED to the identifier charset, not escaped
+// — escaping keeps whatever was there. Only literals reach these call sites today,
+// so this is about not letting that invariant rest on the caller.
+function classAttrToken(s) {
+    return s.replace(/[^A-Za-z0-9_-]/g, "-");
+}
+// Compose a target that is relative to `base` — itself relative to the rendered
+// host file — into a path relative to that host. Pure string work on purpose:
+// render.ts is bundled for the browser (the playground), so no node:path here.
+// A scheme-bearing, protocol-relative or root-relative target is already
+// absolute and passes through untouched.
+function relJoin(base, target) {
+    if (base === "" || target === "" || target.startsWith("/") || /^[a-z][a-z0-9+.-]*:/i.test(target))
+        return target;
+    const out = [];
+    for (const s of (base + "/" + target).split("/")) {
+        if (s === "" || s === ".")
+            continue;
+        if (s === ".." && out.length > 0 && out[out.length - 1] !== "..")
+            out.pop();
+        else
+            out.push(s);
+    }
+    return out.join("/");
+}
+function relDir(p) {
+    const i = p.lastIndexOf("/");
+    return i < 0 ? "" : p.slice(0, i);
+}
+// S2: which blocks a fragment selects. No fragment is the whole document body
+// (meta is frontmatter, not content). A heading id selects its whole SECTION —
+// the heading plus everything up to the next heading at the same or a higher
+// level, the same boundary `geml get` uses — and any other id selects its own
+// block. Nested children are searched too: an id can live inside a flow block.
+function selectEmbed(children, anchor) {
+    if (anchor === undefined)
+        return children.filter((b) => !(b.kind === "block" && b.type === "meta"));
+    return findEmbedTarget(children, anchor);
+}
+function findEmbedTarget(blocks, id) {
+    for (let i = 0; i < blocks.length; i++) {
+        const b = blocks[i];
+        if (b.kind === "heading" && b.id === id) {
+            const out = [b];
+            for (let j = i + 1; j < blocks.length; j++) {
+                const next = blocks[j];
+                if (next.kind === "heading" && next.level <= b.level)
+                    break;
+                out.push(next);
+            }
+            return out;
+        }
+        if (b.kind === "block" && b.id === id)
+            return [b];
+        if (b.kind === "block" && b.children) {
+            const inner = findEmbedTarget(b.children, id);
+            if (inner !== null)
+                return inner;
+        }
+    }
+    return null;
+}
+// id -> label: a heading's text, a block's caption, else the id itself. Free of
+// the render context so a TARGET document can be indexed the same way, which is
+// what a cross-document auto-reference needs for its link text (§5.2).
+function indexLabelsInto(blocks, into) {
+    for (const b of blocks) {
+        if (b.kind === "heading")
+            into.set(b.id ?? "", b.text);
+        else if (b.kind === "block") {
+            if (b.id) {
+                const cap = b.attrs["caption"];
+                into.set(b.id, typeof cap === "string" ? cap : (b.table?.caption ?? b.id));
+            }
+            if (b.children)
+                indexLabelsInto(b.children, into);
+        }
+    }
+}
 export class RenderCtx {
     doc;
     opts;
@@ -46,6 +144,40 @@ export class RenderCtx {
     usedMermaid = false;
     usedCodeGraph = false;
     renderDepth = 0;
+    // S5: the (path#fragment) chain currently being expanded, for cycle
+    // detection and the depth cap. `embedDocs` is the chain of documents being
+    // expanded — each with its path relative to the host, so relative targets inside
+    // borrowed content compose through it (S4) and a fragment-only reference
+    // resolves against the document it was written in.
+    embedStack = [];
+    embedDocs = [];
+    // The global budgets, and a memo so a document is read and parsed at most once
+    // per render — without it a 1.1KB corpus produced 21,845 filesystem reads and
+    // 21,845 full re-parses, because every expansion loaded its target again.
+    embedCount = 0;
+    embedBytes = 0;
+    embedCache = new Map();
+    budgetExhausted() {
+        if (this.embedCount >= EMBED_TOTAL_CAP)
+            return `transclusion budget spent (${EMBED_TOTAL_CAP} expansions)`;
+        if (this.embedBytes >= EMBED_BYTES_CAP)
+            return `transclusion budget spent (${EMBED_BYTES_CAP} bytes)`;
+        return null;
+    }
+    // One read and one parse per document per render, and a size ceiling so a huge
+    // target cannot be expanded (or re-expanded) at all.
+    loadChildren(rel) {
+        const hit = this.embedCache.get(rel);
+        if (hit !== undefined)
+            return hit;
+        const { loadDoc, parseDoc } = this.opts;
+        let children = null;
+        const src = loadDoc && parseDoc ? loadDoc(rel) : null;
+        if (src !== null && src !== undefined && src.length <= EMBED_DOC_BYTES_CAP)
+            children = parseDoc(src).children;
+        this.embedCache.set(rel, children);
+        return children;
+    }
     labels = new Map(); // id -> link label for [[#id]] auto-refs
     constructor(doc, opts = {}) {
         this.doc = doc;
@@ -66,18 +198,7 @@ export class RenderCtx {
     }
     // Build the id -> label map: a heading's text, or a block's caption, or its id.
     indexLabels(blocks) {
-        for (const b of blocks) {
-            if (b.kind === "heading")
-                this.labels.set(b.id ?? "", b.text);
-            else if (b.kind === "block") {
-                if (b.id) {
-                    const cap = b.attrs["caption"];
-                    this.labels.set(b.id, typeof cap === "string" ? cap : (b.table?.caption ?? b.id));
-                }
-                if (b.children)
-                    this.indexLabels(b.children);
-            }
-        }
+        indexLabelsInto(blocks, this.labels);
     }
     docTitle() {
         for (const b of this.doc.children) {
@@ -108,15 +229,220 @@ export class RenderCtx {
             case "image": return this.media(n);
             case "link": return this.link(n);
             case "autoref": {
-                const href = n.doc ? `${n.doc.replace(/\.geml$/, ".html")}#${n.anchor}` : `#${n.anchor}`;
-                const label = n.doc ? (n.anchor ?? n.doc) : (this.labels.get(n.anchor) ?? n.anchor);
+                const href = n.doc ? `${relJoin(relDir(this.currentDocRel), n.doc).replace(/\.geml$/, ".html")}#${n.anchor}` : this.fragmentHref(n.anchor);
+                // §5.2: an auto-reference takes its text from the target's caption or
+                // heading. Across documents that means reading the target — which the
+                // build can do, since an embed pulls whole sections through the same hook.
+                // Inside borrowed content a fragment-only reference means an id of the
+                // BORROWED document, so its label has to come from there too. Taking it
+                // from `this.labels` showed the host's caption on a link whose destination
+                // is the source document's block — a text/target mismatch the host controls.
+                const label = n.doc
+                    ? (this.remoteLabel(n.doc, n.anchor) ?? n.anchor ?? n.doc)
+                    : (this.currentLabels().get(n.anchor) ?? n.anchor);
                 return `<a href="${escAttr(href)}">${esc(label)}</a>`;
             }
-            case "footnote": return `<sup class="fn"><a href="#${escAttr(n.ref)}">${esc(n.ref)}</a></sup>`;
+            case "project": return this.projectInline(n);
+            // Through fragmentHref like every other fragment-only reference: borrowed
+            // content owns no anchors, so a bare `#ref` here landed on a same-named
+            // footnote of the HOST — letting the host author choose what a borrowed
+            // sentence's citation says.
+            case "footnote": return `<sup class="fn"><a href="${escAttr(this.fragmentHref(n.ref))}">${esc(n.ref)}</a></sup>`;
+        }
+    }
+    // S2/S3/S5: expand a transclusion in place, wrapped in a container carrying its
+    // provenance. Every path that cannot expand falls back to a link to the target
+    // with the reason visible — never silently blank, never a broken image.
+    transclude(b, idAttr) {
+        const written = typeof b.attrs["src"] === "string" ? b.attrs["src"].trim() : "";
+        if (written === "")
+            return this.transclusionFallback("", idAttr, "invalid", "embed: missing `src=`");
+        const hash = written.indexOf("#");
+        const docPath = hash < 0 ? written : written.slice(0, hash);
+        const anchor = hash < 0 ? undefined : written.slice(hash + 1);
+        const { loadDoc, parseDoc } = this.opts;
+        // A same-document target (`src=#id`) selects from the document CURRENTLY being
+        // expanded, which inside borrowed content is the borrowed document, not the
+        // host. And it takes a cycle key like any other: the slice a heading id
+        // selects contains the embed that selected it, which is the smallest cycle
+        // there is. Skipping the key here is what let a 7-line document expand into
+        // 256 copies of itself, stopped only by the generic block-nesting guard.
+        const rel = docPath === "" ? this.currentDocRel : relJoin(relDir(this.currentDocRel), docPath);
+        const key = anchor === undefined ? rel : `${rel}#${anchor}`;
+        if (this.embedStack.includes(key)) {
+            return `<div class="transclusion transclusion-error"${idAttr} data-src="${escAttr(written)}">transclusion cycle: ${esc([...this.embedStack, key].join(" → "))}</div>`;
         }
+        if (this.embedStack.length >= EMBED_DEPTH_CAP) {
+            return this.transclusionFallback(written, idAttr, "too-deep", `transclusion depth cap (${EMBED_DEPTH_CAP}) reached`);
+        }
+        const spent = this.budgetExhausted();
+        if (spent !== null)
+            return this.transclusionFallback(written, idAttr, "too-large", spent);
+        let children;
+        if (docPath !== "" && !/\.geml$/i.test(docPath)) {
+            // Same constraint the parser reports: an embed stands for a GEML document.
+            // Parsing whatever else the target happens to contain injected its bytes
+            // into the page as prose.
+            return this.transclusionFallback(written, idAttr, "invalid", `\`${docPath}\` is not a GEML document`);
+        }
+        if (docPath === "") {
+            children = this.currentDocChildren;
+        }
+        else {
+            if (!loadDoc || !parseDoc)
+                return this.transclusionFallback(written, idAttr, "unexpanded", "no document resolver");
+            // Parsed on its own, so S4 holds for free: `{{key}}` inside borrowed content
+            // interpolates against the SOURCE document's meta, never the host's. Read
+            // through the cache: the same target is otherwise re-read and re-parsed once
+            // per expansion.
+            const loaded = this.loadChildren(rel);
+            if (loaded === null)
+                return this.transclusionFallback(written, idAttr, "unresolved", `cannot resolve document \`${docPath}\`, or it is too large`);
+            children = loaded;
+        }
+        const picked = selectEmbed(children, anchor);
+        if (picked === null) {
+            const what = docPath === "" ? `no \`${written}\` in this document` : `no \`#${anchor}\` in \`${docPath}\``;
+            return this.transclusionFallback(written, idAttr, "unresolved", what);
+        }
+        this.embedStack.push(key);
+        this.embedDocs.push({ rel, children });
+        try {
+            return this.transclusionWrap(written, idAttr, picked);
+        }
+        finally {
+            this.embedDocs.pop();
+            this.embedStack.pop();
+        }
+    }
+    // An inline projection: the target block's body, rendered here. Deliberately the
+    // same machinery as the block form — the cycle stack, the depth cap, and the
+    // document chain that drives S4 rebasing and the fragment-only rewrite — rather
+    // than a second path that would have to be kept in step with it. A projected
+    // phrase carrying a link is the normal case, so that rewrite matters more here.
+    projectInline(n) {
+        const written = n.doc === undefined ? `#${n.anchor}` : `${n.doc}#${n.anchor}`;
+        const { loadDoc, parseDoc } = this.opts;
+        const rel = n.doc === undefined ? this.currentDocRel : relJoin(relDir(this.currentDocRel), n.doc);
+        const key = `${rel}#${n.anchor}`;
+        if (this.embedStack.includes(key))
+            return this.projectFallback(written, "error", "transclusion cycle");
+        if (this.embedStack.length >= EMBED_DEPTH_CAP)
+            return this.projectFallback(written, "too-deep", `depth cap (${EMBED_DEPTH_CAP})`);
+        const spentHere = this.budgetExhausted();
+        if (spentHere !== null)
+            return this.projectFallback(written, "too-large", spentHere);
+        let children;
+        if (n.doc === undefined)
+            children = this.currentDocChildren;
+        else {
+            if (!loadDoc || !parseDoc)
+                return this.projectFallback(written, "unexpanded", "no document resolver");
+            const loaded = this.loadChildren(rel);
+            if (loaded === null)
+                return this.projectFallback(written, "unresolved", "unresolvable document, or too large");
+            children = loaded;
+        }
+        const got = projectableInlines(children, n.anchor);
+        if (got === null || got === "not-inline")
+            return this.projectFallback(written, "unresolved", "not inline content");
+        this.embedStack.push(key);
+        this.embedDocs.push({ rel, children });
+        try {
+            this.embedCount++;
+            const inner = this.inlines(got.inlines);
+            this.embedBytes += inner.length;
+            return `<span class="transclusion-inline" data-src="${escAttr(written)}">${inner}</span>`;
+        }
+        finally {
+            this.embedDocs.pop();
+            this.embedStack.pop();
+        }
+    }
+    projectFallback(written, why, note) {
+        const hash = written.indexOf("#");
+        const docPath = written.slice(0, hash);
+        const href = docPath === "" ? written : relJoin(relDir(this.currentDocRel), docPath).replace(/\.geml$/, ".html") + written.slice(hash);
+        const safe = isSafeUrl(href) ? href : "#";
+        return `<span class="transclusion-inline transclusion-${classAttrToken(why)}" data-src="${escAttr(written)}" title="${escAttr(note)}">`
+            + `<a href="${escAttr(safe)}">${esc(written)}</a></span>`;
+    }
+    // The document a transclusion is currently selecting from — the host until an
+    // expansion is in progress. `rel` is its path relative to the rendered host, so
+    // everything relative inside it composes through `relDir(rel)` (S4), and any
+    // fragment-only reference resolves against that document's own page.
+    get currentDocRel() {
+        return this.embedDocs.length === 0 ? "" : this.embedDocs[this.embedDocs.length - 1].rel;
+    }
+    get currentDocChildren() {
+        return this.embedDocs.length === 0 ? this.doc.children : this.embedDocs[this.embedDocs.length - 1].children;
+    }
+    // Labels of the document currently being expanded, built on first use per frame.
+    currentLabels() {
+        if (this.embedDocs.length === 0)
+            return this.labels;
+        const frame = this.embedDocs[this.embedDocs.length - 1];
+        if (frame.labels === undefined) {
+            frame.labels = new Map();
+            indexLabelsInto(frame.children, frame.labels);
+        }
+        return frame.labels;
+    }
+    // S9: borrowed content contributes no anchors to the host page. Two ids named
+    // the same is invalid HTML, and an in-page link to one of them would land on
+    // whichever the browser picked. The host keeps its own ids; a borrowed copy has
+    // none, and references into it resolve against its source document instead.
+    idAttr(id) {
+        return id === undefined || this.embedDocs.length > 0 ? "" : ` id="${escAttr(id)}"`;
+    }
+    // A fragment-only reference (`#id`, `[[#id]]`) inside borrowed content means an
+    // id of the BORROWED document. On the host page that anchor does not exist — or,
+    // worse, a same-named host block silently answers for it — so it points at the
+    // source document's page.
+    // The label a target document gives an id, for a cross-document auto-reference.
+    // Memoized per document: one page can reference the same document many times.
+    remoteLabels = new Map();
+    remoteLabel(doc, anchor) {
+        const { loadDoc, parseDoc } = this.opts;
+        if (!loadDoc || !parseDoc)
+            return undefined;
+        const rel = relJoin(relDir(this.currentDocRel), doc);
+        let labels = this.remoteLabels.get(rel);
+        if (labels === undefined) {
+            labels = new Map();
+            const src = loadDoc(rel);
+            if (src !== null)
+                indexLabelsInto(parseDoc(src).children, labels);
+            this.remoteLabels.set(rel, labels);
+        }
+        return labels.get(anchor);
+    }
+    fragmentHref(anchor) {
+        const rel = this.currentDocRel;
+        return rel === "" ? `#${anchor}` : `${rel.replace(/\.geml$/, ".html")}#${anchor}`;
+    }
+    transclusionWrap(written, idAttr, picked) {
+        this.embedCount++;
+        const inner = picked.map((x) => this.block(x)).filter((s) => s !== "").join("\n");
+        this.embedBytes += inner.length;
+        return `<section class="transclusion"${idAttr} data-src="${escAttr(written)}">${inner}</section>`;
+    }
+    transclusionFallback(written, idAttr, why, note) {
+        const hash = written.indexOf("#");
+        const docPath = hash < 0 ? written : written.slice(0, hash);
+        const frag = hash < 0 ? "" : written.slice(hash);
+        const href = docPath === "" ? frag : relJoin(relDir(this.currentDocRel), docPath).replace(/\.geml$/, ".html") + frag;
+        // Defence in depth: the parse layer already blanks an unsafe scheme (§9.5), so
+        // this should be unreachable. It is here because a fallback that composes an
+        // href from document text is exactly where a missed filter upstream becomes a
+        // live `javascript:` link — the shape of the one Critical finding in review.
+        const safe = isSafeUrl(href) ? href : "#";
+        const link = written === "" ? "" : `<a href="${escAttr(safe)}">${esc(written)}</a> `;
+        return `<div class="transclusion transclusion-${classAttrToken(why)}"${idAttr} data-src="${escAttr(written)}" title="${escAttr(note)}">`
+            + `${link}<span class="transclusion-note">${esc(note)}</span></div>`;
     }
     media(n) {
-        const src = escAttr(n.src);
+        const src = escAttr(relJoin(relDir(this.currentDocRel), n.src));
         if (n.as === "video")
             return `<video class="media" src="${src}" controls></video>`;
         if (n.as === "audio")
@@ -128,9 +454,9 @@ export class RenderCtx {
         if (n.href)
             href = n.href;
         else if (n.doc)
-            href = `${n.doc.replace(/\.geml$/, ".html")}${n.anchor ? "#" + n.anchor : ""}`;
+            href = `${relJoin(relDir(this.currentDocRel), n.doc).replace(/\.geml$/, ".html")}${n.anchor ? "#" + n.anchor : ""}`;
         else if (n.anchor)
-            href = `#${n.anchor}`;
+            href = this.fragmentHref(n.anchor);
         const rel = typeof n.attrs["rel"] === "string" ? ` rel="${escAttr(n.attrs["rel"])}"` : "";
         const target = typeof n.attrs["target"] === "string" ? ` target="${escAttr(n.attrs["target"])}"` : "";
         return `<a href="${escAttr(href)}"${rel}${target}>${this.inlines(n.children)}</a>`;
@@ -156,7 +482,7 @@ export class RenderCtx {
             case "heading": {
                 if (b.hidden)
                     return "";
-                const id = b.id ? ` id="${escAttr(b.id)}"` : "";
+                const id = this.idAttr(b.id);
                 const lvl = Math.min(6, Math.max(1, b.level));
                 return `<h${lvl}${id}>${this.inlines(b.inlines)}</h${lvl}>`;
             }
@@ -188,7 +514,7 @@ export class RenderCtx {
             return ""; // {hidden}: in the model, never rendered
         const raw = (b.raw ?? []).join("\n");
         const caption = typeof b.attrs["caption"] === "string" ? b.attrs["caption"] : undefined;
-        const idAttr = b.id ? ` id="${escAttr(b.id)}"` : "";
+        const idAttr = this.idAttr(b.id);
         switch (b.type) {
             case "meta": return ""; // header metadata, not body content
             case "code": {
@@ -196,8 +522,7 @@ export class RenderCtx {
                 const cls = lang ? ` class="language-${escAttr(lang)}"` : "";
                 return `<pre${idAttr}><code${cls}>${esc(raw)}</code></pre>`;
             }
-            case "output":
-                return `<pre class="output"${idAttr}><code>${esc(raw)}</code></pre>`;
+            case "embed": return this.transclude(b, idAttr);
             case "math":
                 this.usedMath = true;
                 return `<div class="math-block"${idAttr}>\\[${esc(raw)}\\]</div>`;
@@ -225,7 +550,7 @@ export class RenderCtx {
         }
     }
     diagram(b, raw, caption) {
-        const idAttr = b.id ? ` id="${escAttr(b.id)}"` : "";
+        const idAttr = this.idAttr(b.id);
         const fmt = typeof b.attrs["format"] === "string" ? b.attrs["format"] : "";
         const cap = caption ? `<figcaption>${esc(caption)}</figcaption>` : "";
         if (fmt === "geml-chart") {

package/dist/serialize.js

@@ -124,6 +124,7 @@ function serInline(n, esc) {
         case "image": return `![${n.alt}](${n.src})${serAttrs({ attrs: n.attrs })}`;
         case "link": return `[${serSeq(n.children, esc)}](${linkDest(n)})${serAttrs({ attrs: n.attrs })}`;
         case "autoref": return `[[${n.doc !== undefined ? `${n.doc}#${n.anchor}` : `#${n.anchor}`}]]`;
+        case "project": return `![[${n.doc !== undefined ? `${n.doc}#${n.anchor}` : `#${n.anchor}`}]]`;
         case "footnote": return `[^${n.ref}]`;
     }
 }
@@ -138,7 +139,14 @@ function serInlines(ns) {
     const lazy = serSeq(ns, false);
     if (JSON.stringify(parseInline(lazy, 0, { refs: [] })) === JSON.stringify(ns))
         return lazy;
-    return serSeq(ns, true);
+    const escaped = serSeq(ns, true);
+    if (JSON.stringify(parseInline(escaped, 0, { refs: [] })) === JSON.stringify(ns))
+        return escaped;
+    // Neither form round-trips on its own. The case this exists for: a text run
+    // ending in `!` immediately before an auto-reference re-reads as an inline
+    // projection (`!` + `[[` is one atom since §5.3), so the bang has to be escaped
+    // even though nothing about the text itself is a metacharacter.
+    return serSeq(ns, true).replace(/!(?=\[\[)/g, "\\!");
 }
 // ---------------------------------------------------------------------------
 // Blocks