@design-twin/dtwin 0.0.0-stage → 0.1.0

package/src/settings.ts

@@ -0,0 +1,156 @@
+// settings.ts — what a bridge process is configured with, resolved ONCE at its entry (the dtwin CLI, the MCP
+// server, doctor) and passed down: into the bridge holder (bridge-holder.ts), the bridge itself (server-core.ts
+// createBridge), the daemon socket it serves or looks up (daemon.ts), and nothing else reads the environment for
+// these again. No load-time effects, and nothing here exits: a bad value is a result the entry decides about.
+//
+//   port         FIGMA_BRIDGE_PORT — one of the three the plugin can reach (ports.ts), else a problem.
+//   token        the effective bridge token and its source, by token-store.ts's precedence (--token-file >
+//                FIGMA_BRIDGE_TOKEN > the saved file > mint). Resolved without persisting: the bridge holder commits
+//                it (commitToken) once, before it first binds — a minted one is saved then, and the notice printed.
+//                A resolution that FAILS (an unreadable --token-file) is kept as that failure, not thrown: commands
+//                that never open a bridge (--token-status) still run, which is exactly when you want to diagnose
+//                it; the bridge or daemon that needs the token reports it.
+//   maxPayload   FIGMA_BRIDGE_MAX_PAYLOAD_MB — the per-frame cap (maxPayloadFromEnv).
+//   idleMs       FIGMA_DAEMON_IDLE_MIN — how long a shared bridge stays up with nothing using it (idleMsFromEnv).
+//   ephemeralPort  DT_TEST_EPHEMERAL_PORT=1 — the TEST SEAM: bind an ephemeral port instead of `port` (server-core).
+//   runtimeDir   XDG_RUNTIME_DIR — where the daemon socket lives when private (daemonAddressOf; daemon.ts never reads env).
+//
+// --token-file used to reach server-core by being written into process.env before a dynamic import, because the
+// token was resolved at that module's load. It is now an argument here.
+import * as tokenStore from "./token-store.ts";
+import type { ResolvedToken } from "./token-store.ts";
+import { parsePortEnv, portProblem } from "./ports.ts";
+import os from "node:os";
+import { daemonAddress } from "./daemon.ts";
+import type { DaemonAddress } from "./daemon.ts";
+
+/** The effective token, or why none could be resolved. */
+export type TokenSetting = { ok: true; resolved: ResolvedToken } | { ok: false; error: unknown };
+
+export interface MaxPayload { mb: number; bytes: number; warning?: string }
+
+export interface BridgeSettings {
+  readonly port: number;
+  readonly token: TokenSetting;
+  readonly maxPayload: MaxPayload;
+  readonly idleMs: number;
+  /** FIGMA_DAEMON_IDLE_MIN as given (undefined when unset), for a message that says why the window is off */
+  readonly idleRaw: string | undefined;
+  readonly ephemeralPort: boolean;
+  /** XDG_RUNTIME_DIR — where the daemon socket lives when it is private to this user (daemon.ts daemonAddress) */
+  readonly runtimeDir?: string | undefined;
+}
+
+export interface SettingsInput {
+  /** the environment to read (defaults to process.env). token-store itself reads FIGMA_BRIDGE_TOKEN and the saved
+   *  file's location from process.env, so only FIGMA_BRIDGE_TOKEN_FILE of the token's inputs comes from here. */
+  env?: NodeJS.ProcessEnv;
+  /** `--token-file` (wins over FIGMA_BRIDGE_TOKEN_FILE in `env`) */
+  tokenFile?: string | null;
+}
+
+export type SettingsResult = { ok: true; settings: BridgeSettings } | { ok: false; problem: string };
+
+/** Every setting, or the one problem that leaves a bridge here nothing to do (a port no plugin can reach). */
+export function readSettings({ env = process.env, tokenFile }: SettingsInput = {}): SettingsResult {
+  const p = parsePortEnv(env.FIGMA_BRIDGE_PORT);
+  if (p.port === undefined) return { ok: false, problem: portProblem(p.invalid) };
+  return {
+    ok: true,
+    settings: {
+      port: p.port,
+      token: tokenSetting({ env, ...(tokenFile !== undefined ? { tokenFile } : {}) }),
+      maxPayload: maxPayloadFromEnv(env.FIGMA_BRIDGE_MAX_PAYLOAD_MB),
+      idleMs: idleMsFromEnv(env),
+      idleRaw: env.FIGMA_DAEMON_IDLE_MIN,
+      ephemeralPort: env.DT_TEST_EPHEMERAL_PORT === "1",
+      runtimeDir: env.XDG_RUNTIME_DIR,
+    },
+  };
+}
+
+/** THE token resolution every caller goes through: `tokenFile` (the flag) or FIGMA_BRIDGE_TOKEN_FILE, then
+ *  token-store's precedence. Never persists, never throws. */
+export function tokenSetting({ env = process.env, tokenFile }: SettingsInput = {}): TokenSetting {
+  const file = tokenFile ?? (env.FIGMA_BRIDGE_TOKEN_FILE || null);
+  try {
+    return { ok: true, resolved: tokenStore.resolve({ tokenFile: file, persist: false }) };
+  } catch (e) {
+    return { ok: false, error: e };
+  }
+}
+
+/** What committing the settings' token on first use did (token-store.ts commit): the settings as every later bridge
+ *  and daemon lookup of this process should see them, and the lines to tell the user. */
+export interface TokenCommit {
+  readonly settings: BridgeSettings;
+  readonly minted: boolean;
+  readonly saveFailed: boolean;
+  readonly notice: readonly string[];
+}
+
+/** Commit the token before a bridge first uses it: save a minted one, and say which token is in play (printing it
+ *  only on the commit that mints it). A resolution that failed commits nothing — the bridge reports it. */
+export function commitToken(s: BridgeSettings): TokenCommit {
+  if (!s.token.ok) return { settings: s, minted: false, saveFailed: false, notice: [] };
+  const c = tokenStore.commit(s.token.resolved);
+  return { settings: { ...s, token: { ok: true, resolved: c.resolved } }, minted: c.minted, saveFailed: c.saveFailed, notice: c.notice };
+}
+
+/** The token a daemon's pipe is named from and its handshake keys on: the effective one — except a token nothing
+ *  saved yet (no daemon anyone could have started under it: a bridge commits the token it mints before it serves) and
+ *  a resolution that failed, both null. */
+export function daemonTokenOf(t: TokenSetting): string | null {
+  return t.ok && t.resolved.source !== "ephemeral" ? t.resolved.token : null;
+}
+
+/** What the daemon's address takes from the machine rather than the settings: the platform (win32 is a pipe), the
+ *  uid its socket directory must belong to, and the tmpdir that directory falls back under. */
+export interface Host {
+  readonly platform: NodeJS.Platform;
+  readonly uid: number | undefined;
+  readonly tmpdir: string;
+}
+export const thisHost = (): Host => ({ platform: process.platform, uid: process.getuid?.(), tmpdir: os.tmpdir() });
+
+/** Where this process's daemon is looked up or served (daemon.ts daemonAddress): at `port` (the settings' own unless
+ *  given — `dtwin --rotate-token` looks at all three), keyed on the token as these settings have it. Resolved once
+ *  per settings value: a token committed since (commitToken) is a new settings value, and a new address. */
+export function daemonAddressOf(s: BridgeSettings, port: number = s.port, host: Host = thisHost()): DaemonAddress {
+  return daemonAddress({ port, token: daemonTokenOf(s.token), ...host, runtimeDir: s.runtimeDir });
+}
+
+/** Does something other than the saved token file decide the token (FIGMA_BRIDGE_TOKEN or a token file)? Then
+ *  replacing or deleting the saved file changes nothing for a running bridge. */
+export function tokenOverridden(t: TokenSetting): boolean {
+  return t.ok ? t.resolved.source === "env" || t.resolved.source === "token-file" : true;
+}
+
+const DEFAULT_MAX_PAYLOAD_MB = 128;
+const MiB = 1024 * 1024;
+/** The bridge's per-frame cap from FIGMA_BRIDGE_MAX_PAYLOAD_MB. It bounds a single frame so a malformed/huge payload can't
+ *  OOM the process; 128 MB is ~2x a realistic asset-heavy full export, and an unusually large file can raise it. Bun.serve
+ *  takes it as `maxPayloadLength`, an unsigned 32-bit byte count, so a value past 4096 MB is clamped to just under 4 GiB
+ *  and `mb` says so (the too-big diagnosis quotes it — the cap in force, not the number typed).
+ *  A value that is not a finite number above 0 falls back to the default, with a `warning`: `ws` read 0 (and below) as
+ *  "unlimited", but Bun.serve has no unlimited — 0 there refuses every non-empty frame — and a typo must not become either one. */
+export function maxPayloadFromEnv(raw: string | undefined): MaxPayload {
+  const v = (raw ?? "").trim();
+  if (v === "") return { mb: DEFAULT_MAX_PAYLOAD_MB, bytes: DEFAULT_MAX_PAYLOAD_MB * MiB };
+  const n = Number(v);
+  if (!Number.isFinite(n) || n <= 0) {
+    return { mb: DEFAULT_MAX_PAYLOAD_MB, bytes: DEFAULT_MAX_PAYLOAD_MB * MiB, warning: `FIGMA_BRIDGE_MAX_PAYLOAD_MB=${JSON.stringify(raw)} is not a number of megabytes above 0 — using the default ${DEFAULT_MAX_PAYLOAD_MB} MB (there is no "unlimited")` };
+  }
+  const bytes = Math.max(1, Math.min(Math.floor(n * MiB), 0xffffffff));
+  return { mb: Math.round((bytes / MiB) * 100) / 100, bytes };
+}
+
+/** The idle window a shared bridge uses: FIGMA_DAEMON_IDLE_MIN minutes (default 120), in ms. 0 — and an unparsable
+ *  value, as it always was — disables the idle shutdown. */
+export function idleMsFromEnv(env: NodeJS.ProcessEnv = process.env): number {
+  return minutesToMs(env.FIGMA_DAEMON_IDLE_MIN ?? 120);
+}
+export const minutesToMs = (min: unknown): number => Math.max(0, Number(min)) * 60000 || 0;
+
+// The idle window for a log line (human-ms.ts, a leaf the served session imports directly).
+export { humanMs } from "./human-ms.ts";

