@design-twin/dtwin 0.0.0-stage → 0.1.0

package/src/pending-requests.ts

@@ -0,0 +1,187 @@
+// pending-requests.ts — every command the bridge has sent to a plugin and not yet settled, and the one rule for how each
+// settles: a reply from the connection it went to, its budget running out, the stall check, its caller giving up, its
+// connection going away, or the bridge closing.
+//
+// A module of its own, driven only by events and a Clock (clock.ts), so the rules are tested step by step against a
+// fake clock (test/pending-requests.test.ts) instead of through a real port and wall-clock sleeps. server-core's socket
+// handlers feed it what they hear (heard / progress / reply / lost); request() opens an entry and sends the frame; the
+// one thing it does on the wire itself goes through the injected `sendCancel`.
+//
+// The rules, each owned here:
+//   BUDGET  armed at open (= send) for `budgetMs`. It bounds a wait in the plugin's queue behind an earlier run in that
+//           file (figma-plugin state.ts scheduleRun — the one queue on every path, so the wait is not otherwise bounded),
+//           and is re-armed IN FULL when the plugin says this request's run has begun (its own `start` frame: a progress
+//           frame naming this request's id, on this request's connection — an id-less `start` could be anyone's): a run
+//           that began late is not cut short by the time it spent waiting.
+//   STALL   opt-in (`stall`): a separate, shorter wait for ANY frame from this request's connection after the send. It
+//           disarms itself on the first one and never re-arms: a working export goes legitimately quiet for minutes
+//           (measured live 2026-09-25: 14–24 s after one large top-level frame, 116–135 s between the last page tick and
+//           the reply), so "quiet for the window at any point" would abort working exports. What it catches is a
+//           connection that never shows life for the request at all; the budget bounds everything after. Only frames
+//           heard AFTER open count, by event order rather than by timestamp, so a connect or a frame in the same
+//           millisecond as the send can neither pass for life since the send nor be missed.
+//   CANCEL  whenever this side gives up on a request it has sent — the budget, the stall check, the caller's signal,
+//           close() — the plugin is told (`sendCancel`), or it keeps walking the export for nobody and queues every later
+//           command behind it. Not when the connection is gone (a socket that closes is itself a cancel on the plugin
+//           side) and not for a send that never left.
+//   REPLY   settles a request only from the connection it was SENT to. With per-bridge ids a reply carrying this id on
+//           another socket can only be a coincidence or a confused peer, and letting it through would resolve one file's
+//           request with another file's work.
+//   LOST    a connection that closes fails ITS pending requests at once, and only those: another file's export runs on.
+//
+// Settling clears every timer and removes the signal listener, whichever way it happens, so a settled request leaves
+// nothing armed (a one-shot CLI exits on its own) and a long-lived signal shared by many requests accumulates nothing.
+
+import { abortReason } from "./abort-reason.ts";
+import { deadline } from "./clock.ts";
+import type { Clock, Deadline } from "./clock.ts";
+
+/** The connection a request went to, as this module needs it: its id (what events are keyed on). The bridge passes its
+ *  registry entry, so `sendCancel` reaches that exact socket. */
+export interface PendingConn { connId: string }
+
+/** One request to track, opened as it is sent. */
+export interface PendingSpec<C extends PendingConn, T> {
+  id: string;
+  conn: C;
+  /** the per-command budget, ms, and the error it rejects with when it runs out */
+  budgetMs: number;
+  timedOut: () => Error;
+  /** the stall check (see STALL above): absent = none */
+  stall?: { ms: number; error: () => Error } | undefined;
+  /** the caller giving up: aborted while pending → cancel, then reject with abortReason(signal, "request aborted by the
+   *  caller"). Already aborted at open → rejects "request aborted before it was sent" at once, with no cancel and no
+   *  entry (`has(id)` is false), so the caller sends nothing. */
+  signal?: AbortSignal | undefined;
+  /** every progress tick this request's connection sends while it is pending (see `progress`) */
+  onProgress?: ((tick: T) => void) | undefined;
+}
+
+/** What a reply frame said: the plugin's result, or its error. */
+export type ReplyOutcome = { ok: true; result: unknown } | { ok: false; error: Error };
+
+interface Entry<C extends PendingConn, T> {
+  conn: C;
+  budget: Deadline;
+  stall: Deadline | null;
+  onProgress: ((tick: T) => void) | undefined;
+  unlisten: () => void;
+  resolve: (v: unknown) => void;
+  reject: (e: Error) => void;
+}
+
+export interface PendingRequestsOptions<C extends PendingConn> {
+  clock: Clock;
+  /** tell the plugin on `conn` to stop request `id` — best-effort, never awaited; it must not throw */
+  sendCancel: (conn: C, id: string) => void;
+}
+
+export function createPendingRequests<C extends PendingConn, T = unknown>({ clock, sendCancel }: PendingRequestsOptions<C>) {
+  const table = new Map<string, Entry<C, T>>();
+
+  // The one way out of the table: forget the entry, clear its timers and listener, and answer it — or null, when it
+  // has already settled (a timer and a reply can race).
+  function take(id: string): Entry<C, T> | null {
+    const p = table.get(id);
+    if (!p) return null;
+    table.delete(id);
+    p.budget.cancel();
+    p.stall?.cancel();
+    p.unlisten();
+    return p;
+  }
+
+  // Gave up on a request the plugin has: forget it, tell the plugin, then reject.
+  function giveUp(id: string, why: () => Error): void {
+    const p = take(id);
+    if (!p) return;
+    sendCancel(p.conn, id);
+    p.reject(why());
+  }
+
+  /** Track request `spec.id` from now (call it as the command is sent). The promise settles with the plugin's raw
+   *  result; checking its shape is the caller's. */
+  function open(spec: PendingSpec<C, T>): Promise<unknown> {
+    const { id, conn, signal } = spec;
+    return new Promise<unknown>((resolve, reject) => {
+      if (signal?.aborted) return reject(abortReason(signal, "request aborted before it was sent"));
+      let onAbort: (() => void) | null = null;
+      const entry: Entry<C, T> = {
+        conn,
+        budget: deadline(clock, spec.budgetMs, () => giveUp(id, spec.timedOut)),
+        stall: null,
+        onProgress: spec.onProgress,
+        unlisten: () => { if (signal && onAbort) signal.removeEventListener("abort", onAbort); onAbort = null; },
+        resolve,
+        reject,
+      };
+      const stall = spec.stall;
+      if (stall && stall.ms > 0) entry.stall = deadline(clock, stall.ms, () => giveUp(id, stall.error));
+      table.set(id, entry);
+      if (signal) {
+        const sig = signal;
+        onAbort = () => giveUp(id, () => abortReason(sig, "request aborted by the caller"));
+        sig.addEventListener("abort", onAbort, { once: true });
+      }
+    });
+  }
+
+  /** Any parsed frame from `connId` — hello, progress, a reply, even one for an id nobody here knows: life on that
+   *  connection, which disarms the stall check of every request pending on it. Call it before the frame's own event. */
+  function heard(connId: string): void {
+    for (const p of table.values()) {
+      if (p.conn.connId === connId && p.stall) { p.stall.cancel(); p.stall = null; }
+    }
+  }
+
+  /** A progress tick from `connId`. `requestId` names the one request it is for (the plugin's `start` / `queued` for one
+   *  run) — only that request hears it, and a `start` (`start: true`) re-arms that request's budget in full; an id-less
+   *  tick (page ticks, an older plugin) reaches every request pending on the connection and re-arms nothing. A tick
+   *  naming a request this connection does not have feeds nothing. A listener's throw is its own. */
+  function progress(connId: string, requestId: string | null, tick: T, start: boolean): void {
+    if (requestId !== null && start) {
+      const own = table.get(requestId);
+      if (own && own.conn.connId === connId) own.budget.rearm();
+    }
+    for (const [id, p] of table) {
+      if (p.conn.connId !== connId || !p.onProgress || (requestId !== null && id !== requestId)) continue;
+      try { p.onProgress(tick); } catch { /* a listener's failure is its own; the request goes on */ }
+    }
+  }
+
+  /** The plugin on `connId` answered request `id`. Settles it only when `connId` is where it was sent. */
+  function reply(connId: string, id: string, outcome: ReplyOutcome): void {
+    const p = table.get(id);
+    if (!p || p.conn.connId !== connId) return;
+    take(id);
+    if (outcome.ok) p.resolve(outcome.result);
+    else p.reject(outcome.error);
+  }
+
+  /** The command frame for `id` never left (a dropped send): reject now, with no cancel — the plugin never heard of it. */
+  function fail(id: string, err: Error): void {
+    take(id)?.reject(err);
+  }
+
+  /** Connection `connId` closed: every request pending on it rejects with an error of `why`'s, with no cancel; no other
+   *  is touched. (`why` makes one per request, so no two callers share an Error.) */
+  function lost(connId: string, why: () => Error): void {
+    for (const [id, p] of [...table]) if (p.conn.connId === connId) { take(id); p.reject(why()); }
+  }
+
+  /** The bridge is closing: a cancel for EVERY pending request first, while the sockets are still open, then every one
+   *  rejects with an error of `why`'s. */
+  function close(why: () => Error): void {
+    const all = [...table];
+    for (const [id, p] of all) sendCancel(p.conn, id);
+    for (const [id, p] of all) { take(id); p.reject(why()); }
+  }
+
+  return {
+    open, heard, progress, reply, fail, lost, close,
+    has: (id: string): boolean => table.has(id),
+    size: (): number => table.size,
+  };
+}
+
+export type PendingRequests<C extends PendingConn, T = unknown> = ReturnType<typeof createPendingRequests<C, T>>;

