@1agh/maude 0.28.1 → 0.30.0

package/apps/studio/dom-selection.ts

@@ -0,0 +1,342 @@
+/**
+ * @file       dom-selection.ts — selection-from-DOM helpers (leaf module)
+ * @scope      apps/studio/dom-selection.ts
+ * @purpose    Pure DOM → Selection builders shared by the canvas chrome
+ *             (canvas-shell.tsx) and the shell-owned comment mount layer
+ *             (canvas-comment-mount.tsx). Lives in its own leaf module — no
+ *             React, no canvas-lib import — so both consumers can lift the
+ *             same `hoverTargetToSelection` / `deriveFile` logic without a
+ *             cycle and without bundling the heavy DesignCanvas tree into the
+ *             lite comment mount.
+ */
+
+import type { HoverTarget } from './input-router.tsx';
+import type { Selection } from './use-selection-set.tsx';
+
+/**
+ * Canvas file path for the current page. Under the mount harness the page is
+ * `/_canvas-shell.html?canvas=<rel>&designRel=<root>`; for legacy `.html`
+ * mocks it's the served file path itself.
+ */
+export function deriveFile(): string | undefined {
+  if (typeof window === 'undefined') return undefined;
+  try {
+    const p = window.location.pathname;
+    if (p === '/_canvas-shell.html' || p === '/_canvas-shell') {
+      const qs = new URLSearchParams(window.location.search);
+      const canvas = qs.get('canvas') ?? '';
+      const designRel = (qs.get('designRel') ?? '.design').replace(/^\/+|\/+$/g, '');
+      return canvas ? `${designRel}/${canvas}` : undefined;
+    }
+    return decodeURIComponent(p).replace(/^\//, '');
+  } catch {
+    return undefined;
+  }
+}
+
+export function realClasses(el: Element | null): string {
+  if (!el) return '';
+  return (el.getAttribute('class') ?? '')
+    .trim()
+    .split(/\s+/)
+    .filter((c) => c && !c.startsWith('dgn-') && !c.startsWith('dc-cv-'))
+    .join(' ');
+}
+
+export function shortText(el: Element | null, max: number): string {
+  if (!el) return '';
+  const t = ((el as HTMLElement).innerText || el.textContent || '').replace(/\s+/g, ' ').trim();
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+
+export function cssPath(el: Element | null): string {
+  if (!el) return '';
+  const path: string[] = [];
+  let cur: Element | null = el;
+  while (cur && cur.nodeType === 1 && path.length < 8) {
+    const dscEl = cur.getAttribute?.('data-dc-element');
+    if (dscEl) {
+      path.unshift(`[data-dc-element="${dscEl}"]`);
+      break;
+    }
+    const dscSc = cur.getAttribute?.('data-dc-screen');
+    if (dscSc) {
+      path.unshift(`[data-dc-screen="${dscSc}"]`);
+      break;
+    }
+    let sel = cur.nodeName.toLowerCase();
+    if (cur.id) {
+      sel = `#${cur.id}`;
+      path.unshift(sel);
+      break;
+    }
+    const cls = realClasses(cur).split(/\s+/).filter(Boolean).slice(0, 2);
+    if (cls.length) sel += `.${cls.join('.')}`;
+    let sib = 1;
+    let n: Element | null = cur.previousElementSibling;
+    while (n) {
+      sib++;
+      n = n.previousElementSibling;
+    }
+    sel += `:nth-child(${sib})`;
+    path.unshift(sel);
+    cur = cur.parentElement;
+  }
+  return path.join(' > ');
+}
+
+export function domPath(el: Element | null): string[] {
+  const hops: string[] = [];
+  let cur = el;
+  while (cur && cur.nodeType === 1 && hops.length < 8) {
+    let label = cur.nodeName.toLowerCase();
+    const dEl = cur.getAttribute?.('data-dc-element');
+    const dSc = cur.getAttribute?.('data-dc-screen');
+    if (dEl) label += `[data-dc-element="${dEl}"]`;
+    else if (dSc) label += `[data-dc-screen="${dSc}"]`;
+    else if (cur.id) label += `#${cur.id}`;
+    const cls = realClasses(cur).split(/\s+/).filter(Boolean).slice(0, 2);
+    if (cls.length && !dEl && !dSc) label += `.${cls.join('.')}`;
+    hops.unshift(label);
+    cur = cur.parentElement;
+  }
+  return hops;
+}
+
+export function cssEscape(s: string): string {
+  // Minimal CSS.escape polyfill — only handles chars actually present in
+  // pipeline-stamped IDs (alphanumerics + `-` + `_`).
+  return s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`);
+}
+
+/**
+ * Build the wire-shape `Selection` for a resolved hover target. `file`
+ * defaults to `deriveFile()`; the comment mount layer passes it explicitly
+ * so all three consumers (router, overlay, mount) agree on the same key.
+ */
+/**
+ * The artboard-scoped data-cd-id selector. A component shared across artboards
+ * carries the SAME data-cd-id in each, so a bare `[data-cd-id="…"]` resolves
+ * (via querySelector) to the FIRST artboard. Prefixing the hit's artboard makes
+ * the anchor per-instance. Shared by EVERY selector builder + resolver so they
+ * can't drift (the original fix only patched one of ~8 sites).
+ */
+export function scopedCdSelector(cdId: string, artboardId?: string | null): string {
+  return artboardId
+    ? `[data-dc-screen="${artboardId}"] [data-cd-id="${cdId}"]`
+    : `[data-cd-id="${cdId}"]`;
+}
+
+/**
+ * Occurrence index of `el` among `doc.querySelectorAll(selector)`. Even with an
+ * artboard-scoped data-cd-id selector, a component repeated WITHIN one artboard
+ * (a list row, or a reusable used twice) produces several matches — the index
+ * is the only thing that makes the anchor truly unique per DOM instance.
+ */
+export function selectorIndex(doc: Document, selector: string, el: Element | null): number {
+  if (!el) return 0;
+  try {
+    const all = doc.querySelectorAll(selector);
+    for (let i = 0; i < all.length; i++) {
+      if (all[i] === el) return i;
+    }
+  } catch {
+    /* malformed selector */
+  }
+  return 0;
+}
+
+/**
+ * Resolve a stored Selection to its live element, artboard-scoped. Prefers the
+ * id+artboardId scoped selector (the robust path), then the stored `selector`
+ * (already scoped for recent selections; a legacy fallback for old comments).
+ * Every halo / pin / toolbar / spacing-handle resolver routes through this so a
+ * shared component anchors to the instance the user actually clicked.
+ */
+export function resolveSelectionEl(
+  doc: Document,
+  sel: { id?: string | null; selector?: string | null; artboardId?: string | null; index?: number }
+): Element | null {
+  const at = (selector: string): Element | null => {
+    try {
+      const all = doc.querySelectorAll(selector);
+      if (!all.length) return null;
+      const i = sel.index && sel.index > 0 && sel.index < all.length ? sel.index : 0;
+      return all[i] ?? all[0];
+    } catch {
+      return null;
+    }
+  };
+  if (sel.id) {
+    const el = at(scopedCdSelector(sel.id, sel.artboardId));
+    if (el) return el;
+  }
+  if (sel.selector) return at(sel.selector);
+  return null;
+}
+
+/**
+ * Phase 12.2 — style maps for the CSS-knob properties. `authored` is what the
+ * element sets INLINE (React renders `style={{padding:8}}` → `style="padding:8px"`),
+ * so the knob pre-fills the EDITABLE source value and is blank when unset — not
+ * the noisy resolved default (`656.003px`, `rgb(0,0,0)`). `computed` is the
+ * resolved value, shown only as a faint placeholder hint. Empty for a detached
+ * node / SSR.
+ */
+// Phase 12.3 (W2.2 fix) — EVERY property the CSS panel has a control for, so each
+// reads back into `authored` (pre-fills the right control) and is excluded from
+// `customStyles`. The earlier short list omitted the box-model LONGHANDS
+// (`padding-top`, `margin-left`, …) + the Layout/border longhands, so a value the
+// panel wrote (e.g. an alt-scrub `padding-top`) fell through to customStyles and
+// the box-model widget showed it as a "custom CSS property" instead of in the box.
+const KNOB_PROPS = [
+  // Layout
+  'display',
+  'flex-direction',
+  'align-items',
+  'justify-content',
+  'gap',
+  // Typography
+  'font-family',
+  'color',
+  'font-size',
+  'font-weight',
+  'line-height',
+  'letter-spacing',
+  'text-align',
+  // Spacing — shorthand (for customStyles exclusion + whole-side authoring) AND
+  // the 8 longhands the box-model widget actually reads/writes.
+  'margin',
+  'margin-top',
+  'margin-right',
+  'margin-bottom',
+  'margin-left',
+  'padding',
+  'padding-top',
+  'padding-right',
+  'padding-bottom',
+  'padding-left',
+  // Size
+  'width',
+  'height',
+  'max-width',
+  // Appearance
+  'background-color',
+  'border-radius',
+  'border-top-left-radius',
+  'border-top-right-radius',
+  'border-bottom-left-radius',
+  'border-bottom-right-radius',
+  'border-width',
+  'border-style',
+  'border-color',
+  'box-shadow',
+  'opacity',
+] as const;
+
+// Phase 12.3 — HTML attributes the custom-attribute hatch may have written, so a
+// just-added `data-*`/`aria-*`/`role`/`title` round-trips back into a panel row.
+// Excludes the structural ones the panel manages elsewhere (style, class,
+// data-cd-id pipeline anchor, the data-dc-* canvas chrome markers).
+const ATTR_SKIP = /^(style|class|data-cd-id|data-dc-|data-dcid$)/;
+
+function styleMapsFor(el: Element | null): {
+  authored: Record<string, string>;
+  computed: Record<string, string>;
+  customStyles: Record<string, string>;
+  attrs: Record<string, string>;
+} {
+  if (!el || typeof window === 'undefined' || !window.getComputedStyle) {
+    return { authored: {}, computed: {}, customStyles: {}, attrs: {} };
+  }
+  try {
+    const inline = (el as HTMLElement).style;
+    const cs = window.getComputedStyle(el as HTMLElement);
+    const authored: Record<string, string> = {};
+    const computed: Record<string, string> = {};
+    const knob = new Set<string>(KNOB_PROPS as readonly string[]);
+    // Curated knob props: authored value (knob pre-fill) + computed (placeholder).
+    for (const p of KNOB_PROPS) {
+      const a = inline.getPropertyValue(p);
+      if (a) authored[p] = a.trim();
+      const c = cs.getPropertyValue(p);
+      if (c) computed[p] = c.trim();
+    }
+    // Every OTHER authored inline property → customStyles, so the panel can show
+    // a custom CSS property the user added that no curated row covers. EXCLUDE
+    // the panel-managed FAMILIES wholesale: setting `border`/`border-radius` (or
+    // their 3-way shorthands) makes the CSSOM expand them to the per-side
+    // longhands — `border-top-width`, `border-left-color`, … — which the panel
+    // controls but can't enumerate in the knob set. Without the family guard they
+    // leak into "custom CSS properties" (the same class of bug fixed for spacing).
+    const MANAGED_FAMILY = /^(margin|padding|border)(-|$)/;
+    const customStyles: Record<string, string> = {};
+    for (let i = 0; i < inline.length; i++) {
+      const p = inline.item(i);
+      if (!p || knob.has(p) || MANAGED_FAMILY.test(p)) continue;
+      const v = inline.getPropertyValue(p);
+      if (v) customStyles[p] = v.trim();
+    }
+    // Custom HTML attributes (the escape-hatch surface).
+    const attrs: Record<string, string> = {};
+    for (const a of Array.from((el as HTMLElement).attributes)) {
+      if (ATTR_SKIP.test(a.name)) continue;
+      attrs[a.name] = a.value;
+    }
+    return { authored, computed, customStyles, attrs };
+  } catch {
+    return { authored: {}, computed: {}, customStyles: {}, attrs: {} };
+  }
+}
+
+export function hoverTargetToSelection(target: HoverTarget, file?: string): Selection {
+  const el = target.el;
+  const rect =
+    el && (el as HTMLElement).getBoundingClientRect
+      ? (el as HTMLElement).getBoundingClientRect()
+      : null;
+  // `cdId` is the hit element's OWN data-cd-id (deep mode); resolver never
+  // climbs to an ancestor. Falls back to cssPath of the hit when no stable
+  // anchor exists.
+  const cdId = target.cdId;
+  // Selector resolution order:
+  //   1. data-cd-id anchor — stable pipeline-stamped id (preferred). SCOPED by
+  //      the hit's artboard (`[data-dc-screen=…] [data-cd-id=…]`) — a component
+  //      shared across artboards carries the SAME data-cd-id in each, so an
+  //      unscoped `[data-cd-id]` selector resolves (via querySelector) to the
+  //      FIRST artboard's instance and the pin/select lands on the wrong board.
+  //      Prefixing the artboard makes the anchor per-instance.
+  //   2. data-dc-screen — chrome click promoted to whole-artboard select
+  //      (T24.5 G8 multi-artboard gesture).
+  //   3. cssPath of the hit — last-resort path string.
+  const selector = cdId
+    ? scopedCdSelector(cdId, target.artboardId)
+    : target.artboardId
+      ? `[data-dc-screen="${target.artboardId}"]`
+      : cssPath(el);
+  // Disambiguate repeated instances within the same artboard (list rows, a
+  // reusable used twice) — the index is which `querySelectorAll(selector)`
+  // match this element is. cssPath is already unique, so 0 there.
+  const index = cdId && typeof document !== 'undefined' ? selectorIndex(document, selector, el) : 0;
+  return {
+    file: file ?? deriveFile(),
+    id: cdId ?? undefined,
+    selector,
+    artboardId: target.artboardId,
+    index,
+    tag: el?.tagName.toLowerCase() ?? '',
+    classes: realClasses(el),
+    text: shortText(el, 240),
+    dom_path: domPath(el),
+    bounds: rect
+      ? {
+          x: Math.round(rect.left),
+          y: Math.round(rect.top),
+          w: Math.round(rect.width),
+          h: Math.round(rect.height),
+        }
+      : null,
+    html: el ? (el.outerHTML ?? '').slice(0, 4000) : '',
+    ...styleMapsFor(el),
+  };
+}

package/apps/studio/draw/animate.ts

@@ -0,0 +1,333 @@
+/**
+ * @file       draw/animate.ts — draw animation IR (keyframe timeline)
+ * @scope      apps/studio/draw/animate.ts
+ * @purpose    The cross-platform ANIMATION source of truth. Where `primitives.ts`
+ *             names *shape*, this module names *time*: a keyframe `Timeline` of
+ *             property `Track`s on any node. It extends the DDR-067 single-source
+ *             invariant from static geometry to motion — one IR feeds the web
+ *             authoring serializers (SMIL + motion/JSX, `serialize.ts`) AND the
+ *             production `toLottie()` emitter (DDR-094).
+ *
+ *             Vocabulary:
+ *               Keyframe  — { t, value, ease? } at an ABSOLUTE time (seconds).
+ *               Track     — keyframes on one property of one node (`d` morph as a
+ *                           vertex array, `transform`, `opacity`, gradient stops).
+ *               Timeline  — { dur, begin?, repeat?, tracks, stagger? }.
+ *
+ *             Choreography ("animate sequences of anything, scalable") is built
+ *             from pure combinators — `sequence` (in series), `parallel` (at
+ *             once), `stagger` (offset each track by index·delay). Easing is
+ *             per-segment CSS `cubic-bezier`, evaluated with a Newton-Raphson
+ *             solver so authoring tokens (incl. overshoot, `y>1`) round-trip
+ *             exactly into SMIL `keySplines` / Lottie `i`/`o` handles.
+ *
+ *             DEPENDENCY RULE (DDR-067): React-free root. Imports only the pure
+ *             `Point` type from `primitives.ts`; nothing from react or a `.tsx`.
+ */
+
+import type { Point } from './primitives.ts';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Easing — CSS cubic-bezier(x1,y1,x2,y2) timing function
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The four control-point handles of a CSS `cubic-bezier(x1,y1,x2,y2)` easing.
+ * `x` components are clamped to [0,1] (CSS constraint); `y` may exceed [0,1]
+ * to express overshoot/anticipation (`--ease-out (0.34,1.42,…)` "snap").
+ */
+export type CubicBezierHandles = readonly [x1: number, y1: number, x2: number, y2: number];
+
+/** `linear` — the identity timing function. */
+export const LINEAR: CubicBezierHandles = [0, 0, 1, 1];
+
+/** One axis of a cubic Bézier with P0=0, P3=1: B(t) = 3(1-t)²t·c1 + 3(1-t)t²·c2 + t³. */
+function bezierAxis(t: number, c1: number, c2: number): number {
+  const mt = 1 - t;
+  return 3 * mt * mt * t * c1 + 3 * mt * t * t * c2 + t * t * t;
+}
+
+/** dB/dt for the same axis — used by the Newton-Raphson x→t solve. */
+function bezierAxisDeriv(t: number, c1: number, c2: number): number {
+  const mt = 1 - t;
+  return 3 * mt * mt * c1 + 6 * mt * t * (c2 - c1) + 3 * t * t * (1 - c2);
+}
+
+/**
+ * Evaluate a CSS cubic-bezier easing: given progress `x` ∈ [0,1] along the
+ * timeline, return the eased output `y`. Solves `bezierX(t) = x` for the curve
+ * parameter `t` (Newton-Raphson, bisection fallback), then returns `bezierY(t)`.
+ * `linear` short-circuits. Output `y` is NOT clamped — overshoot is preserved.
+ */
+export function easeBezier(handles: CubicBezierHandles, x: number): number {
+  const [x1, y1, x2, y2] = handles;
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+  // Linear fast-path (both handles on the diagonal).
+  if (x1 === y1 && x2 === y2) return x;
+
+  // Solve bezierX(t) = x for t.
+  let t = x;
+  for (let i = 0; i < 8; i++) {
+    const xe = bezierAxis(t, x1, x2) - x;
+    if (Math.abs(xe) < 1e-7) break;
+    const dx = bezierAxisDeriv(t, x1, x2);
+    if (Math.abs(dx) < 1e-7) break;
+    t -= xe / dx;
+  }
+  // Bisection fallback if Newton left the [0,1] domain or stalled.
+  if (t < 0 || t > 1 || Number.isNaN(t)) {
+    let lo = 0;
+    let hi = 1;
+    t = x;
+    for (let i = 0; i < 32; i++) {
+      t = (lo + hi) / 2;
+      const xe = bezierAxis(t, x1, x2);
+      if (Math.abs(xe - x) < 1e-7) break;
+      if (xe < x) lo = t;
+      else hi = t;
+    }
+  }
+  return bezierAxis(t, y1, y2);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// IR types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A value a track can interpolate:
+ *   • `number`     — opacity, scalar scale/rotate, a single stop offset.
+ *   • `number[]`   — element-wise (gradient stop offsets/opacities, a transform
+ *                    decomposed into [tx,ty,scale,rotate], …).
+ *   • `Point[]`    — a `d` shape morph as a vertex array (the cross-renderer
+ *                    interpolable form; see {@link lerpVertices}).
+ *   • `string`     — a discrete value (a `transform` string, a color); NOT
+ *                    numerically interpolated — held until the next keyframe.
+ */
+export type TrackValue = number | number[] | Point[] | string;
+
+/** A single keyframe at an ABSOLUTE time `t` (seconds from the track's begin). */
+export interface Keyframe<V extends TrackValue = TrackValue> {
+  /** Absolute time in seconds. */
+  t: number;
+  value: V;
+  /**
+   * Easing of the segment STARTING at this keyframe (→ the next one), mirroring
+   * SMIL `keySplines` (one spline per interval) and Lottie out/in tangents.
+   * Omit for `linear`. Ignored on the final keyframe.
+   */
+  ease?: CubicBezierHandles;
+}
+
+/** Animatable property names the serializers understand. Open for extension. */
+export type TrackProperty =
+  | 'd'
+  | 'transform'
+  | 'opacity'
+  | 'fill'
+  | 'stroke'
+  | 'gradientStops'
+  | (string & {});
+
+/** Keyframes on one property of one node. */
+export interface Track<V extends TrackValue = TrackValue> {
+  /** The animated property (`d`, `opacity`, `transform`, …). */
+  property: TrackProperty;
+  /** `id` of the node this track drives (the serializer targets it). */
+  target?: string;
+  /** Keyframes, kept sorted ascending by `t` (constructors enforce this). */
+  keyframes: Keyframe<V>[];
+}
+
+/** Repeat policy. `'indefinite'` ⇒ SMIL `indefinite` / Lottie loop. */
+export type Repeat = number | 'indefinite';
+
+/** A timeline: a bundle of property tracks sharing a clock. */
+export interface Timeline {
+  /** Total wall-clock duration in seconds (the choreography envelope). */
+  dur: number;
+  /** Start offset in seconds (default 0). */
+  begin?: number;
+  /** Repeat count or `'indefinite'`. */
+  repeat?: Repeat;
+  tracks: Track[];
+  /**
+   * If set, each track's keyframes are offset by `index · stagger` seconds at
+   * resolve time (see {@link resolveStagger}). A declarative shorthand for
+   * {@link stagger}; resolved (baked into keyframe `t`) before serialization.
+   */
+  stagger?: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constructors
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Build a track, sorting keyframes by time (defensive — callers may be loose). */
+export function track<V extends TrackValue>(
+  property: TrackProperty,
+  keyframes: Keyframe<V>[],
+  target?: string
+): Track<V> {
+  const sorted = [...keyframes].sort((a, b) => a.t - b.t);
+  const out: Track<V> = { property, keyframes: sorted };
+  if (target !== undefined) out.target = target;
+  return out;
+}
+
+/** Build a timeline; `dur` defaults to the latest keyframe time across tracks. */
+export function timeline(o: {
+  tracks: Track[];
+  dur?: number;
+  begin?: number;
+  repeat?: Repeat;
+  stagger?: number;
+}): Timeline {
+  const dur = o.dur ?? trackSpan(o.tracks);
+  const out: Timeline = { dur, tracks: o.tracks };
+  if (o.begin !== undefined) out.begin = o.begin;
+  if (o.repeat !== undefined) out.repeat = o.repeat;
+  if (o.stagger !== undefined) out.stagger = o.stagger;
+  return out;
+}
+
+/** The latest keyframe time across a set of tracks (0 if none). */
+export function trackSpan(tracks: Track[]): number {
+  let max = 0;
+  for (const tr of tracks) {
+    const last = tr.keyframes[tr.keyframes.length - 1];
+    if (last && last.t > max) max = last.t;
+  }
+  return max;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Interpolation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Vertex-array interpolation for `d` morphs. REQUIRES equal length — the
+ * cross-renderer interpolability constraint (an identical command template /
+ * fixed vertex count). Throws on mismatch so a bad morph fails loud at author
+ * time rather than producing a degenerate tween.
+ */
+export function lerpVertices(a: Point[], b: Point[], u: number): Point[] {
+  if (a.length !== b.length) {
+    throw new Error(
+      `lerpVertices: vertex count mismatch (${a.length} vs ${b.length}); ` +
+        'morph endpoints must share a fixed vertex count'
+    );
+  }
+  return a.map((p, i) => ({ x: p.x + (b[i].x - p.x) * u, y: p.y + (b[i].y - p.y) * u }));
+}
+
+/** Interpolate two same-shaped {@link TrackValue}s by `u` ∈ [0,1]. */
+export function lerpValue(a: TrackValue, b: TrackValue, u: number): TrackValue {
+  if (typeof a === 'number' && typeof b === 'number') return a + (b - a) * u;
+  if (typeof a === 'string' || typeof b === 'string') return u < 1 ? a : b; // discrete hold
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) {
+      throw new Error(`lerpValue: array length mismatch (${a.length} vs ${b.length})`);
+    }
+    if (a.length === 0) return [];
+    // Point[] (vertex array) vs number[].
+    if (typeof a[0] === 'object') return lerpVertices(a as Point[], b as Point[], u);
+    return (a as number[]).map((n, i) => n + ((b as number[])[i] - n) * u);
+  }
+  throw new Error('lerpValue: incompatible value kinds');
+}
+
+/**
+ * Sample a track at absolute time `tSec`. Clamps outside the keyframe span
+ * (hold first / hold last). Applies the per-segment easing of the leading
+ * keyframe, then interpolates. Returns `undefined` for an empty track.
+ */
+export function sampleTrack(tr: Track, tSec: number): TrackValue | undefined {
+  const kfs = tr.keyframes;
+  if (kfs.length === 0) return undefined;
+  if (kfs.length === 1 || tSec <= kfs[0].t) return kfs[0].value;
+  const last = kfs[kfs.length - 1];
+  if (tSec >= last.t) return last.value;
+
+  let i = 0;
+  while (i < kfs.length - 1 && kfs[i + 1].t <= tSec) i++;
+  const a = kfs[i];
+  const b = kfs[i + 1];
+  const span = b.t - a.t;
+  const x = span > 0 ? (tSec - a.t) / span : 0;
+  const u = a.ease ? easeBezier(a.ease, x) : x;
+  return lerpValue(a.value, b.value, u);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Choreography combinators (pure)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Shift every keyframe in a track by `dt` seconds (immutable). */
+export function shiftTrack(tr: Track, dt: number): Track {
+  if (dt === 0) return tr;
+  const out: Track = {
+    property: tr.property,
+    keyframes: tr.keyframes.map((k) => ({ ...k, t: k.t + dt })),
+  };
+  if (tr.target !== undefined) out.target = tr.target;
+  return out;
+}
+
+/**
+ * Bake a timeline's declarative `stagger` field into its tracks (keyframe `t`
+ * += index·stagger), clearing the field and growing `dur` to fit. A no-op when
+ * `stagger` is unset/zero. Idempotent on an already-resolved timeline.
+ */
+export function resolveStagger(tl: Timeline): Timeline {
+  if (!tl.stagger) return tl;
+  const tracks = tl.tracks.map((tr, i) => shiftTrack(tr, i * (tl.stagger as number)));
+  const out: Timeline = { dur: Math.max(tl.dur, trackSpan(tracks)), tracks };
+  if (tl.begin !== undefined) out.begin = tl.begin;
+  if (tl.repeat !== undefined) out.repeat = tl.repeat;
+  return out;
+}
+
+/**
+ * Stagger a list of tracks: track `i` is offset by `i · delay` seconds. The
+ * imperative form of {@link Timeline.stagger}. Returns the offset tracks (sort
+ * order preserved).
+ */
+export function stagger(tracks: Track[], delay: number): Track[] {
+  return tracks.map((tr, i) => shiftTrack(tr, i * delay));
+}
+
+/**
+ * Compose timelines IN PARALLEL — all start together; the result's tracks are
+ * the union (each first resolved for its own `stagger`/`begin`). `dur` is the
+ * max. The shape for "these things animate at once".
+ */
+export function parallel(...timelines: Timeline[]): Timeline {
+  const tracks: Track[] = [];
+  let dur = 0;
+  for (const raw of timelines) {
+    const tl = resolveStagger(raw);
+    const b = tl.begin ?? 0;
+    for (const tr of tl.tracks) tracks.push(shiftTrack(tr, b));
+    dur = Math.max(dur, b + tl.dur);
+  }
+  return { dur, tracks };
+}
+
+/**
+ * Compose timelines IN SERIES — each starts where the previous ended (its own
+ * `begin` adds extra gap). The shape for "first this, then that". Durations
+ * sum (plus gaps); tracks are shifted onto the shared clock.
+ */
+export function sequence(...timelines: Timeline[]): Timeline {
+  const tracks: Track[] = [];
+  let cursor = 0;
+  for (const raw of timelines) {
+    const tl = resolveStagger(raw);
+    const start = cursor + (tl.begin ?? 0);
+    for (const tr of tl.tracks) tracks.push(shiftTrack(tr, start));
+    cursor = start + tl.dur;
+  }
+  return { dur: cursor, tracks };
+}

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

@@ -1,6 +1,6 @@
 /**
  * @file       draw/brush.ts — Phase 25.2 brush layer
- * @scope      plugins/design/dev-server/draw/brush.ts
+ * @scope      apps/studio/draw/brush.ts
  * @purpose    "Brush" expression for a pure-vector engine, three levels:
  *               L1  roughenFilter()  — feTurbulence → feDisplacementMap edge
  *                   texture (dry-brush / ink / charcoal roughness) you apply to

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

@@ -1,6 +1,6 @@
 /**
  * @file       draw/composition.ts — Phase 25.1 compositional scaffolding layer
- * @scope      plugins/design/dev-server/draw/composition.ts
+ * @scope      apps/studio/draw/composition.ts
  * @purpose    The missing answer to "blob soup": deterministic COMPOSITION.
  *             Random placement is empirically catastrophic — only ~3–12% of
  *             randomly-placed multi-element layouts even avoid overlap (Shiripour