package/src/source-stamp.ts

@@ -0,0 +1,16 @@
+// source-stamp.ts — which connected Figma file answered a read, stamped onto its reply.
+//
+// A screen export result has no field of its own naming its source file (unlike design-system.json / a
+// library catalog, which the plugin itself stamps), so the caller that knows WHICH client answered — the
+// bridge's request, or a daemon relaying it — stamps it here before the reply reaches
+// write-out.ts, which persists it onto the screen JSON and its index row. read-run.ts stamps every read the CLI and the MCP
+// server run, so both paths write the same field. Unstamped (never guessed) when no client was handed back
+// (a daemon too old to relay it) or the client has no file name yet.
+import type { Stamped } from "./write-out.ts";
+
+export function stampSource<R extends object>(sent: { reply: R; client: { file: string | null; fileKey: string | null } | null }): Stamped<R> {
+  const r: Stamped<R> = sent.reply;
+  const src = sent.client;
+  if (src && src.file) { r.sourceFile = src.file; if (src.fileKey) r.sourceFileKey = src.fileKey; }
+  return r;
+}

package/src/staleness.ts

@@ -0,0 +1,63 @@
+// staleness.ts — the plugin/daemon version-staleness notes, split out of server-core.ts so the CLI's
+// pure, test-driven helpers (figma-pull.ts formatClients) and doctor.ts use them without loading the bridge
+// itself. This module's only load-time effect is reading bridge/package.json for
+// BRIDGE_VERSION. Every caller, server-core.ts included, imports the three public names from here.
+import fs from "node:fs";
+
+// The plugin reports a version so that a stale bundle in Figma (several fixes live only in
+// figma-plugin/code.js — SVG normalisation, case-folded asset names) can be told apart from a fresh
+// one — a plugin instance's startedAt and code.js's own mtime can land in the same minute either way.
+// `BRIDGE_VERSION` is this PACKAGE's version (bridge/package.json — the CLI/MCP the user is actually
+// running); `pluginStalenessNote` compares it against whatever the connected plugin
+// announced in its `hello`. A simple numeric [major,minor,patch] compare, not semver ranges: this is an
+// internal tool with one version number moving in one repo, not a published dependency graph.
+export const BRIDGE_VERSION: string | null = (() => {
+  try {
+    return (JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }).version;
+  } catch (e) { return null; }
+})();
+type Version = [number, number, number];
+function parseVersion(v: unknown): Version | null {
+  if (typeof v !== "string") return null;
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function versionOlder(a: Version, b: Version): boolean {
+  const [aMajor, aMinor, aPatch] = a;
+  const [bMajor, bMinor, bPatch] = b;
+  if (aMajor !== bMajor) return aMajor < bMajor;
+  if (aMinor !== bMinor) return aMinor < bMinor;
+  if (aPatch !== bPatch) return aPatch < bPatch;
+  return false;
+}
+// `null` means "nothing to warn about" — the plugin reported a version, and it isn't older than this
+// CLI/MCP. Everything else IS worth a warn, including a MISSING version: a real daemon + a real Figma plugin
+// both running code from before version reporting would say nothing if the logic only compared two
+// REAL version strings (`list clients --json` would print `pluginVersion: null, pluginStale: null` for
+// both files) and treated "didn't report one" as "nothing to check," which is backwards: no version at
+// all is the ONE case we can be certain predates this feature, so it is unconditionally worth a
+// warning, not a silent pass.
+export function pluginStalenessNote(pluginVersion: unknown): string | null {
+  if (typeof pluginVersion !== "string" || !pluginVersion) {
+    return "plugin bundle predates version reporting (or the daemon was started before this bridge was updated) — " +
+      "re-run Plugins → Development → Design Twin in Figma and restart `dtwin serve`";
+  }
+  const p = parseVersion(pluginVersion), b = parseVersion(BRIDGE_VERSION);
+  if (!p || !b || !versionOlder(p, b)) return null;
+  return `plugin v${pluginVersion} is older than this ${BRIDGE_VERSION} bridge — reload the plugin in Figma (Plugins → Development → Design Twin) to pick up recent fixes`;
+}
+
+// Distinct from the above: this fires when the CLIENT ROW ITSELF has no `pluginVersion` KEY at all
+// (`"pluginVersion" in row` is false), which is not the same as the key being present and `null`.
+// `describe()` in server-core.ts always sets the key — to a string or explicitly to `null` — for any bridge
+// running this code, so a row with the key entirely absent can only have come from an OLDER daemon's
+// own older `describe()`, read back over its status socket by a NEWER `dtwin` CLI. That is a
+// second, independent kind of staleness this tool can detect: not just "the Figma plugin is old" but
+// "the long-running `dtwin serve` process itself predates this bridge version and needs restarting" —
+// which reloading the Figma plugin alone will not fix, since the daemon in front of it is what's stale.
+export function daemonRowStalenessNote(row: unknown): string | null {
+  if (row && typeof row === "object" && !("pluginVersion" in row)) {
+    return "the `dtwin serve` daemon in front of this connection predates plugin-version reporting — restart it (`dtwin serve --stop` then `dtwin serve`) to pick up recent fixes";
+  }
+  return null;
+}

package/src/stdio.ts

@@ -0,0 +1,156 @@
+// The queued console and the exit helpers every CLI entry point ends through — the dtwin CLI, the MCP server and the
+// daemon here, and every design-to-code CLI (design-to-code/proc.ts re-exports this module; bridge/src never imports
+// design-to-code, and the published `designtwin` package ships bridge/src alone, so it lives on this side).
+//
+// Bun (1.4.2, Linux too): console.* writes straight to the fd and DROPS what meets a full non-blocking pipe (a slow
+// reader: CI log shipper, `| less`, Claude Code reading a hook's output), and exit() drops whatever is still queued on a
+// pipe. So: console goes through the streams' queue, and a CLI ends on process.exitCode (the process exits once the queue
+// has drained) — or, when something still holds the loop, through exitFlushed. Never a bare process.exit after output.
+import { format, inspect } from "node:util";
+import type { InspectOptions } from "node:util";
+
+/** console.* through process.stdout/stderr.write: Bun's console writes straight to the fd and DROPS what meets a full
+ *  non-blocking pipe, while stream.write() queues it in order. End with process.exitCode (the process then exits once the
+ *  queue has drained), or after flushStdio() — never a bare exit, which drops the queue. Also counts the streams' writes
+ *  in flight, which flushStdio waits on. Idempotent. */
+export function installQueuedConsole(o: { logTo?: "stdout" | "stderr" } = {}): void {
+  trackWrites(process.stdout);
+  trackWrites(process.stderr);
+  // logTo "stderr": everything console prints goes to stderr — the MCP server, whose stdout carries nothing but the
+  // JSON-RPC its transport writes (a stray console.log there would corrupt the protocol stream).
+  const out = o.logTo === "stderr" ? process.stderr : process.stdout;
+  const err = process.stderr;
+  // console.group indentation, as the built-in console keeps it (two spaces per open group, on every line printed).
+  let indent = "";
+  const write = (s: NodeJS.WriteStream, text: string): void => { s.write((indent ? text.replace(/^/gm, indent) : text) + "\n"); };
+  const line = (s: NodeJS.WriteStream) => (...a: unknown[]): void => { write(s, format(...a)); };
+  console.log = console.info = console.debug = line(out);
+  console.warn = console.error = line(err);
+  // EVERY other console method that prints, so none of them reaches the fd past the queue — or the MCP server's stdout
+  // (test/cli-exit.test.ts holds this list to every method the runtime's console has).
+  // The text is close to the built-in's (inspect for dir, `Trace: …` + a stack for trace, `label: n` for count,
+  // `label: n.nnnms` for the timers), on the stream the built-in uses (stdout, or stderr for trace / assert / a timer
+  // warning); console.table prints its data inspected, not as a grid — nothing here tabulates, and a stray call must
+  // still never reach the fd past the queue, or the MCP server's stdout.
+  console.dir = (item?: unknown, options?: InspectOptions): void => { write(out, inspect(item, { customInspect: false, ...options })); };
+  console.dirxml = line(out);
+  console.table = (data?: unknown): void => { write(out, inspect(data)); };
+  // Bun's own: console.write(...data) is raw bytes to stdout, no newline, no format — returns the byte count.
+  console.write = (...data: Array<string | ArrayBufferView | ArrayBuffer>): number => {
+    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;
+  };
+  // Only a terminal is cleared (as the built-in does); never a pipe — least of all the MCP server's.
+  console.clear = (): void => { if (out.isTTY) out.write("\u001b[1;1H\u001b[0J"); };
+  console.trace = (...a: unknown[]): void => {
+    const e = new Error(format(...a));
+    e.name = "Trace"; // before the capture: the stack's first line is `Trace: <message>`, as the built-in prints
+    Error.captureStackTrace(e, console.trace);
+    write(err, e.stack ?? `Trace: ${e.message}`);
+  };
+  console.assert = (cond?: unknown, ...a: unknown[]): void => { if (!cond) write(err, a.length ? "Assertion failed: " + format(...a) : "Assertion failed"); };
+  console.group = console.groupCollapsed = (...a: unknown[]): void => { if (a.length) write(out, format(...a)); indent += "  "; };
+  console.groupEnd = (): void => { indent = indent.slice(0, -2); };
+  const counts = new Map<string, number>();
+  console.count = (label = "default"): void => { const n = (counts.get(label) ?? 0) + 1; counts.set(label, n); write(out, `${label}: ${n}`); };
+  console.countReset = (label = "default"): void => { counts.delete(label); };
+  const timers = new Map<string, number>();
+  const elapsed = (label: string): string | null => { const t = timers.get(label); return t === undefined ? null : `${label}: ${(performance.now() - t).toFixed(3)}ms`; };
+  console.time = (label = "default"): void => { timers.set(label, performance.now()); };
+  console.timeLog = (label = "default", ...a: unknown[]): void => { 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"): void => { const e = elapsed(label); timers.delete(label); write(e === null ? err : out, e ?? `Warning: No such label '${label}' for console.timeEnd()`); };
+}
+// How many non-empty writes each stream has not yet handed to the OS, and who waits for that to reach 0. Bun (1.4.2) keeps
+// no usable writableLength (0 while 400 KB are queued) and calls back an EMPTY write at once, before what was queued ahead of
+// it is out; a non-empty write's callback does come once its bytes are written, in order. So every write is counted (the
+// stream's write wrapped once) and the count says when the queue is empty.
+const inFlight = new Map<NodeJS.WriteStream, { n: number; idle: Array<() => void> }>();
+function trackWrites(s: NodeJS.WriteStream): void {
+  if (inFlight.has(s)) return;
+  const st = { n: 0, idle: [] as Array<() => void> };
+  inFlight.set(s, st);
+  const write = s.write.bind(s) as (chunk: string | Uint8Array, encoding?: BufferEncoding, cb?: (err?: Error | null) => void) => boolean;
+  const settle = (): void => { if (--st.n === 0) for (const r of st.idle.splice(0)) r(); };
+  s.write = (chunk: string | Uint8Array, encoding?: BufferEncoding | ((err?: Error | null) => void), cb?: (err?: Error | null) => void): boolean => {
+    const done = typeof encoding === "function" ? encoding : cb;
+    const enc = typeof encoding === "function" ? undefined : encoding;
+    if (chunk.length === 0) return write(chunk, enc, done);
+    st.n++;
+    let called = false;
+    return write(chunk, enc, (err?: Error | null) => { if (!called) { called = true; settle(); } done?.(err); });
+  };
+}
+/** Resolves once every write made through installQueuedConsole's streams has been handed to the OS (at once when there is
+ *  none in flight, or the streams are not tracked). */
+export const flushStdio = (): Promise<void> => Promise.all([process.stdout, process.stderr].map((s) => new Promise<void>((r) => {
+  const st = inFlight.get(s);
+  if (!st || st.n === 0) r(); else st.idle.push(r);
+}))).then(() => undefined);
+
+// ---- ending a CLI without losing its output
+// Every CLI entry point (dtwin, seed-components, each design-to-code CLI) runs its main() through runCli: console goes through the queued streams, and the exit
+// code is process.exitCode — the process ends once the queue has drained, never with a bare exit call that drops it
+// (Bun loses what is still queued on a pipe at exit(): a 300 KB report into a slow reader arrived as its first 64 KB).
+// The few library helpers that must end the CLI mid-call (cli-args.ts cliParse, catalog-input.ts's fail-loud readers)
+// call exitCli(): inside runCli it throws CliExit, which unwinds to runCli and becomes the exit code; anywhere else (a
+// suite calling main() in-process, the MCP server importing a module) it exits the process at once, as before.
+// "Inside" is until main() SETTLES: a long-lived server is not a CLI run. `dtwin mcp` awaits the MCP server's module (so
+// an exitCli while it LOADS is still that CLI's exit code, its line out first), starts it (runServer), then returns; from there the server runs exactly as `bun figma-mcp.ts` does, where an exitCli exits at once.
+// One rule for both launches — the server never depends on how it was started.
+/** What exitCli throws inside runCli. Not an error: runCli turns it into the exit code, silently. */
+export class CliExit extends Error {
+  readonly code: number;
+  constructor(code: number) { super(`exit ${code}`); this.name = "CliExit"; this.code = code; }
+}
+let cliDepth = 0;
+/** End the CLI with `code` after what it already printed (see above). Never returns. */
+export function exitCli(code: number): never {
+  if (cliDepth > 0) throw new CliExit(code);
+  process.exit(code);
+}
+export interface RunCliOpts {
+  /** The prefix of an uncaught error's line on stderr (`<name>: <stack>`). */
+  name: string;
+  /** An uncaught error's line on stderr instead (e.g. its message without the stack). */
+  errorLine?: (e: unknown) => string;
+  /** An uncaught error's exit code, after its line (default 1; verifier-guard fails open: 0). */
+  errorCode?: number;
+  /** What to do with the exit code (default: process.exitCode = code). */
+  done?: (code: number) => void;
+}
+/** Run a CLI's main(argv) as the process entry: queued console, exitCli honoured, an uncaught error one line + exit 1. */
+export function runCli(main: (argv: string[]) => number | Promise<number>, o: RunCliOpts, argv: string[] = process.argv.slice(2)): void {
+  installQueuedConsole();
+  const done = o.done ?? ((code: number): void => { process.exitCode = code; });
+  const fail = (e: unknown): void => {
+    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);
+  };
+  // Inside main() — and only until it settles — exitCli throws CliExit (see above). Back to 0 once it has, so whatever
+  // outlives a CLI's main (a server it started, a timer) sees exitCli as it would outside any CLI: an immediate exit.
+  cliDepth++;
+  let settled = false;
+  const leave = (): void => { if (!settled) { settled = true; cliDepth--; } };
+  try {
+    const r = main(argv);
+    if (typeof r === "number") { leave(); done(r); } else r.then((c) => { leave(); done(c); }, (e: unknown) => { leave(); fail(e); });
+  } catch (e) { leave(); fail(e); }
+}
+/** Whether exitCli would throw CliExit here (inside a runCli main that has not settled) rather than exit. For the suites. */
+export const insideCli = (): boolean => cliDepth > 0;
+/** Exit with `code` once everything written to stdout and stderr is out (flushStdio) — or after `capMs` when a reader never
+ *  drains them. For a process that has to end while something still holds the loop (a hung step's watchdog, a browser that
+ *  will not go). Needs installQueuedConsole (runCli calls it) to know what is in flight.
+ *  The cap bounds QUEUED writes (POSIX, where a write to a pipe is queued). On Windows Bun makes stdout/stderr on a pipe
+ *  synchronous (as Node does there): a write into a full pipe blocks the thread until the reader takes it, so nothing is
+ *  ever left in flight here — and a reader that never reads holds the process in that write, as it would any program. */
+export function exitFlushed(code: number, capMs = 2_000): void {
+  const exit = (): never => process.exit(code);
+  setTimeout(exit, capMs).unref(); // a pending write keeps the loop up, so this still fires
+  void flushStdio().then(exit);
+}

package/src/svg-normalize.ts

@@ -0,0 +1,205 @@
+// svg-normalize.ts — the definitions of "same SVG, modulo Figma's export noise". There are TWO, on purpose:
+//
+// Figma's own SVG export is not bit-reproducible: re-exporting the SAME icon, with NOTHING changed in
+// the design, comes back with different floating-point path coordinates (measured ≤0.004px drift —
+// d="…8.77734…4.97401…" vs d="…8.7793 …4.97596…" for one icon exported twice), and with def ids that
+// embed the exporting node's id (`clip0_22012_15691` vs `clip0_22012_24907` for one icon reached through
+// two instances).
+//
+//   1. `normalizeSvgText` (v1, below): round every decimal to 1 place, then hash the text. Used by the
+//      plugin's per-run content hash (figma-plugin/src/assets.ts register(), re-exported crypto-free
+//      from figma-plugin/src/util.ts) and by the change diff (design-to-code/design-diff.ts
+//      hashAssetBytes(), via bridge/src/asset-compare.ts). It stays EXACTLY as it is: design-diff
+//      persists these hashes in snapshot sidecars, so any change to v1 would report every SVG with
+//      defs as "redrawn" against every snapshot already on disk.
+//   2. `svgFingerprint` / `sameSvg` (below v1): a skeleton plus every number, compared within an
+//      absolute tolerance. Used by the bridge's shared assets/ directory — the content reuse in
+//      bridge/src/write-out.ts writeAssets() and its `duplicates` report, via asset-compare.ts
+//      ContentIndex. It closes the three gaps v1 has on real exports: def ids, integer
+//      tokens (`12` vs `11.9999`, which v1's decimal-only regex never touches) and the rounding
+//      boundary (21.9485 → 21.9 but 21.9504 → 22.0: two exports 0.002 apart hash differently).
+//
+// The plugin bundle inlines THIS file, so it stays dependency-free and crypto-free: the byte/hash
+// helpers live in asset-compare.ts, because `node:crypto` does not exist in the plugin's sandbox and
+// this file must also type-check under the plugin's tsconfig, which has no Node types — an
+// `import … from "node:crypto"` ANYWHERE in this file would break the plugin build even if the plugin
+// bundle never calls that function.
+//
+// ---- v1
+// Rounding to 1 decimal place (~0.1px), not 2 (~0.01px): 2 decimals do NOT reliably collapse the
+// drift, because two legitimately identical re-exports can straddle a rounding boundary — 4.97401
+// rounds to 4.97 but 4.97596 (0.00195 away, well inside the ≤0.002px drift budget) rounds to 4.98, so
+// the "same" icon split into two hashes anyway. Checked against eight real exports of one icon
+// (test/fixtures/livetest3/arrow-down/): 1 decimal place is the coarsest rounding that does NOT itself
+// introduce a boundary split on this data, and it still separates the three genuinely different icons
+// among those eight files — two orders of magnitude below anything a human would call "moved".
+// Matches BOTH plain decimals (`-0.000406265`) and scientific notation (`2.09808e-05`) — Figma emits
+// both for a coordinate near zero, sometimes for the SAME logical value across two exports of one
+// icon. The regex must not stop at the decimal mantissa (`-?\d+\.\d+`): `2.09808e-05` would have only
+// its `2.09808` replaced, leaving the exponent dangling as `2.1e-05` — a corrupted leftover that could
+// never match the plain-decimal form's `0.0`, and the icon would fail to dedup even though every other
+// coordinate matched. A real pull showed this: five files for what should have been two (an up/down pair).
+const NUM_RE = /-?\d+\.\d+(?:[eE][+-]?\d+)?/g;
+export function normalizeSvgText(svg: string): string {
+  return svg.replace(NUM_RE, (m) => {
+    const n = Number(m);
+    if (!Number.isFinite(n)) return m;
+    // toFixed can print "-0.0" for a tiny negative value that rounds to zero — a plain "0.0" and a
+    // "-0.0" are the same design value and must normalise identically, or they poison dedup the same
+    // way the scientific-notation bug above did.
+    const fixed = n.toFixed(1);
+    return fixed === "-0.0" ? "0.0" : fixed;
+  });
+}
+
+// `fileName` decides whether normalisation even applies: only a textual SVG has a coordinate space to
+// round. PNG/other bytes are never touched — a changed pixel there is real signal, not noise.
+export function isSvgName(fileName: unknown): boolean {
+  return /\.svg$/i.test(String(fileName || ""));
+}
+
+// ---- the fingerprint (bridge only — see the header for why v1 is not changed instead)
+//
+// The skeleton is the SVG text with (1) every id DEFINED in the document renamed `idN` in order of first
+// definition, together with every `#X` reference to it (`url(#X)`, `href="#X"`, `xlink:href="#X"`) —
+// generic, so it covers any id shape Figma emits, not only the clip/pattern/image ids seen so far; (2)
+// hex colours and `base64,` payloads kept verbatim (a colour is a token, not a coordinate, and a changed
+// pixel in an embedded image is real signal); and (3) every other numeric token, integers included,
+// replaced by `#`, its value pushed to `nums`. Two exports of one icon have equal skeletons and nums
+// within SVG_TOL of each other.
+//
+// SVG_TOL = 0.01, absolute. On the three real export directories every tolerance from 0.005 to 0.05
+// merges the same files; the largest real drift inside a merged group is 0.004 and the closest real
+// pair that is genuinely different is 0.3 apart (a stroke width, 1.5 vs 1.2). 0.01 is 2.5x the drift,
+// far below any visible change, and does not merge opacity steps (0.5 vs 0.54) the way 0.05 would.
+// "Within" is inclusive up to float noise (TOL_EPS): 0.11 vs 0.12 and 0.5 vs 0.51 are both exactly one
+// step apart, but their float differences land on either side of 0.01.
+//
+// One exception: a number inside the `transform` of a `<use>` or `<image>` is in the space of the
+// element it fills — for Figma's raster shells, `<pattern patternContentUnits="objectBoundingBox"><use
+// transform="matrix(0.00195312 0 0 0.00195312 0 0)">`, where the whole box is 1 unit. 0.01 there is a
+// 4.5x zoom of the same photo (scale 1/512 vs 1/113). The `<pattern>`'s own x/y/width/height (and
+// patternTransform) are box fractions too, unless patternUnits="userSpaceOnUse" (a tile size).
+// Those numbers go to `rel` (a `%` in the skeleton)
+// and compare RELATIVELY: within SVG_TOL of the larger magnitude, never looser than the absolute rule.
+// Path and box coordinates keep the absolute tolerance — their near-zero drift (2.09808e-05 vs
+// -0.000406265, one real chevron) is noise, not a different drawing.
+export const SVG_TOL = 0.01;
+const TOL_EPS = 1e-9;
+
+export interface SvgFingerprint {
+  /** the text with ids canonicalised and every number replaced by `#` */
+  skeleton: string;
+  /** every number the skeleton replaced with `#`, in document order */
+  nums: Float64Array;
+  /** every number inside a `<use>`/`<image>` `transform` or a `<pattern>`'s own x/y/width/height/patternTransform
+   *  (a `%` in the skeleton), compared relatively */
+  rel: Float64Array;
+}
+
+const ID_DEF_RE = /(?<![\w:-])id\s*=\s*(["'])(.*?)\1/g;
+// One pass over the text with the protected spans first in the alternation, so a protected span is
+// consumed whole and its digits never reach the number branch: a canonical id marker, a hex colour of
+// 3/4/6/8 digits not followed by another name character (so `#clip0` or `#12345` are not colours), a
+// base64 payload, then the number itself — `-?(\d+\.?\d*|\.\d+)` with an optional exponent.
+const ID_MARK = "\u0000";
+const TOKEN_RE = /(\u0000id\d+\u0000)|(#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})(?![\w-]))|(base64,[A-Za-z0-9+/=]+)|(-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)/g;
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+function canonicalIds(svg: string): string {
+  const order = new Map<string, string>(); // defined id -> its canonical marker, in order of first definition
+  // exec, not matchAll: the plugin's tsconfig is es2019 (no String.prototype.matchAll).
+  ID_DEF_RE.lastIndex = 0;
+  for (let m = ID_DEF_RE.exec(svg); m; m = ID_DEF_RE.exec(svg)) {
+    const id = m[2];
+    if (id && !order.has(id)) order.set(id, ID_MARK + "id" + order.size + ID_MARK);
+  }
+  if (!order.size) return svg;
+  // Longest first, so an id that is a prefix of another (`a` / `a1`) never claims the longer one's text.
+  const alts = [...order.keys()].sort((x, y) => y.length - x.length).map(escapeRe).join("|");
+  const re = new RegExp("(?<![\\w:-])(id\\s*=\\s*[\"'])(" + alts + ")(?=[\"'])|#(" + alts + ")(?![\\w.:-])", "g");
+  return svg.replace(re, (m: string, attr: string | undefined, defined: string | undefined, ref: string | undefined) => {
+    if (attr !== undefined && defined !== undefined) return attr + (order.get(defined) ?? defined);
+    if (ref !== undefined) return "#" + (order.get(ref) ?? ref);
+    return m;
+  });
+}
+
+// The value spans compared relatively: `transform` on `<use>`/`<image>` tags, and a `<pattern>`'s own
+// x/y/width/height/patternTransform. A tag's attributes never contain `>` (a base64 payload has none),
+// so `[^>]*` stays inside the tag.
+const REL_TAG_RE = /<(?:use|image|pattern)\b[^>]*>/g;
+const TRANSFORM_ATTR_RE = /(?<![\w:-])transform\s*=\s*(["'])([^"']*)\1/g;
+// A <pattern>'s own box is a fraction of the filled shape (patternUnits defaults to objectBoundingBox): a
+// TILE fill of 0.05 vs 0.0588 is 20 vs 17 tiles across. With patternUnits="userSpaceOnUse" they are user
+// units, compared absolutely like any other number.
+const PATTERN_ATTR_RE = /(?<![\w:-])(?:x|y|width|height|patternTransform)\s*=\s*(["'])([^"']*)\1/g;
+function relSpans(svg: string): Array<[number, number]> {
+  const spans: Array<[number, number]> = [];
+  REL_TAG_RE.lastIndex = 0;
+  for (let t = REL_TAG_RE.exec(svg); t; t = REL_TAG_RE.exec(svg)) {
+    const re = t[0].startsWith("<pattern") ? (/patternUnits\s*=\s*["']userSpaceOnUse/.test(t[0]) ? null : PATTERN_ATTR_RE) : TRANSFORM_ATTR_RE;
+    if (!re) continue;
+    re.lastIndex = 0;
+    for (let a = re.exec(t[0]); a; a = re.exec(t[0])) {
+      const start = t.index + a.index + a[0].length - 1 - (a[2] || "").length;
+      spans.push([start, start + (a[2] || "").length]);
+    }
+  }
+  return spans;
+}
+
+export function svgFingerprint(svg: string): SvgFingerprint {
+  const nums: number[] = [];
+  const rel: number[] = [];
+  const text = canonicalIds(svg);
+  const spans = relSpans(text);
+  const inRel = (at: number): boolean => spans.some(([s, e]) => at >= s && at < e);
+  const skeleton = text.replace(TOKEN_RE, (m: string, _id: string | undefined, _hex: string | undefined, _b64: string | undefined, num: string | undefined, at: number) => {
+    if (num === undefined) return m;
+    if (spans.length && inRel(at)) { rel.push(Number(num)); return "%"; }
+    nums.push(Number(num));
+    return "#";
+  });
+  return { skeleton, nums: Float64Array.from(nums), rel: Float64Array.from(rel) };
+}
+
+/** Every number within `tol` of its counterpart (and as many of them). Exact equality also counts, so two
+ *  infinities from an overflowing token compare equal rather than NaN-unequal. */
+export function numsWithin(a: Float64Array, b: Float64Array, tol: number = SVG_TOL): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i] as number, y = b[i] as number;
+    if (x !== y && !(Math.abs(x - y) <= tol + TOL_EPS)) return false;
+  }
+  return true;
+}
+
+/** The `rel` half: every number within `tol` × the larger magnitude of the pair, and never more than
+ *  `tol` apart — so a big number keeps the absolute rule and a tiny one is compared to its own scale. */
+export function relWithin(a: Float64Array, b: Float64Array, tol: number = SVG_TOL): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i] as number, y = b[i] as number;
+    if (x !== y && !(Math.abs(x - y) <= Math.min(tol, tol * Math.max(Math.abs(x), Math.abs(y))) + TOL_EPS)) return false;
+  }
+  return true;
+}
+
+/** The bridge's "same SVG": equal skeletons, every number within `tol`, every `rel` number relatively so. */
+export function sameSvg(a: string, b: string, tol: number = SVG_TOL): boolean {
+  const fa = svgFingerprint(a), fb = svgFingerprint(b);
+  return fa.skeleton === fb.skeleton && numsWithin(fa.nums, fb.nums, tol) && relWithin(fa.rel, fb.rel, tol);
+}
+
+// ---- a raster image in an SVG shell
+//
+// An SVG with an embedded `<image>` and almost no paths is a PHOTO in an SVG shell (an avatar exported as an
+// icon-like container: 2 paths and a 1.98 MB base64 JPEG). The "thousands of vector paths" advice is wrong
+// for it: there is nothing to simplify, and a PNG/JPG export of the layer is the fix. ONE rule for the
+// bridge's pull warning (write-out.ts) and the audit's heavy-asset finding (design-to-code/audit.ts):
+// an illustration with 2000 paths and one `<image>` is still "too many paths", in both.
+export const RASTER_SHELL_MAX_PATHS = 50;
+export function isRasterShell(rasters: number | undefined, paths: number | undefined): boolean {
+  return (rasters ?? 0) > 0 && (paths ?? 0) < RASTER_SHELL_MAX_PATHS;
+}