@geml/geml 1.4.6 → 1.5.1

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,
                 };
@@ -288,8 +315,13 @@ function scanAtoms(s, line, sink, depth = 0) {
 // guesswork. Delimiters pair only *within* one text run: they never reach across
 // a code span, inline math, a link or image (atoms from phase A), or a block
 // boundary. Any delimiter left unpaired is literal text.
-const ASCII_PUNCT = /[!-\/:-@\[-`{-~]/;
-const isPunct = (c) => c !== undefined && ASCII_PUNCT.test(c);
+// Unicode punctuation, not just ASCII (§5.3). With an ASCII-only test, `“` and
+// `，` count as ordinary letters, and a run hugged by CJK punctuation on the
+// outside and ASCII punctuation on the inside stops flanking: `“*(foo)*”` loses
+// its emphasis. CommonMark's rule is Unicode-wide, and the algorithm here is
+// meant to be that rule restricted to `*` and `~~` — not a narrower one.
+const PUNCT = /[\p{P}\p{S}]/u;
+const isPunct = (c) => c !== undefined && PUNCT.test(c);
 const isWS = (c) => c === undefined || /\s/.test(c);
 // Left/right-flanking for a delimiter run, given the chars on either side.
 function flank(before, after) {

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,
@@ -611,25 +619,25 @@ export function handleLine(line, write = (s) => process.stdout.write(s)) {
 // ---------------------------------------------------------------------------
 // Entry
 // ---------------------------------------------------------------------------
-export const MCP_USAGE = `usage: geml mcp --root <dir> [--graph <dir>] [--no-history]
-
-  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0), plus the
-  read-only code-graph tools when the root holds a code graph.
-
-  --root <dir>        REQUIRED. Root directory holding the .geml documents.
-                      Relative paths resolve against the server process's CWD,
-                      which the CLIENT chooses — pass an absolute path.
-                      Every path a client names is confined to this directory;
-                      a client cannot widen or override it.
-  --graph <dir>       Code-graph directory, inside --root. Defaults to
-                      <root>/.geml-code-graph when that holds an index.geml.
-                      With no graph, the code-graph tools are not served
-                      at all (a client sees only the document tools).
-  --no-history        Do not auto-commit a .gemlhistory revision before each
-                      write. Default is to commit, so geml_revert always
-                      has a revision to undo to.
-
-  Register with a client:
+export const MCP_USAGE = `usage: geml mcp --root <dir> [--graph <dir>] [--no-history]
+
+  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0), plus the
+  read-only code-graph tools when the root holds a code graph.
+
+  --root <dir>        REQUIRED. Root directory holding the .geml documents.
+                      Relative paths resolve against the server process's CWD,
+                      which the CLIENT chooses — pass an absolute path.
+                      Every path a client names is confined to this directory;
+                      a client cannot widen or override it.
+  --graph <dir>       Code-graph directory, inside --root. Defaults to
+                      <root>/.geml-code-graph when that holds an index.geml.
+                      With no graph, the code-graph tools are not served
+                      at all (a client sees only the document tools).
+  --no-history        Do not auto-commit a .gemlhistory revision before each
+                      write. Default is to 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`;
 export function parseArgs(args) {
     let root;

package/dist/render-html.js

@@ -36,43 +36,43 @@ function page(title, body, ctx, source) {
         ? `<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 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>
+    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>
 `;
 }
 export function renderHtml(doc, opts = {}) {

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;