package/src/plugin-frames.ts

@@ -0,0 +1,32 @@
+// plugin-frames.ts — the plugin <-> bridge protocol on the wire: the JSON each side sends over the socket.
+// The bridge's side is server-core.ts (it sends BridgeFrames and parses what comes back); the plugin's side is
+// figma-plugin/src/relay.ts, bundled into ui.html, which turns main-thread messages into these frames and these
+// frames into main-thread messages. The test suites' fake plugin (test/fake-plugin.ts) drives that same relay.
+//
+// Dependency-free apart from type imports of commands.ts: the plugin's relay imports it, so it must type-check
+// under figma-plugin/tsconfig.json (ES2019 lib, no Node types). server-core.ts re-exports the wire frames.
+import type { Cmd, Commands } from "./commands.ts";
+
+/** bridge -> plugin: run one command; the plugin answers with a ReplyFrame carrying the same id. */
+export interface CommandFrame<C extends Cmd = Cmd> { id: string; cmd: C; args: Commands[C]["args"] }
+/** bridge -> plugin: the bridge gave up on request `id` (timed out, stalled out, or its caller left). */
+export interface CancelFrame { type: "cancel"; id: string }
+export type BridgeFrame = CommandFrame | CancelFrame;
+/** plugin -> bridge: who this plugin is, sent on every socket open. The relay sends null for what it does not
+ *  know; a plugin older than version reporting omits pluginVersion. */
+export interface HelloFrame {
+  type: "hello";
+  instanceId?: string | null; file?: string | null; fileKey?: string | null; page?: string | null; pluginVersion?: string | null;
+}
+/** plugin -> bridge: an unsolicited progress tick (figma-plugin/src/progress.ts), for the run serving `requestId`. */
+export interface ProgressFrame {
+  type: "progress";
+  requestId?: string | null; phase?: string; page?: { index: number; of: number; name?: string | null } | null;
+  nodes?: number | null; assets?: number | null;
+}
+/** plugin -> bridge: the answer to command `id`. */
+export type ReplyFrame = { [C in Cmd]: { id: string; ok: true; result: Commands[C]["reply"] } }[Cmd] | { id: string; ok: false; error: string };
+/** A ReplyFrame as the relay sends it: the main thread's result, whose shape server-core checks on arrival
+ *  (commands.ts replyShapeError) — the relay forwards it, it cannot know it. */
+export type RelayedReplyFrame = { id: string; ok: true; result: unknown } | { id: string; ok: false; error: string };
+export type PluginWireFrame = HelloFrame | ProgressFrame | ReplyFrame;

