@1agh/maude 1.0.9 → 1.2.0

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

@@ -1,182 +0,0 @@
-// 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

@@ -1,192 +0,0 @@
-// 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

@@ -1,113 +0,0 @@
-// 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"');
-  });
-});