@1agh/maude 0.39.0 → 0.40.0

package/apps/studio/canvas-edit.ts

@@ -27,6 +27,10 @@
 // (matches the locator.ts pattern). Two parallel edits against different
 // canvases run in parallel.
 
+import { mkdir, open, stat, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
 import MagicString from 'magic-string';
 import { parseSync } from 'oxc-parser';
 
@@ -144,8 +148,67 @@ function findAttribute(opening: AnyNode, name: string): AnyNode | null {
 }
 
 // ---------------------------------------------------------------------------
-// Per-canvas mutex. Mirrors locator.ts; two concurrent edits against the same
-// .tsx file serialise so they can't race read-modify-write.
+// Per-canvas mutex — TWO layers (DDR-150 P2). (1) An in-process Promise chain
+// serialises edits within THIS process (fast). (2) A cross-process advisory
+// lockfile serialises against edits from ANOTHER process — the `/design:edit`
+// CLI (`import.meta.main` below) or the HMR file-watcher — so their
+// read-modify-write can't interleave with ours and lose an update (the in-
+// process `locks` Map alone couldn't see them). The lockfile lives in the OS
+// temp dir (NOT the versioned design root — never touches the gitignore
+// taxonomy) keyed by the canvas absolute path. A crashed holder leaves a STALE
+// lock, stolen after LOCK_STALE_MS; if it stays contended past LOCK_MAX_WAIT_MS
+// we proceed anyway rather than deadlock — the atomic tmp-rename write + the
+// content-hash fingerprint are the backstop against a truly simultaneous writer.
+
+const LOCK_DIR = path.join(tmpdir(), 'maude-locks');
+const LOCK_STALE_MS = 15_000;
+const LOCK_POLL_MS = 25;
+const LOCK_MAX_WAIT_MS = 10_000;
+
+/** OS-temp lockfile path for a canvas (shared across processes; keyed by abs path). */
+export function lockPathFor(filePath: string): string {
+  return path.join(LOCK_DIR, `${Bun.hash(filePath).toString(16).padStart(16, '0')}.lock`);
+}
+
+/**
+ * Acquire the cross-process advisory lock for `filePath`; resolves to an
+ * idempotent release fn. Exported for tests. Degrades to a no-op lock (rather
+ * than breaking every edit) if the temp dir is unwritable or contention outlasts
+ * LOCK_MAX_WAIT_MS.
+ */
+export async function acquireFileLock(filePath: string): Promise<() => Promise<void>> {
+  const lp = lockPathFor(filePath);
+  await mkdir(LOCK_DIR, { recursive: true }).catch(() => {});
+  const start = Date.now();
+  for (;;) {
+    try {
+      const fh = await open(lp, 'wx'); // O_CREAT | O_EXCL — fails if already held
+      await fh.writeFile(`${process.pid} ${Date.now()}`);
+      await fh.close();
+      let released = false;
+      return async () => {
+        if (released) return;
+        released = true;
+        await unlink(lp).catch(() => {});
+      };
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') {
+        return async () => {}; // can't create a lockfile at all → in-process-only
+      }
+      try {
+        const st = await stat(lp);
+        if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+          await unlink(lp).catch(() => {}); // holder crashed — steal
+          continue;
+        }
+      } catch {
+        continue; // vanished between EEXIST and stat — retry the create
+      }
+      if (Date.now() - start > LOCK_MAX_WAIT_MS) return async () => {}; // don't deadlock
+      await new Promise((r) => setTimeout(r, LOCK_POLL_MS));
+    }
+  }
+}
 
 const locks = new Map<string, Promise<void>>();
 function withLock<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
@@ -156,10 +219,21 @@ function withLock<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
   });
   const next = prev.then(() => gate);
   locks.set(filePath, next);
-  return prev.then(fn).finally(() => {
-    release();
-    if (locks.get(filePath) === next) locks.delete(filePath);
-  });
+  return prev
+    .then(async () => {
+      // In-process calls are already serialised by the chain above, so only ONE
+      // local call ever contends the lockfile — cross-process is its only job.
+      const releaseFile = await acquireFileLock(filePath);
+      try {
+        return await fn();
+      } finally {
+        await releaseFile();
+      }
+    })
+    .finally(() => {
+      release();
+      if (locks.get(filePath) === next) locks.delete(filePath);
+    });
 }
 
 // ---------------------------------------------------------------------------
@@ -402,6 +476,30 @@ export function applyTextEdit(
     });
   }
   const only = meaningful[0];
