@1agh/maude 0.59.0 → 0.60.0

package/apps/studio/figma/fig-differential.test.ts

@@ -0,0 +1,182 @@
+// TIER 2 — the differential. THE SHIP GATE for the `.fig` door (DDR-221 D7).
+//
+// The same document through both doors must normalize to the same tree. This is
+// the only oracle that proves the decoder is RIGHT rather than merely QUIET, and
+// it exists only because the REST door was built first — which is what
+// retroactively justifies the phase ordering.
+//
+// It earned that billing immediately. Every unit test in fig-decode.test.ts was
+// green while the decoder emitted Figma's INTERNAL node vocabulary
+// (FRAME-with-resizeToFit, ROUNDED_RECTANGLE, SYMBOL) instead of the public REST
+// one the translators are written against. Both sides looked perfectly valid in
+// isolation; only the comparison could see it.
+//
+// Offline by construction: the oracle is a COMMITTED capture of
+// `fetchDocument()` for the same two documents, so CI needs no token and no
+// network. The recorded form catches DECODER regressions; only a live re-capture
+// catches FIGMA changing. They are not the same test — see § Re-capturing.
+//
+// ── Re-capturing the oracle ──────────────────────────────────────────────────
+// Needed when Figma changes its REST projection, or when a fixture document is
+// edited. Requires a stored Figma PAT (`getProviderKey('figma')`):
+//
+//   cd apps/studio && bun -e '
+//     const { fetchDocument } = await import("./figma/client.ts");
+//     for (const [key, surface, out] of [
+//       ["dGNzRC2kmrmGnOxaBa0RI7", "design", "design.rest-oracle.json"],
+//       ["Em6NOwaOFTYV7NlQT4NK8l", "board",  "figjam.rest-oracle.json"],
+//     ]) await Bun.write("../../.ai/fixtures/figma/2026-08-03/" + out,
+//          JSON.stringify(await fetchDocument({ fileKey: key, surface }), null, 1));'
+//
+// Both documents live on the StudyFi plan (moved there 2026-08-12; the file keys
+// survived the move). Re-export the `.fig`/`.jam` in the same pass or the two
+// halves drift apart.
+
+import { describe, expect, test } from 'bun:test';
+
+import { decodeFigArchive } from './fig-decode.ts';
+import { type FigmaNode, type NormalizedDocument, walkNodes } from './types.ts';
+
+const FIXTURES = new URL('../../../.ai/fixtures/figma/2026-08-03/', import.meta.url).pathname;
+
+/**
+ * The ONE documented lossy delta, asserted AS lossy rather than tolerated.
+ *
+ * REST expands an INSTANCE's children and mints synthetic ids for them
+ * (`I<instance>;<child>`). A `.fig` stores an instance by reference — only its
+ * overrides — so those nodes genuinely do not exist in the local file. This is
+ * a property of the two formats, not a decoder defect, and it is the reason the
+ * gate compares SHARED nodes plus an explicit allowlist rather than raw counts.
+ */
+const REST_ONLY_ID = /^I[0-9]+:[0-9]+;/;
+
+/** Sub-pixel float noise would be acceptable; we have never needed the slack. */
+const GEOMETRY_EPSILON = 0.5;
+
+interface Case {
+  label: string;
+  fileKey: string;
+  archive: string;
+  oracle: string;
+}
+
+const CASES: Case[] = [
+  {
+    label: 'design',
+    fileKey: 'dGNzRC2kmrmGnOxaBa0RI7',
+    archive: 'design.fig',
+    oracle: 'design.rest-oracle.json',
+  },
+  {
+    label: 'figjam',
+    fileKey: 'Em6NOwaOFTYV7NlQT4NK8l',
+    archive: 'figjam.jam',
+    oracle: 'figjam.rest-oracle.json',
+  },
+];
+
+function index(root: FigmaNode): Map<string, FigmaNode> {
+  const byId = new Map<string, FigmaNode>();
+  walkNodes(root, (n) => byId.set(n.id, n));
+  return byId;
+}
+
+async function load(c: Case) {
+  const rest = (await Bun.file(FIXTURES + c.oracle).json()) as NormalizedDocument;
+  const bytes = new Uint8Array(await Bun.file(FIXTURES + c.archive).arrayBuffer());
+  const { document: fig } = decodeFigArchive(bytes, { fileKey: c.fileKey });
+  return { rest: index(rest.root), fig: index(fig.root), restDoc: rest, figDoc: fig };
+}
+
+describe.each(CASES)('tier 2 — $label through both doors', (c) => {
+  test('the .fig door sees every REST node except the documented instance children', async () => {
+    const { rest, fig } = await load(c);
+    const missing = [...rest.keys()].filter((id) => !fig.has(id));
+    // Every absence must be explained by the ONE known delta.
+    expect(missing.filter((id) => !REST_ONLY_ID.test(id))).toEqual([]);
+    // And nothing may exist locally that REST does not know about.
+    expect([...fig.keys()].filter((id) => !rest.has(id))).toEqual([]);
+  });
+
+  test('node TYPE agrees — the public vocabulary, not Figma internals', async () => {
+    const { rest, fig } = await load(c);
+    const diffs = [...fig.entries()]
+      .filter(([id, n]) => rest.get(id) && rest.get(id)?.type !== n.type)
+      .map(([id, n]) => `${id}: REST=${rest.get(id)?.type} fig=${n.type}`);
+    expect(diffs).toEqual([]);
+  });
+
+  test('node NAME agrees byte for byte, diacritics and hostile characters included', async () => {
+    const { rest, fig } = await load(c);
+    const diffs = [...fig.entries()]
+      .filter(([id, n]) => rest.get(id) && rest.get(id)?.name !== n.name)
+      .map(([id]) => id);
+    expect(diffs).toEqual([]);
+  });
+
+  test('GEOMETRY agrees — the parent-chain composition against REST absolute boxes', async () => {
+    const { rest, fig } = await load(c);
+    const diffs: string[] = [];
+    let worst = 0;
+    for (const [id, n] of fig) {
+      const r = rest.get(id);
+      if (!r?.absoluteBoundingBox || !n.absoluteBoundingBox) continue;
+      const a = r.absoluteBoundingBox;
+      const b = n.absoluteBoundingBox;
+      const delta = Math.max(
+        Math.abs(a.x - b.x),
+        Math.abs(a.y - b.y),
+        Math.abs(a.width - b.width),
+        Math.abs(a.height - b.height)
+      );
+      worst = Math.max(worst, delta);
+      if (delta > GEOMETRY_EPSILON) diffs.push(`${id}: Δ${delta.toFixed(2)}px`);
+    }
+    expect(diffs).toEqual([]);
+    // Recorded rather than merely bounded: the composition is EXACT today, and a
+    // drift into "within tolerance" is worth noticing before it becomes drift
+    // out of it. This is the assertion the A4 float trap would have failed.
+    expect(worst).toBe(0);
+  });
+
+  test('TEXT content agrees', async () => {
+    const { rest, fig } = await load(c);
+    const diffs = [...fig.entries()]
+      .filter(([id, n]) => {
+        const r = rest.get(id);
+        return r && (r.characters ?? '') !== (n.characters ?? '');
+      })
+      .map(([id]) => id);
+    expect(diffs).toEqual([]);
+  });
+
+  test('the surface the prelude declared matches the surface REST was asked for', async () => {
+    const { restDoc, figDoc } = await load(c);
+    expect(figDoc.surface).toBe(restDoc.surface);
+    expect(figDoc.origin).toBe('fig');
+    expect(restDoc.origin).toBe('rest');
+  });
+});
+
+describe('tier 2 — the lossy delta is asserted, not assumed', () => {
+  test('the design file really does carry instance children only REST expands', async () => {
+    const { rest, fig } = await load(CASES[0]);
+    const restOnly = [...rest.keys()].filter((id) => !fig.has(id));
+    // If this ever becomes empty, either the fixture changed or REST stopped
+    // expanding instances — both mean the allowlist above needs re-deriving
+    // rather than silently covering nothing.
+    expect(restOnly.length).toBeGreaterThan(0);
+    expect(restOnly.every((id) => REST_ONLY_ID.test(id))).toBe(true);
+  });
+
+  test('connector endpoints resolve to the same host ids through both doors', async () => {
+    const { rest, fig } = await load(CASES[1]);
+    const pairs = (m: Map<string, FigmaNode>) =>
+      [...m.values()]
+        .filter((n) => n.type === 'CONNECTOR')
+        .map((n) => `${n.id}:${n.connectorStart}->${n.connectorEnd}`)
+        .sort();
+    expect(pairs(fig)).toEqual(pairs(rest));
+    expect(pairs(fig).length).toBe(6);
+  });
+});

