@design-twin/dtwin 0.0.0-stage → 0.1.0

package/src/quick-keys.ts

@@ -0,0 +1,68 @@
+// quick-keys.ts — the ONE text of the "Scripting quick keys": the export-JSON keys a script needs
+// before it walks a screen file. Builders and verifiers kept guessing field names from Figma's Plugin
+// API (`characters`, `width`, `visible`, `layout.scroll`) although ir-fields.md had the right ones —
+// the reference was never opened by the agent writing the walker. So the same text lives in two
+// places, both kept identical by a doc-guard (test/build-screen-docs.test.ts):
+//   - the top of claude-plugin/skills/build-screen/references/ir-fields.md, between the
+//     `quick-keys:start` / `quick-keys:end` markers;
+//   - design/export/SCHEMA.md, which write-out.ts writes next to the data on every pull that writes to
+//     disk (CLI + MCP writeToDisk), so a script-writing agent finds it where it looks.
+// Edit the text HERE and paste it into ir-fields.md; the guard fails until both agree.
+
+/** File name of the generated copy inside the export dir. Not README.md: in the legacy flat layout the
+ *  export dir IS design/, where `dtwin init` writes its own design/README.md. */
+export const SCHEMA_DOC_NAME = "SCHEMA.md";
+
+/** First line of the generated copy. A SCHEMA.md without it is the user's file and is never touched. */
+export const SCHEMA_MARKER = "<!-- generated by dtwin: scripting quick keys -->";
+
+export const QUICK_KEYS = `## Scripting quick keys
+
+Read these before writing ANY script against an export JSON (field names guessed from Figma's Plugin API are wrong).
+
+- **The tree.** A screen file (\`pages/<Page>/<Screen>__<id>.json\`) holds it in \`nodes[]\` — a \`--node\` pull has exactly
+  one root, \`nodes[0]\`; a page-walk layer file holds it at \`tree\`. \`pages/index.json\` \`layers[]\` lists every screen
+  — \`file\` and \`texts\` on every row (\`title\` when the frame shows text); a \`--node\`/selection row also has \`w\`/\`h\`
+  and, when written, \`variables\`, \`assets\`, \`reference\` (a page-walk row has \`nodes\`/\`bytes\`; its \`reference\` is
+  in the layer file) — read it instead of building filenames.
+- **Text** is \`text\`, not \`characters\`. Type: \`font.size\`, \`font.lineHeight\`, \`font.weightValue\`, \`font.letterSpacing\`,
+  \`font.family\`, \`font.color\` (there is no \`style\`). \`runs[]\` present = mixed formatting: \`font\` is then the FIRST
+  run's — read every run.
+- **Size** is \`box.w\`/\`box.h\`; there are no top-level \`width\`/\`height\`. A single-screen index row repeats the size
+  as \`w\`/\`h\`.
+- **Position.** \`box.x\`/\`box.y\` are PAGE (canvas) coordinates — frame-relative = \`box.x − <root>.box.x\` (root = \`nodes[0]\` in a screen file,
+  \`tree\` in a page-walk layer file). A node's
+  own \`x\`/\`y\` are relative to its nearest frame / component / instance / section ancestor (Figma skips GROUPs and
+  boolean operations; the page at top level). Both exist only when the parent does not lay the node out (no auto layout,
+  or \`absolute:true\`); inside an auto-layout parent the position comes from the parent's \`layout\` (padding, gap,
+  order). \`layout.inferred:true\` is a guess on a frame without auto layout — its children still carry \`x\`/\`y\`.
+- **\`absolute:true\`** = out of the parent's auto-layout flow, placed by \`x\`/\`y\`; absent = in flow. \`layout\` describes
+  how a node lays out ITS OWN children, so only a node that can hold children has it: \`layout.mode:"absolute"\` =
+  no auto layout inside — it never means the node itself is absolute.
+- **Child order.** \`children[]\` is Figma's layer list: paint order bottom → top (reversed when the parent's
+  \`layout.reverseZ\` is set). In an auto-layout parent it is also the flow order (first = leading); otherwise — and for
+  every \`absolute:true\` child — the visual order comes only from \`x\`/\`y\`.
+- **Hidden layers stay in the tree.** \`hidden:true\` sits on the layer that was switched off; its descendants are not
+  flagged on its account (they may carry their own). Skip a node when it OR ANY ANCESTOR is hidden. There is no
+  node-level \`visible\` key.
+- **Scroll.** \`clip:true\`; \`scroll\` (\`horizontal\`/\`vertical\`/\`both\`, a node field — not under \`layout\`);
+  \`fixedChildren:N\` = the LAST N entries of \`children[]\` stay pinned while the rest scrolls (Figma moves fixed layers
+  to the top of the layer list); fixed only — "sticky" is not exposed, so a Sticky child is not marked. Each pinned
+  child carries \`x\`/\`y\` (in an auto-layout frame Figma lets only an \`absolute:true\` child be fixed); place it by its
+  \`y\` (top bar → sticky top, bottom bar → sticky bottom).
+- **Render bounds.** \`renderBox\` (only when it differs from \`box\`) = Figma's render bounds: larger than \`box\` for
+  shadow / stroke / blur; on a TEXT usually smaller than \`box\` (observed).
+- **Three \`strokes\`.** \`strokes\` is always an object (\`colors[]\`, \`weight\` or \`weights{}\`, \`align\`…);
+  \`geometry.strokes\` is a list of SVG path strings; \`tokens.strokes\` is a variable name (or a list).
+- **Tokens.** \`tokens.<property>\` = the bound variable's NAME — a string, or a list when several paints are bound;
+  paint-level \`fills[].tokens.color\`; text \`textTokens\` / \`runs[].tokens\`. Never map by the hex beside it.
+- **Ids.** Inside an instance a node id looks like \`I<instance id>;<layer id>\` (observed) and differs per instance;
+  the component itself is \`mainComponent\` (\`key\`/\`setKey\`).
+- **Files.** \`asset\` and \`reference\` are paths relative to \`design/export/\` (\`assets/<file>\`); \`assetFrom\` = a hidden
+  graphic reusing a visible twin's file; \`assetSkipped\` = no file at all. \`<Screen>.assets.json\`
+  (single-screen pulls) lists every file.
+- **Older exports.** A file pulled with an older plugin also has \`gridColumnStart:-1\` / \`gridRowStart:-1\` on every node,
+  \`gridAlignSelf\` / \`gridJustifySelf\` on a node whose parent is not a grid, and \`layout.mode:"absolute"\` on every
+  TEXT, shape, SLICE, STICKY and other leaf type (a node TYPE that cannot hold children has no \`layout\`) — ignore all of it
+  (design-diff does).
+`;

