@design-twin/dtwin 0.0.0-stage → 0.1.0-alpha.0

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@design-twin/dtwin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.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",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "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();

package/src/asset-owners.ts

@@ -0,0 +1,280 @@
+// asset-owners.ts — who owns an exported graphic, and which hidden graphic can reuse a visible twin's file.
+//
+// Pure: plain IR trees in, plain answers out (no fs) — write-out.ts does the reading and writing, so every
+// rule here is testable offline on hand-built trees.
+//
+// 1. Owners. An asset file is named after its layer, and a layer is very often called
+//    `Vector`, `Icon` or `Group_N`. What it IS lives on the nearest component instance above it (or on the
+//    node itself): `Checkbox / Status=Checked`. One walk gives every `asset` pointer its uses — node id,
+//    layer name, hidden or not, owner, the instance above the owner (`context`, which names a self-owned
+//    icon component such as `Glyph 12` inside `Nav item / Type=Settings`) — and the `.assets.json`
+//    row carries them, so a builder searches by component instead of by file name. File names never change.
+//
+// 2. Hidden reuse. The plugin does not export a hidden graphic (`assetSkipped:"hidden"`): its
+//    exporter has nothing to render. When a VISIBLE node in the same pull (or in another screen already
+//    pulled) is the same graphic — the same main component, the same source node inside it, the same
+//    chain of components and variants above the owner, the same non-boolean props, the same effective
+//    variable modes, the same size and transform, and no paint override (nor a shape/visibility override
+//    on a sublayer of the graphic) on either side — the hidden
+//    node points at that file instead (`asset` + `assetFrom`). An owner's booleans are left out of the key
+//    because they are the visibility toggles that hid the node; a SELF-owned icon's own booleans are its
+//    internal toggles (`Show badge`), so they stay in. Variant props are covered by the main
+//    component id. The modes are in because a bound colour renders per mode.
+//    The chain is in the key because a parent variant may recolour a nested icon in its own DEFINITION
+//    (`Button / Type=Danger` drawing its icon red), and Figma's `overrides` list only what is overridden
+//    directly on an instance, never what it inherits — so no override would block that twin.
+import type { InstanceOverride, IrNode } from "./doc-types.ts";
+import { OVERRIDE_CAP } from "./instance-overrides.ts";
+
+/** The nearest INSTANCE ancestor-or-self that names its main component. */
+export interface AssetOwner {
+  /** the component set's name, else the component's own */
+  component: string;
+  variant?: string;
+  componentId?: string;
+  componentKey?: string;
+  /** the owning instance's node id */
+  instance: string;
+  /** the node IS the owning instance (a self-owned icon component) */
+  self: boolean;
+  /** a paint override, a shape/visibility override on a sublayer (or a truncated override list) on this
+   *  use — never reused across, either way */
+  paintOverrides?: true;
+}
+/** The next INSTANCE above the owner. */
+export interface AssetContext { component: string; variant?: string }
+
+/** One node in a tree that holds an exported graphic (`asset`) or a hidden one that was not (`assetSkipped:"hidden"`). */
+export interface Graphic {
+  node: IrNode;
+  /** the node or an ancestor is hidden */
+  hidden: boolean;
+  owner?: AssetOwner;
+  context?: AssetContext;
+  /** see reuseKeyOf; absent without an owner that names a component id or key */
+  reuseKey?: string;
+  /** a paint override, a sublayer shape/visibility override or a truncated override list blocks reuse */
+  blocked: boolean;
+}
+
+// Figma's overriddenFields that change how a graphic LOOKS. Anything else (a text, a swapped instance's
+// visibility, a name) leaves the exported pixels of an icon alone.
+const PAINT_FIELD_RE = /^(?:fills|strokes|strokeWeight|sto?ke\w*Weight|opacity|effects|effectStyleId|blendMode|fillStyleId|strokeStyleId|boundVariables|explicitVariableModes|vectorNetwork)$/;
+// On a SUBLAYER of the graphic (inside the exported file), any field but these changes the drawing: a
+// `visible` override drops a layer, a size/corner/transform one reshapes it.
+const INERT_SUBLAYER_FIELD_RE = /^(?:name|locked|pluginData|reactions|description|exportSettings|expanded|autoRename|hyperlink|characters|styledTextSegments|textStyleId|fontName)$/;
+
+const lastSegment = (id: string): string => { const i = id.lastIndexOf(";"); return i >= 0 ? id.slice(i + 1) : id; };
+const isOwnerInstance = (n: IrNode): boolean => n.type === "INSTANCE" && !!n.mainComponent;
+const overridesOf = (n: IrNode): readonly InstanceOverride[] => (Array.isArray(n.overrides) ? n.overrides : []);
+// The plugin cuts the list at OVERRIDE_CAP (and warns): at that length, what was cut is unknown.
+const truncated = (n: IrNode): boolean => overridesOf(n).length >= OVERRIDE_CAP;
+const paintEntry = (o: InstanceOverride): boolean => !!o && Array.isArray(o.fields) && o.fields.some((f) => typeof f === "string" && PAINT_FIELD_RE.test(f));
+
+// (iii) of the reuse guard. On every instance from the root down to the graphic, a paint entry ABOUT the
+// graphic or one of its sublayers counts (a sublayer id is `<id>;…`, or `I<id>;…` under a top-level
+// instance): an outer instance records a recolour of a nested vector on ITS own `overrides`, not on the
+// vector's owner. For a graphic that is not itself an instance, each paint entry on its owner counts
+// as well — the override's target cannot always be tied to the node more precisely than that from the tree.
+// On a STRICT sublayer (`<id>;…`, inside the exported file) any field but an inert one blocks: a `visible`
+// override drops a layer, a size/corner one reshapes it. The graphic's own `visible` is what hid it.
+// A truncated list on any of those instances blocks too: what was cut is unknown.
+function hasPaintOverride(node: IrNode, instances: readonly IrNode[], owner: IrNode | undefined): boolean {
+  const id = typeof node.id === "string" ? node.id : "";
+  const prefixes = [id + ";", "I" + id + ";"];
+  const about = (o: InstanceOverride): boolean => !!o && typeof o.id === "string" && (o.id === id || prefixes.some((p) => o.id.startsWith(p)));
+  const sub = (o: InstanceOverride): boolean => !!o && typeof o.id === "string" && o.id !== id && prefixes.some((p) => o.id.startsWith(p));
+  const reshapes = (o: InstanceOverride): boolean => Array.isArray(o.fields) && o.fields.some((f) => typeof f === "string" && !INERT_SUBLAYER_FIELD_RE.test(f));
+  if (instances.some((inst) => truncated(inst) || overridesOf(inst).some((o) => (about(o) && paintEntry(o)) || (sub(o) && reshapes(o))))) return true;
+  if (node.type === "INSTANCE" || !owner) return false;
+  return overridesOf(owner).some(paintEntry);
+}
+
+const sortedProps = (n: IrNode, booleans: boolean): Array<[string, unknown]> => {
+  const props = n.props && typeof n.props === "object" ? Object.entries(n.props) : [];
+  return props.filter(([, v]) => booleans || typeof v !== "boolean").sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+};
+
+/** `<componentKey||componentId>|<self|last id segment>|<sorted props JSON>|<chain JSON>[|<modes JSON>]`, or
+ *  undefined. The props drop booleans unless the node IS the owner; `modes` is the effective
+ *  `[collection, mode]` list, sorted (collectGraphics), left off when empty. `chain` is the main component (key, else id — which names the variant; `?` when unnamed) of
+ *  every INSTANCE above the owner, outermost first: `instances` is the root-down list of instances above
+ *  `node` (the owner included, when it is an ancestor). The whole chain, not only the next instance up: an
+ *  outer component's definition can recolour the nested icon just as the parent variant's can.
+ *  Not in the key: WHERE in the parent the owner sits. The full id path would keep a leading and a trailing
+ *  icon of one button variant apart, but on the real exports it refused every same-screen reuse — list
+ *  rows inside an instance carry document ids in that path, different per row for the very same icon. */
+export function reuseKeyOf(node: IrNode, owner: IrNode | undefined, instances: readonly IrNode[] = [], modes = ""): string | undefined {
+  const mc = owner && owner.mainComponent;
+  const comp = mc && (mc.key || mc.id);
+  if (!owner || !comp || typeof node.id !== "string") return undefined;
+  const at = instances.indexOf(owner);
+  const above = at >= 0 ? instances.slice(0, at) : instances.filter((i) => i !== owner);
+  const chain = above.map((i) => (i.mainComponent && (i.mainComponent.key || i.mainComponent.id)) || "?");
+  return comp + "|" + (node === owner ? "self" : lastSegment(node.id)) + "|" + JSON.stringify(sortedProps(owner, node === owner)) + "|" + JSON.stringify(chain) + (modes ? "|" + modes : "");
+}
+
+function ownerRef(inst: IrNode, node: IrNode, blocked: boolean): AssetOwner | undefined {
+  const mc = inst.mainComponent;
+  if (!mc) return undefined;
+  const o: AssetOwner = { component: mc.setName ?? mc.name, instance: inst.id, self: inst === node };
+  if (mc.variant) o.variant = mc.variant;
+  if (mc.id) o.componentId = mc.id;
+  if (mc.key) o.componentKey = mc.key;
+  if (blocked) o.paintOverrides = true;
+  return o;
+}
+
+/** Every graphic node (`asset` string, or `assetSkipped:"hidden"`) in tree order, with its owner and reuse key. */
+export function collectGraphics(roots: readonly IrNode[] | null | undefined): Graphic[] {
+  const out: Graphic[] = [];
+  // instances: every INSTANCE from the root down (paint-override scope); owners: the ones naming a main component.
+  // modes: the effective variable mode per collection (the root's resolvedModes, then every variableModes
+  // pinned on the way down) — a bound colour renders per mode, so a Dark section never reuses a Light file.
+  const visit = (n: IrNode, instances: readonly IrNode[], owners: readonly IrNode[], hiddenAbove: boolean, modesAbove: ReadonlyMap<string, string>): void => {
+    if (!n || typeof n !== "object") return;
+    let modes = modesAbove;
+    for (const pinned of [n.resolvedModes, n.variableModes]) {
+      if (!pinned || typeof pinned !== "object") continue;
+      const next = new Map(modes);
+      for (const [c, m] of Object.entries(pinned)) if (typeof m === "string") next.set(c, m);
+      modes = next;
+    }
+    const insts = n.type === "INSTANCE" ? [...instances, n] : instances;
+    const owns = isOwnerInstance(n) ? [...owners, n] : owners;
+    const hidden = hiddenAbove || n.hidden === true;
+    if (typeof n.asset === "string" || n.assetSkipped === "hidden") {
+      const owner = owns[owns.length - 1];
+      const above = owns[owns.length - 2];
+      const blocked = hasPaintOverride(n, insts, owner);
+      const g: Graphic = { node: n, hidden, blocked };
+      const o = owner && ownerRef(owner, n, blocked);
+      if (o) g.owner = o;
+      const ac = above && above.mainComponent;
+      if (ac) g.context = ac.variant ? { component: ac.setName ?? ac.name, variant: ac.variant } : { component: ac.setName ?? ac.name };
+      const mk = [...modes].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+      const key = reuseKeyOf(n, owner, insts, mk.length ? JSON.stringify(mk) : "");
+      if (key !== undefined) g.reuseKey = key;
+      out.push(g);
+    }
+    // An unrelated screen's JSON on disk may be malformed (`children: {}`): skipped, never a throw.
+    if (Array.isArray(n.children)) for (const c of n.children) visit(c, insts, owns, hidden, modes);
+  };
+  for (const r of roots || []) visit(r, [], [], false, new Map());
+  return out;
+}
+
+/** pointer (`assets/<name>`) → its uses in tree order. */
+export function usesByPointer(graphics: readonly Graphic[]): Map<string, Graphic[]> {
+  const map = new Map<string, Graphic[]>();
+  for (const g of graphics) {
+    const p = g.node.asset;
+    if (typeof p !== "string") continue;
+    let list = map.get(p);
+    if (!list) { list = []; map.set(p, list); }
+    list.push(g);
+  }
+  return map;
+}
+
+// (ii): the transform Figma drew into the file. A visible asset leaf carries it as `sourceTransform`; an older
+// export, and the hidden node before reuse, carry it bare.
+function transformOf(n: IrNode): { rotation: number; flipped: boolean; skew: number } {
+  const t = n.sourceTransform;
+  return t
+    ? { rotation: t.rotation ?? 0, flipped: t.flipped === true, skew: t.skew ?? 0 }
+    : { rotation: n.rotation ?? 0, flipped: n.flipped === true, skew: n.skew ?? 0 };
+}
+const BOX_TOL = 0.5;
+const ANGLE_TOL = 0.01;
+function sameLook(hidden: IrNode, twin: IrNode): boolean {
+  const a = hidden.box, b = twin.box;
+  // `!(d <= tol)`, not `d > tol`: a non-number size (a malformed tree on disk) is NaN and must refuse.
+  if (!a || !b || !(Math.abs(a.w - b.w) <= BOX_TOL) || !(Math.abs(a.h - b.h) <= BOX_TOL)) return false;
+  const x = transformOf(hidden), y = transformOf(twin);
+  return x.flipped === y.flipped && Math.abs(x.rotation - y.rotation) <= ANGLE_TOL && Math.abs(x.skew - y.skew) <= ANGLE_TOL;
+}
+
+// A twin's pointer must be the plugin's own shape, `assets/<name>`: a hand-edited or foreign sibling JSON
+// naming `../x.svg` or another dir would hand that path on, and the reusing screen's `.assets.json` would
+// read the file's bytes.
+const ASSET_POINTER_RE = /^assets\/(?!\.\.?$)[^/\\]+$/;
+const twinOk = (g: Graphic): boolean => !g.hidden && !g.blocked && typeof g.node.asset === "string" && ASSET_POINTER_RE.test(g.node.asset) && g.node.assetFrom === undefined && g.reuseKey !== undefined;
+
+export interface ReuseOptions {
+  /** Trees of OTHER screens that may hold a twin for one of `keys` (writeScreen: from their `.assets.json`
+   *  `reuseKey`). Called at most once, and only when a candidate is left unmatched in its own tree. */
+  otherTrees?: (keys: ReadonlySet<string>) => Iterable<readonly IrNode[]>;
+  /** The twin's pointer names a file on disk — a reuse must never create a dangling pointer. */
+  pointerExists?: (pointer: string) => boolean;
+}
+export interface ReuseResult {
+  /** `assetSkipped:"hidden"` nodes seen */
+  hidden: number;
+  /** of which now point at a twin's file */
+  reused: number;
+  /** of which the twin was in another screen */
+  crossScreen: number;
+}
+
+// The transform move: the reused file already has the twin's transform drawn in, so the bare fields go under
+// `sourceTransform` — a builder that applies `rotation` would otherwise rotate it twice.
+function moveTransform(n: IrNode): void {
+  const t: NonNullable<IrNode["sourceTransform"]> = {};
+  if (typeof n.rotation === "number") t.rotation = n.rotation;
+  if (n.flipped === true) t.flipped = true;
+  if (typeof n.skew === "number") t.skew = n.skew;
+  delete n.rotation; delete n.flipped; delete n.skew;
+  if (Object.keys(t).length) n.sourceTransform = t;
+}
+
+/** Point every hidden graphic that has a visible twin at the twin's file. Mutates `roots` in place. */
+export function reuseHiddenAssets(roots: readonly IrNode[] | null | undefined, opts: ReuseOptions = {}): ReuseResult {
+  const graphics = collectGraphics(roots);
+  const candidates = graphics.filter((g) => g.node.assetSkipped === "hidden");
+  const result: ReuseResult = { hidden: candidates.length, reused: 0, crossScreen: 0 };
+  if (!candidates.length) return result;
+  const exists = opts.pointerExists || (() => true);
+  const pool = (list: readonly Graphic[]): Map<string, Graphic[]> => {
+    const m = new Map<string, Graphic[]>();
+    for (const g of list) {
+      if (!twinOk(g) || g.reuseKey === undefined) continue;
+      let l = m.get(g.reuseKey);
+      if (!l) { l = []; m.set(g.reuseKey, l); }
+      l.push(g);
+    }
+    return m;
+  };
+  const pick = (c: Graphic, twins: Map<string, Graphic[]>): Graphic | undefined =>
+    c.reuseKey === undefined ? undefined : (twins.get(c.reuseKey) || []).find((t) => typeof t.node.asset === "string" && exists(t.node.asset) && sameLook(c.node, t.node));
+  const apply = (c: Graphic, t: Graphic): void => {
+    const n = c.node, file = t.node.asset;
+    if (typeof file !== "string") return; // pick() only returns twins with a pointer
+    n.asset = file;
+    n.assetFrom = t.node.id;
+    delete n.assetSkipped;
+    moveTransform(n);
+  };
+
+  const local = pool(graphics);
+  const left: Graphic[] = [];
+  for (const c of candidates) {
+    if (c.blocked || c.reuseKey === undefined) continue;
+    const t = pick(c, local);
+    if (t) { apply(c, t); result.reused++; } else left.push(c);
+  }
+  if (left.length && opts.otherTrees) {
+    const keys = new Set<string>();
+    for (const c of left) if (c.reuseKey !== undefined) keys.add(c.reuseKey);
+    const other: Graphic[] = [];
+    for (const tree of opts.otherTrees(keys)) {
+      try { other.push(...collectGraphics(tree)); } catch { /* a malformed other screen holds no twin */ }
+    }
+    const far = pool(other);
+    for (const c of left) {
+      const t = pick(c, far);
+      if (t) { apply(c, t); result.reused++; result.crossScreen++; }
+    }
+  }
+  return result;
+}