package/apps/studio/figma/fig-translator.test.ts

@@ -0,0 +1,192 @@
+// TIER 3 — end to end through the REAL translators (DDR-221 D7).
+//
+// Tier 2 proves the two doors normalize to the same TREE. That is necessary and
+// not sufficient: the translators read specific fields, and a tree can agree on
+// everything a diff looks at while still translating differently. This tier
+// runs `toStrokes` (board) and `toCanvas` (design) over BOTH doors' output and
+// compares what they actually produce.
+//
+// It is also where the Tier-2 vocabulary finding pays off concretely: before the
+// internal→REST mapping, `to-strokes`/`to-artboard` saw FRAME where REST gave
+// GROUP and every sticky arrived with empty text — so this comparison is the one
+// that would have caught the user-visible half of that bug.
+
+import { describe, expect, test } from 'bun:test';
+
+import { decodeFigArchive } from './fig-decode.ts';
+import { toArtboard, toCanvas } from './to-artboard.ts';
+import { toStrokes } from './to-strokes.ts';
+import { type FigmaNode, type NormalizedDocument, walkNodes } from './types.ts';
+
+const FIXTURES = new URL('../../../.ai/fixtures/figma/2026-08-03/', import.meta.url).pathname;
+
+async function doors(archive: string, oracle: string, fileKey: string) {
+  const rest = (await Bun.file(FIXTURES + oracle).json()) as NormalizedDocument;
+  const bytes = new Uint8Array(await Bun.file(FIXTURES + archive).arrayBuffer());
+  const { document: fig } = decodeFigArchive(bytes, { fileKey });
+  return { rest, fig };
+}
+
+/** The first CANVAS page, which is what an import actually translates. */
+function firstPage(doc: NormalizedDocument): FigmaNode {
+  let page: FigmaNode | undefined;
+  walkNodes(doc.root, (n) => {
+    if (!page && n.type === 'CANVAS') page = n;
+  });
+  if (!page) throw new Error('no CANVAS page in the document');
+  return page;
+}
+
+describe('tier 3 — FigJam board through to-strokes', () => {
+  test('both doors produce the same stroke set: kinds, geometry, text and bindings', async () => {
+    const { rest, fig } = await doors(
+      'figjam.jam',
+      'figjam.rest-oracle.json',
+      'Em6NOwaOFTYV7NlQT4NK8l'
+    );
+    const a = toStrokes(rest);
+    const b = toStrokes(fig);
+
+    // A stroke's identity for comparison purposes: what the user would see.
+    const shape = (s: Record<string, unknown>) =>
+      [
+        s.tool,
+        Math.round(Number(s.x ?? 0)),
+        Math.round(Number(s.y ?? 0)),
+        Math.round(Number(s.w ?? 0)),
+        Math.round(Number(s.h ?? 0)),
+        String(s.text ?? s.label ?? ''),
+        String(s.color ?? ''),
+      ].join('|');
+
+    const av = (a.strokes as unknown as Record<string, unknown>[]).map(shape).sort();
+    const bv = (b.strokes as unknown as Record<string, unknown>[]).map(shape).sort();
+    expect(bv).toEqual(av);
+    expect(b.strokes.length).toBe(a.strokes.length);
+    expect(b.origin).toEqual(a.origin);
+  });
+
+  test('sticky TEXT actually arrives — the regression Tier 2 found, at the user-visible layer', async () => {
+    const { fig } = await doors('figjam.jam', 'figjam.rest-oracle.json', 'Em6NOwaOFTYV7NlQT4NK8l');
+    const { strokes } = toStrokes(fig);
+    const texts = (strokes as unknown as Record<string, unknown>[])
+      .map((s) => String(s.text ?? s.label ?? ''))
+      .filter(Boolean);
+    // Before the override-path fix every one of these was an empty string while
+    // the board still looked structurally perfect.
+    expect(texts.some((t) => t.includes('palette yellow'))).toBe(true);
+    expect(texts.some((t) => t.includes('Sekce vnější'))).toBe(true);
+    expect(texts.filter((t) => t.trim().length > 0).length).toBeGreaterThan(10);
+  });
+
+  test('bound connectors survive as bindings, not as frozen lines', async () => {
+    const { rest, fig } = await doors(
+      'figjam.jam',
+      'figjam.rest-oracle.json',
+      'Em6NOwaOFTYV7NlQT4NK8l'
+    );
+    // `to-strokes` mints ids as `fig_<session>_<local>_<n>` where <n> is a
+    // process-wide counter, so the SECOND call in a test file is offset by the
+    // first. Compare the host NODE, which is the part that carries meaning.
+    const host = (b: unknown) => {
+      const id = (b as { hostId?: string } | null)?.hostId;
+      return id ? id.replace(/_\d+$/, '') : null;
+    };
+    const bindings = (r: ReturnType<typeof toStrokes>) =>
+      (r.strokes as unknown as Record<string, unknown>[])
+        .filter((s) => s.tool === 'arrow')
+        .map((s) => `${host(s.startBind)}->${host(s.endBind)}`)
+        .sort();
+    expect(bindings(toStrokes(fig))).toEqual(bindings(toStrokes(rest)));
+  });
+
+  test('the two doors report the same dispositions', async () => {
+    const { rest, fig } = await doors(
+      'figjam.jam',
+      'figjam.rest-oracle.json',
+      'Em6NOwaOFTYV7NlQT4NK8l'
+    );
+    const codes = (r: ReturnType<typeof toStrokes>) =>
+      r.report.entries.map((e) => `${e.node}:${e.disposition}`).sort();
+    expect(codes(toStrokes(fig))).toEqual(codes(toStrokes(rest)));
+  });
+});
+
+describe('tier 3 — design page through to-canvas', () => {
+  const KEY = 'dGNzRC2kmrmGnOxaBa0RI7';
+
+  test('both doors produce the same artboard set and the same JSX', async () => {
+    const { rest, fig } = await doors('design.fig', 'design.rest-oracle.json', KEY);
+    const a = toCanvas(rest, firstPage(rest));
+    const b = toCanvas(fig, firstPage(fig));
+
+    expect(b.artboardCount).toBe(a.artboardCount);
+    expect(b.origin).toEqual(a.origin);
+    // The emitted component source is the real deliverable — compare it whole,
+    // minus the ONE field a local file cannot reproduce (see the next test).
+    // Normalized: the ONE field a local export cannot reproduce (next test).
+    // `toCanvas`'s banner carries no verb, so there is nothing else to allow for.
+    const norm = (tsx: string) => tsx.replace(/ lineHeight: "[^"]*",/g, '');
+    expect(norm(b.tsx)).toBe(norm(a.tsx));
+  });
+
+  test('a single-frame artboard names the DOOR it came through', async () => {
+    // `--fig` reads a local export with no network at all. A banner claiming
+    // `--frames` on a file nobody fetched is a false provenance claim, so
+    // `toArtboard` reads `doc.origin` rather than hardcoding the verb.
+    const { rest, fig } = await doors('design.fig', 'design.rest-oracle.json', KEY);
+    const frameOf = (d: NormalizedDocument) => {
+      let f: FigmaNode | undefined;
+      walkNodes(d.root, (n) => {
+        if (!f && n.type === 'FRAME') f = n;
+      });
+      if (!f) throw new Error('no FRAME in the fixture');
+      return f;
+    };
+    expect(toArtboard(rest, frameOf(rest)).tsx).toContain('import-figma --frames`');
+    expect(toArtboard(fig, frameOf(fig)).tsx).toContain('--fig (offline, local export)`');
+  });
+
+  test('lineHeight is the ONLY thing the local door cannot reproduce, and it says so', async () => {
+    // REST reports a RESOLVED pixel line-height; a .fig stores the authored
+    // value, and `{value: 100, units: "PERCENT"}` cannot become pixels without
+    // font metrics we do not have offline. Asserted AS lossy per the plan's
+    // "known-lossy fields are listed explicitly; nothing degrades silently" —
+    // and asserted as the only one, so the list cannot quietly grow.
+    const bytes = new Uint8Array(await Bun.file(`${FIXTURES}design.fig`).arrayBuffer());
+    const { report } = decodeFigArchive(bytes, { fileKey: KEY });
+    expect(report.lossyFields.map((f) => f.field)).toEqual(['style.lineHeightPx']);
+    expect(report.lossyFields[0]?.count).toBeGreaterThan(0);
+
+    const { rest, fig } = await doors('design.fig', 'design.rest-oracle.json', KEY);
+    const a = toCanvas(rest, firstPage(rest)).tsx;
+    const b = toCanvas(fig, firstPage(fig)).tsx;
+    // Everything OTHER than lineHeight matches, so the diff really is that one
+    // property and not a bucket that happens to contain it.
+    expect(a.includes('lineHeight:')).toBe(true);
+    expect(b.includes('lineHeight:')).toBe(false);
+  });
+
+  test('the GROUP mapping reaches the translator — flattening depends on it', async () => {
+    // `isStylelessWrapper`/`flattenWrappers` key off GROUP. While the decoder
+    // emitted Figma's internal FRAME for those nodes, the three nested wrappers
+    // in the design fixture would never have been flattened.
+    const { rest, fig } = await doors('design.fig', 'design.rest-oracle.json', KEY);
+    const groups = (d: NormalizedDocument) => {
+      let n = 0;
+      walkNodes(d.root, (x) => {
+        if (x.type === 'GROUP') n++;
+      });
+      return n;
+    };
+    expect(groups(fig)).toBe(groups(rest));
+    expect(groups(fig)).toBeGreaterThan(0);
+  });
+
+  test('the two doors report the same dispositions', async () => {
+    const { rest, fig } = await doors('design.fig', 'design.rest-oracle.json', KEY);
+    const codes = (r: ReturnType<typeof toCanvas>) =>
+      r.report.entries.map((e) => `${e.node}:${e.disposition}`).sort();
+    expect(codes(toCanvas(fig, firstPage(fig)))).toEqual(codes(toCanvas(rest, firstPage(rest))));
+  });
+});

