@1agh/maude 0.51.1 → 0.52.1

package/apps/studio/clip-ops.ts

@@ -0,0 +1,1980 @@
+// clip-ops.ts — composed timeline clip operations (feature-enhanced-video-editing).
+//
+// The verbs the iMovie-style editor speaks: each is a pure `applyX(source, …)
+// → { source', … }` built from the canvas-edit primitives + the Phase-0 ripple
+// engine, plus a disk wrapper (atomic write + cross-process lock). Lives in its
+// own module because ripple.ts already imports canvas-edit.ts — composing here
+// keeps the import graph acyclic.
+
+import MagicString from 'magic-string';
+import { parseSync } from 'oxc-parser';
+
+import {
+  applyRemoveClip,
+  assertCompSemantics,
+  CanvasEditError,
+  type ClipInfo,
+  enumerateClips,
+  escapeAttr,
+  lineStartInfo,
+  spanWithFraming,
+  withLock,
+} from './canvas-edit.ts';
+import { applyRippleAfterClip, collectConsts, resolveNum } from './ripple.ts';
+
+/** Parse a `<TransitionSeries.Transition>`'s duration out of its source span
+ *  (`timing={linearTiming({ durationInFrames: XF })}` — the attr the AST-level
+ *  numAttr can't see because it nests inside the timing call). */
+export function transitionDurationFrames(
+  source: string,
+  transition: ClipInfo,
+  consts?: Record<string, number>
+): number | null {
+  const text = source.slice(transition.start, transition.end);
+  const m = text.match(/durationInFrames:\s*([^,}\s)]+)/);
+  if (!m) return null;
+  return resolveNum(m[1] as string, consts ?? collectConsts(source));
+}
+
+/** The transition applyRemoveClip will drop alongside a series clip (its NEXT
+ *  transition, else its PREVIOUS — the same preference order). */
+function adjacentTransition(clips: ClipInfo[], idx: number): ClipInfo | null {
+  const next = clips[idx + 1];
+  const prev = clips[idx - 1];
+  if (next?.kind === 'transition') return next;
+  if (prev?.kind === 'transition') return prev;
+  return null;
+}
+
+/**
+ * Remove a clip WITH ripple (the iMovie Delete): a series beat's removal
+ * shrinks the comp TOTAL by (clip duration − the dropped transition's overlap)
+ * so the cut stays truthful; a standalone `<Sequence>` (overlay/audio band) is
+ * removed WITHOUT ripple — overlays are absolutely positioned by design and
+ * deleting one must not move the rest of the cut. Pure.
+ */
+export function applyRemoveClipRippled(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined
+): { source: string; rippled: boolean } {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const idx = clips.findIndex((c) => c.stableId === stableId);
+  const clip = idx >= 0 ? (clips[idx] as ClipInfo) : null;
+  let mid = source;
+  let rippled = false;
+  if (
+    clip &&
+    clip.kind === 'sequence' &&
+    (clip.tag.startsWith('TransitionSeries.') || clip.tag.startsWith('Series.')) &&
+    clip.durationInFrames != null
+  ) {
+    const t = adjacentTransition(clips, idx);
+    const overlap = t ? (transitionDurationFrames(source, t) ?? 0) : 0;
+    const delta = -(clip.durationInFrames - overlap);
+    if (delta !== 0) {
+      // TOTAL only — series siblings position themselves, and overlay-band
+      // standalone clips deliberately stay put on a storyline delete.
+      const r = applyRippleAfterClip(canvasAbsPath, mid, artboardId, stableId, delta, {
+        shiftFroms: false,
+      });
+      mid = r.source;
+      rippled = r.totalEdited;
+    }
+  }
+  // Ripple never touches the clip's own span text, so the caller's contentHash
+  // still fingerprints it — applyRemoveClip re-verifies on the rippled source.
+  const out = applyRemoveClip(canvasAbsPath, mid, artboardId, stableId, expectedHash);
+  return { source: out.source, rippled };
+}
+
+/** Remove-with-ripple on disk (atomic write + cross-process lock). */
+export async function removeClipRippled(
+  canvasAbsPath: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined
+): Promise<{ source: string; rippled: 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 = applyRemoveClipRippled(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;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Task 6 — magnetic storyline reorder (a real MOVE, not the ▲▼ adjacent swap).
+
+/** Resolve a clip by stableId + optional fingerprint (local mirror of
+ *  canvas-edit's resolveClip, against an already-enumerated list). */
+function mustResolve(
+  canvasAbsPath: string,
+  clips: ClipInfo[],
+  stableId: string,
+  expectedHash: string | undefined
+): { clip: ClipInfo; idx: number } {
+  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 }
+    );
+  }
+  return { clip, idx };
+}
+
+const isSeriesSeq = (c: ClipInfo) =>
+  c.kind === 'sequence' && (c.tag.startsWith('TransitionSeries.') || c.tag.startsWith('Series.'));
+
+/**
+ * Move a series beat before/after another beat — the drag-to-reorder commit.
+ * Cuts the beat plus ONE companion transition (its preceding one when it has
+ * one, else the following) and reinserts the pair at the target so the
+ * S/T/S/T alternation survives any distance: inserting BEFORE a beat emits
+ * `B T`, inserting AFTER emits `T B`. Pure; semantic-gated.
+ */
+export function applySeriesMove(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  movedStableId: string,
+  movedHash: string | undefined,
+  refStableId: string,
+  refHash: string | undefined,
+  position: 'before' | 'after'
+): { source: string; stableId: string } {
+  if (movedStableId === refStableId) {
+    throw new CanvasEditError('cannot move a clip relative to itself', {
+      canvas: canvasAbsPath,
+      id: movedStableId,
+    });
+  }
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip: moved, idx } = mustResolve(canvasAbsPath, clips, movedStableId, movedHash);
+  const { clip: ref } = mustResolve(canvasAbsPath, clips, refStableId, refHash);
+  if (!isSeriesSeq(moved) || !isSeriesSeq(ref)) {
+    throw new CanvasEditError('series move needs two series beats', {
+      canvas: canvasAbsPath,
+      id: movedStableId,
+    });
+  }
+  const prev = clips[idx - 1];
+  const next = clips[idx + 1];
+  const companion = prev?.kind === 'transition' ? prev : next?.kind === 'transition' ? next : null;
+
+  const movedSpan = spanWithFraming(source, moved.start, moved.end);
+  const companionSpan = companion ? spanWithFraming(source, companion.start, companion.end) : null;
+  const beatText = source.slice(movedSpan[0], movedSpan[1]);
+  const transitionText = companionSpan ? source.slice(companionSpan[0], companionSpan[1]) : '';
+
+  const s = new MagicString(source);
+  s.remove(movedSpan[0], movedSpan[1]);
+  if (companionSpan) s.remove(companionSpan[0], companionSpan[1]);
+  const insertText =
+    position === 'before' ? `${beatText}${transitionText}` : `${transitionText}${beatText}`;
+  if (position === 'before') {
+    const [rs] = spanWithFraming(source, ref.start, ref.end);
+    s.appendLeft(rs, insertText);
+  } else {
+    s.appendRight(ref.end, insertText);
+  }
+  const out = s.toString();
+  assertParses(canvasAbsPath, out, 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 };
+}
+
+/** Series move on disk (atomic write + cross-process lock). */
+export async function seriesMove(
+  canvasAbsPath: string,
+  artboardId: string | undefined,
+  movedStableId: string,
+  movedHash: string | undefined,
+  refStableId: string,
+  refHash: string | undefined,
+  position: 'before' | 'after'
+): Promise<{ source: string; stableId: string }> {
+  return withLock(canvasAbsPath, async () => {
+    const source = await Bun.file(canvasAbsPath).text();
+    const next = applySeriesMove(
+      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;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Task 6 — positional insert (the drop caret): storyline index-aware insert,
+// or a standalone overlay/audio clip that lands OUTSIDE the series.
+
+const INSERTABLE_MEDIA = new Set(['Video', 'Audio', 'Img', 'OffthreadVideo']);
+
+function assertContainedSrc(canvasAbsPath: string, src: string, id: string): void {
+  // Allowlist, not blocklist (security review 2026-07-30): the src the export
+  // renderer fetches must be a contained asset — a relative path or a `/`-rooted
+  // path under the design root — never a scheme (`javascript:`/`data:`/`http(s):`)
+  // and never a protocol-relative `//host/...` (which the blocklist let slip →
+  // SSRF residue in the server-side render). `/\...` (a single leading slash) is
+  // allowed; `//...` is not.
+  const t = src.trim();
+  const contained =
+    t.length > 0 &&
+    !/\.\./.test(t) &&
+    !/^[a-z][a-z0-9+.-]*:/i.test(t) && // any URI scheme
+    !t.startsWith('//'); // protocol-relative
+  if (!contained) {
+    throw new CanvasEditError(
+      'media src must be a contained asset path (no ../, schemes, or //host)',
+      {
+        canvas: canvasAbsPath,
+        id,
+      }
+    );
+  }
+}
+
+export interface InsertAtOptions {
+  lane: 'storyline' | 'overlay' | 'audio';
+  /** storyline only: beat position 0..N (N = append at the end). */
+  index?: number;
+  /** overlay/audio only: start frame. */
+  from?: number;
+  durationInFrames: number;
+  mediaTag?: string | null;
+  src?: string | null;
+  /** Task 22 — a prompt-carrying AI slate instead of media. Prompt is USER
+   *  TEXT → JSON.stringify into the JSX (DDR-150 P1). */
+  placeholder?: { prompt: string; kind: string } | null;
+}
+
+const PLACEHOLDER_KINDS = new Set(['veo', 'motion', 'image']);
+
+function placeholderChildText(
+  canvasAbsPath: string,
+  artboardId: string | undefined,
+  p: { prompt: string; kind: string },
+  indent: string,
+  dur: number
+): string {
+  const kind = PLACEHOLDER_KINDS.has(p.kind) ? p.kind : 'veo';
+  const prompt = String(p.prompt ?? '').slice(0, 2000);
+  if (!prompt.trim()) {
+    throw new CanvasEditError('an AI placeholder needs a prompt', {
+      canvas: canvasAbsPath,
+      id: artboardId ?? '',
+    });
+  }
+  // Paired-tag form: the prompt lives in a plain <span> child (a stamped,
+  // data-cd-editable leaf — double-click in the artboard edits it in place;
+  // the modal-prompt flow is gone). JSON.stringify keeps DDR-150 P1 discipline.
+  return (
+    `\n${indent}  <AIPlaceholder kind="${kind}" durationInFrames={${dur}}>` +
+    `\n${indent}    <span>{${JSON.stringify(prompt)}}</span>` +
+    `\n${indent}  </AIPlaceholder>\n${indent}`
+  );
+}
+
+/**
+ * Insert a clip at a POSITION (unlike canvas-edit's append-only insert):
+ *   • `lane: 'storyline'` inserts a series beat at `index`, cloning an existing
+ *     transition to keep the alternation (B T at the head, T B elsewhere) and
+ *     bumping the comp TOTAL by (duration − transition overlap);
+ *   • `lane: 'overlay' | 'audio'` inserts a standalone `<Sequence from>` as a
+ *     SIBLING after the series (never inside it), no TOTAL change.
+ * Pure; returns the new clip's stableId.
+ */
+export function applyInsertClipAt(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  opts: InsertAtOptions
+): { source: string; stableId: string | null } {
+  const cc = enumerateClips(canvasAbsPath, source, artboardId);
+  if (!cc.compName) {
+    // A `kind="video"` artboard without a comp is the user saying "this is a
+    // video" — upgrade it in place and retry, instead of refusing.
+    if (opts.lane === 'storyline') {
+      const ensured = applyEnsureVideoComp(canvasAbsPath, source, artboardId);
+      if (ensured) {
+        return applyInsertClipAt(canvasAbsPath, ensured.source, ensured.artboardId, opts);
+      }
+    }
+    throw new CanvasEditError(
+      'no video-comp for this artboard — set an artboard’s Kind to "Video" in the Inspector and drop again, or use ⌘K → New video…',
+      { canvas: canvasAbsPath, id: artboardId ?? '' }
+    );
+  }
+  const dur = Math.max(1, Math.round(opts.durationInFrames));
+  const srcTrim = (opts.src ?? '').trim();
+  const media =
+    opts.mediaTag && INSERTABLE_MEDIA.has(opts.mediaTag) && srcTrim
+      ? { tag: opts.mediaTag, src: srcTrim }
+      : null;
+  if (media) {
+    assertContainedSrc(canvasAbsPath, media.src, artboardId ?? '');
+    // House spelling: <OffthreadVideo> for video (frame-accurate export, and it
+    // can never collide with a canvas component named `Video` — the brief-board
+    // upgrade bug where the emitted tag resolved to the canvas itself).
+    if (media.tag === 'Video') media.tag = 'OffthreadVideo';
+  }
+
+  const seqs = cc.clips.filter((c) => c.kind === 'sequence');
+  const s = new MagicString(source);
+
+  if (opts.lane === 'storyline') {
+    const beats = seqs.filter(isSeriesSeq);
+    if (beats.length === 0) {
+      // Greenfield first drop (Task 20, default-container rule): author the
+      // <TransitionSeries> storyline around the first beat, inside the comp's
+      // root <AbsoluteFill>.
+      if (!media && !opts.placeholder) {
+        throw new CanvasEditError('the first storyline insert needs media', {
+          canvas: canvasAbsPath,
+          id: artboardId ?? '',
+        });
+      }
+      const bodyM = source.match(
+        new RegExp(`(?:const\\s+${cc.compName}\\s*=|function\\s+${cc.compName}\\b)`)
+      );
+      if (!bodyM || bodyM.index == null) {
+        throw new CanvasEditError(`could not locate component ${cc.compName}`, {
+          canvas: canvasAbsPath,
+          id: artboardId ?? '',
+        });
+      }
+      const rootClose = source.indexOf('</AbsoluteFill>', bodyM.index);
+      if (rootClose < 0) {
+        throw new CanvasEditError(
+          'greenfield insert needs a root <AbsoluteFill> in the comp — add one, then drop again',
+          { canvas: canvasAbsPath, id: artboardId ?? '' }
+        );
+      }
+      const indent = `${lineStartInfo(source, rootClose).indent}  `;
+      const s2 = new MagicString(source);
+      const gfChild = opts.placeholder
+        ? placeholderChildText(
+            canvasAbsPath,
+            artboardId,
+            opts.placeholder,
+            `${indent}  `,
+            dur
+          ).trimEnd()
+        : `\n${indent}    <${media.tag} src="${escapeAttr(media.src)}" />`;
+      s2.appendLeft(
+        rootClose,
+        `  <TransitionSeries>\n${indent}  <TransitionSeries.Sequence durationInFrames={${dur}}>` +
+          `${gfChild}\n` +
+          `${indent}  </TransitionSeries.Sequence>\n${indent}</TransitionSeries>\n${indent.slice(2)}`
+      );
+      ensureImportPublic(s2, source, 'TransitionSeries', '@remotion/transitions');
+      if (opts.placeholder) ensureNamedImport(s2, source, 'AIPlaceholder', '@maude/canvas-lib');
+      if (media) ensureNamedImport(s2, source, media.tag, 'remotion');
+      const out2 = s2.toString();
+      assertParses(canvasAbsPath, out2, artboardId ?? '');
+      assertCompSemantics(canvasAbsPath, out2);
+      const after2 = enumerateClips(canvasAbsPath, out2, artboardId);
+      const beat = after2.clips.find((c) => isSeriesSeq(c));
+      return { source: out2, stableId: beat?.stableId ?? null };
+    }
+    // A transition proto is cloned when the series has one; a series of hard
+    // cuts (no transitions — valid Remotion) inserts a bare beat.
+    const proto = cc.clips.find((c) => c.kind === 'transition') ?? null;
+    const protoOverlap = proto ? (transitionDurationFrames(source, proto) ?? 0) : 0;
+    const index = Math.max(0, Math.min(beats.length, Math.round(opts.index ?? beats.length)));
+    const seriesPrefix = (beats[0] as ClipInfo).tag.split('.')[0]; // TransitionSeries | Series
+    const anchor = (index === 0 ? beats[0] : beats[index - 1]) as ClipInfo;
+    const indent = lineStartInfo(source, anchor.start).indent;
+    const transitionText = proto ? `\n${indent}${source.slice(proto.start, proto.end)}` : '';
+    const mediaText = opts.placeholder
+      ? placeholderChildText(canvasAbsPath, artboardId, opts.placeholder, indent, dur)
+      : media
+        ? `\n${indent}  <${media.tag} src="${escapeAttr(media.src)}" />\n${indent}`
+        : '';
+    if (opts.placeholder) ensureNamedImport(s, source, 'AIPlaceholder', '@maude/canvas-lib');
+    if (media) ensureNamedImport(s, source, media.tag, 'remotion');
+    const beatText = `<${seriesPrefix}.Sequence durationInFrames={${dur}}>${mediaText}</${seriesPrefix}.Sequence>`;
+    if (index === 0) {
+      // Head insert: B (T) before the first beat.
+      const [rs] = spanWithFraming(source, anchor.start, anchor.end);
+      s.appendLeft(rs, `\n${indent}${beatText}${transitionText}`);
+    } else {
+      // Insert after the anchor beat: (T) B.
+      s.appendRight(anchor.end, `${transitionText}\n${indent}${beatText}`);
+    }
+    let out = s.toString();
+    assertParses(canvasAbsPath, out, artboardId ?? '');
+    assertCompSemantics(canvasAbsPath, out);
+    // The cut grew — bump the comp TOTAL (const-preferring) by dur − overlap.
+    const mid = enumerateClips(canvasAbsPath, out, artboardId);
+    const midBeats = mid.clips.filter((c) => c.kind === 'sequence' && isSeriesSeq(c));
+    const inserted = midBeats[index] as ClipInfo | undefined;
+    if (inserted && dur - protoOverlap !== 0) {
+      out = applyRippleAfterClip(
+        canvasAbsPath,
+        out,
+        artboardId,
+        inserted.stableId,
+        dur - protoOverlap,
+        {
+          shiftFroms: false,
+        }
+      ).source;
+    }
+    const after = enumerateClips(canvasAbsPath, out, artboardId);
+    const afterBeats = after.clips.filter((c) => c.kind === 'sequence' && isSeriesSeq(c));
+    return { source: out, stableId: (afterBeats[index] as ClipInfo | undefined)?.stableId ?? null };
+  }
+
+  // overlay / audio — a standalone <Sequence from> sibling, never inside the series.
+  const from = Math.max(0, Math.round(opts.from ?? 0));
+  const lastSeries = [...cc.clips].reverse().find((c) => isSeriesSeq(c) || c.kind === 'transition');
+  let insertAt: number;
+  let indent: string;
+  if (lastSeries) {
+    const closeTag = lastSeries.tag.startsWith('Series.') ? '</Series>' : '</TransitionSeries>';
+    const closeIdx = source.indexOf(closeTag, lastSeries.end);
+    if (closeIdx < 0) {
+      throw new CanvasEditError('could not locate the series close tag', {
+        canvas: canvasAbsPath,
+        id: artboardId ?? '',
+      });
+    }
+    insertAt = closeIdx + closeTag.length;
+    indent = lineStartInfo(source, closeIdx).indent;
+  } else {
+    const last = seqs[seqs.length - 1];
+    if (last) {
+      insertAt = last.end;
+      indent = lineStartInfo(source, last.start).indent;
+    } else {
+      // Empty comp (greenfield) — anchor inside the comp's root <AbsoluteFill>,
+      // exactly like the storyline greenfield insert.
+      const bodyM = source.match(
+        new RegExp(`(?:const\\s+${cc.compName}\\s*=|function\\s+${cc.compName}\\b)`)
+      );
+      const rootClose = bodyM ? source.indexOf('</AbsoluteFill>', bodyM.index) : -1;
+      if (rootClose < 0) {
+        throw new CanvasEditError(
+          'comp has no clip and no root <AbsoluteFill> to anchor the insert — drop onto the storyline instead',
+          { canvas: canvasAbsPath, id: artboardId ?? '' }
+        );
+      }
+      insertAt = rootClose;
+      indent = `${lineStartInfo(source, rootClose).indent}  `;
+    }
+  }
+  // Task 19 — "+ Title": a literal text block instead of a media child. The
+  // caption is USER TEXT → JSON.stringify (DDR-150 P1 quoted-string discipline).
+  const titleText =
+    opts.mediaTag === 'Title'
+      ? `\n${indent}  <AbsoluteFill style={{ display: 'grid', placeItems: 'center', pointerEvents: 'none' }}>` +
+        `\n${indent}    <div style={{ color: 'white', fontSize: 64, fontWeight: 700, textShadow: '0 2px 24px rgba(0,0,0,0.55)', pointerEvents: 'auto' }}>{${JSON.stringify(String(opts.src || 'Title'))}}</div>` +
+        `\n${indent}  </AbsoluteFill>\n${indent}`
+      : null;
+  const mediaText = opts.placeholder
+    ? placeholderChildText(canvasAbsPath, artboardId, opts.placeholder, indent, dur)
+    : titleText
+      ? titleText
+      : media
+        ? `\n${indent}  <${media.tag} src="${escapeAttr(media.src)}" />\n${indent}`
+        : '';
+  if (opts.placeholder) ensureNamedImport(s, source, 'AIPlaceholder', '@maude/canvas-lib');
+  if (media) ensureNamedImport(s, source, media.tag, 'remotion');
+  if (titleText) ensureNamedImport(s, source, 'AbsoluteFill', 'remotion');
+  ensureNamedImport(s, source, 'Sequence', 'remotion');
+  const clipText = `\n${indent}<Sequence from={${from}} durationInFrames={${dur}}>${mediaText}</Sequence>`;
+  s.appendRight(insertAt, clipText);
+  let out = s.toString();
+  try {
+    assertParses(canvasAbsPath, out, artboardId ?? '');
+  } catch {
+    // A comp whose body is the bare series (`() => (<TransitionSeries>…`)
+    // can't take a sibling — wrap series + new clip in a fragment.
+    if (!lastSeries)
+      throw new CanvasEditError('insert produced invalid source', {
+        canvas: canvasAbsPath,
+        id: artboardId ?? '',
+      });
+    // The container's OWN open tag — never a `<TransitionSeries.Sequence>`
+    // member tag (a bare lastIndexOf prefix-matched those).
+    const openRe = lastSeries.tag.startsWith('Series.')
+      ? /<Series(?![.\w])/g
+      : /<TransitionSeries(?![.\w])/g;
+    let openStart = -1;
+    for (const m of source.matchAll(openRe)) {
+      if ((m.index as number) < lastSeries.start) openStart = m.index as number;
+    }
+    if (openStart < 0) {
+      throw new CanvasEditError('insert produced invalid source', {
+        canvas: canvasAbsPath,
+        id: artboardId ?? '',
+      });
+    }
+    const s2 = new MagicString(source);
+    s2.appendLeft(openStart, '<>');
+    s2.appendRight(insertAt, `${clipText}\n${indent}</>`);
+    if (opts.placeholder) ensureNamedImport(s2, source, 'AIPlaceholder', '@maude/canvas-lib');
+    if (media) ensureNamedImport(s2, source, media.tag, 'remotion');
+    if (titleText) ensureNamedImport(s2, source, 'AbsoluteFill', 'remotion');
+    ensureNamedImport(s2, source, 'Sequence', 'remotion');
+    out = s2.toString();
+    assertParses(canvasAbsPath, out, artboardId ?? '');
+  }
+  assertCompSemantics(canvasAbsPath, out);
+  // A clip landing past the current comp end stretches the timeline to it.
+  out = applyFitTotalToContent(canvasAbsPath, out, artboardId).source;
+  const after = enumerateClips(canvasAbsPath, out, artboardId);
+  const standalone = after.clips.filter((c) => c.kind === 'sequence' && c.tag === 'Sequence');
+  return {
+    source: out,
+    stableId: (standalone[standalone.length - 1] as ClipInfo | undefined)?.stableId ?? null,
+  };
+}
+
+/** Positional insert on disk (atomic write + cross-process lock). */
+export async function insertClipAt(
+  canvasAbsPath: string,
+  artboardId: string | undefined,
+  opts: InsertAtOptions
+): 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 = applyInsertClipAt(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;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Phase 2 (Tasks 10–15) — parametric clip verbs. All text-surgical on ONE
+// opening tag (media element / clip tag / transition), reparse + semantic
+// gated, composed with the ripple engine for anything that changes length.
+
+/** End index (exclusive) of the opening tag starting at `tagStart` — brace-aware
+ *  so `style={{ … }}` doesn't fool the `>` scan. */
+function openTagEnd(source: string, tagStart: number): number {
+  let depth = 0;
+  for (let i = tagStart; i < source.length; i += 1) {
+    const ch = source[i];
+    if (ch === '{') depth += 1;
+    else if (ch === '}') depth -= 1;
+    else if (ch === '>' && depth <= 0) return i + 1;
+  }
+  return source.length;
+}
+
+/** Span of `name=<value>` (incl. leading space) inside the opening tag at
+ *  `tagStart`, brace-matching the value. Null when absent. */
+function attrSpanInTag(
+  source: string,
+  tagStart: number,
+  name: string
+): { start: number; end: number; valueText: string | null } | null {
+  const end = openTagEnd(source, tagStart);
+  const tag = source.slice(tagStart, end);
+  const re = new RegExp(`\\s${name}(?=[\\s/>=])`);
+  const m = tag.match(re);
+  if (!m || m.index == null) return null;
+  const attrStart = tagStart + m.index;
+  let i = attrStart + m[0].length;
+  if (source[i] !== '=') return { start: attrStart, end: i, valueText: null }; // bare attr
+  i += 1;
+  if (source[i] === '"' || source[i] === "'") {
+    const q = source[i];
+    const close = source.indexOf(q, i + 1);
+    const vEnd = close < 0 ? end : close + 1;
+    return { start: attrStart, end: vEnd, valueText: source.slice(i, vEnd) };
+  }
+  if (source[i] === '{') {
+    let depth = 0;
+    for (let k = i; k < end; k += 1) {
+      if (source[k] === '{') depth += 1;
+      else if (source[k] === '}') {
+        depth -= 1;
+        if (depth === 0) {
+          return { start: attrStart, end: k + 1, valueText: source.slice(i, k + 1) };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/** Set (`next` = full JSX value text like `{2}` or `"x"` or '' for bare) or
+ *  remove (`next` = null) an attribute on the opening tag at `tagStart`. */
+function setTagAttr(
+  s: MagicString,
+  source: string,
+  tagStart: number,
+  name: string,
+  next: string | null
+): void {
+  const existing = attrSpanInTag(source, tagStart, name);
+  if (next == null) {
+    if (existing) s.remove(existing.start, existing.end);
+    return;
+  }
+  const text = next === '' ? ` ${name}` : ` ${name}=${next}`;
+  if (existing) {
+    s.overwrite(existing.start, existing.end, text);
+  } else {
+    const nameM = source.slice(tagStart).match(/^<[A-Za-z][\w.]*/);
+    if (!nameM) return;
+    s.appendLeft(tagStart + nameM[0].length, text);
+  }
+}
+
+/** The clip's DIRECT media element open-tag start, or null (wrapper/array-fed
+ *  media is refused by the callers — editing a shared component would leak). */
+function directMediaTagStart(
+  source: string,
+  clip: ClipInfo,
+  tags = ['Video', 'OffthreadVideo', 'Audio', 'Img']
+): number | null {
+  const span = source.slice(clip.start, clip.end);
+  const m = span.match(new RegExp(`<(${tags.join('|')})\\b`));
+  if (!m || m.index == null) return null;
+  return clip.start + m.index;
+}
+
+function numAttrText(source: string, tagStart: number, name: string): number | null {
+  const a = attrSpanInTag(source, tagStart, name);
+  if (!a?.valueText) return null;
+  const inner = a.valueText.replace(/^\{|\}$/g, '').trim();
+  return resolveNum(inner, collectConsts(source));
+}
+
+/** Overwrite a clip tag's durationInFrames with a literal (a shared const must
+ *  not absorb a per-clip change). Throws when the attr is missing. */
+function setClipDurationLiteral(
+  s: MagicString,
+  source: string,
+  canvasAbsPath: string,
+  clip: ClipInfo,
+  frames: number
+): void {
+  const a = attrSpanInTag(source, clip.start, 'durationInFrames');
+  if (!a) {
+    throw new CanvasEditError(`clip "${clip.stableId}" has no durationInFrames to rewrite`, {
+      canvas: canvasAbsPath,
+      id: clip.stableId,
+    });
+  }
+  s.overwrite(a.start, a.end, ` durationInFrames={${Math.max(1, Math.round(frames))}}`);
+}
+
+interface SpeedResult {
+  source: string;
+  rate: number;
+  newDuration: number | null;
+}
+
+/**
+ * Task 10 — set/remove a clip's playback speed. Writes `playbackRate` on the
+ * clip's DIRECT media element, recomputes the clip's `durationInFrames`
+ * (source frames consumed stay constant: d1 = d0 × r0 / r1), and ripples the
+ * length delta (downstream `from`s + TOTAL). `rate === 1` removes the attr.
+ */
+export function applySetPlaybackRate(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined,
+  rate: number
+): SpeedResult {
+  if (!(rate > 0.01 && rate <= 16)) {
+    throw new CanvasEditError('playbackRate must be between 0.01 and 16', {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip } = mustResolve(canvasAbsPath, clips, stableId, expectedHash);
+  const mediaStart = directMediaTagStart(source, clip, ['Video', 'OffthreadVideo', 'Audio']);
+  if (mediaStart == null) {
+    throw new CanvasEditError(
+      `clip "${stableId}" has no direct media element — speed applies to <Video>/<Audio> clips (shared/wrapper media would change every user)`,
+      { canvas: canvasAbsPath, id: stableId }
+    );
+  }
+  const oldRate = numAttrText(source, mediaStart, 'playbackRate') ?? 1;
+  const oldDur = clip.durationInFrames;
+  const s = new MagicString(source);
+  setTagAttr(s, source, mediaStart, 'playbackRate', rate === 1 ? null : `{${rate}}`);
+  let newDur: number | null = null;
+  if (oldDur != null) {
+    newDur = Math.max(1, Math.round((oldDur * oldRate) / rate));
+    setClipDurationLiteral(s, source, canvasAbsPath, clip, newDur);
+  }
+  let out = s.toString();
+  assertParses(canvasAbsPath, out, stableId);
+  assertCompSemantics(canvasAbsPath, out);
+  if (oldDur != null && newDur != null && newDur !== oldDur) {
+    out = applyRippleAfterClip(canvasAbsPath, out, artboardId, stableId, newDur - oldDur).source;
+  }
+  return { source: out, rate, newDuration: newDur };
+}
+
+/**
+ * Task 11 — in-point trim (the left-edge drag). `deltaFrames > 0` trims INTO
+ * the clip (later in-point, shorter clip); negative restores. Writes
+ * `trimBefore` on the media element (reads legacy `startFrom` too), shortens
+ * the clip, moves a standalone clip's `from` (the left edge follows), and
+ * ripples downstream.
+ */
+export function applyTrimIn(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined,
+  deltaFrames: number
+): { source: string; trimBefore: number; newDuration: number } {
+  const delta = Math.round(deltaFrames);
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip } = mustResolve(canvasAbsPath, clips, stableId, expectedHash);
+  const mediaStart = directMediaTagStart(source, clip, ['Video', 'OffthreadVideo', 'Audio']);
+  if (mediaStart == null) {
+    throw new CanvasEditError(
+      `clip "${stableId}" has no direct media element — in-point trim applies to media clips`,
+      { canvas: canvasAbsPath, id: stableId }
+    );
+  }
+  const oldDur = clip.durationInFrames;
+  if (oldDur == null) {
+    throw new CanvasEditError(`clip "${stableId}" has no resolvable durationInFrames`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const rate = numAttrText(source, mediaStart, 'playbackRate') ?? 1;
+  const oldTrim =
+    numAttrText(source, mediaStart, 'trimBefore') ??
+    numAttrText(source, mediaStart, 'startFrom') ??
+    0;
+  const newTrim = Math.max(0, Math.round(oldTrim + delta * rate));
+  const effDelta = Math.round((newTrim - oldTrim) / rate); // clamped at trim 0
+  const newDur = oldDur - effDelta;
+  if (newDur < 1) {
+    throw new CanvasEditError('trim would leave the clip shorter than 1 frame', {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const s = new MagicString(source);
+  setTagAttr(s, source, mediaStart, 'trimBefore', newTrim === 0 ? null : `{${newTrim}}`);
+  // Emit trimBefore, retire the legacy spelling if present.
+  if (attrSpanInTag(source, mediaStart, 'startFrom')) {
+    setTagAttr(s, source, mediaStart, 'startFrom', null);
+  }
+  setClipDurationLiteral(s, source, canvasAbsPath, clip, newDur);
+  if (clip.tag === 'Sequence' && clip.from != null) {
+    const a = attrSpanInTag(source, clip.start, 'from');
+    if (a) s.overwrite(a.start, a.end, ` from={${Math.max(0, clip.from + effDelta)}}`);
+  }
+  let out = s.toString();
+  assertParses(canvasAbsPath, out, stableId);
+  assertCompSemantics(canvasAbsPath, out);
+  if (effDelta !== 0) {
+    out = applyRippleAfterClip(canvasAbsPath, out, artboardId, stableId, -effDelta).source;
+  }
+  return { source: out, trimBefore: newTrim, newDuration: newDur };
+}
+
+/**
+ * Task 12 — per-clip audio: mute toggle + constant volume on the clip's direct
+ * media element. `muted: true` writes the bare attr; `volume` writes
+ * `volume={n}` (0–1); null/1 removes it.
+ */
+export function applyClipAudio(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined,
+  opts: { muted?: boolean; volume?: number | null }
+): { source: string } {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip } = mustResolve(canvasAbsPath, clips, stableId, expectedHash);
+  const mediaStart = directMediaTagStart(source, clip, ['Video', 'OffthreadVideo', 'Audio']);
+  if (mediaStart == null) {
+    throw new CanvasEditError(`clip "${stableId}" has no direct media element to set audio on`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const s = new MagicString(source);
+  if (opts.muted != null) setTagAttr(s, source, mediaStart, 'muted', opts.muted ? '' : null);
+  if (opts.volume !== undefined) {
+    const v = opts.volume;
+    if (v != null && !(v >= 0 && v <= 1)) {
+      throw new CanvasEditError('volume must be between 0 and 1', {
+        canvas: canvasAbsPath,
+        id: stableId,
+      });
+    }
+    setTagAttr(s, source, mediaStart, 'volume', v == null || v === 1 ? null : `{${v}}`);
+  }
+  const out = s.toString();
+  assertParses(canvasAbsPath, out, stableId);
+  assertCompSemantics(canvasAbsPath, out);
+  return { source: out };
+}
+
+/**
+ * Task 12 — detach audio: mute the video clip AND add an audio-band
+ * `<Sequence from><Audio src={same} trimBefore={same} playbackRate={same}>`
+ * (same file, two elements, zero preprocessing).
+ */
+export function applyDetachAudio(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined
+): { source: string; audioStableId: string | null } {
+  const cc = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip } = mustResolve(canvasAbsPath, cc.clips, stableId, expectedHash);
+  const mediaStart = directMediaTagStart(source, clip, ['Video', 'OffthreadVideo']);
+  if (mediaStart == null || !clip.mediaSrc) {
+    throw new CanvasEditError(
+      `clip "${stableId}" has no direct video media with a literal src to detach`,
+      { canvas: canvasAbsPath, id: stableId }
+    );
+  }
+  if (clip.durationInFrames == null) {
+    throw new CanvasEditError(`clip "${stableId}" has no resolvable duration`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const trim = numAttrText(source, mediaStart, 'trimBefore') ?? 0;
+  const rate = numAttrText(source, mediaStart, 'playbackRate') ?? 1;
+  // Mute the video in place…
+  const s = new MagicString(source);
+  setTagAttr(s, source, mediaStart, 'muted', '');
+  const muted = s.toString();
+  // …then insert the audio clip at the clip's absolute start.
+  const startFrame = clipAbsoluteStart(muted, canvasAbsPath, artboardId, stableId);
+  const inserted = applyInsertClipAt(canvasAbsPath, muted, artboardId, {
+    lane: 'audio',
+    from: startFrame,
+    durationInFrames: clip.durationInFrames,
+    mediaTag: 'Audio',
+    src: clip.mediaSrc,
+  });
+  // applyInsertClipAt writes a plain `<Audio src>`; graft trim/rate onto it.
+  let out = inserted.source;
+  if (trim || rate !== 1) {
+    const after = enumerateClips(canvasAbsPath, out, artboardId);
+    const audioClip = after.clips.find((c) => c.stableId === inserted.stableId);
+    const audioMedia = audioClip ? directMediaTagStart(out, audioClip, ['Audio']) : null;
+    if (audioMedia != null) {
+      const s2 = new MagicString(out);
+      if (trim) setTagAttr(s2, out, audioMedia, 'trimBefore', `{${trim}}`);
+      if (rate !== 1) setTagAttr(s2, out, audioMedia, 'playbackRate', `{${rate}}`);
+      out = s2.toString();
+      assertParses(canvasAbsPath, out, stableId);
+    }
+  }
+  assertCompSemantics(canvasAbsPath, out);
+  return { source: out, audioStableId: inserted.stableId };
+}
+
+/** Absolute start frame of a clip: explicit `from`, or the series cursor walk
+ *  (sum of prior beat durations minus transition overlaps). */
+export function clipAbsoluteStart(
+  source: string,
+  canvasAbsPath: string,
+  artboardId: string | undefined,
+  stableId: string
+): number {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const consts = collectConsts(source);
+  let cursor = 0;
+  for (const c of clips) {
+    if (c.kind === 'transition') {
+      cursor -= transitionDurationFrames(source, c, consts) ?? 0;
+      continue;
+    }
+    const start = c.tag === 'Sequence' && c.from != null ? c.from : cursor;
+    if (c.stableId === stableId) return Math.max(0, Math.round(start));
+    cursor = start + (c.durationInFrames ?? 0);
+  }
+  return 0;
+}
+
+/** Task 14 — grade parameter vocabulary (the PhotoEdit subset that compiles to
+ *  a CSS filter chain — deterministic in Player + both export paths). */
+export interface GradeParams {
+  brightness?: number; // 1 = neutral
+  contrast?: number; // 1 = neutral
+  saturation?: number; // 1 = neutral
+  hue?: number; // deg, 0 = neutral
+  sepia?: number; // 0 = neutral
+  grayscale?: number; // 0 = neutral
+  invert?: number; // 0 = neutral
+}
+
+export function gradeToFilter(p: GradeParams): string {
+  const parts: string[] = [];
+  const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+  const b = num(p.brightness);
+  if (b != null && b !== 1) parts.push(`brightness(${b})`);
+  const c = num(p.contrast);
+  if (c != null && c !== 1) parts.push(`contrast(${c})`);
+  const s = num(p.saturation);
+  if (s != null && s !== 1) parts.push(`saturate(${s})`);
+  const h = num(p.hue);
+  if (h != null && h !== 0) parts.push(`hue-rotate(${h}deg)`);
+  const se = num(p.sepia);
+  if (se != null && se !== 0) parts.push(`sepia(${se})`);
+  const g = num(p.grayscale);
+  if (g != null && g !== 0) parts.push(`grayscale(${g})`);
+  const i = num(p.invert);
+  if (i != null && i !== 0) parts.push(`invert(${i})`);
+  return parts.join(' ');
+}
+
+/** Round-trip: parse a filter chain back to params. Unrecognized functions →
+ *  null (the UI shows a read-only badge instead of clobbering hand-written CSS). */
+export function filterToGrade(filter: string): GradeParams | null {
+  const out: GradeParams = {};
+  let rest = String(filter).trim();
+  const fnRe = /^([a-z-]+)\(([^)]*)\)\s*/;
+  while (rest.length) {
+    const m = rest.match(fnRe);
+    if (!m) return null;
+    const val = Number.parseFloat(m[2] as string);
+    if (!Number.isFinite(val)) return null;
+    switch (m[1]) {
+      case 'brightness':
+        out.brightness = val;
+        break;
+      case 'contrast':
+        out.contrast = val;
+        break;
+      case 'saturate':
+        out.saturation = val;
+        break;
+      case 'hue-rotate':
+        out.hue = val;
+        break;
+      case 'sepia':
+        out.sepia = val;
+        break;
+      case 'grayscale':
+        out.grayscale = val;
+        break;
+      case 'invert':
+        out.invert = val;
+        break;
+      default:
+        return null;
+    }
+    rest = rest.slice(m[0].length);
+  }
+  return out;
+}
+
+/**
+ * Task 14 — set/clear a clip's color grade: ONE CSS `filter` string on the
+ * media element's `style` (literal object only). `params === null` clears it.
+ */
+export function applyClipGrade(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined,
+  params: GradeParams | null
+): { source: string; filter: string } {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip } = mustResolve(canvasAbsPath, clips, stableId, expectedHash);
+  const mediaStart = directMediaTagStart(source, clip, ['Video', 'OffthreadVideo', 'Img']);
+  if (mediaStart == null) {
+    throw new CanvasEditError(`clip "${stableId}" has no direct media element to grade`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const filter = params ? gradeToFilter(params) : '';
+  const styleAttr = attrSpanInTag(source, mediaStart, 'style');
+  const s = new MagicString(source);
+  if (!styleAttr) {
+    if (filter) setTagAttr(s, source, mediaStart, 'style', `{{ filter: '${filter}' }}`);
+  } else {
+    const v = styleAttr.valueText ?? '';
+    if (!v.startsWith('{{')) {
+      throw new CanvasEditError(
+        `clip "${stableId}"'s media style is not a literal object — edit it by hand`,
+        { canvas: canvasAbsPath, id: stableId }
+      );
+    }
+    const filterProp = v.match(/(['"]?)filter\1\s*:\s*(['"])((?:\\.|(?!\2).)*)\2\s*,?\s*/);
+    if (filterProp && filterProp.index != null) {
+      const abs = styleAttr.start + (styleAttr.end - styleAttr.start - v.length) + filterProp.index;
+      if (filter) {
+        s.overwrite(
+          abs,
+          abs + filterProp[0].length,
+          `filter: '${filter}'${filterProp[0].trimEnd().endsWith(',') ? ', ' : ' '}`
+        );
+      } else {
+        s.remove(abs, abs + filterProp[0].length);
+      }
+    } else if (filter) {
+      const openIdx = styleAttr.end - v.length + 2; // after `{{`
+      s.appendLeft(openIdx, ` filter: '${filter}',`);
+    }
+  }
+  const out = s.toString();
+  assertParses(canvasAbsPath, out, stableId);
+  assertCompSemantics(canvasAbsPath, out);
+  return { source: out, filter };
+}
+
+/**
+ * Task 13 — crop/reposition: an idempotent framing wrapper around the media
+ * element (`overflow:hidden` outer + scaled/translated inner), marked with
+ * `data-mframe` for lossless round-trip. `framing === null` unwraps.
+ */
+export function applyClipFraming(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined,
+  framing: { scale: number; x: number; y: number } | null
+): { source: string } {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip } = mustResolve(canvasAbsPath, clips, stableId, expectedHash);
+  const mediaStart = directMediaTagStart(source, clip, ['Video', 'OffthreadVideo', 'Img']);
+  if (mediaStart == null) {
+    throw new CanvasEditError(`clip "${stableId}" has no direct media element to frame`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  // Existing wrapper? (marker on the OUTER div, inside this clip's span)
+  const span = source.slice(clip.start, clip.end);
+  const marker = span.match(/<div data-mframe="[^"]*"[^>]*>/);
+  const s = new MagicString(source);
+  if (marker && marker.index != null) {
+    const outerStart = clip.start + marker.index;
+    // The wrapper is exactly: <div data-mframe …><div …>MEDIA</div></div>
+    const outerEnd = matchTagEnd(source, outerStart);
+    if (outerEnd == null) {
+      throw new CanvasEditError('framing wrapper is malformed — fix the JSX by hand', {
+        canvas: canvasAbsPath,
+        id: stableId,
+      });
+    }
+    const inner = source.slice(outerStart, outerEnd);
+    const mediaM = inner.match(/<(?:Video|OffthreadVideo|Img)\b[\s\S]*?\/>/);
+    if (!mediaM || mediaM.index == null) {
+      throw new CanvasEditError('framing wrapper holds no media — fix the JSX by hand', {
+        canvas: canvasAbsPath,
+        id: stableId,
+      });
+    }
+    const mediaText = mediaM[0];
+    if (framing == null) {
+      s.overwrite(outerStart, outerEnd, mediaText);
+    } else {
+      s.overwrite(outerStart, outerEnd, framingWrapper(mediaText, framing));
+    }
+  } else if (framing != null) {
+    const mEnd = matchSelfClosing(source, mediaStart);
+    if (mEnd == null) {
+      throw new CanvasEditError(
+        'framing needs a self-closing media element (`<Video … />`) — adjust the JSX',
+        { canvas: canvasAbsPath, id: stableId }
+      );
+    }
+    s.overwrite(mediaStart, mEnd, framingWrapper(source.slice(mediaStart, mEnd), framing));
+  }
+  const out = s.toString();
+  assertParses(canvasAbsPath, out, stableId);
+  assertCompSemantics(canvasAbsPath, out);
+  return { source: out };
+}
+
+function framingWrapper(mediaText: string, f: { scale: number; x: number; y: number }): string {
+  const scale = Math.max(1, Math.min(8, f.scale || 1));
+  const x = Math.max(-100, Math.min(100, f.x || 0));
+  const y = Math.max(-100, Math.min(100, f.y || 0));
+  return (
+    `<div data-mframe="${scale},${x},${y}" style={{ overflow: 'hidden', width: '100%', height: '100%' }}>` +
+    `<div style={{ width: '100%', height: '100%', transform: 'scale(${scale}) translate(${x}%, ${y}%)' }}>` +
+    mediaText +
+    `</div></div>`
+  );
+}
+
+/** End index (exclusive) of the `<div …>…</div>` element starting at `start`
+ *  (depth-counted on <div/</div> only — the wrapper contains no other divs
+ *  except its own inner). */
+function matchTagEnd(source: string, start: number): number | null {
+  const re = /<div\b|<\/div>/g;
+  re.lastIndex = start;
+  let depth = 0;
+  let m: RegExpExecArray | null = re.exec(source);
+  while (m) {
+    if (m[0] === '<div') depth += 1;
+    else {
+      depth -= 1;
+      if (depth === 0) return m.index + m[0].length;
+    }
+    m = re.exec(source);
+  }
+  return null;
+}
+
+/** End (exclusive) of a self-closing tag starting at `start`, or null. */
+function matchSelfClosing(source: string, start: number): number | null {
+  const end = openTagEnd(source, start);
+  return source.slice(end - 2, end) === '/>' ? end : null;
+}
+
+// Task 15 / 17 — the 6 bundled transition presentations.
+const PRESENTATIONS: Record<string, { factory: string; specifier: string; importName: string }> = {
+  fade: { factory: 'fade()', specifier: '@remotion/transitions/fade', importName: 'fade' },
+  slide: { factory: 'slide()', specifier: '@remotion/transitions/slide', importName: 'slide' },
+  wipe: { factory: 'wipe()', specifier: '@remotion/transitions/wipe', importName: 'wipe' },
+  flip: { factory: 'flip()', specifier: '@remotion/transitions/flip', importName: 'flip' },
+  'clock-wipe': {
+    factory: 'clockWipe({ width: 1920, height: 1080 })',
+    specifier: '@remotion/transitions/clock-wipe',
+    importName: 'clockWipe',
+  },
+  none: { factory: 'none()', specifier: '@remotion/transitions/none', importName: 'none' },
+};
+
+export const PRESENTATION_KEYS = Object.keys(PRESENTATIONS);
+
+/** Ensure `import { name } from 'specifier';` exists (inserted after the last
+ *  import when absent). */
+function ensureImport(s: MagicString, source: string, importName: string, specifier: string): void {
+  if (new RegExp(`from ['"]${specifier.replace(/[/]/g, '\\/')}['"]`).test(source)) return;
+  const imports = [...source.matchAll(/^import [^\n]*\n/gm)];
+  const last = imports[imports.length - 1];
+  const at = last ? (last.index as number) + last[0].length : 0;
+  s.appendLeft(at, `import { ${importName} } from '${specifier}';\n`);
+}
+
+/**
+ * Task 15 — edit an existing seam: presentation (among the 6 bundled) and/or
+ * duration (TOTAL-rippled). The transition is addressed by ITS stableId from
+ * the enumerator.
+ */
+export function applyEditTransition(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  transitionId: string,
+  expectedHash: string | undefined,
+  opts: { presentation?: string; durationInFrames?: number }
+): { source: string } {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip: t } = mustResolve(canvasAbsPath, clips, transitionId, expectedHash);
+  if (t.kind !== 'transition') {
+    throw new CanvasEditError(`"${transitionId}" is not a transition`, {
+      canvas: canvasAbsPath,
+      id: transitionId,
+    });
+  }
+  const s = new MagicString(source);
+  if (opts.presentation != null) {
+    const p = PRESENTATIONS[opts.presentation];
+    if (!p) {
+      throw new CanvasEditError(
+        `unknown presentation "${opts.presentation}" — one of: ${PRESENTATION_KEYS.join(', ')}`,
+        { canvas: canvasAbsPath, id: transitionId }
+      );
+    }
+    const attr = attrSpanInTag(source, t.start, 'presentation');
+    if (!attr) {
+      throw new CanvasEditError('transition has no presentation attr to rewrite', {
+        canvas: canvasAbsPath,
+        id: transitionId,
+      });
+    }
+    // clockWipe sizes itself to the comp when we can read it.
+    let factory = p.factory;
+    if (opts.presentation === 'clock-wipe') {
+      const wh = compDimensions(source);
+      if (wh) factory = `clockWipe({ width: ${wh.width}, height: ${wh.height} })`;
+    }
+    s.overwrite(attr.start, attr.end, ` presentation={${factory}}`);
+    ensureImport(s, source, p.importName, p.specifier);
+  }
+  let out: string;
+  let delta = 0;
+  if (opts.durationInFrames != null) {
+    const next = Math.max(1, Math.round(opts.durationInFrames));
+    const span = source.slice(t.start, t.end);
+    const m = span.match(/durationInFrames:\s*([^,}\s)]+)/);
+    if (!m || m.index == null) {
+      throw new CanvasEditError('transition has no timing durationInFrames to rewrite', {
+        canvas: canvasAbsPath,
+        id: transitionId,
+      });
+    }
+    const old = resolveNum(m[1] as string, collectConsts(source));
+    const valStart = t.start + m.index + m[0].indexOf(m[1] as string);
+    s.overwrite(valStart, valStart + (m[1] as string).length, String(next));
+    if (old != null) delta = -(next - old); // longer overlap ⇒ SHORTER comp
+    out = s.toString();
+  } else {
+    out = s.toString();
+  }
+  assertParses(canvasAbsPath, out, transitionId);
+  assertCompSemantics(canvasAbsPath, out);
+  if (delta !== 0) {
+    out = applyRippleAfterClip(canvasAbsPath, out, artboardId, transitionId, delta, {
+      shiftFroms: false,
+    }).source;
+  }
+  return { source: out };
+}
+
+/** The comp's VideoComp width/height (for clockWipe), when resolvable. */
+function compDimensions(source: string): { width: number; height: number } | null {
+  const m = source.match(/<VideoComp\b[^>]*>/);
+  if (!m || m.index == null) return null;
+  const w = numAttrText(source, m.index, 'width');
+  const h = numAttrText(source, m.index, 'height');
+  return w && h ? { width: w, height: h } : null;
+}
+
+// ---------------------------------------------------------------------------
+// Phase 3 — structural ops: split at playhead, transition insert/remove.
+
+/** Rewrite/insert/remove an attr on the FIRST tag of a detached text fragment. */
+function textWithAttr(text: string, name: string, next: string | null): string {
+  const s = new MagicString(text);
+  setTagAttr(s, text, 0, name, next);
+  return s.toString();
+}
+
+/** Rewrite an attr on the first MEDIA tag inside a detached clip text. */
+function textWithMediaAttr(text: string, name: string, next: string | null): string {
+  const m = text.match(/<(?:Video|OffthreadVideo|Audio|Img)\b/);
+  if (!m || m.index == null) return text;
+  const s = new MagicString(text);
+  setTagAttr(s, text, m.index, name, next);
+  return s.toString();
+}
+
+/**
+ * Task 16 — split a clip at an absolute comp frame. Two literal halves: the
+ * first keeps the in-point and takes `offset` frames; the second starts at the
+ * cut (`trimBefore += offset × rate`) and takes the remainder. Both inherit
+ * every other attr (grade, crop wrapper, audio props ride along verbatim).
+ *
+ * Scope fence (DDR-150 deferral): standalone `<Sequence>` clips, and series
+ * beats NOT adjacent to a transition — at a seam the overlap math makes the
+ * halves lie, so the engine refuses with guidance instead.
+ */
+export function applySplitClip(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined,
+  atFrame: number
+): { source: string; firstStableId: string | null; secondStableId: string | null } {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip, idx } = mustResolve(canvasAbsPath, clips, stableId, expectedHash);
+  if (clip.kind !== 'sequence') {
+    throw new CanvasEditError(`"${stableId}" is a transition, not a splittable clip`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  if (isSeriesSeq(clip)) {
+    const prev = clips[idx - 1];
+    const next = clips[idx + 1];
+    if (prev?.kind === 'transition' || next?.kind === 'transition') {
+      throw new CanvasEditError(
+        'this beat touches a transition — remove the transition first (or move the clip out of it), then split',
+        { canvas: canvasAbsPath, id: stableId }
+      );
+    }
+  }
+  const dur = clip.durationInFrames;
+  if (dur == null) {
+    throw new CanvasEditError(`clip "${stableId}" has no resolvable durationInFrames`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const start = clipAbsoluteStart(source, canvasAbsPath, artboardId, stableId);
+  const offset = Math.round(atFrame - start);
+  if (offset < 1 || offset > dur - 1) {
+    throw new CanvasEditError(
+      `split point is ${offset <= 0 ? 'at/before the clip start' : 'at/after the clip end'} — scrub inside the clip first`,
+      { canvas: canvasAbsPath, id: stableId }
+    );
+  }
+  const clipText = source.slice(clip.start, clip.end);
+  const mediaM = clipText.match(/<(?:Video|OffthreadVideo|Audio|Img)\b/);
+  const rate = mediaM ? (numAttrText(clipText, mediaM.index as number, 'playbackRate') ?? 1) : 1;
+  const oldTrim = mediaM
+    ? (numAttrText(clipText, mediaM.index as number, 'trimBefore') ??
+      numAttrText(clipText, mediaM.index as number, 'startFrom') ??
+      0)
+    : 0;
+  const nameM = clipText.match(/^<[A-Za-z][\w.]*\s[^>]*?name="([^"]*)"/);
+
+  // First half — duration only.
+  const first = textWithAttr(clipText, 'durationInFrames', `{${offset}}`);
+  // Second half — remainder + shifted in-point (+ shifted `from` when standalone).
+  let second = textWithAttr(clipText, 'durationInFrames', `{${dur - offset}}`);
+  if (mediaM) {
+    const newTrim = Math.round(oldTrim + offset * rate);
+    second = textWithMediaAttr(second, 'startFrom', null);
+    second = textWithMediaAttr(second, 'trimBefore', newTrim === 0 ? null : `{${newTrim}}`);
+  }
+  if (clip.tag === 'Sequence' && clip.from != null) {
+    second = textWithAttr(second, 'from', `{${clip.from + offset}}`);
+  }
+  if (nameM) {
+    // Duplicate names would collide the stableId — suffix the second half.
+    second = second.replace(`name="${nameM[1]}"`, `name="${nameM[1]}-${atFrame}"`);
+  }
+  const indent = lineStartInfo(source, clip.start).indent;
+  const s = new MagicString(source);
+  s.overwrite(clip.start, clip.end, `${first}\n${indent}${second}`);
+  const out = s.toString();
+  assertParses(canvasAbsPath, out, stableId);
+  assertCompSemantics(canvasAbsPath, out);
+  // No ripple: the halves sum to the original (a hard cut between them).
+  const after = enumerateClips(canvasAbsPath, out, artboardId);
+  const seqIdxBefore = clips.slice(0, idx).filter((c) => c.kind === 'sequence').length;
+  const seqs = after.clips.filter((c) => c.kind === 'sequence');
+  return {
+    source: out,
+    firstStableId: seqs[seqIdxBefore]?.stableId ?? null,
+    secondStableId: seqs[seqIdxBefore + 1]?.stableId ?? null,
+  };
+}
+
+/** Ensure `name` is among the named imports from `specifier` (extends an
+ *  existing import line, else adds one after the last import). */
+function ensureNamedImport(s: MagicString, source: string, name: string, specifier: string): void {
+  const esc = specifier.replace(/[/]/g, '\\/');
+  const line = source.match(new RegExp(`import \\{([^}]*)\\} from ['"]${esc}['"]`));
+  if (line && line.index != null) {
+    if (new RegExp(`\\b${name}\\b`).test(line[1] as string)) return;
+    const braceOpen = line.index + (line[0] as string).indexOf('{') + 1;
+    s.appendLeft(braceOpen, ` ${name},`);
+    return;
+  }
+  const imports = [...source.matchAll(/^import [^\n]*\n/gm)];
+  const last = imports[imports.length - 1];
+  const at = last ? (last.index as number) + last[0].length : 0;
+  s.appendLeft(at, `import { ${name} } from '${specifier}';\n`);
+}
+
+/**
+ * Task 17 — insert a transition into a hard cut AFTER `afterStableId` (a
+ * series beat whose next sibling is another beat). TOTAL shrinks by the new
+ * overlap (ripple). Refuses standalone pairs and already-transitioned seams.
+ */
+export function applyInsertTransition(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  afterStableId: string,
+  expectedHash: string | undefined,
+  presentation: string,
+  frames: number
+): { source: string; transitionStableId: string | null } {
+  const p = PRESENTATIONS[presentation];
+  if (!p) {
+    throw new CanvasEditError(
+      `unknown presentation "${presentation}" — one of: ${PRESENTATION_KEYS.join(', ')}`,
+      { canvas: canvasAbsPath, id: afterStableId }
+    );
+  }
+  const dur = Math.max(1, Math.round(frames));
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip, idx } = mustResolve(canvasAbsPath, clips, afterStableId, expectedHash);
+  if (!isSeriesSeq(clip)) {
+    throw new CanvasEditError(
+      'transitions live between series beats — standalone clips take a hard cut (convert to a series first)',
+      { canvas: canvasAbsPath, id: afterStableId }
+    );
+  }
+  const next = clips[idx + 1];
+  if (!next || !isSeriesSeq(next)) {
+    throw new CanvasEditError(
+      next?.kind === 'transition'
+        ? 'this seam already has a transition — click its ⧓ chip to edit it'
+        : 'no following beat — a transition needs a clip on both sides',
+      { canvas: canvasAbsPath, id: afterStableId }
+    );
+  }
+  let factory = p.factory;
+  if (presentation === 'clock-wipe') {
+    const wh = compDimensionsPublic(source);
+    if (wh) factory = `clockWipe({ width: ${wh.width}, height: ${wh.height} })`;
+  }
+  const indent = lineStartInfo(source, clip.start).indent;
+  const s = new MagicString(source);
+  s.appendRight(
+    clip.end,
+    `\n${indent}<${clip.tag.split('.')[0]}.Transition presentation={${factory}} timing={linearTiming({ durationInFrames: ${dur} })} />`
+  );
+  ensureNamedImport(s, source, 'linearTiming', '@remotion/transitions');
+  ensureImportPublic(s, source, p.importName, p.specifier);
+  let out = s.toString();
+  assertParses(canvasAbsPath, out, afterStableId);
+  assertCompSemantics(canvasAbsPath, out);
+  // New overlap ⇒ the comp SHRINKS by `dur`.
+  out = applyRippleAfterClip(canvasAbsPath, out, artboardId, afterStableId, -dur, {
+    shiftFroms: false,
+  }).source;
+  const after = enumerateClips(canvasAbsPath, out, artboardId);
+  const afterIdx = after.clips.findIndex((c) => c.stableId === afterStableId);
+  const t = after.clips[afterIdx + 1];
+  return { source: out, transitionStableId: t?.kind === 'transition' ? t.stableId : null };
+}
+
+/**
+ * Task 17 — remove a transition (the seam becomes a hard cut). TOTAL grows by
+ * the removed overlap (ripple).
+ */
+export function applyRemoveTransition(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  transitionId: string,
+  expectedHash: string | undefined
+): { source: string } {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip: t, idx } = mustResolve(canvasAbsPath, clips, transitionId, expectedHash);
+  if (t.kind !== 'transition') {
+    throw new CanvasEditError(`"${transitionId}" is not a transition`, {
+      canvas: canvasAbsPath,
+      id: transitionId,
+    });
+  }
+  const overlap = transitionDurationFrames(source, t) ?? 0;
+  const prevBeat = clips[idx - 1];
+  const span = spanWithFraming(source, t.start, t.end);
+  const s = new MagicString(source);
+  s.remove(span[0], span[1]);
+  let out = s.toString();
+  assertParses(canvasAbsPath, out, transitionId);
+  assertCompSemantics(canvasAbsPath, out);
+  if (overlap !== 0 && prevBeat) {
+    out = applyRippleAfterClip(canvasAbsPath, out, artboardId, prevBeat.stableId, overlap, {
+      shiftFroms: false,
+    }).source;
+  }
+  return { source: out };
+}
+
+// Small public shims so Task-17 code can reuse the Task-15 internals.
+function compDimensionsPublic(source: string): { width: number; height: number } | null {
+  const m = source.match(/<VideoComp\b[^>]*>/);
+  if (!m || m.index == null) return null;
+  const w = numAttrText(source, m.index, 'width');
+  const h = numAttrText(source, m.index, 'height');
+  return w && h ? { width: w, height: h } : null;
+}
+function ensureImportPublic(
+  s: MagicString,
+  source: string,
+  importName: string,
+  specifier: string
+): void {
+  if (new RegExp(`from ['"]${specifier.replace(/[/]/g, '\\/')}['"]`).test(source)) return;
+  const imports = [...source.matchAll(/^import [^\n]*\n/gm)];
+  const last = imports[imports.length - 1];
+  const at = last ? (last.index as number) + last[0].length : 0;
+  s.appendLeft(at, `import { ${importName} } from '${specifier}';\n`);
+}
+
+/**
+ * Task 22 — resolve an AI placeholder: swap the `<AIPlaceholder …/>` slate for
+ * the generated media IN PLACE (the clip tag — and with it the stableId slot,
+ * timing, and any name — survives).
+ */
+export function applyResolvePlaceholder(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined,
+  src: string,
+  mediaKind: 'video' | 'image'
+): { source: string } {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip } = mustResolve(canvasAbsPath, clips, stableId, expectedHash);
+  const srcTrim = String(src ?? '').trim();
+  if (!srcTrim) {
+    throw new CanvasEditError('resolve needs a generated asset src', {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  assertContainedSrc(canvasAbsPath, srcTrim, stableId);
+  const span = source.slice(clip.start, clip.end);
+  const m = span.match(/<AIPlaceholder\b/);
+  if (!m || m.index == null) {
+    throw new CanvasEditError(`clip "${stableId}" has no <AIPlaceholder> to resolve`, {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const phStart = clip.start + m.index;
+  let phEnd = openTagEnd(source, phStart);
+  if (source.slice(phEnd - 2, phEnd) !== '/>') {
+    // Paired-tag form (`<AIPlaceholder …><span>{"…"}</span></AIPlaceholder>`,
+    // the inline-editable emit) — swap the WHOLE element, close tag included.
+    // Security (adversarial review 2026-07-30): a prompt of `foo</AIPlaceholder>`
+    // emits a FAKE close tag inside the `{"…"}` string literal. `indexOf` would
+    // match that fake first and overwrite through it (assertParses then fails
+    // closed, but the placeholder becomes permanently un-resolvable). One
+    // placeholder per clip span ⇒ the REAL closer is the LAST `</AIPlaceholder>`
+    // before clip.end; a string-embedded fake always precedes it. Scan backwards.
+    const closeTag = '</AIPlaceholder>';
+    const close = source.lastIndexOf(closeTag, clip.end - 1);
+    if (close < phEnd || close + closeTag.length > clip.end) {
+      throw new CanvasEditError(
+        'placeholder element has no matching close tag — fix the JSX by hand',
+        {
+          canvas: canvasAbsPath,
+          id: stableId,
+        }
+      );
+    }
+    phEnd = close + closeTag.length;
+  }
+  const tag = mediaKind === 'image' ? 'Img' : 'OffthreadVideo';
+  const s = new MagicString(source);
+  s.overwrite(phStart, phEnd, `<${tag} src="${escapeAttr(srcTrim)}" />`);
+  const out = s.toString();
+  assertParses(canvasAbsPath, out, stableId);
+  assertCompSemantics(canvasAbsPath, out);
+  return { source: out };
+}
+
+/**
+ * Dogfood fix — an artboard marked `kind="video"` in the Inspector IS the
+ * user's "this is a video" intent, but without a `<VideoComp>` inside it the
+ * timeline can't see it and every drop dead-ended in a new canvas. This
+ * injects the missing comp IN PLACE: a minimal component + a `<VideoComp>`
+ * mounted as the artboard's last child (paints over the brief content), sized
+ * to the artboard. Returns null when the canvas has no eligible artboard
+ * (an explicit `artboardId`, else the first `kind="video"` one).
+ */
+export function applyEnsureVideoComp(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined
+): { source: string; artboardId: string } | null {
+  const re = /<DCArtboard\b[^>]*>/g;
+  let target: { start: number; tag: string } | null = null;
+  for (const m of source.matchAll(re)) {
+    const start = m.index as number;
+    const idAttr = attrSpanInTag(source, start, 'id');
+    const id = idAttr?.valueText?.replace(/^["']|["']$/g, '') ?? null;
+    const kindAttr = attrSpanInTag(source, start, 'kind');
+    const kind = kindAttr?.valueText?.replace(/^["']|["']$/g, '') ?? null;
+    if ((artboardId && id === artboardId) || (!artboardId && kind === 'video')) {
+      if (artboardId && kind !== 'video') return null; // explicit target must opt in
+      target = { start, tag: m[0] as string };
+      break;
+    }
+  }
+  if (!target) return null;
+  const idAttr = attrSpanInTag(source, target.start, 'id');
+  const targetId = idAttr?.valueText?.replace(/^["']|["']$/g, '') ?? '';
+  const width = numAttrText(source, target.start, 'width') ?? 1280;
+  const height = numAttrText(source, target.start, 'height') ?? 720;
+  const closeIdx = source.indexOf('</DCArtboard>', target.start);
+  if (closeIdx < 0) return null;
+  // Unique component name.
+  let compName = 'VideoCut';
+  for (let i = 2; new RegExp(`\\b${compName}\\b`).test(source); i += 1) compName = `VideoCut${i}`;
+  const indent = lineStartInfo(source, closeIdx).indent;
+  const s = new MagicString(source);
+  s.appendLeft(
+    closeIdx,
+    `  <VideoComp component={${compName}} durationInFrames={150} fps={30} width={${width}} height={${height}} />\n${indent}`
+  );
+  // The comp body — an AbsoluteFill root so the first storyline drop can
+  // author its <TransitionSeries> inside (the greenfield insert contract).
+  const exportM = source.match(/^export default function\b/m) ?? source.match(/^export default\b/m);
+  const at = exportM?.index ?? 0;
+  s.appendLeft(
+    at,
+    `const ${compName} = () => (\n  <AbsoluteFill style={{ background: '#000' }}>\n  </AbsoluteFill>\n);\n\n`
+  );
+  ensureNamedImport(s, source, 'VideoComp', '@maude/canvas-lib');
+  ensureNamedImport(s, source, 'AbsoluteFill', 'remotion');
+  const out = s.toString();
+  assertParses(canvasAbsPath, out, targetId);
+  return { source: out, artboardId: targetId };
+}
+
+/**
+ * Dogfood — edit the text a clip carries: a Title overlay's literal child or an
+ * AIPlaceholder's `prompt`. Both are authored as a JSON-stringified expression
+ * (`{"…"}`, DDR-150 P1), so ONE rewrite covers them: replace the clip's first
+ * quoted-string expression with the new JSON literal.
+ */
+export function applySetClipText(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined,
+  text: string
+): { source: string } {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip } = mustResolve(canvasAbsPath, clips, stableId, expectedHash);
+  const t = String(text ?? '').slice(0, 2000);
+  if (!t.trim()) {
+    throw new CanvasEditError('text must not be empty', { canvas: canvasAbsPath, id: stableId });
+  }
+  const span = source.slice(clip.start, clip.end);
+  const m = span.match(/\{"(?:[^"\\]|\\.)*"\}/);
+  if (!m || m.index == null) {
+    throw new CanvasEditError(
+      'this clip has no editable text literal (Title overlays and AI placeholders do)',
+      { canvas: canvasAbsPath, id: stableId }
+    );
+  }
+  const start = clip.start + m.index;
+  const s = new MagicString(source);
+  s.overwrite(start, start + m[0].length, `{${JSON.stringify(t)}}`);
+  const out = s.toString();
+  assertParses(canvasAbsPath, out, stableId);
+  assertCompSemantics(canvasAbsPath, out);
+  return { source: out };
+}
+
+/**
+ * Dogfood (2026-07-30) — vertical layer reorder. Standalone overlay clips are
+ * SIBLINGS whose document order IS their paint order (later paints on top).
+ * Move one to `toIndex` in that ladder (audio-kind standalones are excluded —
+ * they have no z-order). One-pass span permutation, then reparse + gate.
+ */
+export function applyReorderOverlayLayer(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined,
+  toIndex: number
+): { source: string } {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip } = mustResolve(canvasAbsPath, clips, stableId, expectedHash);
+  if (isSeriesSeq(clip)) {
+    throw new CanvasEditError('storyline beats reorder horizontally — drag the beat instead', {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const ladder = clips.filter(
+    (c) => c.kind === 'sequence' && !isSeriesSeq(c) && c.mediaTag !== 'Audio'
+  ) as ClipInfo[];
+  const from = ladder.findIndex((c) => c.stableId === clip.stableId);
+  if (from < 0) {
+    throw new CanvasEditError('this clip has no layer order (audio clips stack freely)', {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const to = Math.max(0, Math.min(ladder.length - 1, Math.round(toIndex)));
+  if (to === from) return { source };
+  const order = ladder.map((_, k) => k);
+  order.splice(from, 1);
+  order.splice(to, 0, from);
+  const texts = ladder.map((c) => source.slice(c.start, c.end));
+  const s = new MagicString(source);
+  order.forEach((srcIdx, slot) => {
+    const at = ladder[slot] as ClipInfo;
+    if (srcIdx !== slot) s.overwrite(at.start, at.end, texts[srcIdx] as string);
+  });
+  const out = s.toString();
+  assertParses(canvasAbsPath, out, stableId);
+  assertCompSemantics(canvasAbsPath, out);
+  return { source: out };
+}
+
+/** Graft trim/rate onto a freshly-inserted clip's media element. */
+function graftMediaAttrs(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string | null,
+  trim: number,
+  rate: number
+): string {
+  if (!stableId || (trim === 0 && rate === 1)) return source;
+  const after = enumerateClips(canvasAbsPath, source, artboardId);
+  const clip = after.clips.find((c) => c.stableId === stableId);
+  const mediaStart = clip ? directMediaTagStart(source, clip) : null;
+  if (mediaStart == null) return source;
+  const s = new MagicString(source);
+  if (trim) setTagAttr(s, source, mediaStart, 'trimBefore', `{${trim}}`);
+  if (rate !== 1) setTagAttr(s, source, mediaStart, 'playbackRate', `{${rate}}`);
+  const out = s.toString();
+  assertParses(canvasAbsPath, out, stableId);
+  return out;
+}
+
+/**
+ * Layers model (dogfood) — move a storyline beat OUT into its own overlay
+ * layer (a standalone `<Sequence from>` at the beat's absolute start), or a
+ * standalone overlay clip INTO the storyline (appended as a beat). Media-
+ * carrying clips only; timing (trimBefore/playbackRate) rides along.
+ * Insert-first, then remove the original (found again by content hash), so
+ * the "cannot remove the only clip" guard never blocks the move.
+ */
+export function applyMoveClipToOverlay(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined
+): { source: string; stableId: string | null } {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip } = mustResolve(canvasAbsPath, clips, stableId, expectedHash);
+  if (!isSeriesSeq(clip)) {
+    throw new CanvasEditError('already an overlay/standalone clip', {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const mediaStart = directMediaTagStart(source, clip);
+  if (mediaStart == null || !clip.mediaSrc || clip.durationInFrames == null) {
+    throw new CanvasEditError('only a media clip with a direct source can move between layers', {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const start = clipAbsoluteStart(source, canvasAbsPath, artboardId, stableId);
+  const trim =
+    numAttrText(source, mediaStart, 'trimBefore') ??
+    numAttrText(source, mediaStart, 'startFrom') ??
+    0;
+  const rate = numAttrText(source, mediaStart, 'playbackRate') ?? 1;
+  const ins = applyInsertClipAt(canvasAbsPath, source, artboardId, {
+    lane: 'overlay',
+    from: start,
+    durationInFrames: clip.durationInFrames,
+    mediaTag: clip.mediaTag === 'Audio' ? 'Audio' : 'Video',
+    src: clip.mediaSrc,
+  });
+  let out = graftMediaAttrs(canvasAbsPath, ins.source, artboardId, ins.stableId, trim, rate);
+  const again = enumerateClips(canvasAbsPath, out, artboardId);
+  const insertedHash = again.clips.find((c) => c.stableId === ins.stableId)?.contentHash ?? null;
+  const original = again.clips.find(
+    (c) => c.contentHash === clip.contentHash && c.stableId !== ins.stableId
+  );
+  if (original) {
+    out = applyRemoveClipRippled(
+      canvasAbsPath,
+      out,
+      artboardId,
+      original.stableId,
+      undefined
+    ).source;
+  }
+  // The storyline shrank under the overlay — stretch the comp back to it.
+  out = applyFitTotalToContent(canvasAbsPath, out, artboardId).source;
+  assertCompSemantics(canvasAbsPath, out);
+  // Positional ids shift when the original leaves — re-address the moved clip.
+  const settled = insertedHash
+    ? enumerateClips(canvasAbsPath, out, artboardId).clips.find(
+        (c) => c.contentHash === insertedHash
+      )
+    : null;
+  return { source: out, stableId: settled?.stableId ?? ins.stableId };
+}
+
+export function applyMoveClipToStoryline(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined,
+  stableId: string,
+  expectedHash: string | undefined
+): { source: string; stableId: string | null } {
+  const { clips } = enumerateClips(canvasAbsPath, source, artboardId);
+  const { clip } = mustResolve(canvasAbsPath, clips, stableId, expectedHash);
+  if (clip.tag !== 'Sequence') {
+    throw new CanvasEditError('already a storyline beat', { canvas: canvasAbsPath, id: stableId });
+  }
+  const mediaStart = directMediaTagStart(source, clip);
+  if (mediaStart == null || !clip.mediaSrc || clip.durationInFrames == null) {
+    throw new CanvasEditError('only a media clip with a direct source can move between layers', {
+      canvas: canvasAbsPath,
+      id: stableId,
+    });
+  }
+  const trim =
+    numAttrText(source, mediaStart, 'trimBefore') ??
+    numAttrText(source, mediaStart, 'startFrom') ??
+    0;
+  const rate = numAttrText(source, mediaStart, 'playbackRate') ?? 1;
+  const ins = applyInsertClipAt(canvasAbsPath, source, artboardId, {
+    lane: 'storyline',
+    durationInFrames: clip.durationInFrames,
+    mediaTag: clip.mediaTag === 'Audio' ? 'Audio' : 'Video',
+    src: clip.mediaSrc,
+  });
+  let out = graftMediaAttrs(canvasAbsPath, ins.source, artboardId, ins.stableId, trim, rate);
+  const again = enumerateClips(canvasAbsPath, out, artboardId);
+  const insertedHash = again.clips.find((c) => c.stableId === ins.stableId)?.contentHash ?? null;
+  const original = again.clips.find(
+    (c) => c.contentHash === clip.contentHash && c.stableId !== ins.stableId
+  );
+  if (original) {
+    out = applyRemoveClipRippled(
+      canvasAbsPath,
+      out,
+      artboardId,
+      original.stableId,
+      undefined
+    ).source;
+  }
+  // Exact-fit the comp end (the storyline insert over-bumped while the overlay
+  // still existed).
+  out = applyFitTotalToContent(canvasAbsPath, out, artboardId).source;
+  assertCompSemantics(canvasAbsPath, out);
+  // Positional ids shift when the original leaves — re-address the moved clip.
+  const settled = insertedHash
+    ? enumerateClips(canvasAbsPath, out, artboardId).clips.find(
+        (c) => c.contentHash === insertedHash
+      )
+    : null;
+  return { source: out, stableId: settled?.stableId ?? ins.stableId };
+}
+
+/**
+ * "The timeline always reaches the last clip" (dogfood rule): compute the real
+ * content end — storyline cursor end, every standalone clip's from+duration —
+ * and set the comp duration to it exactly — the timeline always ends where
+ * the last clip ends (grows AND shrinks with the content).
+ */
+export function applyFitTotalToContent(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string | undefined
+): { source: string; total: number | null } {
+  const cc = enumerateClips(canvasAbsPath, source, artboardId);
+  if (!cc.compName || cc.durationInFrames == null) return { source, total: cc.durationInFrames };
+  const consts = collectConsts(source);
+  let cursor = 0;
+  let maxEnd = 0;
+  for (const c of cc.clips) {
+    if (c.kind === 'transition') {
+      cursor -= transitionDurationFrames(source, c, consts) ?? 0;
+      continue;
+    }
+    const start = c.tag === 'Sequence' && c.from != null ? c.from : cursor;
+    const end = start + (c.durationInFrames ?? 0);
+    if (c.tag !== 'Sequence') cursor = end;
+    if (end > maxEnd) maxEnd = end;
+  }
+  const delta = maxEnd - cc.durationInFrames;
+  if (delta === 0 || maxEnd <= 0 || cc.clips.length === 0) {
+    return { source, total: cc.durationInFrames };
+  }
+  const anchor = cc.clips.find((c) => c.kind === 'sequence');
+  if (!anchor) return { source, total: cc.durationInFrames };
+  const out = applyRippleAfterClip(canvasAbsPath, source, artboardId, anchor.stableId, delta, {
+    shiftFroms: false,
+  }).source;
+  return { source: out, total: maxEnd };
+}
+
+/** Run a pure source-op on disk (atomic write + cross-process lock). */
+export async function applyOnDisk<T extends { source: string }>(
+  canvasAbsPath: string,
+  fn: (source: string) => T
+): Promise<T> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: '',
+      });
+    }
+    const source = await file.text();
+    const next = fn(source);
+    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;
+  });
+}
+
+/** Re-parse gate shared by ops in this module (parse-clean before semantics). */
+export function assertParses(canvasAbsPath: string, source: string, id: string): void {
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CanvasEditError(
+      `edit produced invalid source: ${parsed.errors[0]?.message ?? 'parse error'}`,
+      { canvas: canvasAbsPath, id }
+    );
+  }
+}