@1agh/maude 0.58.3 → 0.59.0

package/apps/studio/figma/sanitize.test.ts

@@ -7,16 +7,20 @@
 
 import { describe, expect, test } from 'bun:test';
 
+import { ASSET_DISPOSITIONS } from './assets.ts';
 import {
   attrValue,
   clampIntoBounds,
   cleanText,
   contrastRatio,
+  DISPOSITIONS,
   ensureContrast,
   ensureFontSize,
   hexToRgb01,
   ImportReport,
   identifierFromNodeId,
+  isCodeOwnedDetail,
+  isDisposition,
   jsxStringLiteral,
   MIN_FONT_SIZE,
   rgb01ToHex,
@@ -254,3 +258,68 @@ describe('D6a covers blank-glyph LETTERS, not just format characters (review F10
     expect(out.strippedHidden).toBe(true);
   });
 });
+
+// ── DDR-219 D9 — the fixed-enum promise is a CONTROL, not a comment ──────────
+//
+// `Disposition` was a bare union, i.e. a compile-time promise, in a repo that
+// runs no `tsc` gate. `assets.ts` shipped an off-enum `'asset-degraded'` to
+// main — onto the wire, into verb stdout an agent reads (DDR-216 D10) and into
+// the panel. These tests are what makes the promise true at runtime.
+
+describe('DDR-219 D9 — disposition enum is enforced, not asserted', () => {
+  test('every disposition assets.ts declares is a member', () => {
+    // The drift that shipped: ASSET_DISPOSITIONS and the union disagreed, and
+    // nothing compared them.
+    for (const d of ASSET_DISPOSITIONS) expect(isDisposition(d)).toBe(true);
+  });
+
+  test('asset-degraded is a member — the specific drift found in main', () => {
+    expect(isDisposition('asset-degraded')).toBe(true);
+    expect(() => new ImportReport().add('1:2', 'ASSET', 'asset-degraded')).not.toThrow();
+  });
+
+  test('an invented disposition throws rather than reaching the wire', () => {
+    const r = new ImportReport();
+    // @ts-expect-error — the runtime backstop for exactly what tsc would catch
+    expect(() => r.add('1:2', 'ASSET', 'asset-vanished')).toThrow(/unknown disposition/);
+    expect(r.entries).toHaveLength(0);
+  });
+
+  test('DISPOSITIONS is frozen — a caller cannot widen the set at runtime', () => {
+    expect(Object.isFrozen(DISPOSITIONS)).toBe(true);
+  });
+
+  test('every real detail in the codebase satisfies the code-owned rule', () => {
+    // Non-ASCII is legitimate here — real notes carry em-dash and arrow. What
+    // separates a code-owned note from interpolated node text is length and the
+    // absence of a zero-glyph payload.
+    for (const d of [
+      'vector unavailable — rasterized',
+      'group → groupIds tag',
+      'page has no frames — rendered whole',
+      'loose content wrapped in one artboard',
+    ])
+      expect(isCodeOwnedDetail(d)).toBe(true);
+  });
+
+  test('detail rejects an interpolated upstream string', () => {
+    const r = new ImportReport();
+    // A Figma layer name is exactly what must never ride out in `detail`.
+    const layerName = 'V4 — Airy / light — Property 1=Cisty-a-zeleny-kraj 1 — Úprava 3d modelu';
+    expect(() => r.add('1:2', 'FRAME', 'imported', layerName)).toThrow(/code-owned/);
+  });
+
+  test('detail rejects a zero-glyph payload even when short', () => {
+    const r = new ImportReport();
+    expect(() => r.add('1:2', 'FRAME', 'imported', `ok\u{E0041}`)).toThrow(/code-owned/);
+  });
+
+  test('the zero-glyph predicate is not stateful across calls', () => {
+    // ZERO_GLYPH_RE carries `g`, so `.test()` on THAT instance alternates
+    // true/false via lastIndex. The one-shot predicate must not share it.
+    const dirty = 'a​b';
+    expect(isCodeOwnedDetail(dirty)).toBe(false);
+    expect(isCodeOwnedDetail(dirty)).toBe(false);
+    expect(isCodeOwnedDetail(dirty)).toBe(false);
+  });
+});