package/src/png.ts

@@ -0,0 +1,196 @@
+// png.ts — a small PNG codec for the visual diff: Node builtins only (node:zlib), so the shipped bundles stay
+// builtins-only and the pixels never go through a browser. It lives in bridge/src because the bridge reads a PNG's
+// size too (write-out.ts, via pngSize) and bridge/src never imports design-to-code; design-to-code imports it from here.
+//
+// Why not decode in Chromium: an <img> / createImageBitmap colour-manages gAMA / cHRM / iCCP by default,
+// a 2D canvas quantises alpha, and returning the pixels through page.evaluate takes 45 s (a number[]) or 4–5× the time of
+// this decoder (base64). Both sides of the diff are raw sRGB samples: Figma's references carry sRGB + gAMA 45455, and
+// Playwright's screenshots are taken under --force-color-profile=srgb.
+//
+// What it reads: colour type 2 (RGB) and 6 (RGBA), bit depth 8, not interlaced — every Figma reference and every Playwright
+// screenshot seen. Anything else throws PngError naming the colour type / depth / interlace. Every chunk's CRC
+// is checked (W3C PNG 3 §5.3), the filters are §9 (None, Sub, Up, Average, Paeth). What it writes: RGB8, filter 0, deflate
+// level 1 (a mostly uniform diff image compresses well at level 1, and fast), CRC via node:zlib's crc32 (which Bun implements).
+import { crc32, deflateSync, inflateSync } from "node:zlib";
+import { errMsg } from "./errmsg.ts";
+
+/** RGBA8 pixels, row-major, w·h·4 bytes. */
+export interface Rgba { w: number; h: number; data: Uint8Array }
+/** The PNG is malformed or of a kind this codec does not read. */
+export class PngError extends Error {}
+
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+interface Chunk { type: string; data: Buffer }
+
+/** The chunks in file order, CRC-checked; stops at IEND. Throws PngError on a bad signature, a truncated chunk or a CRC. */
+function chunks(b: Uint8Array): Chunk[] {
+  const buf = Buffer.from(b.buffer, b.byteOffset, b.byteLength);
+  if (buf.length < 8 || !buf.subarray(0, 8).equals(SIGNATURE)) throw new PngError("not a PNG (bad signature)");
+  const out: Chunk[] = [];
+  let o = 8;
+  while (o + 12 <= buf.length) {
+    const len = buf.readUInt32BE(o);
+    if (o + 12 + len > buf.length) throw new PngError("truncated PNG chunk");
+    const type = buf.toString("latin1", o + 4, o + 8), data = buf.subarray(o + 8, o + 8 + len);
+    if ((crc32(buf.subarray(o + 4, o + 8 + len)) >>> 0) !== buf.readUInt32BE(o + 8 + len)) throw new PngError(`bad CRC in the ${type} chunk`);
+    out.push({ type, data });
+    o += 12 + len;
+    if (type === "IEND") break;
+  }
+  if (!out.length || out[0]?.type !== "IHDR") throw new PngError("not a PNG (no IHDR)");
+  return out;
+}
+
+/** Width/height from the signature + IHDR header bytes alone, for a reader that only needs the size and must not reject a
+ *  PNG over a later chunk (no CRC check, no walk past IHDR — unlike pngInfo, which needs every chunk intact). null when the
+ *  bytes are not a PNG header. */
+export function pngSize(b: Uint8Array): { w: number; h: number } | null {
+  const buf = Buffer.from(b.buffer, b.byteOffset, b.byteLength);
+  if (buf.length < 24 || !buf.subarray(0, 8).equals(SIGNATURE) || buf.readUInt32BE(8) < 13 || buf.toString("latin1", 12, 16) !== "IHDR") return null;
+  return { w: buf.readUInt32BE(16), h: buf.readUInt32BE(20) };
+}
+
+export interface PngInfo { w: number; h: number; colorType: number; bitDepth: number; interlace: number; srgb: boolean; gama: number | null; iccp: string | null }
+/** IHDR + the colour chunks (sRGB, gAMA, the iCCP profile's name), or null when the bytes are not a readable PNG. */
+export function pngInfo(b: Uint8Array): PngInfo | null {
+  let cs: Chunk[];
+  try { cs = chunks(b); } catch { return null; }
+  const ihdr = cs[0];
+  if (!ihdr || ihdr.data.length < 13) return null;
+  const d = ihdr.data;
+  const info: PngInfo = { w: d.readUInt32BE(0), h: d.readUInt32BE(4), bitDepth: d[8] ?? 0, colorType: d[9] ?? 0, interlace: d[12] ?? 0, srgb: false, gama: null, iccp: null };
+  for (const c of cs) {
+    if (c.type === "sRGB") info.srgb = true;
+    else if (c.type === "gAMA" && c.data.length >= 4) info.gama = c.data.readUInt32BE(0);
+    else if (c.type === "iCCP") { const z = c.data.indexOf(0); info.iccp = c.data.toString("latin1", 0, z < 0 ? Math.min(79, c.data.length) : z); }
+  }
+  return info;
+}
+
+/** The largest image decodePng reads: 4096 × 4096 px (64 MB of RGBA). */
+export const MAX_DECODE_SIDE = 4096;
+const MAX_DECODE_PIXELS = MAX_DECODE_SIDE * MAX_DECODE_SIDE;
+/** Decode to RGBA8 (an RGB image gets alpha 255). Throws PngError for anything but colour type 2/6, depth 8, non-interlaced. */
+export function decodePng(b: Uint8Array): Rgba {
+  const cs = chunks(b);
+  const d = cs[0]?.data;
+  if (!d || d.length < 13) throw new PngError("bad IHDR");
+  const w = d.readUInt32BE(0), h = d.readUInt32BE(4), depth = d[8] ?? 0, ct = d[9] ?? 0, interlace = d[12] ?? 0;
+  if (depth !== 8 || (ct !== 2 && ct !== 6) || interlace !== 0) throw new PngError(`unsupported PNG (colour type ${ct} / depth ${depth}${interlace ? " / interlaced" : ""}) — only 8-bit RGB / RGBA, not interlaced`);
+  if (!w || !h) throw new PngError("empty PNG");
+  // refused BEFORE inflating — a few-MB zlib stream can claim gigabytes (Figma's references are ≤ ~2100 px on the long side)
+  if (w * h > MAX_DECODE_PIXELS) throw new PngError(`the PNG is ${w}×${h} px — over the ${MAX_DECODE_SIDE}×${MAX_DECODE_SIDE} pixels this decoder reads`);
+  const ch = ct === 6 ? 4 : 3, stride = w * ch;
+  let raw: Buffer;
+  // the inflated size is capped at exactly what the IHDR implies (one filter byte per row)
+  try { raw = inflateSync(Buffer.concat(cs.filter((c) => c.type === "IDAT").map((c) => c.data)), { maxOutputLength: (stride + 1) * h }); } catch (e) { throw new PngError(`bad image data (${errMsg(e)})`); }
+  if (raw.length < (stride + 1) * h) throw new PngError("truncated image data");
+  const px = new Uint8Array(stride * h);
+  for (let y = 0; y < h; y++) {
+    const f = raw[y * (stride + 1)] ?? 0, s = y * (stride + 1) + 1, dst = y * stride, prev = dst - stride;
+    if (f > 4) throw new PngError(`bad filter type ${f} on row ${y}`);
+    for (let i = 0; i < stride; i++) {
+      const x = raw[s + i] ?? 0, a = i >= ch ? px[dst + i - ch] ?? 0 : 0, up = y ? px[prev + i] ?? 0 : 0, c = y && i >= ch ? px[prev + i - ch] ?? 0 : 0;
+      let v: number;
+      if (f === 0) v = x;
+      else if (f === 1) v = x + a;
+      else if (f === 2) v = x + up;
+      else if (f === 3) v = x + ((a + up) >> 1);
+      else { const p = a + up - c, pa = Math.abs(p - a), pb = Math.abs(p - up), pc = Math.abs(p - c); v = x + (pa <= pb && pa <= pc ? a : pb <= pc ? up : c); }
+      px[dst + i] = v & 255;
+    }
+  }
+  if (ch === 4) return { w, h, data: px };
+  const data = new Uint8Array(w * h * 4);
+  for (let i = 0, j = 0; i < px.length; i += 3, j += 4) { data[j] = px[i] ?? 0; data[j + 1] = px[i + 1] ?? 0; data[j + 2] = px[i + 2] ?? 0; data[j + 3] = 255; }
+  return { w, h, data };
+}
+
+function chunk(type: string, data: Buffer): Buffer {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(data.length, 0);
+  head.write(type, 4, "latin1");
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])) >>> 0, 0);
+  return Buffer.concat([head, data, crc]);
+}
+/** Encode as RGB8 (alpha dropped — the diff image is opaque), filter 0, deflate level 1. */
+export function encodePng(img: Rgba): Buffer {
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(img.w, 0); ihdr.writeUInt32BE(img.h, 4);
+  ihdr[8] = 8; ihdr[9] = 2; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0;
+  const stride = img.w * 3 + 1, raw = Buffer.alloc(stride * img.h);
+  for (let y = 0; y < img.h; y++) {
+    let o = y * stride + 1, i = y * img.w * 4;
+    for (let x = 0; x < img.w; x++, i += 4) { raw[o++] = img.data[i] ?? 0; raw[o++] = img.data[i + 1] ?? 0; raw[o++] = img.data[i + 2] ?? 0; }
+  }
+  return Buffer.concat([SIGNATURE, chunk("IHDR", ihdr), chunk("IDAT", deflateSync(raw, { level: 1 })), chunk("IEND", Buffer.alloc(0))]);
+}
+
+/** The pixels of `r` (clamped to the image; integer px). A crop of the whole image is `img` itself, not a copy: the result
+ *  is read-only to every caller (the diff, the diff image, the encoder). */
+export function crop(img: Rgba, r: { x: number; y: number; w: number; h: number }): Rgba {
+  const x0 = Math.max(0, Math.min(img.w, Math.round(r.x))), y0 = Math.max(0, Math.min(img.h, Math.round(r.y)));
+  const w = Math.max(0, Math.min(img.w - x0, Math.round(r.w))), h = Math.max(0, Math.min(img.h - y0, Math.round(r.h)));
+  if (x0 === 0 && y0 === 0 && w === img.w && h === img.h && img.data.length === w * h * 4) return img;
+  const data = new Uint8Array(w * h * 4);
+  for (let y = 0; y < h; y++) data.set(img.data.subarray(((y0 + y) * img.w + x0) * 4, ((y0 + y) * img.w + x0 + w) * 4), y * w * 4);
+  return { w, h, data };
+}
+
+/** Area-average (box) resample to w×h: every output pixel is the coverage-weighted mean of the source pixels under it,
+ *  colour weighted by alpha (a transparent pixel adds no colour). Exact for integer factors on uniform blocks. At the
+ *  image's own size it is `img` itself, not a copy (read-only to every caller, as crop's). */
+export function resampleBox(img: Rgba, w: number, h: number): Rgba {
+  if (w <= 0 || h <= 0) return { w: Math.max(0, w), h: Math.max(0, h), data: new Uint8Array(0) };
+  if (w === img.w && h === img.h) return img.data.length === w * h * 4 ? img : { w, h, data: img.data.slice() };
+  /** per output index, the source spans and their weights along one axis */
+  const spans = (n: number, m: number): Array<Array<[number, number]>> => {
+    const sc = n / m, out: Array<Array<[number, number]>> = [];
+    for (let o = 0; o < m; o++) {
+      const a = o * sc, b = (o + 1) * sc, list: Array<[number, number]> = [];
+      for (let s = Math.floor(a); s < Math.min(n, Math.ceil(b)); s++) { const wgt = Math.min(b, s + 1) - Math.max(a, s); if (wgt > 1e-9) list.push([s, wgt]); }
+      out.push(list);
+    }
+    return out;
+  };
+  const xs = spans(img.w, w), ys = spans(img.h, h);
+  // horizontal pass into premultiplied floats (r·a, g·a, b·a, a), then vertical. The horizontal pass is per source row, made
+  // when an output row first needs it and dropped once the spans (which only move down) have passed it: a few rows of
+  // w × 4 doubles, not one w × img.h × 4 plane (512 MiB at 4096²). Each row holds the same doubles the plane did.
+  const rows = new Map<number, Float64Array>(), spare: Float64Array[] = [];
+  const hRow = (y: number): Float64Array => {
+    const have = rows.get(y);
+    if (have) return have;
+    const t = spare.pop() ?? new Float64Array(w * 4);
+    for (let x = 0; x < w; x++) {
+      let r = 0, g = 0, bl = 0, a = 0, tw = 0;
+      for (const [s, wgt] of xs[x] ?? []) {
+        const i = (y * img.w + s) * 4, al = img.data[i + 3] ?? 0;
+        r += (img.data[i] ?? 0) * al * wgt; g += (img.data[i + 1] ?? 0) * al * wgt; bl += (img.data[i + 2] ?? 0) * al * wgt; a += al * wgt; tw += wgt;
+      }
+      const o = x * 4;
+      t[o] = r / tw; t[o + 1] = g / tw; t[o + 2] = bl / tw; t[o + 3] = a / tw;
+    }
+    rows.set(y, t);
+    return t;
+  };
+  const data = new Uint8Array(w * h * 4);
+  for (let y = 0; y < h; y++) {
+    const span = ys[y] ?? [], first = span[0]?.[0];
+    if (first !== undefined) for (const [s, t] of rows) if (s < first) { rows.delete(s); spare.push(t); }
+    const src = span.map(([s]) => hRow(s));
+    for (let x = 0; x < w; x++) {
+      let r = 0, g = 0, bl = 0, a = 0, tw = 0;
+      for (let j = 0; j < span.length; j++) {
+        const t = src[j], wgt = span[j]?.[1] ?? 0, i = x * 4;
+        r += (t?.[i] ?? 0) * wgt; g += (t?.[i + 1] ?? 0) * wgt; bl += (t?.[i + 2] ?? 0) * wgt; a += (t?.[i + 3] ?? 0) * wgt; tw += wgt;
+      }
+      const o = (y * w + x) * 4;
+      a /= tw;
+      data[o + 3] = Math.round(a);
+      if (a > 0) { data[o] = Math.round(r / tw / a); data[o + 1] = Math.round(g / tw / a); data[o + 2] = Math.round(bl / tw / a); }
+    }
+  }
+  return { w, h, data };
+}

