@1agh/maude 0.28.1 → 0.29.0

package/apps/studio/draw/morph.ts

@@ -0,0 +1,204 @@
+/**
+ * @file       draw/morph.ts — deterministic shape-morph producer for the IR
+ * @scope      apps/studio/draw/morph.ts
+ * @purpose    Turn ONE base `d` path into an animatable `d`-morph {@link Track}
+ *             of VERTEX ARRAYS — the cross-renderer interpolable form. Every
+ *             keyframe shares an identical command template + a fixed vertex
+ *             count, which is the hard constraint that lets web (SMIL/motion)
+ *             AND Lottie tween the morph without reparsing geometry per frame.
+ *
+ *             This is the engine replacement for the studyfi-v3 "Python
+ *             perturbation outside the engine" anti-pattern (DDR-094 Findings):
+ *             `morphVariants(base, { n, jitter, seed })` is PURE + deterministic
+ *             (a seeded LCG, no `Math.random`), so a morph is reproducible and
+ *             reviewable as code.
+ *
+ *             Constraint: morph paths must use ABSOLUTE, pair-coordinate
+ *             commands only (`M L C S Q T Z`). `H`/`V`/`A` and relative commands
+ *             throw — they break the "fixed vertex count" interpolability
+ *             invariant. The engine's `blobPath` (M…C…Z) already conforms.
+ *
+ *             React-free (DDR-067); depends only on `animate.ts` + the `Point`
+ *             type.
+ */
+
+import type { CubicBezierHandles, Keyframe, Track } from './animate.ts';
+import type { Point } from './primitives.ts';
+
+/** One command of a parsed morph path + how many (x,y) pairs it consumes. */
+export interface MorphCommand {
+  cmd: 'M' | 'L' | 'C' | 'S' | 'Q' | 'T' | 'Z';
+  /** Number of (x,y) vertex pairs this command consumes (`Z` = 0). */
+  nPairs: number;
+}
+
+/** A shared path template: the command skeleton every morph keyframe reuses. */
+export interface PathTemplate {
+  commands: MorphCommand[];
+  /** Total vertex count = Σ nPairs. The fixed-length morph invariant. */
+  vertexCount: number;
+}
+
+/** A parsed morph path: the reusable template + its base vertex array. */
+export interface ParsedMorph {
+  template: PathTemplate;
+  vertices: Point[];
+}
+
+const PAIRS_PER_CMD: Record<MorphCommand['cmd'], number> = {
+  M: 1,
+  L: 1,
+  C: 3,
+  S: 2,
+  Q: 2,
+  T: 1,
+  Z: 0,
+};
+
+const NUM_RE = /-?\d*\.?\d+(?:[eE][-+]?\d+)?/g;
+
+/**
+ * Parse an absolute, pair-coordinate `d` path into a {@link PathTemplate} plus
+ * its flat vertex array (vertices in document order). Throws on relative or
+ * `H`/`V`/`A` commands — they violate the fixed-vertex-count morph constraint.
+ */
+export function parseMorphPath(d: string): ParsedMorph {
+  const commands: MorphCommand[] = [];
+  const vertices: Point[] = [];
+  // Split on PATH-command letters only — NOT every letter — so the `e`/`E` of an
+  // exponent (`2e1`) stays inside its number rather than being read as a command.
+  const re = /([MLHVCSQTAZmlhvcsqtaz])([^MLHVCSQTAZmlhvcsqtaz]*)/g;
+  let m: RegExpExecArray | null = re.exec(d);
+  for (; m !== null; m = re.exec(d)) {
+    const letter = m[1];
+    if (letter === 'z' || letter === 'Z') {
+      commands.push({ cmd: 'Z', nPairs: 0 });
+      continue;
+    }
+    if (!(letter in PAIRS_PER_CMD)) {
+      throw new Error(
+        `parseMorphPath: command "${letter}" is not morph-safe — use only ` +
+          'absolute pair-coordinate commands (M L C S Q T Z); the blobPath form conforms'
+      );
+    }
+    const cmd = letter as MorphCommand['cmd'];
+    const nPairs = PAIRS_PER_CMD[cmd];
+    const nums = (m[2].match(NUM_RE) ?? []).map(Number);
+    if (nums.length !== nPairs * 2) {
+      throw new Error(
+        `parseMorphPath: command "${cmd}" expected ${nPairs * 2} numbers, got ${nums.length} ` +
+          '(repeated/implicit commands are not supported — emit one explicit command per segment)'
+      );
+    }
+    commands.push({ cmd, nPairs });
+    for (let i = 0; i < nums.length; i += 2) vertices.push({ x: nums[i], y: nums[i + 1] });
+  }
+  return { template: { commands, vertexCount: vertices.length }, vertices };
+}
+
+/** Format a number the way the rest of the engine does (no float noise). */
+function fmt(n: number): string {
+  return Number.isInteger(n) ? String(n) : String(Math.round(n * 1e4) / 1e4);
+}
+
+/**
+ * Reassemble a `d` string from a template + a vertex array (the inverse of
+ * {@link parseMorphPath}). Throws if the vertex count doesn't match the
+ * template — the morph invariant, checked at the seam.
+ */
+export function templateToPath(template: PathTemplate, vertices: Point[]): string {
+  if (vertices.length !== template.vertexCount) {
+    throw new Error(
+      `templateToPath: vertex count ${vertices.length} ≠ template ${template.vertexCount}`
+    );
+  }
+  const parts: string[] = [];
+  let vi = 0;
+  for (const c of template.commands) {
+    if (c.cmd === 'Z') {
+      parts.push('Z');
+      continue;
+    }
+    const coords: string[] = [];
+    for (let p = 0; p < c.nPairs; p++) {
+      const v = vertices[vi++];
+      coords.push(`${fmt(v.x)} ${fmt(v.y)}`);
+    }
+    parts.push(`${c.cmd}${coords.join(' ')}`);
+  }
+  return parts.join('');
+}
+
+/** Deterministic LCG in [0,1) — same generator the geometry layer uses. */
+function lcg(seed: number): () => number {
+  let s = seed >>> 0 || 1;
+  return () => {
+    s = (s * 1664525 + 1013904223) >>> 0;
+    return s / 4294967296;
+  };
+}
+
+export interface MorphVariantsOpts {
+  /** Number of distinct jittered variants between the base endpoints (default 3). */
+  n?: number;
+  /** Max per-vertex displacement in user units (default 2). 0 ⇒ no motion. */
+  jitter?: number;
+  /** Integer seed for the deterministic jitter (default 1). */
+  seed?: number;
+  /** Total morph duration in seconds (default 1). */
+  dur?: number;
+  /** Per-segment easing (default linear). */
+  ease?: CubicBezierHandles;
+  /** Node id this track drives. */
+  target?: string;
+  /**
+   * Close the loop by returning to the base shape on the final keyframe
+   * (default true) — a seamless `repeat` morph.
+   */
+  loop?: boolean;
+}
+
+/** The morph producer's output: the IR track + the template to render it. */
+export interface MorphResult {
+  track: Track<Point[]>;
+  template: PathTemplate;
+  /** Render any keyframe's vertex array back to a `d` string. */
+  toPath: (vertices: Point[]) => string;
+}
+
+/**
+ * Produce a deterministic `d`-morph track from a base path. Every keyframe is a
+ * vertex array of the SAME length (the base's), jittered by a seeded LCG, evenly
+ * spaced over `dur`. With `loop` (default) the last keyframe is the base again,
+ * so a repeating timeline morphs seamlessly. Pure + reproducible — the engine
+ * replacement for ad-hoc out-of-engine perturbation.
+ */
+export function morphVariants(basePath: string, opts: MorphVariantsOpts = {}): MorphResult {
+  const n = Math.max(1, opts.n ?? 3);
+  const jitter = opts.jitter ?? 2;
+  const dur = opts.dur ?? 1;
+  const loop = opts.loop ?? true;
+  const { template, vertices: base } = parseMorphPath(basePath);
+  const rnd = lcg(opts.seed ?? 1);
+
+  // Keyframe times: base at 0, n jittered variants, optional base again at dur.
+  const stops = loop ? n + 2 : n + 1; // includes the base endpoint(s)
+  const keyframes: Keyframe<Point[]>[] = [];
+  for (let k = 0; k < stops; k++) {
+    const t = (k / (stops - 1)) * dur;
+    const isBase = k === 0 || (loop && k === stops - 1);
+    const value: Point[] = isBase
+      ? base.map((p) => ({ ...p }))
+      : base.map((p) => ({
+          x: p.x + (rnd() * 2 - 1) * jitter,
+          y: p.y + (rnd() * 2 - 1) * jitter,
+        }));
+    const kf: Keyframe<Point[]> = { t, value };
+    if (opts.ease && k < stops - 1) kf.ease = opts.ease;
+    keyframes.push(kf);
+  }
+
+  const track: Track<Point[]> = { property: 'd', keyframes };
+  if (opts.target !== undefined) track.target = opts.target;
+  return { track, template, toPath: (v) => templateToPath(template, v) };
+}

