@geml/geml 1.5.0 → 1.6.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/inline.js

@@ -315,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.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,20 +275,24 @@ 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",
+                },
             },
             required: ["file", "id"],
         },
         run: (args) => {
             const real = resolveInRoot(args.file);
-            const run = runCli(["get", real, hashId(args.id)]);
+            const sel = selectorArg(args.id);
+            const run = runCli(["get", real, sel]);
             if (!run.ok)
-                throw new Error(run.stderr || `no block with id ${hashId(args.id)}`);
+                throw new Error(run.stderr || `nothing matches ${sel}`);
             return run.stdout;
         },
     },
@@ -304,14 +323,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 +408,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 +430,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)}`,
             });
         },
     },
@@ -633,8 +682,8 @@ export const MCP_USAGE = `usage: geml mcp --root <dir> [--graph <dir>] [--no-his
                       <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
+  --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:

package/dist/render.js

@@ -611,35 +611,14 @@ export class RenderCtx {
         const maxRows = this.isCodemapDoc && id === "modules" ? Infinity : (this.opts.tableRows ?? 500);
         const allRows = t.rows;
         const rows = allRows.length > maxRows ? allRows.slice(0, maxRows) : allRows;
-        // Coverage grid for declared spans, so cells a span covers are not emitted.
-        const covered = rows.map((r) => r.map(() => false));
-        rows.forEach((row, r) => row.forEach((cell, c) => {
-            if (!cell.span)
-                return;
-            // Bound the sweep to the rendered grid regardless of the declared span, so
-            // an oversized span can never drive an O(hugerows×hugecols) loop (DoS).
-            const spanRows = Math.min(cell.span.rows, rows.length - r);
-            const spanCols = Math.min(cell.span.cols, row.length - c);
-            for (let dr = 0; dr < spanRows; dr++)
-                for (let dc = 0; dc < spanCols; dc++) {
-                    if (dr === 0 && dc === 0)
-                        continue;
-                    const rr = r + dr, cc = c + dc;
-                    if (covered[rr]?.[cc] !== undefined)
-                        covered[rr][cc] = true;
-                }
-        }));
         const thead = t.header
             ? `<thead><tr>${t.columns.map((col, c) => `<th${alignStyle(t.align[c])}>${esc(col)}</th>`).join("")}</tr></thead>`
             : "";
         const bodyRows = rows.map((row, r) => {
             const cells = row.map((cell, c) => {
-                if (covered[r]?.[c])
-                    return "";
-                const span = cell.span ? `${cell.span.rows > 1 ? ` rowspan="${cell.span.rows}"` : ""}${cell.span.cols > 1 ? ` colspan="${cell.span.cols}"` : ""}` : "";
                 const cls = cell.computed ? ' class="computed"' : "";
                 const sortVal = typeof cell.value === "number" ? ` data-sort="${cell.value}"` : "";
-                return `<td${alignStyle(cell.align ?? t.align[c])}${span}${cls}${sortVal}>${this.inlines(cell.inlines)}</td>`;
+                return `<td${alignStyle(cell.align ?? t.align[c])}${cls}${sortVal}>${this.inlines(cell.inlines)}</td>`;
             }).join("");
             return `<tr>${cells}</tr>`;
         }).join("\n");

package/dist/selector.d.ts

@@ -0,0 +1,55 @@
+export interface Span {
+    start: number;
+    end: number;
+}
+export interface Unit {
+    span: Span;
+    kind: "block" | "heading" | "footnote";
+    type?: string;
+    id?: string;
+    level?: number;
+    text?: string;
+}
+export type Selector = {
+    form: "list";
+} | {
+    form: "id";
+    raw: string;
+} | {
+    form: "type";
+    type: string;
+} | {
+    form: "content";
+    type?: string;
+    hex: string;
+    nth: number;
+} | {
+    form: "attr";
+    type: string;
+    key: string;
+};
+export declare function sha8(text: string): string;
+export declare function parseSelector(raw: string | undefined, attrsIdOf: (braces: string) => string | undefined): Selector;
+export interface Addressed {
+    unit: Unit;
+    hex: string;
+    nth: number;
+}
+export declare function addressUnits(units: Unit[], textOf: (u: Unit) => string): Addressed[];
+export declare function shortestAddress(a: Addressed, all: Addressed[]): string;
+export type ContentHit = {
+    ok: true;
+    unit: Unit;
+} | {
+    ok: false;
+    why: "no-match";
+} | {
+    ok: false;
+    why: "wrong-type";
+    found: string;
+};
+export declare function matchContent(sel: Extract<Selector, {
+    form: "content";
+}>, all: Addressed[]): ContentHit;
+export declare function discoveryHint(where: string): string;
+export declare function matchType(type: string, all: Addressed[]): Unit[];

package/dist/selector.js

@@ -0,0 +1,112 @@
+// Block selectors — the one syntax `get`, `set` and `history get` all address
+// blocks with (design: docs/design/specs/2026-08-04-geml-get-set-selector-design-change.md).
+//
+// §2's rule: a selector is a FILTER over blocks, `{…}` holds keys, and the same
+// abbreviation rule applies twice — `#id` is `{#id}` short, `@<hex>` is
+// `{@<hex>}` short. Both are keys; they differ only in selectivity.
+//
+// This module is PURE: it parses selector text and matches it against a unit
+// index the caller supplies. It deliberately imports nothing from geml.ts —
+// that module runs the CLI dispatch on import, so depending on it here would
+// turn `import { parseSelector }` into "run the CLI". The scan that produces
+// `Unit[]` therefore stays in geml.ts (one walk, several sinks) and the
+// selector logic stays here, where it can be unit-tested on plain data.
+import { createHash } from "node:crypto";
+// The content address's hash. Same spelling as the `.gemlhistory` unit key
+// (history.ts:112) because both answer the same question — how to address a
+// unit that carries no id. The VALUES are deliberately not promised to match:
+// history hashes a tile (trailing blank lines included), this hashes a block's
+// span (§3.3). Do not port an address from one layer to the other.
+export function sha8(text) {
+    return createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex").slice(0, 8);
+}
+const FENCE_SEL = /^={3,}[ \t]*([A-Za-z][A-Za-z0-9_-]*)[ \t]*(@[0-9a-fA-F]{1,}(?:~\d+)?)?[ \t]*(\{.*\})?[ \t]*$/;
+const BARE_AT = /^@([0-9a-fA-F]+)(?:~(\d+))?$/;
+// Parse selector TEXT. Never touches a document: every form is decided by
+// lexis alone, which is also what keeps the two selector namespaces on
+// `history get <file> <rev> <selector>` from overlapping (history design §10.2).
+// `attrsIdOf` lets the caller reuse its own `{…}` parser (parseAttrs) rather
+// than this module growing a second one.
+export function parseSelector(raw, attrsIdOf) {
+    if (raw === undefined || raw.trim() === "")
+        return { form: "list" };
+    const s = raw.trim();
+    const bare = BARE_AT.exec(s);
+    if (bare)
+        return { form: "content", hex: bare[1].toLowerCase(), nth: bare[2] ? Number(bare[2]) : 0 };
+    const fence = FENCE_SEL.exec(s);
+    if (fence) {
+        const type = fence[1];
+        const at = fence[2];
+        const braces = fence[3];
+        if (braces !== undefined) {
+            // `=== type {#id}` is the id key written out in full — redundant but
+            // legal (§2). Any OTHER key is the declared-not-implemented form.
+            const id = attrsIdOf(braces);
+            if (id !== undefined)
+                return { form: "id", raw: `#${id}` };
+            return { form: "attr", type, key: firstKey(braces) };
+        }
+        if (at !== undefined) {
+            const m = BARE_AT.exec(at);
+            return { form: "content", type, hex: m[1].toLowerCase(), nth: m[2] ? Number(m[2]) : 0 };
+        }
+        return { form: "type", type };
+    }
+    // Anything else is an id or a pasted heading line; the caller resolves it.
+    return { form: "id", raw: s };
+}
+// The first key inside `{…}`, for the §7 error message. Best-effort: it only
+// has to name what the caller typed, and a class (`.warn`) is reported as
+// written so the message does not claim a key that is not there.
+function firstKey(braces) {
+    const inner = braces.replace(/^\{/, "").replace(/\}$/, "").trim();
+    const m = /^([.#]?[A-Za-z_][A-Za-z0-9_-]*)/.exec(inner);
+    return m ? m[1] : inner.split(/[\s=]/)[0] ?? "";
+}
+export function addressUnits(units, textOf) {
+    const seen = new Map();
+    return units.map((unit) => {
+        // LF-normalized so a CRLF checkout and an LF one address the same block.
+        const hex = sha8(textOf(unit).replace(/\r\n?/g, "\n"));
+        const nth = seen.get(hex) ?? 0;
+        seen.set(hex, nth + 1);
+        return { unit, hex, nth };
+    });
+}
+// §6.1 — the SHORTEST address that identifies this unit uniquely, which is what
+// the listing prints. `#id` when it has one; else the bare type when the
+// document holds exactly one block of it; else the content address. The three
+// cases are one rule ("shortest unique"), not three rules.
+export function shortestAddress(a, all) {
+    const u = a.unit;
+    if (u.id !== undefined)
+        return `#${u.id}`;
+    if (u.type === undefined)
+        return `@${a.hex}${a.nth ? `~${a.nth}` : ""}`;
+    const sameType = all.filter((x) => x.unit.type === u.type).length;
+    if (sameType === 1)
+        return `=== ${u.type}`;
+    return `=== ${u.type}@${a.hex}${a.nth ? `~${a.nth}` : ""}`;
+}
+export function matchContent(sel, all) {
+    const hit = all.find((a) => a.hex === sel.hex && a.nth === sel.nth);
+    if (!hit)
+        return { ok: false, why: "no-match" };
+    if (sel.type !== undefined && hit.unit.type !== sel.type) {
+        return { ok: false, why: "wrong-type", found: hit.unit.type ?? hit.unit.kind };
+    }
+    return { ok: true, unit: hit.unit };
+}
+// Where to send a caller whose selector found nothing: the listing IS the
+// discovery command, and every address it prints pastes straight back (§6.2).
+// One place, so `get`, `set` and `history get` all point at the same next step.
+export function discoveryHint(where) {
+    return ` — run \`geml get ${where}\` to list every addressable block`;
+}
+// Match a type filter: every block of that type in document order. Blocks that
+// carry an id are INCLUDED — the selector says nothing about ids, so filtering
+// by whether one is present would be a rule nobody wrote down (§2).
+export function matchType(type, all) {
+    return all.filter((a) => a.unit.type === type).map((a) => a.unit);
+}

package/dist/table.d.ts

@@ -8,10 +8,6 @@ export interface TableCell {
     align?: Align;
     value?: number;
     computed?: boolean;
-    span?: {
-        rows: number;
-        cols: number;
-    };
 }
 export interface TableModel {
     caption?: string;