package/src/ports.ts

@@ -0,0 +1,25 @@
+// ports.ts — the ONLY ports a published plugin can reach. figma-plugin/manifest.json lists these three
+// in `networkAccess.allowedDomains`, Figma's match patterns have no port wildcard, and a plugin socket
+// to any other port is blocked by Figma before it leaves the iframe. So FIGMA_BRIDGE_PORT is a choice
+// of three, not a free number: binding 9999 gives a bridge that nothing can ever connect to. Keep this
+// array and the manifest's allowedDomains in sync — they are two halves of one contract.
+//
+// Its own module (no imports, no load-time effects) so doctor.ts — which must diagnose a bad
+// FIGMA_BRIDGE_PORT rather than die of it — reads the same list and the same parse the bridge's settings
+// (settings.ts) are read with, instead of a restated copy the test suite had to assert equal.
+export const ALLOWED_PORTS: readonly [number, ...number[]] = [8787, 8788, 8789];
+
+/** FIGMA_BRIDGE_PORT -> the port it selects, or `{ invalid }` (the raw value) when it names none of
+ *  ALLOWED_PORTS. Unset or empty selects the first. The value goes through Number(), so surrounding
+ *  whitespace is ignored and " 8788" selects 8788; a whitespace-only value is 0, which is invalid. */
+export function parsePortEnv(raw: string | undefined): { port: number; invalid?: undefined } | { invalid: string; port?: undefined } {
+  if (!raw) return { port: ALLOWED_PORTS[0] };
+  const n = Number(raw);
+  return ALLOWED_PORTS.includes(n) ? { port: n } : { invalid: raw };
+}
+
+/** The refusal for a FIGMA_BRIDGE_PORT that names none of ALLOWED_PORTS. */
+export function portProblem(raw: string): string {
+  return `[bridge] FIGMA_BRIDGE_PORT=${raw} is not one of ${ALLOWED_PORTS.join(", ")}. The Figma plugin ` +
+    "may only open sockets to ports named in its manifest, so a bridge here would never be reachable.";
+}

