@1agh/maude 0.58.2 → 0.59.0

package/apps/studio/figma/types.ts

@@ -0,0 +1,544 @@
+/**
+ * @file       figma/types.ts — the normalized Figma node tree (DDR-216).
+ * @scope      apps/studio/figma/types.ts
+ * @purpose    The ONE shape both ingestion doors emit and all three translators
+ *             consume. `client.ts` (REST, Phase 1) produces it today; a future
+ *             `fig-decode.ts` (Phase 6) only has to produce the same shape and
+ *             it inherits `to-strokes` / `to-artboard` / `to-tokens` for free.
+ *             That seam is also what makes Phase 6's Tier-2 differential smoke
+ *             possible at all — the same document through both doors must
+ *             normalize to the same tree.
+ *
+ * @invariant  FIELD NAMES MIRROR THE REST API deliberately. Renaming them into
+ *             a prettier house vocabulary would make the Phase-6 decoder's job
+ *             "translate twice" instead of "emit this shape", and would make a
+ *             differential diff read as a wall of false positives.
+ *
+ * @invariant  EVERY STRING FROM A DOCUMENT IS UNTRUSTED. `name` and
+ *             `characters` in particular: a TEXT node's layer name DEFAULTS to
+ *             its own content, so `name` is user text on a real file. They are
+ *             carried verbatim through normalization on purpose — sanitization
+ *             belongs at the emission sinks (DDR-216 D6), where the target
+ *             grammar is known — and are marked UNTRUSTED at every declaration
+ *             so nobody interpolates one into JSX, a path or a shell argument
+ *             on the way past.
+ *
+ * @invariant  DEPENDENCY-FREE. No `node:*`, no network, no filesystem — the
+ *             normalizer walks an already-parsed object and nothing else.
+ */
+
+// ── Caps (DDR-216 D5) ───────────────────────────────────────────────────────
+// Pre-translation HARD REFUSALS. Each fails with a clear, actionable message —
+// never an OOM, never a truncated best-effort tree. Measured baseline: a real
+// first-party page is 449 KB / 4 125 nodes / depth 13 in the metadata-only
+// projection, and the full REST payload (fills, strokes, effects, typeStyle per
+// node) is materially larger.
+
+/** ~18× the measured real page's metadata projection. */
+export const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+/** ~5× the measured 4 125. */
+export const MAX_NODE_COUNT = 20_000;
+/** ~5× the measured 13. Also bounds every recursive walk structurally. */
+export const MAX_TREE_DEPTH = 64;
+
+/** Keys that must never be copied off an untrusted object (DDR-172 Decision 3). */
+const POLLUTING_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+// ── Node vocabulary ─────────────────────────────────────────────────────────
+
+/**
+ * The node types both doors can produce. Sourced from the `.fig` container's
+ * own embedded schema (`NodeType`, read out of the committed fixtures), so the
+ * Phase-6 decoder has nothing to guess and this union needs no widening later.
+ */
+export type FigmaNodeType =
+  | 'DOCUMENT'
+  | 'CANVAS'
+  | 'FRAME'
+  | 'GROUP'
+  | 'SECTION'
+  | 'COMPONENT'
+  | 'COMPONENT_SET'
+  | 'INSTANCE'
+  | 'VECTOR'
+  | 'BOOLEAN_OPERATION'
+  | 'STAR'
+  | 'LINE'
+  | 'ELLIPSE'
+  | 'RECTANGLE'
+  | 'ROUNDED_RECTANGLE'
+  | 'REGULAR_POLYGON'
+  | 'TEXT'
+  | 'SLICE'
+  | 'STICKY'
+  | 'SHAPE_WITH_TEXT'
+  | 'CONNECTOR'
+  | 'CODE_BLOCK'
+  | 'WIDGET'
+  | 'STAMP'
+  | 'TABLE'
+  | 'MEDIA'
+  | 'EMBED'
+  | 'LINK_UNFURL'
+  | 'WASHI_TAPE'
+  | 'UNKNOWN';
+
+/**
+ * Exported so the `.fig` door can tell a vocabulary gap from a mapped type
+ * WITHOUT keeping a second copy of the list (DDR-221 D3 degrade-and-report).
+ * `nodeType()` below still owns the mapping; this is read-only.
+ */
+export const KNOWN_NODE_TYPES: ReadonlySet<string> = new Set<string>([
+  'DOCUMENT',
+  'CANVAS',
+  'FRAME',
+  'GROUP',
+  'SECTION',
+  'COMPONENT',
+  'COMPONENT_SET',
+  'INSTANCE',
+  'VECTOR',
+  'BOOLEAN_OPERATION',
+  'STAR',
+  'LINE',
+  'ELLIPSE',
+  'RECTANGLE',
+  'ROUNDED_RECTANGLE',
+  'REGULAR_POLYGON',
+  'TEXT',
+  'SLICE',
+  'STICKY',
+  'SHAPE_WITH_TEXT',
+  'CONNECTOR',
+  'CODE_BLOCK',
+  'WIDGET',
+  'STAMP',
+  'TABLE',
+  'MEDIA',
+  'EMBED',
+  'LINK_UNFURL',
+  'WASHI_TAPE',
+]);
+
+export interface FigmaRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface FigmaColor {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+export interface FigmaPaint {
+  type: string; // SOLID | GRADIENT_LINEAR | IMAGE | …
+  visible: boolean;
+  opacity?: number;
+  color?: FigmaColor;
+  /** Present on IMAGE paints — the handle `/v1/images` resolves. */
+  imageRef?: string;
+  gradientStops?: Array<{ position: number; color: FigmaColor }>;
+  gradientHandlePositions?: Array<{ x: number; y: number }>;
+}
+
+export interface FigmaEffect {
+  type: string; // DROP_SHADOW | INNER_SHADOW | LAYER_BLUR | BACKGROUND_BLUR
+  visible: boolean;
+  color?: FigmaColor;
+  offset?: { x: number; y: number };
+  radius?: number;
+  spread?: number;
+}
+
+/** Figma's `style` block on a TEXT node. */
+export interface FigmaTypeStyle {
+  fontFamily?: string; // UNTRUSTED
+  fontPostScriptName?: string; // UNTRUSTED
+  fontWeight?: number;
+  fontSize?: number;
+  lineHeightPx?: number;
+  letterSpacing?: number;
+  textAlignHorizontal?: string;
+  textAlignVertical?: string;
+  textCase?: string;
+  textDecoration?: string;
+}
+
+/**
+ * One normalized node. Optional everywhere by design: both doors see partial
+ * documents (a `getFileNodes` projection carries less than `getFile`), and a
+ * translator that copes with an absent field copes with both doors.
+ */
+export interface FigmaNode {
+  /** `^[0-9]+:[0-9]+$` in practice — the ONLY string safe to derive an identifier from. */
+  id: string;
+  type: FigmaNodeType;
+  /** UNTRUSTED — a TEXT node's layer name defaults to its own content. */
+  name: string;
+  /** False ⇒ the node is not emitted at all (DDR-216 D6b). */
+  visible: boolean;
+  absoluteBoundingBox?: FigmaRect;
+  /**
+   * What is actually DRAWN — geometry plus stroke weight, arrowheads and
+   * effects. Differs from `absoluteBoundingBox` by more than a rounding error
+   * on stroked paths: a horizontal arrow's geometric box has height 0.0001
+   * while its render bounds are 22.09. Placing such a node at its geometric
+   * box renders it into nothing, which is how nine flow arrows imported
+   * "successfully" and were invisible.
+   */
+  absoluteRenderBounds?: FigmaRect;
+  rotation?: number;
+  opacity?: number;
+  blendMode?: string;
+  clipsContent?: boolean;
+
+  // ── design-side layout ──
+  layoutMode?: 'HORIZONTAL' | 'VERTICAL' | 'NONE';
+  itemSpacing?: number;
+  paddingLeft?: number;
+  paddingRight?: number;
+  paddingTop?: number;
+  paddingBottom?: number;
+  primaryAxisAlignItems?: string;
+  counterAxisAlignItems?: string;
+  layoutWrap?: string;
+
+  // ── paint ──
+  fills?: FigmaPaint[];
+  strokes?: FigmaPaint[];
+  strokeWeight?: number;
+  effects?: FigmaEffect[];
+  cornerRadius?: number;
+  rectangleCornerRadii?: number[];
+
+  // ── text ──
+  /** UNTRUSTED — the literal user text. */
+  characters?: string;
+  style?: FigmaTypeStyle;
+
+  // ── FigJam ──
+  shapeType?: string;
+  /** A real node id — the shape `ArrowBind.hostId` wants (DDR-216 D9). */
+  connectorStart?: string;
+  connectorEnd?: string;
+  connectorStartCap?: string;
+  connectorEndCap?: string;
+  connectorLineType?: string;
+
+  // ── component semantics (display-only; no runtime equivalent) ──
+  componentId?: string;
+
+  children?: FigmaNode[];
+}
+
+/** What either door hands the translators. */
+export interface NormalizedDocument {
+  /** Charset-validated by `url.ts` — never free text. */
+  fileKey: string;
+  /** `design` | `board`, from the URL shape or the `.fig` prelude. */
+  surface: 'design' | 'board';
+  /** Which door produced this — recorded for the Tier-2 differential diff. */
+  origin: 'rest' | 'fig';
+  root: FigmaNode;
+  /** Post-normalization counts, so callers report rather than re-walk. */
+  nodeCount: number;
+  maxDepth: number;
+}
+
+export class FigmaCapError extends Error {
+  readonly cap: 'nodes' | 'depth' | 'bytes';
+  constructor(cap: 'nodes' | 'depth' | 'bytes', message: string) {
+    super(message);
+    this.name = 'FigmaCapError';
+    this.cap = cap;
+  }
+}
+
+// ── Normalization ───────────────────────────────────────────────────────────
+
+function str(v: unknown): string | undefined {
+  return typeof v === 'string' ? v : undefined;
+}
+
+function num(v: unknown): number | undefined {
+  return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+
+function bool(v: unknown, fallback: boolean): boolean {
+  return typeof v === 'boolean' ? v : fallback;
+}
+
+function rect(v: unknown): FigmaRect | undefined {
+  if (!v || typeof v !== 'object') return undefined;
+  const r = v as Record<string, unknown>;
+  const x = num(r.x);
+  const y = num(r.y);
+  const width = num(r.width);
+  const height = num(r.height);
+  if (x === undefined || y === undefined || width === undefined || height === undefined) {
+    return undefined;
+  }
+  return { x, y, width, height };
+}
+
+function color(v: unknown): FigmaColor | undefined {
+  if (!v || typeof v !== 'object') return undefined;
+  const c = v as Record<string, unknown>;
+  const r = num(c.r);
+  const g = num(c.g);
+  const b = num(c.b);
+  if (r === undefined || g === undefined || b === undefined) return undefined;
+  return { r, g, b, a: num(c.a) ?? 1 };
+}
+
+function paints(v: unknown): FigmaPaint[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  const out: FigmaPaint[] = [];
+  // Bounded: a node with thousands of paints is not a real node, and this walk
+  // runs once per node under MAX_NODE_COUNT.
+  for (const item of v.slice(0, 32)) {
+    if (!item || typeof item !== 'object') continue;
+    const p = item as Record<string, unknown>;
+    const type = str(p.type);
+    if (!type) continue;
+    const entry: FigmaPaint = { type, visible: bool(p.visible, true) };
+    const o = num(p.opacity);
+    if (o !== undefined) entry.opacity = o;
+    const col = color(p.color);
+    if (col) entry.color = col;
+    const ref = str(p.imageRef);
+    if (ref) entry.imageRef = ref;
+    if (Array.isArray(p.gradientStops)) {
+      const stops: Array<{ position: number; color: FigmaColor }> = [];
+      for (const s of p.gradientStops.slice(0, 32)) {
+        if (!s || typeof s !== 'object') continue;
+        const sr = s as Record<string, unknown>;
+        const pos = num(sr.position);
+        const sc = color(sr.color);
+        if (pos !== undefined && sc) stops.push({ position: pos, color: sc });
+      }
+      if (stops.length) entry.gradientStops = stops;
+    }
+    out.push(entry);
+  }
+  return out.length ? out : undefined;
+}
+
+function effects(v: unknown): FigmaEffect[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  const out: FigmaEffect[] = [];
+  for (const item of v.slice(0, 32)) {
+    if (!item || typeof item !== 'object') continue;
+    const e = item as Record<string, unknown>;
+    const type = str(e.type);
+    if (!type) continue;
+    const entry: FigmaEffect = { type, visible: bool(e.visible, true) };
+    const col = color(e.color);
+    if (col) entry.color = col;
+    const off = e.offset as Record<string, unknown> | undefined;
+    if (off && typeof off === 'object') {
+      const ox = num(off.x);
+      const oy = num(off.y);
+      if (ox !== undefined && oy !== undefined) entry.offset = { x: ox, y: oy };
+    }
+    const radius = num(e.radius);
+    if (radius !== undefined) entry.radius = radius;
+    const spread = num(e.spread);
+    if (spread !== undefined) entry.spread = spread;
+    out.push(entry);
+  }
+  return out.length ? out : undefined;
+}
+
+function typeStyle(v: unknown): FigmaTypeStyle | undefined {
+  if (!v || typeof v !== 'object') return undefined;
+  const s = v as Record<string, unknown>;
+  const out: FigmaTypeStyle = {};
+  const assignStr = (k: keyof FigmaTypeStyle, raw: unknown) => {
+    const val = str(raw);
+    if (val !== undefined) (out as Record<string, unknown>)[k] = val;
+  };
+  const assignNum = (k: keyof FigmaTypeStyle, raw: unknown) => {
+    const val = num(raw);
+    if (val !== undefined) (out as Record<string, unknown>)[k] = val;
+  };
+  assignStr('fontFamily', s.fontFamily);
+  assignStr('fontPostScriptName', s.fontPostScriptName);
+  assignNum('fontWeight', s.fontWeight);
+  assignNum('fontSize', s.fontSize);
+  assignNum('lineHeightPx', s.lineHeightPx);
+  assignNum('letterSpacing', s.letterSpacing);
+  assignStr('textAlignHorizontal', s.textAlignHorizontal);
+  assignStr('textAlignVertical', s.textAlignVertical);
+  assignStr('textCase', s.textCase);
+  assignStr('textDecoration', s.textDecoration);
+  return Object.keys(out).length ? out : undefined;
+}
+
+function nodeType(v: unknown): FigmaNodeType {
+  const t = str(v);
+  return t && KNOWN_NODE_TYPES.has(t) ? (t as FigmaNodeType) : 'UNKNOWN';
+}
+
+interface WalkState {
+  count: number;
+  maxDepth: number;
+}
+
+/**
+ * Recursively normalize one raw API node.
+ *
+ * Depth is checked BEFORE descent and the node count BEFORE each node is
+ * built, so a document engineered to be deep or wide trips a cap rather than
+ * exhausting the stack or the heap. `__proto__`/`constructor`/`prototype` keys
+ * are never read off the input — every field is pulled by explicit name, which
+ * is a stronger version of the DDR-172 Decision 3 guard: there is no generic
+ * key-copy loop here to pollute.
+ */
+function normalizeNode(raw: unknown, depth: number, state: WalkState): FigmaNode | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (depth > MAX_TREE_DEPTH) {
+    throw new FigmaCapError(
+      'depth',
+      `Figma document nests deeper than ${MAX_TREE_DEPTH} levels — import a specific frame instead`
+    );
+  }
+  const r = raw as Record<string, unknown>;
+
+  const id = str(r.id);
+  if (!id) return null; // a node with no id cannot be referenced, stamped, or bound
+
+  state.count += 1;
+  if (state.count > MAX_NODE_COUNT) {
+    throw new FigmaCapError(
+      'nodes',
+      `Figma document has more than ${MAX_NODE_COUNT} nodes — import a specific frame instead`
+    );
+  }
+  if (depth > state.maxDepth) state.maxDepth = depth;
+
+  const node: FigmaNode = {
+    id,
+    type: nodeType(r.type),
+    // UNTRUSTED, carried verbatim — see the file-level invariant.
+    name: str(r.name) ?? '',
+    visible: bool(r.visible, true),
+  };
+
+  const assign = <K extends keyof FigmaNode>(key: K, value: FigmaNode[K] | undefined) => {
+    if (value !== undefined) node[key] = value;
+  };
+
+  assign('absoluteBoundingBox', rect(r.absoluteBoundingBox));
+  assign('absoluteRenderBounds', rect(r.absoluteRenderBounds));
+  assign('rotation', num(r.rotation));
+  assign('opacity', num(r.opacity));
+  assign('blendMode', str(r.blendMode));
+  assign('clipsContent', typeof r.clipsContent === 'boolean' ? r.clipsContent : undefined);
+
+  const layoutMode = str(r.layoutMode);
+  if (layoutMode === 'HORIZONTAL' || layoutMode === 'VERTICAL' || layoutMode === 'NONE') {
+    node.layoutMode = layoutMode;
+  }
+  assign('itemSpacing', num(r.itemSpacing));
+  assign('paddingLeft', num(r.paddingLeft));
+  assign('paddingRight', num(r.paddingRight));
+  assign('paddingTop', num(r.paddingTop));
+  assign('paddingBottom', num(r.paddingBottom));
+  assign('primaryAxisAlignItems', str(r.primaryAxisAlignItems));
+  assign('counterAxisAlignItems', str(r.counterAxisAlignItems));
+  assign('layoutWrap', str(r.layoutWrap));
+
+  assign('fills', paints(r.fills));
+  assign('strokes', paints(r.strokes));
+  assign('strokeWeight', num(r.strokeWeight));
+  assign('effects', effects(r.effects));
+  assign('cornerRadius', num(r.cornerRadius));
+  if (Array.isArray(r.rectangleCornerRadii)) {
+    const radii = r.rectangleCornerRadii
+      .slice(0, 4)
+      .map((n) => num(n))
+      .filter((n): n is number => n !== undefined);
+    if (radii.length) node.rectangleCornerRadii = radii;
+  }
+
+  // UNTRUSTED, carried verbatim.
+  assign('characters', str(r.characters));
+  assign('style', typeStyle(r.style));
+
+  assign('shapeType', str(r.shapeType));
+  assign('connectorStart', connectorEndpointId(r.connectorStart));
+  assign('connectorEnd', connectorEndpointId(r.connectorEnd));
+  assign('connectorStartCap', str(r.connectorStartCap));
+  assign('connectorEndCap', str(r.connectorEndCap));
+  assign('connectorLineType', str(r.connectorLineType));
+  assign('componentId', str(r.componentId));
+
+  if (Array.isArray(r.children)) {
+    const kids: FigmaNode[] = [];
+    for (const child of r.children) {
+      const normalized = normalizeNode(child, depth + 1, state);
+      if (normalized) kids.push(normalized);
+    }
+    if (kids.length) node.children = kids;
+  }
+
+  return node;
+}
+
+/**
+ * A connector endpoint is `{ endpointNodeId, magnet }` (bound) or
+ * `{ position }` (free-floating). Only the bound form carries a host id — and
+ * a free endpoint must NOT be mistaken for one, or T5 mints a bind to nothing.
+ */
+function connectorEndpointId(v: unknown): string | undefined {
+  if (!v || typeof v !== 'object') return undefined;
+  const e = v as Record<string, unknown>;
+  return str(e.endpointNodeId);
+}
+
+/**
+ * Normalize a raw `GET /v1/files/:key` (or `/nodes`) document into the shape
+ * both doors share. Throws `FigmaCapError` on a hard refusal — callers turn
+ * that into the user-facing "import a specific frame instead" message.
+ */
+export function normalizeDocument(
+  raw: unknown,
+  meta: { fileKey: string; surface: 'design' | 'board'; origin?: 'rest' | 'fig' }
+): NormalizedDocument {
+  const state: WalkState = { count: 0, maxDepth: 0 };
+  const root = normalizeNode(raw, 0, state);
+  if (!root) throw new FigmaCapError('nodes', 'Figma document has no readable root node');
+  return {
+    fileKey: meta.fileKey,
+    surface: meta.surface,
+    origin: meta.origin ?? 'rest',
+    root,
+    nodeCount: state.count,
+    maxDepth: state.maxDepth,
+  };
+}
+
+/** Depth-first walk over a normalized tree. Iterative — no stack growth. */
+export function walkNodes(root: FigmaNode, visit: (node: FigmaNode, depth: number) => void): void {
+  const stack: Array<{ node: FigmaNode; depth: number }> = [{ node: root, depth: 0 }];
+  while (stack.length > 0) {
+    const entry = stack.pop();
+    if (!entry) break;
+    visit(entry.node, entry.depth);
+    const kids = entry.node.children;
+    if (!kids) continue;
+    for (let i = kids.length - 1; i >= 0; i--) {
+      stack.push({ node: kids[i], depth: entry.depth + 1 });
+    }
+  }
+}
+
+/** Guard used by the normalizer's own tests and by the `.fig` door later. */
+export function isPollutingKey(key: string): boolean {
+  return POLLUTING_KEYS.has(key);
+}