@1agh/maude 0.58.2 → 0.59.0

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

@@ -0,0 +1,1103 @@
+/**
+ * @file       figma/from-codegen.ts — Figma Dev Mode codegen → one Maude artboard.
+ * @scope      apps/studio/figma/from-codegen.ts
+ * @purpose    Convert the React + Tailwind MODULE the local Dev Mode server
+ *             returns into a `DCArtboard` a Maude canvas renders and a human
+ *             edits — for ONE frame, on explicit invocation (`--explode`).
+ *
+ * @rationale  Two earlier routes were built and both measured broken on the same
+ *             live file (DDR-219 § Context). Route 1 derived layout from the node
+ *             tree, which means reimplementing auto-layout, constraints,
+ *             clipping, blend modes and vector networks in CSS — the bug surface
+ *             grows with the fidelity of the source. Route 2 rendered each frame
+ *             to an image, which is faithful and inert. This route asks Figma for
+ *             the layout ALREADY RESOLVED and converts the result. The editability
+ *             bar is met, not abandoned — but it is met by taking Figma's DOM
+ *             rather than by deriving one.
+ *
+ * @invariant  THE MODULE STAYS REACT. The first spike flattened to HTML by
+ *             stripping with regexes, and on the first real screen it rendered
+ *             `type IconsProps = …` as visible body text — exactly the defect
+ *             class the "named parser, never regex" rule exists to prevent.
+ *             A real response is a MODULE: asset constants, a type alias, a
+ *             parameterized helper component, then the default export. Maude
+ *             canvases ARE React, so keeping the helper is both natively
+ *             renderable and strictly MORE editable than inlining it fourteen
+ *             times.
+ *
+ * @invariant  EVERY IDENTIFIER IS REGENERATED (DDR-216 D6 via DDR-219 D4).
+ *             D6 calls the identifier space "airtight — there is no Figma string
+ *             in it at all", and that holds only because every name comes from
+ *             `identifierFromNodeId`. Codegen returns React source carrying its
+ *             OWN names, derived from layer names
+ *             (`Component231320F78B2B43C7B5A04A6Ff8B6244C45005C` was measured).
+ *             So: component names, parameter names and local names are ALL
+ *             discarded and regenerated. Only string VALUES survive, escaped.
+ *
+ * @invariant  ELEMENT AND ATTRIBUTE ALLOWLISTS, NEVER DENYLISTS (D5 rule 3). A
+ *             denylist has to remember `<script>`, `<style>`, `<iframe>`,
+ *             `<foreignObject>`, `on*`, `href`, `dangerouslySetInnerHTML`.
+ *             An allowlist does not.
+ *
+ * @invariant  THE PARSER'S LEAF ENUMERATION IS THE CONTROL — not `sanitize.ts`
+ *             "in full", which is not a thing that can be done (D4): every
+ *             export there is a FIELD-LEVEL string function, and
+ *             `jsxStringLiteral` run over a JSX document destroys the markup.
+ *             What is true is that every string this module *extracts* — text
+ *             node, attribute value, class token — goes through the right
+ *             field-level function on the way out.
+ *
+ * @invariant  A PARSE ERROR REFUSES THE FRAME (D5 rule 4). Never a partial
+ *             artboard: a half-converted screen that renders is this feature's
+ *             signature failure mode (report success, deliver something else).
+ *
+ * @invariant  ASSET URLS ARE DISCARDED (D6). The response carries loopback
+ *             `assets/<sha1>.svg` constants served by the Dev Mode server
+ *             itself; every one is
+ *             thrown away and the artwork is re-requested BY NODE ID through the
+ *             existing `/v1/images` lane — same frozen host allowlist, same byte
+ *             sniff, same DDR-167 SVG lane, same `renderKey` dedupe. There is no
+ *             new URL surface, and the local server's loopback links (which
+ *             `_fetch-asset.mjs` refuses three ways, correctly) never arise.
+ *
+ * @invariant  `Object.create(null)` FOR EVERY MAP KEYED BY A PARSED STRING
+ *             (D5 rule 5), and `__proto__`/`constructor`/`prototype` are skipped
+ *             wherever a key comes from the document.
+ *
+ * @dependency `oxc-parser` — and this is the named-parser decision D5 rule 1
+ *             asks for, not an implementation detail. It is ALREADY a production
+ *             dependency of `apps/studio` (`package.json` `dependencies`), with
+ *             all seven platform bindings already staged in `devDependencies`,
+ *             and it ALREADY parses third-party-authored TSX in this exact repo
+ *             (`canvas-pipeline.ts` parses every canvas; `ripple.ts`,
+ *             `clip-ops.ts`, `canvas-lib-inline.ts` likewise). So the two costs
+ *             D5 named — "a different risk class from a JS parser" and "it drags
+ *             per-platform staging (D12)" — are both ALREADY PAID by shipped
+ *             code. Choosing it adds no dependency, no staging and no new
+ *             platform matrix; hand-rolling a TSX parser would add several
+ *             hundred lines of novel code whose whole job is to be correct on
+ *             hostile input, which is the strictly worse trade. DDR-042 records
+ *             the bun-compile workaround it needs, and that is already in place.
+ */
+
+import { parseSync } from 'oxc-parser';
+import { FontSubstitutions, type FontToken } from './codegen-fonts.ts';
+import {
+  cssPropToCamel,
+  isAllowedArbitraryProperty,
+  isCodegenColor,
+  isCodegenKeyword,
+  isCodegenLength,
+  isCodegenLengthList,
+  isCodegenNumber,
+  isCodegenShortValueList,
+} from './codegen-values.ts';
+import {
+  attrValue,
+  cleanText,
+  type ImportReport,
+  identifierFromNodeId,
+  jsxStringLiteral,
+  reportToken,
+} from './sanitize.ts';
+
+// Re-exported for the existing from-codegen tests and callers; the helper now
+// lives in sanitize.ts because the `.fig` door needs the same bounding
+// (DDR-221 A8/F1) and `attrValue` is NOT sufficient — it maps rejected
+// characters to SPACES, so a bounded label can still read as prose.
+export { reportToken };
+
+import type { DsToken } from './style-map.ts';
+import { mapClassName, type TailwindContext } from './tailwind-map.ts';
+
+// ── Caps (D5 rule 2 — the response's OWN input-side bounds) ─────────────────
+//
+// D5's existing 512 KB is an OUTPUT cap and `client.ts`'s 8 MB is enforced on a
+// REST response this one never traverses. Measured: a real 375×812 screen is
+// 32 KB of code.
+
+/** Source bytes we will parse at all. */
+export const MAX_SOURCE_BYTES = 512 * 1024;
+/** Emitted JSX bytes per artboard (D5). */
+export const MAX_OUTPUT_BYTES = 512 * 1024;
+/** JSX nodes across the whole module. */
+export const MAX_JSX_NODES = 5_000;
+/** JSX nesting depth. Measured max on a real file: 13. */
+export const MAX_JSX_DEPTH = 40;
+/** Helper components. Figma emits one per component variant set. */
+export const MAX_COMPONENTS = 64;
+/** One text run. Longer is truncated and reported, never dropped. */
+export const MAX_TEXT_LEN = 2_000;
+/** Module-level `const` asset declarations. */
+export const MAX_ASSET_CONSTS = 512;
+
+/**
+ * Elements this converter will emit. D5 rule 3, verbatim, plus `br`.
+ *
+ * Measured surface on a real screen: `div` ×132, `img` ×34, `p` ×26 and one
+ * helper component. The list is already generous against that.
+ *
+ * `svg` is deliberately ABSENT. Inline third-party SVG is a whole other risk
+ * class — the one DDR-167 exists for — and codegen hands vectors over as
+ * `<img src>` anyway, which is the containment the render route also relies on.
+ */
+const ELEMENT_ALLOWLIST: ReadonlySet<string> = new Set([
+  'div',
+  'span',
+  'p',
+  'ul',
+  'ol',
+  'li',
+  'img',
+  'br',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+]);
+
+/** Elements that may not have children. */
+const VOID_ELEMENTS: ReadonlySet<string> = new Set(['img', 'br']);
+
+/** Attributes read off the source. `className` is CONSUMED, never emitted. */
+const ATTRIBUTE_ALLOWLIST: ReadonlySet<string> = new Set([
+  'className',
+  'style',
+  'src',
+  'alt',
+  'data-node-id',
+]);
+
+/** A Figma node id, including the instance form `I425:2940;0:95`. Charset
+ *  excludes every character that could terminate a JSX attribute literal. */
+const NODE_ID_ATTR_RE = /^[A-Za-z0-9:;_-]{1,120}$/;
+
+/** Keys that must never be written into a map built from parsed input. */
+const FORBIDDEN_KEYS: ReadonlySet<string> = new Set(['__proto__', 'constructor', 'prototype']);
+
+/** Refusal. Its message is code-owned and reaches verb stdout (D10). */
+export class CodegenConvertError extends Error {
+  readonly reason: string;
+  constructor(reason: string) {
+    super(`codegen conversion refused: ${reason}`);
+    this.name = 'CodegenConvertError';
+    this.reason = reason;
+  }
+}
+
+export interface ConvertOptions {
+  /** The frame's Figma node id — the identifier space's only root. */
+  nodeId: string;
+  /** Already `attrValue`-bounded by the caller. */
+  label: string;
+  width: number;
+  height: number;
+  kind: string;
+  tokens?: readonly DsToken[];
+  fontTokens?: readonly FontToken[];
+  threshold?: number;
+  report: ImportReport;
+}
+
+export interface PendingCodegenAsset {
+  nodeId: string;
+  format: 'svg';
+  placeholder: string;
+}
+
+export interface ConvertResult {
+  /** The `<DCArtboard>…</DCArtboard>` block, ready to splice into a canvas. */
+  artboardJsx: string;
+  /** Helper component declarations, for module scope above the canvas export. */
+  helpers: string;
+  /** Artwork to fetch by node id through the existing `/v1/images` lane (D6). */
+  pendingAssets: PendingCodegenAsset[];
+  /** Distinct Tailwind utilities the mapper did not know. */
+  unmappedUtilities: string[];
+  bytes: number;
+  /**
+   * The root element's own `data-node-id`, for the open-document cross-check.
+   * `null` when the response did not carry one.
+   */
+  rootNodeId: string | null;
+  /**
+   * The root element's `data-name`, `attrValue`-bounded — the raw layer name is
+   * NEVER kept. Compared against the stored frame label by the caller and then
+   * discarded; it exists only to answer "is this the document we imported?"
+   * (DDR-219 probe finding 1 / residual 8).
+   */
+  rootName: string;
+}
+
+// ── AST helpers ─────────────────────────────────────────────────────────────
+
+/* biome-ignore-start lint/suspicious/noExplicitAny: oxc AST nodes are
+   heterogeneous; every access below is shape-checked at its use site, which is
+   the same discipline canvas-pipeline.ts states for the same parser. */
+type Node = any;
+
+/** oxc preserves `(expr)`. Every expression read must unwrap it first. */
+function unparen(n: Node): Node {
+  let cur = n;
+  for (let i = 0; i < 8 && cur && cur.type === 'ParenthesizedExpression'; i += 1)
+    cur = cur.expression;
+  return cur;
+}
+
+function isStringLiteral(n: Node): boolean {
+  return n && n.type === 'Literal' && typeof n.value === 'string';
+}
+
+function jsxName(n: Node): string | null {
+  if (!n) return null;
+  if (n.type === 'JSXIdentifier') return String(n.name);
+  // `<Foo.Bar>` / `<svg:use>` — refused by returning null, never resolved.
+  return null;
+}
+
+function attrName(a: Node): string | null {
+  if (a.type !== 'JSXAttribute') return null;
+  return jsxName(a.name);
+}
+
+// ── The converter ───────────────────────────────────────────────────────────
+
+interface ComponentDecl {
+  /** The regenerated name. The source name never survives. */
+  name: string;
+  /** original prop name → regenerated parameter name. */
+  props: Map<string, string>;
+  /** original prop name → its string-literal default, already escaped. */
+  defaults: Map<string, string>;
+  /** original local const → regenerated name. */
+  locals: Map<string, string>;
+  /** The prop that carried `className`, renamed to a STYLE object. */
+  styleProp: string | null;
+  node: Node;
+}
+
+/**
+ * Convert one codegen module.
+ *
+ * The whole function is a single pass with hard caps and no recovery: anything
+ * outside the supported subset throws, and the caller turns that into a refusal
+ * with a `codegen-unavailable` disposition. There is deliberately no "best
+ * effort" branch — a design importer that guesses is worse than one that stops.
+ */
+export function convertCodegenModule(source: string, opts: ConvertOptions): ConvertResult {
+  if (source.length > MAX_SOURCE_BYTES) throw new CodegenConvertError('response over the size cap');
+  if (source.length === 0) throw new CodegenConvertError('empty response');
+
+  const parsed = parseSync('figma-codegen.tsx', source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    // The parser's own message can quote the source, so it is NOT propagated
+    // (D10: every byte this verb prints is code-owned).
+    throw new CodegenConvertError('response did not parse as a TSX module');
+  }
+
+  const tw: TailwindContext = {
+    ...(opts.tokens ? { tokens: opts.tokens } : {}),
+    ...(opts.fontTokens ? { fontTokens: opts.fontTokens } : {}),
+    ...(opts.threshold !== undefined ? { threshold: opts.threshold } : {}),
+  };
+  const root = identifierFromNodeId(opts.nodeId);
+  const fonts = new FontSubstitutions();
+  const unmapped = new Set<string>();
+  const pendingAssets: PendingCodegenAsset[] = [];
+  const assetPlaceholders = new Map<string, string>();
+
+  /** Asset constant name → its (discarded) URL. Kept only so a `src={ident}`
+   *  can be RECOGNISED as an asset reference rather than an unknown identifier. */
+  const assetConsts: Set<string> = new Set();
+  const components: ComponentDecl[] = [];
+  const byOriginalName = new Map<string, ComponentDecl>();
+  let rootComponent: ComponentDecl | null = null;
+  let jsxNodes = 0;
+
+  // ── Pass 1 — top-level shape ──
+  for (const stmt of parsed.program.body as Node[]) {
+    switch (stmt.type) {
+      case 'VariableDeclaration': {
+        for (const d of stmt.declarations) {
+          if (d.id?.type !== 'Identifier' || !isStringLiteral(unparen(d.init))) {
+            throw new CodegenConvertError('unsupported module-level declaration');
+          }
+          if (assetConsts.size >= MAX_ASSET_CONSTS) {
+            throw new CodegenConvertError('too many asset constants');
+          }
+          // The URL is READ AND DROPPED HERE. Nothing downstream can reach it,
+          // which is what makes D6 structural rather than a convention.
+          assetConsts.add(String(d.id.name));
+        }
+        break;
+      }
+      case 'TSTypeAliasDeclaration':
+      case 'TSInterfaceDeclaration':
+        // Types are dropped wholesale — we regenerate plain-JS signatures, so
+        // there is nothing for a type to describe. (The first spike left these
+        // in the output and they rendered as body text.)
+        break;
+      case 'FunctionDeclaration': {
+        const decl = declareComponent(stmt, root, components.length);
+        components.push(decl);
+        if (stmt.id?.name) byOriginalName.set(String(stmt.id.name), decl);
+        break;
+      }
+      case 'ExportDefaultDeclaration': {
+        const inner = stmt.declaration;
+        if (inner?.type !== 'FunctionDeclaration') {
+          throw new CodegenConvertError('default export is not a component');
+        }
+        const decl = declareComponent(inner, root, components.length);
+        rootComponent = decl;
+        if (inner.id?.name) byOriginalName.set(String(inner.id.name), decl);
+        break;
+      }
+      default:
+        throw new CodegenConvertError('unsupported module-level statement');
+    }
+    if (components.length > MAX_COMPONENTS) throw new CodegenConvertError('too many components');
+  }
+  if (!rootComponent) throw new CodegenConvertError('no default-exported component');
+
+  // ── Emission ──
+
+  /** Escape + bound one text run; empty means "nothing to emit". */
+  function textChild(raw: string): string | null {
+    const trimmed = raw.replace(/\s+/g, ' ');
+    if (trimmed.trim().length === 0) return null;
+    const clean = cleanText(trimmed, MAX_TEXT_LEN);
+    if (clean.strippedHidden) {
+      opts.report.add(opts.nodeId, 'TEXT', 'hidden-chars-dropped', 'codegen text');
+    }
+    if (clean.truncated) opts.report.add(opts.nodeId, 'TEXT', 'truncated-text', 'codegen text');
+    if (clean.text.trim().length === 0) return null;
+    return `{${jsxStringLiteral(clean.text)}}`;
+  }
+
+  /** A validated declaration map → a JSX style-object literal. */
+  function styleLiteral(decls: Record<string, string>): string {
+    const parts: string[] = [];
+    for (const [k, v] of Object.entries(decls)) {
+      // Keys come from OUR tables, never from the document — but the guard is
+      // free and this is a map that a future edit could start feeding parsed
+      // keys into.
+      if (FORBIDDEN_KEYS.has(k) || !/^[A-Za-z][A-Za-z0-9]{0,48}$/.test(k)) continue;
+      parts.push(`${k}: ${jsxStringLiteral(v)}`);
+    }
+    return `{ ${parts.join(', ')} }`;
+  }
+
+  /**
+   * Read an inline `style={{…}}`. Figma emits exactly one on a real screen
+   * (`fontVariationSettings`), but it is a direct write into the style object so
+   * it gets the same property allowlist as the bracket utilities.
+   */
+  function inlineStyle(expr: Node): Record<string, string> {
+    const out: Record<string, string> = Object.create(null);
+    const obj = unparen(expr);
+    if (obj?.type !== 'ObjectExpression') return out;
+    for (const prop of obj.properties as Node[]) {
+      if (prop.type !== 'Property' || prop.computed) continue;
+      const key = prop.key?.type === 'Identifier' ? String(prop.key.name) : prop.key?.value;
+      if (typeof key !== 'string' || FORBIDDEN_KEYS.has(key)) continue;
+      const camel = cssPropToCamel(key);
+      // The allowlist is spelled in kebab-case, so probe both spellings rather
+      // than assuming which form the document used.
+      const kebab = key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+      if (!isAllowedArbitraryProperty(kebab)) {
+        unmapped.add(`style:${attrValue(key, 24)}`);
+        continue;
+      }
+      const value = unparen(prop.value);
+      const raw =
+        value?.type === 'Literal' &&
+        (typeof value.value === 'string' || typeof value.value === 'number')
+          ? String(value.value)
+          : null;
+      if (raw === null) {
+        unmapped.add(`style:${attrValue(key, 24)}`);
+        continue;
+      }
+      if (
+        !isCodegenKeyword(raw) &&
+        !isCodegenLength(raw) &&
+        !isCodegenNumber(raw) &&
+        !isCodegenLengthList(raw) &&
+        !isCodegenShortValueList(raw) &&
+        !isCodegenColor(raw) &&
+        !/^"[A-Za-z]{1,8}" -?\d{1,4}$/.test(raw)
+      ) {
+        unmapped.add(`style:${attrValue(key, 24)}`);
+        continue;
+      }
+      out[camel] = raw;
+    }
+    return out;
+  }
+
+  /**
+   * Turn a `className` attribute into style. Returns the SPREAD sources so a
+   * component that forwards its incoming style still composes.
+   *
+   * Supported, because these are what a real response contains:
+   *   `className="a b"`, `className={"a b"}`,
+   *   `className={someProp || "a b"}`  (the forwarding idiom),
+   *   `` className={`a b ${someProp}`} ``.
+   * Anything else is a BOUNDED DEGRADATION, not a refusal: the classes are lost,
+   * the element survives, and `codegen-utility-unmapped` says so. Refusing a
+   * whole frame over one dynamic class string would trade a small visual loss
+   * for a total one.
+   */
+  function classNameToStyle(
+    value: Node,
+    scope: ComponentDecl | null
+  ): { decls: Record<string, string>; spreads: string[] } {
+    const decls: Record<string, string> = Object.create(null);
+    const spreads: string[] = [];
+    const take = (literal: string): void => {
+      const mapped = mapClassName(literal, tw);
+      Object.assign(decls, mapped.declarations);
+      for (const u of mapped.unmapped) unmapped.add(attrValue(u, 40) || 'unprintable');
+      for (const f of mapped.substitutedFonts)
+        fonts.note({ css: '', substituted: true, requested: f });
+    };
+    const ident = (n: Node): boolean => {
+      if (n?.type !== 'Identifier' || !scope) return false;
+      const renamed = scope.props.get(String(n.name)) ?? scope.locals.get(String(n.name));
+      if (!renamed) return false;
+      spreads.push(renamed);
+      return true;
+    };
+
+    if (isStringLiteral(value)) {
+      take(String(value.value));
+      return { decls, spreads };
+    }
+    if (value?.type !== 'JSXExpressionContainer') {
+      unmapped.add('className:unsupported');
+      return { decls, spreads };
+    }
+    const expr = unparen(value.expression);
+    if (isStringLiteral(expr)) {
+      take(String(expr.value));
+      return { decls, spreads };
+    }
+    if (expr?.type === 'LogicalExpression' && (expr.operator === '||' || expr.operator === '??')) {
+      const left = unparen(expr.left);
+      const right = unparen(expr.right);
+      // `className || "fallback"` — the fallback IS the design's own styling and
+      // the prop is the caller's override. Merged prop-last so the override wins,
+      // which is a superset of the source's either/or semantics.
+      if (isStringLiteral(right)) take(String(right.value));
+      if (!ident(left)) unmapped.add('className:dynamic');
+      return { decls, spreads };
+    }
+    if (expr?.type === 'TemplateLiteral') {
+      for (const q of expr.quasis as Node[]) take(String(q.value?.cooked ?? ''));
+      for (const e of expr.expressions as Node[]) {
+        if (!ident(unparen(e))) unmapped.add('className:dynamic');
+      }
+      return { decls, spreads };
+    }
+    unmapped.add('className:dynamic');
+    return { decls, spreads };
+  }
+
+  /** Emit one JSX element/child. `nodeIdCtx` is the nearest `data-node-id`. */
+  function emitNode(
+    n: Node,
+    scope: ComponentDecl | null,
+    depth: number,
+    nodeIdCtx: string
+  ): string | null {
+    if (depth > MAX_JSX_DEPTH) throw new CodegenConvertError('JSX nesting over the depth cap');
+    jsxNodes += 1;
+    if (jsxNodes > MAX_JSX_NODES) throw new CodegenConvertError('JSX node count over the cap');
+
+    const node = unparen(n);
+    if (!node) return null;
+
+    switch (node.type) {
+      case 'JSXText':
+        return textChild(String(node.value ?? ''));
+      case 'Literal':
+        return typeof node.value === 'string' ? textChild(node.value) : null;
+      case 'JSXFragment': {
+        const kids = emitChildren(node.children, scope, depth + 1, nodeIdCtx);
+        return kids.length > 0 ? `<>\n${kids.join('\n')}\n</>` : null;
+      }
+      case 'JSXExpressionContainer': {
+        const expr = unparen(node.expression);
+        if (!expr || expr.type === 'JSXEmptyExpression') return null;
+        if (isStringLiteral(expr)) return textChild(String(expr.value));
+        if (expr.type === 'TemplateLiteral') {
+          // Figma wraps text containing `&` or `{` in a template literal
+          // (`` {`Ancient Near East & Egypt`} ``) rather than escaping it. With
+          // no interpolations it is just text; WITH one it would be a value this
+          // converter cannot resolve, so that refuses rather than dropping the
+          // dynamic half and shipping a sentence with a hole in it.
+          if ((expr.expressions ?? []).length > 0) {
+            throw new CodegenConvertError('interpolated template as a child');
+          }
+          return textChild(
+            (expr.quasis ?? []).map((q: Node) => String(q.value?.cooked ?? '')).join('')
+          );
+        }
+        if (expr.type === 'LogicalExpression' && expr.operator === '&&') {
+          // `{isAccount && (<div/>)}` — Figma's variant idiom.
+          const test = unparen(expr.left);
+          if (!scope || test?.type !== 'Identifier') {
+            throw new CodegenConvertError('unsupported conditional child');
+          }
+          const renamed = scope.locals.get(String(test.name)) ?? scope.props.get(String(test.name));
+          if (!renamed) throw new CodegenConvertError('unsupported conditional child');
+          const body = emitNode(expr.right, scope, depth + 1, nodeIdCtx);
+          return body ? `{${renamed} && (\n${indent(body, 1)}\n)}` : null;
+        }
+        if (expr.type === 'ConditionalExpression') {
+          const test = unparen(expr.test);
+          if (!scope || test?.type !== 'Identifier') {
+            throw new CodegenConvertError('unsupported conditional child');
+          }
+          const renamed = scope.locals.get(String(test.name)) ?? scope.props.get(String(test.name));
+          if (!renamed) throw new CodegenConvertError('unsupported conditional child');
+          const a = emitNode(expr.consequent, scope, depth + 1, nodeIdCtx) ?? 'null';
+          const b = emitNode(expr.alternate, scope, depth + 1, nodeIdCtx) ?? 'null';
+          return `{${renamed} ? (\n${indent(a, 1)}\n) : (\n${indent(b, 1)}\n)}`;
+        }
+        throw new CodegenConvertError('unsupported JSX expression');
+      }
+      case 'JSXElement':
+        return emitElement(node, scope, depth, nodeIdCtx);
+      default:
+        throw new CodegenConvertError('unsupported JSX child');
+    }
+  }
+
+  function emitChildren(
+    children: Node[] | undefined,
+    scope: ComponentDecl | null,
+    depth: number,
+    nodeIdCtx: string
+  ): string[] {
+    const out: string[] = [];
+    for (const c of children ?? []) {
+      const emitted = emitNode(c, scope, depth, nodeIdCtx);
+      if (emitted) out.push(indent(emitted, 1));
+    }
+    return out;
+  }
+
+  function emitElement(
+    node: Node,
+    scope: ComponentDecl | null,
+    depth: number,
+    parentNodeId: string
+  ): string {
+    const rawName = jsxName(node.openingElement?.name);
+    if (!rawName) throw new CodegenConvertError('unsupported element name');
+
+    const component = byOriginalName.get(rawName);
+    const isComponent = component !== undefined;
+    if (!isComponent && !ELEMENT_ALLOWLIST.has(rawName)) {
+      // Refusal, not a drop. This feature's history is losing content while
+      // reporting success; an element outside the allowlist is a structural
+      // surprise and it stops the frame.
+      throw new CodegenConvertError('element outside the allowlist');
+    }
+
+    const decls: Record<string, string> = Object.create(null);
+    const spreads: string[] = [];
+    const attrs: string[] = [];
+    let ownNodeId = parentNodeId;
+    let src: string | null = null;
+    let hasSrc = false;
+
+    for (const a of (node.openingElement?.attributes ?? []) as Node[]) {
+      if (a.type === 'JSXSpreadAttribute') {
+        throw new CodegenConvertError('spread attribute');
+      }
+      const name = attrName(a);
+      if (!name) continue;
+
+      if (isComponent) {
+        // A helper's props are its own vocabulary. Only string-literal values
+        // pass, and only for props the declaration actually declared.
+        if (name === 'className') {
+          const st = classNameToStyle(a.value, scope);
+          Object.assign(decls, st.decls);
+          spreads.push(...st.spreads);
+          continue;
+        }
+        const renamed = component.props.get(name);
+        const v = a.value;
+        if (renamed && isStringLiteral(v)) {
+          attrs.push(`${renamed}={${jsxStringLiteral(String(v.value))}}`);
+        } else if (
+          renamed &&
+          v?.type === 'JSXExpressionContainer' &&
+          isStringLiteral(unparen(v.expression))
+        ) {
+          attrs.push(`${renamed}={${jsxStringLiteral(String(unparen(v.expression).value))}}`);
+        }
+        continue;
+      }
+
+      if (!ATTRIBUTE_ALLOWLIST.has(name)) continue;
+
+      if (name === 'className') {
+        const st = classNameToStyle(a.value, scope);
+        Object.assign(decls, st.decls);
+        spreads.push(...st.spreads);
+        continue;
+      }
+      if (name === 'style') {
+        const v = a.value;
+        if (v?.type === 'JSXExpressionContainer') Object.assign(decls, inlineStyle(v.expression));
+        continue;
+      }
+      if (name === 'data-node-id') {
+        const raw = isStringLiteral(a.value) ? String(a.value.value) : '';
+        if (NODE_ID_ATTR_RE.test(raw)) ownNodeId = raw;
+        continue;
+      }
+      if (name === 'alt') {
+        const raw = isStringLiteral(a.value) ? String(a.value.value) : '';
+        attrs.push(`alt=${JSON.stringify(attrValue(raw, 64))}`);
+        continue;
+      }
+      if (name === 'src') {
+        hasSrc = true;
+        const v = a.value;
+        const expr = v?.type === 'JSXExpressionContainer' ? unparen(v.expression) : null;
+        // ONLY a reference to a module-level asset constant is recognised. A
+        // literal URL is refused rather than downloaded — there is no URL entry
+        // point into the asset lane and this route must not invent one (D6).
+        if (expr?.type === 'Identifier' && assetConsts.has(String(expr.name))) {
+          src = assetFor(ownNodeId);
+        }
+      }
+    }
+
+    if (rawName === 'img' && hasSrc && src === null) {
+      opts.report.add(ownNodeId, 'ASSET', 'asset-skipped', 'unrecognized codegen src');
+    }
+
+    const styleParts: string[] = [];
+    if (Object.keys(decls).length > 0) styleParts.push(`...${styleLiteral(decls)}`);
+    for (const s of spreads) styleParts.push(`...${s}`);
+    const styleAttr =
+      styleParts.length > 0
+        ? styleParts.length === 1 && styleParts[0].startsWith('...{')
+          ? ` style={${styleLiteral(decls)}}`
+          : ` style={{ ${styleParts.join(', ')} }}`
+        : '';
+
+    const name = isComponent ? component.name : rawName;
+    const provenance =
+      !isComponent && ownNodeId && ownNodeId !== parentNodeId
+        ? ` data-figma-node=${JSON.stringify(ownNodeId)}`
+        : '';
+    const srcAttr = src ? ` src=${JSON.stringify(src)}` : '';
+    const extra = attrs.length > 0 ? ` ${attrs.join(' ')}` : '';
+    const open = `<${name}${styleAttr}${srcAttr}${extra}${provenance}`;
+
+    if (isComponent || VOID_ELEMENTS.has(rawName)) {
+      if (!isComponent && (node.children ?? []).length > 0) {
+        throw new CodegenConvertError('void element with children');
+      }
+      return `${open} />`;
+    }
+
+    const kids = emitChildren(node.children, scope, depth + 1, ownNodeId);
+    if (kids.length === 0) return `${open} />`;
+    return `${open}>\n${kids.join('\n')}\n</${name}>`;
+  }
+
+  /** One placeholder per source NODE, so `renderKey` dedupe does the rest (D6). */
+  function assetFor(nodeId: string): string {
+    const existing = assetPlaceholders.get(nodeId);
+    if (existing) return existing;
+    const placeholder = `/assets/pending-codegen-${nodeId.replace(/[^0-9]+/g, '-')}.svg`;
+    assetPlaceholders.set(nodeId, placeholder);
+    pendingAssets.push({ nodeId, format: 'svg', placeholder });
+    return placeholder;
+  }
+
+  /** A component's `return` — the one statement shape that produces output. */
+  function componentBody(decl: ComponentDecl): string {
+    const body = decl.node.body?.body ?? [];
+    let ret: Node | null = null;
+    const consts: string[] = [];
+    for (const stmt of body as Node[]) {
+      if (stmt.type === 'VariableDeclaration') {
+        for (const d of stmt.declarations) {
+          const renamed = decl.locals.get(String(d.id?.name ?? ''));
+          const init = unparen(d.init);
+          // The only local a real response declares is a variant test —
+          // `const isAccount = property1 === "account"`. Nothing else is
+          // admitted, because anything else is code we would be re-emitting
+          // without understanding it.
+          if (!renamed || !init || init.type !== 'BinaryExpression') {
+            throw new CodegenConvertError('unsupported local declaration');
+          }
+          if (init.operator !== '===' && init.operator !== '!==') {
+            throw new CodegenConvertError('unsupported local declaration');
+          }
+          const left = unparen(init.left);
+          const right = unparen(init.right);
+          const leftName = left?.type === 'Identifier' ? decl.props.get(String(left.name)) : null;
+          if (!leftName || !isStringLiteral(right)) {
+            throw new CodegenConvertError('unsupported local declaration');
+          }
+          consts.push(
+            `  const ${renamed} = ${leftName} ${init.operator} ${jsxStringLiteral(String(right.value))};`
+          );
+        }
+        continue;
+      }
+      if (stmt.type === 'ReturnStatement') {
+        ret = stmt.argument;
+        continue;
+      }
+      throw new CodegenConvertError('unsupported statement in a component');
+    }
+    if (!ret) throw new CodegenConvertError('component returns nothing');
+    const jsx = emitNode(ret, decl, 0, opts.nodeId);
+    if (!jsx) throw new CodegenConvertError('component produced no output');
+    return `${consts.join('\n')}${consts.length ? '\n' : ''}  return (\n${indent(jsx, 2)}\n  );`;
+  }
+
+  const helperSources: string[] = [];
+  for (const decl of components) {
+    helperSources.push(`function ${decl.name}(${paramList(decl)}) {\n${componentBody(decl)}\n}`);
+  }
+  const rootJsx = (() => {
+    const body = componentBody(rootComponent);
+    // The root component's body is inlined into the artboard rather than kept as
+    // a component: an artboard IS the component boundary here, and one fewer
+    // indirection is one fewer thing the selection ladder drills through.
+    const m = /return \(\n([\s\S]*)\n {2}\);$/.exec(body);
+    if (!m) throw new CodegenConvertError('root component has an unsupported shape');
+    return m[1];
+  })();
+
+  fonts.flush(opts.report, opts.nodeId);
+  for (const u of [...unmapped].sort().slice(0, 40)) {
+    opts.report.add(opts.nodeId, 'CSS', 'codegen-utility-unmapped', reportToken(u));
+  }
+  if (unmapped.size > 40) {
+    opts.report.add(
+      opts.nodeId,
+      'CSS',
+      'codegen-utility-unmapped',
+      `and ${unmapped.size - 40} more`
+    );
+  }
+
+  const abId = identifierFromNodeId(opts.nodeId).toLowerCase().replace(/_/g, '-');
+  const artboardJsx = `      <DCArtboard
+        id=${JSON.stringify(abId)}
+        label=${JSON.stringify(`${opts.label} · codegen`)}
+        width={${Math.max(1, Math.round(opts.width))}}
+        height={${Math.max(1, Math.round(opts.height))}}
+        kind=${JSON.stringify(ARTBOARD_KINDS.has(opts.kind) ? opts.kind : 'digital')}
+        layout="block"
+      >
+${indent(rootJsx, 2)}
+      </DCArtboard>`;
+
+  const helpers = helperSources.join('\n\n');
+  const bytes = artboardJsx.length + helpers.length;
+  if (bytes > MAX_OUTPUT_BYTES)
+    throw new CodegenConvertError('emitted artboard over the output cap');
+
+  const rootMeta = rootIdentity(rootComponent);
+
+  return {
+    artboardJsx,
+    helpers,
+    pendingAssets,
+    unmappedUtilities: [...unmapped].sort(),
+    bytes,
+    rootNodeId: rootMeta.nodeId,
+    rootName: rootMeta.name,
+  };
+}
+
+/**
+ * The root element's `data-node-id` + bounded `data-name`.
+ *
+ * Read straight off the AST rather than off the emitted output, because the
+ * emitter deliberately drops `data-name` (a raw layer name) and omits
+ * `data-figma-node` on the root. This is the ONLY place that name is read, it is
+ * bounded on the way out, and the caller compares it and throws it away.
+ */
+function rootIdentity(decl: ComponentDecl): { nodeId: string | null; name: string } {
+  let nodeId: string | null = null;
+  let name = '';
+  for (const stmt of (decl.node.body?.body ?? []) as Node[]) {
+    if (stmt.type !== 'ReturnStatement') continue;
+    const el = unparen(stmt.argument);
+    if (el?.type !== 'JSXElement') break;
+    for (const a of (el.openingElement?.attributes ?? []) as Node[]) {
+      const n = attrName(a);
+      if (!isStringLiteral(a.value)) continue;
+      if (n === 'data-node-id' && NODE_ID_ATTR_RE.test(String(a.value.value))) {
+        nodeId = String(a.value.value);
+      }
+      if (n === 'data-name') name = attrValue(String(a.value.value), 64);
+    }
+    break;
+  }
+  return { nodeId, name };
+}
+
+/**
+ * The existing `<DCArtboard id="…">`'s own size and label.
+ *
+ * Read from the CANVAS rather than only from `.meta.json` because the canvas is
+ * the live truth: sizes are JSX-authoritative (DDR-027), a user may have resized
+ * the board since the import, and canvases imported before `figma.frames[]`
+ * carried `w`/`h` have no stored size at all. Returns `null` when the artboard
+ * is absent — the caller turns that into a refusal.
+ */
+/**
+ * Does this source parse as a TSX module?
+ *
+ * Exported so the WRITE path can gate on it. DDR-219 D8 says "build out-of-tree,
+ * validate it parses, then write", and the first implementation spliced by byte
+ * range and renamed straight onto the live path — the validation existed only in
+ * the comment (post-implementation review F2).
+ */
+export function parsesAsModule(source: string): boolean {
+  try {
+    return parseSync('canvas.tsx', source, { sourceType: 'module' }).errors.length === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The closed set of artboard kinds (`canvas-lib.tsx`'s `ArtboardKind`).
+ *
+ * An ALLOWLIST, because `kind` lands in an emitted JSX opening tag. The first
+ * version took it from a `.meta.json` field with no bound at all, which made a
+ * peer-authored sidecar an injection vector into canvas source — see
+ * `explodeArtboard`'s note. A closed enum is the whole vocabulary, so nothing
+ * legitimate is lost by refusing everything else.
+ */
+export const ARTBOARD_KINDS: ReadonlySet<string> = new Set(['digital', 'print', 'web', 'video']);
+
+export function readArtboardBox(
+  canvasSource: string,
+  artboardId: string
+): { width: number; height: number; label: string; kind: string } | null {
+  const parsed = parseSync('canvas.tsx', canvasSource, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) return null;
+
+  let found: { width: number; height: number; label: string; kind: string } | null = null;
+  const numeric = (a: Node): number | null => {
+    const v = a?.value;
+    if (v?.type === 'JSXExpressionContainer') {
+      const e = unparen(v.expression);
+      if (e?.type === 'Literal' && typeof e.value === 'number') return e.value;
+    }
+    if (v?.type === 'Literal' && typeof v.value === 'number') return v.value;
+    return null;
+  };
+  const walk = (n: Node): void => {
+    if (!n || typeof n !== 'object' || found) return;
+    if (Array.isArray(n)) {
+      for (const c of n) walk(c);
+      return;
+    }
+    if (n.type === 'JSXElement' && jsxName(n.openingElement?.name) === 'DCArtboard') {
+      let id: string | null = null;
+      let width: number | null = null;
+      let height: number | null = null;
+      let label = '';
+      // Default, not a passthrough: an unrecognised kind is refused rather than
+      // carried, because this value is re-emitted into a JSX opening tag.
+      let kind = 'digital';
+      for (const a of (n.openingElement?.attributes ?? []) as Node[]) {
+        const k = attrName(a);
+        if (k === 'id' && isStringLiteral(a.value)) id = String(a.value.value);
+        if (k === 'label' && isStringLiteral(a.value)) label = attrValue(String(a.value.value), 64);
+        if (k === 'kind' && isStringLiteral(a.value) && ARTBOARD_KINDS.has(String(a.value.value))) {
+          kind = String(a.value.value);
+        }
+        if (k === 'width') width = numeric(a);
+        if (k === 'height') height = numeric(a);
+      }
+      if (id === artboardId && width !== null && height !== null) {
+        found = { width, height, label, kind };
+        return;
+      }
+    }
+    for (const k of Object.keys(n)) {
+      if (k === 'type' || k === 'start' || k === 'end') continue;
+      walk(n[k]);
+    }
+  };
+  walk(parsed.program);
+  return found;
+}
+
+/**
+ * Replace ONE `<DCArtboard id="…">` subtree in an existing canvas, and hoist the
+ * helper components to module scope.
+ *
+ * Parsed, not regexed, for the same reason the converter is: a canvas is a real
+ * TSX file and `<DCArtboard` appears in its header comment. A byte-range
+ * replacement over a located AST node cannot mistake prose for markup.
+ *
+ * @throws CodegenConvertError when the artboard id is not present exactly once —
+ *         the write model refuses rather than guessing which one was meant.
+ */
+export function spliceArtboard(
+  canvasSource: string,
+  opts: { artboardId: string; artboardJsx: string; helpers: string; banner: string }
+): string {
+  const parsed = parseSync('canvas.tsx', canvasSource, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CodegenConvertError('target canvas does not parse');
+  }
+
+  const hits: Array<{ start: number; end: number }> = [];
+  let exportStart = -1;
+
+  const walk = (n: Node): void => {
+    if (!n || typeof n !== 'object') return;
+    if (Array.isArray(n)) {
+      for (const c of n) walk(c);
+      return;
+    }
+    if (n.type === 'ExportDefaultDeclaration' && exportStart < 0) exportStart = n.start;
+    if (n.type === 'JSXElement' && jsxName(n.openingElement?.name) === 'DCArtboard') {
+      for (const a of (n.openingElement?.attributes ?? []) as Node[]) {
+        if (attrName(a) !== 'id') continue;
+        const v = a.value;
+        const literal = isStringLiteral(v)
+          ? String(v.value)
+          : v?.type === 'JSXExpressionContainer' && isStringLiteral(unparen(v.expression))
+            ? String(unparen(v.expression).value)
+            : null;
+        if (literal === opts.artboardId) hits.push({ start: n.start, end: n.end });
+      }
+    }
+    for (const k of Object.keys(n)) {
+      if (k === 'type' || k === 'start' || k === 'end') continue;
+      walk(n[k]);
+    }
+  };
+  walk(parsed.program);
+
+  if (hits.length === 0) throw new CodegenConvertError('artboard id not found in the canvas');
+  if (hits.length > 1) throw new CodegenConvertError('artboard id is not unique in the canvas');
+  if (exportStart < 0) throw new CodegenConvertError('canvas has no default export');
+
+  const hit = hits[0];
+  if (hit.start <= exportStart) throw new CodegenConvertError('artboard is outside the export');
+
+  // Both edits are byte offsets into the SAME original source, and the export
+  // always starts before the artboard it contains — so splicing from the end
+  // backwards keeps the earlier offset valid without a source-map library.
+  const preamble = `${opts.banner}\n${opts.helpers ? `${opts.helpers}\n\n` : ''}`;
+  // The artboard block carries its own leading indentation.
+  const artboard = opts.artboardJsx.replace(/^\s+/, '');
+  return (
+    canvasSource.slice(0, exportStart) +
+    preamble +
+    canvasSource.slice(exportStart, hit.start) +
+    artboard +
+    canvasSource.slice(hit.end)
+  );
+}
+
+/**
+ * Declare a component with a FULLY REGENERATED signature.
+ *
+ * Every name here — the component, each parameter, each local — is derived from
+ * the frame's node id and an index. Nothing from the response's identifier space
+ * survives, which is the only way DDR-216 D6's "airtight" claim stays true on a
+ * route that receives third-party source (DDR-219 D4).
+ */
+function declareComponent(fn: Node, rootId: string, index: number): ComponentDecl {
+  const decl: ComponentDecl = {
+    name: `${rootId}_C${index}`,
+    props: new Map(),
+    defaults: new Map(),
+    locals: new Map(),
+    styleProp: null,
+    node: fn,
+  };
+
+  const params = fn.params ?? [];
+  if (params.length > 1) throw new CodegenConvertError('component takes more than one parameter');
+  if (params.length === 1) {
+    const p = params[0];
+    if (p.type !== 'ObjectPattern') throw new CodegenConvertError('non-destructured props');
+    let i = 0;
+    for (const prop of p.properties as Node[]) {
+      if (prop.type !== 'Property' || prop.computed) {
+        throw new CodegenConvertError('unsupported prop pattern');
+      }
+      const key = prop.key?.type === 'Identifier' ? String(prop.key.name) : null;
+      if (!key || FORBIDDEN_KEYS.has(key)) throw new CodegenConvertError('unsupported prop name');
+      const renamed = `p${i}`;
+      i += 1;
+      decl.props.set(key, renamed);
+      // `className` becomes a STYLE object: this converter turns classes into
+      // inline style everywhere else, so a forwarded `className` would be the
+      // one string in the output nothing consumes.
+      if (key === 'className') decl.styleProp = renamed;
+      const value = prop.value;
+      if (value?.type === 'AssignmentPattern') {
+        const right = unparen(value.right);
+        if (!isStringLiteral(right)) throw new CodegenConvertError('unsupported prop default');
+        decl.defaults.set(key, jsxStringLiteral(String(right.value)));
+      }
+    }
+  }
+
+  // Locals are enumerated up front so a JSX body can reference one declared
+  // above it without the emitter needing a second pass.
+  let li = 0;
+  for (const stmt of (fn.body?.body ?? []) as Node[]) {
+    if (stmt.type !== 'VariableDeclaration') continue;
+    for (const d of stmt.declarations) {
+      if (d.id?.type !== 'Identifier')
+        throw new CodegenConvertError('unsupported local declaration');
+      decl.locals.set(String(d.id.name), `v${li}`);
+      li += 1;
+    }
+  }
+  return decl;
+}
+
+function paramList(decl: ComponentDecl): string {
+  if (decl.props.size === 0) return '';
+  const parts: string[] = [];
+  for (const [original, renamed] of decl.props) {
+    if (renamed === decl.styleProp) {
+      parts.push(`${renamed} = {}`);
+      continue;
+    }
+    const def = decl.defaults.get(original);
+    parts.push(def ? `${renamed} = ${def}` : renamed);
+  }
+  return `{ ${parts.join(', ')} }`;
+}
+
+function indent(text: string, levels: number): string {
+  const pad = '  '.repeat(levels);
+  return text
+    .split('\n')
+    .map((line) => (line.length > 0 ? pad + line : line))
+    .join('\n');
+}
+/* biome-ignore-end lint/suspicious/noExplicitAny: see the note above. */