package/apps/studio/figma/fig-vector.test.ts

@@ -0,0 +1,113 @@
+// figma/fig-vector.ts — path geometry out of a local `.fig` (DDR-221 A11).
+//
+// These exist because the DDR SHIPPED A FALSE CLAIM: A9/A10 said a vector
+// cluster is a server-side render absent from a local export, and a
+// user-visible `asset-unavailable-offline` disposition said so out loud. The
+// geometry was in the file the whole time. The tests below pin the command set
+// that was measured, so the claim cannot silently regress in either direction.
+
+import { describe, expect, test } from 'bun:test';
+
+import { artToSvg, FigVectorError, MAX_PATH_COMMANDS, pathFromBlob } from './fig-vector.ts';
+
+/** Encode `cmd` + float32 LE pairs, the layout measured on a real export. */
+function blob(...items: Array<[number, number[]]>): Uint8Array {
+  const out: number[] = [];
+  for (const [cmd, coords] of items) {
+    out.push(cmd);
+    for (const c of coords) {
+      const b = new Uint8Array(4);
+      new DataView(b.buffer).setFloat32(0, c, true);
+      out.push(...b);
+    }
+  }
+  return new Uint8Array(out);
+}
+
+describe('path blob decoding', () => {
+  test('the measured command set round-trips to SVG', () => {
+    const d = pathFromBlob(
+      blob(
+        [1, [40.56, 0]],
+        [2, [50.89, 30.24]],
+        [3, [1, 2, 3, 4]],
+        [4, [1, 2, 3, 4, 5, 6]],
+        [0, []]
+      )
+    );
+    expect(d).toBe('M40.56 0 L50.89 30.24 Q1 2 3 4 C1 2 3 4 5 6 Z');
+  });
+
+  test('the real sparkle decodes to a closed 8-point star', () => {
+    // Byte-for-byte the 82-byte blob from the export (`Untitled.fig`, node 1:6).
+    const pts: Array<[number, number[]]> = [
+      [1, [40.56, 0]],
+      [2, [50.89, 30.24]],
+      [2, [81.13, 40.56]],
+      [2, [50.89, 50.89]],
+      [2, [40.56, 81.13]],
+      [2, [30.24, 50.89]],
+      [2, [0, 40.56]],
+      [2, [30.24, 30.24]],
+      [2, [40.56, 0]],
+      [0, []],
+    ];
+    const d = pathFromBlob(blob(...pts));
+    expect(d.startsWith('M40.56 0')).toBe(true);
+    expect(d.endsWith('Z')).toBe(true);
+    expect(d.split('L')).toHaveLength(9);
+  });
+
+  test('an unknown command REFUSES rather than truncating the path', () => {
+    // A half-read path renders as confident nonsense — the exact failure the
+    // fail-loud posture exists to prevent.
+    expect(() => pathFromBlob(blob([1, [0, 0]], [9, []]))).toThrow(/unknown path command 9/);
+  });
+
+  test('a command running past the end refuses', () => {
+    const b = blob([1, [1, 2]]);
+    expect(() => pathFromBlob(b.subarray(0, b.length - 2))).toThrow(/past the end/);
+  });
+
+  test('an empty blob refuses instead of emitting an empty path', () => {
+    expect(() => pathFromBlob(new Uint8Array(0))).toThrow(FigVectorError);
+  });
+
+  test('a command flood is capped', () => {
+    const many: Array<[number, number[]]> = Array.from({ length: MAX_PATH_COMMANDS + 10 }, () => [
+      2,
+      [1, 1],
+    ]);
+    expect(() => pathFromBlob(blob(...many))).toThrow(/more than/);
+  });
+});
+
+describe('SVG serialization', () => {
+  test('emits only geometry and colour — nothing the DDR-167 lane would strip', () => {
+    const svg = artToSvg({
+      width: 118,
+      height: 118,
+      paths: [
+        { d: 'M0 0 L1 1 Z', fill: '#5b62e8', fillOpacity: 1, fillRule: 'nonzero', x: 0, y: 0 },
+        { d: 'M2 2 Z', fill: '#ffffff', fillOpacity: 0.5, fillRule: 'evenodd', x: 5, y: 6 },
+      ],
+    });
+    expect(svg).toContain('viewBox="0 0 118 118"');
+    expect(svg).toContain('fill="#5b62e8"');
+    expect(svg).toContain('fill-opacity="0.5"');
+    expect(svg).toContain('fill-rule="evenodd"');
+    expect(svg).toContain('transform="translate(5 6)"');
+    for (const forbidden of ['<script', 'xlink', '<use', 'href', 'onload']) {
+      expect(svg).not.toContain(forbidden);
+    }
+  });
+
+  test('a path with no fill is explicit about it rather than inheriting', () => {
+    const svg = artToSvg({
+      width: 10,
+      height: 10,
+      paths: [{ d: 'M0 0 Z', fill: null, fillOpacity: 1, fillRule: 'nonzero', x: 0, y: 0 }],
+    });
+    expect(svg).toContain('fill="none"');
+  });
+});

