@geml/geml 1.4.5 → 1.5.0

package/dist/geml.js

@@ -18,7 +18,7 @@ import { renderHtml } from "./render-html.js";
 import { normalizeBlockId } from "./block-edit.js";
 import { normalizeSource } from "./diagnostics.js";
 import { coerce, parseAttrs } from "./attrs.js";
-import { META_REF_SRC, parseInline } from "./inline.js";
+import { META_REF_SRC, parseInline, isSafeUrl, schemeOf } from "./inline.js";
 import { parseTable } from "./table.js";
 import { buildChart } from "./chart.js";
 import { mdToGeml } from "./from-md.js";
@@ -46,7 +46,7 @@ const REGISTRY = {
     diagram: "raw",
     math: "raw",
     table: "raw", // structured table parsing lands in M3
-    output: "raw", // captured result of a code block (stored, never executed)
+    embed: "raw", // block transclusion: `src=` points at the content, body unused
     note: "flow",
     text: "flow", // addressable prose container: an id/attrs for a run of flow, no callout chrome
     meta: "data",
@@ -319,12 +319,50 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             }
             if (attrs.attrs["hidden"] === true)
                 block.hidden = true; // §4: not rendered, still in model
-            // §3: an `output` block stores a code block's captured result; `of=#id`
-            // (when present) binds it to that block and is checked like any reference.
-            if (type === "output" && typeof attrs.attrs["of"] === "string") {
-                const of = attrs.attrs["of"];
-                if (of.startsWith("#"))
-                    ctx.refs.push({ kind: "internal", anchor: of.slice(1), line: openLineNo });
+            // Block transclusion: `src=` names the content this block stands for, and
+            // is registered as an ordinary reference so the existing §8 resolver
+            // validates the document and the id. Without that, an embed would be the
+            // one reference shape whose rot is silent.
+            if (type === "embed") {
+                const src = typeof attrs.attrs["src"] === "string" ? attrs.attrs["src"].trim() : "";
+                if (src === "") {
+                    diags.push({ severity: "error", code: "embed-missing-src", message: "embed: missing `src=`", line: openLineNo });
+                }
+                else {
+                    const hash = src.indexOf("#");
+                    const docPath = hash < 0 ? src : src.slice(0, hash);
+                    const anchor = hash < 0 ? undefined : src.slice(hash + 1);
+                    // §9.5: a destination naming a scheme outside the allowlist MUST NOT be
+                    // emitted as a navigable or loadable target, and the check belongs HERE —
+                    // when the model is built — so no consumer of the model can reintroduce
+                    // it. The attribute is blanked as well as reported, the same treatment a
+                    // media `src` already gets: a diagnostic alone would still leave the
+                    // string in `attrs` for a renderer to put in an href.
+                    if (!isSafeUrl(src)) {
+                        diags.push({ severity: "error", code: "unsafe-embed-scheme", message: `embed: \`src=${src}\` names a disallowed URL scheme`, line: openLineNo });
+                        block.attrs = { ...block.attrs, src: "" };
+                    }
+                    else if (docPath !== "" && !/\.geml$/i.test(docPath)) {
+                        diags.push({ severity: "error", code: "embed-target-not-geml", message: `embed: \`${docPath}\` is not a GEML document; \`src=\` names a \`.geml\` file (optionally with a #fragment)`, line: openLineNo });
+                    }
+                    else if (docPath === "") {
+                        // Recorded with an empty doc so the self-cycle pass can see it.
+                        if (anchor !== undefined)
+                            (ctx.embeds ??= []).push({ doc: "", anchor, line: openLineNo });
+                        // `src=#id`: a block of THIS document. Validated against local ids.
+                        if (anchor !== undefined)
+                            ctx.refs.push({ kind: "internal", anchor, line: openLineNo });
+                    }
+                    else {
+                        ctx.refs.push({ kind: "cross", doc: docPath, anchor, line: openLineNo });
+                        // Kept apart from refs: a transclusion can pull in a document that
+                        // transcludes further, so cycle detection has to walk the graph.
+                        (ctx.embeds ??= []).push(anchor === undefined ? { doc: docPath, line: openLineNo } : { doc: docPath, anchor, line: openLineNo });
+                    }
+                }
+                if (body.some((l) => l.trim() !== "")) {
+                    diags.push({ severity: "warning", code: "ignored-embed-body", message: "embed body is ignored; the target lives in `src=`", line: openLineNo });
+                }
             }
             if (mode === "flow") {
                 if (depth >= MAX_NESTING) {
@@ -344,8 +382,18 @@ function scanBlocks(lines, base, ctx, depth = 0) {
             else {
                 block.raw = body;
                 if (type === "table") {
+                    // `src=` and `data=` are one attribute in two spellings: where this
+                    // table's data comes from. Recorded for the post-scan pass.
+                    const srcAttr = typeof attrs.attrs["src"] === "string" ? attrs.attrs["src"].trim() : undefined;
+                    const dataAttr = typeof attrs.attrs["data"] === "string" ? attrs.attrs["data"].trim() : undefined;
+                    if (srcAttr !== undefined && dataAttr !== undefined) {
+                        diags.push({ severity: "error", code: "source-attr-conflict", message: "table has both `src=` and `data=`; they mean the same thing — use one", line: openLineNo });
+                    }
+                    const target = srcAttr ?? dataAttr;
                     // §6: parse the raw body (visual or csv/tsv) into one table model.
-                    const { model, diagnostics } = parseTable(body, attrs.attrs, openLineNo, ctx);
+                    const { model, diagnostics } = parseTable(body, target === undefined ? attrs.attrs : { ...attrs.attrs, src: target }, openLineNo, ctx);
+                    if (target !== undefined)
+                        (ctx.tableSources ??= []).push({ block, line: openLineNo, target });
                     block.table = model;
                     for (const d of diagnostics)
                         diags.push({ ...d, line: openLineNo });
@@ -448,6 +496,343 @@ function parseData(lines) {
 // ---------------------------------------------------------------------------
 // Collect the block ids of a (cross-document) source, without validation, for
 // resolving `other.geml#id` references.
+// S5/S6: a transclusion may pull in a document that transcludes further, so a
+// cycle is only visible by walking the graph. Reported at check time — before
+// any rendering — so a build fails on the cycle rather than on a placeholder in
+// the output. Paths compose the way the renderer composes them: a target inside
+// a borrowed document is relative to THAT document.
+// `data=rows.csv` on a chart, desugared: the anonymous table it stands for. Built
+// by handing the loaded lines to the SAME body parser a `=== table {src=…}` uses,
+// with the chart's own `format=`/`header=` carried over, so nothing about how the
+// data is read is specific to charts. Returns null when the source could not be
+// resolved — the diagnostic is already pushed, in the table rules' own words.
+function chartSourceTable(ctx, opts, block, target, line) {
+    const scheme = schemeOf(target);
+    if (scheme === "http" || scheme === "https") {
+        // §9.4: fetched at render time, so there is nothing to chart at build time —
+        // the same state a remote-sourced table leaves behind.
+        return null;
+    }
+    if (!opts.resolveDoc) {
+        ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `geml-chart: data source \`${target}\` not checked (no document resolver)`, line });
+        return null;
+    }
+    const text = opts.resolveDoc(target);
+    if (text === null) {
+        ctx.diags.push({ severity: "error", code: "unresolvable-table-source", message: `geml-chart: cannot resolve data source \`${target}\``, line });
+        return null;
+    }
+    const attrs = {
+        format: typeof block.attrs["format-data"] === "string" ? block.attrs["format-data"] : inferDataFormat(target),
+        header: block.attrs["header"] === undefined ? true : block.attrs["header"],
+    };
+    const { model, diagnostics } = parseTable(normalizeSource(text).split("\n"), attrs, line, ctx);
+    for (const d of diagnostics)
+        ctx.diags.push({ ...d, line });
+    model.src = target;
+    return model;
+}
+const inferDataFormat = (target) => (/\.tsv$/i.test(target) ? "tsv" : "csv");
+// The renderer's own cap (render.ts EMBED_DEPTH_CAP). Kept in step here so the
+// check and the render agree on which documents are reachable at all.
+const EMBED_DEPTH_LIMIT = 8;
+function detectTransclusionCycles(ctx, opts) {
+    if (!opts.resolveDoc || ctx.embeds === undefined || ctx.embeds.length === 0)
+        return;
+    const resolve = opts.resolveDoc;
+    const embedsOf = new Map(); // memoized per path
+    const reported = new Set();
+    // A three-colour DFS over DOCUMENTS, not over paths. Enumerating every path
+    // through the graph is exponential in its fan-out: a chain of 21 tiny files,
+    // each embedding the next three times, took over two minutes — and `check` is
+    // the CI gate and the validator every MCP write runs twice. Grey means "on the
+    // current stack" and is the cycle; black means already fully explored, so each
+    // edge is walked once and the whole traversal is O(V+E).
+    const colour = new Map();
+    const walk = (path, base, stack, line) => {
+        const rel = relJoinPath(base, path);
+        if (colour.get(rel) === "grey") {
+            const chain = [...stack, rel].join(" → ");
+            if (reported.has(chain))
+                return;
+            reported.add(chain);
+            ctx.diags.push({ severity: "error", code: "transclusion-cycle", message: `transclusion cycle: ${chain}`, line });
+            return;
+        }
+        if (colour.get(rel) === "black")
+            return;
+        // Agree with the renderer about what is even reachable, instead of exploring
+        // eight times deeper than it will ever expand.
+        if (stack.length >= EMBED_DEPTH_LIMIT)
+            return;
+        colour.set(rel, "grey");
+        let inner = embedsOf.get(rel);
+        if (inner === undefined) {
+            const src = resolve(rel);
+            inner = src === null ? [] : gatherEmbeds(src); // an unresolvable doc is already an error
+            embedsOf.set(rel, inner);
+        }
+        for (const e of inner)
+            walk(e.doc, relDirPath(rel), [...stack, rel], line);
+        colour.set(rel, "black");
+    };
+    // The root is named so a chain can be seen returning to it. Falling back to ""
+    // only loses the A→…→A case, which is what happened before `self` existed.
+    const root = opts.self ?? "";
+    for (const e of ctx.embeds)
+        walk(e.doc, relDirPath(root), [root], e.line);
+}
+// The smallest cycle of all, and the one the cross-document walk above cannot
+// see: `=== embed {src=#sec}` written INSIDE the section `#sec` selects the slice
+// that contains it. Decided on spans, so the boundary is exactly the one `geml
+// get` uses — a heading id spans its whole section, so an embed anywhere in that
+// section is inside its own target.
+function detectSelfEmbedCycles(source, ctx) {
+    const selfEmbeds = (ctx.embeds ?? []).filter((e) => e.doc === "" && e.anchor !== undefined);
+    if (selfEmbeds.length === 0)
+        return;
+    const spans = blockSpans(source);
+    for (const e of selfEmbeds) {
+        const span = spans.get(e.anchor);
+        if (span === undefined)
+            continue; // a missing id is already an unresolved reference
+        const line = e.line - 1; // spans are 0-based line indices
+        if (line >= span.start && line <= span.end) {
+            ctx.diags.push({
+                severity: "error",
+                code: "transclusion-cycle",
+                message: `transclusion cycle: \`#${e.anchor}\` selects the content this embed is part of`,
+                line: e.line,
+            });
+        }
+    }
+}
+// A phrase that projects itself. The same shape as detectSelfEmbedCycles, and
+// deliberately the same machinery rather than a second parallel one: decided on
+// spans, so a projection written anywhere inside its own target is caught.
+function detectSelfProjectionCycles(source, ctx) {
+    const local = (ctx.projections ?? []).filter((p) => p.doc === undefined);
+    if (local.length === 0)
+        return;
+    const spans = blockSpans(source);
+    for (const p of local) {
+        const span = spans.get(p.anchor);
+        if (span === undefined)
+            continue;
+        const line = p.line - 1;
+        if (line >= span.start && line <= span.end) {
+            ctx.diags.push({
+                severity: "error",
+                code: "transclusion-cycle",
+                message: `transclusion cycle: \`![[#${p.anchor}]]\` projects the content it is part of`,
+                line: p.line,
+            });
+        }
+    }
+}
+// Inline content that a projection may stand for: a `text` block whose body is a
+// single paragraph. Returned so the renderer and this validator agree on one
+// definition. Anything else — a heading (and so a whole section), a table, a
+// diagram, a multi-paragraph body — is block content, and no amount of syntax
+// makes it fit inside a sentence.
+export function projectableInlines(blocks, id) {
+    const found = (function find(bs) {
+        for (const b of bs) {
+            if ((b.kind === "block" || b.kind === "heading") && b.id === id)
+                return b;
+            if (b.kind === "block" && b.children) {
+                const inner = find(b.children);
+                if (inner)
+                    return inner;
+            }
+        }
+        return undefined;
+    })(blocks);
+    if (found === undefined)
+        return null;
+    if (found.kind !== "block" || found.type !== "text")
+        return "not-inline";
+    const kids = (found.children ?? []).filter((c) => !(c.kind === "paragraph" && c.text.trim() === ""));
+    if (kids.length !== 1 || kids[0].kind !== "paragraph")
+        return "not-inline";
+    return { inlines: kids[0].inlines };
+}
+// A projection may only stand for inline content, and the target decides — the
+// same shape of rule as `table-source-not-a-table`, not a rule about where the
+// reference was written.
+function validateProjections(children, ctx, opts) {
+    for (const p of ctx.projections ?? []) {
+        let blocks = null;
+        if (p.doc === undefined)
+            blocks = children;
+        else if (opts.resolveDoc) {
+            const src = opts.resolveDoc(p.doc);
+            if (src === null)
+                continue; // already an unresolvable-document error
+            blocks = parse(src).children;
+        }
+        if (blocks === null)
+            continue; // unchecked without a resolver, like any cross-doc ref
+        const got = projectableInlines(blocks, p.anchor);
+        if (got === null)
+            continue; // already an unresolved-reference error
+        if (got === "not-inline") {
+            const target = p.doc === undefined ? `#${p.anchor}` : `${p.doc}#${p.anchor}`;
+            ctx.diags.push({
+                severity: "error",
+                code: "inline-transclusion-not-inline",
+                message: `\`![[${target}]]\` projects inline content, but the target is not a single-paragraph \`text\` block; for block content use \`=== embed {src=${target}}\``,
+                line: p.line,
+            });
+        }
+    }
+}
+// Same pure-string path composition the renderer uses (relJoin/relDir there).
+function relJoinPath(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 relDirPath(p) {
+    const i = p.lastIndexOf("/");
+    return i < 0 ? "" : p.slice(0, i);
+}
+function gatherEmbeds(source) {
+    const ctx = { diags: [], ids: new Map(), refs: [], meta: new Map(), embeds: [] };
+    scanBlocks(normalizeSource(source).split("\n"), 0, ctx);
+    return (ctx.embeds ?? []).map((e) => (e.anchor === undefined ? { doc: e.doc } : { doc: e.doc, anchor: e.anchor }));
+}
+// One rule for "where this data comes from", shared by a table's `src=`/`data=`
+// and a chart's `data=`. Three target forms: a data file, `#id` naming a table
+// block in this document, or `doc.geml#id` naming one in another document. An
+// unresolvable target is an error — a table whose source silently produced no
+// rows used to render as an empty table with no diagnostic at all.
+function tableFromDocument(source, id) {
+    const ctx = { diags: [], ids: new Map(), refs: [], meta: new Map() };
+    const blocks = scanBlocks(normalizeSource(source).split("\n"), 0, ctx);
+    const found = ctx.tables?.get(id);
+    if (found !== undefined)
+        return found;
+    const anyBlock = (function find(bs) {
+        for (const b of bs) {
+            if ((b.kind === "block" || b.kind === "heading") && b.id === id)
+                return b;
+            if (b.kind === "block" && b.children) {
+                const inner = find(b.children);
+                if (inner)
+                    return inner;
+            }
+        }
+        return undefined;
+    })(blocks);
+    return anyBlock === undefined ? null : "not-a-table";
+}
+function resolveTableSources(ctx, opts) {
+    const pending = ctx.tableSources ?? [];
+    if (pending.length === 0)
+        return;
+    const err = (line, code, message) => void ctx.diags.push({ severity: "error", code, message, line });
+    // Data files first: a `#id` target may point at a table whose OWN rows come
+    // from a file, and this way that table is already populated when it is read.
+    for (const { block, line, target } of pending) {
+        if (target.includes("#"))
+            continue;
+        // §9.4: a remote source is fetched by the RENDERER, not the parser. Leaving
+        // `model.src` set with no columns is the state resolveCharts already handles,
+        // so a chart over it defers too. Passing it to resolveDoc treated a URL as a
+        // filesystem path and failed a spec-conformant document.
+        const scheme = schemeOf(target);
+        if (scheme === "http" || scheme === "https")
+            continue;
+        if (scheme !== null) {
+            err(line, "unresolvable-table-source", `table source \`${target}\` names a disallowed URL scheme`);
+            continue;
+        }
+        // A data source is data. Without this the loader read any file under the base
+        // — a `.env`, a private key — split it into rows, and put it in the model and
+        // the page, with no diagnostic. `embed` already applies the same shape of rule.
+        if (!/\.(csv|tsv)$/i.test(target)) {
+            err(line, "unresolvable-table-source", `table source \`${target}\` is not a \`.csv\`/\`.tsv\` data file`);
+            continue;
+        }
+        if (!opts.resolveDoc) {
+            ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `table source \`${target}\` not checked (no document resolver)`, line });
+            continue;
+        }
+        const text = opts.resolveDoc(target);
+        if (text === null) {
+            err(line, "unresolvable-table-source", `cannot resolve table source \`${target}\``);
+            continue;
+        }
+        // Reuse the body parser: with `src`/`data` dropped, the file's lines are just
+        // this table's body, so format/header/compute/summary all behave identically.
+        const attrs = { ...block.attrs };
+        delete attrs["src"];
+        delete attrs["data"];
+        const { model, diagnostics } = parseTable(normalizeSource(text).split("\n"), attrs, line, ctx);
+        model.src = target;
+        block.table = model;
+        for (const d of diagnostics)
+            ctx.diags.push({ ...d, line });
+        if (block.id !== undefined)
+            (ctx.tables ??= new Map()).set(block.id, model);
+    }
+    for (const { block, line, target } of pending) {
+        const hash = target.indexOf("#");
+        if (hash < 0)
+            continue;
+        const docPath = target.slice(0, hash);
+        const id = target.slice(hash + 1);
+        let model;
+        if (docPath === "") {
+            const local = ctx.tables?.get(id);
+            if (local === undefined) {
+                if (ctx.ids.has(id))
+                    err(line, "table-source-not-a-table", `table source \`#${id}\` is not a table`);
+                else
+                    err(line, "unresolved-reference", `unresolved reference \`#${id}\``);
+                continue;
+            }
+            model = local;
+        }
+        else {
+            if (!opts.resolveDoc) {
+                ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `table source \`${target}\` not checked (no document resolver)`, line });
+                continue;
+            }
+            const text = opts.resolveDoc(docPath);
+            if (text === null) {
+                err(line, "unresolvable-document", `cannot resolve document \`${docPath}\``);
+                continue;
+            }
+            const remote = tableFromDocument(text, id);
+            if (remote === null) {
+                err(line, "unresolved-cross-document-reference", `unresolved reference \`${target}\``);
+                continue;
+            }
+            if (remote === "not-a-table") {
+                err(line, "table-source-not-a-table", `table source \`${target}\` is not a table`);
+                continue;
+            }
+            model = remote;
+        }
+        // Borrowed, not copied in the source: the model is shared, so the borrowing
+        // table means exactly what the original means. Its own caption still wins.
+        const caption = block.table?.caption;
+        block.table = caption === undefined ? model : { ...model, caption };
+        if (block.id !== undefined)
+            (ctx.tables ??= new Map()).set(block.id, block.table);
+    }
+}
 function gatherIds(source) {
     const ctx = { diags: [], ids: new Map(), refs: [], meta: new Map() };
     scanBlocks(normalizeSource(source).split("\n"), 0, ctx);
@@ -512,26 +897,77 @@ function validateRefs(ctx, opts) {
 }
 // §7: resolve every geml-chart against its referenced table. Runs after the
 // scan so that `data=#id` may point at a table defined anywhere in the doc.
-function resolveCharts(ctx) {
+function resolveCharts(ctx, opts) {
     for (const { block, line } of ctx.charts ?? []) {
-        const ref = typeof block.attrs["data"] === "string" ? block.attrs["data"] : "";
-        const id = ref.replace(/^#/, "");
-        if (id === "") {
+        const ref = typeof block.attrs["data"] === "string" ? block.attrs["data"].trim() : "";
+        if (ref === "" || ref === "#") {
             ctx.diags.push({ severity: "error", code: "chart-missing-data", message: "geml-chart: missing `data=#id`", line });
             continue;
         }
-        const table = ctx.tables?.get(id);
-        if (!table) {
-            const known = ctx.ids.has(id);
-            const what = known ? `data target \`#${id}\` is not a table` : `unresolved reference \`#${id}\``;
-            const code = known ? "chart-data-not-a-table" : "unresolved-reference";
-            ctx.diags.push({ severity: "error", code, message: `geml-chart: ${what}`, line });
-            continue;
+        // `data=` resolves by the same rule as a table's source: `#id` (or a bare id)
+        // names a table in THIS document, `doc.geml#id` one in another. Splitting on
+        // the LAST `#` is what the old code got wrong — it stripped the leading one
+        // and reported `#other.geml#fy25`, a target that never existed.
+        const hash = ref.indexOf("#");
+        const docPath = hash <= 0 ? "" : ref.slice(0, hash);
+        const id = hash < 0 ? ref : ref.slice(hash + 1);
+        let table;
+        if (docPath === "") {
+            table = ctx.tables?.get(id);
+            if (!table) {
+                // A chart is a view of a table, and a data file is one of the three ways
+                // §6 lets a table name its content. So `data=rows.csv` desugars: it is an
+                // anonymous table with that source, feeding this chart. Nothing new is
+                // invented — the resolution, the `.csv`/`.tsv` gate, the §9.4 remote rule
+                // and `format=` all come from the table rules, which is what makes the one
+                // source rule hold for charts too instead of charts being its exception.
+                if (hash < 0 && /\.(csv|tsv)$/i.test(id)) {
+                    const sugar = chartSourceTable(ctx, opts, block, id, line);
+                    if (sugar === null)
+                        continue; // already reported by the table rules
+                    table = sugar;
+                }
+                else if (hash < 0 && /\.[a-z0-9]+$/i.test(id)) {
+                    ctx.diags.push({ severity: "error", code: "unresolvable-table-source", message: `geml-chart: \`data=${id}\` is not a \`.csv\`/\`.tsv\` data file, and not a \`#id\` naming a table`, line });
+                    continue;
+                }
+                else {
+                    const known = ctx.ids.has(id);
+                    const what = known ? `data target \`#${id}\` is not a table` : `unresolved reference \`#${id}\``;
+                    const code = known ? "chart-data-not-a-table" : "unresolved-reference";
+                    ctx.diags.push({ severity: "error", code, message: `geml-chart: ${what}`, line });
+                    continue;
+                }
+            }
         }
-        if (table.src !== undefined) {
-            // §6: the table's data is external (src=), loaded at render time. The
-            // chart is therefore resolved at render time too — its column references
-            // are checked there, not here — so skip build-time chart resolution.
+        else {
+            if (!opts.resolveDoc) {
+                ctx.diags.push({ severity: "warning", code: "unchecked-cross-document-reference", message: `geml-chart: data target \`${ref}\` not checked (no document resolver)`, line });
+                continue;
+            }
+            const text = opts.resolveDoc(docPath);
+            if (text === null) {
+                ctx.diags.push({ severity: "error", code: "unresolvable-document", message: `geml-chart: cannot resolve document \`${docPath}\``, line });
+                continue;
+            }
+            const remote = tableFromDocument(text, id);
+            if (remote === null) {
+                ctx.diags.push({ severity: "error", code: "unresolved-cross-document-reference", message: `geml-chart: unresolved reference \`${ref}\``, line });
+                continue;
+            }
+            if (remote === "not-a-table") {
+                ctx.diags.push({ severity: "error", code: "chart-data-not-a-table", message: `geml-chart: data target \`${ref}\` is not a table`, line });
+                continue;
+            }
+            table = remote;
+        }
+        if (table.src !== undefined && table.columns.length === 0) {
+            // §6: the table names a source whose data did not arrive at build time — a
+            // remote URL, or any source with no document resolver supplied. The chart is
+            // therefore resolved at render time, and its column names are checked there.
+            // The test is whether the data is actually here, not what the source looks
+            // like: skipping every `src` table unconditionally is what left a chart
+            // unbuilt with no diagnostic while the page said to go and read one.
             continue;
         }
         const { model, diagnostics } = buildChart(block.attrs, table);
@@ -545,8 +981,25 @@ export function parse(source, opts = {}) {
     const lines = normalizeSource(source).split("\n");
     const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines), resolveDoc: opts.resolveDoc };
     const children = scanBlocks(lines, 0, ctx);
-    resolveCharts(ctx);
+    // Table sources first: a chart reads the build-time model of the table it
+    // charts, so that model has to be filled before charts are resolved.
+    resolveTableSources(ctx, opts);
+    resolveCharts(ctx, opts);
     validateRefs(ctx, opts);
+    detectTransclusionCycles(ctx, opts);
+    detectSelfEmbedCycles(source, ctx);
+    validateProjections(children, ctx, opts);
+    detectSelfProjectionCycles(source, ctx);
+    for (const m of ctx.mediaDocTargets ?? []) {
+        ctx.diags.push({
+            severity: "error",
+            code: "media-target-is-document",
+            // `!` projects, so a GEML target here is a near-miss an author will reach for
+            // once that reading is established. Name both forms it could have meant.
+            message: `\`![](${m.src})\` projects a GEML document, which is not media: for block content use \`=== embed {src=${m.src}}\`, for a phrase use \`![[${m.src}]]\``,
+            line: m.line,
+        });
+    }
     return { kind: "document", children, ids: [...ctx.ids.keys()], diagnostics: ctx.diags };
 }
 // The id that a fence/heading line defines, matching how scanBlocks derives it
@@ -797,7 +1250,10 @@ export const PARSER_VERSION = (() => {
 const USAGE = `geml — GEML reference CLI
 
 Usage:
-  geml <file.geml|-> [--to <fmt>] [--from <fmt>] [-o out]   transform a document (default: --to json)
+  geml <file.geml|-> [--to <fmt>] [--from <fmt>] [--root d] [-o out]   transform a document (default: --to json)
+                                             (--root widens cross-doc resolution to dir d, as on check — an
+                                              === embed whose target sits above the file's own directory
+                                              needs it, or it renders unresolved)
                                              --to  <output>: json | html | md | geml
                                                --to md    -> Markdown (lossy)
                                                --to html  -> self-contained HTML
@@ -826,9 +1282,10 @@ Usage:
   geml history <commit|verify|show|restore|log> <file.geml> [...]   .gemlhistory version sidecar
   geml codemap <build|verify|render|serve|refresh|find> [...]       code-graph toolkit (alias: codegraph)
   geml mcp    --root <dir> [--graph <dir>] [--no-history]   serve documents (and the code graph) over MCP (stdio)
-                                             (9 tools: list/read/check/history + write/add/delete/rename/revert;
-                                              every write is validated before it reaches disk. A code graph under
-                                              --root adds resolve_name/open_symbol/get_backlinks to the same server)
+                                             (10 tools, each geml_ + its CLI verb: list/get/check/history/to +
+                                              set/add/delete/rename/revert; every write is validated before it
+                                              reaches disk. A code graph under --root adds four read-only
+                                              geml_codemap_* tools to the same server)
   geml --help | --version [--json]
 
 Use '-' as the file to read from stdin.
@@ -861,20 +1318,22 @@ const SUBHELP = {
     mcp: `usage: geml mcp --root <dir> [--graph <dir>] [--no-history]
 
   Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).
-  Nine tools: geml_list_ids · geml_read_block · geml_check · geml_history_log
-              geml_write_block · geml_add_block · geml_delete_block
-              geml_rename_id · geml_revert_block
-  With a code graph under --root, three more (read-only), so one client entry
-  covers both: resolve_name · open_symbol · get_backlinks
+  Every tool is geml_ + its CLI verb, so the terminal and the assistant share
+  one vocabulary.
+  Ten tools: geml_list · geml_get · geml_check · geml_history · geml_to
+             geml_set · geml_add · geml_delete · geml_rename · geml_revert
+  With a code graph under --root, four more (read-only), so one client entry
+  covers both: geml_codemap_search · geml_codemap_callchain
+               geml_codemap_list · geml_codemap_node
 
   --root <dir>        REQUIRED. Root holding the .geml documents. Every path a
                       client names is confined here; a client cannot widen it.
   --graph <dir>       Code-graph directory, inside --root. Defaults to
                       <root>/.geml-code-graph when it holds an index.geml; with
-                      no graph the three graph tools are not served at all.
+                      no graph the four graph tools are not served at all.
   --no-history        Skip the .gemlhistory commit taken before each write
-                      (default: commit, so geml_revert_block always has a
-                      revision to undo to).
+                      (default: commit, so geml_revert always has a revision to
+                      undo to).
 
   Register with a client:
     claude mcp add geml -- geml mcp --root /abs/path/to/repo`,
@@ -999,7 +1458,7 @@ function runCheck(args) {
         if (!isDir)
             fail(`--root ${root} is not a directory`);
     }
-    const doc = parse(readInput(file), { resolveDoc: resolverFor(file, root) });
+    const doc = parse(readInput(file), { resolveDoc: resolverFor(file, root), self: file === "-" ? undefined : basename(file) });
     if (json) {
         console.log(JSON.stringify(doc.diagnostics, null, 2));
     }
@@ -1087,7 +1546,15 @@ function runTransform(argv) {
     const out = flag(argv, "-o") ?? flag(argv, "--out");
     const fromRaw = flag(argv, "--from");
     const toRaw = flag(argv, "--to");
-    const [file] = positionals(argv, ["-o", "--out", "--from", "--to"]);
+    // Same `--root` as `check`, and for the same reason: cross-document resolution is
+    // fail-closed at the document's own directory, so a reference that climbs out of
+    // it needs the tree's root named. Without this the transform silently ignored the
+    // flag — a document whose embeds `check --root .` validated still rendered with
+    // every one of them unresolved, which reads as "transclusion does not work".
+    const root = flag(argv, "--root");
+    if (argv.includes("--root") && root === undefined)
+        fail("--root needs a directory", 2);
+    const [file] = positionals(argv, ["-o", "--out", "--from", "--to", "--root"]);
     if (!file)
         fail("no input file (use '-' to read from stdin)", 2);
     // A bare `--to`/`--from` (no following value) is a mistyped flag, not a
@@ -1146,10 +1613,10 @@ function runTransform(argv) {
     else if (inFmt === "md") {
         const conv = mdToGeml(src);
         notes = conv.notes;
-        doc = parse(conv.geml, { resolveDoc: resolverFor(file) });
+        doc = parse(conv.geml, { resolveDoc: resolverFor(file, root), self: file === "-" ? undefined : basename(file) });
     }
     else {
-        doc = parse(src, { resolveDoc: resolverFor(file) });
+        doc = parse(src, { resolveDoc: resolverFor(file, root), self: file === "-" ? undefined : basename(file) });
     }
     let output;
     switch (outFmt) {
@@ -1163,8 +1630,8 @@ function runTransform(argv) {
             output = renderHtml(doc, {
                 source: file === "-" ? "stdin" : basename(file),
                 // geml-code-graph embeds load + parse sibling codemap docs on demand.
-                loadDoc: resolverFor(file),
-                parseDoc: (s) => parse(s),
+                loadDoc: resolverFor(file, root),
+                parseDoc: (s) => parse(s, { resolveDoc: resolverFor(file, root) }),
             });
             break;
         case "md": {
@@ -1288,7 +1755,7 @@ function resolveSelector(source, file, raw) {
         return bare;
     const level = m[1].length;
     const want = m[2];
-    const doc = parse(source, { resolveDoc: resolverFor(file) });
+    const doc = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const heads = doc.ids.flatMap((id) => {
         const site = findBlockSite(doc.children, id);
         const b = site?.siblings[site.index];
@@ -1329,7 +1796,7 @@ function resolveSelector(source, file, raw) {
 // (the registration order parse() records), covering the same set `get #id`
 // resolves against: typed blocks, headings, and footnote definitions.
 function listIds(source, file, json) {
-    const doc = parse(source, { resolveDoc: resolverFor(file) });
+    const doc = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const rows = doc.ids.map((id) => {
         const site = findBlockSite(doc.children, id);
         const b = site?.siblings[site.index];
@@ -1388,7 +1855,7 @@ function getByType(source, file, type, json, headOnly) {
             // The ONLY block of its type: locating it in the model needs no index, so
             // --json can still answer with the parsed node (meta's key/values, a
             // table's model) rather than a mere location.
-            const node = onlyBlockOfType(parse(source, { resolveDoc: resolverFor(file) }).children, type);
+            const node = onlyBlockOfType(parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) }).children, type);
             if (node) {
                 console.log(JSON.stringify(node, null, 2));
                 return;
@@ -1454,7 +1921,7 @@ function runGet(args) {
     if (json) {
         // The model node(s) — same shapes `geml <file>` emits. Parsing is needed
         // to resolve the tree (and nested-block ids), but only the target prints.
-        const doc = parse(source, { resolveDoc: resolverFor(file) });
+        const doc = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
         const site = findBlockSite(doc.children, id);
         if (!site)
             fail(`no block with id \`${id}\``, 1);
@@ -1529,6 +1996,11 @@ function runSet(args) {
         return;
     }
     // default / --head: content is a whole block (default) or a bare head line.
+    // Does the target exist? Asked FIRST: the shape checks below name the id in
+    // their advice ("use --body to set the body of #far"), which reads as though the
+    // id were there. Whether the content is prose is the second question.
+    if (!blockSpans(source).has(id))
+        fail(`no block with id \`${id}\``, 1);
     let content;
     if (rawChannel) {
         content = readInput("-");
@@ -1652,7 +2124,7 @@ function runAdd(args) {
 // or duplicate id surfaces as an error diagnostic) and no pre-existing id may
 // vanish. Returns the updated text; on any violation fail()s and writes nothing.
 function insertFragment(source, lines, at, fragment, file) {
-    const beforeIds = parse(source, { resolveDoc: resolverFor(file) }).ids;
+    const beforeIds = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) }).ids;
     const before = lines.slice(0, at);
     const after = lines.slice(at);
     const nl = newlineOf(source); // the fragment AND every separator we add
@@ -1669,7 +2141,7 @@ function insertFragment(source, lines, at, fragment, file) {
     const sepBefore = before.length && !blank(before[before.length - 1]) ? nl : "";
     const sepAfter = after.length && !blank(after[0]) ? nl : "";
     const updated = before.join("") + sepBefore + frag + sepAfter + after.join("");
-    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
     if (errs.length) {
         const first = errs[0];
@@ -1719,7 +2191,7 @@ function runDelete(args) {
     const updated = splitLines(source).filter((_, i) => !toDelete.has(i)).join("");
     // Lenient guard: surface any resulting error diagnostic (a reference now
     // dangling) as a WARNING, but write regardless.
-    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     for (const d of reparsed.diagnostics.filter((x) => x.severity === "error")) {
         console.error(`warning: ${d.message} (line ${d.line}) — left dangling by delete; run 'geml check' to see it as an error`);
     }
@@ -1738,7 +2210,7 @@ function runRename(args) {
     if (oldId === newId)
         fail("#old and #new are the same id — nothing to rename", 2);
     const source = readInput(file);
-    const before = parse(source, { resolveDoc: resolverFor(file) });
+    const before = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     if (!before.ids.includes(oldId))
         fail(`no block with id \`${oldId}\``, 1);
     if (before.ids.includes(newId))
@@ -1758,7 +2230,7 @@ function runRename(args) {
         }
     }
     const updated = rewriteId(source, oldId, newId, file);
-    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
     if (errs.length) {
         const e = errs[0];
@@ -1789,7 +2261,7 @@ function runRename(args) {
 // text, not a reference. (Known residual: id-less raw bodies and inline
 // code/math spans in flow content — see design §8.)
 function rewriteId(source, oldId, newId, file) {
-    const doc = parse(source, { resolveDoc: resolverFor(file) });
+    const doc = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const spans = blockSpans(source);
     const protectedLines = new Set();
     for (const b of doc.children) {
@@ -1897,7 +2369,7 @@ function spliceBlock(source, id, replacement, file, headOnly = false, guardCount
     const found = blockSpans(source).get(id);
     if (!found)
         fail(`no block with id \`${id}\``, 1);
-    const beforeDoc = parse(source, { resolveDoc: resolverFor(file) });
+    const beforeDoc = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const beforeIds = beforeDoc.ids;
     // Keep the bytes before and after the target span exactly; give the new block
     // a single trailing newline so the following block still starts on its own
@@ -1921,7 +2393,7 @@ function spliceBlock(source, id, replacement, file, headOnly = false, guardCount
     // surface as error diagnostics (registerId flags dups); one check covers both.
     // Then require the target id to survive, and — because a malformed replacement
     // can swallow a neighbour — that every other pre-existing id survives too.
-    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
     if (errs.length) {
         const first = errs[0];
@@ -2104,9 +2576,9 @@ function runRevert(args) {
         return;
     }
     const span = curFull;
-    const beforeIds = parse(source, { resolveDoc: resolverFor(file) }).ids;
+    const beforeIds = parse(source, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) }).ids;
     const updated = splitLines(source).filter((_, i) => i < span.start || i >= span.end).join("");
-    const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
+    const reparsed = parse(updated, { resolveDoc: resolverFor(file), self: file === "-" ? undefined : basename(file) });
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
     if (errs.length) {
         const first = errs[0];