package/src/atomic-write.ts

@@ -0,0 +1,79 @@
+// The one atomic file write: a tmp file beside the target, then a rename over it. Shared by bridge/ and
+// design-to-code/ (the layer may import bridge/src; bridge cannot import the layer).
+//
+// rename(2) replaces the destination atomically on POSIX, so a run killed mid-write (Ctrl-C, OOM) leaves the
+// PREVIOUS file whole instead of a truncated one every later reader fails on. The tmp file sits in the target's
+// own directory so the rename never crosses a filesystem. There is no fsync by default: these files are
+// re-creatable exports, plans and reports, and the guarantee wanted is "never half a file after a killed process",
+// which rename gives; surviving a power cut would cost a sync per write on hundreds of layer files. A file that has
+// to outlive a power cut as well (a migration's journal) passes `sync`. `sync` is fsyncSync (node:fs). On macOS a
+// plain fsync does not flush the drive's write cache (that takes fcntl F_FULLFSYNC); which one Bun issues is unverified.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { errCode } from "./errmsg.ts";
+
+/** A `.tmp-<pid>-<random>` suffix: unique per call, so two writers (two processes, or two writes in one) never
+ *  share a tmp name, and a stale tmp from a killed run is never reused. */
+export const tmpSuffix = (): string => `.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+
+// On Windows a rename over a file that another process has open — a reader polling it (verify-screen --wait reads the live
+// status every --interval while the verifier writes it), an antivirus scan or an indexer — is refused
+// (ERROR_ACCESS_DENIED / ERROR_SHARING_VIOLATION → EPERM, EACCES, EBUSY) until that handle closes, which is a moment: the
+// rename is retried for up to RENAME_RETRY_MS (as graceful-fs does for npm) before the refusal stands. POSIX renames over
+// an open file at once; there the first error is final — as it is for a target that is a directory (a refusal no handle
+// closing will lift).
+const RENAME_RETRY_MS = 2_000;
+const RENAME_TRANSIENT = new Set(["EPERM", "EACCES", "EBUSY"]);
+const sleeper = new Int32Array(new SharedArrayBuffer(4));
+/** fs.renameSync(from, to), retried on Windows while the refusal can be another process's open handle (see above). */
+export function renameOver(from: string, to: string): void {
+  const t0 = Date.now();
+  for (let delay = 5; ; delay = Math.min(delay * 2, 100)) {
+    try { fs.renameSync(from, to); return; } catch (e) {
+      const code = errCode(e);
+      if (process.platform !== "win32" || code === undefined || !RENAME_TRANSIENT.has(code) || Date.now() - t0 >= RENAME_RETRY_MS) throw e;
+      let dir = false;
+      try { dir = fs.statSync(to).isDirectory(); } catch { /* gone or unreadable: retried */ }
+      if (dir) throw e;
+      Atomics.wait(sleeper, 0, 0, delay);
+    }
+  }
+}
+
+/** The directory's entries flushed to disk (a rename into it, made durable). Not on Windows, where a directory
+ *  cannot be opened for it; a filesystem that refuses it keeps the rename as it is. */
+function syncDir(dir: string): void {
+  if (process.platform === "win32") return;
+  try {
+    const fd = fs.openSync(dir, "r");
+    try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  } catch { /* no directory fsync here: the rename stands, only its durability is the filesystem's */ }
+}
+
+/** Writes `data` to `file` atomically: a reader sees the old file or the new one, never half of either. The parent
+ *  directory is created when missing. On any error the tmp file is removed, the old file is left as it was and the
+ *  error is rethrown. `mode`: the new file's permission bits (a secret passes 0o600) — applied to the tmp file
+ *  with open(2)'s mode AND chmod, because the umask masks the first. Without `mode` the umask default applies.
+ *  `sync`: the bytes are fsynced before the rename and the directory after it, so the new file survives a power
+ *  cut too. */
+export function writeFileAtomic(file: string, data: string | Uint8Array, opts: { mode?: number; sync?: boolean } = {}): void {
+  const dir = path.dirname(path.resolve(file));
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = file + tmpSuffix();
+  try {
+    // "wx": exclusive create — never follows a symlink planted at the tmp name
+    if (opts.sync) {
+      const fd = fs.openSync(tmp, "wx", opts.mode);
+      try { fs.writeFileSync(fd, data); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    } else {
+      fs.writeFileSync(tmp, data, { flag: "wx", ...(opts.mode === undefined ? {} : { mode: opts.mode }) });
+    }
+    if (opts.mode !== undefined) fs.chmodSync(tmp, opts.mode);
+    renameOver(tmp, file);
+  } catch (e) {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* best effort */ }
+    throw e;
+  }
+  if (opts.sync) syncDir(dir);
+}