package/src/read-json.ts

@@ -0,0 +1,67 @@
+// read-json.ts — the ONE way a JSON document is read off disk, by the bridge's export reader (export-reader.ts) and
+// the whole design-to-code layer alike.
+//
+// readJson(file, guard) reads, parses and checks the file against a guard (design-to-code/doc-guards.ts holds one per
+// document kind that layer reads; export-reader.ts holds the export index's and manifest's), and returns either the
+// typed document or a one-line reason. It never throws and never exits: each caller keeps its own reporting convention
+// (a CLI prints the reason and exits 2; a best-effort lookup treats an unreadable file as absent). This replaces the
+// `JSON.parse(fs.readFileSync(f)) as T` reads — and the five generic `<T>(f) => … as T` helpers — that trusted every
+// file to be what its name said.
+import fs from "node:fs";
+import { errMsg } from "./errmsg.ts";
+
+/** A type guard that can say, in words, what it expects (readJson prints it on a mismatch). */
+export type DocGuard<T> = ((x: unknown) => x is T) & { expected?: string };
+
+/** readJson()'s result: the document, or why there is none. `missing` is set when the file does not exist. */
+export type ReadResult<T> = { doc: T } | { error: string; missing?: true };
+
+/** Any JSON value at all — for a caller that narrows the parsed value itself. */
+export const anyJson: DocGuard<unknown> = (_x: unknown): _x is unknown => true;
+
+// Why a read failed, in words (the same wording catalog-input.ts's readJsonFile has always printed).
+function readFailure(e: unknown): { error: string; missing?: true } {
+  const code = e && typeof e === "object" && "code" in e ? e.code : undefined;
+  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)})`,
+  };
+}
+
+/** Read + parse + check. The reason is a phrase that follows the file name: `'<file>' <error>`. */
+export function readJson<T>(file: string, guard: DocGuard<T>): ReadResult<T> {
+  let buf: Buffer;
+  try { buf = fs.readFileSync(file); } catch (e) { return readFailure(e); }
+  // A UTF-16 BOM (FF FE little-endian, FE FF big-endian) means decoding as UTF-8 below would either
+  // throw or (worse) silently produce mojibake that then fails JSON.parse with a confusing error — catch
+  // it up front and say what is actually wrong.
+  if (buf.length >= 2 && ((buf[0] === 0xff && buf[1] === 0xfe) || (buf[0] === 0xfe && buf[1] === 0xff))) {
+    return { error: "is UTF-16, not UTF-8 — re-save it as UTF-8" };
+  }
+  let raw = buf.toString("utf8");
+  // A UTF-8 BOM (EF BB BF, decoded as U+FEFF) is invisible but not valid JSON syntax — strip it before
+  // parsing (verified: JSON.parse of a BOM'd file throws "Unexpected token" otherwise).
+  if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
+  let parsed: unknown;
+  try { const value: unknown = JSON.parse(raw); parsed = value; } catch (e) { return { error: `is not valid JSON — ${errMsg(e)}` }; }
+  if (!guard(parsed)) return { error: `is not ${guard.expected || "the expected kind of document"}` };
+  return { doc: parsed };
+}
+
+/** A regular file's bytes, or null when it is absent, unreadable or not a regular file (a directory, a FIFO, a device —
+ *  a path a hand-edited document names must not hang a hook: /dev/zero never ends, a FIFO's open waits for a writer).
+ *  Checked before the open (opening a FIFO blocks) and again on the open descriptor. */
+export function readRegularFile(file: string): Buffer | null {
+  try { if (!fs.statSync(file).isFile()) return null; } catch { return null; }
+  let fd: number;
+  try { fd = fs.openSync(file, "r"); } catch { return null; }
+  try { return fs.fstatSync(fd).isFile() ? fs.readFileSync(fd) : null; } catch { return null; } finally { fs.closeSync(fd); }
+}
+
+/** The document, or null when it is absent, unreadable or the wrong shape — for best-effort lookups. */
+export function readJsonOrNull<T>(file: string, guard: DocGuard<T>): T | null {
+  const r = readJson(file, guard);
+  return "doc" in r ? r.doc : null;
+}

package/src/read-opts.ts

@@ -0,0 +1,125 @@
+// read-opts.ts — THE registry of the extractor's opt-in read options.
+//
+// The same six names would otherwise be written out by hand in four places: the plugin's run reads
+// (run.ts), the `CollectOpts` interface (collect.ts), the CLI's flag table (figma-pull.ts), and the
+// MCP tool schema (figma-mcp.ts). Every one of those is a place a new option can be forgotten, and
+// the failure is SILENT in both front-ends: the CLI just never sets the flag, and the MCP SDK's Zod
+// object mode STRIPS undeclared keys before the handler runs. That is not hypothetical — `skipAssets`
+// was once declared on figma_export_full only, which made it dead on the other two export tools with
+// nothing to make the lists disagree loudly. Fixing that *within each file* would leave four
+// consistent-by-luck lists instead of one.
+//
+// So: one row here is the whole change. `name` is the wire/option key the plugin reads, `flag` is the
+// CLI spelling, `describe` is the MCP tool-schema help (the only consumer of prose, but it lives here
+// so a new option cannot ship undocumented), `scopes` the reads that take it (see READ_SCOPES below).
+//
+// Dependency-free on purpose — the same arrangement as node-id.ts / pages-layout.ts / errmsg.ts:
+// imported by the CLI and the MCP entry, and inlined into the plugin bundle by esbuild, so it must
+// type-check under the plugin's tsconfig too (ES2019 lib, no Node types).
+//
+// ReadOptName is DERIVED from the registry below (`as const satisfies`), so the names are typed in
+// exactly one place: CollectOpts and the run's reads both derive from it, and adding a row here makes
+// TypeScript fail loudly at every site that must handle the new option rather than letting one
+// drift silently.
+
+// The read SCOPES — what one read exports. read-plan.ts turns a scope into the command that reads it; each
+// row below declares the scopes that take it, and a read option given to any other scope is refused (the
+// CLI) or not declared at all (each MCP tool's schema is derived from its scope). Declared as what each
+// front-end accepted before the rows said so, not as what the plugin is known to read: variantVisuals on a
+// node or selection pull builds no catalog, and a variant walk does serialize with the walk options on —
+// both decisions for another day, and one row each when they are made.
+export const READ_SCOPES = ["node", "selection", "pages", "designSystem", "library", "screenshot"] as const;
+export type ReadScopeKind = (typeof READ_SCOPES)[number];
+/** The scopes that walk nodes: every walk option is read there. */
+const WALK = ["node", "selection", "pages"] as const;
+
+export interface ReadOptDef {
+  /** The option key on the wire / in CollectOpts. */
+  name: string;
+  /** The figma-pull CLI spelling. */
+  flag: string;
+  /** Help text for the MCP tool schema. */
+  describe: string;
+  /** The read scopes that take this option. */
+  scopes: readonly ReadScopeKind[];
+}
+
+export const READ_OPTS = [
+  {
+    name: "css",
+    flag: "--css",
+    describe:
+      "Include Figma's OWN computed CSS per node (getCSSAsync) — the design-to-code oracle. One async call per node, so larger/slower; use for a screen you're implementing.",
+    scopes: WALK,
+  },
+  {
+    // NOT "Dev Mode only": per developers.figma.com only addMeasurement/editMeasurement/
+    // deleteMeasurement carry that restriction — PageNode.getMeasurements() has no such note. And no
+    // longer "current page": collect.ts reads measurements from the page(s) actually exported.
+    name: "measurements",
+    flag: "--measurements",
+    describe:
+      "Include measurement redlines (spacing specs the designer placed) for the exported page(s). Reading them does not require Dev Mode.",
+    scopes: WALK,
+  },
+  {
+    name: "pluginData",
+    flag: "--plugin-data",
+    describe:
+      "Include own-scope plugin data (getPluginData) stamped on nodes — round-trip metadata. Usually empty unless the write plane wrote it.",
+    scopes: WALK,
+  },
+  {
+    name: "motion",
+    flag: "--motion",
+    describe:
+      "Include motion/animation reads (timelines, manual keyframe tracks, animations, applied animation styles). Free via the Plugin API; useful for Slides/prototype animation. Can be verbose.",
+    scopes: WALK,
+  },
+  {
+    name: "sharedData",
+    flag: "--shared-data",
+    describe:
+      "Include cross-plugin shared data (getSharedPluginData) — notably Tokens Studio applied tokens (the semantic token layer on files without native Figma Variables). Free; per-node.",
+    scopes: WALK,
+  },
+  {
+    name: "variantVisuals",
+    flag: "--variant-visuals",
+    describe:
+      "Walk each COMPONENT_SET's variant children and record their real layout/fills/radius/tokens/css — the master-component source of truth, not the component-set wrapper's own selection-chrome visuals. One node walk per variant; noticeably slower on large systems.",
+    scopes: [...WALK, "designSystem", "library"],
+  },
+  {
+    // The odd one out: the others ADD work, this one REMOVES it. Asset export is one exportAsync (a
+    // real render round-trip — SVG per vector, 2x PNG per image) PER NODE, run sequentially, and
+    // unlike getCSSAsync it was never gated despite being the same O(nodes) shape and far more
+    // expensive. On a real design-system page it dominates the export and can outgrow the bridge's
+    // frame limit. Opt-IN to skipping, so the default stays exactly as it was.
+    name: "skipAssets",
+    flag: "--no-assets",
+    describe:
+      "Skip the per-node SVG/PNG render pass — the dominant cost on a big file. Structure, layout and tokens are unaffected; skipped nodes stay leaves marked `assetSkipped: true`. Asset BYTES are stripped from MCP results anyway, so this is usually pure savings here.",
+    scopes: WALK,
+  },
+] as const satisfies readonly ReadOptDef[];
+
+/** The literal union of every option key — "css" | "measurements" | … | "skipAssets". */
+export type ReadOptName = (typeof READ_OPTS)[number]["name"];
+
+/** A registry row as its readers take it: its name typed, its scopes widened to every scope (so a reader
+ *  can ask whether a row lists any scope, not only one it already knows it lists). */
+export type ReadOptRow = ReadOptDef & { name: ReadOptName };
+export const READ_OPT_ROWS: readonly ReadOptRow[] = READ_OPTS;
+
+/** The options a scope takes, as a literal union — what an MCP tool's schema for that scope declares. */
+export type ReadOptNameFor<K extends ReadScopeKind> = RowNameFor<(typeof READ_OPTS)[number], K>;
+type RowNameFor<R, K> = R extends { name: infer N; scopes: readonly (infer S)[] } ? (K extends S ? N : never) : never;
+
+// Every option defaulted off, as a fresh object per call (callers fill it in — each run builds its own
+// reads from one). Derived here so no consumer restates the names just to zero them.
+export function readOptDefaults(): Record<ReadOptName, boolean> {
+  const o: Partial<Record<ReadOptName, boolean>> = {};
+  for (const d of READ_OPTS) o[d.name] = false;
+  return o as Record<ReadOptName, boolean>; // every key was just set by the loop above
+}

package/src/read-plan.ts

@@ -0,0 +1,105 @@
+// read-plan.ts — what a front-end sends for one read: the command, its arguments, its time budget and the
+// line that names it, or the read options that scope does not take.
+//
+// Both front-ends used to build these themselves — the CLI in exportCmd/screenshotCmd, the MCP server in
+// each export tool — and each one restated the rules: which command a scope is, that an empty page list is
+// no selector, that a catalog pull takes variantVisuals alone, which budget tier a scope gets (the CLI from
+// one call, the MCP server from five spelled-out constants). One function now, so a scope, a tier or a
+// read option reaches both at once. The route (route.ts) then carries the plan to the plugin.
+//
+// The rules it owns:
+//   - the command per scope, and its arguments: every read option the scope takes is SAID, as a boolean, in
+//     registry order — never left out. The plugin's autoCss resolves only an absent `css`, so leaving one out
+//     would quietly switch CSS on for a small node; a decision the plan makes for every caller or none.
+//   - `page` is sent only when the list is non-empty (an empty list is the current page, not a selector);
+//     a blank entry IS sent, so collectFull warns about it. allPages with pages is sent as asked: collectFull
+//     refuses it, one guard for every caller (the CLI also refuses it while reading its arguments).
+//   - the refusal: a read option given as true to a scope whose row (read-opts.ts `scopes`) does not list it.
+//     Returned as the option names, not a message: each front-end words it in its own terms.
+//   - the budget: the scope's tier from TIMEOUTS, or the caller's override (the CLI's --timeout).
+//
+// Pure and side-effect free: figma-pull.ts and figma-mcp.ts import it at module level.
+import { READ_OPT_ROWS } from "./read-opts.ts";
+import { TIMEOUTS } from "./timeouts.ts";
+import { ifDefined } from "./json-util.ts";
+import type { ReadOptName, ReadOptRow, ReadScopeKind } from "./read-opts.ts";
+import type { Commands, ExportCmd } from "./commands.ts";
+
+export type { ReadScopeKind } from "./read-opts.ts";
+
+/** One read: a scope and what it needs to name its target. */
+export type ReadScope =
+  | { kind: "node"; nodeId: string }
+  | { kind: "selection" }
+  /** `pages` empty and `allPages` false: the current page. */
+  | { kind: "pages"; allPages: boolean; pages: readonly string[] }
+  | { kind: "designSystem" }
+  | { kind: "library"; name: string }
+  | { kind: "screenshot"; nodeId: string; scale?: number | undefined };
+
+/** Read options as a caller has them: true asks, false or absent does not. Extra keys are ignored. */
+export type ReadOptsGiven = Partial<Record<ReadOptName, boolean | undefined>>;
+
+/** What a read sends: the commands whose run traits say `export` (commands.ts). */
+export type ReadCmd = ExportCmd;
+export interface PlanOf<C extends ReadCmd> {
+  cmd: C;
+  args: Commands[C]["args"];
+  /** The request's budget in ms. */
+  timeout: number;
+  /** What is being read, for a log line ("node 1:2", "page(s) A, B", "design system only", …). */
+  label: string;
+}
+export type ReadPlan = { [C in ReadCmd]: PlanOf<C> }[ReadCmd];
+/** The read options given to a scope that does not take them, in registry order. */
+export interface ReadRefusal { refused: ReadOptName[]; scope: ReadScopeKind }
+
+/** The registry rows a scope takes, in registry order. */
+export function readOptsFor(kind: ReadScopeKind): ReadOptRow[] {
+  return READ_OPT_ROWS.filter((o) => o.scopes.includes(kind));
+}
+
+// The scope -> tier rule. A selection is small by construction; the whole file is the long walk; every other
+// read (one node, a page or a few, a catalog, one screenshot) is an export's.
+function tier(scope: ReadScope): number {
+  if (scope.kind === "selection") return TIMEOUTS.selection;
+  if (scope.kind === "pages" && scope.allPages) return TIMEOUTS.exportAll;
+  return TIMEOUTS.export;
+}
+
+function label(scope: ReadScope): string {
+  switch (scope.kind) {
+    case "node": return `node ${scope.nodeId}`;
+    case "selection": return "selection";
+    case "pages": return scope.allPages ? "all pages" : scope.pages.length ? `page(s) ${scope.pages.join(", ")}` : "current page";
+    case "designSystem": return "design system only";
+    case "library": return `library "${scope.name}"`;
+    case "screenshot": return `screenshot of ${scope.nodeId}`;
+  }
+}
+
+/** Every read option the scope takes, as a boolean, in registry order. */
+function optsFor(kind: ReadScopeKind, given: ReadOptsGiven): Partial<Record<ReadOptName, boolean>> {
+  const o: Partial<Record<ReadOptName, boolean>> = {};
+  for (const { name } of readOptsFor(kind)) o[name] = given[name] === true;
+  return o;
+}
+
+export function planRead(scope: Extract<ReadScope, { kind: "screenshot" }>, given?: ReadOptsGiven, o?: { timeoutMs?: number | undefined }): PlanOf<"screenshot"> | ReadRefusal;
+export function planRead(scope: ReadScope, given?: ReadOptsGiven, o?: { timeoutMs?: number | undefined }): ReadPlan | ReadRefusal;
+export function planRead(scope: ReadScope, given: ReadOptsGiven = {}, o: { timeoutMs?: number | undefined } = {}): ReadPlan | ReadRefusal {
+  const refused = READ_OPT_ROWS.filter((d) => given[d.name] === true && !d.scopes.includes(scope.kind)).map((d) => d.name);
+  if (refused.length) return { refused, scope: scope.kind };
+  const timeout = o.timeoutMs ?? tier(scope);
+  const at = { timeout, label: label(scope) };
+  const opts = optsFor(scope.kind, given);
+  switch (scope.kind) {
+    case "node": return { cmd: "exportNode", args: { nodeId: scope.nodeId, ...opts }, ...at };
+    case "selection": return { cmd: "exportSelection", args: opts, ...at };
+    case "pages": return { cmd: "exportFull", args: { allPages: scope.allPages, ...(scope.pages.length ? { page: [...scope.pages] } : {}), ...opts }, ...at };
+    case "designSystem": return { cmd: "exportDesignSystem", args: opts, ...at };
+    case "library": return { cmd: "exportLibrary", args: { asLibrary: scope.name, ...opts }, ...at };
+    // A screenshot's row set is empty, so `opts` is too: it renders a PNG and walks nothing.
+    case "screenshot": return { cmd: "screenshot", args: { nodeId: scope.nodeId, ...ifDefined("scale", scope.scale) }, ...at };
+  }
+}

package/src/read-run.ts

@@ -0,0 +1,119 @@
+// read-run.ts — one read, executed once: a read plan (read-plan.ts) sent through a route (route.ts), its progress
+// relayed, cancellable, timed, and its reply stamped with WHICH connected Figma file answered (source-stamp.ts) before
+// anything can write it out.
+//
+// Both front-ends ran this sequence themselves — the MCP server's pull() and the CLI's timed send plus timedWrite —
+// each with its own clock, its own reading of the plugin's progress ticks, and its own `stampSource(...)` call that
+// nothing made it remember. What is left to them is delivery: the CLI prints and writes (figma-pull.ts), the MCP server
+// decides inline / written / refused (delivery.ts) and turns ticks into progress notifications.
+//
+// The rules it owns:
+//   - the plan is sent as planned: its command, arguments and budget, to the target the caller names.
+//   - progress: every tick reaches the caller's onProgress and the meter; the first `queued` tick (the run waits behind
+//     another in that file) is said once through onQueued; tickMessage words a tick (MCP's progress message).
+//     A run that asks for none of these asks the route for no ticks at all.
+//   - the clock: durationMs().request is the time inside the request (the meter's sent/replied included), writeMs the time
+//     inside write(), and total the run so far. A tally, when given, adds both to the caller's running totals
+//     (the CLI's `done in …` line and its DTWIN_TIMINGS record).
+//   - the stamp: the reply a run hands out is already stamped — write() hands it to the writer, so a writer never
+//     sees an unstamped reply.
+import { stampSource } from "./source-stamp.ts";
+import type { Commands, Cmd } from "./commands.ts";
+import type { PlanOf, ReadCmd } from "./read-plan.ts";
+import type { Route, Sent } from "./route.ts";
+import type { ProgressTick } from "./server-core.ts";
+import type { Stamped } from "./write-out.ts";
+
+/** What hears a run's request, reply and ticks (timings.ts StageClock is one). */
+export interface ReadMeter {
+  sent(): void;
+  replied(reply: unknown): void;
+  tick(phase: string | null): void;
+}
+
+/** Running totals a run adds its time to. */
+export interface ReadTally { exportMs: number; writeMs: number }
+
+/** How a request is measured: the meter that hears it, the totals it adds to, the clock. */
+export interface Metering {
+  meter?: ReadMeter | null | undefined;
+  tally?: ReadTally | undefined;
+  now?: (() => number) | undefined;
+}
+
+export interface ReadRunOptions extends Metering {
+  /** which connected file (route.ts resolves it) */
+  target?: string | null | undefined;
+  signal?: AbortSignal | undefined;
+  /** every progress tick, as it arrives */
+  onProgress?: ((tick: ProgressTick) => void) | undefined;
+  /** once, at the first `queued` tick */
+  onQueued?: (() => void) | undefined;
+}
+
+/** One read, answered: its reply stamped with its source, and its clock. */
+export interface ReadRun<C extends ReadCmd> {
+  readonly reply: Stamped<Commands[C]["reply"]>;
+  /** Runs the write-out on the stamped reply, timed. */
+  write<W>(out: (reply: Stamped<Commands[C]["reply"]>) => W): W;
+  /** total since the run started, the request, the write (0 until written) */
+  durationMs(): { total: number; request: number; write: number };
+}
+
+/** One request, measured: the meter hears it sent and answered, and its time is added to the tally's exportMs —
+ *  a read's or any other command's (the CLI's index commands count toward the same line). */
+export async function meteredRequest<C extends Cmd>(request: () => Promise<Sent<C>>, m: Metering = {}): Promise<{ sent: Sent<C>; ms: number }> {
+  const now = m.now ?? Date.now;
+  const t = now();
+  m.meter?.sent();
+  let ms: number | undefined;
+  try {
+    const sent = await request();
+    m.meter?.replied(sent.reply);
+    ms = now() - t;
+    return { sent, ms };
+  } finally {
+    // a request that fails counts too, up to its failure
+    if (m.tally) m.tally.exportMs += ms ?? now() - t;
+  }
+}
+
+/** A tick, said: its phase, then where the walk is ("pages, page 2 of 3 (Home), 120 nodes, 4 assets"). */
+export function tickMessage(t: ProgressTick): string {
+  const parts = [t.phase ?? "export"];
+  if (t.page) parts.push(`page ${t.page.index} of ${t.page.of}${t.page.name ? ` (${t.page.name})` : ""}`);
+  if (t.nodes !== null) parts.push(`${t.nodes} nodes`);
+  if (t.assets !== null) parts.push(`${t.assets} assets`);
+  return parts.join(", ");
+}
+
+/** Runs `plan` through `route`. Rejects as the request does (a refusal, a timeout, a cancel). */
+export async function runRead<C extends ReadCmd>(route: Pick<Route, "request">, plan: PlanOf<C>, o: ReadRunOptions = {}): Promise<ReadRun<C>> {
+  const now = o.now ?? Date.now;
+  const t0 = now();
+  const { meter, onProgress, onQueued } = o;
+  let queued = false;
+  const onTick = meter || onProgress || onQueued
+    ? (tick: ProgressTick): void => {
+      meter?.tick(tick.phase);
+      if (tick.phase === "queued" && !queued) { queued = true; onQueued?.(); }
+      onProgress?.(tick);
+    }
+    : undefined;
+  const { sent, ms: requestMs } = await meteredRequest(
+    () => route.request(plan.cmd, plan.args, { timeoutMs: plan.timeout, target: o.target, onProgress: onTick, signal: o.signal }), o);
+  const reply = stampSource(sent);
+  let writeMs = 0;
+  return {
+    reply,
+    write(out) {
+      const t = now();
+      try { return out(reply); } finally {
+        const ms = now() - t;
+        writeMs += ms;
+        if (o.tally) o.tally.writeMs += ms;
+      }
+    },
+    durationMs: () => ({ total: now() - t0, request: requestMs, write: writeMs }),
+  };
+}