package/{plugins/design/dev-server → apps/studio}/draw/optimize.ts

@@ -1,6 +1,6 @@
 /**
  * @file       draw/optimize.ts — Phase 25 geometry-engine SVGO wrapper
- * @scope      plugins/design/dev-server/draw/optimize.ts
+ * @scope      apps/studio/draw/optimize.ts
  * @purpose    The single external dependency (SVGO — DDR-071). Two jobs:
  *               1. Minify the final on-disk SVG asset (multipass, 2-decimal
  *                  precision) without stripping the a11y/scaling contract.

package/{plugins/design/dev-server → apps/studio}/draw/palette.ts

@@ -1,6 +1,6 @@
 /**
  * @file       draw/palette.ts — Phase 25 geometry-engine color layer
- * @scope      plugins/design/dev-server/draw/palette.ts
+ * @scope      apps/studio/draw/palette.ts
  * @purpose    Color correctness the draw-agent verifies from SOURCE, never from
  *             the vision model (VLMs misread color confidently):
  *               • WCAG 2.1 relative-luminance + contrast ratio (4.5 / 3 / 7);

package/{plugins/design/dev-server → apps/studio}/draw/primitives.ts

@@ -1,6 +1,6 @@
 /**
  * @file       draw/primitives.ts — Phase 25 geometry-engine primitive layer
- * @scope      plugins/design/dev-server/draw/primitives.ts
+ * @scope      apps/studio/draw/primitives.ts
  * @purpose    The `DrawPrimitive` union + grid-snapped constructors + transform
  *             composition + viewBox presets. This is the "intent" layer the
  *             draw-agent emits: the LLM names shapes and where they go; the

package/apps/studio/draw/serialize-animate.ts

@@ -0,0 +1,324 @@
+/**
+ * @file       draw/serialize-animate.ts — IR Timeline → animated SVG/JSX
+ * @scope      apps/studio/draw/serialize-animate.ts
+ * @purpose    Time-generalize the DDR-067 single-source invariant: ONE node tree
+ *             + ONE {@link Timeline} emits BOTH an animated SVG (on-disk `.svg`
+ *             form) AND an animated JSX string (inline canvas-preview form). Both
+ *             render the SAME tree — `primitivesToNodes` from `serialize.ts` with
+ *             SMIL animation children injected onto each track's target — so the
+ *             two forms can never structurally drift (the test asserts this).
+ *
+ *             Mechanism (per the DDR-094 conversion rules + `_draw-motion-rules`):
+ *               • `d` shape morph → `<animate attributeName="d" calcMode="spline">`
+ *                 (NEVER CSS `d:path()`, which doesn't animate live).
+ *               • opacity / fill / stroke → `<animate>`.
+ *               • translate / scale / rotate → `<animateTransform additive="sum">`
+ *                 — the position-vs-animation split: animated transforms compose
+ *                 with (never clobber) a static `transform=` attribute.
+ *               • Per-segment easing → `keySplines` + `calcMode="spline"`, taken
+ *                 verbatim from the IR `cubic-bezier` handles (overshoot survives).
+ *
+ *             Reduced motion: emitted as a `<style>` `prefers-reduced-motion`
+ *             gate for the SVG form (CSS-driven host). SMIL itself ignores the
+ *             CSS catch-all (a re-discovered gotcha — DDR-094 background); the
+ *             durable RM story is the host wrapper (`useReducedMotion`) for JSX
+ *             and the Lottie host for production. Documented in `_draw-motion-rules.md`.
+ *
+ *             Production delivery is Lottie (DDR-094) — this is the maude
+ *             authoring/preview form. React-free (DDR-067): JSX is a STRING.
+ */
+
+import type { CubicBezierHandles, Repeat, Timeline, Track, TrackValue } from './animate.ts';
+import { resolveStagger } from './animate.ts';
+import type { DrawPrimitive, Point } from './primitives.ts';
+import {
+  type Dialect,
+  primitivesToNodes,
+  renderNode,
+  type SerializeOpts,
+  type SvgNode,
+} from './serialize.ts';
+
+/** Per-target renderer for a `d`-morph track's vertex arrays → a path string. */
+export type PathRenderer = (vertices: Point[]) => string;
+
+export interface AnimateOpts extends SerializeOpts {
+  /**
+   * Per-target path renderers for `d`-morph tracks (a {@link Track} on `d`
+   * carries vertex arrays; rendering them to `d` strings needs the shared
+   * command template). Wire `{ [targetId]: morphResult.toPath }`. A `d` track
+   * whose target has no renderer throws.
+   */
+  pathRenderers?: Record<string, PathRenderer>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Animation plan — the dialect-neutral intermediate both forms share
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Properties driven through `<animateTransform>` rather than `<animate>`. */
+const TRANSFORM_TYPES: Record<string, 'translate' | 'scale' | 'rotate'> = {
+  translate: 'translate',
+  scale: 'scale',
+  rotate: 'rotate',
+};
+
+/** Logical property → SMIL `attributeName` (transforms handled separately). */
+const ATTR_NAME: Record<string, string> = {
+  d: 'd',
+  opacity: 'opacity',
+  fillOpacity: 'fill-opacity',
+  strokeOpacity: 'stroke-opacity',
+  fill: 'fill',
+  stroke: 'stroke',
+};
+
+/** One resolved, normalized animation (a single SMIL element's worth). */
+export interface AnimEntry {
+  target: string;
+  property: string;
+  /** SMIL element to emit. */
+  kind: 'animate' | 'animateTransform';
+  /** `attributeName` (animate) or transform `type` (animateTransform). */
+  attr: string;
+  /** Serialized keyframe values (`;`-joined at render). */
+  values: string[];
+  /** Normalized 0–1 keyframe times (first 0, last 1). */
+  keyTimes: number[];
+  /** `n-1` `"x1 y1 x2 y2"` splines when any segment eases; else undefined. */
+  keySplines?: string[];
+  /** Animation window start (seconds). */
+  begin: number;
+  /** Animation window duration (seconds). */
+  dur: number;
+  repeat: Repeat;
+}
+
+function num(n: number): string {
+  return Number.isInteger(n) ? String(n) : String(Math.round(n * 1e4) / 1e4);
+}
+
+function serializeValue(
+  property: string,
+  v: TrackValue,
+  pathRenderers: Record<string, PathRenderer>,
+  target: string
+): string {
+  if (property === 'd') {
+    const r = pathRenderers[target];
+    if (!r) {
+      throw new Error(
+        `serialize-animate: d-morph track on "${target}" needs a pathRenderer ` +
+          '(pass { pathRenderers: { [target]: morphResult.toPath } })'
+      );
+    }
+    return r(v as Point[]);
+  }
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number') return num(v);
+  if (Array.isArray(v)) {
+    // number[] (transform components / stops). Point[] only valid for `d` (above).
+    return (v as number[]).map(num).join(' ');
+  }
+  throw new Error(`serialize-animate: unserializable value for "${property}"`);
+}
+
+function splineStr(h: CubicBezierHandles): string {
+  return h.map(num).join(' ');
+}
+
+/** Resolve one track into an {@link AnimEntry} (normalize times, splines). */
+function planTrack(
+  tr: Track,
+  pathRenderers: Record<string, PathRenderer>,
+  repeat: Repeat
+): AnimEntry | null {
+  const target = tr.target;
+  if (!target) return null; // untargeted tracks can't be serialized
+  const kfs = tr.keyframes;
+  if (kfs.length < 2) return null;
+
+  const begin = kfs[0].t;
+  const dur = kfs[kfs.length - 1].t - begin;
+  if (dur <= 0) return null;
+
+  const keyTimes = kfs.map((k) => Math.min(1, Math.max(0, (k.t - begin) / dur)));
+  const values = kfs.map((k) => serializeValue(tr.property, k.value, pathRenderers, target));
+
+  // keySplines: one per interval. Present only if at least one segment eases.
+  const hasEase = kfs.slice(0, -1).some((k) => k.ease);
+  let keySplines: string[] | undefined;
+  if (hasEase) {
+    keySplines = kfs.slice(0, -1).map((k) => splineStr(k.ease ?? [0, 0, 1, 1]));
+  }
+
+  const transformType = TRANSFORM_TYPES[tr.property];
+  const entry: AnimEntry = transformType
+    ? {
+        target,
+        property: tr.property,
+        kind: 'animateTransform',
+        attr: transformType,
+        values,
+        keyTimes,
+        begin,
+        dur,
+        repeat,
+      }
+    : {
+        target,
+        property: tr.property,
+        kind: 'animate',
+        attr: ATTR_NAME[tr.property] ?? tr.property,
+        values,
+        keyTimes,
+        begin,
+        dur,
+        repeat,
+      };
+  if (keySplines) entry.keySplines = keySplines;
+  return entry;
+}
+
+/**
+ * Build the dialect-neutral animation plan from a timeline. Resolves `stagger`,
+ * normalizes each track to its own [0,1] window, and maps property → SMIL kind.
+ * Both serializers consume this — it IS the single source the parity test checks.
+ */
+export function buildAnimPlan(
+  timeline: Timeline,
+  opts: { pathRenderers?: Record<string, PathRenderer> } = {}
+): AnimEntry[] {
+  const tl = resolveStagger(timeline);
+  const repeat: Repeat = tl.repeat ?? 'indefinite';
+  const renderers = opts.pathRenderers ?? {};
+  const out: AnimEntry[] = [];
+  for (const tr of tl.tracks) {
+    const e = planTrack(tr, renderers, repeat);
+    if (e) out.push(e);
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SMIL node injection
+// ─────────────────────────────────────────────────────────────────────────────
+
+function repeatCount(r: Repeat): string {
+  return r === 'indefinite' ? 'indefinite' : String(r);
+}
+
+/** An {@link AnimEntry} → a leaf {@link SvgNode} (`<animate>`/`<animateTransform>`). */
+function entryToNode(e: AnimEntry): SvgNode {
+  const attrs: Array<[string, string]> = [];
+  if (e.kind === 'animateTransform') {
+    attrs.push(['attributeName', 'transform']);
+    attrs.push(['type', e.attr]);
+    attrs.push(['additive', 'sum']); // compose, never clobber a static transform=
+  } else {
+    attrs.push(['attributeName', e.attr]);
+  }
+  attrs.push(['values', e.values.join(';')]);
+  attrs.push(['keyTimes', e.keyTimes.map(num).join(';')]);
+  if (e.keySplines) {
+    attrs.push(['calcMode', 'spline']);
+    attrs.push(['keySplines', e.keySplines.join(';')]);
+  }
+  if (e.begin > 0) attrs.push(['begin', `${num(e.begin)}s`]);
+  attrs.push(['dur', `${num(e.dur)}s`]);
+  attrs.push(['repeatCount', repeatCount(e.repeat)]);
+  if (e.repeat !== 'indefinite') attrs.push(['fill', 'freeze']);
+  return { tag: e.kind, attrs, children: [] };
+}
+
+/** Find a node by `id` (depth-first) and append animation children to it. */
+function injectAnimations(
+  root: SvgNode,
+  plan: AnimEntry[]
+): { injected: number; missing: string[] } {
+  const byTarget = new Map<string, AnimEntry[]>();
+  for (const e of plan) {
+    const list = byTarget.get(e.target) ?? [];
+    list.push(e);
+    byTarget.set(e.target, list);
+  }
+  const found = new Set<string>();
+
+  const walk = (node: SvgNode): void => {
+    const id = node.attrs.find(([k]) => k === 'id')?.[1];
+    if (id && byTarget.has(id)) {
+      for (const e of byTarget.get(id) as AnimEntry[]) node.children.push(entryToNode(e));
+      found.add(id);
+    }
+    for (const c of node.children) walk(c);
+  };
+  walk(root);
+
+  const missing = [...byTarget.keys()].filter((t) => !found.has(t));
+  return { injected: found.size, missing };
+}
+
+/** Reduced-motion `<style>` (CSS-host best-effort; SMIL caveat documented). */
+function reducedMotionStyle(): SvgNode {
+  const css =
+    '@media (prefers-reduced-motion: reduce){' +
+    '*{animation-duration:.001ms!important;animation-iteration-count:1!important;' +
+    'transition-duration:.001ms!important}}';
+  return { tag: 'style', attrs: [], children: [], text: css };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public serializers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function buildAnimatedTree(
+  primitives: DrawPrimitive[],
+  timeline: Timeline,
+  opts: AnimateOpts,
+  dialect: Dialect
+): { tree: SvgNode; missing: string[] } {
+  const tree = primitivesToNodes(primitives, opts);
+  const plan = buildAnimPlan(timeline, opts);
+  const { missing } = injectAnimations(tree, plan);
+  // Only the SVG form gets a live <style> RM gate — a CSS `{}` block can't be a
+  // JSX text child without entity-escaping the braces; JSX hosts gate via
+  // useReducedMotion (see _draw-motion-rules.md).
+  if (dialect === 'svg') tree.children.unshift(reducedMotionStyle());
+  return { tree, missing };
+}
+
+/**
+ * Serialize primitives + a timeline to an animated SVG document string (SMIL +
+ * a `prefers-reduced-motion` `<style>` gate). Throws if a track targets an id
+ * not present in the tree (fail loud — a typo'd target silently animates nothing).
+ */
+export function toAnimatedSvg(
+  primitives: DrawPrimitive[],
+  timeline: Timeline,
+  opts: AnimateOpts
+): string {
+  const { tree, missing } = buildAnimatedTree(primitives, timeline, opts, 'svg');
+  if (missing.length) {
+    throw new Error(`toAnimatedSvg: track target(s) not found in tree: ${missing.join(', ')}`);
+  }
+  return renderNode(tree, 'svg', '');
+}
+
+/**
+ * Serialize primitives + a timeline to an animated JSX string for inline canvas
+ * embedding. Renders the SAME SMIL node tree in the JSX dialect (React renders
+ * SMIL inside an `<svg>`), so the on-disk and on-canvas animated forms are
+ * structurally identical. The reduced-motion gate is the host's responsibility
+ * (`useReducedMotion`) — see `_draw-motion-rules.md`.
+ */
+export function toAnimatedJsx(
+  primitives: DrawPrimitive[],
+  timeline: Timeline,
+  opts: AnimateOpts
+): string {
+  const { tree, missing } = buildAnimatedTree(primitives, timeline, opts, 'jsx');
+  if (missing.length) {
+    throw new Error(`toAnimatedJsx: track target(s) not found in tree: ${missing.join(', ')}`);
+  }
+  return renderNode(tree, 'jsx', '');
+}

package/{plugins/design/dev-server → apps/studio}/draw/serialize.ts

@@ -1,6 +1,6 @@
 /**
  * @file       draw/serialize.ts — Phase 25 geometry-engine serializer
- * @scope      plugins/design/dev-server/draw/serialize.ts
+ * @scope      apps/studio/draw/serialize.ts
  * @purpose    The dual serializer: ONE `DrawPrimitive[]` produces BOTH an
  *             optimized SVG string (`toSvg`) for on-disk assets AND a JSX string
  *             (`toJsx`) for inline canvas embedding. Both render the SAME
@@ -379,7 +379,7 @@ export function primitivesToNodes(primitives: DrawPrimitive[], opts: SerializeOp
 // Rendering
 // ─────────────────────────────────────────────────────────────────────────────
 
-type Dialect = 'svg' | 'jsx';
+export type Dialect = 'svg' | 'jsx';
 
 function attrName(key: string, dialect: Dialect): string {
   const mapped = ATTR_DIALECT[key];
@@ -397,7 +397,13 @@ function escapeAttr(s: string): string {
   return s.replace(/&/g, '&').replace(/"/g, '"');
 }
 
-function renderNode(node: SvgNode, dialect: Dialect, indent: string): string {
+/**
+ * Render one {@link SvgNode} tree to a dialect string. Exported so the animation
+ * serializer (`serialize-animate.ts`) can render the SAME node tree after it
+ * injects SMIL animation children — preserving the DDR-067 single-source
+ * invariant for animated marks.
+ */
+export function renderNode(node: SvgNode, dialect: Dialect, indent: string): string {
   const pad = indent;
   const attrParts: string[] = [];