@1agh/maude 0.58.3 → 0.60.0

package/apps/studio/figma/codegen-fonts.ts

@@ -0,0 +1,195 @@
+/**
+ * @file       figma/codegen-fonts.ts — font resolution + honest reporting (plan T18, DDR-219 D9).
+ * @scope      apps/studio/figma/codegen-fonts.ts
+ * @purpose    Turn a Figma font family into something the PROJECT can actually
+ *             render, and say so every single time that is not what was asked
+ *             for.
+ *
+ * @rationale  Measured on the dogfood machine 2026-08-11: Inter installed;
+ *             **Nunito, SF Pro, Hanken Grotesk and General Sans absent** — while
+ *             the DS declares `--font-body: 'Hanken Grotesk','Inter',…` and
+ *             loads no webfont at all (no `@font-face`, no import). Copying the
+ *             family name through therefore lands on a serif fallback that
+ *             *looks fine* and is not the design. Silent visual drift is exactly
+ *             the failure mode this import has already shipped three times
+ *             (dropped loose content, stripped `href`, zero-height arrows) —
+ *             each time reporting success.
+ *
+ * @invariant  A CSS FALLBACK IS NOT A REPORT. `font-family: 'SF Pro', sans-serif`
+ *             degrades silently by design; that is what a fallback IS. So every
+ *             substitution emits a `font-substituted` disposition, and the
+ *             per-import summary names it.
+ *
+ * @invariant  THE FIGMA FAMILY NEVER REACHES THE ARTIFACT. `style-map.ts` states
+ *             the same rule for the tree lane ("FONT FAMILY IS DELIBERATELY NOT
+ *             CARRIED") because a family value is free text from the document
+ *             that reaches a live stylesheet. This lane resolves to a DS token
+ *             or to a system stack — never to the requested literal.
+ *
+ * @invariant  THE REPORTED NAME IS BOUNDED, NOT VERBATIM (DDR-219 D9). `detail`
+ *             is the one field on the wire no sanitizer touches, and it reaches
+ *             verb stdout (which D10 declares entirely code-owned), the HTTP
+ *             route and the panel. So the family travels as
+ *             `attrValue(name, 32)` — charset-allowlisted and length-capped —
+ *             never as the raw string.
+ *
+ * @invariant  DEPENDENCY-FREE — pure string work over an injected token list.
+ */
+
+import { attrValue, type ImportReport } from './sanitize.ts';
+
+/** How much of a family name may appear in a report entry (D9). */
+export const MAX_FAMILY_DETAIL = 32;
+
+/**
+ * Figma writes a family as `Family:Style` inside a Tailwind arbitrary value —
+ * `SF_Pro:Bold`, `Inter:Regular`, `SF_Pro_Display:Semibold`. The style half is a
+ * WEIGHT, not part of the family, and passing it through produces a family name
+ * no font on earth answers to.
+ */
+export function splitFamilyAndStyle(raw: string): { family: string; style: string | null } {
+  const colon = raw.indexOf(':');
+  if (colon < 0) return { family: raw.trim(), style: null };
+  return { family: raw.slice(0, colon).trim(), style: raw.slice(colon + 1).trim() || null };
+}
+
+/** Figma's style words → a numeric CSS weight. Anything unrecognised is ignored
+ *  rather than guessed — a wrong weight is a visible defect with no report. */
+const STYLE_WEIGHTS: ReadonlyMap<string, number> = new Map([
+  ['thin', 100],
+  ['extralight', 200],
+  ['ultralight', 200],
+  ['light', 300],
+  ['regular', 400],
+  ['normal', 400],
+  ['book', 400],
+  ['medium', 500],
+  ['semibold', 600],
+  ['demibold', 600],
+  ['bold', 700],
+  ['extrabold', 800],
+  ['heavy', 800],
+  ['black', 900],
+]);
+
+export function styleToWeight(style: string | null): number | null {
+  if (!style) return null;
+  return STYLE_WEIGHTS.get(style.toLowerCase().replace(/[^a-z]/g, '')) ?? null;
+}
+
+/**
+ * Families that are genuinely present on essentially every target, so resolving
+ * to them is not a substitution anyone needs telling about. Deliberately tiny:
+ * the honest default when we do not know is "this WAS substituted".
+ */
+const UBIQUITOUS: ReadonlySet<string> = new Set(['inter', 'arial', 'helvetica', 'georgia']);
+
+/**
+ * The stack a substituted family lands on. Not a serif — the measured failure
+ * was a design landing on a serif fallback, so the replacement is explicitly the
+ * neutral UI stack the rest of Maude uses.
+ */
+export const SYSTEM_STACK =
+  "system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif";
+
+export interface FontToken {
+  /** e.g. `--font-body`. */
+  name: string;
+  /** The declared stack, lowercased, for family matching. */
+  value: string;
+}
+
+export interface FontResolution {
+  /** What to emit as `fontFamily`. Never the requested literal. */
+  css: string;
+  /** True when the emitted family is not the requested one. */
+  substituted: boolean;
+  /** Bounded requested family, for the report. Empty when unprintable. */
+  requested: string;
+  /** Which DS token matched, when one did. */
+  token?: string;
+}
+
+/**
+ * Resolve a requested family against the project's own type tokens first, then
+ * against the ubiquitous set, then to the system stack.
+ *
+ * DS token first is not only a fidelity choice — it is the editability one. An
+ * imported frame that inherits the project's type stack looks like it belongs to
+ * the project, which is the same reasoning `style-map.ts` gives for not carrying
+ * the family at all in the tree lane.
+ */
+export function resolveFontFamily(
+  rawFamily: string,
+  tokens: readonly FontToken[] = []
+): FontResolution {
+  const { family } = splitFamilyAndStyle(rawFamily);
+  const requested = attrValue(family, MAX_FAMILY_DETAIL);
+  const needle = family.toLowerCase().replace(/['"]/g, '').trim();
+
+  if (needle.length === 0) {
+    return { css: SYSTEM_STACK, substituted: true, requested };
+  }
+
+  // A DS token whose declared stack NAMES this family is not a substitution —
+  // it is the same typeface, reached through the project's own variable.
+  for (const t of tokens) {
+    if (t.value.includes(needle)) {
+      return { css: `var(${t.name})`, substituted: false, requested, token: t.name };
+    }
+  }
+  if (UBIQUITOUS.has(needle)) {
+    return { css: `${quoteFamily(family)}, ${SYSTEM_STACK}`, substituted: false, requested };
+  }
+  // Nothing matched. Prefer the project's body token over a bare system stack —
+  // an imported frame in the project's own typeface beats one in the OS default.
+  const body = tokens.find((t) => /body|sans|text|base/.test(t.name));
+  if (body) return { css: `var(${body.name})`, substituted: true, requested, token: body.name };
+  return { css: SYSTEM_STACK, substituted: true, requested };
+}
+
+/**
+ * Quote a family name for a CSS value position. Charset-allowlisted first, so a
+ * family carrying a quote, a semicolon or a brace cannot terminate the
+ * declaration — the same reason DDR-172 Decision 4 has a font grammar at all.
+ */
+export function quoteFamily(family: string): string {
+  const safe = family
+    .replace(/[^A-Za-z0-9 _-]+/g, '')
+    .trim()
+    .slice(0, 48);
+  return safe.length > 0 ? `'${safe}'` : SYSTEM_STACK;
+}
+
+/**
+ * Record substitutions ONCE PER FAMILY, with a count — not once per element.
+ *
+ * A screen using SF Pro on 40 nodes is ONE substitution a human needs to know
+ * about; forty identical entries would bury the other dispositions and blow the
+ * summary's 200-line cap for no information. The count is what makes the single
+ * entry honest.
+ */
+export class FontSubstitutions {
+  private readonly counts = new Map<string, number>();
+
+  note(resolution: FontResolution): void {
+    if (!resolution.substituted) return;
+    const key = resolution.requested || 'unnamed';
+    this.counts.set(key, (this.counts.get(key) ?? 0) + 1);
+  }
+
+  get size(): number {
+    return this.counts.size;
+  }
+
+  /**
+   * Flush into the import report. `nodeId` is the FRAME's id — the substitution
+   * is a property of the import, not of one element, and `detail` is bounded to
+   * `<= MAX_DETAIL_LEN` by `ImportReport.add` throwing if it is not.
+   */
+  flush(report: ImportReport, nodeId: string): void {
+    for (const [family, n] of [...this.counts].sort((a, b) => a[0].localeCompare(b[0]))) {
+      report.add(nodeId, 'FONT', 'font-substituted', `${family} x${n}`.slice(0, 63));
+    }
+  }
+}

package/apps/studio/figma/codegen-values.test.ts

@@ -0,0 +1,179 @@
+// figma/codegen-values.ts — the codegen lane's value grammar.
+//
+// Two things are being defended here, and they pull in opposite directions:
+// a `var()` WITH a fallback must be ADMITTED (it is the fidelity this whole
+// route exists for), and nothing SHARED with the tree translator or DDR-172's
+// token importer may be widened to get it. So the tests assert both the new
+// admissions and that the old refusals still refuse.
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  cssPropToCamel,
+  isAllowedArbitraryProperty,
+  isCodegenColor,
+  isCodegenKeyword,
+  isCodegenLength,
+  isCodegenLengthList,
+  isCodegenNumber,
+  isCodegenShortValueList,
+  MAX_VALUE_LEN,
+  normalizeCalc,
+  splitVar,
+  unescapeArbitrary,
+} from './codegen-values.ts';
+import { isValidColorValue } from './style-map.ts';
+
+describe('the shared grammar is not widened', () => {
+  test('style-map still refuses a fallback-bearing var() — that is the point', () => {
+    // If this ever passes, someone widened `VAR_RE` instead of composing, which
+    // is verbatim the root pattern the DDR-216 review named twice.
+    expect(isValidColorValue('var(--black,#0f161e)')).toBe(false);
+    expect(isValidColorValue('var(--black)')).toBe(true);
+  });
+
+  test('the lane admits it locally', () => {
+    expect(isCodegenColor('var(--black,#0f161e)')).toBe(true);
+    expect(isCodegenColor('var(--black-10,rgba(15,22,30,0.1))')).toBe(true);
+  });
+});
+
+describe('isCodegenColor', () => {
+  test.each([
+    ['#0f161e', true],
+    ['rgba(15,22,30,0.1)', true],
+    ['var(--accent)', true],
+    ['var(--accent, #fff)', true],
+    ['white', true],
+    ['transparent', true],
+    // The fallback is validated as a colour IN ITS OWN RIGHT, so a URL smuggled
+    // into it is refused by the grammar and not merely by the canvas CSP.
+    ['var(--x,url(https://attacker.example/p))', false],
+    ['url(https://attacker.example/p)', false],
+    ['var(--x);color:red', false],
+    ['expression(alert(1))', false],
+    ['var(--ABC)', false],
+    ['#0f161e /* */', false],
+  ])('%s -> %s', (value, expected) => {
+    expect(isCodegenColor(value as string)).toBe(expected);
+  });
+
+  test('nested var() fallbacks terminate', () => {
+    expect(isCodegenColor('var(--a,var(--b,var(--c,#fff)))')).toBe(true);
+    expect(isCodegenColor('var(--a,var(--b,var(--c,var(--d,var(--e,#fff)))))')).toBe(false);
+  });
+
+  test('a value over the length cap is refused before any grammar runs', () => {
+    expect(isCodegenColor(`#${'0'.repeat(MAX_VALUE_LEN)}`)).toBe(false);
+  });
+});
+
+describe('lengths', () => {
+  test.each([
+    ['375px', true],
+    ['0', true],
+    ['4.17%', true],
+    ['1.5rem', true],
+    ['100vh', true],
+    ['auto', true],
+    ['calc(50% - 32.5px)', true],
+    ['99999999px', false],
+    ['red', false],
+    ['12px;color:red', false],
+    ['calc(50% - 32.5px) !important', false],
+  ])('%s -> %s', (v, expected) => {
+    expect(isCodegenLength(v as string)).toBe(expected);
+  });
+
+  test('a shorthand of up to four lengths', () => {
+    expect(isCodegenLengthList('37.5% 18.75% 26.56% 18.75%')).toBe(true);
+    expect(isCodegenLengthList('0 4.17%')).toBe(true);
+    expect(isCodegenLengthList('1px 2px 3px 4px 5px')).toBe(false);
+  });
+});
+
+describe('normalizeCalc', () => {
+  test('re-spaces the operator Figma omits', () => {
+    // `calc(50%-32.5px)` is INVALID CSS — a browser drops the declaration — so a
+    // pass-through would silently lose the position.
+    expect(normalizeCalc('calc(50%-32.5px)')).toBe('calc(50% - 32.5px)');
+    expect(normalizeCalc('calc(50%-0.02px)')).toBe('calc(50% - 0.02px)');
+  });
+
+  test('REGRESSION: a custom-property name is not an arithmetic expression', () => {
+    // The first version used a lookbehind regex and rewrote this to
+    // `var(--black - 10,…)`, which is a broken declaration on the single most
+    // common value shape this whole route exists to preserve.
+    expect(normalizeCalc('var(--black-10,rgba(15,22,30,0.1))')).toBe(
+      'var(--black-10,rgba(15,22,30,0.1))'
+    );
+    expect(normalizeCalc('calc(var(--gap-2) + 4px)')).toBe('calc(var(--gap-2) + 4px)');
+  });
+
+  test('a leading sign is not an operator', () => {
+    expect(normalizeCalc('calc(-4px)')).toBe('calc(-4px)');
+  });
+
+  test('a value with no calc is returned untouched', () => {
+    expect(normalizeCalc('1 0 0')).toBe('1 0 0');
+  });
+});
+
+describe('unescapeArbitrary', () => {
+  test('an underscore is a space', () => {
+    expect(unescapeArbitrary('37.5%_18.75%')).toBe('37.5% 18.75%');
+    expect(unescapeArbitrary("'SF_Pro:Bold'")).toBe("'SF Pro:Bold'");
+  });
+
+  test('an escaped underscore stays an underscore', () => {
+    expect(unescapeArbitrary('a\\_b_c')).toBe('a_b c');
+  });
+});
+
+describe('splitVar', () => {
+  test('splits at depth 1 only', () => {
+    expect(splitVar('var(--a,rgba(1,2,3,0.5))')).toEqual({
+      name: '--a',
+      fallback: 'rgba(1,2,3,0.5)',
+    });
+    expect(splitVar('var(--a)')).toEqual({ name: '--a', fallback: null });
+    expect(splitVar('#fff')).toBeNull();
+  });
+});
+
+describe('arbitrary properties are an allowlist', () => {
+  test('admits what Figma emits', () => {
+    expect(isAllowedArbitraryProperty('word-break')).toBe(true);
+    expect(isAllowedArbitraryProperty('font-variation-settings')).toBe(true);
+  });
+
+  test('refuses everything else, including things a denylist would forget', () => {
+    for (const prop of ['behavior', '-moz-binding', 'content', 'background-image', 'src']) {
+      expect(isAllowedArbitraryProperty(prop)).toBe(false);
+    }
+  });
+});
+
+describe('misc predicates', () => {
+  test('numbers are magnitude-bounded, not only shape-checked', () => {
+    expect(isCodegenNumber('0.5')).toBe(true);
+    expect(isCodegenNumber('999999999')).toBe(false);
+  });
+
+  test('keywords are short and lowercase', () => {
+    expect(isCodegenKeyword('max-content')).toBe(true);
+    expect(isCodegenKeyword('break-word')).toBe(true);
+    expect(isCodegenKeyword('URL(x)')).toBe(false);
+  });
+
+  test('short value lists', () => {
+    expect(isCodegenShortValueList('1 0 0')).toBe(true);
+    expect(isCodegenShortValueList('max-content')).toBe(true);
+    expect(isCodegenShortValueList('1 2 3 4 5 6 7')).toBe(false);
+  });
+
+  test('camelCase, because a hyphenated key in a JSX style OBJECT is a syntax error', () => {
+    expect(cssPropToCamel('word-break')).toBe('wordBreak');
+    expect(cssPropToCamel('font-variation-settings')).toBe('fontVariationSettings');
+  });
+});

package/apps/studio/figma/codegen-values.ts

@@ -0,0 +1,270 @@
+/**
+ * @file       figma/codegen-values.ts — the CODEGEN LANE's value grammar (DDR-219 D5 rule 7).
+ * @scope      apps/studio/figma/codegen-values.ts
+ * @purpose    Decide what a Tailwind arbitrary value is allowed to become in an
+ *             emitted style object — for THIS lane only.
+ *
+ * @invariant  NOTHING SHARED IS WIDENED. `style-map.ts`'s `VAR_RE` rejects a
+ *             `var()` with a fallback — i.e. every `var(--black,#0f161e)` this
+ *             route exists to preserve. The fix is NOT to loosen it: that
+ *             constant is shared with the tree translator AND with DDR-172's
+ *             token importer, and "widen a shared grammar to satisfy a new
+ *             caller" is verbatim the root pattern the DDR-216 review named
+ *             twice. This module COMPOSES the exported predicates
+ *             (`isValidColorValue`, `isValidDimension`) and adds the lane's own
+ *             admissions on top.
+ *
+ * @invariant  A FALLBACK-BEARING `var()` IS ADMITTED, DELIBERATELY. It is the
+ *             fidelity this route exists for — Figma resolves its own design
+ *             variables and hands them over with a literal fallback. Admitted
+ *             under a strict shape: the custom-property NAME is charset-bounded
+ *             and the FALLBACK must itself pass the colour grammar.
+ *
+ * @invariant  ReDoS DISCIPLINE (DDR-172 Decision 4, carried into this lane by
+ *             D5 rule 6): printable-ASCII pre-filter first, no `m`/`s` flags,
+ *             bounded quantifiers, and no construct where two adjacent parts can
+ *             match the same empty input. Tailwind's bracket syntax is unbounded
+ *             free-text capture wearing a utility name, so the pre-filter and
+ *             the length bound do most of the work before any grammar runs.
+ *
+ * @invariant  MAGNITUDE, NOT ONLY SHAPE. A grammar-valid `99999999px` is a
+ *             live-render hang vector in a canvas iframe even though its shape
+ *             is fine — every numeric admission is paired with a bound.
+ *
+ * @invariant  DEPENDENCY-FREE beyond `style-map.ts`'s pure predicates.
+ */
+
+import { isValidColorValue, isValidDimension } from './style-map.ts';
+
+/** Longest arbitrary value we will even look at. Measured longest real one is
+ *  `inset-[37.5%_18.75%_26.56%_18.75%]` at 33 chars; 160 is generous. */
+export const MAX_VALUE_LEN = 160;
+
+const PRINTABLE_ASCII_RE = /^[\x20-\x7E]*$/;
+
+/** A CSS custom-property name. Same charset the shared `VAR_RE` uses — the
+ *  difference here is only that a FALLBACK may follow, never a looser name. */
+const CUSTOM_PROP_RE = /^--[a-z0-9-]{1,64}$/;
+
+/** `1 0 0`, `max-content`, `min-content`, `auto`, `none`, `normal`, `break-word`… */
+const KEYWORD_RE = /^[a-z][a-z-]{0,31}$/;
+
+/** Bounds. Layout numbers in a canvas are px-scale; nothing legitimate is huge. */
+const DIM_MAX = 8192;
+const UNITLESS_MAX = 10_000;
+
+function printableAscii(v: string): boolean {
+  return v.length <= MAX_VALUE_LEN && PRINTABLE_ASCII_RE.test(v);
+}
+
+/**
+ * Tailwind escapes a space as `_` inside an arbitrary value, so
+ * `inset-[0_4.17%]` is `inset: 0 4.17%` and `font-['SF_Pro:Bold']` is
+ * `SF Pro:Bold`. `\_` is a literal underscore and is preserved.
+ */
+export function unescapeArbitrary(raw: string): string {
+  // ONE pass with a replacer rather than a sentinel round-trip: a sentinel is a
+  // character that must be impossible in the input, and "impossible" is the kind
+  // of assumption this lane is not allowed to make about a third-party string.
+  return raw.replace(/\\_|_/g, (m) => (m === '\\_' ? '_' : ' '));
+}
+
+/**
+ * Figma emits `calc(50%-32.5px)` — no spaces. That is INVALID CSS (a `-` with no
+ * surrounding whitespace is part of the number, not an operator), so a
+ * pass-through would silently produce a declaration the browser drops. Tailwind's
+ * own pipeline re-spaces it; so do we, before the grammar runs.
+ *
+ * Only a `+`/`-` that sits BETWEEN two operands is touched — a leading sign is
+ * left alone.
+ */
+export function normalizeCalc(v: string): string {
+  if (!v.includes('calc(')) return v;
+  // A LINEAR SCAN, not a regex. The naive `(?<=[\w%)])([-+])(?=[\d.(])` version
+  // was wrong in a way that only showed up on a real value: it rewrote
+  // `var(--black-10,…)` into `var(--black - 10,…)`, because a hyphen inside a
+  // custom-property NAME looks exactly like a subtraction operator. The fix is
+  // context, and context is a stack — which is also ReDoS-free by construction.
+  const out: string[] = [];
+  /** Innermost function name, so `var(` nested inside `calc(` is left alone. */
+  const fnStack: string[] = [];
+  for (let i = 0; i < v.length; i += 1) {
+    const ch = v[i];
+    if (ch === '(') {
+      const m = /([a-z-]{1,16})$/i.exec(v.slice(0, i));
+      fnStack.push(m ? m[1].toLowerCase() : '');
+      out.push(ch);
+      continue;
+    }
+    if (ch === ')') {
+      fnStack.pop();
+      out.push(ch);
+      continue;
+    }
+    const inCalc = fnStack[fnStack.length - 1] === 'calc';
+    if (inCalc && (ch === '-' || ch === '+')) {
+      const prev = v[i - 1] ?? '';
+      const next = v[i + 1] ?? '';
+      // An operator sits between two operands. A leading sign has no operand to
+      // its left; `e` is excluded so `1e-5` keeps its exponent.
+      const prevIsOperand = /[\d%)a-df-z]/i.test(prev);
+      if (prevIsOperand && /[\d.(]/.test(next)) {
+        out.push(' ', ch, ' ');
+        continue;
+      }
+    }
+    out.push(ch);
+  }
+  return out.join('');
+}
+
+/** One `calc()` term: an optionally-signed bounded number with an optional unit. */
+const CALC_TERM = '-?\\d{1,7}(?:\\.\\d{1,6})?(?:px|%|rem|em|vw|vh)?';
+/** `calc(a op b op c …)`, at most 8 terms. Written so no two adjacent parts can
+ *  match empty — the property that keeps a bounded quantifier from backtracking. */
+const CALC_RE = new RegExp(`^calc\\(\\s*${CALC_TERM}(?:\\s*[-+*/]\\s*${CALC_TERM}){0,7}\\s*\\)$`);
+
+/** A single length: what the shared grammar admits, plus viewport units and calc. */
+export function isCodegenLength(v: string, max = DIM_MAX): boolean {
+  if (!printableAscii(v)) return false;
+  if (v === '0' || v === 'auto' || v === 'none') return true;
+  if (isValidDimension(v, max)) return true;
+  const vw = /^(-?\d{1,7}(?:\.\d{1,6})?)(vw|vh)$/.exec(v);
+  if (vw) return Math.abs(Number.parseFloat(vw[1])) <= max;
+  return CALC_RE.test(v);
+}
+
+/**
+ * A shorthand of 1–4 lengths (`inset`, `padding`, `margin`). Split-then-validate
+ * rather than one composite regex: the parts are already bounded individually,
+ * and a composite would be the exact nested-quantifier shape D5 rule 6 bans.
+ */
+export function isCodegenLengthList(v: string, max = DIM_MAX): boolean {
+  if (!printableAscii(v)) return false;
+  const parts = v.trim().split(/\s+/);
+  if (parts.length === 0 || parts.length > 4) return false;
+  return parts.every((p) => isCodegenLength(p, max));
+}
+
+/**
+ * Split `var(--name, fallback)` without a nested-quantifier regex: find the
+ * first comma at depth 1. Returns `null` when the string is not a `var()` at all.
+ */
+export function splitVar(v: string): { name: string; fallback: string | null } | null {
+  if (!v.startsWith('var(') || !v.endsWith(')')) return null;
+  const inner = v.slice(4, -1);
+  let depth = 0;
+  for (let i = 0; i < inner.length; i += 1) {
+    const ch = inner[i];
+    if (ch === '(') depth += 1;
+    else if (ch === ')') depth -= 1;
+    else if (ch === ',' && depth === 0) {
+      return { name: inner.slice(0, i).trim(), fallback: inner.slice(i + 1).trim() };
+    }
+  }
+  return { name: inner.trim(), fallback: null };
+}
+
+/**
+ * A colour for this lane: everything the shared grammar admits, PLUS a `var()`
+ * carrying a fallback, PLUS the handful of bare keywords Tailwind emits.
+ *
+ * The fallback is validated as a colour in its own right, so
+ * `var(--x,url(https://attacker/))` is rejected here rather than relying on the
+ * canvas CSP to refuse the fetch. (The CSP — `default-src 'none'`,
+ * `img-src 'self' data: blob:` — WOULD block it, which is why the blast radius
+ * of a grammar gap in this lane is spoofing rather than beaconing. That bounds
+ * the damage; it does not make the grammar sound, so the grammar is sound.)
+ */
+export function isCodegenColor(v: string, depth = 0): boolean {
+  // A `var()` fallback may itself be a `var()`. Bounded explicitly rather than
+  // relying on the 160-char length cap to run out first — a recursion whose
+  // termination is an accident of another constant is one edit from unbounded.
+  if (depth > 4) return false;
+  if (!printableAscii(v)) return false;
+  if (v === 'transparent' || v === 'currentColor' || v === 'inherit') return true;
+  if (isValidColorValue(v)) return true;
+  const parsed = splitVar(v);
+  if (!parsed) return NAMED_COLOR_SET.has(v);
+  if (!CUSTOM_PROP_RE.test(parsed.name)) return false;
+  if (parsed.fallback === null) return true;
+  return isCodegenColor(parsed.fallback, depth + 1);
+}
+
+/**
+ * The CSS named colours Figma's generator actually reaches for. Deliberately a
+ * short allowlist rather than the full 148-name table: a name is a value
+ * position, and the shorter the admitted vocabulary the smaller the surface.
+ */
+const NAMED_COLOR_SET: ReadonlySet<string> = new Set([
+  'white',
+  'black',
+  'red',
+  'green',
+  'blue',
+  'gray',
+  'grey',
+  'silver',
+  'transparent',
+]);
+
+/** A unitless number (`opacity`, `z-index`, `flex-grow`, `line-height`). */
+export function isCodegenNumber(v: string, max = UNITLESS_MAX): boolean {
+  if (!printableAscii(v)) return false;
+  if (!/^-?\d{1,7}(?:\.\d{1,6})?$/.test(v)) return false;
+  return Math.abs(Number.parseFloat(v)) <= max;
+}
+
+/** A bare keyword value (`max-content`, `break-word`, `nowrap`, `normal`). */
+export function isCodegenKeyword(v: string): boolean {
+  return printableAscii(v) && KEYWORD_RE.test(v);
+}
+
+/**
+ * `flex: 1 0 0`, `grid-template-columns: max-content`, and friends: a short
+ * sequence of numbers, lengths and keywords. Never a `url()`, never a function
+ * this module has not admitted by name.
+ */
+export function isCodegenShortValueList(v: string): boolean {
+  if (!printableAscii(v)) return false;
+  const parts = v.trim().split(/\s+/);
+  if (parts.length === 0 || parts.length > 6) return false;
+  return parts.every(
+    (p) => isCodegenNumber(p) || isCodegenLength(p) || isCodegenKeyword(p) || /^\d+fr$/.test(p)
+  );
+}
+
+/**
+ * Properties an ARBITRARY-PROPERTY utility (`[word-break:break-word]`) may set.
+ *
+ * An allowlist, never a denylist (D5 rule 3): the bracket syntax is a hole
+ * straight into the style object, and a denylist has to remember `behavior`,
+ * `-moz-binding`, `content` and whatever the next engine ships.
+ */
+const ARBITRARY_PROPERTY_ALLOWLIST: ReadonlySet<string> = new Set([
+  'word-break',
+  'overflow-wrap',
+  'white-space',
+  'text-wrap',
+  'font-variation-settings',
+  'font-feature-settings',
+  'text-overflow',
+  'letter-spacing',
+  'line-height',
+  'vertical-align',
+  'mix-blend-mode',
+  'object-fit',
+  'object-position',
+  'aspect-ratio',
+]);
+
+export function isAllowedArbitraryProperty(prop: string): boolean {
+  return ARBITRARY_PROPERTY_ALLOWLIST.has(prop);
+}
+
+/** `word-break` → `wordBreak`. Emitted style objects are JSX, and a hyphenated
+ *  key in a style OBJECT is a syntax error that takes the whole canvas down —
+ *  the exact defect that made one gradient unparse a whole page (DDR-216 D12). */
+export function cssPropToCamel(prop: string): string {
+  return prop.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}