@design-twin/dtwin 0.0.0-stage → 0.1.0

package/layer/map-validate.js

@@ -0,0 +1,397 @@
+// GENERATED from design-to-code/ by claude-plugin/build-scripts.js — edit the source, then rebuild.
+
+
+// design-to-code/cli-args.ts
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// bridge/src/errmsg.ts
+var errMsg = (e) => typeof e === "string" ? e : String(e && e.message || e);
+
+// bridge/src/stdio.ts
+import { format, inspect } from "node:util";
+function installQueuedConsole(o = {}) {
+  trackWrites(process.stdout);
+  trackWrites(process.stderr);
+  const out = o.logTo === "stderr" ? process.stderr : process.stdout;
+  const err = process.stderr;
+  let indent = "";
+  const write = (s, text) => {
+    s.write((indent ? text.replace(/^/gm, indent) : text) + "\n");
+  };
+  const line = (s) => (...a) => {
+    write(s, format(...a));
+  };
+  console.log = console.info = console.debug = line(out);
+  console.warn = console.error = line(err);
+  console.dir = (item, options) => {
+    write(out, inspect(item, { customInspect: false, ...options }));
+  };
+  console.dirxml = line(out);
+  console.table = (data) => {
+    write(out, inspect(data));
+  };
+  console.write = (...data) => {
+    let n = 0;
+    for (const d of data) {
+      const b = typeof d === "string" ? Buffer.from(d) : d instanceof ArrayBuffer ? Buffer.from(d) : Buffer.from(d.buffer, d.byteOffset, d.byteLength);
+      if (b.length) {
+        out.write(b);
+        n += b.length;
+      }
+    }
+    return n;
+  };
+  console.clear = () => {
+    if (out.isTTY) out.write("\x1B[1;1H\x1B[0J");
+  };
+  console.trace = (...a) => {
+    const e = new Error(format(...a));
+    e.name = "Trace";
+    Error.captureStackTrace(e, console.trace);
+    write(err, e.stack ?? `Trace: ${e.message}`);
+  };
+  console.assert = (cond, ...a) => {
+    if (!cond) write(err, a.length ? "Assertion failed: " + format(...a) : "Assertion failed");
+  };
+  console.group = console.groupCollapsed = (...a) => {
+    if (a.length) write(out, format(...a));
+    indent += "  ";
+  };
+  console.groupEnd = () => {
+    indent = indent.slice(0, -2);
+  };
+  const counts = /* @__PURE__ */ new Map();
+  console.count = (label = "default") => {
+    const n = (counts.get(label) ?? 0) + 1;
+    counts.set(label, n);
+    write(out, `${label}: ${n}`);
+  };
+  console.countReset = (label = "default") => {
+    counts.delete(label);
+  };
+  const timers = /* @__PURE__ */ new Map();
+  const elapsed = (label) => {
+    const t = timers.get(label);
+    return t === void 0 ? null : `${label}: ${(performance.now() - t).toFixed(3)}ms`;
+  };
+  console.time = (label = "default") => {
+    timers.set(label, performance.now());
+  };
+  console.timeLog = (label = "default", ...a) => {
+    const e = elapsed(label);
+    if (e === null) write(err, `Warning: No such label '${label}' for console.timeLog()`);
+    else write(out, [e, ...a.map((x) => format(x))].join(" "));
+  };
+  console.timeEnd = (label = "default") => {
+    const e = elapsed(label);
+    timers.delete(label);
+    write(e === null ? err : out, e ?? `Warning: No such label '${label}' for console.timeEnd()`);
+  };
+}
+var inFlight = /* @__PURE__ */ new Map();
+function trackWrites(s) {
+  if (inFlight.has(s)) return;
+  const st = { n: 0, idle: [] };
+  inFlight.set(s, st);
+  const write = s.write.bind(s);
+  const settle = () => {
+    if (--st.n === 0) for (const r of st.idle.splice(0)) r();
+  };
+  s.write = (chunk, encoding, cb) => {
+    const done = typeof encoding === "function" ? encoding : cb;
+    const enc = typeof encoding === "function" ? void 0 : encoding;
+    if (chunk.length === 0) return write(chunk, enc, done);
+    st.n++;
+    let called = false;
+    return write(chunk, enc, (err) => {
+      if (!called) {
+        called = true;
+        settle();
+      }
+      done?.(err);
+    });
+  };
+}
+var CliExit = class extends Error {
+  code;
+  constructor(code) {
+    super(`exit ${code}`);
+    this.name = "CliExit";
+    this.code = code;
+  }
+};
+var cliDepth = 0;
+function exitCli(code) {
+  if (cliDepth > 0) throw new CliExit(code);
+  process.exit(code);
+}
+function runCli(main2, o, argv = process.argv.slice(2)) {
+  installQueuedConsole();
+  const done = o.done ?? ((code) => {
+    process.exitCode = code;
+  });
+  const fail = (e) => {
+    if (e instanceof CliExit) return done(e.code);
+    console.error(o.errorLine ? o.errorLine(e) : `${o.name}: ${e instanceof Error && e.stack || String(e)}`);
+    done(o.errorCode ?? 1);
+  };
+  cliDepth++;
+  let settled = false;
+  const leave = () => {
+    if (!settled) {
+      settled = true;
+      cliDepth--;
+    }
+  };
+  try {
+    const r = main2(argv);
+    if (typeof r === "number") {
+      leave();
+      done(r);
+    } else r.then((c) => {
+      leave();
+      done(c);
+    }, (e) => {
+      leave();
+      fail(e);
+    });
+  } catch (e) {
+    leave();
+    fail(e);
+  }
+}
+
+// design-to-code/proc.ts
+var pause = new Int32Array(new SharedArrayBuffer(4));
+
+// design-to-code/cli-args.ts
+var SELF = fileURLToPath(import.meta.url);
+var shellQuote = (p) => /["$`\\!]/.test(p) ? `'${p.replaceAll("'", `'\\''`)}'` : `"${p}"`;
+var SCRIPT_RUNNER = "bun --no-install --no-env-file";
+var scriptCmd = (name) => `${SCRIPT_RUNNER} ${shellQuote(path.join(path.dirname(SELF), name + path.extname(SELF)))}`;
+
+// bridge/src/read-json.ts
+import fs from "node:fs";
+var anyJson = (_x) => true;
+function readFailure(e) {
+  const code = e && typeof e === "object" && "code" in e ? e.code : void 0;
+  if (code === "ENOENT") return { error: "does not exist", missing: true };
+  return {
+    error: code === "EISDIR" ? "is a directory, not a file" : code === "EACCES" ? "is not readable (permission denied)" : `could not be read (${String(code || e)})`
+  };
+}
+function readJson(file, guard) {
+  let buf;
+  try {
+    buf = fs.readFileSync(file);
+  } catch (e) {
+    return readFailure(e);
+  }
+  if (buf.length >= 2 && (buf[0] === 255 && buf[1] === 254 || buf[0] === 254 && buf[1] === 255)) {
+    return { error: "is UTF-16, not UTF-8 \u2014 re-save it as UTF-8" };
+  }
+  let raw = buf.toString("utf8");
+  if (raw.charCodeAt(0) === 65279) raw = raw.slice(1);
+  let parsed;
+  try {
+    const value = JSON.parse(raw);
+    parsed = value;
+  } catch (e) {
+    return { error: `is not valid JSON \u2014 ${errMsg(e)}` };
+  }
+  if (!guard(parsed)) return { error: `is not ${guard.expected || "the expected kind of document"}` };
+  return { doc: parsed };
+}
+
+// design-to-code/catalog-input.ts
+function readJsonFile(file, what, hint) {
+  return readDocFile(file, what, anyJson, hint);
+}
+function readDocFile(file, what, guard, hint) {
+  return docOrExit(loadDocFile(file, what, guard, hint));
+}
+function loadDocFile(file, what, guard, hint, readAt = file) {
+  const r = readJson(readAt, guard);
+  if ("doc" in r) return r;
+  const ioFailure = r.missing || /^(is a directory|is not readable|could not be read)/.test(r.error);
+  return { error: `${what}: '${file}' ${r.error}${ioFailure ? "." : ""}` + (ioFailure && hint ? `
+       ${hint}` : "") };
+}
+function docOrExit(r) {
+  if ("doc" in r) return r.doc;
+  console.error(`error  ${r.error}`);
+  exitCli(2);
+}
+
+// bridge/src/json-util.ts
+function nullProto() {
+  return /* @__PURE__ */ Object.create(null);
+}
+function isRecord(x) {
+  return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+
+// design-to-code/map-validate-core.ts
+var STATUSES = ["active", "deprecated", "needs-review"];
+var KEYS = {
+  root: ["version", "figmaFileKey", "components"],
+  entry: ["figma", "code", "props", "variantOverrides", "childrenByLayer", "status", "note"],
+  figma: ["key", "id", "name", "unstable"],
+  code: ["module", "export", "targets"],
+  target: ["module", "export"],
+  vo: ["when", "code"],
+  voCode: ["module", "export"],
+  children: ["layerNamePattern", "slot"],
+  prop: Object.assign(nullProto(), {
+    enum: ["kind", "codeProp", "values", "default", "omitDefault"],
+    boolean: ["kind", "codeProp", "default", "omitDefault"],
+    string: ["kind", "codeProp"],
+    instance: ["kind", "codeProp", "slot"]
+  })
+};
+var PROP_KINDS = Object.keys(KEYS.prop);
+var isStr = (v) => typeof v === "string";
+var isBool = (v) => typeof v === "boolean";
+var noExtra = (obj, allowed, at, err) => {
+  if (!Array.isArray(allowed)) return;
+  for (const k of Object.keys(obj)) if (!allowed.includes(k)) err(`${at}.${k}`, "unknown property (additionalProperties:false)");
+};
+var optStrings = (obj, keys, at, err) => {
+  for (const k of keys) if (obj[k] !== void 0 && !isStr(obj[k])) err(`${at}.${k}`, "must be a string");
+};
+function validateMap(map) {
+  const errors = [];
+  const err = (path2, message) => errors.push({ path: path2, message });
+  if (!isRecord(map)) return { ok: false, errors: [{ path: "", message: "map must be an object" }] };
+  noExtra(map, KEYS.root, "", err);
+  if (map.version !== 1) err("version", "must be 1");
+  if (map.figmaFileKey !== void 0 && !isStr(map.figmaFileKey)) err("figmaFileKey", "must be a string");
+  if (!isRecord(map.components)) {
+    err("components", "must be an object");
+    return { ok: false, errors };
+  }
+  for (const key of Object.keys(map.components)) {
+    const e = map.components[key];
+    const at = `components.${key}`;
+    if (!isRecord(e)) {
+      err(at, "entry must be an object");
+      continue;
+    }
+    noExtra(e, KEYS.entry, at, err);
+    if (!isRecord(e.figma)) err(`${at}.figma`, "required object");
+    else {
+      noExtra(e.figma, KEYS.figma, `${at}.figma`, err);
+      if (!isStr(e.figma.name)) err(`${at}.figma.name`, "required string");
+      optStrings(e.figma, ["key", "id"], `${at}.figma`, err);
+      if (e.figma.unstable !== void 0 && !isBool(e.figma.unstable)) err(`${at}.figma.unstable`, "must be a boolean");
+    }
+    if (!isRecord(e.code)) err(`${at}.code`, "required object");
+    else {
+      noExtra(e.code, KEYS.code, `${at}.code`, err);
+      if (!isStr(e.code.module)) err(`${at}.code.module`, "required string");
+      if (!isStr(e.code.export)) err(`${at}.code.export`, "required string");
+      if (e.code.targets !== void 0) {
+        if (!isRecord(e.code.targets)) err(`${at}.code.targets`, "must be an object");
+        else for (const t of Object.keys(e.code.targets)) {
+          const tv = e.code.targets[t], ta = `${at}.code.targets.${t}`;
+          if (!isRecord(tv)) err(ta, "must be an object");
+          else {
+            noExtra(tv, KEYS.target, ta, err);
+            optStrings(tv, ["module", "export"], ta, err);
+          }
+        }
+      }
+    }
+    if (e.status !== void 0 && (!isStr(e.status) || !STATUSES.includes(e.status))) err(`${at}.status`, `must be one of ${STATUSES.join("|")}`);
+    optStrings(e, ["note"], at, err);
+    if (e.props !== void 0) {
+      if (!isRecord(e.props)) err(`${at}.props`, "must be an object");
+      else for (const pn of Object.keys(e.props)) validateProp(e.props[pn], `${at}.props.${pn}`, err);
+    }
+    if (e.variantOverrides !== void 0) {
+      if (!Array.isArray(e.variantOverrides)) err(`${at}.variantOverrides`, "must be an array");
+      else e.variantOverrides.forEach((vo, i) => {
+        const va = `${at}.variantOverrides[${i}]`;
+        if (!isRecord(vo)) {
+          err(va, "must be an object");
+          return;
+        }
+        noExtra(vo, KEYS.vo, va, err);
+        if (!isRecord(vo.when)) err(`${va}.when`, "required object");
+        else for (const wk of Object.keys(vo.when)) if (!isStr(vo.when[wk])) err(`${va}.when.${wk}`, "value must be a string");
+        if (!isRecord(vo.code)) err(`${va}.code`, "required object");
+        else {
+          noExtra(vo.code, KEYS.voCode, `${va}.code`, err);
+          if (!isStr(vo.code.module)) err(`${va}.code.module`, "required string");
+          if (!isStr(vo.code.export)) err(`${va}.code.export`, "required string");
+        }
+      });
+    }
+    if (e.childrenByLayer !== void 0) {
+      if (!isRecord(e.childrenByLayer)) err(`${at}.childrenByLayer`, "must be an object");
+      else {
+        noExtra(e.childrenByLayer, KEYS.children, `${at}.childrenByLayer`, err);
+        optStrings(e.childrenByLayer, ["layerNamePattern", "slot"], `${at}.childrenByLayer`, err);
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+function validateProp(p, at, err) {
+  if (!isRecord(p)) {
+    err(at, "prop must be an object");
+    return;
+  }
+  const allowed = typeof p.kind === "string" ? KEYS.prop[p.kind] : void 0;
+  if (!Array.isArray(allowed)) {
+    err(`${at}.kind`, `must be one of ${PROP_KINDS.join("|")}`);
+    return;
+  }
+  noExtra(p, allowed, at, err);
+  if (p.kind !== "instance" && !isStr(p.codeProp)) err(`${at}.codeProp`, "required string");
+  if (p.kind === "instance" && p.codeProp !== void 0 && !isStr(p.codeProp)) err(`${at}.codeProp`, "must be a string");
+  if (p.kind === "instance" && p.slot !== void 0 && !isStr(p.slot)) err(`${at}.slot`, "must be a string");
+  if (p.kind === "enum") {
+    if (p.values !== void 0 && !isRecord(p.values)) err(`${at}.values`, "must be an object (VARIANT option -> code value)");
+    else if (isRecord(p.values)) for (const k of Object.keys(p.values)) {
+      const t = typeof p.values[k];
+      if (p.values[k] !== null && !["string", "number", "boolean"].includes(t)) err(`${at}.values.${k}`, "value must be string|number|boolean|null");
+    }
+    if (p.default !== void 0 && !["string", "number", "boolean"].includes(typeof p.default)) err(`${at}.default`, "must be string|number|boolean");
+  }
+  if (p.kind === "boolean" && p.default !== void 0 && !isBool(p.default)) err(`${at}.default`, "must be a boolean");
+  if ((p.kind === "enum" || p.kind === "boolean") && p.omitDefault !== void 0 && !isBool(p.omitDefault)) err(`${at}.omitDefault`, "must be a boolean");
+}
+function isCodeConnectMap(x) {
+  return validateMap(x).ok;
+}
+isCodeConnectMap.expected = "a valid component map (the map-validate script lists what is wrong with it)";
+
+// design-to-code/map-validate.ts
+function main(argv) {
+  const file = argv[0];
+  const USAGE = `usage: ${scriptCmd("map-validate")} <map.json>`;
+  if (file === "--help" || file === "-h") {
+    console.log(USAGE);
+    return 0;
+  }
+  if (!file || file.startsWith("-")) {
+    console.error((file ? `map-validate: unknown flag ${file}
+` : "") + USAGE);
+    return 1;
+  }
+  const res = validateMap(readJsonFile(file, "component map"));
+  if (res.ok) {
+    console.log("map valid");
+    return 0;
+  }
+  res.errors.forEach((e) => console.error(`  ${e.path || "(root)"}: ${e.message}`));
+  console.error(`
+${res.errors.length} error(s)`);
+  return 1;
+}
+if (import.meta.main) runCli(main, { name: "map-validate" });
+export {
+  main
+};

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@design-twin/dtwin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Design Twin bridge: local CLI + MCP server between Claude Code and the Design Twin Figma plugin. Reads a design on the free Figma plan, fully offline.",
+  "license": "MIT",
+  "author": "Mohamed Magdy Omar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/its-magdy/design-twin.git",
+    "directory": "bridge"
+  },
+  "homepage": "https://github.com/its-magdy/design-twin/tree/main/bridge#readme",
+  "bugs": "https://github.com/its-magdy/design-twin/issues",
+  "keywords": [
+    "figma",
+    "mcp",
+    "model-context-protocol",
+    "design-to-code",
+    "design-system",
+    "design-tokens",
+    "claude-code",
+    "figma-plugin",
+    "cli"
+  ],
+  "type": "module",
+  "engines": {
+    "bun": ">=1.4.2"
+  },
+  "bin": {
+    "dtwin": "src/figma-pull.ts"
+  },
+  "files": [
+    "src",
+    "layer",
+    "figma-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "prepack": "bun --no-install --no-env-file pack.ts",
+    "postpack": "bun --no-install --no-env-file pack.ts --clean",
+    "pull": "bun src/figma-pull.ts",
+    "pull:selection": "bun src/figma-pull.ts design --selection",
+    "mcp": "bun src/figma-mcp.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  }
+}

package/src/abort-reason.ts

@@ -0,0 +1,12 @@
+// abort-reason.ts — bridge-side only (AbortSignal, DOMException): json-util.ts is also type-checked by the
+// plugin, which has no DOM lib.
+
+/**
+ * Why a request the caller gave up on is rejected: the signal's reason when that is an Error of the
+ * caller's own, else `fallback`. A bare abort() carries a DOMException "AbortError" (itself an Error in
+ * Node), which names nothing, so it gets the fixed text. The one rule for the bridge and the daemon client.
+ */
+export function abortReason(signal: AbortSignal, fallback: string): Error {
+  const r: unknown = signal.reason;
+  return r instanceof Error && !(r instanceof DOMException) ? r : new Error(fallback);
+}

package/src/asset-compare.ts

@@ -0,0 +1,175 @@
+// asset-compare.ts — bridge-side byte comparison built on svg-normalize.ts's two definitions: the v1
+// normalised hash (normalizeForCompare/sameAsset — design-diff's, unchanged) and the fingerprint index
+// the shared assets/ directory dedups with (ContentIndex, below).
+//
+// Split out of svg-normalize.ts (rather than living there) because this needs `crypto`, which the
+// Figma plugin sandbox does not have — and svg-normalize.ts must type-check under the plugin's
+// tsconfig (no Node types) and bundle into the plugin, so an `import … from "node:crypto"` anywhere
+// in a file the plugin bundle imports breaks that build, even for a function the bundle never calls.
+// svg-normalize.ts stays crypto-free so figma-plugin/src/util.ts can safely re-export it; this file
+// is imported only from the Bun side (bridge/src/write-out.ts, design-to-code/design-diff.ts — the latter
+// bundled by claude-plugin/build-scripts.ts the same way it already bundles bridge/src/export-verdict.ts).
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { normalizeSvgText, isSvgName, svgFingerprint, numsWithin, relWithin, SVG_TOL } from "./svg-normalize.ts";
+import { FileMemo } from "./file-memo.ts";
+
+// `content` may be a Buffer (bytes on disk / about to be written) or a string (an SVG the plugin just
+// produced, before it's ever touched a filesystem) — normalised either way. Always returns a Buffer.
+export function normalizeForCompare(fileName: unknown, content: Buffer | string): Buffer {
+  const buf = Buffer.isBuffer(content) ? content : Buffer.from(String(content), "utf8");
+  if (!isSvgName(fileName)) return buf;
+  return Buffer.from(normalizeSvgText(buf.toString("utf8")), "utf8");
+}
+
+export function sha1Hex(buf: Buffer | string): string {
+  return crypto.createHash("sha1").update(buf).digest("hex");
+}
+
+// The comparison every "is this the same asset" decision should use: true if the two byte strings are
+// the same asset MODULO Figma's own export noise (SVG coordinate rounding only; PNG/other bytes are
+// compared exactly — a changed pixel there is real signal, not noise).
+export function sameAsset(fileName: unknown, a: Buffer | string, b: Buffer | string): boolean {
+  return Buffer.compare(normalizeForCompare(fileName, a), normalizeForCompare(fileName, b)) === 0;
+}
+
+// ---- ContentIndex: "is this content already in assets/, under ANY name"
+//
+// A hash cannot express "within a tolerance", so the index is two-level: the KEY is exact — sha1 of the
+// SVG's fingerprint skeleton (ids canonical, numbers out), or sha1 of the bytes for anything that is not an
+// SVG (a changed pixel is real signal) — and inside one key's bucket the members are compared on their
+// numbers, every one within SVG_TOL (a `<use>`/`<image>` transform's relatively — see svg-normalize.ts). Members are kept in
+// REPRESENTATIVE order — the plain name before a `-<6 hex>[_N]` suffixed copy, then the shortest, then
+// alphabetical (ownCopyWithContent's order in write-out.ts) — so `find` names the same file whichever order
+// the directory listed them in.
+
+/** The exact half of an asset's content identity, plus the numbers its tolerance applies to (`rel`: the
+ *  relatively compared ones). */
+export interface ContentKey { key: string; nums: Float64Array; rel: Float64Array }
+interface Member { name: string; nums: Float64Array; rel: Float64Array }
+/** One cluster of files the index treats as the same asset; `files[0]` is its representative. */
+export interface ContentGroup { hash: string; files: string[] }
+
+const EMPTY_NUMS = new Float64Array(0);
+const SUFFIXED_RE = /-[0-9a-z]{6}(_\d+)?\.[^.]+$/i;
+
+/** Representative order: plain name first, then shortest, then alphabetical. */
+export function representativeOrder(x: string, y: string): number {
+  const sx = SUFFIXED_RE.test(x) ? 1 : 0, sy = SUFFIXED_RE.test(y) ? 1 : 0;
+  return sx - sy || x.length - y.length || (x < y ? -1 : x > y ? 1 : 0);
+}
+
+export function contentKey(fileName: unknown, content: Buffer | string): ContentKey {
+  const buf = Buffer.isBuffer(content) ? content : Buffer.from(String(content), "utf8");
+  if (!isSvgName(fileName)) return { key: "b:" + sha1Hex(buf), nums: EMPTY_NUMS, rel: EMPTY_NUMS };
+  const fp = svgFingerprint(buf.toString("utf8"));
+  return { key: "s:" + sha1Hex(fp.skeleton), nums: fp.nums, rel: fp.rel };
+}
+
+// A stable id for a cluster: its key plus its representative's numbers rounded to 2 places (`-0.00` folded
+// into `0.00`), and its `rel` numbers to 3 significant digits (two clusters of one key may differ only
+// there). Reported as `duplicates[].hash` — it names the group, it is not a hash of any one file.
+function groupHash(key: string, m: Member): string {
+  let text = key + "|";
+  for (const n of m.nums) { const f = n.toFixed(2); text += (f === "-0.00" ? "0.00" : f) + ","; }
+  if (m.rel.length) { text += "|"; for (const n of m.rel) text += (n === 0 ? "0" : n.toPrecision(3)) + ","; }
+  return sha1Hex(text);
+}
+const within = (a: Member | ContentKey, b: Member | ContentKey, tol: number): boolean => numsWithin(a.nums, b.nums, tol) && relWithin(a.rel, b.rel, tol);
+
+export class ContentIndex {
+  private readonly buckets = new Map<string, Member[]>();
+  // name -> the key of the bucket holding it, so a replace touches one bucket instead of scanning them all.
+  private readonly bucketOf = new Map<string, string>();
+  // Buckets added to since they were last sorted. Sorting is deferred to the next read of the bucket, so
+  // building the index over a directory sorts each bucket once instead of once per add. The order is the
+  // same either way: representativeOrder never ties two different names.
+  private readonly unsorted = new Set<string>();
+  private readonly tol: number;
+  constructor(tol: number = SVG_TOL) { this.tol = tol; }
+
+  private sortedBucket(key: string): Member[] | undefined {
+    const bucket = this.buckets.get(key);
+    if (bucket && this.unsorted.delete(key)) bucket.sort((x, y) => representativeOrder(x.name, y.name));
+    return bucket;
+  }
+
+  /** The first member (representative order) the same as `k`, or undefined. */
+  findKey(k: ContentKey): string | undefined {
+    const bucket = this.sortedBucket(k.key);
+    if (!bucket) return undefined;
+    for (const m of bucket) if (within(m, k, this.tol)) return m.name;
+    return undefined;
+  }
+  find(fileName: string, content: Buffer | string): string | undefined { return this.findKey(contentKey(fileName, content)); }
+
+  /** Add a file under `name` (a name already present is replaced, so a rewrite never leaves a stale member). */
+  addKey(name: string, k: ContentKey): void {
+    const prevKey = this.bucketOf.get(name);
+    const prev = prevKey === undefined ? undefined : this.buckets.get(prevKey);
+    if (prevKey !== undefined && prev) {
+      const i = prev.findIndex((m) => m.name === name);
+      if (i >= 0) prev.splice(i, 1);
+      if (!prev.length) { this.buckets.delete(prevKey); this.unsorted.delete(prevKey); }
+    }
+    let bucket = this.buckets.get(k.key);
+    if (!bucket) { bucket = []; this.buckets.set(k.key, bucket); }
+    bucket.push({ name, nums: k.nums, rel: k.rel });
+    this.bucketOf.set(name, k.key);
+    if (bucket.length > 1) this.unsorted.add(k.key);
+  }
+  add(name: string, content: Buffer | string): void { this.addKey(name, contentKey(name, content)); }
+
+  /** Every cluster, singletons included. Each member joins the first cluster (representative order) whose
+   *  representative is within tolerance of it. `find` answers "the first member within tolerance", which is
+   *  that same representative unless members chain apart by more than the tolerance (never seen: the real
+   *  drift is 0.004, the tolerance 0.01). */
+  groups(): ContentGroup[] { return this.clustersOf(null); }
+
+  /** groups(), limited to the buckets holding `names` — the same clusters, in the same order, as groups() gives for
+   *  them. Clustering is quadratic in a bucket's size, so a pull asking about its own few files does not pay for
+   *  every bucket of a directory every screen ever pulled shares. A name not in the index adds nothing. */
+  groupsOf(names: Iterable<string>): ContentGroup[] {
+    const keys = new Set<string>();
+    for (const n of names) { const k = this.bucketOf.get(n); if (k !== undefined) keys.add(k); }
+    return keys.size ? this.clustersOf(keys) : [];
+  }
+
+  private clustersOf(only: ReadonlySet<string> | null): ContentGroup[] {
+    const out: ContentGroup[] = [];
+    for (const key of this.buckets.keys()) {
+      if (only && !only.has(key)) continue;
+      const members = this.sortedBucket(key) ?? [];
+      const clusters: Member[][] = [];
+      for (const m of members) {
+        const c = clusters.find((cl) => { const rep = cl[0]; return rep !== undefined && within(rep, m, this.tol); });
+        if (c) c.push(m); else clusters.push([m]);
+      }
+      for (const cl of clusters) {
+        const rep = cl[0];
+        if (rep) out.push({ hash: groupHash(key, rep), files: cl.map((m) => m.name) });
+      }
+    }
+    return out;
+  }
+}
+
+// ---- FileKeyCache: a file's ContentKey, remembered across pulls in one process
+//
+// Every screen pull builds the ContentIndex over the whole shared assets/ directory, so a process that pulls
+// many screens would otherwise re-read and re-fingerprint every file in it on every pull. file-memo.ts says
+// when a remembered key may be used.
+
+export class FileKeyCache extends FileMemo<ContentKey> {
+  /** contentKey(name, <the bytes of `file`>), or undefined when the file cannot be read. */
+  keyOf(file: string, name: string): ContentKey | undefined {
+    return this.get(file, () => {
+      let bytes: Buffer;
+      try { bytes = fs.readFileSync(file); } catch { return undefined; }
+      return contentKey(name, bytes);
+    });
+  }
+}
+
+/** The process-wide cache buildContentIndex (write-out.ts) reads assets/ through. */
+export const fileKeyCache = new FileKeyCache();