package/apps/studio/figma/fig-vector.ts

@@ -0,0 +1,145 @@
+/**
+ * @file       figma/fig-vector.ts — path geometry out of a local `.fig`.
+ * @scope      apps/studio/figma/fig-vector.ts
+ * @purpose    Turn a `.fig`'s own vector geometry into SVG, so the offline door
+ *             does NOT need Figma to render an icon.
+ *
+ * @invariant  THIS CORRECTS A CLAIM DDR-221 MADE. A9/A10 asserted that a vector
+ *             cluster is a server-side render absent from a local export, and
+ *             shipped an `asset-unavailable-offline` disposition saying so. That
+ *             is false: every `VECTOR` carries `fillGeometry[].commandsBlob`, an
+ *             index into the message's `blobs[]`, and the blob holds the actual
+ *             path. Measured on a real export — both blobs decoded to the byte
+ *             (196/196 and 82/82) with the command set below.
+ *
+ * @invariant  DEPENDENCY-FREE and pure. Bytes in, path string out. Every input
+ *             is attacker-controlled, so each blob is bounded and a command the
+ *             table does not know REFUSES the path rather than guessing at it
+ *             (DDR-221 D3 — a half-read path draws plausible nonsense).
+ */
+
+/** Observed command set. Arity is in FLOAT PAIRS-worth of float32s. */
+const CLOSE = 0;
+const MOVE_TO = 1;
+const LINE_TO = 2;
+const QUAD_TO = 3;
+const CUBIC_TO = 4;
+
+const ARITY: Record<number, number> = {
+  [CLOSE]: 0,
+  [MOVE_TO]: 2,
+  [LINE_TO]: 2,
+  [QUAD_TO]: 4,
+  [CUBIC_TO]: 6,
+};
+
+const LETTER: Record<number, string> = {
+  [CLOSE]: 'Z',
+  [MOVE_TO]: 'M',
+  [LINE_TO]: 'L',
+  [QUAD_TO]: 'Q',
+  [CUBIC_TO]: 'C',
+};
+
+/** ~10x the largest observed (464 B). A path is not a payload. */
+export const MAX_PATH_BLOB_BYTES = 64 * 1024;
+/** Bounds the emitted string as well as the walk. */
+export const MAX_PATH_COMMANDS = 4096;
+
+export class FigVectorError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FigVectorError';
+  }
+}
+
+/** Trim float noise without pretending to more precision than Figma stored. */
+function n(v: number): string {
+  if (!Number.isFinite(v)) throw new FigVectorError('path coordinate is not finite');
+  const r = Math.round(v * 100) / 100;
+  return Object.is(r, -0) ? '0' : String(r);
+}
+
+/**
+ * Decode one commands blob into an SVG `d` attribute.
+ *
+ * Refuses rather than truncates: an unknown command byte, a run past the end,
+ * or a non-finite coordinate all throw, because a partially-read path renders
+ * as confident nonsense — the exact failure mode the fail-loud posture exists
+ * to prevent.
+ */
+export function pathFromBlob(bytes: Uint8Array): string {
+  if (bytes.length > MAX_PATH_BLOB_BYTES) {
+    throw new FigVectorError(`path blob is ${bytes.length} bytes, over the limit`);
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const parts: string[] = [];
+  let offset = 0;
+
+  while (offset < bytes.length) {
+    const command = bytes[offset];
+    const arity = ARITY[command];
+    if (arity === undefined) {
+      throw new FigVectorError(`unknown path command ${command} at byte ${offset}`);
+    }
+    offset += 1;
+    if (offset + arity * 4 > bytes.length) {
+      throw new FigVectorError(`path command ${command} runs past the end of the blob`);
+    }
+    if (parts.length >= MAX_PATH_COMMANDS) {
+      throw new FigVectorError(`path has more than ${MAX_PATH_COMMANDS} commands`);
+    }
+    const coords: string[] = [];
+    for (let i = 0; i < arity; i++) {
+      coords.push(n(view.getFloat32(offset, true)));
+      offset += 4;
+    }
+    parts.push(coords.length > 0 ? `${LETTER[command]}${coords.join(' ')}` : LETTER[command]);
+  }
+
+  if (parts.length === 0) throw new FigVectorError('path blob is empty');
+  return parts.join(' ');
+}
+
+export interface VectorPath {
+  /** SVG `d`, in the owning node's own coordinate space. */
+  d: string;
+  /** `#rrggbb` of the first visible solid fill, or null when there is none. */
+  fill: string | null;
+  fillOpacity: number;
+  /** `nonzero` | `evenodd`, straight from the geometry record. */
+  fillRule: string;
+  /** Placement inside the cluster, already composed. */
+  x: number;
+  y: number;
+}
+
+/** One cluster's worth of paths plus the box they live in. */
+export interface VectorArt {
+  width: number;
+  height: number;
+  paths: VectorPath[];
+}
+
+/**
+ * Serialize to a standalone SVG.
+ *
+ * Emits ONLY `<svg>`, `<path>` and plain geometry/colour attributes — no
+ * scripts, no `<use>`, no external references — so the result is trivially
+ * within the DDR-167 allowlist it is then promoted through. It is still routed
+ * through that sanitizer rather than trusted, on the standing rule that this
+ * module's input is a third party's file.
+ */
+export function artToSvg(art: VectorArt): string {
+  const w = Math.max(1, Math.round(art.width));
+  const h = Math.max(1, Math.round(art.height));
+  const body = art.paths
+    .map((p) => {
+      const transform = p.x !== 0 || p.y !== 0 ? ` transform="translate(${n(p.x)} ${n(p.y)})"` : '';
+      const opacity = p.fillOpacity < 1 ? ` fill-opacity="${n(p.fillOpacity)}"` : '';
+      const rule = p.fillRule === 'evenodd' ? ' fill-rule="evenodd"' : '';
+      return `<path d="${p.d}" fill="${p.fill ?? 'none'}"${opacity}${rule}${transform}/>`;
+    })
+    .join('');
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}" fill="none">${body}</svg>`;
+}

package/apps/studio/figma/sanitize.ts

@@ -71,6 +71,13 @@ export const DISPOSITIONS = Object.freeze([
   'asset-cap-reached',
   /** A vector Figma declined to render as SVG, re-requested as PNG. */
   'asset-degraded',
+  /**
+   * The LOCAL `.fig` door (DDR-221) cannot produce this asset: a vector cluster
+   * is rendered by Figma's servers and is simply absent from an export. The
+   * archive carries image FILLS, never renders. Distinct from `asset-skipped`
+   * ("we tried and it failed") — nothing was attempted and nothing could be.
+   */
+  'asset-unavailable-offline',
   'jsx-cap-reached',
   'value-rejected',
   // ── The codegen route (DDR-219 D9). Three dispositions, one rule: what makes