+  // A single `{'string literal'}` expression child — `<h1>{'Title'}</h1>` — is
+  // editable (DDR-150 P1): rewrite the literal in place. Written back via
+  // JSON.stringify so the result is an inert, correctly-escaped quoted string —
+  // the value never leaves the `{...}`, so (unlike JSXText) there is no markup /
+  // entity injection surface to guard. Any OTHER expression (identifier,
+  // template, call, member — `{title}`, `` {`${n} items`} ``) is genuinely
+  // dynamic: refuse and route to /design:edit rather than delete the binding.
+  if (meaningful.length === 1 && only?.type === 'JSXExpressionContainer') {
+    const expr = (only as AnyNode).expression;
+    if (
+      expr &&
+      (expr.type === 'Literal' || expr.type === 'StringLiteral') &&
+      typeof expr.value === 'string'
+    ) {
+      const s = new MagicString(source);
+      s.overwrite(expr.start as number, expr.end as number, JSON.stringify(text));
+      const out = s.toString();
+      return { source: out, delta: out.length - source.length };
+    }
+    throw new CanvasEditError(`element "${id}" has dynamic content — edit it via /design:edit`, {
+      canvas: canvasAbsPath,
+      id,
+    });
+  }
   if (meaningful.length > 1 || only?.type !== 'JSXText') {
     throw new CanvasEditError(
       `element "${id}" has mixed or expression content — edit it via /design:edit`,
@@ -831,131 +929,1814 @@ export function applyMove(
 }
 
 // ---------------------------------------------------------------------------
-// Edit shapes.
+// DDR-148 — Timeline drag-to-retime. Rewrites a `<...Sequence>`'s
+// `durationInFrames` / `from` to a new frame count. Sequences are addressed by
+// their document ORDER (the same order timeline-parse.js tokenizes them), not a
+// data-cd-id — a member-expression element (`TransitionSeries.Sequence`) has no
+// stable cd-id, and the order is what the Timeline UI already knows.
+
+export interface RetimePatch {
+  durationInFrames?: number;
+  from?: number;
+}
 
-function editStringAttr(s: MagicString, opening: AnyNode, name: string, value: string): void {
-  const attr = findAttribute(opening, name);
-  if (attr) {
-    // Replace existing value. JSX attribute value forms we handle:
-    //   - <Tag name="literal" />           → replace inside the quotes
-    //   - <Tag name={'literal'} />         → wrap quotes around new value
-    //   - <Tag name={expr} />              → replace the whole expression text
-    //   - <Tag name />                     → no value node; add `="..."`
-    const v = attr.value;
-    if (!v) {
-      // <Tag name /> → <Tag name="value" />
-      s.appendLeft(attr.end, `="${escapeAttr(value)}"`);
-      return;
+const SEQ_TAG_RE = /<(?:TransitionSeries\.Sequence|Series\.Sequence|Sequence)\b[^>]*>/g;
+
+/**
+ * Rewrite one attribute on a sequence tag. Prefers editing a referenced const
+ * (`durationInFrames={A}` → bump `const A = …`) so a derived total
+ * (`const TOTAL = A + B - XF`) updates in lock-step; falls back to editing a
+ * literal in place; refuses a non-trivial expression (returns false).
+ */
+function retimeAttr(
+  s: MagicString,
+  source: string,
+  tag: string,
+  tagStart: number,
+  key: 'durationInFrames' | 'from',
+  newVal: number
+): boolean {
+  const am = tag.match(new RegExp(`\\b${key}=\\{\\s*([^}]*?)\\s*\\}`));
+  if (!am || am.index == null) {
+    // Attr absent. For `from`, INSERT it — moving a cursor-implicit clip
+    // (`<Sequence durationInFrames={…}>`) to a new start needs an explicit
+    // `from` (DDR-150 P3 Task 6). durationInFrames is required on a clip, so
+    // never auto-insert it.
+    if (key === 'from') {
+      const nameMatch = tag.match(/^<([A-Za-z][\w.]*)/);
+      if (nameMatch) {
+        s.appendLeft(tagStart + nameMatch[0].length, ` from={${newVal}}`);
+        return true;
+      }
     }
-    if (v.type === 'Literal' || v.type === 'StringLiteral') {
-      // Replace the whole `"value"` (quotes included) so we control the escaping.
-      // The value lands in a JSX *attribute*, where `"` must become `&quot;` and
-      // `<`/`>` their entities — NOT JS backslash escaping. `JSON.stringify` would
-      // emit `\"`, which is invalid in a JSX attribute and corrupts the source on
-      // any value containing a double quote. Use the same `escapeAttr` as the two
-      // insert branches so all four paths agree. See DDR-103 / DDR-105.
-      s.overwrite(v.start, v.end, `"${escapeAttr(value)}"`);
-      return;
+    return false;
+  }
+  const inner = am[1].trim();
+  if (/^[A-Za-z_$][\w$]*$/.test(inner)) {
+    const cm = source.match(new RegExp(`\\bconst\\s+${inner}\\s*=\\s*(-?\\d+)`));
+    if (cm && cm.index != null && cm[1]) {
+      const numStart = cm.index + cm[0].lastIndexOf(cm[1]);
+      s.overwrite(numStart, numStart + cm[1].length, String(newVal));
+      return true;
     }
-    if (v.type === 'JSXExpressionContainer') {
-      // Replace the whole `{...}` with a plain quoted literal — keeps the
-      // resulting JSX readable. Same JSX-attribute escaping as above (NOT
-      // `JSON.stringify`, which would JS-escape a `"` and corrupt the source).
-      s.overwrite(v.start, v.end, `"${escapeAttr(value)}"`);
-      return;
+  }
+  if (/^-?\d+$/.test(inner)) {
+    const innerRel = am[0].indexOf(inner, am[0].indexOf('{'));
+    const valStart = tagStart + am.index + innerRel;
+    s.overwrite(valStart, valStart + inner.length, String(newVal));
+    return true;
+  }
+  return false;
+}
+
+/** Pure retime — exposed for tests. Never mutates disk. */
+export function applyRetimeSequence(
+  canvasAbsPath: string,
+  source: string,
+  seqIndex: number,
+  patch: RetimePatch
+): { source: string } {
+  const s = new MagicString(source);
+  SEQ_TAG_RE.lastIndex = 0;
+  let i = 0;
+  let touched = false;
+  let m: RegExpExecArray | null = SEQ_TAG_RE.exec(source);
+  while (m) {
+    if (i === seqIndex) {
+      const tag = m[0];
+      const tagStart = m.index;
+      for (const [key, val] of [
+        ['durationInFrames', patch.durationInFrames],
+        ['from', patch.from],
+      ] as const) {
+        if (val == null || !Number.isFinite(val)) continue;
+        if (retimeAttr(s, source, tag, tagStart, key, Math.max(0, Math.round(val)))) touched = true;
+      }
+      break;
     }
-    // Unknown shape — refuse rather than corrupt.
-    throw new Error(`Unsupported JSX attribute value shape: ${v.type}`);
+    i += 1;
+    m = SEQ_TAG_RE.exec(source);
   }
-  // Attribute missing — insert right after the tag name (mirrors pipeline's
-  // injection point so attribute order stays predictable).
-  const insertAt: number | undefined = opening?.name?.end;
-  if (typeof insertAt !== 'number') {
-    throw new Error('Opening element has no resolvable name range');
+  if (!touched) {
+    throw new CanvasEditError(`no retimable sequence at index ${seqIndex}`, {
+      canvas: canvasAbsPath,
+      id: String(seqIndex),
+    });
   }
-  s.appendLeft(insertAt, ` ${name}="${escapeAttr(value)}"`);
+  const next = s.toString();
+  const parsed = parseSync(canvasAbsPath, next, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CanvasEditError(
+      `retime produced invalid source: ${parsed.errors[0]?.message ?? 'parse error'}`,
+      { canvas: canvasAbsPath, id: String(seqIndex) }
+    );
+  }
+  return { source: next };
 }
 
-function escapeAttr(value: string): string {
-  return value.replace(/"/g, '&quot;').replace(/[<>]/g, (c) => (c === '<' ? '&lt;' : '&gt;'));
+/** Retime a sequence on disk (atomic write + per-file lock, like moveElement). */
+export async function retimeSequence(
+  canvasAbsPath: string,
+  seqIndex: number,
+  patch: RetimePatch
+): Promise<{ source: string }> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: String(seqIndex),
+      });
+    }
+    const source = await file.text();
+    const next = applyRetimeSequence(canvasAbsPath, source, seqIndex, patch);
+    if (next.source === source) return next;
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return next;
+  });
 }
 
 /**
- * Escape JSX-significant characters so user-typed text lands in source `.tsx`
- * as inert TEXT, never as markup or an expression. The text is written between
- * an element's tags (`<button>HERE</button>`), where `<`/`>` would start a tag
- * and `{`/`}` would open a JSX expression — so all four (plus a bare `&`, which
- * begins an entity) are encoded. This is the load-bearing guard that keeps the
- * inline text editor (Phase 12) from being a source-injection vector. See
- * DDR-103.
+ * Retime a clip addressed by the enumerator's `stableId` (comp-scoped) instead of
+ * a whole-file index — the DDR-150 P2 fix for the multi-comp mis-hit. Verifies
+ * the content-hash fingerprint (refuse a stale/raced target), patches the clip's
+ * own tag via `retimeAttr` (const-preferring), then reparse + semantic gate.
  */
-function escapeJsxText(value: string): string {
-  return value
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/\{/g, '&#123;')
-    .replace(/\}/g, '&#125;');
-}
-
-function editStyleProp(
-  s: MagicString,
-  opening: AnyNode,
-  prop: string,
-  value: string,
+export function applyRetimeSequenceByClip(
   canvasAbsPath: string,
-  id: string
-): void {
-  const attr = findAttribute(opening, 'style');
-  if (!attr) {
-    // No style prop yet — insert one with a single key.
-    const insertAt: number | undefined = opening?.name?.end;
-    if (typeof insertAt !== 'number') {
-      throw new Error('Opening element has no resolvable name range');
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined,
+  patch: RetimePatch
+): { source: string } {
+  const clip = resolveClip(canvasAbsPath, source, artboardId, stableId, expectedHash);
+  // A `from` move is STANDALONE-<Sequence>-only. `<TransitionSeries.Sequence>` /
+  // `<Series.Sequence>` compute their own offsets — Remotion silently IGNORES a
+  // `from` prop on them, so patching/inserting one writes a lie: the timeline
+  // draws a gap while the rendered video never changes (the dogfood bug —
+  // "video je furt stejné, ať klipem pohnu jakkoliv"). Refuse loudly instead.
+  if (patch.from != null && clip.tag !== 'Sequence') {
+    throw new CanvasEditError(
+      `"${stableId}" is a ${clip.tag} — the series computes its position, so moving it has no effect. Trim its duration instead, or reorder the beats.`,
+      { canvas: canvasAbsPath, id: stableId }
+    );
+  }
+  const s = new MagicString(source);
+  SEQ_TAG_RE.lastIndex = 0;
+  let touched = false;
+  let m: RegExpExecArray | null = SEQ_TAG_RE.exec(source);
+  while (m) {
+    if (m.index === clip.start) {
+      for (const [key, val] of [
+        ['durationInFrames', patch.durationInFrames],
+        ['from', patch.from],
+      ] as const) {
+        if (val == null || !Number.isFinite(val)) continue;
+        if (retimeAttr(s, source, m[0], m.index, key, Math.max(0, Math.round(val)))) touched = true;
+      }
+      break;
     }
-    s.appendLeft(insertAt, ` style={{ ${jsKey(prop)}: ${value} }}`);
-    return;
+    m = SEQ_TAG_RE.exec(source);
   }
-  const v = attr.value;
-  if (v?.type !== 'JSXExpressionContainer') {
+  if (!touched) {
+    throw new CanvasEditError(`clip "${stableId}" has no retimable from/durationInFrames`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const next = s.toString();
+  const parsed = parseSync(canvasAbsPath, next, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
     throw new CanvasEditError(
-      `style attribute on ${id} is not a {{...}} expression — refusing to edit`,
-      { canvas: canvasAbsPath, id }
+      `retime produced invalid source: ${parsed.errors[0]?.message ?? 'parse error'}`,
+      { canvas: canvasAbsPath, id: stableId }
     );
   }
-  const obj = v.expression;
-  if (obj?.type !== 'ObjectExpression') {
-    throw new CanvasEditError(
-      `style={...} on ${id} is not an inline ObjectExpression — refusing to edit`,
-      { canvas: canvasAbsPath, id }
+  assertCompSemantics(canvasAbsPath, next);
+  return { source: next };
+}
+
+/** Retime a clip by stableId on disk (atomic write + cross-process lock). */
+export async function retimeSequenceByClip(
+  canvasAbsPath: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined,
+  patch: RetimePatch
+): Promise<{ source: string }> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: stableId,
+      });
+    }
+    const source = await file.text();
+    const next = applyRetimeSequenceByClip(
+      canvasAbsPath,
+      source,
+      artboardId,
+      stableId,
+      expectedHash,
+      patch
     );
+    if (next.source === source) return next;
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return next;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Clip addressing (DDR-150 P2). The SINGLE authoritative tokenizer for a
+// video-comp's clips. The Timeline UI addresses every op through the `stableId`
+// this returns, NOT its own regex position — killing the two-tokenizer
+// document-order disagreement that made destructive ops corrupt the wrong clip
+// on a multi-comp canvas (the debate's headline defect). AST-based, so it skips
+// tags inside comments/strings (the regex parser didn't) and scopes cleanly to
+// one comp's body even when several comps share a file.
+
+/** Sequence-family "clip" tags (the timeline rows). */
+const CLIP_TAGS = new Set(['Sequence', 'Series.Sequence', 'TransitionSeries.Sequence']);
+/** Transition tags (occupy a slot between clips inside a TransitionSeries). */
+const TRANSITION_TAGS = new Set(['Series.Transition', 'TransitionSeries.Transition']);
+/** Media tags that carry a `src` (the replace-media + drop targets). */
+const MEDIA_TAGS = new Set(['Video', 'OffthreadVideo', 'Audio', 'Img', 'Image']);
+/** Remotion/layout primitives that are structural, not their own timeline layer. */
+const LAYER_SKIP_TAGS = new Set([
+  'AbsoluteFill',
+  'Sequence',
+  'Series',
+  'Series.Sequence',
+  'Series.Transition',
+  'TransitionSeries',
+  'TransitionSeries.Sequence',
+  'TransitionSeries.Transition',
+  'Loop',
+  'Freeze',
+  'Fragment',
+]);
+
+/** Full tag string of a JSXElement: `Sequence` | `TransitionSeries.Sequence` | … */
+function jsxTagName(node: AnyNode): string | null {
+  const n = node?.openingElement?.name;
+  if (!n) return null;
+  if (n.type === 'JSXIdentifier') return typeof n.name === 'string' ? n.name : null;
+  if (n.type === 'JSXMemberExpression') {
+    const obj = n.object?.type === 'JSXIdentifier' ? n.object.name : null;
+    const prop = n.property?.type === 'JSXIdentifier' ? n.property.name : null;
+    if (obj && prop) return `${obj}.${prop}`;
   }
+  return null;
+}
 
-  // Search for an existing property with the same key. JSX styles permit
-  // camelCase identifiers (paddingTop) AND quoted strings ("padding-top").
-  // Compare both forms.
-  const propCamel = prop.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-  for (const p of obj.properties as AnyNode[]) {
-    if (p?.type !== 'Property' && p?.type !== 'ObjectProperty') continue;
-    const k = p.key;
-    if (!k) continue;
-    const kname = k.type === 'Identifier' ? k.name : k.type === 'Literal' ? String(k.value) : null;
-    if (kname === prop || kname === propCamel) {
-      s.overwrite(p.value.start, p.value.end, value);
+/** Evaluate a numeric AST expression against a resolved const map (literal,
+ *  negation, const identifier, or simple arithmetic of them). null if not
+ *  resolvable — from/duration are best-effort labels, never load-bearing for
+ *  addressing (that's stableId + contentHash). */
+function evalNum(n: AnyNode, consts: Record<string, number>): number | null {
+  if (!n || typeof n !== 'object') return null;
+  const t = n.type;
+  if ((t === 'Literal' || t === 'NumericLiteral') && typeof n.value === 'number') return n.value;
+  if (t === 'UnaryExpression' && n.operator === '-') {
+    const v = evalNum(n.argument, consts);
+    return v == null ? null : -v;
+  }
+  if (t === 'Identifier') return Object.hasOwn(consts, n.name) ? (consts[n.name] as number) : null;
+  if (t === 'BinaryExpression') {
+    const l = evalNum(n.left, consts);
+    const r = evalNum(n.right, consts);
+    if (l == null || r == null) return null;
+    switch (n.operator) {
+      case '+':
+        return l + r;
+      case '-':
+        return l - r;
+      case '*':
+        return l * r;
+      case '/':
+        return r ? l / r : null;
+      default:
+        return null;
+    }
+  }
+  return null;
+}
+
+/** Top-level numeric const bindings (3 passes so a derived `TOTAL = A + B` resolves). */
+function collectNumericConsts(program: AnyNode): Record<string, number> {
+  const consts: Record<string, number> = {};
+  const decls: Array<{ name: string; init: AnyNode }> = [];
+  for (const node of program?.body ?? []) {
+    if (node?.type !== 'VariableDeclaration') continue;
+    for (const d of node.declarations ?? []) {
+      if (d?.id?.type === 'Identifier' && d.init) decls.push({ name: d.id.name, init: d.init });
+    }
+  }
+  for (let pass = 0; pass < 3; pass += 1) {
+    for (const { name, init } of decls) {
+      if (Object.hasOwn(consts, name)) continue;
+      const v = evalNum(init, consts);
+      if (v != null && Number.isFinite(v)) consts[name] = Math.round(v);
+    }
+  }
+  return consts;
+}
+
+/** Resolve a numeric JSX attribute (`from={20}` / `durationInFrames={A}`). */
+function numAttr(opening: AnyNode, name: string, consts: Record<string, number>): number | null {
+  const a = findAttribute(opening, name);
+  let v = a?.value;
+  if (!v) return null;
+  if (v.type === 'JSXExpressionContainer') v = v.expression;
+  const n = evalNum(v, consts);
+  return n == null ? null : Math.round(n);
+}
+
+/** First media descendant of a clip (its `<Video>`/`<Audio>`/`<Img>` — the replace target). */
+function firstMediaDescendant(clip: AnyNode): AnyNode | null {
+  let found: AnyNode | null = null;
+  function walk(n: AnyNode): void {
+    if (found || !n || typeof n !== 'object') return;
+    if (Array.isArray(n)) {
+      for (const c of n) {
+        if (found) return;
+        walk(c);
+      }
       return;
     }
+    if (n.type === 'JSXElement' && MEDIA_TAGS.has(jsxTagName(n) ?? '')) {
+      found = n;
+      return;
+    }
+    for (const k of Object.keys(n)) {
+      if (k === 'loc' || k === 'range' || k === 'start' || k === 'end' || k === 'type') continue;
+      walk(n[k]);
+    }
   }
+  walk(clip.children ?? []);
+  return found;
+}
 
-  // Key missing — append before the closing `}`. ObjectExpression's last char
-  // is the `}`; magic-string appendLeft at end keeps the brace in place.
-  const props = obj.properties as AnyNode[];
-  const tail = props.length > 0 ? (props[props.length - 1].end as number) : obj.start + 1;
-  const sep = props.length > 0 ? ', ' : ' ';
+/** Map every top-level component name → its render body root (for nested-media resolution). */
+function collectComponentBodies(program: AnyNode): Map<string, AnyNode> {
+  const out = new Map<string, AnyNode>();
+  const body = (program?.body ?? []) as AnyNode[];
+  for (const stmt of body) {
+    if (stmt?.type === 'FunctionDeclaration' && isPascalIdent(stmt.id?.name)) {
+      out.set(stmt.id.name, stmt.body);
+    } else if (stmt?.type === 'VariableDeclaration') {
+      for (const d of stmt.declarations ?? []) {
+        const name = componentNameOf(d);
+        if (name && d.init?.body) out.set(name, d.init.body);
+      }
+    }
+  }
+  return out;
+}
+
+/** Map every top-level `const NAME = [ {…}, … ]` → its ArrayExpression (for `CLIPS[i].src`). */
+function collectArrayLiterals(program: AnyNode): Map<string, AnyNode> {
+  const out = new Map<string, AnyNode>();
+  for (const stmt of (program?.body ?? []) as AnyNode[]) {
+    if (stmt?.type !== 'VariableDeclaration') continue;
+    for (const d of stmt.declarations ?? []) {
+      if (d?.id?.type === 'Identifier' && d.init?.type === 'ArrayExpression') {
+        out.set(d.id.name, d.init);
+      }
+    }
+  }
+  return out;
+}
+
+/** The first JSXElement child of `clip` whose tag is a PascalCase component (not a primitive). */
+function firstComponentChild(clip: AnyNode): AnyNode | null {
+  for (const child of (clip.children ?? []) as AnyNode[]) {
+    if (child?.type === 'JSXElement') {
+      const tag = jsxTagName(child);
+      if (tag && isPascalIdent(tag) && !MEDIA_TAGS.has(tag)) return child;
+    }
+  }
+  return null;
+}
+
+/** A media element's `src` attr node (JSX value), or null. */
+function srcAttrValue(mediaEl: AnyNode): AnyNode | null {
+  const attr = findAttribute(mediaEl.openingElement, 'src');
+  return attr?.value ?? null;
+}
+
+/**
+ * Resolve a clip's media even when it's nested one level inside a wrapper
+ * component whose `src` is fed by an array element (the showreel
+ * `<ClipShot clip={CLIPS[2]} />` → `<Video src={clip.src} />` pattern). Returns
+ * the media tag + a replace target: a direct `cdId` (literal src), an
+ * `arrayRef` (edit `NAME[i].field`), or `shared` (literal src in a reused comp).
+ */
+function resolveNestedMedia(
+  clip: AnyNode,
+  componentBodies: Map<string, AnyNode>,
+  arrays: Map<string, AnyNode>,
+  cdIdOf: Map<AnyNode, string>
+): {
+  el: AnyNode;
+  tag: string;
+  src: string | null;
+  cdId: string | null;
+  arrayRef: { arrayName: string; index: number; field: string } | null;
+  shared: boolean;
+} | null {
+  // 1. Direct media descendant (literal or prop src).
+  const direct = firstMediaDescendant(clip);
+  if (direct) {
+    return {
+      el: direct,
+      tag: jsxTagName(direct) ?? 'Video',
+      src: getStringAttr(direct.openingElement, 'src'),
+      cdId: cdIdOf.get(direct) ?? null,
+      arrayRef: null,
+      shared: false,
+    };
+  }
+  // 2. Wrapper component: <Comp propName={ARR[i]} /> → Comp body → media <X src={param.field}>.
+  const wrapper = firstComponentChild(clip);
+  if (!wrapper) return null;
+  const compName = jsxTagName(wrapper);
+  const body = compName ? componentBodies.get(compName) : null;
+  if (!body) return null;
+  const media = firstMediaDescendant({ children: [body] });
+  if (!media) return null;
+  const tag = jsxTagName(media) ?? 'Video';
+  const srcVal = srcAttrValue(media);
+  // Literal src inside the shared component → replaceable, but shared.
+  if (srcVal?.type === 'Literal' || srcVal?.type === 'StringLiteral') {
+    return {
+      el: media,
+      tag,
+      src: String(srcVal.value),
+      cdId: cdIdOf.get(media) ?? null,
+      arrayRef: null,
+      shared: true,
+    };
+  }
+  // Prop-bound src: `src={param.field}` where `param` is the component's first
+  // destructured/parameter name, bound at the call site to `ARR[i]`.
+  if (srcVal?.type === 'JSXExpressionContainer') {
+    const expr = srcVal.expression;
+    // member: param.field
+    if (
+      expr?.type === 'MemberExpression' &&
+      expr.object?.type === 'Identifier' &&
+      expr.property?.type === 'Identifier'
+    ) {
+      const field = expr.property.name;
+      // Find the call-site prop bound to this component's param: <Comp X={ARR[i]}>.
+      // The wrapper's first attribute value that is `ARR[i]` gives the array + index.
+      for (const attr of (wrapper.openingElement?.attributes ?? []) as AnyNode[]) {
+        const v = attr?.value;
+        if (v?.type !== 'JSXExpressionContainer') continue;
+        const e = v.expression;
+        if (
+          e?.type === 'MemberExpression' &&
+          e.object?.type === 'Identifier' &&
+          arrays.has(e.object.name) &&
+          e.property?.type === 'Literal' &&
+          typeof e.property.value === 'number'
+        ) {
+          const arr = arrays.get(e.object.name);
+          const el = (arr?.elements ?? [])[e.property.value] as AnyNode | undefined;
+          const prop =
+            el?.type === 'ObjectExpression'
+              ? (el.properties ?? []).find(
+                  (p: AnyNode) => p?.key?.name === field || p?.key?.value === field
+                )
+              : null;
+          const litSrc =
+            prop?.value && (prop.value.type === 'Literal' || prop.value.type === 'StringLiteral')
+              ? String(prop.value.value)
+              : null;
+          return {
+            el: media,
+            tag,
+            src: litSrc,
+            cdId: null,
+            arrayRef: { arrayName: e.object.name, index: e.property.value, field },
+            shared: false,
+          };
+        }
+      }
+    }
+  }
+  // Media exists but src isn't resolvable to a replaceable target.
+  return { el: media, tag, src: null, cdId: null, arrayRef: null, shared: false };
+}
+
+/** One visually-meaningful layer inside a clip (a media element or a named
+ *  sub-component) — so the Timeline can show a ClipShot's mp4 background and its
+ *  title/lower-third as SEPARATE rows instead of one opaque "ClipShot". */
+export interface ClipLayer {
+  kind: 'video' | 'image' | 'audio' | 'component';
+  /** Human label — the media filename, or the sub-component's tag. */
+  label: string;
+  mediaTag: string | null;
+  mediaSrc: string | null;
+  mediaCdId: string | null;
+  mediaArrayRef: { arrayName: string; index: number; field: string } | null;
+  mediaShared: boolean;
+}
+
+/**
+ * Decompose a clip into its stacked layers (media elements + named sub-components),
+ * resolving through a wrapper component (the showreel `<ClipShot clip={CLIPS[i]}>`
+ * → its `<Video>` + `<LowerThird>`). Ordered by source position. Skips Remotion/
+ * layout primitives (AbsoluteFill, Sequence, …). Returns [] when the clip has no
+ * decomposable structure (a pure inline card).
+ */
+function collectClipLayers(
+  clip: AnyNode,
+  componentBodies: Map<string, AnyNode>,
+  arrays: Map<string, AnyNode>,
+  cdIdOf: Map<AnyNode, string>
+): ClipLayer[] {
+  // Resolve the root to walk: the wrapper component's body if the clip wraps one,
+  // else the clip's own children. Carry the wrapper element so prop-fed src (the
+  // component's `clip` param → `CLIPS[i]`) resolves against the call site.
+  const wrapper = firstComponentChild(clip);
+  const wrapperTag = wrapper ? jsxTagName(wrapper) : null;
+  const body = wrapperTag ? componentBodies.get(wrapperTag) : null;
+  const root: AnyNode = body ? { children: [body] } : clip;
+
+  const layers: ClipLayer[] = [];
+  (function walk(n: AnyNode): void {
+    if (!n || typeof n !== 'object') return;
+    if (Array.isArray(n)) {
+      for (const c of n) walk(c);
+      return;
+    }
+    if (n.type === 'JSXElement') {
+      const tag = jsxTagName(n) ?? '';
+      if (MEDIA_TAGS.has(tag)) {
+        // Media layer — resolve src the same way replace does (literal / prop / array).
+        const m = wrapper
+          ? resolveMediaSrcThroughWrapper(n, wrapper, arrays, cdIdOf)
+          : {
+              src: getStringAttr(n.openingElement, 'src'),
+              cdId: cdIdOf.get(n) ?? null,
+              arrayRef: null as ClipLayer['mediaArrayRef'],
+              shared: false,
+            };
+        const kind: ClipLayer['kind'] =
+          tag === 'Audio' ? 'audio' : tag === 'Img' || tag === 'Image' ? 'image' : 'video';
+        layers.push({
+          kind,
+          label: m.src ? String(m.src).split('/').pop() || tag : tag,
+          mediaTag: tag,
+          mediaSrc: m.src,
+          mediaCdId: m.cdId,
+          mediaArrayRef: m.arrayRef,
+          mediaShared: m.shared,
+        });
+      } else if (
+        /^[A-Z]/.test(tag) &&
+        !LAYER_SKIP_TAGS.has(tag) &&
+        tag !== wrapperTag &&
+        componentBodies.has(tag) // a KNOWN locally-defined component → a real layer
+      ) {
+        // A named sub-component (LowerThird, TitleBadge, …) → a component layer.
+        // Only surface locally-defined components (skip unknown/library tags to
+        // avoid noise); its media (if any) is walked below and attributed to it.
+        layers.push({
+          kind: 'component',
+          label: tag,
+          mediaTag: null,
+          mediaSrc: null,
+          mediaCdId: null,
+          mediaArrayRef: null,
+          mediaShared: false,
+        });
+      }
+    }
+    // Generic recursion (mirrors firstMediaDescendant) so wrapped/parenthesized
+    // arrow bodies + all child positions are traversed, not just `children`.
+    for (const k of Object.keys(n)) {
+      if (k === 'loc' || k === 'range' || k === 'start' || k === 'end' || k === 'type') continue;
+      walk(n[k]);
+    }
+  })(root);
+  return layers;
+}
+
+/** Resolve a media element's src (literal / prop-fed-from-array) via its wrapper's call site. */
+function resolveMediaSrcThroughWrapper(
+  media: AnyNode,
+  wrapper: AnyNode,
+  arrays: Map<string, AnyNode>,
+  cdIdOf: Map<AnyNode, string>
+): {
+  src: string | null;
+  cdId: string | null;
+  arrayRef: ClipLayer['mediaArrayRef'];
+  shared: boolean;
+} {
+  const srcVal = srcAttrValue(media);
+  if (srcVal?.type === 'Literal' || srcVal?.type === 'StringLiteral') {
+    return {
+      src: String(srcVal.value),
+      cdId: cdIdOf.get(media) ?? null,
+      arrayRef: null,
+      shared: true,
+    };
+  }
+  if (
+    srcVal?.type === 'JSXExpressionContainer' &&
+    srcVal.expression?.type === 'MemberExpression' &&
+    srcVal.expression.property?.type === 'Identifier'
+  ) {
+    const field = srcVal.expression.property.name;
+    for (const attr of (wrapper.openingElement?.attributes ?? []) as AnyNode[]) {
+      const v = attr?.value;
+      const e = v?.type === 'JSXExpressionContainer' ? v.expression : null;
+      if (
+        e?.type === 'MemberExpression' &&
+        e.object?.type === 'Identifier' &&
+        arrays.has(e.object.name) &&
+        e.property?.type === 'Literal' &&
+        typeof e.property.value === 'number'
+      ) {
+        const arr = arrays.get(e.object.name);
+        const el = (arr?.elements ?? [])[e.property.value] as AnyNode | undefined;
+        const prop =
+          el?.type === 'ObjectExpression'
+            ? (el.properties ?? []).find(
+                (p: AnyNode) => p?.key?.name === field || p?.key?.value === field
+              )
+            : null;
+        const lit =
+          prop?.value && (prop.value.type === 'Literal' || prop.value.type === 'StringLiteral')
+            ? String(prop.value.value)
+            : null;
+        return {
+          src: lit,
+          cdId: null,
+          arrayRef: { arrayName: e.object.name, index: e.property.value, field },
+          shared: false,
+        };
+      }
+    }
+  }
+  return { src: null, cdId: cdIdOf.get(media) ?? null, arrayRef: null, shared: false };
+}
+
+/** The child span [start, end] of a clip element (between its `>` and `</`), or null (self-closing). */
+function clipChildrenSpan(node: AnyNode): { start: number; end: number } | null {
+  const oe = node.openingElement;
+  const ce = node.closingElement;
+  if (!oe || !ce || typeof oe.end !== 'number' || typeof ce.start !== 'number') return null;
+  return { start: oe.end as number, end: ce.start as number };
+}
+
+/** True when a clip's children are gated behind `{false && (…)}` (the hide marker). */
+function clipChildrenHidden(node: AnyNode, source: string): boolean {
+  const span = clipChildrenSpan(node);
+  if (!span) return false;
+  return /^\s*\{false && \(/.test(source.slice(span.start, span.end));
+}
+
+/** Stable content fingerprint of a clip's exact source span (optimistic-concurrency check). */
+function hashSpan(source: string, start: number, end: number): string {
+  return Bun.hash(source.slice(start, end)).toString(16).padStart(16, '0').slice(0, 12);
+}
+
+/** One clip (timeline row) + everything an op needs to address + label it. */
+export interface ClipInfo {
+  /** Durable identity: `name:<Sequence name>` → `mclip:<sentinel>` → `<comp>#<indexInComp>`. */
+  stableId: string;
+  kind: 'sequence' | 'transition';
+  tag: string;
+  from: number | null;
+  durationInFrames: number | null;
+  mediaTag: string | null;
+  mediaSrc: string | null;
+  /** Positional cd-id of the media element (for `editAttribute` src-replace). */
+  mediaCdId: string | null;
+  /**
+   * When the clip's media lives inside a wrapper component whose `src` is fed by
+   * an array element (`<ClipShot clip={CLIPS[2]} />` → `<Video src={clip.src}>`),
+   * this points at the array-literal string to edit for a replace (the showreel
+   * pattern). `mediaCdId` is then null (the element's src is a prop, not literal).
+   */
+  mediaArrayRef: { arrayName: string; index: number; field: string } | null;
+  /**
+   * True when the media's literal `src` lives in a SHARED wrapper component (every
+   * instance renders the same element) — replacing it changes every clip using
+   * that component. The client warns before applying.
+   */
+  mediaShared: boolean;
+  /** Positional cd-id of the clip's OWN `<Sequence>` node (for `moveElement` z-order reorder). */
+  clipCdId: string | null;
+  /** The clip's stacked layers (mp4 background + title/lower-third + …) for the
+   *  expandable timeline rows. Empty for a pure inline card. */
+  layers: ClipLayer[];
+  /** True when the clip's body is gated behind `{false && (…)}` (hidden — renders
+   *  nothing but keeps its time slot + the TransitionSeries alternation). */
+  hidden: boolean;
+  /** Fingerprint of the clip's source span — refuse an op if it no longer matches. */
+  contentHash: string;
+  start: number;
+  end: number;
+}
+
+/** A media element sitting DIRECTLY in the comp body (not inside a clip) — an
+ *  `<Audio>` music bed under the reel, a full-length `<Video>` background, … .
+ *  Not a clip (no from/duration semantics of its own), but it IS addressable:
+ *  the Timeline's audio rows use `cdId` for a replace (`editAttribute` on src). */
+export interface LooseMediaInfo {
+  tag: string;
+  src: string | null;
+  cdId: string | null;
+  contentHash: string;
+}
+
+export interface CompClips {
+  compName: string | null;
+  artboardId: string | null;
+  fps: number | null;
+  durationInFrames: number | null;
+  clips: ClipInfo[];
+  /** DDR-150 dogfood #5 — loose media beds (document order), for audio replace. */
+  media: LooseMediaInfo[];
+}
+
+/**
+ * Enumerate the clips of ONE video-comp (scoped by `artboardId` → its
+ * `<VideoComp component={X}>` → component X's body). The Timeline UI renders
+ * rows from this and addresses every op by `clip.stableId` — so UI and engine
+ * can never disagree about which clip is which (the multi-comp defect). Throws
+ * `CanvasEditError` on unparseable source.
+ */
+export function enumerateClips(
+  canvasAbsPath: string,
+  source: string,
+  artboardId?: string
+): CompClips {
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CanvasEditError(
+      `oxc-parser failed on ${canvasAbsPath}: ${parsed.errors[0]?.message ?? 'unknown'}`,
+      { canvas: canvasAbsPath, id: artboardId ?? '' }
+    );
+  }
+  const program = parsed.program;
+  const consts = collectNumericConsts(program);
+  const cdIdOf = new Map<AnyNode, string>();
+  for (const { id, node } of collectElements(program)) cdIdOf.set(node, id);
+
+  interface Usage {
+    compName: string | null;
+    artboardId: string | null;
+    fps: number | null;
+    duration: number | null;
+  }
+  interface RawClip {
+    tag: string;
+    kind: 'sequence' | 'transition';
+    node: AnyNode;
+    comp: string;
+    indexInComp: number;
+    start: number;
+    end: number;
+  }
+  interface RawMedia {
+    tag: string;
+    node: AnyNode;
+    comp: string;
+    start: number;
+    end: number;
+  }
+  const usages: Usage[] = [];
+  const clips: RawClip[] = [];
+  const mediaEls: RawMedia[] = [];
+  const compClipCount: Record<string, number> = {};
+  const compStack: string[] = [''];
+  const artboardStack: Array<string | null> = [];
+
+  function visit(node: AnyNode): void {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) {
+      for (const c of node) visit(c);
+      return;
+    }
+    if (typeof node.type !== 'string') return;
+    const newComp = componentNameOf(node);
+    let pushedComp = false;
+    if (newComp !== null) {
+      compStack.push(newComp);
+      pushedComp = true;
+    }
+    if (node.type === 'JSXElement') {
+      const tag = jsxTagName(node);
+      let pushedArt = false;
+      if (tag === 'DCArtboard') {
+        artboardStack.push(getStringAttr(node.openingElement, 'id'));
+        pushedArt = true;
+      }
+      if (tag === 'VideoComp') {
+        const compAttr = findAttribute(node.openingElement, 'component');
+        const cv = compAttr?.value;
+        const cn =
+          cv?.type === 'JSXExpressionContainer' && cv.expression?.type === 'Identifier'
+            ? cv.expression.name
+            : null;
+        usages.push({
+          compName: cn,
+          artboardId: artboardStack.length ? artboardStack[artboardStack.length - 1] : null,
+          fps: numAttr(node.openingElement, 'fps', consts),
+          duration: numAttr(node.openingElement, 'durationInFrames', consts),
+        });
+      }
+      if (tag && (CLIP_TAGS.has(tag) || TRANSITION_TAGS.has(tag))) {
+        const comp = compStack[compStack.length - 1] as string;
+        const idx = compClipCount[comp] ?? 0;
+        compClipCount[comp] = idx + 1;
+        clips.push({
+          tag,
+          kind: TRANSITION_TAGS.has(tag) ? 'transition' : 'sequence',
+          node,
+          comp,
+          indexInComp: idx,
+          start: node.start as number,
+          end: node.end as number,
+        });
+      }
+      if (tag && MEDIA_TAGS.has(tag)) {
+        // Every media element, with its owning comp — loose beds are filtered
+        // out of clip spans below (an <Audio> under the reel vs inside a clip).
+        mediaEls.push({
+          tag,
+          node,
+          comp: compStack[compStack.length - 1] as string,
+          start: node.start as number,
+          end: node.end as number,
+        });
+      }
+      if (node.openingElement) visit(node.openingElement.attributes);
+      visit(node.children);
+      if (pushedArt) artboardStack.pop();
+      if (pushedComp) compStack.pop();
+      return;
+    }
+    for (const k of Object.keys(node)) {
+      if (k === 'loc' || k === 'range' || k === 'start' || k === 'end' || k === 'type') continue;
+      visit(node[k]);
+    }
+    if (pushedComp) compStack.pop();
+  }
+  visit(program);
+
+  // Resolve which comp to scope to. Preference mirrors timeline-parse.js:
+  // the selected artboard's comp → a comp with clips → the first usage.
+  const target =
+    (artboardId && usages.find((u) => u.artboardId === artboardId && u.compName)) ||
+    usages.find((u) => u.compName && clips.some((c) => c.comp === u.compName)) ||
+    usages.find((u) => u.compName) ||
+    null;
+  const targetComp = target?.compName ?? clips[0]?.comp ?? null;
+
+  const componentBodies = collectComponentBodies(program);
+  const arrays = collectArrayLiterals(program);
+  const scoped = targetComp == null ? [] : clips.filter((c) => c.comp === targetComp);
+  const clipInfos: ClipInfo[] = scoped.map((c) => {
+    const opening = c.node.openingElement;
+    const nameAttr = getStringAttr(opening, 'name');
+    const before = source.slice(Math.max(0, c.start - 160), c.start);
+    const sentinel = before.match(/\{\/\*\s*@mclip\s+([A-Za-z0-9_-]+)\s*\*\/\}\s*$/);
+    const stableId =
+      nameAttr != null && nameAttr !== ''
+        ? `name:${nameAttr}`
+        : sentinel
+          ? `mclip:${sentinel[1]}`
+          : `${targetComp}#${c.indexInComp}`;
+    // Resolve media even through a wrapper component (the showreel pattern) so
+    // the Timeline can badge the clip video/image/audio AND replace its source.
+    const m = resolveNestedMedia(c.node, componentBodies, arrays, cdIdOf);
+    return {
+      stableId,
+      kind: c.kind,
+      tag: c.tag,
+      from: numAttr(opening, 'from', consts),
+      durationInFrames: numAttr(opening, 'durationInFrames', consts),
+      mediaTag: m ? m.tag : null,
+      mediaSrc: m ? m.src : null,
+      mediaCdId: m ? m.cdId : null,
+      mediaArrayRef: m ? m.arrayRef : null,
+      mediaShared: m ? m.shared : false,
+      clipCdId: cdIdOf.get(c.node) ?? null,
+      layers: collectClipLayers(c.node, componentBodies, arrays, cdIdOf),
+      hidden: clipChildrenHidden(c.node, source),
+      contentHash: hashSpan(source, c.start, c.end),
+      start: c.start,
+      end: c.end,
+    };
+  });
+
+  // Loose media beds — media in the target comp OUTSIDE every clip span
+  // (an <Audio> music bed, a background <Video>). Document order.
+  const media: LooseMediaInfo[] = mediaEls
+    .filter(
+      (mel) =>
+        mel.comp === targetComp && !scoped.some((c) => mel.start >= c.start && mel.end <= c.end)
+    )
+    .map((mel) => ({
+      tag: mel.tag,
+      src: getStringAttr(mel.node.openingElement, 'src'),
+      cdId: cdIdOf.get(mel.node) ?? null,
+      contentHash: hashSpan(source, mel.start, mel.end),
+    }));
+
+  return {
+    compName: targetComp,
+    artboardId: target?.artboardId ?? null,
+    fps: target?.fps ?? null,
+    durationInFrames: target?.duration ?? null,
+    clips: clipInfos,
+    media,
+  };
+}
+
+/**
+ * Resolve a `stableId` (from `enumerateClips`) to its live clip in `source`,
+ * verifying the caller's `expectedHash` still matches (optimistic concurrency —
+ * a stale UI index or a concurrent edit is refused, not silently mis-applied).
+ * Returns the ClipInfo (with current start/end for the patch). Throws on a
+ * missing id or a hash mismatch.
+ */
+export function resolveClip(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash?: string
+): ClipInfo {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const hit = clips.find((c) => c.stableId === stableId);
+  if (!hit) {
+    throw new CanvasEditError(`clip "${stableId}" not found`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  if (expectedHash != null && expectedHash !== hit.contentHash) {
+    throw new CanvasEditError(
+      `clip "${stableId}" changed since it was read (concurrent edit); reload and retry`,
+      { canvas: canvasAbsPath, id: stableId }
+    );
+  }
+  return hit;
+}
+
+/**
+ * The semantic gate (DDR-150 P2). Parse-clean is NOT correct: a wrong-clip
+ * delete, an orphaned/leading/double `<TransitionSeries.Transition>`, all parse
+ * fine yet render wrong. After any structural clip edit, assert every
+ * `<TransitionSeries>` strictly alternates Sequence/Transition and begins + ends
+ * with a Sequence. Throws `CanvasEditError` on a violation.
+ */
+export function assertCompSemantics(canvasAbsPath: string, source: string): { ok: true } {
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CanvasEditError(
+      `oxc-parser failed on ${canvasAbsPath}: ${parsed.errors[0]?.message ?? 'unknown'}`,
+      { canvas: canvasAbsPath, id: '' }
+    );
+  }
+  const series: AnyNode[] = [];
+  (function find(node: AnyNode): void {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) {
+      for (const c of node) find(c);
+      return;
+    }
+    if (node.type === 'JSXElement' && jsxTagName(node) === 'TransitionSeries') series.push(node);
+    for (const k of Object.keys(node)) {
+      if (k === 'loc' || k === 'range' || k === 'start' || k === 'end' || k === 'type') continue;
+      find(node[k]);
+    }
+  })(parsed.program);
+
+  for (const s of series) {
+    const kinds: Array<'sequence' | 'transition'> = [];
+    for (const child of s.children ?? []) {
+      if (child?.type !== 'JSXElement') continue;
+      const tag = jsxTagName(child);
+      if (tag && TRANSITION_TAGS.has(tag)) kinds.push('transition');
+      else if (tag && CLIP_TAGS.has(tag)) kinds.push('sequence');
+    }
+    if (kinds.length === 0) continue;
+    const bad =
+      kinds[0] !== 'sequence' ||
+      kinds[kinds.length - 1] !== 'sequence' ||
+      kinds.some((k, i) => i > 0 && k === kinds[i - 1]);
+    if (bad) {
+      throw new CanvasEditError(
+        'TransitionSeries must alternate Sequence/Transition and begin + end with a Sequence (a leading, trailing, or doubled Transition is invalid Remotion)',
+        { canvas: canvasAbsPath, id: '' }
+      );
+    }
+  }
+  return { ok: true };
+}
+
+/** Source span of an element extended back over its leading indent + newline
+ *  (so removing it doesn't leave a blank line) — mirrors moveElement's removeStart. */
+function spanWithFraming(source: string, start: number, end: number): [number, number] {
+  const line = lineStartInfo(source, start);
+  const rs = line.newlineBefore ? line.indentStart - 1 : line.indentStart;
+  return [rs, end];
+}
+
+/**
+ * Remove a clip (DDR-150 P3), addressed by the enumerator's stableId. Verifies
+ * the content-hash fingerprint; refuses removing the ONLY clip; when the clip
+ * lives in a `<TransitionSeries>` also removes ONE adjacent transition so the
+ * series stays valid; then reparse + semantic gate (the backstop that refuses a
+ * remove which would leave a dangling/doubled transition, rather than corrupt).
+ */
+export function applyRemoveClip(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined
+): { source: string } {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const idx = clips.findIndex((c) => c.stableId === stableId);
+  if (idx < 0) {
+    throw new CanvasEditError(`clip "${stableId}" not found`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const clip = clips[idx] as ClipInfo;
+  if (expectedHash != null && expectedHash !== clip.contentHash) {
+    throw new CanvasEditError(
+      `clip "${stableId}" changed since it was read (concurrent edit); reload and retry`,
+      { canvas: canvasAbsPath, id: stableId }
+    );
+  }
+  if (clip.kind !== 'sequence') {
+    throw new CanvasEditError(`"${stableId}" is a transition, not a removable clip`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  if (clips.filter((c) => c.kind === 'sequence').length <= 1) {
+    throw new CanvasEditError('cannot remove the only clip — delete the comp instead', {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const spans: Array<[number, number]> = [spanWithFraming(source, clip.start, clip.end)];
+  if (clip.tag.startsWith('TransitionSeries.')) {
+    const next = clips[idx + 1];
+    const prev = clips[idx - 1];
+    const t = next?.kind === 'transition' ? next : prev?.kind === 'transition' ? prev : null;
+    if (t) spans.push(spanWithFraming(source, t.start, t.end));
+  }
+  const s = new MagicString(source);
+  for (const [a, b] of spans) s.remove(a, b);
+  const out = s.toString();
+  const parsed = parseSync(canvasAbsPath, out, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CanvasEditError(
+      `remove produced invalid source: ${parsed.errors[0]?.message ?? 'parse error'}`,
+      { canvas: canvasAbsPath, id: stableId }
+    );
+  }
+  assertCompSemantics(canvasAbsPath, out); // refuse a dangling/doubled transition
+  return { source: out };
+}
+
+/** Remove a clip on disk (atomic write + cross-process lock). */
+export async function removeClip(
+  canvasAbsPath: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined
+): Promise<{ source: string }> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: stableId,
+      });
+    }
+    const source = await file.text();
+    const nextSrc = applyRemoveClip(canvasAbsPath, source, artboardId, stableId, expectedHash);
+    if (nextSrc.source === source) return nextSrc;
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, nextSrc.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return nextSrc;
+  });
+}
+
+/**
+ * Reorder a clip among its STANDALONE `<Sequence>` siblings (DDR-150 P5) — the
+ * z-order / render-stacking gesture (later sibling paints on top), distinct from
+ * the horizontal `from`-move. Reuses the shipped `applyMove` (re-indent + reparse
+ * + re-settle-through-id-churn) addressed by each clip's own cd-id, then runs the
+ * semantic gate. Refuses a `<TransitionSeries.Sequence>`/`<Series.Sequence>`
+ * (reordering those breaks the transition/back-to-back timing — not a stacking
+ * op) and a self-move. Both `stableId`s are fingerprint-checked. Returns the moved
+ * clip's stableId (recomputed from disk — a pure reorder leaves its content hash
+ * unchanged, so it's found even when addressed by scoped index).
+ */
+export function applyReorderClip(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  movedStableId: string,
+  movedHash: string | undefined,
+  refStableId: string,
+  refHash: string | undefined,
+  position: MovePosition
+): { source: string; stableId: string } {
+  if (movedStableId === refStableId) {
+    throw new CanvasEditError('cannot reorder a clip relative to itself', {
+      canvas: canvasAbsPath,
+      id: movedStableId,
+    });
+  }
+  const moved = resolveClip(canvasAbsPath, source, artboardId, movedStableId, movedHash);
+  const ref = resolveClip(canvasAbsPath, source, artboardId, refStableId, refHash);
+  const bothSeries =
+    (moved.tag === 'TransitionSeries.Sequence' || moved.tag === 'Series.Sequence') &&
+    (ref.tag === 'TransitionSeries.Sequence' || ref.tag === 'Series.Sequence');
+  // TransitionSeries/Series clips play in ORDER (not z-stacked) — "reorder" means
+  // change PLAY order. Physically moving the tag would break the S/T/S/T
+  // alternation, so instead SWAP the two sequences' spans in place: the
+  // transitions between them stay put, alternation is preserved, and the beats
+  // change order (DDR-150 dogfood — "reorder klip vrstvy" on a showreel).
+  if (bothSeries) {
+    const a = moved.start <= ref.start ? moved : ref;
+    const b = moved.start <= ref.start ? ref : moved;
+    const s = new MagicString(source);
+    s.overwrite(a.start, a.end, source.slice(b.start, b.end));
+    s.overwrite(b.start, b.end, source.slice(a.start, a.end));
+    const out = s.toString();
+    const parsed = parseSync(canvasAbsPath, out, { sourceType: 'module' });
+    if (parsed.errors && parsed.errors.length > 0) {
+      throw new CanvasEditError(
+        `reorder produced invalid source: ${parsed.errors[0]?.message ?? 'parse error'}`,
+        { canvas: canvasAbsPath, id: movedStableId }
+      );
+    }
+    assertCompSemantics(canvasAbsPath, out);
+    const after = enumerateClips(canvasAbsPath, out, artboardId);
+    const settled = after.clips.find((c) => c.contentHash === moved.contentHash);
+    return { source: out, stableId: settled?.stableId ?? movedStableId };
+  }
+  if (moved.tag !== 'Sequence' || ref.tag !== 'Sequence') {
+    throw new CanvasEditError(
+      'reorder needs two sequences of the same kind (standalone ↔ standalone, or series ↔ series)',
+      { canvas: canvasAbsPath, id: movedStableId }
+    );
+  }
+  if (!moved.clipCdId || !ref.clipCdId) {
+    throw new CanvasEditError('clip has no addressable node to reorder', {
+      canvas: canvasAbsPath,
+      id: movedStableId,
+    });
+  }
+  const res = applyMove(canvasAbsPath, source, moved.clipCdId, ref.clipCdId, position);
+  assertCompSemantics(canvasAbsPath, res.source);
+  // A pure reorder never touches the clip body → its content hash is preserved.
+  // Re-address by that hash so a scoped-index stableId still resolves post-move.
+  const after = enumerateClips(canvasAbsPath, res.source, artboardId);
+  const settled = after.clips.find((c) => c.contentHash === moved.contentHash);
+  return { source: res.source, stableId: settled?.stableId ?? movedStableId };
+}
+
+/** Reorder a clip on disk (atomic write + cross-process lock). */
+export async function reorderClip(
+  canvasAbsPath: string,
+  artboardId: string | undefined,
+  movedStableId: string,
+  movedHash: string | undefined,
+  refStableId: string,
+  refHash: string | undefined,
+  position: MovePosition
+): Promise<{ source: string; stableId: string }> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: movedStableId,
+      });
+    }
+    const source = await file.text();
+    const next = applyReorderClip(
+      canvasAbsPath,
+      source,
+      artboardId,
+      movedStableId,
+      movedHash,
+      refStableId,
+      refHash,
+      position
+    );
+    if (next.source === source) return next;
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return next;
+  });
+}
+
+/**
+ * Toggle a clip's visibility (DDR-150 dogfood — "hide clip"). Gates the clip's
+ * children behind `{false && (…)}` (hide) or strips it (show). The clip TAG stays
+ * — so it keeps its time slot and, inside a `<TransitionSeries>`, the S/T/S
+ * alternation stays valid — only its content stops rendering. Reversible.
+ * Fingerprint-checked. Returns the new hidden state.
+ */
+export function applyToggleClipHidden(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined
+): { source: string; hidden: boolean } {
+  resolveClip(canvasAbsPath, source, artboardId, stableId, expectedHash); // validate + fingerprint
+  // Re-parse to locate the clip's node (need its opening/closing tag spans).
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CanvasEditError(`oxc-parser failed: ${parsed.errors[0]?.message ?? 'unknown'}`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const info = clips.find((c) => c.stableId === stableId);
+  if (!info)
+    throw new CanvasEditError(`clip "${stableId}" not found`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  // Walk for the JSXElement whose span matches the resolved clip.
+  let node: AnyNode | null = null;
+  (function find(n: AnyNode): void {
+    if (node || !n || typeof n !== 'object') return;
+    if (Array.isArray(n)) {
+      for (const c of n) find(c);
+      return;
+    }
+    if (n.type === 'JSXElement' && n.start === info.start && n.end === info.end) {
+      node = n;
+      return;
+    }
+    for (const k of Object.keys(n)) {
+      if (k === 'loc' || k === 'range' || k === 'start' || k === 'end' || k === 'type') continue;
+      find(n[k]);
+    }
+  })(parsed.program);
+  if (!node)
+    throw new CanvasEditError(`clip "${stableId}" node not found`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  const span = clipChildrenSpan(node);
+  if (!span) {
+    throw new CanvasEditError('this clip has no body to hide (self-closing)', {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const children = source.slice(span.start, span.end);
+  const s = new MagicString(source);
+  let hidden: boolean;
+  if (/^\s*\{false && \(/.test(children)) {
+    // Unhide — strip the exact wrapper we added.
+    const inner = children.replace(/^(\s*)\{false && \(/, '$1').replace(/\)\}(\s*)$/, '$1');
+    s.overwrite(span.start, span.end, inner);
+    hidden = false;
+  } else {
+    s.overwrite(span.start, span.end, `{false && (${children})}`);
+    hidden = true;
+  }
+  const out = s.toString();
+  const re = parseSync(canvasAbsPath, out, { sourceType: 'module' });
+  if (re.errors && re.errors.length > 0) {
+    throw new CanvasEditError(
+      `hide produced invalid source: ${re.errors[0]?.message ?? 'parse error'}`,
+      {
+        canvas: canvasAbsPath,
+        id: stableId,
+      }
+    );
+  }
+  assertCompSemantics(canvasAbsPath, out);
+  return { source: out, hidden };
+}
+
+/** Toggle a clip's hidden state on disk (atomic write + cross-process lock). */
+export async function toggleClipHidden(
+  canvasAbsPath: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined
+): Promise<{ source: string; hidden: boolean }> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: stableId,
+      });
+    }
+    const source = await file.text();
+    const next = applyToggleClipHidden(canvasAbsPath, source, artboardId, stableId, expectedHash);
+    if (next.source === source) return next;
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return next;
+  });
+}
+
+/** Media tags a caller may insert as a clip's child (also gated at the api layer). */
+const INSERTABLE_MEDIA = new Set(['Video', 'Audio', 'Img', 'OffthreadVideo']);
+
+/**
+ * Insert a new `<Sequence>` clip into a comp (DDR-150 P4), addressed by
+ * artboardId. Appends after the comp's LAST clip (matching its indentation),
+ * optionally with a media child. Scoped to STANDALONE `<Sequence>` comps —
+ * refuses a `<TransitionSeries>` (its overlap/transition math isn't a clean
+ * append) and a comp with no existing clip to anchor to. Reparse + semantic
+ * gate; `src` contained (no ../ or script schemes). Returns the new stableId.
+ */
+export function applyInsertClip(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  opts: { from: number; durationInFrames: number; mediaTag?: string | null; src?: string | null }
+): { source: string; stableId: string | null } {
+  const { clips, compName } = enumerateClips(canvasAbsPath, source, artboardId);
+  if (!compName) {
+    throw new CanvasEditError('no video-comp for this artboard', {
+      canvas: canvasAbsPath,
+      id: artboardId ?? '',
+    });
+  }
+  if (clips.length === 0) {
+    throw new CanvasEditError('comp has no existing clip to anchor the insert', {
+      canvas: canvasAbsPath,
+      id: artboardId ?? '',
+    });
+  }
+  const last = clips[clips.length - 1] as ClipInfo;
+  const from = Math.max(0, Math.round(opts.from));
+  const dur = Math.max(1, Math.round(opts.durationInFrames));
+  const indent = lineStartInfo(source, last.start).indent;
+  const srcTrim = (opts.src ?? '').trim();
+  if (
+    opts.mediaTag &&
+    INSERTABLE_MEDIA.has(opts.mediaTag) &&
+    srcTrim &&
+    (/\.\./.test(srcTrim) || /^\s*(javascript|vbscript|file|data):/i.test(srcTrim))
+  ) {
+    throw new CanvasEditError(
+      'media src must be a contained asset path (no ../ or script schemes)',
+      {
+        canvas: canvasAbsPath,
+        id: artboardId ?? '',
+      }
+    );
+  }
+  const s = new MagicString(source);
+  if (last.tag.startsWith('TransitionSeries.') || last.tag.startsWith('Series.')) {
+    // DDR-150 dogfood — append INTO a TransitionSeries: add a transition + a new
+    // TransitionSeries.Sequence, keeping the S/T/S alternation. The transition is
+    // CLONED verbatim from an existing one in the series so its
+    // presentation/timing imports are already satisfied (we can't invent a
+    // `fade()` the comp may not import). Series sequences carry no `from`.
+    const seriesPrefix = last.tag.split('.')[0]; // 'TransitionSeries' | 'Series'
+    const proto = clips.find(
+      (c) => c.kind === 'transition' && c.tag.startsWith(`${seriesPrefix}.`)
+    );
+    if (!proto) {
+      throw new CanvasEditError(
+        `cannot append into a <${seriesPrefix}> with no existing transition to clone — add a beat via chat`,
+        { canvas: canvasAbsPath, id: artboardId ?? '' }
+      );
+    }
+    const transitionText = source.slice(proto.start, proto.end);
+    const media =
+      opts.mediaTag && INSERTABLE_MEDIA.has(opts.mediaTag)
+        ? `\n${indent}  <${opts.mediaTag} src="${escapeAttr(srcTrim)}" />\n${indent}`
+        : '';
+    const clipText =
+      `\n${indent}${transitionText}` +
+      `\n${indent}<${seriesPrefix}.Sequence durationInFrames={${dur}}>${media}</${seriesPrefix}.Sequence>`;
+    s.appendLeft(last.end, clipText);
+  } else {
+    const media =
+      opts.mediaTag && INSERTABLE_MEDIA.has(opts.mediaTag)
+        ? `\n${indent}  <${opts.mediaTag} src="${escapeAttr(srcTrim)}" />\n${indent}`
+        : '';
+    const clipText = `\n${indent}<Sequence from={${from}} durationInFrames={${dur}}>${media}</Sequence>`;
+    s.appendLeft(last.end, clipText);
+  }
+  const out = s.toString();
+  const parsed = parseSync(canvasAbsPath, out, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CanvasEditError(
+      `insert produced invalid source: ${parsed.errors[0]?.message ?? 'parse error'}`,
+      { canvas: canvasAbsPath, id: artboardId ?? '' }
+    );
+  }
+  assertCompSemantics(canvasAbsPath, out);
+  const after = enumerateClips(canvasAbsPath, out, artboardId);
+  const newStableId = after.clips.length
+    ? (after.clips[after.clips.length - 1]?.stableId ?? null)
+    : null;
+  return { source: out, stableId: newStableId };
+}
+
+/** Insert a clip on disk (atomic write + cross-process lock). */
+export async function insertClip(
+  canvasAbsPath: string,
+  artboardId: string | undefined,
+  opts: { from: number; durationInFrames: number; mediaTag?: string | null; src?: string | null }
+): Promise<{ source: string; stableId: string | null }> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: artboardId ?? '',
+      });
+    }
+    const source = await file.text();
+    const next = applyInsertClip(canvasAbsPath, source, artboardId, opts);
+    if (next.source === source) return next;
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return next;
+  });
+}
+
+/**
+ * Replace a media `src` that lives in an array-of-objects literal
+ * (`const CLIPS = [{ src: 'assets/a.mp4', … }, …]`) — the showreel pattern where
+ * a clip's `<Video src={clip.src}>` is fed by `<ClipShot clip={CLIPS[i]} />`.
+ * Pure. Rewrites `NAME[index].field`'s string to `value` (contained asset path).
+ * Throws `CanvasEditError` on a bad path / missing target.
+ */
+export function applyEditArrayElementString(
+  canvasAbsPath: string,
+  source: string,
+  arrayName: string,
+  index: number,
+  field: string,
+  value: string
+): { source: string } {
+  const v = value.trim();
+  if (!v || /\.\./.test(v) || /^\s*(javascript|vbscript|file|data|https?):/i.test(v)) {
+    throw new CanvasEditError('src must be a contained asset path (no ../ or scheme)', {
+      canvas: canvasAbsPath,
+      id: `${arrayName}[${index}].${field}`,
+    });
+  }
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CanvasEditError(`oxc-parser failed: ${parsed.errors[0]?.message ?? 'unknown'}`, {
+      canvas: canvasAbsPath,
+      id: arrayName,
+    });
+  }
+  let arr: AnyNode | null = null;
+  for (const stmt of (parsed.program?.body ?? []) as AnyNode[]) {
+    if (stmt?.type !== 'VariableDeclaration') continue;
+    for (const d of stmt.declarations ?? []) {
+      if (
+        d?.id?.type === 'Identifier' &&
+        d.id.name === arrayName &&
+        d.init?.type === 'ArrayExpression'
+      ) {
+        arr = d.init;
+      }
+    }
+  }
+  if (!arr)
+    throw new CanvasEditError(`array "${arrayName}" not found`, {
+      canvas: canvasAbsPath,
+      id: arrayName,
+    });
+  const el = (arr.elements ?? [])[index] as AnyNode | undefined;
+  if (!el || el.type !== 'ObjectExpression') {
+    throw new CanvasEditError(`${arrayName}[${index}] is not an object literal`, {
+      canvas: canvasAbsPath,
+      id: `${arrayName}[${index}]`,
+    });
+  }
+  const prop = (el.properties ?? []).find(
+    (p: AnyNode) => p?.key?.name === field || p?.key?.value === field
+  );
+  const valNode = prop?.value;
+  if (!valNode || (valNode.type !== 'Literal' && valNode.type !== 'StringLiteral')) {
+    throw new CanvasEditError(`${arrayName}[${index}].${field} is not a string literal`, {
+      canvas: canvasAbsPath,
+      id: `${arrayName}[${index}].${field}`,
+    });
+  }
+  const s = new MagicString(source);
+  s.overwrite(valNode.start as number, valNode.end as number, JSON.stringify(v));
+  const out = s.toString();
+  const re = parseSync(canvasAbsPath, out, { sourceType: 'module' });
+  if (re.errors && re.errors.length > 0) {
+    throw new CanvasEditError(
+      `edit produced invalid source: ${re.errors[0]?.message ?? 'parse error'}`,
+      {
+        canvas: canvasAbsPath,
+        id: arrayName,
+      }
+    );
+  }
+  return { source: out };
+}
+
+/** Edit an array-element src on disk (atomic write + cross-process lock). */
+export async function editArrayElementString(
+  canvasAbsPath: string,
+  arrayName: string,
+  index: number,
+  field: string,
+  value: string
+): Promise<{ source: string }> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: arrayName,
+      });
+    }
+    const source = await file.text();
+    const next = applyEditArrayElementString(canvasAbsPath, source, arrayName, index, field, value);
+    if (next.source === source) return next;
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return next;
+  });
+}
+
+/** A clip in an assemble request — a dropped reference chip's src + kind. */
+export interface AssembleClip {
+  src: string;
+  mediaKind: 'video' | 'audio';
+  /** Intrinsic duration probed client-side; falls back to fps*3 when absent. */
+  durationInFrames?: number | null;
+}
+
+/** Reject a src that isn't a contained relative asset path (no ../, no scheme). */
+function assertContainedAssetSrc(src: string, canvasAbsPath: string): void {
+  const t = src.trim();
+  if (!t || /\.\./.test(t) || /^\s*(javascript|vbscript|file|data|https?):/i.test(t)) {
+    throw new CanvasEditError(
+      'clip src must be a contained asset path (assets/…, no ../ or scheme)',
+      { canvas: canvasAbsPath, id: '' }
+    );
+  }
+}
+
+/**
+ * Generate a full video-comp canvas TSX from a set of dropped reference clips
+ * (DDR-150 P4 Task 12 — the "udělej z toho video" one-click). Video clips are
+ * laid back-to-back as named `<Sequence>`s (explicit from/durationInFrames — so
+ * they're immediately hand-editable on the Timeline, DDR-150); audio clips become
+ * `<Audio>` beds under the whole reel. Only bundled Remotion imports are used
+ * (skill invariant). `componentName` is the exported Canvas component; every src
+ * is escaped + contained. The comp is a genuine frame-driven composition, never a
+ * frozen preview. Throws `CanvasEditError` on an empty set / bad src.
+ */
+export function assembleCompSource(
+  componentName: string,
+  clips: AssembleClip[],
+  opts: { fps?: number; width?: number; height?: number } = {}
+): string {
+  const fps = Math.max(1, Math.round(opts.fps ?? 30));
+  const width = Math.max(1, Math.round(opts.width ?? 1280));
+  const height = Math.max(1, Math.round(opts.height ?? 720));
+  const videos = clips.filter((c) => c.mediaKind === 'video');
+  const audios = clips.filter((c) => c.mediaKind === 'audio');
+  if (videos.length === 0 && audios.length === 0) {
+    throw new CanvasEditError('assemble needs at least one clip', {
+      canvas: componentName,
+      id: '',
+    });
+  }
+  for (const c of clips) assertContainedAssetSrc(c.src, componentName);
+
+  const defDur = fps * 3;
+  let cursor = 0;
+  const seqLines: string[] = [];
+  videos.forEach((c, i) => {
+    const dur = Math.max(1, Math.round(c.durationInFrames ?? defDur));
+    seqLines.push(
+      `      <Sequence name="clip-${i + 1}" from={${cursor}} durationInFrames={${dur}}>`,
+      `        <OffthreadVideo src="${escapeAttr(c.src)}" />`,
+      `      </Sequence>`
+    );
+    cursor += dur;
+  });
+  // Audio beds run under the whole reel (no seek — a bed, not a clip).
+  audios.forEach((c) => {
+    seqLines.push(`      <Audio src="${escapeAttr(c.src)}" />`);
+  });
+  const total = Math.max(cursor, defDur);
+
+  const remotionImports = ['AbsoluteFill', 'Sequence'];
+  if (videos.length) remotionImports.push('OffthreadVideo');
+  if (audios.length) remotionImports.push('Audio');
+
+  return [
+    `import { DesignCanvas, DCSection, DCArtboard, VideoComp } from '@maude/canvas-lib';`,
+    `import { ${remotionImports.join(', ')} } from 'remotion';`,
+    ``,
+    `const Comp = () => (`,
+    `  <AbsoluteFill style={{ background: 'var(--bg-0)' }}>`,
+    ...seqLines,
+    `  </AbsoluteFill>`,
+    `);`,
+    ``,
+    `export default function ${componentName}() {`,
+    `  return (`,
+    `    <DesignCanvas>`,
+    `      <DCSection title="Assembled reel">`,
+    `        <DCArtboard id="reel" label="Reel" width={${width}} height={${height}}>`,
+    `          <VideoComp component={Comp} durationInFrames={${total}} fps={${fps}} width={${width}} height={${height}} />`,
+    `        </DCArtboard>`,
+    `      </DCSection>`,
+    `    </DesignCanvas>`,
+    `  );`,
+    `}`,
+    ``,
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Edit shapes.
+
+function editStringAttr(s: MagicString, opening: AnyNode, name: string, value: string): void {
+  const attr = findAttribute(opening, name);
+  if (attr) {
+    // Replace existing value. JSX attribute value forms we handle:
+    //   - <Tag name="literal" />           → replace inside the quotes
+    //   - <Tag name={'literal'} />         → wrap quotes around new value
+    //   - <Tag name={expr} />              → replace the whole expression text
+    //   - <Tag name />                     → no value node; add `="..."`
+    const v = attr.value;
+    if (!v) {
+      // <Tag name /> → <Tag name="value" />
+      s.appendLeft(attr.end, `="${escapeAttr(value)}"`);
+      return;
+    }
+    if (v.type === 'Literal' || v.type === 'StringLiteral') {
+      // Replace the whole `"value"` (quotes included) so we control the escaping.
+      // The value lands in a JSX *attribute*, where `"` must become `&quot;` and
+      // `<`/`>` their entities — NOT JS backslash escaping. `JSON.stringify` would
+      // emit `\"`, which is invalid in a JSX attribute and corrupts the source on
+      // any value containing a double quote. Use the same `escapeAttr` as the two
+      // insert branches so all four paths agree. See DDR-103 / DDR-105.
+      s.overwrite(v.start, v.end, `"${escapeAttr(value)}"`);
+      return;
+    }
+    if (v.type === 'JSXExpressionContainer') {
+      // Replace the whole `{...}` with a plain quoted literal — keeps the
+      // resulting JSX readable. Same JSX-attribute escaping as above (NOT
+      // `JSON.stringify`, which would JS-escape a `"` and corrupt the source).
+      s.overwrite(v.start, v.end, `"${escapeAttr(value)}"`);
+      return;
+    }
+    // Unknown shape — refuse rather than corrupt.
+    throw new Error(`Unsupported JSX attribute value shape: ${v.type}`);
+  }
+  // Attribute missing — insert right after the tag name (mirrors pipeline's
+  // injection point so attribute order stays predictable).
+  const insertAt: number | undefined = opening?.name?.end;
+  if (typeof insertAt !== 'number') {
+    throw new Error('Opening element has no resolvable name range');
+  }
+  s.appendLeft(insertAt, ` ${name}="${escapeAttr(value)}"`);
+}
+
+function escapeAttr(value: string): string {
+  return value.replace(/"/g, '&quot;').replace(/[<>]/g, (c) => (c === '<' ? '&lt;' : '&gt;'));
+}
+
+/**
+ * Escape JSX-significant characters so user-typed text lands in source `.tsx`
+ * as inert TEXT, never as markup or an expression. The text is written between
+ * an element's tags (`<button>HERE</button>`), where `<`/`>` would start a tag
+ * and `{`/`}` would open a JSX expression — so all four (plus a bare `&`, which
+ * begins an entity) are encoded. This is the load-bearing guard that keeps the
+ * inline text editor (Phase 12) from being a source-injection vector. See
+ * DDR-103.
+ */
+function escapeJsxText(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/\{/g, '&#123;')
+    .replace(/\}/g, '&#125;');
+}
+
+function editStyleProp(
+  s: MagicString,
+  opening: AnyNode,
+  prop: string,
+  value: string,
+  canvasAbsPath: string,
+  id: string
+): void {
+  const attr = findAttribute(opening, 'style');
+  if (!attr) {
+    // No style prop yet — insert one with a single key.
+    const insertAt: number | undefined = opening?.name?.end;
+    if (typeof insertAt !== 'number') {
+      throw new Error('Opening element has no resolvable name range');
+    }
+    s.appendLeft(insertAt, ` style={{ ${jsKey(prop)}: ${value} }}`);
+    return;
+  }
+  const v = attr.value;
+  if (v?.type !== 'JSXExpressionContainer') {
+    throw new CanvasEditError(
+      `style attribute on ${id} is not a {{...}} expression — refusing to edit`,
+      { canvas: canvasAbsPath, id }
+    );
+  }
+  const obj = v.expression;
+  if (obj?.type !== 'ObjectExpression') {
+    throw new CanvasEditError(
+      `style={...} on ${id} is not an inline ObjectExpression — refusing to edit`,
+      { canvas: canvasAbsPath, id }
+    );
+  }
+
+  // Search for an existing property with the same key. JSX styles permit
+  // camelCase identifiers (paddingTop) AND quoted strings ("padding-top").
+  // Compare both forms.
+  const propCamel = prop.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  for (const p of obj.properties as AnyNode[]) {
+    if (p?.type !== 'Property' && p?.type !== 'ObjectProperty') continue;
+    const k = p.key;
+    if (!k) continue;
+    const kname = k.type === 'Identifier' ? k.name : k.type === 'Literal' ? String(k.value) : null;
+    if (kname === prop || kname === propCamel) {
+      s.overwrite(p.value.start, p.value.end, value);
+      return;
+    }
+  }
+
+  // Key missing — append before the closing `}`. ObjectExpression's last char
+  // is the `}`; magic-string appendLeft at end keeps the brace in place.
+  //
+  // TRAILING-COMMA guard: a frame-driven inline style often ends the last
+  // property with a trailing comma (`opacity: o,\n}`). Unconditionally
+  // prepending `, ` there produced `opacity: o, , color: X` — a double comma =
+  // syntax error, so the canvas failed to rebuild and the Player kept rendering
+  // the OLD source (the "my CSS edit resets when I replay the video" bug).
+  // Detect an existing trailing comma between the last property and the `}` and
+  // omit our separating comma when one is already there.
+  const props = obj.properties as AnyNode[];
+  let sep = ' ';
+  if (props.length > 0) {
+    const lastEnd = props[props.length - 1].end as number;
+    const between = s.original.slice(lastEnd, (obj.end as number) - 1);
+    sep = /,/.test(between) ? ' ' : ', ';
+  }
   // The object's textual end is `obj.end - 1` for `}` after the chars.
   // appendLeft at obj.end -1 puts new text before the `}`.
-  s.appendLeft(obj.end - 1, `${sep}${jsKey(prop)}: ${value} `);
-  // Suppress unused-var lint without bypassing TS:
-  void tail;
+  s.appendLeft((obj.end as number) - 1, `${sep}${jsKey(prop)}: ${value} `);
 }
 
 /**