package/apps/studio/figma/sanitize.ts

@@ -39,28 +39,81 @@
  * @invariant  DEPENDENCY-FREE — pure string/number work.
  */
 
-/** Every disposition this feature can report. A FIXED enum: the per-import
+/** Every disposition this feature can report. A FIXED set: the per-import
  *  summary's "never silently dropped" promise is only true because a caller
- *  cannot invent a reason string (DDR-216 D5/D7). */
-export type Disposition =
-  | 'imported'
-  | 'hidden-chars-dropped'
-  | 'hidden-node-skipped'
-  | 'text-normalized'
-  | 'geometry-clamped'
-  | 'truncated-text'
-  | 'truncated-attr'
-  | 'unmappable-type'
-  | 'unmappable-shape'
+ *  cannot invent a reason string (DDR-216 D5/D7).
+ *
+ *  A frozen ARRAY, with the type derived from it, rather than a bare union —
+ *  because a union alone is a compile-time promise and this repo runs **no
+ *  `tsc` gate** (CLAUDE.md states the omission deliberately: `quality` is
+ *  lint/tests/build/parity/tarball/tokens/site-content, no typecheck). That gap
+ *  is not hypothetical: `assets.ts` shipped `'asset-degraded'` — absent from the
+ *  union — to `main`, onto the wire (`http.ts` `/_api/figma/import`), into verb
+ *  stdout that an agent reads (D10), and into `FigmaImportPanel`. Found by the
+ *  DDR-219 design-stage review, fixed here with `asset-degraded` admitted as the
+ *  legitimate outcome it always was. See DDR-219 D9. */
+export const DISPOSITIONS = Object.freeze([
+  'imported',
+  'hidden-chars-dropped',
+  'hidden-node-skipped',
+  'text-normalized',
+  'geometry-clamped',
+  'truncated-text',
+  'truncated-attr',
+  'unmappable-type',
+  'unmappable-shape',
   /** A comment whose pinned node no longer exists in the file — no position to place it at. */
-  | 'comment-target-deleted'
-  | 'bind-degraded-to-bbox'
-  | 'bind-dropped-self-connector'
-  | 'asset-pending'
-  | 'asset-skipped'
-  | 'asset-cap-reached'
-  | 'jsx-cap-reached'
-  | 'value-rejected';
+  'comment-target-deleted',
+  'bind-degraded-to-bbox',
+  'bind-dropped-self-connector',
+  'asset-pending',
+  'asset-skipped',
+  'asset-cap-reached',
+  /** A vector Figma declined to render as SVG, re-requested as PNG. */
+  'asset-degraded',
+  'jsx-cap-reached',
+  'value-rejected',
+  // ── The codegen route (DDR-219 D9). Three dispositions, one rule: what makes
+  // them safe is that `detail` carries a BOUNDED token plus a count, never the
+  // upstream family or utility name verbatim — `detail` is the one field on the
+  // wire no sanitizer touches, and it reaches verb stdout (D10), the HTTP route
+  // and the panel.
+  /** A Tailwind utility the mapper does not know, or whose value failed its grammar. */
+  'codegen-utility-unmapped',
+  /** A font family that did not survive the copy — a CSS fallback is NOT a report. */
+  'font-substituted',
+  /** Dev Mode unreachable / no seat / wrong document. The COMMON case, not an error state. */
+  'codegen-unavailable',
+  /** The converter itself could not be LOADED. Contract: REFUSE, never "let a model do it". */
+  'codegen-converter-unavailable',
+  /**
+   * The converter ran and REFUSED this frame — a parse error, an element outside
+   * the allowlist, a construct it does not understand (DDR-219 D5 rule 4).
+   *
+   * Deliberately NOT folded into `codegen-unavailable`: "Figma was unreachable"
+   * and "we looked at what Figma sent and would not emit it" are different
+   * facts, and conflating outcomes is how this feature reported success three
+   * times while losing content.
+   */
+  'codegen-frame-refused',
+] as const);
+
+export type Disposition = (typeof DISPOSITIONS)[number];
+
+const DISPOSITION_SET: ReadonlySet<string> = new Set(DISPOSITIONS);
+
+export function isDisposition(v: string): v is Disposition {
+  return DISPOSITION_SET.has(v);
+}
+
+/** `detail` is a code-owned note, and the only field on the wire that no
+ *  sanitizer touches — so it is the one place an upstream string would ride out
+ *  to a model unescaped (DDR-219 D9). It is NOT charset-restricted to ASCII:
+ *  real notes carry `—` and `→` legitimately. What distinguishes a code-owned
+ *  note from interpolated node text is that it is SHORT and carries no
+ *  zero-glyph payload, so those are what get asserted. Longest real note today
+ *  is 36 chars. */
+export const MAX_DETAIL_LEN = 64;
 
 export interface ReportEntry {
   /** `^[0-9]+:[0-9]+$` — an identifier, never node text (DDR-216 D7). */
@@ -76,6 +129,17 @@ export class ImportReport {
   readonly entries: ReportEntry[] = [];
 
   add(nodeId: string, type: string, disposition: Disposition, detail?: string): void {
+    // The backstop the missing `tsc` gate cannot provide. A disposition outside
+    // the set is a programming error, never bad input — so it throws rather than
+    // degrading: silent acceptance is exactly how `asset-degraded` reached main.
+    if (!DISPOSITION_SET.has(disposition)) {
+      throw new Error(`ImportReport: unknown disposition ${JSON.stringify(disposition)}`);
+    }
+    if (detail !== undefined && !isCodeOwnedDetail(detail)) {
+      throw new Error(
+        `ImportReport: detail must be a short code-owned note (<=${MAX_DETAIL_LEN} chars, no zero-glyph); got ${detail.length} chars`
+      );
+    }
     this.entries.push(
       detail ? { nodeId, type, disposition, detail } : { nodeId, type, disposition }
     );
@@ -86,6 +150,11 @@ export class ImportReport {
   }
 }
 
+/** True when `detail` looks like the code-owned note it is contracted to be. */
+export function isCodeOwnedDetail(detail: string): boolean {
+  return detail.length <= MAX_DETAIL_LEN && !ZERO_GLYPH_ONESHOT_RE.test(detail);
+}
+
 // ── D6a — character classes ─────────────────────────────────────────────────
 
 /**
@@ -111,33 +180,37 @@ export class ImportReport {
  * *letters or symbols* by category but render blank. A category rule cannot rot
  * the way an enumeration does.
  */
-const ZERO_GLYPH_RE = new RegExp(
-  [
-    // Format / control / private-use / unassigned — the categories that cover
-    // every bidi control, every zero-width, the Tags block, and anything Unicode
-    // adds later without this list needing an edit.
-    '[\\p{Cf}\\p{Cc}\\p{Co}\\p{Cn}]',
-    // Blank-rendering code points that are LETTERS or SYMBOLS by category, so no
-    // category rule catches them. Listed one per alternative rather than as a
-    // character class: `\u034F` is a COMBINING character, and a class mixing it
-    // with base characters is the `noMisleadingCharacterClass` footgun.
-    '\\u00AD', // soft hyphen
-    '\\u034F', // combining grapheme joiner
-    '\\u061C', // arabic letter mark (Trojan Source)
-    '\\u115F', // hangul choseong filler
-    '\\u1160', // hangul jungseong filler
-    '\\u17B4', // khmer inherent AQ
-    '\\u17B5', // khmer inherent AA
-    '[\\u180B-\\u180E]', // mongolian selectors + vowel separator
-    '\\u2800', // braille pattern blank
-    '\\u3164', // HANGUL FILLER — category Lo, i.e. a LETTER
-    '[\\uFE00-\\uFE0F]', // variation selectors
-    '\\uFFA0', // halfwidth hangul filler
-    '[\\uFFF9-\\uFFFB]', // interlinear annotation
-    '[\\u{E0100}-\\u{E01EF}]', // variation selectors supplement
-  ].join('|'),
-  'gu'
-);
+const ZERO_GLYPH_SOURCE = [
+  // Format / control / private-use / unassigned — the categories that cover
+  // every bidi control, every zero-width, the Tags block, and anything Unicode
+  // adds later without this list needing an edit.
+  '[\\p{Cf}\\p{Cc}\\p{Co}\\p{Cn}]',
+  // Blank-rendering code points that are LETTERS or SYMBOLS by category, so no
+  // category rule catches them. Listed one per alternative rather than as a
+  // character class: `\u034F` is a COMBINING character, and a class mixing it
+  // with base characters is the `noMisleadingCharacterClass` footgun.
+  '\\u00AD', // soft hyphen
+  '\\u034F', // combining grapheme joiner
+  '\\u061C', // arabic letter mark (Trojan Source)
+  '\\u115F', // hangul choseong filler
+  '\\u1160', // hangul jungseong filler
+  '\\u17B4', // khmer inherent AQ
+  '\\u17B5', // khmer inherent AA
+  '[\\u180B-\\u180E]', // mongolian selectors + vowel separator
+  '\\u2800', // braille pattern blank
+  '\\u3164', // HANGUL FILLER — category Lo, i.e. a LETTER
+  '[\\uFE00-\\uFE0F]', // variation selectors
+  '\\uFFA0', // halfwidth hangul filler
+  '[\\uFFF9-\\uFFFB]', // interlinear annotation
+  '[\\u{E0100}-\\u{E01EF}]', // variation selectors supplement
+].join('|');
+
+const ZERO_GLYPH_RE = new RegExp(ZERO_GLYPH_SOURCE, 'gu');
+
+/** The same rule without `g`. `RegExp.prototype.test` on a GLOBAL regex advances
+ *  `lastIndex` and so alternates true/false across calls on the same instance —
+ *  a one-shot predicate must never share the `g` instance. */
+const ZERO_GLYPH_ONESHOT_RE = new RegExp(ZERO_GLYPH_SOURCE, 'u');
 
 /** Tab / newline / carriage return are legitimate content — never stripped. */
 const KEEP_WHITESPACE_RE = /[\t\n\r]/;
@@ -184,6 +257,25 @@ export function attrValue(raw: string, maxLen = 64): string {
     .slice(0, maxLen);
 }
 
+/**
+ * A report token for `detail` — strict, and deliberately NOT `attrValue`.
+ *
+ * `attrValue` rewrites rejected characters to SPACES, which is right for a label
+ * and wrong here: a class token like `ignore.all.prior.instructions.and` comes
+ * back as that sentence, and `detail` reaches verb stdout (which D10 declares
+ * entirely code-owned), the HTTP summary and the panel. Charset-bounding is a
+ * markup control; it was never a semantic one (post-implementation review F3).
+ *
+ * So: a Tailwind FAMILY shape only — lowercase, digits, hyphens, NO SPACES ever
+ * — and anything else collapses to a fixed word. `unrecognized x7` is less
+ * informative than the raw token and cannot be read as an instruction, which is
+ * the right trade for a field an agent reads.
+ */
+export function reportToken(raw: string): string {
+  const head = /^[a-z][a-z0-9-]{0,23}/.exec(raw.trim().toLowerCase());
+  return head ? head[0] : 'unrecognized';
+}
+
 /**
  * A JSX-safe identifier derived from a NODE ID — never from a Figma string.
  * `2:17` → `Node_2_17`. This is the whole identifier story: there is no Figma

package/apps/studio/figma/tailwind-map.test.ts

@@ -0,0 +1,142 @@
+// figma/tailwind-map.ts — Tailwind utility → JSX style object.
+//
+// The coverage claim is a MEASUREMENT, not an aspiration: 129 distinct classes
+// across 64 families were counted on a real 375×812 screen (DDR-219 § Spike),
+// and the census below is that exact list. If a future Figma release emits
+// something new, this test is where it shows up — as an `unmapped` entry, which
+// is the reportable outcome the acceptance criteria demand, not a silent drop.
+
+import { describe, expect, test } from 'bun:test';
+
+import { MAX_CLASSES_PER_ELEMENT, mapClassName } from './tailwind-map.ts';
+
+const DS_FONTS = [{ name: '--font-body', value: "'hanken grotesk','inter',sans-serif" }];
+
+/** Every distinct class observed on `425:2939`. */
+const MEASURED_CLASSES = `relative shrink-0 flex content-stretch items-center flex-col absolute
+justify-center size-full max-w-none block inset-0 [word-break:break-word] not-italic leading-[0]
+whitespace-nowrap size-[24px] w-full text-black items-start border-solid leading-[normal] gap-[8px]
+text-[12px] font-normal border bg-[var(--black-10,rgba(15,22,30,0.1))] py-[8px] px-[12px]
+rounded-[8px] overflow-clip leading-[20px] font-bold tracking-[0.288px] text-[14px] justify-between
+font-[family-name:var(--font,'Inter:Regular')] font-[family-name:var(--font,'Inter:Bold')] p-[10px]
+border-black w-[185px] rounded-[9px] min-w-px flex-[1_0_0] text-center self-stretch rounded-[999px]
+w-[40px] text-[color:var(--black,#0f161e)] size-[21.5px] rounded-[99px] p-px h-[32px] gap-px
+font-['Inter:Regular'] border-[var(--black,#0f161e)] row-1 py-[16px] px-[24px] col-1 w-[34.018px]
+w-[16px] text-[10px] text-[#0f161e] size-[32px] px-[10px] mt-0 h-[12px] border-b
+border-[var(--black-10,rgba(15,22,30,0.1))] -translate-y-1/2 -translate-x-1/2 w-[54px] w-[375px]
+w-[364px] w-[358px] w-[341.871px] w-[327px] w-[25px] w-[18px] w-0 tracking-[0.24px] tracking-[-0.3px]
+top-[695.49px] top-[25.01px] top-[191px] top-1/2 text-[16px] size-[16px] size-[14.018px]
+rounded-[16px] py-[12px] px-[20px] place-items-start pb-[8px] mt-px ml-[50px] ml-[26px] ml-0
+left-[calc(50%-32.5px)] left-[calc(50%-0.02px)] left-[6.35px] left-1/2 leading-[12px] justify-end
+inset-[37.5%_18.75%_26.56%_18.75%] inset-[10.42%_16.67%_8.33%_16.67%] inset-[0_4.17%] inset-[0_-0.5px]
+inset-[0.49%_0.06%_-0.36%_0.07%] inset-[-6.64%_-7.07%_-7.49%_-7.07%] inline-grid h-full h-[768px]
+h-[58.766px] h-[480px] h-[296px] h-[14.454px] h-[14.018px] h-[10px] grid-rows-[max-content]
+grid-cols-[max-content] gap-[7px] gap-[4px] font-['SF_Pro_Display:Semibold'] font-['SF_Pro:Bold']
+flex-row border-[red] bg-white`
+  .trim()
+  .split(/\s+/);
+
+describe('the measured surface', () => {
+  test('every class from the real screen maps — 129/129, zero unmapped', () => {
+    const unmapped: string[] = [];
+    for (const cls of MEASURED_CLASSES) {
+      const r = mapClassName(cls, { fontTokens: DS_FONTS });
+      if (r.unmapped.length > 0) unmapped.push(cls);
+    }
+    expect(unmapped).toEqual([]);
+    expect(MEASURED_CLASSES.length).toBe(129);
+  });
+});
+
+describe('the disambiguations that are easy to get wrong', () => {
+  test('text-[16px] is a font size and text-[#hex] is a colour', () => {
+    expect(mapClassName('text-[16px]').declarations).toEqual({ fontSize: '16px' });
+    expect(mapClassName('text-[#0f161e]').declarations).toEqual({ color: '#0f161e' });
+  });
+
+  test("Tailwind's own color: hint wins", () => {
+    expect(mapClassName('text-[color:var(--black,#0f161e)]').declarations).toEqual({
+      color: 'var(--black,#0f161e)',
+    });
+  });
+
+  test('border-[red] is a colour, border-[2px] is a width', () => {
+    expect(mapClassName('border-[red]').declarations).toEqual({ borderColor: 'red' });
+    expect(mapClassName('border-[2px]').declarations).toEqual({
+      borderWidth: '2px',
+      borderStyle: 'solid',
+    });
+  });
+
+  test('a negative utility carries its sign on the FAMILY, not the value', () => {
+    expect(mapClassName('-ml-[26px]').declarations).toEqual({ marginLeft: '-26px' });
+  });
+
+  test('transforms compose into ONE declaration', () => {
+    expect(mapClassName('-translate-x-1/2 -translate-y-1/2').declarations.transform).toBe(
+      'translateX(-50%) translateY(-50%)'
+    );
+  });
+
+  test('leading-[0] becomes normal — a zero line box hides the text', () => {
+    // D6b's rule in miniature: the translator can GUARANTEE visibility, so it
+    // does, rather than faithfully reproducing a collapsed line and reporting
+    // success on an empty-looking screen.
+    expect(mapClassName('leading-[0]').declarations).toEqual({ lineHeight: 'normal' });
+    expect(mapClassName('leading-[20px]').declarations).toEqual({ lineHeight: '20px' });
+  });
+
+  test('size-[N] sets both axes', () => {
+    expect(mapClassName('size-[16px]').declarations).toEqual({ width: '16px', height: '16px' });
+  });
+});
+
+describe('what must NOT get through', () => {
+  test.each([
+    'bg-[url(https://attacker.example/beacon.png)]',
+    '[behavior:url(#x)]',
+    '[content:"pwned"]',
+    'w-[99999999px]',
+    'text-[expression(alert(1))]',
+    'bg-[#fff;position:fixed]',
+    'grid-cols-[repeat(999999,1fr)]',
+  ])('%s is reported, never emitted', (cls) => {
+    const r = mapClassName(cls);
+    expect(r.declarations).toEqual({});
+    expect(r.unmapped.length).toBeGreaterThan(0);
+  });
+
+  test('an unknown utility is REPORTED — "never silently dropped" is the criterion', () => {
+    const r = mapClassName('flex definitely-not-a-tailwind-class');
+    expect(r.declarations).toEqual({ display: 'flex' });
+    expect(r.unmapped).toEqual(['definitely-not-a-tailwind-class']);
+  });
+
+  test('a class list long enough to be a payload is capped, and the cap is reported', () => {
+    const many = Array.from({ length: MAX_CLASSES_PER_ELEMENT + 10 }, () => 'flex').join(' ');
+    const r = mapClassName(many);
+    expect(r.unmapped).toContain('class-cap-reached');
+  });
+
+  test('an oversized single token never reaches a grammar', () => {
+    const r = mapClassName(`w-[${'1'.repeat(500)}px]`);
+    expect(r.declarations).toEqual({});
+    expect(r.unmapped).toEqual(['oversized']);
+  });
+});
+
+describe('DS tokens', () => {
+  test('a bare hex snaps onto a near DS token', () => {
+    const r = mapClassName('bg-[#0f161e]', {
+      tokens: [{ name: '--fg-0', hex: '#0f161e' }],
+    });
+    expect(r.declarations.background).toBe('var(--fg-0)');
+  });
+
+  test('a var() Figma already resolved is NOT re-snapped — that would be a downgrade', () => {
+    const r = mapClassName('bg-[var(--black,#0f161e)]', {
+      tokens: [{ name: '--fg-0', hex: '#0f161e' }],
+    });
+    expect(r.declarations.background).toBe('var(--black,#0f161e)');
+  });
+});