@1agh/maude 0.58.3 → 0.60.0

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

@@ -0,0 +1,839 @@
+/**
+ * @file       figma/fig-decode.ts — the local `.fig` / `.jam` ingestion door.
+ * @scope      apps/studio/figma/fig-decode.ts
+ * @purpose    ZIP → `canvas.fig` → container → the two decompressors → Kiwi →
+ *             a REST-SHAPED raw tree → `normalizeDocument(raw, {origin:'fig'})`.
+ *             The second door onto the tree the translators already consume
+ *             (DDR-221). No network, no token, no SSRF: the whole door is local.
+ *
+ * @invariant  EMIT REST-SHAPED RAW, DO NOT BUILD A NormalizedDocument (DDR-221
+ *             A5). Handing raw to the EXISTING normalizer makes the node/depth
+ *             caps and the prototype-pollution guard literally the same code as
+ *             the REST door, rather than a parallel implementation that drifts.
+ *
+ * @invariant  FRAMING ERRORS REFUSE THE FILE; VOCABULARY GAPS DEGRADE AND
+ *             REPORT (DDR-221 D3). An unknown prelude or container version is
+ *             a refusal — never a best-effort decode, because a design importer
+ *             that guesses produces wrong geometry that looks right.
+ *
+ * @invariant  EVERY SCHEMA-SOURCED STRING IS ATTACKER-CHOSEN (DDR-221 A8/F1).
+ *             Enum member names come from the file's own schema, so node
+ *             `type` is attacker-controlled. Anything reaching a report goes
+ *             through `reportToken` + a count, never verbatim — `attrValue`
+ *             is NOT enough, it maps rejected characters to spaces and a
+ *             bounded label can still read as prose.
+ */
+
+import { createHash } from 'node:crypto';
+import { inflateRawSync, zstdDecompressSync } from 'node:zlib';
+
+import { styleToWeight } from './codegen-fonts.ts';
+import { decodeKiwi, findRootDefinition, type KiwiSchema, parseKiwiSchema } from './fig-kiwi.ts';
+import { pathFromBlob, type VectorPath } from './fig-vector.ts';
+import { FigZipError, readFigZip } from './fig-zip.ts';
+import { reportToken } from './sanitize.ts';
+import {
+  KNOWN_NODE_TYPES,
+  MAX_NODE_COUNT,
+  type NormalizedDocument,
+  normalizeDocument,
+} from './types.ts';
+
+// ── Container constants (measured on the committed fixtures) ────────────────
+
+/** The 8-byte ASCII prelude is the ONLY editor discriminator. */
+const PRELUDES: Record<string, 'design' | 'board'> = {
+  'fig-kiwi': 'design',
+  'fig-jam.': 'board',
+};
+
+/**
+ * Container versions we have actually observed. INFORMATIONAL — not a gate.
+ *
+ * DDR-221 D3 originally REFUSED an unrecognised version, on the assumption that
+ * the number predicts framing compatibility. Measured on a real third-party
+ * export (2026-08-12): it does not. That file is version **101** — LOWER than
+ * the fixtures' 106 despite being exported nine days later — carries a
+ * DIFFERENT schema (`7ae1921b` vs `c22712ff`), and decodes perfectly under the
+ * same code, because the framing is byte-identical and the file brings its own
+ * schema (D1's whole thesis).
+ *
+ * So the version was refusing valid files while predicting nothing. What
+ * actually gates correctness is STRUCTURE, all of it still enforced: the
+ * prelude, exactly two chunks with zero trailing bytes, a raw-deflate schema
+ * that parses and consumes every byte, the zstd magic, STRICT root resolution
+ * (exactly one `Message` of kind MESSAGE with a `nodeChanges: NodeChange[]`),
+ * and a data chunk that decodes with nothing left over. A file passing all of
+ * those is a Figma document whatever integer sits in bytes 8–11.
+ *
+ * The version is reported instead, and an unobserved one is worth noticing —
+ * see `FigDecodeReport.containerVersion` and the schema-hash alarm (D8).
+ */
+export const OBSERVED_CONTAINER_VERSIONS: ReadonlySet<number> = new Set([101, 106]);
+
+/** ~1 500x the measured 42 KB. */
+export const MAX_CANVAS_FIG_BYTES = 64 * 1024 * 1024;
+/** 2 observed. */
+export const MAX_CHUNKS = 8;
+/** ~117x the measured 71 777 B. */
+export const MAX_SCHEMA_BYTES = 8 * 1024 * 1024;
+/** ~1 000x the measured 67 207 B. */
+export const MAX_DATA_BYTES = 64 * 1024 * 1024;
+
+const CANVAS_ENTRY = 'canvas.fig';
+const META_ENTRY = 'meta.json';
+
+export class FigDecodeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FigDecodeError';
+  }
+}
+
+export interface FigContainer {
+  surface: 'design' | 'board';
+  prelude: string;
+  version: number;
+  schema: Uint8Array;
+  data: Uint8Array;
+  /**
+   * `sha256` of the COMPRESSED schema chunk. Stable and shared across editor
+   * types, so a change is an early drift warning that fires before anything
+   * breaks (DDR-221 D8).
+   */
+  schemaSha256: string;
+}
+
+export interface FigDecodeReport {
+  /** Observed, not validated. See `OBSERVED_CONTAINER_VERSIONS`. */
+  containerVersion: number;
+  /** True when this version is one we have seen before — a soft drift signal. */
+  containerVersionKnown: boolean;
+  schemaSha256: string;
+  /** From `meta.json`. Makes a dated fixture corpus self-labelling. */
+  exportedAt?: string;
+  nodeCount: number;
+  /**
+   * Node types the file carried that `FigmaNodeType` has no member for.
+   * `reportToken`-bounded: one lowercase token, never spaces (DDR-221 A8/F1).
+   */
+  unmappedTypes: Array<{ type: string; count: number }>;
+  /** Nodes dropped because Figma marks them internal (e.g. the hidden canvas). */
+  internalNodesSkipped: number;
+  /**
+   * Fields this door CANNOT reproduce from a local file, with how many nodes
+   * each affected. Reported rather than left implicit: the plan's bar is that
+   * known-lossy fields are named, never silently degraded.
+   */
+  lossyFields: Array<{ field: string; count: number; why: string }>;
+}
+
+export interface FigDecodeResult {
+  document: NormalizedDocument;
+  report: FigDecodeReport;
+  /**
+   * Vector geometry the archive carries, by node id. Kept OUT of the normalized
+   * tree on purpose: REST has no equivalent, so putting it there would make the
+   * Tier-2 differential diverge for a field the REST door cannot produce. The
+   * local importer reads this to build SVGs without asking Figma to render.
+   */
+  vectors: Map<string, VectorPath>;
+}
+
+function u32le(b: Uint8Array, o: number): number {
+  return (b[o] | (b[o + 1] << 8) | (b[o + 2] << 16) | (b[o + 3] << 24)) >>> 0;
+}
+
+function decompress(chunk: Uint8Array, kind: 'schema' | 'data', max: number): Uint8Array {
+  try {
+    // maxOutputLength is enforced BY the codec, so a bomb never allocates
+    // (DDR-221 D4, measured: a 28 533:1 zstd bomb throws instead of expanding).
+    return kind === 'schema'
+      ? inflateRawSync(chunk, { maxOutputLength: max })
+      : zstdDecompressSync(chunk, { maxOutputLength: max });
+  } catch (err) {
+    if ((err as { code?: string }).code === 'ERR_BUFFER_TOO_LARGE') {
+      throw new FigDecodeError(`the ${kind} chunk decompresses past the ${max}-byte limit`);
+    }
+    throw new FigDecodeError(
+      kind === 'schema'
+        ? 'the schema chunk is not raw-deflate data'
+        : 'the data chunk is not zstd data'
+    );
+  }
+}
+
+/**
+ * Read `canvas.fig`'s framing. Every failure here refuses the file and names
+ * the observed value, so diagnosis is one line rather than an afternoon.
+ */
+export function readFigContainer(bytes: Uint8Array): FigContainer {
+  if (bytes.length > MAX_CANVAS_FIG_BYTES) {
+    throw new FigDecodeError(
+      `canvas.fig is ${bytes.length} bytes, over the ${MAX_CANVAS_FIG_BYTES}-byte limit`
+    );
+  }
+  if (bytes.length < 12)
+    throw new FigDecodeError('canvas.fig is too short to be a Figma container');
+
+  const prelude = new TextDecoder('latin1').decode(bytes.subarray(0, 8));
+  const surface = PRELUDES[prelude];
+  if (!surface) {
+    // The observed bytes are attacker-chosen; hex keeps them inert in a report.
+    const hex = Array.from(bytes.subarray(0, 8), (b) => b.toString(16).padStart(2, '0')).join(' ');
+    throw new FigDecodeError(`unrecognised Figma container prelude (bytes: ${hex})`);
+  }
+
+  // Read, reported, NOT gated — see OBSERVED_CONTAINER_VERSIONS for why the
+  // allowlist was removed. Structure gates; the integer does not.
+  const version = u32le(bytes, 8);
+
+  const chunks: Uint8Array[] = [];
+  let offset = 12;
+  while (offset + 4 <= bytes.length) {
+    const len = u32le(bytes, offset);
+    offset += 4;
+    if (offset + len > bytes.length) {
+      throw new FigDecodeError(
+        `chunk ${chunks.length} declares ${len} bytes past the end of canvas.fig`
+      );
+    }
+    chunks.push(bytes.subarray(offset, offset + len));
+    offset += len;
+    if (chunks.length > MAX_CHUNKS) {
+      throw new FigDecodeError(`canvas.fig declares more than ${MAX_CHUNKS} chunks`);
+    }
+  }
+
+  if (chunks.length !== 2) {
+    throw new FigDecodeError(`canvas.fig has ${chunks.length} chunks, expected exactly 2`);
+  }
+  if (offset !== bytes.length) {
+    throw new FigDecodeError(`canvas.fig has ${bytes.length - offset} trailing bytes`);
+  }
+
+  // The zstd magic is checked up front so a swapped chunk order refuses with a
+  // clear message instead of a confusing inflate failure.
+  const d = chunks[1];
+  if (!(d.length >= 4 && d[0] === 0x28 && d[1] === 0xb5 && d[2] === 0x2f && d[3] === 0xfd)) {
+    throw new FigDecodeError('the data chunk is missing its zstd magic');
+  }
+
+  return {
+    surface,
+    prelude,
+    version,
+    schema: decompress(chunks[0], 'schema', MAX_SCHEMA_BYTES),
+    data: decompress(chunks[1], 'data', MAX_DATA_BYTES),
+    schemaSha256: createHash('sha256').update(chunks[0]).digest('hex'),
+  };
+}
+
+// ── Tree reconstruction ─────────────────────────────────────────────────────
+
+interface Matrix {
+  m00: number;
+  m01: number;
+  m02: number;
+  m10: number;
+  m11: number;
+  m12: number;
+}
+
+const IDENTITY: Matrix = { m00: 1, m01: 0, m02: 0, m10: 0, m11: 1, m12: 0 };
+
+function num(v: unknown): number | undefined {
+  return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === 'string' ? v : undefined;
+}
+
+function obj(v: unknown): Record<string, unknown> | undefined {
+  return typeof v === 'object' && v !== null && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : undefined;
+}
+
+/**
+ * ABSENT is not the same as NaN. A missing `transform` legitimately means the
+ * identity, but a component that is PRESENT and non-finite is a crafted or
+ * corrupt file: defaulting it to the identity yields plausible-but-wrong
+ * geometry with no error signal, which is the exact failure D3 exists to
+ * prevent (and the same shape as the A4 float trap). Refuse instead.
+ */
+function component(v: unknown, fallback: number, name: string): number {
+  if (v === undefined) return fallback;
+  const n = num(v);
+  if (n === undefined)
+    throw new FigDecodeError(`transform component ${name} is not a finite number`);
+  return n;
+}
+
+function matrixOf(v: unknown): Matrix {
+  const m = obj(v);
+  if (!m) return IDENTITY;
+  return {
+    m00: component(m.m00, 1, 'm00'),
+    m01: component(m.m01, 0, 'm01'),
+    m02: component(m.m02, 0, 'm02'),
+    m10: component(m.m10, 0, 'm10'),
+    m11: component(m.m11, 1, 'm11'),
+    m12: component(m.m12, 0, 'm12'),
+  };
+}
+
+function compose(p: Matrix, c: Matrix): Matrix {
+  return {
+    m00: p.m00 * c.m00 + p.m01 * c.m10,
+    m01: p.m00 * c.m01 + p.m01 * c.m11,
+    m02: p.m00 * c.m02 + p.m01 * c.m12 + p.m02,
+    m10: p.m10 * c.m00 + p.m11 * c.m10,
+    m11: p.m10 * c.m01 + p.m11 * c.m11,
+    m12: p.m10 * c.m02 + p.m11 * c.m12 + p.m12,
+  };
+}
+
+/**
+ * `.fig` geometry is a parent-relative affine transform plus a size; REST
+ * reports an absolute axis-aligned box. Composing down the parent chain is one
+ * of the two places the two doors can legitimately disagree, so it is also one
+ * of the two things the Tier-2 differential exists to check (DDR-221 A3).
+ */
+function absoluteBox(m: Matrix, w: number, h: number) {
+  const xs = [m.m02, m.m00 * w + m.m02, m.m01 * h + m.m02, m.m00 * w + m.m01 * h + m.m02];
+  const ys = [m.m12, m.m10 * w + m.m12, m.m11 * h + m.m12, m.m10 * w + m.m11 * h + m.m12];
+  const x = Math.min(...xs);
+  const y = Math.min(...ys);
+  return { x, y, width: Math.max(...xs) - x, height: Math.max(...ys) - y };
+}
+
+function guidOf(v: unknown): string | undefined {
+  const g = obj(v);
+  if (!g) return undefined;
+  const s = num(g.sessionID);
+  const l = num(g.localID);
+  return s === undefined || l === undefined ? undefined : `${s}:${l}`;
+}
+
+/**
+ * Map ONE decoded `NodeChange` onto REST-shaped fields.
+ *
+ * Reads a HARDCODED list of field names and never iterates the decoded
+ * object's own keys (DDR-221 A8/F5) — field names come from the attacker's
+ * schema, so a generic copy would let them choose which REST field each value
+ * lands in (`absoluteBoundingBox`, `characters`, `children`).
+ */
+/**
+ * `.fig` carries Figma's INTERNAL node vocabulary; REST reports the public one,
+ * and the translators are written against REST. Measured by the Tier-2
+ * differential on the fixtures — the unit tests could not have found this,
+ * because both sides of an internal-vocabulary mismatch look perfectly valid.
+ *
+ * A GROUP is internally a FRAME with `resizeToFit` (shrink-wrap to children);
+ * that flag is the discriminator, 5/5 on the design fixture and 1/1 on the
+ * board. `ROUNDED_RECTANGLE` collapses to `RECTANGLE` (the radius survives in
+ * `cornerRadius`), and `SYMBOL` is Figma's internal name for a `COMPONENT`.
+ */
+function restType(change: Record<string, unknown>): string | undefined {
+  const type = str(change.type);
+  if (type === 'FRAME' && change.resizeToFit === true) return 'GROUP';
+  if (type === 'ROUNDED_RECTANGLE') return 'RECTANGLE';
+  if (type === 'SYMBOL') return 'COMPONENT';
+  return type;
+}
+
+/**
+ * Pull a FigJam node's text out of its template overrides. Reads only the
+ * hardcoded `nodeGenerationData.overrides[].textData.characters` path (A8/F5) —
+ * the override list is attacker-controlled, so it is walked, never spread — and
+ * takes the first entry that carries characters, which is what REST reports as
+ * the node's own `characters`.
+ */
+/**
+ * `.fig` identifies an image fill by a 20-byte `image.hash`; REST calls the same
+ * thing `imageRef` and states it as hex. Measured on a real export: the hex IS
+ * the archive entry name (`images/<hex>`), which is what makes D6's "images
+ * travel inside the file" resolvable with no network at all.
+ *
+ * Only that one field is added — the paint is otherwise passed through for
+ * `normalizeDocument` to sanitize, exactly like the REST door's paints.
+ */
+function toRestPaint(paint: unknown): unknown {
+  const p = obj(paint);
+  if (!p || p.imageRef !== undefined) return paint;
+  const hash = obj(p.image)?.hash;
+  if (!Array.isArray(hash) || hash.length === 0 || hash.length > 64) return paint;
+  let hex = '';
+  for (const byte of hash) {
+    const n = num(byte);
+    if (n === undefined || n < 0 || n > 255 || !Number.isInteger(n)) return paint;
+    hex += n.toString(16).padStart(2, '0');
+  }
+  return { ...p, imageRef: hex };
+}
+
+function overrides(change: Record<string, unknown>): unknown[] {
+  const list = obj(change.nodeGenerationData)?.overrides;
+  return Array.isArray(list) ? list : [];
+}
+
+/**
+ * First override carrying `key`. The template's own root comes first, so this
+ * resolves to the node's own paint/text rather than a sub-part's.
+ *
+ * The ordering is an OBSERVED property, not a documented one — which is exactly
+ * why the Tier-3 comparison is the guard: if Figma ever reorders these, the
+ * translator diff against REST fails loudly instead of quietly picking the
+ * wrong colour. Only hardcoded keys are read (A8/F5).
+ */
+function fromOverrides(change: Record<string, unknown>, key: string): unknown {
+  for (const entry of overrides(change)) {
+    const value = obj(entry)?.[key];
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+function overrideText(change: Record<string, unknown>): string | undefined {
+  for (const entry of overrides(change)) {
+    const characters = str(obj(obj(entry)?.textData)?.characters);
+    if (characters !== undefined) return characters;
+  }
+  return undefined;
+}
+
+function toRestNode(
+  change: Record<string, unknown>,
+  absolute: Matrix,
+  lossy: { lineHeights: number }
+): Record<string, unknown> {
+  const size = obj(change.size);
+  const w = num(size?.x) ?? 0;
+  const h = num(size?.y) ?? 0;
+
+  const raw: Record<string, unknown> = {
+    id: guidOf(change.guid),
+    type: restType(change),
+    name: str(change.name) ?? '',
+    visible: change.visible !== false,
+    absoluteBoundingBox: absoluteBox(absolute, w, h),
+  };
+
+  const opacity = num(change.opacity);
+  if (opacity !== undefined) raw.opacity = opacity;
+  const blend = str(change.blendMode);
+  if (blend) raw.blendMode = blend;
+  const cornerRadius = num(change.cornerRadius);
+  if (cornerRadius !== undefined) raw.cornerRadius = cornerRadius;
+  const strokeWeight = num(change.strokeWeight);
+  if (strokeWeight !== undefined) raw.strokeWeight = strokeWeight;
+  // A FigJam STICKY / SHAPE_WITH_TEXT is a template instance: its own paint is
+  // an override, not a top-level field. Reading only the top level left every
+  // board node on the translator's default colour (found by Tier 3).
+  const fills = change.fillPaints ?? fromOverrides(change, 'fillPaints');
+  if (Array.isArray(fills)) raw.fills = fills.map(toRestPaint);
+  const strokes = change.strokePaints ?? fromOverrides(change, 'strokePaints');
+  if (Array.isArray(strokes)) raw.strokes = strokes;
+  if (Array.isArray(change.effects)) raw.effects = change.effects;
+
+  // Auto-layout. `.fig` calls it `stack*`; REST calls it `layout*`.
+  const stackMode = str(change.stackMode);
+  if (stackMode === 'HORIZONTAL' || stackMode === 'VERTICAL') {
+    raw.layoutMode = stackMode;
+    const spacing = num(change.stackSpacing);
+    if (spacing !== undefined) raw.itemSpacing = spacing;
+    const hPad = num(change.stackHorizontalPadding);
+    const vPad = num(change.stackVerticalPadding);
+    if (hPad !== undefined) {
+      raw.paddingLeft = hPad;
+      raw.paddingRight = hPad;
+    }
+    if (vPad !== undefined) {
+      raw.paddingTop = vPad;
+      raw.paddingBottom = vPad;
+    }
+    const primary = str(change.stackPrimaryAlignItems);
+    if (primary) raw.primaryAxisAlignItems = primary;
+    const counter = str(change.stackCounterAlignItems);
+    if (counter) raw.counterAxisAlignItems = counter;
+  }
+
+  // Text. Two storage locations, and the second one is not optional:
+  //  - a design-file TEXT node carries `textData.characters` directly;
+  //  - a FigJam STICKY / SHAPE_WITH_TEXT is an instance of an internal
+  //    template, and its text is an OVERRIDE on a sub-node, under
+  //    `nodeGenerationData.overrides[].textData.characters`.
+  // Missing the second path lost the text of every sticky and every shape on
+  // the board while the tree still looked perfect — found by the Tier-2
+  // differential (20 nodes), invisible to every unit test.
+  const characters = str(obj(change.textData)?.characters) ?? overrideText(change);
+  if (characters !== undefined) raw.characters = characters;
+  const fontSize = num(change.fontSize);
+  const fontName = obj(change.fontName);
+  if (fontSize !== undefined || fontName || characters !== undefined) {
+    // `.fig` encodes typography sparsely and semantically; REST reports it
+    // resolved. Three deltas, all found by the Tier-3 translator comparison:
+    //  - weight lives in the font STYLE name ("Bold"), not a number — reuse the
+    //    codegen lane's map rather than keeping a second one;
+    //  - a default alignment is OMITTED, where REST always states it;
+    //  - lineHeight is authored ({value, units}), and REST reports the RESOLVED
+    //    pixel value. A PERCENT line-height cannot be resolved to px without
+    //    font metrics we do not have offline, so it is carried only when the
+    //    file already states pixels. This is the local door's one genuinely
+    //    lossy typography field and it is asserted as lossy in the Tier-3 test.
+    const lineHeight = obj(change.lineHeight);
+    const lineHeightPx = str(lineHeight?.units) === 'PIXELS' ? num(lineHeight?.value) : undefined;
+    if (lineHeight && lineHeightPx === undefined) lossy.lineHeights++;
+    raw.style = {
+      fontSize,
+      fontFamily: str(fontName?.family),
+      fontPostScriptName: str(fontName?.postscript),
+      fontWeight: styleToWeight(str(fontName?.style) ?? null) ?? undefined,
+      textAlignHorizontal: str(change.textAlignHorizontal) ?? 'LEFT',
+      ...(lineHeightPx !== undefined ? { lineHeightPx } : {}),
+    };
+  }
+
+  // FigJam.
+  const shapeType = str(change.shapeWithTextType);
+  if (shapeType) raw.shapeType = shapeType;
+  // REST wraps an endpoint as `{ endpointNodeId }` (lowercase d) and the
+  // normalizer unwraps it; `.fig` carries a GUID struct under `endpointNodeID`
+  // (uppercase D). Emit REST's shape so the SHARED normalizer resolves it —
+  // handing it a bare string silently yields an unbound connector.
+  const start = guidOf(obj(change.connectorStart)?.endpointNodeID);
+  if (start) raw.connectorStart = { endpointNodeId: start };
+  const end = guidOf(obj(change.connectorEnd)?.endpointNodeID);
+  if (end) raw.connectorEnd = { endpointNodeId: end };
+  const startCap = str(change.connectorStartCap);
+  if (startCap) raw.connectorStartCap = startCap;
+  const endCap = str(change.connectorEndCap);
+  if (endCap) raw.connectorEndCap = endCap;
+  const lineStyle = str(change.connectorLineStyle);
+  if (lineStyle) raw.connectorLineType = lineStyle;
+
+  return raw;
+}
+
+/**
+ * A PERCENT line-height cannot be resolved to pixels without font metrics, and
+ * REST reports the resolved value. Counted per node so the import summary can
+ * say so out loud (the only lossy typography field — Tier 3 asserts it is).
+ */
+const LOSSY_LINE_HEIGHT = {
+  field: 'style.lineHeightPx',
+  why: 'a percent line-height needs font metrics the local file does not carry',
+};
+
+/**
+ * Read one node's own path geometry, if it has any.
+ *
+ * A decode failure DEGRADES to "no vector" rather than refusing the document:
+ * a single unreadable icon should not cost the whole import, and the caller
+ * reports the absence. That is the one place the fail-loud rule bends, and it
+ * bends toward reporting rather than toward guessing at the shape.
+ */
+function vectorOf(change: Record<string, unknown>, blobs: readonly unknown[]): VectorPath | null {
+  const geometry = change.fillGeometry;
+  if (!Array.isArray(geometry) || geometry.length === 0) return null;
+  const first = obj(geometry[0]);
+  const index = num(first?.commandsBlob);
+  if (index === undefined || index < 0 || index >= blobs.length) return null;
+
+  const raw = obj(blobs[index])?.bytes;
+  const bytes =
+    raw instanceof Uint8Array ? raw : Array.isArray(raw) ? Uint8Array.from(raw as number[]) : null;
+  if (!bytes) return null;
+
+  let d: string;
+  try {
+    d = pathFromBlob(bytes);
+  } catch {
+    return null;
+  }
+
+  const paint = (Array.isArray(change.fillPaints) ? change.fillPaints : []).find(
+    (p) => obj(p)?.type === 'SOLID' && obj(p)?.visible !== false
+  );
+  const colour = obj(obj(paint)?.color);
+  const hex =
+    colour === undefined
+      ? null
+      : `#${(['r', 'g', 'b'] as const)
+          .map((k) => {
+            const v = num(colour[k]) ?? 0;
+            return Math.max(0, Math.min(255, Math.round(v * 255)))
+              .toString(16)
+              .padStart(2, '0');
+          })
+          .join('')}`;
+
+  return {
+    d,
+    fill: hex,
+    fillOpacity: num(obj(paint)?.opacity) ?? 1,
+    fillRule: str(first?.windingRule) === 'EVENODD' ? 'evenodd' : 'nonzero',
+    x: 0,
+    y: 0,
+  };
+}
+
+interface RebuildResult {
+  root: Record<string, unknown>;
+  unmapped: Map<string, number>;
+  internalSkipped: number;
+  nodeCount: number;
+  lossyLineHeights: number;
+  vectors: Map<string, VectorPath>;
+}
+
+/**
+ * Rebuild the tree from `parentIndex`. A `.fig` is a FLAT `nodeChanges[]`, not
+ * a nested document (DDR-221 A3), and this reconstruction is a SECOND recursion
+ * that the Kiwi decode-depth cap does not bound (A8/F4) — hence the explicit
+ * cycle, duplicate, orphan and single-root controls here.
+ */
+function rebuildTree(changes: unknown[], blobs: readonly unknown[]): RebuildResult {
+  if (changes.length > MAX_NODE_COUNT) {
+    throw new FigDecodeError(
+      `file carries ${changes.length} nodes, over the ${MAX_NODE_COUNT} limit. Import a specific frame instead.`
+    );
+  }
+
+  const byId = new Map<string, Record<string, unknown>>();
+  const order: string[] = [];
+
+  for (const entry of changes) {
+    const change = obj(entry);
+    if (!change) throw new FigDecodeError('a node change is not an object');
+    const id = guidOf(change.guid);
+    if (!id) throw new FigDecodeError('a node change has no usable guid');
+    if (byId.has(id)) throw new FigDecodeError(`duplicate node guid ${id}`);
+    // Internal-only nodes are NOT removed here. Dropping them before parentage
+    // is resolved would orphan their children and refuse a legitimate file —
+    // the fixtures' internal canvas happens to be childless, which is why this
+    // looked safe. They are pruned as whole subtrees during the walk instead.
+    byId.set(id, change);
+    order.push(id);
+  }
+
+  const childIds = new Map<string, string[]>();
+  const roots: string[] = [];
+  for (const id of order) {
+    const change = byId.get(id) as Record<string, unknown>;
+    const parentIndex = obj(change.parentIndex);
+    const parent = guidOf(parentIndex?.guid);
+    if (parent === undefined) {
+      roots.push(id);
+      continue;
+    }
+    if (parent === id) throw new FigDecodeError(`node ${id} is its own parent`);
+    if (!byId.has(parent)) {
+      // Not silently dropped: an orphan means we misread the file or the file
+      // is crafted, and either way a partial tree is the wrong outcome.
+      throw new FigDecodeError(`node ${id} references parent ${parent}, which is not in the file`);
+    }
+    const siblings = childIds.get(parent);
+    if (siblings) siblings.push(id);
+    else childIds.set(parent, [id]);
+  }
+
+  if (roots.length !== 1) {
+    throw new FigDecodeError(`file has ${roots.length} root nodes, expected exactly 1`);
+  }
+
+  // Fractional-index ordering. Plain comparison, not `localeCompare`: the
+  // strings are attacker-controlled and locale collation on 20k items is both
+  // slow and locale-dependent.
+  for (const siblings of childIds.values()) {
+    siblings.sort((a, b) => {
+      const pa = str(obj(byId.get(a)?.parentIndex)?.position) ?? '';
+      const pb = str(obj(byId.get(b)?.parentIndex)?.position) ?? '';
+      return pa < pb ? -1 : pa > pb ? 1 : 0;
+    });
+  }
+
+  const unmapped = new Map<string, number>();
+  const onStack = new Set<string>();
+  const vectors = new Map<string, VectorPath>();
+  const lossy = { lineHeights: 0 };
+  let nodeCount = 0;
+  let internalSkipped = 0;
+
+  /** Count a pruned internal subtree so the report says how much was dropped. */
+  const countSubtree = (id: string, seen: Set<string>): number => {
+    if (seen.has(id)) return 0;
+    seen.add(id);
+    let n = 1;
+    for (const kid of childIds.get(id) ?? []) n += countSubtree(kid, seen);
+    return n;
+  };
+
+  const build = (id: string, parentAbsolute: Matrix, depth: number): Record<string, unknown> => {
+    // Cycle detection. A→B→A would otherwise recurse until the stack dies.
+    if (onStack.has(id)) throw new FigDecodeError(`node parentage forms a cycle at ${id}`);
+    onStack.add(id);
+
+    const change = byId.get(id) as Record<string, unknown>;
+    const absolute = compose(parentAbsolute, matrixOf(change.transform));
+    const node = toRestNode(change, absolute, lossy);
+    nodeCount++;
+
+    const art = vectorOf(change, blobs);
+    if (art) vectors.set(String(node.id), art);
+
+    const type = node.type;
+    if (typeof type !== 'string' || !KNOWN_NODE_TYPES.has(type)) {
+      // Vocabulary gap: degrade and report (D3). The raw string is left in
+      // place so the SHARED normalizer maps it to 'UNKNOWN' — this door does
+      // not get its own opinion about the vocabulary (A5). Only the REPORT
+      // label is produced here, and it is BOUNDED because the type name comes
+      // from the attacker's schema (A8/F1).
+      // `reportToken`, NOT `attrValue`: attrValue maps rejected characters to
+      // SPACES, so a 32-char bound still yields readable prose — measured, the
+      // test for this control failed against attrValue first. One token, no
+      // spaces, or the fixed word `unrecognized`.
+      const label = reportToken(typeof type === 'string' ? type : '');
+      unmapped.set(label, (unmapped.get(label) ?? 0) + 1);
+    }
+
+    const kids = childIds.get(id);
+    if (kids?.length) {
+      const kept: Array<Record<string, unknown>> = [];
+      for (const kid of kids) {
+        // Prune Figma's internal-only nodes as WHOLE SUBTREES here, where the
+        // parentage is already resolved, rather than dropping them up front.
+        if (byId.get(kid)?.internalOnly === true) {
+          internalSkipped += countSubtree(kid, new Set());
+          continue;
+        }
+        kept.push(build(kid, absolute, depth + 1));
+      }
+      if (kept.length > 0) node.children = kept;
+    }
+
+    onStack.delete(id);
+    return node;
+  };
+
+  if (byId.get(roots[0])?.internalOnly === true) {
+    throw new FigDecodeError('the document root is marked internal-only');
+  }
+  const root = build(roots[0], IDENTITY, 0);
+  return {
+    root,
+    unmapped,
+    internalSkipped,
+    nodeCount,
+    lossyLineHeights: lossy.lineHeights,
+    vectors,
+  };
+}
+
+// ── The door ────────────────────────────────────────────────────────────────
+
+export interface DecodeFigOptions {
+  /** Charset-validated upstream. Provenance only — never derived from the file. */
+  fileKey: string;
+}
+
+/**
+ * Decode a `.fig` / `.jam` archive into the normalized tree both doors share.
+ */
+export function decodeFigArchive(archive: Uint8Array, opts: DecodeFigOptions): FigDecodeResult {
+  // Both the directory parse AND the lazy per-entry read can refuse, and a
+  // caller of this door should only ever have to catch FigDecodeError. Wrapping
+  // just the first call let a FigZipError escape from `get()` — caught by the
+  // fuzz corpus, which is exactly the class of leak it exists to find.
+  let zip: ReturnType<typeof readFigZip>;
+  let canvas: Uint8Array | undefined;
+  try {
+    zip = readFigZip(archive);
+    canvas = zip.get(CANVAS_ENTRY);
+  } catch (err) {
+    if (err instanceof FigZipError) throw new FigDecodeError(err.message);
+    throw err;
+  }
+
+  if (!canvas) throw new FigDecodeError(`archive has no ${CANVAS_ENTRY} entry`);
+
+  const container = readFigContainer(canvas);
+
+  let schema: KiwiSchema;
+  let message: Record<string, unknown> | undefined;
+  try {
+    schema = parseKiwiSchema(container.schema);
+    const rootIndex = findRootDefinition(schema, 'Message', 'nodeChanges', 'NodeChange');
+    message = obj(decodeKiwi(container.data, schema, rootIndex));
+  } catch (err) {
+    throw new FigDecodeError(`could not decode canvas.fig: ${(err as Error).message}`);
+  }
+
+  const changes = message?.nodeChanges;
+  if (!Array.isArray(changes) || changes.length === 0) {
+    throw new FigDecodeError('canvas.fig carries no node changes');
+  }
+
+  const blobs = Array.isArray(message?.blobs) ? message.blobs : [];
+  const { root, unmapped, internalSkipped, nodeCount, lossyLineHeights, vectors } = rebuildTree(
+    changes,
+    blobs
+  );
+
+  const document = normalizeDocument(root, {
+    fileKey: opts.fileKey,
+    surface: container.surface,
+    origin: 'fig',
+  });
+
+  return {
+    document,
+    vectors,
+    report: {
+      containerVersion: container.version,
+      containerVersionKnown: OBSERVED_CONTAINER_VERSIONS.has(container.version),
+      schemaSha256: container.schemaSha256,
+      exportedAt: readExportedAt(safeEntry(zip, META_ENTRY)),
+      nodeCount,
+      unmappedTypes: [...unmapped.entries()]
+        .map(([type, count]) => ({ type, count }))
+        .sort((a, b) => b.count - a.count),
+      internalNodesSkipped: internalSkipped,
+      lossyFields: lossyLineHeights > 0 ? [{ ...LOSSY_LINE_HEIGHT, count: lossyLineHeights }] : [],
+    },
+  };
+}
+
+/**
+ * `meta.json` is optional and its bytes are lazily verified, so a corrupt entry
+ * must not turn a decodable document into a hard failure — nor let a
+ * FigZipError escape this door's error type.
+ */
+function safeEntry(zip: ReturnType<typeof readFigZip>, name: string): Uint8Array | undefined {
+  try {
+    return zip.get(name);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Read `exported_at` (Tier 4 needs it) and DELIBERATELY DROP `file_name`, which
+ * sits in the same object: DDR-216 D7 forbids recording the Figma file NAME
+ * anywhere an agent later reads (DDR-221 A6). The REST door never had it to
+ * hand; this one must decline it explicitly.
+ */
+function readExportedAt(metaBytes: Uint8Array | undefined): string | undefined {
+  if (!metaBytes) return undefined;
+  try {
+    const meta = obj(JSON.parse(new TextDecoder().decode(metaBytes)));
+    const exportedAt = str(meta?.exported_at);
+    if (!exportedAt) return undefined;
+    // Bounded and charset-checked: it is untrusted text from the archive.
+    return /^[0-9TZ:.-]{1,32}$/.test(exportedAt) ? exportedAt : undefined;
+  } catch {
+    return undefined;
+  }
+}