@geml/geml 1.5.1 → 1.7.0

package/dist/history.d.ts

@@ -27,14 +27,14 @@ interface History {
 }
 /** Reconstruct the content of revision `targetId`. */
 export declare function reconstruct(h: History, targetId: string): string;
-export interface CommitOpts {
+export interface SaveOpts {
     gemlPath: string;
     historyPath: string;
     summary: string;
     author?: string;
     at?: Date;
 }
-export declare function commit(o: CommitOpts): {
+export declare function save(o: SaveOpts): {
     id: string;
     hash: string;
 };
@@ -63,7 +63,9 @@ export interface RevisionInfo {
     current: boolean;
 }
 /** Is the working file byte-identical to the sidecar's tip revision? False
- *  means uncommitted drift (e.g. an earlier commit attempt was refused). */
+ *  means unsaved drift (e.g. an earlier save was refused by the round-trip
+ *  gate). Both write paths gate on this so a no-change `save` appends nothing:
+ *  `geml mcp` before each write (mcp.ts) and `geml history save` (geml.ts). */
 export declare function isCurrent(historyPath: string, gemlPath: string): boolean;
 /** Revisions newest-first, each tagged with the `-N` offset that selects it. */
 export declare function listRevisions(historyPath: string): RevisionInfo[];
@@ -74,11 +76,12 @@ export declare function listRevisions(historyPath: string): RevisionInfo[];
  *
  *  There is exactly one selector grammar — `0` (the tip), `-N` (N revisions
  *  back), or an unambiguous revision id (prefix, suffix, or exact) — and it is
- *  the grammar `history log` prints in its first column, so its output is
- *  copy-pasteable into `revert --rev`, `history show`, and `history restore`
- *  alike. Keeping this in one function is what makes that true: it used to be
- *  written twice, and the copy in `restore` never grew the `0`/`-N` arm, so the
- *  selectors `history log` advertised were rejected by `history show`. */
+ *  the grammar `history get` prints in its first column, so its output is
+ *  copy-pasteable into `revert --rev`, `history get <rev>`, and
+ *  `history restore` alike. Keeping this in one function is what makes that
+ *  true: it used to be written twice, and the copy in `restore` never grew the
+ *  `0`/`-N` arm, so the selectors the revision list advertised were rejected by
+ *  the command that printed a revision. */
 export declare function resolveRevision(h: History, selector: string): string;
 export declare function resolveContent(historyPath: string, selector: string): {
     id: string;

package/dist/history.js

@@ -1,9 +1,9 @@
-// GEML History extension — commit / restore / verify.
+// GEML History extension — save / restore / verify.
 //
 // Implements the `.gemlhistory` companion spec: a self-contained, reverse-delta
 // version history beside the live `.geml` file. The history file is itself a
 // GEML document (meta + keyframe + revision + blob blocks). Reverse patches and
-// hashes are tool-generated here; every commit re-applies its reverse patch and
+// hashes are tool-generated here; every save re-applies its reverse patch and
 // asserts a byte-exact round-trip before writing (the spec's verify gate).
 //
 // Revision id = `<YYYYMMDDTHHMMSSZ>-<first 8 hex of the version content hash>`.
@@ -83,7 +83,7 @@ function fenceFor(contentLf) {
 // Unit-key = `#id` (explicit), or `@<8hex content hash>` (derived), with `~n`
 // disambiguating equal keys by document-order occurrence (§4). `~n` on an #id
 // key only arises for OUT-OF-SPEC documents that repeat an id — without it the
-// key is ambiguous, reverse-patch ops hit the wrong occurrence, and commit()'s
+// key is ambiguous, reverse-patch ops hit the wrong occurrence, and save()'s
 // round-trip gate (correctly) aborts. Well-formed documents never emit it.
 const KEY = String.raw `(#[A-Za-z][A-Za-z0-9_-]*(?:~\d+)?|@[0-9a-f]+(?:~\d+)?)`;
 function sha8(s) {
@@ -267,7 +267,7 @@ function applyReverse(textLf, ops, blobs) {
  *
  * If keys were ever non-unique (no public entry point produces that — the only
  * caller, diffReverse, feeds keyedUnits output), posInB keeps b's LAST index
- * per key and the LIS still yields *a* valid monotonic matching; commit()'s
+ * per key and the LIS still yields *a* valid monotonic matching; save()'s
  * byte-exact round-trip gate rejects any diff that fails to reproduce the
  * parent regardless. */
 function lcsMatch(a, b) {
@@ -478,7 +478,7 @@ function renderHistory(h, baseName) {
     }
     return parts.join("\n");
 }
-export function commit(o) {
+export function save(o) {
     const { lf: working, nl } = loadBytes(o.gemlPath);
     const hash = fullHash(working, nl);
     const stamp = stampUTC(o.at ?? new Date());
@@ -494,10 +494,10 @@ export function commit(o) {
         const blobMap = new Map(patch.blobs.map((b) => [b.id, b.payload]));
         const back = applyReverse(working, patch.ops, blobMap);
         if (bytesOf(back, nl).compare(bytesOf(prevContent, nl)) !== 0) {
-            throw new Error("history: reverse patch does NOT round-trip to the previous revision; aborting commit");
+            throw new Error("history: reverse patch does NOT round-trip to the previous revision; aborting save");
         }
-        // Blob ids are minted per-diff (b1, b2, …). Renumber this commit's blobs to
-        // start past the highest id already stored, so a later commit never reuses
+        // Blob ids are minted per-diff (b1, b2, …). Renumber this save's blobs to
+        // start past the highest id already stored, so a later save never reuses
         // an earlier revision's blob id — an overwrite in the shared store silently
         // corrupts reconstruction of older revisions, whose `replace … <- blob:bN`
         // would then resolve to the wrong (newer) content.
@@ -597,7 +597,9 @@ export function restore(o) {
         if (existsSync(o.gemlPath)) {
             const { lf, nl } = loadBytes(o.gemlPath);
             if (fullHash(lf, nl) !== h.revisions.get(h.current).hash && !o.force) {
-                throw new Error("history: uncommitted changes in doc.geml; rerun with force to discard them, or commit first");
+                // "save first" names the live verb: this string used to say `commit`,
+                // which the four-verb collapse removed (design §2).
+                throw new Error("history: uncommitted changes in doc.geml; rerun with force to discard them, or save first");
             }
         }
         // destructive linear truncation to `target`
@@ -623,7 +625,9 @@ export function restore(o) {
     return content;
 }
 /** Is the working file byte-identical to the sidecar's tip revision? False
- *  means uncommitted drift (e.g. an earlier commit attempt was refused). */
+ *  means unsaved drift (e.g. an earlier save was refused by the round-trip
+ *  gate). Both write paths gate on this so a no-change `save` appends nothing:
+ *  `geml mcp` before each write (mcp.ts) and `geml history save` (geml.ts). */
 export function isCurrent(historyPath, gemlPath) {
     const h = parseHistory(historyPath);
     const tip = h.revisions.get(h.current);
@@ -647,11 +651,12 @@ export function listRevisions(historyPath) {
  *
  *  There is exactly one selector grammar — `0` (the tip), `-N` (N revisions
  *  back), or an unambiguous revision id (prefix, suffix, or exact) — and it is
- *  the grammar `history log` prints in its first column, so its output is
- *  copy-pasteable into `revert --rev`, `history show`, and `history restore`
- *  alike. Keeping this in one function is what makes that true: it used to be
- *  written twice, and the copy in `restore` never grew the `0`/`-N` arm, so the
- *  selectors `history log` advertised were rejected by `history show`. */
+ *  the grammar `history get` prints in its first column, so its output is
+ *  copy-pasteable into `revert --rev`, `history get <rev>`, and
+ *  `history restore` alike. Keeping this in one function is what makes that
+ *  true: it used to be written twice, and the copy in `restore` never grew the
+ *  `0`/`-N` arm, so the selectors the revision list advertised were rejected by
+ *  the command that printed a revision. */
 export function resolveRevision(h, selector) {
     const off = /^(0|-\d+)$/.exec(selector);
     if (off) {

package/dist/mcp.d.ts

@@ -22,5 +22,5 @@ export declare function allTools(): Tool[];
  */
 export declare function loadGraphTools(): Promise<Tool[]>;
 export declare function handleLine(line: string, write?: (s: string) => void): void;
-export declare const MCP_USAGE = "usage: geml mcp --root <dir> [--graph <dir>] [--no-history]\n\n  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0), plus the\n  read-only code-graph tools when the root holds a code graph.\n\n  --root <dir>        REQUIRED. Root directory holding the .geml documents.\n                      Relative paths resolve against the server process's CWD,\n                      which the CLIENT chooses \u2014 pass an absolute path.\n                      Every path a client names is confined to this directory;\n                      a client cannot widen or override it.\n  --graph <dir>       Code-graph directory, inside --root. Defaults to\n                      <root>/.geml-code-graph when that holds an index.geml.\n                      With no graph, the code-graph tools are not served\n                      at all (a client sees only the document tools).\n  --no-history        Do not auto-commit a .gemlhistory revision before each\n                      write. Default is to commit, so geml_revert always\n                      has a revision to undo to.\n\n  Register with a client:\n    claude mcp add geml -- geml mcp --root /abs/path/to/repo";
+export declare const MCP_USAGE = "usage: geml mcp --root <dir> [--graph <dir>] [--no-history]\n\n  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0), plus the\n  read-only code-graph tools when the root holds a code graph.\n\n  --root <dir>        REQUIRED. Root directory holding the .geml documents.\n                      Relative paths resolve against the server process's CWD,\n                      which the CLIENT chooses \u2014 pass an absolute path.\n                      Every path a client names is confined to this directory;\n                      a client cannot widen or override it.\n  --graph <dir>       Code-graph directory, inside --root. Defaults to\n                      <root>/.geml-code-graph when that holds an index.geml.\n                      With no graph, the code-graph tools are not served\n                      at all (a client sees only the document tools).\n  --no-history        Do not save a .gemlhistory revision before each\n                      write. Default is to save one, so geml_revert always\n                      has a revision to undo to.\n\n  Register with a client:\n    claude mcp add geml -- geml mcp --root /abs/path/to/repo";
 export declare function parseArgs(args: string[]): McpOptions;

package/dist/mcp.js

@@ -35,14 +35,14 @@
 // The mutations run through the CLI rather than re-implementing block editing:
 // the tool table is *defined* as CLI equivalences, and `-o -` already yields
 // the mutated document without touching the file — exactly the "produce, then
-// validate, then commit" order invariant 1 needs.
+// validate, then save" order invariant 1 needs.
 import { readFileSync, writeFileSync, existsSync, realpathSync, statSync } from "node:fs";
 import { resolve, dirname, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
 import { parse, PARSER_VERSION } from "./geml.js";
-import { commit, listRevisions, isCurrent } from "./history.js";
+import { save, listRevisions, isCurrent, resolveContent } from "./history.js";
 // One version for the whole package: `geml --version` and the MCP handshake
 // must not disagree. This used to be its own literal and had drifted to 0.1.0
 // against a 1.4.x package — invisible to everyone except the user reading their
@@ -200,12 +200,12 @@ function applyWrite(spec) {
     if (after === before) {
         return { ok: true, file: spec.file, diagnostics: diags, hint: "No change: the document already had this content." };
     }
-    // 3. Commit the PRE-write state so this edit is revertible, then write.
+    // 3. Save the PRE-write state so this edit is revertible, then write.
     const revision = spec.summary && OPTS.history ? snapshot(real, spec.summary) : undefined;
     writeFileSync(real, after, "utf8");
     return { ok: true, file: spec.file, diagnostics: diags, revision };
 }
-// Commit the file's CURRENT bytes as a revision, so the about-to-happen write
+// Save the file's CURRENT bytes as a revision, so the about-to-happen write
 // has something to revert to. A file already identical to its tip needs no
 // second revision.
 function snapshot(realPath, summary) {
@@ -213,7 +213,7 @@ function snapshot(realPath, summary) {
     try {
         if (existsSync(historyPath) && isCurrent(historyPath, realPath))
             return undefined;
-        return commit({ gemlPath: realPath, historyPath, summary }).id;
+        return save({ gemlPath: realPath, historyPath, summary }).id;
     }
     catch {
         // A sidecar that cannot be written must not cost the caller their edit;
@@ -243,12 +243,27 @@ function docResolver(root, fromFile) {
     };
 }
 const hashId = (id) => (id.startsWith("#") ? id : `#${id}`);
+// `geml get`/`geml set` take a full block SELECTOR, not only an id: a content
+// address reaches a block the author never named, which is the whole point of
+// `geml_list` now reporting one for those. So a value that is ALREADY a
+// selector must pass through untouched — hashId would turn `@a3f9c1d2` into
+// `#@a3f9c1d2` and address nothing. A bare word is still an id, so the
+// long-standing "id with or without #" contract is unchanged.
+//
+// The parameter is still NAMED `id`: renaming it to `selector` would break
+// every registered client for a cosmetic gain, and both design docs park that
+// rename as a follow-up. The other verbs keep hashId — their CLI counterparts
+// (add/delete/rename/revert) take ids only, so accepting a selector here would
+// promise something the CLI would then refuse.
+// A selector starts with `#` (id or heading line), `@` (content address), or a
+// `=` fence run (type filter). Anything else is a bare id.
+const selectorArg = (s) => (/^([#@]|={3,})/.test(s.trim()) ? s.trim() : `#${s}`);
 const FILE_ARG = { type: "string", description: "Document path relative to the server's --root directory, e.g. notes/spec.geml" };
 export const TOOLS = [
     // ----- read -----
     {
         name: "geml_list",
-        description: "List every addressable block in a GEML document: its `#id`, kind, and heading text. Call this FIRST — the ids it returns are what every other tool in this server addresses. Cheaper and more reliable than reading the file to find out what is in it.",
+        description: "List every addressable block in a GEML document: its address, kind, and heading text. Call this FIRST — the `id` values it returns are what every other tool in this server addresses. Cheaper and more reliable than reading the file to find out what is in it. Rows marked `anon` have no `#id` (their `address` is a type or content address the CLI understands); this server's other tools take an `id`, so give such a block an id before addressing it here.",
         inputSchema: { type: "object", properties: { file: FILE_ARG }, required: ["file"] },
         run: (args) => {
             const real = resolveInRoot(args.file);
@@ -260,21 +275,46 @@ export const TOOLS = [
     },
     {
         name: "geml_get",
-        description: "Read ONE block from a GEML document by its `#id`. Use this instead of reading the whole file: it returns only that block, typically a few percent of the document. Get available ids from `geml_list` first. Reading the whole file to change one block wastes context and risks modifying unrelated content.",
+        description: "Read ONE block from a GEML document. Use this instead of reading the whole file: it returns only that block, typically a few percent of the document. Call `geml_list` first and pass back the `address` it gives — that also reaches blocks with no `#id`, which an id alone cannot.",
         inputSchema: {
             type: "object",
             properties: {
                 file: FILE_ARG,
-                id: { type: "string", description: "Block id, with or without the leading `#`" },
+                id: {
+                    type: "string",
+                    description: "What to read: a block id (with or without `#`), a `## Heading` line (its whole section), `=== type` for every block of a type, or a `@<hex>` content address for a block with no id — the forms `geml_list` prints",
+                },
+                view: {
+                    type: "boolean",
+                    description: "Read THROUGH an `embed` block to the entity block it stands for, following a multi-layer chain to its end. An `embed` has no content of its own, so this is the only way to see what it points at; on any other block it changes nothing. Returns {from, content}: `from` names the document the content actually came from, and its references and relative paths resolve against THAT document, not this one.",
+                },
+                part: {
+                    type: "string",
+                    enum: ["whole", "head", "body"],
+                    description: "How much of the block to return (default: whole). `body` is usually what you want together with `view`.",
+                },
             },
             required: ["file", "id"],
         },
         run: (args) => {
             const real = resolveInRoot(args.file);
-            const run = runCli(["get", real, hashId(args.id)]);
+            const sel = selectorArg(args.id);
+            // Same name, same enum, same validation as `geml_set` — one concept for a
+            // model to learn, and `body` is already taken there for the replacement text.
+            const part = args.part ?? "whole";
+            if (!["whole", "head", "body"].includes(part))
+                throw new Error(`part must be whole|head|body, got \`${part}\``);
+            const flag = part === "head" ? ["--head"] : part === "body" ? ["--body"] : [];
+            const run = runCli(["get", real, sel, ...flag, ...(args.view ? ["--view"] : [])]);
             if (!run.ok)
-                throw new Error(run.stderr || `no block with id ${hashId(args.id)}`);
-            return run.stdout;
+                throw new Error(run.stderr || `nothing matches ${sel}`);
+            if (!args.view)
+                return run.stdout;
+            // There is no stderr across an MCP call, and provenance is mandatory: lift
+            // it out of the CLI's pinned `view: <sel> -> <doc>[#<id>]` line into a
+            // field of its own.
+            const m = /^view: .*? -> (.+)$/m.exec(run.stderr);
+            return { from: m ? m[1].trim() : null, content: run.stdout };
         },
     },
     {
@@ -304,14 +344,41 @@ export const TOOLS = [
     },
     {
         name: "geml_history",
-        description: "List the recorded revisions of a document, newest first. Each entry's `offset` is the selector `geml_revert` takes as `rev` (-1 is the revision before the current one). Use this to find WHICH revision to revert a block to; an empty list means the document has no sidecar yet and nothing can be reverted.",
-        inputSchema: { type: "object", properties: { file: FILE_ARG }, required: ["file"] },
+        // The name mirrors the CLI COMMAND PATH (`geml history`), not a verb: this
+        // group's only read verb is `get`, and it is the only one that belongs on a
+        // server an agent drives (`save` would insert hand-made revisions between
+        // the automatic pre-write ones, and `restore` rewrites a whole file where
+        // the agent already has block-level geml_revert). So there will be no second
+        // history tool to disambiguate from, and `_get` would be a suffix that
+        // distinguishes nothing — design §5.
+        description: "Read a document's recorded history. WITHOUT `rev`: list every revision, newest first — each entry's `offset` is the selector `geml_revert` takes as `rev` (-1 is the revision before the current one), and an empty list means the document has no sidecar yet and nothing can be reverted. WITH `rev`: the full text of that one revision, for reading what the document looked like then without restoring it.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file: FILE_ARG,
+                rev: { type: "string", description: "Revision selector — `0` for the current tip, `-N` for N revisions back, or a revision id from the list. Omit it to get the list instead of one revision's text." },
+            },
+            required: ["file"],
+        },
         run: (args) => {
             const real = resolveInRoot(args.file);
             const historyPath = real.replace(/\.geml$/, "") + ".gemlhistory";
-            if (!existsSync(historyPath))
+            const rev = args.rev === undefined ? undefined : String(args.rev);
+            if (!existsSync(historyPath)) {
+                // Naming a revision of a document that has no history at all is an
+                // error, not an empty result: the caller asked for specific content.
+                // The LIST tier stays a plain empty answer — "nothing yet" is a real,
+                // useful state there.
+                if (rev !== undefined)
+                    throw new Error(`no .gemlhistory sidecar for ${args.file} yet, so revision ${rev} does not exist — the first write through this server creates one`);
                 return { file: args.file, revisions: [], note: "no .gemlhistory sidecar yet — the first write through this server creates one" };
-            return { file: args.file, revisions: listRevisions(historyPath) };
+            }
+            if (rev === undefined)
+                return { file: args.file, revisions: listRevisions(historyPath) };
+            // resolveContent() is the CLI's own path for `geml history get <file>
+            // <rev>`, so one selector grammar answers on both surfaces.
+            const { id, text } = resolveContent(historyPath, rev);
+            return { file: args.file, id, text };
         },
     },
     {
@@ -362,12 +429,15 @@ export const TOOLS = [
     // ----- write -----
     {
         name: "geml_set",
-        description: "Replace ONE block, addressed by `#id`, leaving every other byte of the document untouched. Prefer this over rewriting a file. The replacement is VALIDATED BEFORE it is written: if it would break the document, nothing is written and you get the diagnostics back — re-read them and fix the body rather than retrying the same content. `part` selects whole block (default), just the head/fence line, or just the body.",
+        description: "Replace ONE block, leaving every other byte of the document untouched. Prefer this over rewriting a file. The replacement is VALIDATED BEFORE it is written: if it would break the document, nothing is written and you get the diagnostics back — re-read them and fix the body rather than retrying the same content. `part` selects whole block (default), just the head/fence line, or just the body. An address matching SEVERAL blocks is refused — this writes one block, so narrow it first.",
         inputSchema: {
             type: "object",
             properties: {
                 file: FILE_ARG,
-                id: { type: "string", description: "Block id to replace, with or without `#`" },
+                id: {
+                    type: "string",
+                    description: "Which block to replace: an id (with or without `#`), or a `@<hex>` content address from `geml_list` for a block with no id. Must match exactly one block",
+                },
                 body: { type: "string", description: "The replacement text" },
                 part: { type: "string", enum: ["whole", "head", "body"], description: "What to replace (default: whole)" },
             },
@@ -381,9 +451,9 @@ export const TOOLS = [
             const flag = part === "head" ? ["--head"] : part === "body" ? ["--body"] : [];
             return applyWrite({
                 file: args.file,
-                cliArgs: ["set", real, hashId(args.id), ...flag, "--in", "-", "-o", "-"],
+                cliArgs: ["set", real, selectorArg(args.id), ...flag, "--in", "-", "-o", "-"],
                 input: args.body,
-                summary: `mcp: before write to ${hashId(args.id)}`,
+                summary: `mcp: before write to ${selectorArg(args.id)}`,
             });
         },
     },
@@ -619,25 +689,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 save a .gemlhistory revision before each
+                      write. Default is to save one, 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.d.ts

@@ -1,3 +1,8 @@
 import { type Document } from "./geml.js";
 import { type RenderOptions } from "./render.js";
 export declare function renderHtml(doc: Document, opts?: RenderOptions): string;
+export declare const pageAssets: {
+    readonly css: "\n:root { --fg:#1f2328; --muted:#656d76; --bd:#d0d7de; --bg:#fff; --accent:#2563eb; --code-bg:#f6f8fa; }\n* { box-sizing: border-box; }\nbody { margin:0; color:var(--fg); background:#fafbfc; font:16px/1.6 -apple-system,BlinkMacSystemFont,\"Segoe UI\",Helvetica,Arial,\"PingFang SC\",\"Microsoft Yahei\",sans-serif; }\nmain { max-width: 860px; margin: 0 auto; padding: 48px 24px 96px; background:var(--bg); }\nh1,h2,h3,h4,h5,h6 { line-height:1.25; margin:1.6em 0 .6em; scroll-margin-top:16px; }\nh1 { font-size:2em; border-bottom:1px solid var(--bd); padding-bottom:.3em; }\nh2 { font-size:1.5em; border-bottom:1px solid var(--bd); padding-bottom:.3em; }\nh3 { font-size:1.25em; } h4 { font-size:1em; }\np { margin:.7em 0; }\na { color:var(--accent); text-decoration:none; } a:hover { text-decoration:underline; }\ncode { background:var(--code-bg); padding:.15em .35em; border-radius:6px; font:.88em ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }\npre { background:var(--code-bg); padding:14px 16px; border-radius:8px; overflow:auto; }\npre code { background:none; padding:0; font-size:.85em; }\npre.output { background:#0d1117; color:#e6edf3; }\npre.output code { color:inherit; }\nul,ol { padding-left:1.6em; } li { margin:.2em 0; }\nul.task-list { list-style:none; padding-left:.2em; }\nli.task input[type=checkbox] { appearance:none; -webkit-appearance:none; width:1.1em; height:1.1em; margin:0 .5em 0 0; vertical-align:-.2em; border:1.5px solid #c8ccd0; border-radius:4px; background:#fff; position:relative; opacity:1; cursor:default; box-sizing:border-box; }\nli.task input[type=checkbox]:checked { background-color:#1f883d; border-color:#1f883d; }\nli.task input[type=checkbox]:checked::after { content:\"✓\"; position:absolute; top:0; right:0; bottom:0; left:0; display:flex; align-items:center; justify-content:center; color:#fff; font-size:.8em; line-height:1; font-weight:700; }\naside.callout { border-left:4px solid var(--accent); background:#f0f6ff; padding:.4em 16px; border-radius:0 8px 8px 0; margin:1em 0; }\naside.aside { border-left-color:#8b949e; background:#f6f8fa; }\naside.warning { border-left-color:#d97706; background:#fff8f0; }\naside.callout > :first-child { margin-top:0; } aside.callout > :last-child { margin-bottom:0; }\nfigure { margin:1.2em 0; }\nfigcaption { color:var(--muted); font-size:.86em; text-align:center; margin-top:.5em; }\ntable.geml-table { border-collapse:collapse; width:100%; font-size:.92em; }\ntable.geml-table th, table.geml-table td { border:1px solid var(--bd); padding:6px 12px; }\ntable.geml-table thead th { background:var(--code-bg); cursor:pointer; user-select:none; white-space:nowrap; }\ntable.geml-table thead th::after { content:\" \\2195\"; color:var(--muted); font-size:.8em; }\ntable.geml-table thead th.asc::after { content:\" \\2191\"; color:var(--accent); }\ntable.geml-table thead th.desc::after { content:\" \\2193\"; color:var(--accent); }\ntable.geml-table tbody tr:nth-child(2n) { background:#fafbfc; }\ntable.geml-table td.computed { color:#0a7c52; }\ntable.geml-table tfoot td { background:var(--code-bg); font-weight:600; border-top:2px solid var(--bd); }\n.table-tools { margin-bottom:6px; } .table-filter { width:240px; max-width:100%; padding:5px 9px; border:1px solid var(--bd); border-radius:7px; font-size:.85em; }\n.table-figure details > summary { cursor:pointer; color:var(--muted); font-size:.86em; padding:4px 0; }\n.table-note { color:var(--muted); font-size:.82em; margin:6px 0 0; }\n.geml-chart { width:100%; height:auto; background:var(--bg); border:1px solid var(--bd); border-radius:8px; }\n.c-title { font-size:15px; font-weight:600; fill:var(--fg); }\n.c-grid { stroke:#eaecef; } .c-axis { stroke:#aab1b8; } .c-tick { font-size:11px; fill:var(--muted); } .c-legend { font-size:12px; fill:var(--fg); }\n.media { max-width:100%; border-radius:8px; }\n.diagram-src { color:var(--muted); } .render-error { color:#cf222e; }\n.math-block { overflow-x:auto; padding:.4em 0; }\nsup.fn a { font-size:.75em; }\n.geml-footer { max-width:860px; margin:0 auto; padding:16px 24px 40px; color:var(--muted); font-size:.82em; }\n.geml-footer code { font-size:.95em; }\n.code-graph { margin:1.4em 0; }\n.cg-mount { border:1px solid var(--bd); border-radius:8px; padding:10px 12px; background:var(--bg); }\n.cg-scroll { overflow:auto; min-height:52vh; max-height:72vh; }\n.cg-svg { display:block; }\n.cg-search-wrap { position:relative; display:inline-block; }\n.cg-search { font:12px/1.4 inherit; padding:2px 7px; border:1px solid var(--bd); border-radius:4px; background:var(--bg); color:var(--fg); min-width:13ch; }\n.cg-search-menu { position:absolute; z-index:30; top:calc(100% + 2px); left:0; min-width:24ch; max-width:52ch; max-height:52vh; overflow:auto; background:var(--bg); border:1px solid var(--bd); border-radius:6px; box-shadow:0 6px 20px rgba(0,0,0,.18); }\n.cg-search-row { display:block; width:100%; text-align:left; padding:4px 9px 4px 18px; border:0; background:none; color:var(--fg); cursor:pointer; font:12px/1.4 inherit; }\n.cg-search-row:hover { background:var(--bd); }\n.cg-search-count { position:sticky; top:0; padding:4px 9px; font-size:11px; opacity:.65; background:var(--bg); border-bottom:1px solid var(--bd); }\n.cg-search-grp { padding:6px 9px 2px; font-size:11px; font-weight:600; opacity:.7; border-top:1px solid var(--bd); }\n.cg-search-grp:first-of-type { border-top:0; }\n.cg-stage { display:flex; gap:10px; align-items:flex-start; }\n.cg-stage .cg-scroll { flex:1 1 auto; min-width:0; }\n.cg-src { flex:0 0 42%; max-width:46%; display:flex; flex-direction:column; border:1px solid var(--bd); border-radius:6px; overflow:hidden; background:var(--bg); }\n.cg-src-hd { display:flex; gap:8px; align-items:center; justify-content:space-between; padding:4px 8px; border-bottom:1px solid var(--bd); color:var(--muted); font:.76em ui-monospace,Consolas,monospace; word-break:break-all; }\n.cg-src-hd button { font:inherit; border:1px solid var(--bd); border-radius:5px; background:transparent; color:var(--muted); cursor:pointer; padding:0 6px; }\n.cg-src-body { margin:0; padding:8px 10px; overflow:auto; max-height:72vh; color:var(--fg); font:12px/1.5 ui-monospace,Consolas,monospace; white-space:pre; }\n.cg-src-note { color:var(--muted); font-style:italic; white-space:pre-wrap; }\n.cg-bar { display:flex; gap:8px; align-items:center; flex-wrap:wrap; font-size:.82em; color:var(--muted); margin-bottom:6px; }\n.cg-bar button { font:inherit; padding:1px 8px; border:1px solid var(--bd); border-radius:5px; background:transparent; cursor:pointer; }\n.cg-crumb .cg-seg { border:0; border-radius:0; padding:0; background:none; color:var(--accent); cursor:pointer; font:inherit; }\n.cg-crumb .cg-seg:hover { text-decoration:underline; }\n.cg-frame { display:block; width:100%; height:72vh; border:0; background:var(--bg); }\n.cg-flash { color:#b42318; }\n.cg-legend { display:flex; gap:14px; align-items:center; justify-content:space-between; flex-wrap:wrap; font-size:.75em; color:var(--muted); margin-top:6px; }\n.cg-upbtn { cursor:pointer; }\n.cg-upbtn circle { fill:#fff; stroke:#94a3b8; }\n.cg-upbtn text { font-size:11px; fill:#57606a; }\n.cg-upbtn:hover circle { stroke:var(--accent); stroke-width:1.6; }\n.cg-upbtn:hover text { fill:var(--accent); }\n.cg-uplink { fill:none; stroke:#94a3b8; stroke-dasharray:3 2.5; pointer-events:none; }\n.cg-groups { display:flex; flex-wrap:wrap; gap:4px 12px; margin-top:6px; font-size:.75em; color:var(--muted); }\n.cg-chip { display:inline-flex; align-items:center; gap:4px; }\n.cg-chip i { width:10px; height:10px; border-radius:2px; border:1px solid #94a3b8; display:inline-block; }\n.cg-note { font-size:.8em; color:#9a6700; }\n.cg-n rect { fill:#eef2f7; stroke:#94a3b8; }\n.cg-n text { font-size:12px; fill:var(--fg); font-family:ui-monospace,Consolas,monospace; }\n.cg-n { cursor:pointer; }\n.cg-n.root rect { fill:#dbeafe; stroke:#2563eb; stroke-width:2; }\n.cg-n.leaf { opacity:.45; }\n.cg-n.test rect { stroke-dasharray:3 2; }\n.cg-n.grp rect { stroke-width:1.8; }\n.cg-e { fill:none; stroke:#94a3b8; stroke-width:.9; }\n.cg-e.cand { stroke-dasharray:2 3; }\n.cg-e.back { stroke:#dc2626; stroke-dasharray:5 3; }\n.cg-e.http { stroke:#0891b2; stroke-width:1.5; stroke-dasharray:5 2; } /* cross-stack API link */\n.cg-e.soft { opacity:.55; }\n.cg-svg.hl .cg-n { opacity:.22; }\n.cg-svg.hl .cg-e { opacity:.1; }\n.cg-svg.hl .cg-n.hl { opacity:1; }\n.cg-svg.hl .cg-e.hl { opacity:1; stroke-width:1.6; }\n";
+    readonly js: "\n(function () {\n  function cmp(a, b) {\n    var na = a.dataset.sort, nb = b.dataset.sort;\n    if (na !== undefined && nb !== undefined) return parseFloat(na) - parseFloat(nb);\n    return (a.textContent || \"\").localeCompare(b.textContent || \"\");\n  }\n  document.querySelectorAll(\"table.geml-table\").forEach(function (table) {\n    var tbody = table.tBodies[0];\n    if (!tbody) return;\n    // Sort on header click.\n    var ths = table.tHead ? table.tHead.rows[0].cells : [];\n    Array.prototype.forEach.call(ths, function (th, col) {\n      th.addEventListener(\"click\", function () {\n        var dir = th.classList.contains(\"asc\") ? \"desc\" : \"asc\";\n        Array.prototype.forEach.call(ths, function (h) { h.classList.remove(\"asc\", \"desc\"); });\n        th.classList.add(dir);\n        var rows = Array.prototype.slice.call(tbody.rows);\n        rows.sort(function (r1, r2) {\n          var c = cmp(r1.cells[col], r2.cells[col]);\n          return dir === \"asc\" ? c : -c;\n        });\n        rows.forEach(function (r) { tbody.appendChild(r); });\n      });\n    });\n    // Filter rows.\n    var fig = table.closest(\".table-figure\");\n    var input = fig ? fig.querySelector(\".table-filter\") : null;\n    if (input) input.addEventListener(\"input\", function () {\n      var q = input.value.toLowerCase();\n      Array.prototype.forEach.call(tbody.rows, function (r) {\n        r.style.display = (r.textContent || \"\").toLowerCase().indexOf(q) >= 0 ? \"\" : \"none\";\n      });\n    });\n  });\n})();\n";
+    readonly codeGraphJs: string;
+};

package/dist/render-html.js

@@ -33,46 +33,46 @@ function page(title, body, ctx, source) {
     const wantLive = ctx.usedCodeGraph && !!ctx.opts.liveGraph;
     const lg = wantLive ? escAttr(ctx.opts.liveGraph) : "";
     const importMap = wantLive
-        ? `<script type="importmap">{"imports":{"node:fs":"${lg}_node-stub.js","node:path":"${lg}_node-stub.js","node:crypto":"${lg}_node-stub.js","node:url":"${lg}_node-stub.js","node:child_process":"${lg}_node-stub.js"}}</script>\n`
+        ? `<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","node:os":"${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 = {}) {
@@ -90,6 +90,15 @@ export function renderHtml(doc, opts = {}) {
             : `layered method flow — roots: in-degree-zero methods (no <code>entry</code> declared)`;
         body = ctx.codeGraphFigure(opts.source, "", `<figcaption>${cap}</figcaption>`) + "\n" + body;
     }
+    // Fragment mode: the body markup alone, for embedding into an existing
+    // layout. No shell, no CDN tags, no inline CSS/JS — see RenderOptions.
+    if (opts.fragment)
+        return body + "\n";
     const title = opts.title ?? ctx.docTitle() ?? "GEML document";
     return page(title, body, ctx, opts.source);
 }
+// The page shell's static assets, for fragment consumers: `css` styles every
+// geml-* class a fragment emits (include once per site); `js` is the tables'
+// sort/filter enhancement (once per page); `codeGraphJs` matters only when a
+// fragment carries a code-graph mount. The full-page output inlines all three.
+export const pageAssets = { css: CSS, js: JS, codeGraphJs: CODE_GRAPH_JS };

package/dist/render.d.ts

@@ -8,6 +8,7 @@ export interface RenderOptions {
     tableRows?: number;
     liveGraph?: string;
     graphSidecar?: string;
+    fragment?: boolean;
 }
 export declare function esc(s: string): string;
 export declare function escAttr(s: string): string;