package/src/project-layout.ts

@@ -0,0 +1,189 @@
+// project-layout.ts — the ONE definition of where a Design Twin project keeps things.
+//
+// The layout is not "everything under design/", which would put two incompatible kinds of file in one
+// directory: what a pull WRITES and may overwrite without asking (pages/, design-system/, assets/,
+// variables.json), and what a human or a build step OWNS and cannot regenerate (target.json, the
+// component map, the plan, the audit, the verification evidence). "Delete design/ and re-pull" is the
+// obvious recovery move for a bad export, and it would silently destroy the second kind — including a
+// component map that can represent hours of hand-mapping. Moving the component map to
+// the repo root would only draw the line in two different places.
+//
+// So the line is drawn once, and where it can be seen:
+//
+//   design/
+//     export/                  <- dtwin writes ONLY here. Safe to delete and re-pull.
+//       pages/<Page>/<Screen>__<id>.json      the screen tree, its .vars.json and .assets.json
+//       pages/index.json                      every screen pulled, whatever the pull shape
+//       design-system/                        tokens, styles, component catalogs
+//       libraries/<slug>/                     a --as-library export
+//       assets/                               shared, cumulative
+//       variables.json                        the union of every screen slice
+//     target.json              <- the stack. Written by init, confirmed by build-screen.
+//     codeconnect.local.json   <- the component map. HAND-OWNED; a re-pull must never touch it.
+//     plan/<Screen>.json       <- build-screen's plan and decisions
+//     audit/<Screen>.{md,json} <- audit-design
+//     verify/<Screen>.{expected,report}.json  <- verify's machine-readable evidence
+//     .sync/                   <- design-diff --snapshot's pre-re-pull copies (tool-owned)
+//     changes/<name>.md        <- sync-design's diff reports
+//
+// Projects created before this split have their export directly in design/. Nothing rewrites them:
+// findExportDir() recognises the old shape and every consumer keeps working, while doctor says which
+// layout it found so the difference is never a silent surprise.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const DESIGN_DIR = "design";
+export const EXPORT_SUBDIR = "export";
+export const EXPORT_DIR = path.join(DESIGN_DIR, EXPORT_SUBDIR);
+export const TARGET_FILE = path.join(DESIGN_DIR, "target.json");
+export const MAP_FILE = path.join(DESIGN_DIR, "codeconnect.local.json");
+export const LEGACY_MAP_FILE = "codeconnect.local.json"; // the repo-root map of projects that predate design/
+export const PLAN_DIR = path.join(DESIGN_DIR, "plan");
+export const AUDIT_DIR = path.join(DESIGN_DIR, "audit");
+export const VERIFY_DIR = path.join(DESIGN_DIR, "verify");
+/** Where design-diff --snapshot keeps the copy of an export file taken before a re-pull. */
+export const SNAPSHOT_DIR = path.join(DESIGN_DIR, ".sync");
+/** The merged token file at the export root: the union of every screen pull's variables slice. */
+export const MERGED_VARIABLES_FILE = "variables.json";
+
+// Tailwind v4's automatic source detection scans every file git does not ignore — Markdown
+// included (tailwindcss.com/docs/detecting-classes-in-source-files) — so class names quoted in design/
+// notes, audits and plans are generated into the shipped CSS. The exclusion is `@source not "<path
+// relative to the stylesheet>";` (Tailwind v4.1+). Only SUGGESTED: the path depends on where the
+// CSS entry lives, and the user's stylesheet is theirs. One wording for `dtwin init` and tokens.ts.
+export const TAILWIND_SOURCE_NOT_NOTE =
+  `Tailwind v4 scans every file git does not ignore, ${DESIGN_DIR}/ included, so class names quoted in ${DESIGN_DIR}/ notes, audits and plans end up in your CSS. ` +
+  `Next to \`@import "tailwindcss";\` in your CSS entry, add \`@source not "<path from that CSS file to ${DESIGN_DIR}/>";\` ` +
+  `(e.g. \`@source not "../${DESIGN_DIR}";\` for src/app.css) — Tailwind v4.1+`;
+
+// Suggest only. What was proven on a real Vite + Tailwind v4 app: with Tailwind's automatic source
+// detection, rewriting an existing text file under design/ makes Vite fully reload the page — the reload that aborted
+// a measurement. Either Vite's `server.watch.ignored` (chokidar options, vite.dev/config/server-options) or Tailwind's
+// `@source not` stops it. Only emitted when the project lists BOTH vite and Tailwind v4: without Tailwind scanning
+// design/, Vite reloads only for files in its module graph, which design/ is not — so the note would be noise there.
+// (The verify tools themselves write nothing under design/ while a page is open: live status + staging live in
+// node_modules/.cache/designtwin-verify/.) Never edited for the user: vite.config is theirs.
+export const VITE_WATCH_IGNORED_NOTE =
+  `With Tailwind v4's automatic source detection, rewriting an existing text file under ${DESIGN_DIR}/ (a re-export, a verify report) makes Vite fully reload the open page. ` +
+  `Either add \`server: { watch: { ignored: ['**/${DESIGN_DIR}/**'] } }\` in vite.config (merge it with any existing \`server.watch\` options), or the Tailwind \`@source not\` above — both stop it`;
+
+// design/verify/ is regenerated on every verify run (measurements, screenshots, reports); the
+// plan's waivers and descopes live in design/plan/, so ignoring it loses no decision. Spelt with `/` on every OS: a
+// .gitignore pattern takes only `/` (a `\` there escapes the next character, so `design\verify/` ignores nothing).
+const slashed = (p: string): string => p.split(path.sep).join("/");
+export const VERIFY_GITIGNORE_NOTE =
+  `${slashed(VERIFY_DIR)}/ is regenerated on every verify run (measurements, screenshots, reports) — consider adding \`${slashed(VERIFY_DIR)}/\` to .gitignore; decisions live in ${slashed(PLAN_DIR)}/ and are not affected`;
+
+// The marks of an export directory, in the order a pull creates them. Used to tell "this project uses
+// the old flat layout" from "this project has no export yet", which are different problems with
+// different fixes.
+const EXPORT_MARKERS = ["pages", "design-system", "design-system.json", MERGED_VARIABLES_FILE, "assets", "libraries"];
+
+export function looksLikeExportDir(dir: string): boolean {
+  try {
+    if (!fs.statSync(dir).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return EXPORT_MARKERS.some((m) => fs.existsSync(path.join(dir, m)));
+}
+
+// Where THIS project's export actually is. Prefers the current layout; falls back to the legacy one
+// only when that directory really holds an export, so a fresh `design/` with nothing but target.json
+// in it is reported as "no export yet" rather than as a legacy project.
+/** Where findExportDir found (or would put) the export. `parallelLegacy` only on the modern layout. */
+export type ExportDirInfo =
+  | { dir: string; layout: "export-subdir"; rel: string; parallelLegacy: boolean }
+  | { dir: string; layout: "legacy-flat" | "none"; rel: string; parallelLegacy?: undefined };
+
+export function findExportDir(cwd: string): ExportDirInfo {
+  const modern = path.join(cwd, EXPORT_DIR);
+  const legacy = path.join(cwd, DESIGN_DIR);
+  const modernExists = looksLikeExportDir(modern);
+  const legacyExists = looksLikeExportDir(legacy);
+  // Both layouts present at once: a stray `dtwin pull design …` wrote a
+  // second, parallel export tree directly in design/ beside the real design/export/. The modern one
+  // still wins (it is where every tool looks), but the caller must be told the legacy one exists too
+  // — picking one silently is exactly what a project in this state cannot afford, since the two trees
+  // can disagree (e.g. two different `variables.json`).
+  if (modernExists) return { dir: modern, layout: "export-subdir", rel: EXPORT_DIR, parallelLegacy: legacyExists };
+  if (legacyExists) return { dir: legacy, layout: "legacy-flat", rel: DESIGN_DIR };
+  return { dir: modern, layout: "none", rel: EXPORT_DIR };
+}
+
+// The component map moved from the repo root into design/. An existing project's root copy is still
+// the real one — finding it and saying so beats writing a second map beside it and linting the wrong one.
+export interface MapFileInfo {
+  file: string;
+  rel: string;
+  legacy: boolean;
+  /** Present (true) only when neither location holds a map; `file` is then where a new one goes. */
+  missing?: true;
+}
+
+export function findMapFile(cwd: string): MapFileInfo {
+  const modern = path.join(cwd, MAP_FILE);
+  if (fs.existsSync(modern)) return { file: modern, rel: MAP_FILE, legacy: false };
+  const legacy = path.join(cwd, LEGACY_MAP_FILE);
+  if (fs.existsSync(legacy)) return { file: legacy, rel: LEGACY_MAP_FILE, legacy: true };
+  return { file: modern, rel: MAP_FILE, legacy: false, missing: true };
+}
+
+// The plan files in a plan directory (PLAN_DIR, or one a caller names): every `*.json` name, sorted so every
+// reader walks them in the same order. A directory that does not exist holds none.
+export function listPlans(dir: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith(".json")).sort();
+}
+
+// Shipped into design/ by `dtwin init`, because the one thing this layout has to communicate is which
+// half of it a re-pull is allowed to destroy — and a comment in a source file cannot do that.
+export const README = `# design/
+
+Two kinds of file live here, and the difference matters.
+
+## design/export/ — dtwin owns this
+
+Everything \`dtwin pull\` writes lands under \`export/\` and nowhere else. It is a snapshot of Figma:
+delete the whole directory and re-pull and you lose nothing.
+
+    export/pages/<Page>/<Screen>__<node-id>.json   one exported screen
+    export/pages/<Page>/<Screen>__<node-id>.vars.json    the tokens THAT screen binds
+    export/pages/<Page>/<Screen>__<node-id>.assets.json  which assets it uses, with content hashes
+    export/pages/index.json                        every screen pulled, whatever the pull shape
+    export/design-system/                          tokens.json, styles.*.json, components.*.json
+    export/variables.json                          the union of every screen's slice (merged, never replaced)
+    export/SCHEMA.md                               scripting quick keys (generated)
+    export/assets/                                 shared and cumulative across screens
+
+## design/.sync/ — a working snapshot, not an export
+
+\`design-diff.ts --snapshot <file or export dir>\` copies a file here BEFORE you re-pull it, so the sync-design skill
+can diff the old export against the new one afterwards. It is non-destructive: a snapshot that would
+replace an existing, DIFFERENT one is refused until a diff has used the old one, or you pass
+\`--force\`. The copy it replaces is kept as \`<name>.prev\` (one level; a diff never reads one a diff had already
+used — pass it with \`--against\`) — see \`claude-plugin/skills/sync-design/SKILL.md\`. It is not part of the
+Figma-owned export above and not something a re-pull ever writes to; delete it any time, it only
+affects what the next diff compares against.
+
+## design/changes/ — where a diff report lands
+
+\`design-diff.ts ... --out design/changes/<name>.md\` writes its human-readable report here, per the
+sync-design skill. Also yours: it is evidence of what changed on a given sync, not something
+\`dtwin pull\` regenerates.
+
+## Everything else here — you own it
+
+These are decisions and evidence. They are not regenerable, and a re-pull never touches them.
+
+    target.json              which stack you are building for
+    codeconnect.local.json   Figma component key -> your code component. Hand-maintained.
+    plan/<Screen>.json       what build-screen decided, and why
+    audit/<Screen>.{md,json} the pre-build design review
+    verify/<Screen>.report.json  the measured per-node comparison behind any "pass"
+
+Commit both halves. If your .gitignore ignores \`design/\`, un-ignore this half —
+\`!design/target.json\`, \`!design/codeconnect.local.json\`, \`!design/plan/\` — or the work is lost
+with the next clone.
+`;