@1agh/maude 0.39.1 → 0.41.0

package/apps/studio/api.ts

@@ -3,17 +3,37 @@
 
 import crypto from 'node:crypto';
 import type { Dirent } from 'node:fs';
-import { mkdir, readdir, readFile, rename, rm, stat as statp } from 'node:fs/promises';
+import { lstat, mkdir, readdir, readFile, rename, rm, stat as statp } from 'node:fs/promises';
 import path from 'node:path';
 
 import { renderBriefBoard, validateCanvasName } from './canvas-create.ts';
 import {
+  type AssembleClip,
+  assembleCompSource,
   CanvasEditError,
+  type ClipInfo,
+  deleteArtboard,
+  deleteElement,
+  duplicateElement,
+  type EditScope,
+  editArrayElementString,
   editAttribute,
+  enumerateClips,
+  type InsertKind,
+  insertArtboard,
+  insertClip,
+  insertElement,
   type MovePosition,
   moveElement,
   removeAttribute,
+  removeClip,
+  reorderClip,
+  resizeArtboard,
+  resolveEditScope,
+  retimeSequence,
+  retimeSequenceByClip,
   editText as runEditText,
+  toggleClipHidden,
 } from './canvas-edit.ts';
 import type { Context } from './context.ts';
 import { createHistory } from './history.ts';
@@ -180,7 +200,7 @@ export type DeleteCanvasResult =
 
 /** Phase 12 — result of an in-canvas direct edit (`editCss` / `editText`). */
 export type EditOpResult =
-  | { ok: true; delta: number }
+  | { ok: true; delta: number; seq?: number }
   | { ok: false; status: number; error: string };
 
 /**
@@ -230,6 +250,10 @@ export interface Api {
   saveCanvasState(file: string, state: Record<string, unknown>): Promise<void>;
   // Canvas meta sidecar (Phase 4 T5 — .design/ui/<slug>.meta.json)
   loadCanvasMeta(file: string): Promise<Record<string, unknown> | null>;
+  /** DDR-148 — raw .tsx source for the Timeline sequence/keyframe parser. */
+  loadCanvasSource(
+    file: unknown
+  ): Promise<{ ok: true; source: string } | { ok: false; status: number; error: string }>;
   patchCanvasMeta(
     file: string,
     patch: Record<string, unknown>
@@ -239,17 +263,27 @@ export interface Api {
   saveAnnotations(file: string, svg: string): Promise<boolean>;
   // Phase 23 — content-addressed binary image write (drag-drop / paste / picker)
   saveAsset(bytes: Uint8Array): Promise<SaveAssetResult>;
+  /** Stage F1 — list content-addressed image/video assets for the AssetPicker. */
+  listAssets(): Promise<{ ok: true; assets: AssetListing[] }>;
+  /** DDR-148 — streaming variant for the HTTP route (100 MB video without a
+   *  full in-RAM buffer). Sniffs + caps + content-addresses like saveAsset. */
+  saveAssetFromStream(stream: ReadableStream<Uint8Array>): Promise<SaveAssetResult>;
   // Persist a clipboard-pasted ACP composer image → runtime `_chat/attachments/`,
   // returns an absolute path (Phase 31 follow-up — POST /_api/acp/attachment).
   saveChatAttachment(bytes: Uint8Array): Promise<SaveAssetResult>;
   // Resolve a content-addressed attachment name (`<sha8>.<ext>`) to its absolute
   // path, or null (GET /_api/acp/attachment — the read side of the pair above).
   resolveChatAttachment(name: unknown): Promise<string | null>;
-  // Create a blank brief board from the browser (Phase 22 — POST /_api/canvas)
+  // Create a blank brief board OR an assembled video-comp from the browser
+  // (Phase 22 — POST /_api/canvas; DDR-150 P4 Task 12 adds kind "video-comp").
   createCanvas(input: {
     name?: unknown;
     kind?: unknown;
     group?: unknown;
+    clips?: unknown;
+    fps?: unknown;
+    width?: unknown;
+    height?: unknown;
   }): Promise<CreateCanvasResult>;
   // Soft-delete a canvas from the browser (Phase 22 — DELETE /_api/canvas)
   deleteCanvas(input: { file?: unknown }): Promise<DeleteCanvasResult>;
@@ -260,6 +294,8 @@ export interface Api {
     id?: unknown;
     property?: unknown;
     value?: unknown;
+    reset?: unknown;
+    idIndex?: unknown;
   }): Promise<EditOpResult>;
   // Phase 12 (DDR-103) — inline text-content edit (POST /_api/edit-text). Main-origin only.
   editText(input: { canvas?: unknown; id?: unknown; text?: unknown }): Promise<EditOpResult>;
@@ -281,6 +317,142 @@ export interface Api {
     refId?: unknown;
     position?: unknown;
   }): Promise<ReorderOpResult>;
+  /** DDR-148 — Timeline drag-to-retime a sequence's durationInFrames / from. */
+  retimeSequenceOp(input: {
+    canvas?: unknown;
+    // DDR-150 P2 — prefer stableId (comp-scoped, multi-comp-safe) over index.
+    stableId?: unknown;
+    artboardId?: unknown;
+    contentHash?: unknown;
+    index?: unknown;
+    durationInFrames?: unknown;
+    from?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
+  // DDR-150 P3 — remove a clip addressed by stableId (fingerprint + semantic
+  // gate; refuses the only clip; drops an adjacent transition in a series).
+  removeSequenceOp(input: {
+    canvas?: unknown;
+    stableId?: unknown;
+    artboardId?: unknown;
+    contentHash?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
+  // DDR-150 P4 — insert a new <Sequence> (optionally with media) after a comp's
+  // last clip. Returns the new clip's stableId.
+  insertSequenceOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    from?: unknown;
+    durationInFrames?: unknown;
+    mediaTag?: unknown;
+    src?: unknown;
+  }): Promise<
+    | { ok: true; stableId: string | null; seq?: number }
+    | { ok: false; status: number; error: string }
+  >;
+  // DDR-150 P5 — z-order reorder: move a standalone <Sequence> before/after a
+  // sibling (render stacking), reusing moveElement + the semantic gate. Both
+  // clips are fingerprint-checked. Returns the moved clip's (re-settled) stableId.
+  reorderSequenceOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    stableId?: unknown;
+    contentHash?: unknown;
+    refStableId?: unknown;
+    refContentHash?: unknown;
+    position?: unknown;
+  }): Promise<
+    | { ok: true; stableId: string | null; seq?: number }
+    | { ok: false; status: number; error: string }
+  >;
+  // DDR-150 dogfood — replace a media src that lives in an array literal
+  // (the showreel `CLIPS[i].src` pattern), addressed by mediaArrayRef.
+  editArraySrcOp(input: {
+    canvas?: unknown;
+    arrayName?: unknown;
+    index?: unknown;
+    field?: unknown;
+    value?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
+  // DDR-150 dogfood — hide/show a clip (gates its body behind {false && …}).
+  toggleHideOp(input: {
+    canvas?: unknown;
+    stableId?: unknown;
+    artboardId?: unknown;
+    contentHash?: unknown;
+  }): Promise<
+    { ok: true; hidden: boolean; seq?: number } | { ok: false; status: number; error: string }
+  >;
+  // DDR-150 P2 — the single authoritative clip enumerator for a video-comp.
+  // Read-only; the Timeline addresses every op by the returned `stableId`
+  // (never a regex document-order index — the multi-comp mis-hit defect).
+  compClips(input: { canvas?: unknown; artboardId?: unknown }): Promise<
+    | {
+        ok: true;
+        compName: string | null;
+        artboardId: string | null;
+        fps: number | null;
+        durationInFrames: number | null;
+        clips: Array<Omit<ClipInfo, 'start' | 'end'>>;
+      }
+    | { ok: false; status: number; error: string }
+  >;
+  // Stage I (feature-element-editing-robustness) — general element structural
+  // edits. Each logs a whole-file undo seq (reverted via reorderRevert).
+  /** Delete an element by data-cd-id (reused-component instance via idIndex). */
+  deleteElementOp(input: {
+    canvas?: unknown;
+    id?: unknown;
+    idIndex?: unknown;
+  }): Promise<
+    { ok: true; deletedId: string; seq?: number } | { ok: false; status: number; error: string }
+  >;
+  /** Insert a synthesized div/text/image relative to a reference element. */
+  insertElementOp(input: {
+    canvas?: unknown;
+    refId?: unknown;
+    position?: unknown;
+    kind?: unknown;
+    src?: unknown;
+    refIndex?: unknown;
+  }): Promise<
+    { ok: true; newId: string | null; seq?: number } | { ok: false; status: number; error: string }
+  >;
+  /** Insert a new empty artboard from a screen-size preset. */
+  insertArtboardOp(input: {
+    canvas?: unknown;
+    id?: unknown;
+    label?: unknown;
+    width?: unknown;
+    height?: unknown;
+  }): Promise<
+    { ok: true; artboardId: string; seq?: number } | { ok: false; status: number; error: string }
+  >;
+  /** Free-hand artboard resize — write width/height numeric props (DDR-027, D4). */
+  resizeArtboardOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    width?: unknown;
+    height?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
+  /** Duplicate an element (Cmd+D) — a copy as the next sibling, whole-file undo. */
+  duplicateElementOp(input: {
+    canvas?: unknown;
+    id?: unknown;
+    idIndex?: unknown;
+  }): Promise<
+    { ok: true; newId: string | null; seq?: number } | { ok: false; status: number; error: string }
+  >;
+  /** Delete an artboard by its `id` prop (whole-file undo seq). */
+  deleteArtboardOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
+  /** Edit-scope verdict (local vs shared component instance) for the INV-3 badge. */
+  editScopeOp(input: {
+    canvas?: unknown;
+    id?: unknown;
+    rendered?: unknown;
+  }): Promise<({ ok: true } & EditScope) | { ok: false; status: number; error: string }>;
   // Undo/redo a prior reorder by seq (Cmd+Z from the canvas undo stack). Whole-
   // file content swap from the in-memory revert log — immune to the positional
   // data-cd-id churn a reorder causes (inverse-descriptor undo would go stale).
@@ -327,7 +499,10 @@ export const ASSET_MAX_BYTES = 10 * 1024 * 1024;
  */
 export const ASSET_SESSION_BUDGET = (() => {
   const env = Number(process.env.MAUDE_ASSET_SESSION_BUDGET);
-  return Number.isFinite(env) && env > 0 ? env : 256 * 1024 * 1024;
+  // DDR-148 — raised 256 MB → 1 GB now that the route accepts video/audio (one
+  // 100 MB clip would blow a 256 MB budget after a couple of drops). Still an
+  // aggregate per-server-instance disk-fill bound; env-overridable.
+  return Number.isFinite(env) && env > 0 ? env : 1024 * 1024 * 1024;
 })();
 
 /**
@@ -392,6 +567,121 @@ export interface SaveAssetResult {
   path?: string;
 }
 
+/** Stage F1 — one media asset in the AssetPicker listing. */
+export interface AssetListing {
+  /** designRoot-relative path (`assets/<sha8>.<ext>`) — what a src/href uses. */
+  path: string;
+  name: string;
+  ext: string;
+  kind: 'image' | 'video';
+  size: number;
+  mtimeMs: number;
+}
+
+/** DDR-148 — media category, decides which per-file cap applies. */
+export type AssetCategory = 'image' | 'video' | 'audio';
+
+export interface AssetTypeInfo {
+  /** Stored file extension (bytes decide it, never the upload name). */
+  ext: string;
+  category: AssetCategory;
+}
+
+/**
+ * DDR-148 — per-file ceiling for time-based media (video + audio). Images keep
+ * the tighter {@link ASSET_MAX_BYTES} 10 MB cap. Overridable via
+ * `MAUDE_ASSET_MAX_VIDEO_BYTES` (bytes) for power users. The route lives on the
+ * (untrusted) canvas origin, so this cap + the session budget + the streamed
+ * write are the trust mitigation, exactly like the image caps (DDR-088).
+ */
+export const ASSET_MAX_VIDEO_BYTES = (() => {
+  const env = Number(process.env.MAUDE_ASSET_MAX_VIDEO_BYTES);
+  return Number.isFinite(env) && env > 0 ? env : 100 * 1024 * 1024;
+})();
+
+/** The byte cap for a category. */
+export function assetCapForCategory(category: AssetCategory): number {
+  return category === 'image' ? ASSET_MAX_BYTES : ASSET_MAX_VIDEO_BYTES;
+}
+
+const UNSUPPORTED_ASSET_MSG =
+  'unsupported media type — png/jpeg/gif/webp images or mp4/mov/webm/mp3/wav/m4a media only (SVG/script rejected)';
+
+function capError(category?: AssetCategory): string {
+  if (category === 'image') return 'image exceeds the 10 MB cap';
+  const mb = Math.round(ASSET_MAX_VIDEO_BYTES / (1024 * 1024));
+  return `media exceeds the ${mb} MB cap`;
+}
+
+/** Concatenate a small list of chunks (used only for the ≤ few-KB sniff head). */
+function concatBytes(chunks: readonly Uint8Array[]): Uint8Array {
+  let len = 0;
+  for (const c of chunks) len += c.length;
+  const out = new Uint8Array(len);
+  let off = 0;
+  for (const c of chunks) {
+    out.set(c, off);
+    off += c.length;
+  }
+  return out;
+}
+
+/**
+ * DDR-148 — magic-byte type sniff for the WIDENED asset route: images (via
+ * {@link sniffImageType}) PLUS time-based media. The declared name / extension
+ * / Content-Type is NEVER trusted — the bytes decide the stored extension AND
+ * the category (→ which cap applies). The server only sniffs; it never PARSES a
+ * container (parsing happens in the sandboxed capture browser). Anything that
+ * isn't a recognised raster/video/audio magic number (SVG, HTML, arbitrary
+ * script) → null → rejected (415). Needs ≥ 12 bytes for the ISO-BMFF brands.
+ */
+export function sniffAssetType(bytes: Uint8Array): AssetTypeInfo | null {
+  const img = sniffImageType(bytes);
+  if (img) return { ext: img, category: 'image' };
+  const b = bytes;
+  // ISO-BMFF (mp4 / mov / m4a): "ftyp" box at offset 4, brand at offset 8.
+  if (
+    b.length >= 12 &&
+    b[4] === 0x66 && // f
+    b[5] === 0x74 && // t
+    b[6] === 0x79 && // y
+    b[7] === 0x70 // p
+  ) {
+    const brand = String.fromCharCode(b[8] ?? 0, b[9] ?? 0, b[10] ?? 0, b[11] ?? 0);
+    if (brand === 'qt  ') return { ext: 'mov', category: 'video' };
+    if (brand.startsWith('M4A')) return { ext: 'm4a', category: 'audio' };
+    if (brand.startsWith('M4V')) return { ext: 'm4v', category: 'video' };
+    // isom / mp41 / mp42 / avc1 / iso2 / iso5 / dash / mp4v / … → treat as mp4.
+    return { ext: 'mp4', category: 'video' };
+  }
+  // Matroska / WebM — EBML header 1A 45 DF A3.
+  if (b.length >= 4 && b[0] === 0x1a && b[1] === 0x45 && b[2] === 0xdf && b[3] === 0xa3) {
+    return { ext: 'webm', category: 'video' };
+  }
+  // MP3 — "ID3" tag OR a frame-sync (0xFF followed by 0b111xxxxx).
+  if (b.length >= 3 && b[0] === 0x49 && b[1] === 0x44 && b[2] === 0x33) {
+    return { ext: 'mp3', category: 'audio' };
+  }
+  if (b.length >= 2 && b[0] === 0xff && ((b[1] ?? 0) & 0xe0) === 0xe0) {
+    return { ext: 'mp3', category: 'audio' };
+  }
+  // WAV — "RIFF"????"WAVE".
+  if (
+    b.length >= 12 &&
+    b[0] === 0x52 &&
+    b[1] === 0x49 &&
+    b[2] === 0x46 &&
+    b[3] === 0x46 &&
+    b[8] === 0x57 &&
+    b[9] === 0x41 &&
+    b[10] === 0x56 &&
+    b[11] === 0x45
+  ) {
+    return { ext: 'wav', category: 'audio' };
+  }
+  return null;
+}
+
 export function createApi(ctx: Context, hooks: ApiHooks): Api {
   const onCommentsChanged = hooks.onCommentsChanged;
   const onAnnotationsChanged = hooks.onAnnotationsChanged;
@@ -405,6 +695,67 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   const reorderLog = new Map<number, { abs: string; before: string; after: string }>();
   let reorderSeq = 0;
 
+  // DDR-150 dogfood #1 — the SAME whole-file log backs the Timeline clip ops
+  // (retime / remove / insert / z-reorder / replace-src): every successful op
+  // registers its {before, after} and returns the seq; the shell keeps a
+  // per-canvas undo/redo stack of seqs and replays them through
+  // /_api/reorder-revert (guarded whole-file swap, 409 on divergence).
+  function logUndo(abs: string, before: string, after: string): number {
+    const seq = ++reorderSeq;
+    reorderLog.set(seq, { abs, before, after });
+    while (reorderLog.size > REORDER_LOG_CAP) {
+      const oldest = reorderLog.keys().next().value;
+      if (oldest === undefined) break;
+      reorderLog.delete(oldest);
+    }
+    return seq;
+  }
+
+  // ── Structural-write throttle + source-size ceiling (G3 security, DDR-152) ──
+  // The new structural verbs (delete / insert-element / insert-artboard /
+  // resize-artboard) are the first that let an UNTRUSTED active canvas both
+  // *remove* and *grow* its own source: the shell relays a canvas's `dgn:*`
+  // request after gating only on `e.source === activeWin` — there is no user
+  // gesture on the wire, so a hostile on-load script can drive these in a loop.
+  // Two bounds close the disk-fill / silent-shred DoS the adversarial review
+  // flagged (mirrors the ASSET_SESSION_BUDGET the /_api/asset lane already has,
+  // DDR-088 — this is the OTHER untrusted-origin disk-write surface):
+  //   (a) a per-api token bucket caps the sustained rate. A human does a few
+  //       structural edits/sec; a scripted loop can't beat the refill, which
+  //       keeps every whole-file _history snapshot + RAM undo entry rate-bound.
+  //   (b) a growth op is refused once the source already exceeds
+  //       MAX_CANVAS_SOURCE, so inserts can't inflate the .tsx (and the snapshot
+  //       + undo copies it holds) without bound. Deletes/shrinks always pass.
+  // Bucket state is per-createApi (each test/instance starts full); env-tunable.
+  const STRUCTURAL_BURST = (() => {
+    const env = Number(process.env.MAUDE_STRUCTURAL_BURST);
+    return Number.isFinite(env) && env > 0 ? Math.floor(env) : 40;
+  })();
+  const STRUCTURAL_REFILL_PER_SEC = 8;
+  let structuralTokens = STRUCTURAL_BURST;
+  let structuralLastRefill = Date.now();
+  /** Consume one token; false when the caller is over the sustained rate. */
+  function takeStructuralToken(): boolean {
+    const now = Date.now();
+    structuralTokens = Math.min(
+      STRUCTURAL_BURST,
+      structuralTokens + ((now - structuralLastRefill) / 1000) * STRUCTURAL_REFILL_PER_SEC
+    );
+    structuralLastRefill = now;
+    if (structuralTokens < 1) return false;
+    structuralTokens -= 1;
+    return true;
+  }
+  const RATE_LIMITED = {
+    ok: false as const,
+    status: 429,
+    error: 'too many structural edits — slow down',
+  };
+  const MAX_CANVAS_SOURCE = (() => {
+    const env = Number(process.env.MAUDE_MAX_CANVAS_SOURCE);
+    return Number.isFinite(env) && env > 0 ? Math.floor(env) : 512 * 1024;
+  })();
+
   function fileSlug(file: string): string {
     return canvasSlugFromRel(file, paths.designRel);
   }
@@ -987,51 +1338,191 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   //     user input, but a poisoned designRoot must still not escape).
   // Running total of bytes this server instance has actually written (post-dedupe).
   let assetBytesWritten = 0;
-  async function saveAsset(bytes: Uint8Array): Promise<SaveAssetResult> {
-    if (!bytes || bytes.length === 0) return { ok: false, status: 400, error: 'empty body' };
-    if (bytes.length > ASSET_MAX_BYTES) {
-      return { ok: false, status: 413, error: 'asset exceeds the 10 MB cap' };
-    }
-    const kind = sniffImageType(bytes);
-    if (!kind) {
-      return {
-        ok: false,
-        status: 415,
-        error: 'unsupported image type — png/jpeg/gif/webp only (SVG rejected)',
-      };
-    }
-    const sha8 = crypto.createHash('sha256').update(bytes).digest('hex').slice(0, 8);
-    const name = `${sha8}.${kind}`;
+
+  /**
+   * DDR-148 — the streaming write path behind `POST /_api/asset`. Reads the
+   * request body chunk-by-chunk so a 100 MB video never lands as a single
+   * ArrayBuffer in RAM (the memory-amplification vector DDR-088 §review flagged
+   * for the untrusted canvas origin — worse now that the per-file cap is 100 MB,
+   * not 10 MB). Sniffs the type from the head, applies the CATEGORY cap while
+   * streaming (image 10 MB · video/audio {@link ASSET_MAX_VIDEO_BYTES}), writes
+   * to a temp file, then content-addresses (sha8) → dedupe-rename. Nothing is
+   * ever parsed — only magic bytes are read. `saveAsset(bytes)` wraps this so
+   * both the route and any programmatic caller share ONE tested path.
+   */
+  async function saveAssetFromStream(stream: ReadableStream<Uint8Array>): Promise<SaveAssetResult> {
     const assetsDir = path.join(paths.designRoot, 'assets');
-    const fileAbs = path.join(assetsDir, name);
-    // Containment backstop — the name is content-addressed (sha8 hex + sniffed
-    // ext), so there is no user-controlled path segment, but assert anyway.
-    const resolved = path.resolve(fileAbs);
-    const assetsResolved = path.resolve(assetsDir);
-    if (resolved !== path.join(assetsResolved, name)) {
-      return { ok: false, status: 400, error: 'resolved asset path escapes assets dir' };
-    }
+    const tmpName = `.tmp-${crypto.randomBytes(8).toString('hex')}`;
+    const tmpAbs = path.join(assetsDir, tmpName);
+    const hash = crypto.createHash('sha256');
+    let sink: Bun.FileSink | null = null;
+    let typeInfo: AssetTypeInfo | null = null;
+    let cap = ASSET_MAX_VIDEO_BYTES; // provisional max until the head is sniffed
+    let total = 0;
+    const headChunks: Uint8Array[] = [];
+    let headLen = 0;
+
+    const cleanup = async () => {
+      try {
+        if (sink) await sink.end();
+      } catch {
+        /* sink already closed */
+      }
+      try {
+        await rm(tmpAbs, { force: true });
+      } catch {
+        /* temp already gone */
+      }
+    };
+    const flushHead = () => {
+      for (const c of headChunks) {
+        hash.update(c);
+        sink?.write(c);
+      }
+      headChunks.length = 0;
+      headLen = 0;
+    };
+
+    // Explicit reader (NOT `for await` — Bun's HTTP `req.body` ReadableStream
+    // does not implement Symbol.asyncIterator, so async-iteration throws
+    // "undefined is not a function"; getReader().read() works for every stream).
+    const reader = stream.getReader();
     try {
-      // Dedupe — identical bytes hash to the same name; skip the write if present.
-      if (!(await Bun.file(fileAbs).exists())) {
-        // Aggregate write budget (DDR-088 follow-up) — bounds a scripted
-        // one-byte-mutation disk-fill loop from the untrusted canvas origin.
-        // Only a genuinely NEW file counts (a dedupe hit is free).
-        if (assetBytesWritten + bytes.length > ASSET_SESSION_BUDGET) {
-          return {
-            ok: false,
-            status: 429,
-            error: 'asset write budget exceeded for this server session',
-          };
+      await mkdir(assetsDir, { recursive: true });
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const chunk = value;
+        if (!chunk || chunk.length === 0) continue;
+        total += chunk.length;
+        if (total > cap) {
+          await cleanup();
+          return { ok: false, status: 413, error: capError(typeInfo?.category) };
         }
-        await mkdir(assetsDir, { recursive: true });
-        await Bun.write(fileAbs, bytes);
-        assetBytesWritten += bytes.length;
+        if (!typeInfo) {
+          headChunks.push(chunk);
+          headLen += chunk.length;
+          if (headLen >= 12) {
+            typeInfo = sniffAssetType(concatBytes(headChunks));
+            if (!typeInfo) {
+              await cleanup(); // nothing written yet — no temp file to remove
+              return { ok: false, status: 415, error: UNSUPPORTED_ASSET_MSG };
+            }
+            cap = assetCapForCategory(typeInfo.category);
+            if (total > cap) {
+              await cleanup();
+              return { ok: false, status: 413, error: capError(typeInfo.category) };
+            }
+            sink = Bun.file(tmpAbs).writer();
+            flushHead();
+          }
+        } else {
+          hash.update(chunk);
+          sink?.write(chunk);
+        }
+      }
+
+      if (total === 0) {
+        await cleanup();
+        return { ok: false, status: 400, error: 'empty body' };
+      }
+      // A body shorter than 12 bytes never triggered the mid-stream sniff.
+      if (!typeInfo) {
+        typeInfo = sniffAssetType(concatBytes(headChunks));
+        if (!typeInfo) {
+          await cleanup();
+          return { ok: false, status: 415, error: UNSUPPORTED_ASSET_MSG };
+        }
+        cap = assetCapForCategory(typeInfo.category);
+        if (total > cap) {
+          await cleanup();
+          return { ok: false, status: 413, error: capError(typeInfo.category) };
+        }
+        sink = Bun.file(tmpAbs).writer();
+        flushHead();
+      }
+      if (sink) await sink.end();
+
+      const sha8 = hash.digest('hex').slice(0, 8);
+      const name = `${sha8}.${typeInfo.ext}`;
+      const fileAbs = path.join(assetsDir, name);
+      // Containment backstop — the name is content-addressed (sha8 hex + sniffed
+      // ext), no user-controlled segment, but assert anyway (poisoned designRoot).
+      if (path.resolve(fileAbs) !== path.join(path.resolve(assetsDir), name)) {
+        await rm(tmpAbs, { force: true });
+        return { ok: false, status: 400, error: 'resolved asset path escapes assets dir' };
+      }
+      // Dedupe — identical bytes hash to the same name; drop the temp copy.
+      if (await Bun.file(fileAbs).exists()) {
+        await rm(tmpAbs, { force: true });
+        return { ok: true, path: `assets/${name}` };
+      }
+      // Aggregate write budget — bounds a scripted disk-fill loop from the
+      // untrusted canvas origin. Only a genuinely NEW file counts.
+      if (assetBytesWritten + total > ASSET_SESSION_BUDGET) {
+        await rm(tmpAbs, { force: true });
+        return {
+          ok: false,
+          status: 429,
+          error: 'asset write budget exceeded for this server session',
+        };
       }
+      await rename(tmpAbs, fileAbs);
+      assetBytesWritten += total;
+      return { ok: true, path: `assets/${name}` };
     } catch (err) {
+      await cleanup();
       return { ok: false, status: 500, error: err instanceof Error ? err.message : 'write failed' };
+    } finally {
+      try {
+        reader.releaseLock();
+      } catch {
+        /* already released */
+      }
+    }
+  }
+
+  async function saveAsset(bytes: Uint8Array): Promise<SaveAssetResult> {
+    if (!bytes || bytes.length === 0) return { ok: false, status: 400, error: 'empty body' };
+    return saveAssetFromStream(new Response(bytes).body as ReadableStream<Uint8Array>);
+  }
+
+  // Stage F1 (feature-element-editing-robustness) — list the versioned content-
+  // addressed media under <designRoot>/assets/ for the AssetPicker (Replace
+  // image / insert image). Read-only; returns image + video assets only (never
+  // arbitrary files), newest first, capped. MAIN-ORIGIN ONLY at the route layer.
+  async function listAssets(): Promise<{ ok: true; assets: AssetListing[] }> {
+    const assetsDir = path.join(paths.designRoot, 'assets');
+    const IMG = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.svg']);
+    const VID = new Set(['.mp4', '.webm', '.mov', '.m4v', '.ogg']);
+    let entries: string[] = [];
+    try {
+      entries = await readdir(assetsDir);
+    } catch {
+      return { ok: true, assets: [] }; // no assets dir yet
+    }
+    const out: AssetListing[] = [];
+    for (const name of entries) {
+      const ext = path.extname(name).toLowerCase();
+      const kind = IMG.has(ext) ? 'image' : VID.has(ext) ? 'video' : null;
+      if (!kind) continue;
+      let size = 0;
+      let mtimeMs = 0;
+      try {
+        // lstat (not stat): a symlink planted under assets/ resolves to isFile()
+        // === false here → skipped. Defends the listing against a symlink that
+        // would otherwise be served by the /assets/<file> static route.
+        const st = await lstat(path.join(assetsDir, name));
+        if (!st.isFile()) continue;
+        size = st.size;
+        mtimeMs = st.mtimeMs;
+      } catch {
+        continue;
+      }
+      out.push({ path: `assets/${name}`, name, ext: ext.slice(1), kind, size, mtimeMs });
     }
-    return { ok: true, path: `assets/${name}` };
+    out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return { ok: true, assets: out.slice(0, 500) };
   }
 
   // Phase 31 follow-up — persist an image pasted straight from the clipboard into
@@ -1112,11 +1603,37 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     name?: unknown;
     kind?: unknown;
     group?: unknown;
+    // DDR-150 P4 Task 12 — video-comp assemble payload (kind === 'video-comp').
+    clips?: unknown;
+    fps?: unknown;
+    width?: unknown;
+    height?: unknown;
   }): Promise<CreateCanvasResult> {
-    // v1 only stamps blank boards — generation stays with `/design:new` (Claude).
+    // v1 stamps blank brief-boards + assembled video-comps — richer generation
+    // stays with `/design:new` (Claude).
     const kind = input.kind == null || input.kind === '' ? 'brief-board' : input.kind;
-    if (kind !== 'brief-board') {
-      return { ok: false, status: 400, error: 'only kind "brief-board" is supported' };
+    if (kind !== 'brief-board' && kind !== 'video-comp') {
+      return { ok: false, status: 400, error: 'kind must be "brief-board" or "video-comp"' };
+    }
+    // Parse + validate the assemble clip list up front (video-comp only).
+    const assembleClips: AssembleClip[] = [];
+    if (kind === 'video-comp') {
+      if (!Array.isArray(input.clips) || input.clips.length === 0) {
+        return { ok: false, status: 400, error: 'video-comp needs a non-empty clips[]' };
+      }
+      if (input.clips.length > 60) {
+        return { ok: false, status: 400, error: 'too many clips (max 60)' };
+      }
+      for (const raw of input.clips) {
+        const c = raw as { src?: unknown; mediaKind?: unknown; durationInFrames?: unknown };
+        const src = typeof c?.src === 'string' ? c.src : '';
+        if (!src) return { ok: false, status: 400, error: 'each clip needs a src' };
+        const mediaKind = c?.mediaKind === 'audio' ? 'audio' : 'video';
+        const durationInFrames = Number.isFinite(Number(c?.durationInFrames))
+          ? Math.max(1, Math.min(100000, Math.round(Number(c.durationInFrames))))
+          : null;
+        assembleClips.push({ src, mediaKind, durationInFrames });
+      }
     }
     const v = validateCanvasName(input.name);
     if (!v.ok || !v.name || !v.componentName) {
@@ -1169,25 +1686,55 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     const slug = fileSlug(rel);
     const dsName = cfg.defaultDesignSystem || 'project';
     const platform = 'desktop';
-    const tsx = renderBriefBoard({
-      name: v.name,
-      componentName: v.componentName,
-      dsName,
-      platform,
-      seedHint: 'Empty brief board — annotate me',
-      historyDir: path.posix.join(paths.designRel, '_history', slug),
-    });
+    let tsx: string;
+    if (kind === 'video-comp') {
+      try {
+        tsx = assembleCompSource(v.componentName, assembleClips, {
+          fps: Number.isFinite(Number(input.fps)) ? Number(input.fps) : undefined,
+          width: Number.isFinite(Number(input.width)) ? Number(input.width) : undefined,
+          height: Number.isFinite(Number(input.height)) ? Number(input.height) : undefined,
+        });
+      } catch (err) {
+        return {
+          ok: false,
+          status: 400,
+          error: err instanceof Error ? err.message : 'assemble failed',
+        };
+      }
+    } else {
+      tsx = renderBriefBoard({
+        name: v.name,
+        componentName: v.componentName,
+        dsName,
+        platform,
+        seedHint: 'Empty brief board — annotate me',
+        historyDir: path.posix.join(paths.designRel, '_history', slug),
+      });
+    }
     const now = new Date().toISOString();
-    const meta = {
-      kind: 'brief-board',
-      title: v.name,
-      subtitle: 'brief board',
-      brief: v.name,
-      designSystem: dsName,
-      platform,
-      created: now,
-      last_modified: now,
-    };
+    const meta =
+      kind === 'video-comp'
+        ? {
+            kind: 'video-comp',
+            title: v.name,
+            subtitle: 'assembled reel',
+            brief: v.name,
+            tags: ['video'],
+            designSystem: dsName,
+            platform,
+            created: now,
+            last_modified: now,
+          }
+        : {
+            kind: 'brief-board',
+            title: v.name,
+            subtitle: 'brief board',
+            brief: v.name,
+            designSystem: dsName,
+            platform,
+            created: now,
+            last_modified: now,
+          };
     await Bun.write(fileAbs, tsx);
     await Bun.write(
       path.join(groupAbs, `${v.name}.meta.json`),
@@ -1356,6 +1903,27 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     return { ok: true, abs };
   }
 
+  /**
+   * DDR-148 — read a canvas's RAW .tsx source (containment via resolveCanvasAbs).
+   * The Timeline panel parses `<Sequence>`/`<TransitionSeries.Sequence>` blocks
+   * + `interpolate` windows from it to draw the sequence/keyframe rows. Read-only,
+   * MAIN-ORIGIN ONLY at the route layer (never the untrusted canvas iframe).
+   */
+  async function loadCanvasSource(
+    file: unknown
+  ): Promise<{ ok: true; source: string } | { ok: false; status: number; error: string }> {
+    const r = resolveCanvasAbs(file);
+    if (!r.ok) return r;
+    const f = Bun.file(r.abs);
+    if (!(await f.exists())) return { ok: false, status: 404, error: 'canvas not found' };
+    const source = await f.text();
+    // A comp is small; never stream a huge blob into the panel.
+    if (source.length > 512 * 1024) {
+      return { ok: false, status: 413, error: 'canvas source too large for the timeline parser' };
+    }
+    return { ok: true, source };
+  }
+
   // 8-hex lowercase, the shape `computeId` (canvas-edit.ts) stamps on data-cd-id.
   const CD_ID_RE = /^[0-9a-f]{8}$/;
 
@@ -1374,11 +1942,20 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     const rel = path.relative(paths.designRoot, abs);
     ctx.bus.emit('activity:suppress', rel);
     try {
+      // DDR-150 dogfood #1 — capture before/after so the edit registers in the
+      // whole-file undo log (the Timeline replace-src path rides this; other
+      // inspector edits get an undoable seq for free).
+      const before = await Bun.file(abs).text();
       const res = await run();
       // `changed === false` = the op collapsed to a no-op and nothing hit disk —
       // NOT `delta === 0`, which an equal-length replacement also produces.
-      if (res.changed === false) ctx.bus.emit('activity:unsuppress', rel);
-      return { ok: true, delta: res.delta };
+      if (res.changed === false) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true, delta: res.delta };
+      }
+      const after = await Bun.file(abs).text();
+      const seq = after !== before ? logUndo(abs, before, after) : undefined;
+      return { ok: true, delta: res.delta, seq };
     } catch (err) {
       ctx.bus.emit('activity:unsuppress', rel);
       return {
@@ -1395,11 +1972,20 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     property?: unknown;
     value?: unknown;
     reset?: unknown;
+    idIndex?: unknown;
   }): Promise<EditOpResult> {
     const r = resolveCanvasAbs(input.canvas);
     if (!r.ok) return r;
     const id = typeof input.id === 'string' ? input.id.trim() : '';
     if (!CD_ID_RE.test(id)) return { ok: false, status: 400, error: 'invalid data-cd-id' };
+    // Stage H3 — optional DOM-occurrence index. Present only for a whole-instance
+    // move/resize (reposition/resize-request); routes the write to the dragged
+    // component instance's own `<Component/>` usage so it stays LOCAL. Absent for
+    // knob / paste-style edits (those stay global on the shared inner element).
+    const idIndex =
+      typeof input.idIndex === 'number' && Number.isInteger(input.idIndex) && input.idIndex >= 0
+        ? input.idIndex
+        : undefined;
     const property = typeof input.property === 'string' ? input.property.trim() : '';
     // CSS property names are ASCII letters + hyphens only (optionally a leading
     // `-` for vendor prefixes) — reject anything that could smuggle a second key
@@ -1414,7 +2000,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     if (input.reset === true) {
       return suppressedEdit(
         r.abs,
-        () => removeAttribute(r.abs, id, `style.${camel}`),
+        () => removeAttribute(r.abs, id, `style.${camel}`, idIndex),
         'reset failed'
       );
     }
@@ -1427,7 +2013,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     // `#fff`, `8px`, `700`, `1.5` all ride verbatim.
     return suppressedEdit(
       r.abs,
-      () => editAttribute(r.abs, id, `style.${camel}`, JSON.stringify(value)),
+      () => editAttribute(r.abs, id, `style.${camel}`, JSON.stringify(value), idIndex),
       'edit failed'
     );
   }
@@ -1478,6 +2064,18 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     const value = typeof input.value === 'string' ? input.value : '';
     if (!value.trim()) return { ok: false, status: 400, error: 'value required' };
     if (value.length > 256) return { ok: false, status: 413, error: 'value too long' };
+    // DDR-150 P3 — a media/image `src` edit (the clip-replace path) must stay a
+    // contained asset reference: no path traversal, no script/file/data schemes.
+    if (
+      attr === 'src' &&
+      (/\.\./.test(value) || /^\s*(javascript|vbscript|file|data):/i.test(value))
+    ) {
+      return {
+        ok: false,
+        status: 400,
+        error: 'src must be a contained asset path (no ../ or javascript:/file:/data: schemes)',
+      };
+    }
     // Non-`style.` attr name → editAttribute writes a plain quoted JSX attribute.
     // Pass the value RAW: editStringAttr quotes/escapes it itself (JSON.stringify
     // on replace, escapeAttr on insert) — pre-stringifying here double-encoded
@@ -1566,6 +2164,640 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
   }
 
+  /**
+   * DDR-148 — Timeline drag-to-retime. Rewrites the `durationInFrames` / `from`
+   * of the `index`-th sequence (document order). MAIN-ORIGIN ONLY at the route
+   * layer. Snapshots pre-retime for /design:rollback; suppresses the agent-rim.
+   */
+  async function retimeSequenceOp(input: {
+    canvas?: unknown;
+    stableId?: unknown;
+    artboardId?: unknown;
+    contentHash?: unknown;
+    index?: unknown;
+    durationInFrames?: unknown;
+    from?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    // DDR-150 P2 — prefer the comp-scoped stableId (multi-comp-safe) over the
+    // legacy whole-file index. The index path stays for back-compat.
+    const stableId = typeof input.stableId === 'string' ? input.stableId : null;
+    const artboardId = typeof input.artboardId === 'string' ? input.artboardId : undefined;
+    const contentHash = typeof input.contentHash === 'string' ? input.contentHash : undefined;
+    const index = Number.isInteger(input.index) ? (input.index as number) : -1;
+    if (!stableId && (index < 0 || index > 500))
+      return { ok: false, status: 400, error: 'invalid sequence index' };
+    const frames = (v: unknown, lo: number): number | undefined => {
+      const n = Math.round(Number(v));
+      return Number.isFinite(n) ? Math.max(lo, Math.min(100000, n)) : undefined;
+    };
+    const patch: { durationInFrames?: number; from?: number } = {};
+    if (input.durationInFrames != null) patch.durationInFrames = frames(input.durationInFrames, 1);
+    if (input.from != null) patch.from = frames(input.from, 0);
+    if (patch.durationInFrames == null && patch.from == null) {
+      return { ok: false, status: 400, error: 'nothing to retime' };
+    }
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      if (stableId) await retimeSequenceByClip(r.abs, artboardId, stableId, contentHash, patch);
+      else await retimeSequence(r.abs, index, patch);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-retime');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'retime failed',
+      };
+    }
+  }
+
+  async function removeSequenceOp(input: {
+    canvas?: unknown;
+    stableId?: unknown;
+    artboardId?: unknown;
+    contentHash?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    const stableId = typeof input.stableId === 'string' ? input.stableId : null;
+    if (!stableId) return { ok: false, status: 400, error: 'stableId required' };
+    const artboardId = typeof input.artboardId === 'string' ? input.artboardId : undefined;
+    const contentHash = typeof input.contentHash === 'string' ? input.contentHash : undefined;
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      await removeClip(r.abs, artboardId, stableId, contentHash);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-remove-clip');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'remove failed',
+      };
+    }
+  }
+
+  async function insertSequenceOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    from?: unknown;
+    durationInFrames?: unknown;
+    mediaTag?: unknown;
+    src?: unknown;
+  }): Promise<
+    | { ok: true; stableId: string | null; seq?: number }
+    | { ok: false; status: number; error: string }
+  > {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    const artboardId = typeof input.artboardId === 'string' ? input.artboardId : undefined;
+    const from = Number.isFinite(Number(input.from))
+      ? Math.max(0, Math.round(Number(input.from)))
+      : 0;
+    const durationInFrames = Number.isFinite(Number(input.durationInFrames))
+      ? Math.max(1, Math.min(100000, Math.round(Number(input.durationInFrames))))
+      : 90;
+    const mediaTag = typeof input.mediaTag === 'string' ? input.mediaTag : null;
+    const src = typeof input.src === 'string' ? input.src : null;
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      const res = await insertClip(r.abs, artboardId, { from, durationInFrames, mediaTag, src });
+      const after = await Bun.file(r.abs).text();
+      let seq: number | undefined;
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+      } else {
+        try {
+          await history.writeSnapshot(rel, before, 'pre-insert-clip');
+        } catch {
+          /* snapshot best-effort */
+        }
+        seq = logUndo(r.abs, before, after);
+      }
+      return { ok: true, stableId: res.stableId, seq };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'insert failed',
+      };
+    }
+  }
+
+  // Stage I (feature-element-editing-robustness) — general element structural
+  // edits (delete / insert / new-artboard) + free-hand artboard resize (D4). All
+  // MAIN-ORIGIN ONLY at the route layer; each logs a whole-file {before, after}
+  // under a seq (logUndo) so Cmd+Z reverts through /_api/reorder-revert (a
+  // structural edit renumbers positional data-cd-ids → an inverse descriptor
+  // goes stale). Same agent-rim suppression + pre-op snapshot as reorder.
+
+  /** Delete the element with `data-cd-id === id` (reused-component instance via idIndex). */
+  async function deleteElementOp(input: {
+    canvas?: unknown;
+    id?: unknown;
+    idIndex?: unknown;
+  }): Promise<
+    { ok: true; deletedId: string; seq?: number } | { ok: false; status: number; error: string }
+  > {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    if (!takeStructuralToken()) return RATE_LIMITED;
+    const id = typeof input.id === 'string' ? input.id.trim() : '';
+    if (!CD_ID_RE.test(id)) return { ok: false, status: 400, error: 'invalid data-cd-id' };
+    const idIndex = Number.isInteger(input.idIndex) ? (input.idIndex as number) : undefined;
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      const res = await deleteElement(r.abs, id, idIndex);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true, deletedId: res.deletedId };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-delete-element');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, deletedId: res.deletedId, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'delete failed',
+      };
+    }
+  }
+
+  /** Insert a synthesized element (div/text/image) relative to `refId`. */
+  async function insertElementOp(input: {
+    canvas?: unknown;
+    refId?: unknown;
+    position?: unknown;
+    kind?: unknown;
+    src?: unknown;
+    refIndex?: unknown;
+  }): Promise<
+    { ok: true; newId: string | null; seq?: number } | { ok: false; status: number; error: string }
+  > {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    if (!takeStructuralToken()) return RATE_LIMITED;
+    const refId = typeof input.refId === 'string' ? input.refId.trim() : '';
+    if (!CD_ID_RE.test(refId)) {
+      return { ok: false, status: 400, error: 'invalid reference data-cd-id' };
+    }
+    const position = input.position;
+    if (typeof position !== 'string' || !MOVE_POSITIONS.has(position)) {
+      return { ok: false, status: 400, error: 'invalid position' };
+    }
+    const kind = input.kind;
+    if (kind !== 'div' && kind !== 'text' && kind !== 'image') {
+      return { ok: false, status: 400, error: 'invalid kind (div|text|image)' };
+    }
+    const src = typeof input.src === 'string' ? input.src : undefined;
+    const refIndex = Number.isInteger(input.refIndex) ? (input.refIndex as number) : undefined;
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      if (before.length > MAX_CANVAS_SOURCE) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: false, status: 413, error: 'canvas source too large to grow' };
+      }
+      const res = await insertElement(r.abs, refId, position as MovePosition, kind as InsertKind, {
+        src,
+        occurrence: refIndex,
+      });
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true, newId: res.newId };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-insert-element');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, newId: res.newId, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'insert failed',
+      };
+    }
+  }
+
+  /** Insert a new empty artboard (id/label/width/height) after the last one. */
+  async function insertArtboardOp(input: {
+    canvas?: unknown;
+    id?: unknown;
+    label?: unknown;
+    width?: unknown;
+    height?: unknown;
+  }): Promise<
+    { ok: true; artboardId: string; seq?: number } | { ok: false; status: number; error: string }
+  > {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    if (!takeStructuralToken()) return RATE_LIMITED;
+    const id = typeof input.id === 'string' ? input.id.trim() : '';
+    if (!/^[A-Za-z][\w-]{0,63}$/.test(id)) {
+      return { ok: false, status: 400, error: 'invalid artboard id' };
+    }
+    const label = typeof input.label === 'string' ? input.label.slice(0, 120) : id;
+    const width = Number.isFinite(Number(input.width))
+      ? Math.max(64, Math.min(8192, Math.round(Number(input.width))))
+      : 0;
+    const height = Number.isFinite(Number(input.height))
+      ? Math.max(64, Math.min(8192, Math.round(Number(input.height))))
+      : 0;
+    if (!width || !height) return { ok: false, status: 400, error: 'width and height required' };
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      if (before.length > MAX_CANVAS_SOURCE) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: false, status: 413, error: 'canvas source too large to grow' };
+      }
+      const res = await insertArtboard(r.abs, { id, label, width, height });
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true, artboardId: res.artboardId };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-insert-artboard');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, artboardId: res.artboardId, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'insert-artboard failed',
+      };
+    }
+  }
+
+  /** Free-hand artboard resize (D4) — write width/height NUMERIC props (DDR-027). */
+  async function resizeArtboardOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    width?: unknown;
+    height?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    if (!takeStructuralToken()) return RATE_LIMITED;
+    const artboardId = typeof input.artboardId === 'string' ? input.artboardId.trim() : '';
+    if (!/^[A-Za-z][\w-]{0,63}$/.test(artboardId)) {
+      return { ok: false, status: 400, error: 'invalid artboard id' };
+    }
+    const dim = (v: unknown): number | undefined =>
+      Number.isFinite(Number(v)) ? Math.max(64, Math.min(8192, Math.round(Number(v)))) : undefined;
+    const width = dim(input.width);
+    const height = dim(input.height);
+    if (width == null && height == null) {
+      return { ok: false, status: 400, error: 'width or height required' };
+    }
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      await resizeArtboard(r.abs, artboardId, width, height);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-resize-artboard');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'resize-artboard failed',
+      };
+    }
+  }
+
+  /** Duplicate an element (Cmd+D) — insert a copy as the next sibling. */
+  async function duplicateElementOp(input: {
+    canvas?: unknown;
+    id?: unknown;
+    idIndex?: unknown;
+  }): Promise<
+    { ok: true; newId: string | null; seq?: number } | { ok: false; status: number; error: string }
+  > {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    if (!takeStructuralToken()) return RATE_LIMITED;
+    const id = typeof input.id === 'string' ? input.id.trim() : '';
+    if (!CD_ID_RE.test(id)) return { ok: false, status: 400, error: 'invalid data-cd-id' };
+    const idIndex = Number.isInteger(input.idIndex) ? (input.idIndex as number) : undefined;
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      if (before.length > MAX_CANVAS_SOURCE) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: false, status: 413, error: 'canvas source too large to grow' };
+      }
+      const res = await duplicateElement(r.abs, id, idIndex);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true, newId: res.newId };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-duplicate-element');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, newId: res.newId, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'duplicate failed',
+      };
+    }
+  }
+
+  /** Delete an artboard by its `id` prop (Backspace / context-menu on a frame). */
+  async function deleteArtboardOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    if (!takeStructuralToken()) return RATE_LIMITED;
+    const artboardId = typeof input.artboardId === 'string' ? input.artboardId.trim() : '';
+    if (!/^[A-Za-z][\w-]{0,63}$/.test(artboardId)) {
+      return { ok: false, status: 400, error: 'invalid artboard id' };
+    }
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      await deleteArtboard(r.abs, artboardId);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-delete-artboard');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'delete-artboard failed',
+      };
+    }
+  }
+
+  /**
+   * Edit-scope verdict for the INV-3 predictability badge (Stage H). READ-only —
+   * parses the canvas + returns whether an edit to `id` is local or shared. No
+   * write, no undo, no rate-cap (a mere parse the shell runs on selection). The
+   * client supplies `rendered` = the DOM occurrence count of the cd-id so the
+   * `.map()` case is honest.
+   */
+  async function editScopeOp(input: {
+    canvas?: unknown;
+    id?: unknown;
+    rendered?: unknown;
+  }): Promise<({ ok: true } & EditScope) | { ok: false; status: number; error: string }> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    const id = typeof input.id === 'string' ? input.id.trim() : '';
+    if (!CD_ID_RE.test(id)) return { ok: false, status: 400, error: 'invalid data-cd-id' };
+    const rendered = Number.isFinite(Number(input.rendered))
+      ? Math.max(1, Math.round(Number(input.rendered)))
+      : 1;
+    try {
+      const source = await Bun.file(r.abs).text();
+      const scope = resolveEditScope(r.abs, source, id, rendered);
+      return { ok: true, ...scope };
+    } catch (err) {
+      return { ok: false, status: 500, error: err instanceof Error ? err.message : 'scope failed' };
+    }
+  }
+
+  async function toggleHideOp(input: {
+    canvas?: unknown;
+    stableId?: unknown;
+    artboardId?: unknown;
+    contentHash?: unknown;
+  }): Promise<
+    { ok: true; hidden: boolean; seq?: number } | { ok: false; status: number; error: string }
+  > {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    const stableId = typeof input.stableId === 'string' ? input.stableId : null;
+    if (!stableId) return { ok: false, status: 400, error: 'stableId required' };
+    const artboardId = typeof input.artboardId === 'string' ? input.artboardId : undefined;
+    const contentHash = typeof input.contentHash === 'string' ? input.contentHash : undefined;
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      const res = await toggleClipHidden(r.abs, artboardId, stableId, contentHash);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true, hidden: res.hidden };
+      }
+      return { ok: true, hidden: res.hidden, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'hide failed',
+      };
+    }
+  }
+
+  async function editArraySrcOp(input: {
+    canvas?: unknown;
+    arrayName?: unknown;
+    index?: unknown;
+    field?: unknown;
+    value?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    const arrayName = typeof input.arrayName === 'string' ? input.arrayName : '';
+    const field = typeof input.field === 'string' ? input.field : 'src';
+    const index = Number.isInteger(input.index) ? (input.index as number) : -1;
+    const value = typeof input.value === 'string' ? input.value : '';
+    if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(arrayName)) {
+      return { ok: false, status: 400, error: 'invalid array name' };
+    }
+    if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(field)) {
+      return { ok: false, status: 400, error: 'invalid field' };
+    }
+    if (index < 0 || index > 500) return { ok: false, status: 400, error: 'invalid index' };
+    if (!value.trim()) return { ok: false, status: 400, error: 'value required' };
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      await editArrayElementString(r.abs, arrayName, index, field, value);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true };
+      }
+      return { ok: true, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'edit failed',
+      };
+    }
+  }
+
+  async function reorderSequenceOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    stableId?: unknown;
+    contentHash?: unknown;
+    refStableId?: unknown;
+    refContentHash?: unknown;
+    position?: unknown;
+  }): Promise<
+    | { ok: true; stableId: string | null; seq?: number }
+    | { ok: false; status: number; error: string }
+  > {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    const stableId = typeof input.stableId === 'string' ? input.stableId : null;
+    const refStableId = typeof input.refStableId === 'string' ? input.refStableId : null;
+    if (!stableId || !refStableId) {
+      return { ok: false, status: 400, error: 'stableId and refStableId required' };
+    }
+    const position: MovePosition = input.position === 'before' ? 'before' : 'after';
+    const artboardId = typeof input.artboardId === 'string' ? input.artboardId : undefined;
+    const contentHash = typeof input.contentHash === 'string' ? input.contentHash : undefined;
+    const refContentHash =
+      typeof input.refContentHash === 'string' ? input.refContentHash : undefined;
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      const res = await reorderClip(
+        r.abs,
+        artboardId,
+        stableId,
+        contentHash,
+        refStableId,
+        refContentHash,
+        position
+      );
+      const after = await Bun.file(r.abs).text();
+      let seq: number | undefined;
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+      } else {
+        try {
+          await history.writeSnapshot(rel, before, 'pre-reorder-clip');
+        } catch {
+          /* snapshot best-effort */
+        }
+        seq = logUndo(r.abs, before, after);
+      }
+      return { ok: true, stableId: res.stableId, seq };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'reorder failed',
+      };
+    }
+  }
+
+  async function compClips(input: { canvas?: unknown; artboardId?: unknown }) {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    const artboardId = typeof input.artboardId === 'string' ? input.artboardId : undefined;
+    try {
+      const source = await Bun.file(r.abs).text();
+      const result = enumerateClips(r.abs, source, artboardId);
+      // Strip the internal source offsets — the client addresses by stableId.
+      const clips = result.clips.map(({ start: _s, end: _e, ...c }) => c);
+      return {
+        ok: true as const,
+        compName: result.compName,
+        artboardId: result.artboardId,
+        fps: result.fps,
+        durationInFrames: result.durationInFrames,
+        clips,
+        // DDR-150 dogfood #5 — loose media beds (audio/bg video) for replace.
+        media: result.media,
+      };
+    } catch (err) {
+      return {
+        ok: false as const,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'enumerate failed',
+      };
+    }
+  }
+
   async function reorderRevert(input: {
     canvas?: unknown;
     seq?: unknown;
@@ -2009,10 +3241,13 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     loadCanvasState,
     saveCanvasState,
     loadCanvasMeta,
+    loadCanvasSource,
     patchCanvasMeta,
     loadAnnotations,
     saveAnnotations,
     saveAsset,
+    listAssets,
+    saveAssetFromStream,
     saveChatAttachment,
     resolveChatAttachment,
     createCanvas,
@@ -2020,7 +3255,21 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     editCss,
     editText,
     editAttr,
+    removeSequenceOp,
+    insertSequenceOp,
+    reorderSequenceOp,
+    editArraySrcOp,
+    toggleHideOp,
+    compClips,
     reorder,
+    retimeSequenceOp,
+    deleteElementOp,
+    insertElementOp,
+    insertArtboardOp,
+    resizeArtboardOp,
+    deleteArtboardOp,
+    duplicateElementOp,
+    editScopeOp,
     reorderRevert,
     buildIndexData,
     buildSystemData,