@1agh/maude 0.42.0 → 0.44.0

package/apps/studio/api.ts

@@ -23,6 +23,7 @@ import {
   insertArtboard,
   insertClip,
   insertElement,
+  insertElementIntoArtboard,
   type MovePosition,
   moveElement,
   removeAttribute,
@@ -33,10 +34,19 @@ import {
   retimeSequence,
   retimeSequenceByClip,
   editText as runEditText,
+  setArtboardHug,
+  setArtboardStyle,
   toggleClipHidden,
 } from './canvas-edit.ts';
 import type { Context } from './context.ts';
+import {
+  type AudioMatch,
+  type Candidate,
+  rankMatches,
+  sanitizeReuseText,
+} from './generation/audio-library.ts';
 import { createHistory } from './history.ts';
+import { STICKERS_DIR } from './paths.ts';
 
 // Directories that never hold user-facing canvases. Exported so the
 // external-canvas watcher (`canvas-list-watch.ts`) shares one source instead of
@@ -255,6 +265,32 @@ export interface Api {
   saveAsset(bytes: Uint8Array): Promise<SaveAssetResult>;
   /** Stage F1 — list content-addressed image/video assets for the AssetPicker. */
   listAssets(): Promise<{ ok: true; assets: AssetListing[] }>;
+  /** feature-ai-media-generation (Task 1.2) — read a content-addressed
+   *  `assets/<sha8>.<ext>` source's bytes + sniffed mime for the image-edit /
+   *  image-to-video generation flows. Contained to <designRoot>/assets/;
+   *  null for an unknown/contained-out path. */
+  readAssetBytes(rel: unknown): Promise<{ bytes: Uint8Array; mime: string } | null>;
+  /** feature-ai-media-generation (Task 2.6) — write a caption sidecar
+   *  (`assets/<sha8>.srt|.vtt`) next to a content-addressed source, so a cloud
+   *  STT result lands where the local whisper path also writes it. Contained to
+   *  <designRoot>/assets/; text byte-capped; format allowlisted. */
+  writeCaptionSidecar(
+    sourceRel: unknown,
+    format: unknown,
+    text: unknown
+  ): Promise<{ ok: boolean; path?: string; error?: string }>;
+  /** feature-ai-media-generation (Task 2.5) — write the audio-intent sidecar
+   *  (`assets/<sha8>.audio.json`) for reuse-before-you-pay search. */
+  writeAudioIntent(
+    assetRel: unknown,
+    meta: { kind?: string; prompt?: string; provider?: string; model?: string; at?: string }
+  ): Promise<{ ok: boolean; path?: string; error?: string }>;
+  /** feature-ai-media-generation (Task 2.5) — keyword-search the project's own
+   *  generated audio by recorded intent; ranked reuse candidates. */
+  searchAudioLibrary(query: unknown, limit?: number): Promise<AudioMatch[]>;
+  /** Phase 4 (feature-whiteboard-annotation-improvements) — the bundled sticker
+   *  catalogue (MAUDE's own, not the served project's) for the StickerPicker. */
+  listStickers(): Promise<{ ok: true; packs: StickerPack[] }>;
   /** 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>;
@@ -288,7 +324,13 @@ export interface Api {
     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>;
+  editText(input: {
+    canvas?: unknown;
+    id?: unknown;
+    text?: unknown;
+    occurrence?: unknown;
+    before?: unknown;
+  }): Promise<EditOpResult>;
   // Phase 12.2 (DDR-104) — custom HTML attribute edit (POST /_api/edit-attr). Main-origin
   // only. The CSS panel's "custom HTML attribute" escape hatch (data-*, aria-*, role, …);
   // writes a plain JSX attribute via editAttribute's non-`style.` path.
@@ -396,10 +438,16 @@ export interface Api {
   }): Promise<
     { ok: true; deletedId: string; seq?: number } | { ok: false; status: number; error: string }
   >;
-  /** Insert a synthesized div/text/image relative to a reference element. */
+  /**
+   * Insert a synthesized div/text/image relative to a reference element, OR —
+   * when the artboard has no element to anchor on yet — as a direct child of
+   * `artboardId` (the tool-palette "+ Element" empty-artboard fallback).
+   * Exactly one of `refId` / `artboardId` must be provided.
+   */
   insertElementOp(input: {
     canvas?: unknown;
     refId?: unknown;
+    artboardId?: unknown;
     position?: unknown;
     kind?: unknown;
     src?: unknown;
@@ -424,6 +472,22 @@ export interface Api {
     width?: unknown;
     height?: unknown;
   }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
+  /** Toggle an artboard's Hug/Fixed height sizing mode (CSS-panel control). */
+  setArtboardHugOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    fixed?: unknown;
+    freezeHeight?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
+  /** Set artboard "more settings" — background / padding / layout / gap. */
+  setArtboardStyleOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    background?: unknown;
+    padding?: unknown;
+    layout?: unknown;
+    gap?: 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;
@@ -472,8 +536,19 @@ export { ASSET_IMAGE_HREF_RE, sanitizeAnnotationSvg } from './annotations-model.
 
 import { sanitizeAnnotationSvg } from './annotations-model.ts';
 
-/** Phase 23 — hard ceiling on a single uploaded asset (10 MB). */
-export const ASSET_MAX_BYTES = 10 * 1024 * 1024;
+/**
+ * Phase 23 — per-file ceiling for a still image. Raised 10 MB → 50 MB (still
+ * well under the video cap / MAX_REQUEST_BODY headroom) after a real drone
+ * photo tripped the old ceiling. Overridable via `MAUDE_ASSET_MAX_IMAGE_BYTES`
+ * (bytes), mirroring {@link ASSET_MAX_VIDEO_BYTES}'s override. The route lives
+ * on the (untrusted) canvas origin (DDR-088), and images stream through the
+ * same category-capped writer as video/audio (`saveAssetFromStream`), so
+ * raising this doesn't reintroduce the memory-amplification risk DDR-088 capped.
+ */
+export const ASSET_MAX_BYTES = (() => {
+  const env = Number(process.env.MAUDE_ASSET_MAX_IMAGE_BYTES);
+  return Number.isFinite(env) && env > 0 ? env : 50 * 1024 * 1024;
+})();
 
 /**
  * Phase 23 security review (DDR-088 follow-up) — aggregate per-server-instance
@@ -560,11 +635,29 @@ export interface AssetListing {
   path: string;
   name: string;
   ext: string;
-  kind: 'image' | 'video';
+  kind: 'image' | 'video' | 'audio';
   size: number;
   mtimeMs: number;
 }
 
+/** Phase 4 (feature-whiteboard-annotation-improvements) — one bundled sticker. */
+export interface StickerItem {
+  file: string;
+  keywords: string[];
+  /** Servable path — `/_stickers/<pack>/<file>` (main-origin static route). */
+  url: string;
+}
+
+/** A bundled sticker pack — one `apps/studio/stickers/<slug>/manifest.json`. */
+export interface StickerPack {
+  slug: string;
+  name: string;
+  author: string;
+  attributionUrl: string;
+  license: string;
+  stickers: StickerItem[];
+}
+
 /** DDR-148 — media category, decides which per-file cap applies. */
 export type AssetCategory = 'image' | 'video' | 'audio';
 
@@ -576,7 +669,7 @@ export interface AssetTypeInfo {
 
 /**
  * DDR-148 — per-file ceiling for time-based media (video + audio). Images keep
- * the tighter {@link ASSET_MAX_BYTES} 10 MB cap. Overridable via
+ * the tighter {@link ASSET_MAX_BYTES} 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).
@@ -595,7 +688,9 @@ 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';
+  if (category === 'image') {
+    return `image exceeds the ${Math.round(ASSET_MAX_BYTES / (1024 * 1024))} MB cap`;
+  }
   const mb = Math.round(ASSET_MAX_VIDEO_BYTES / (1024 * 1024));
   return `media exceeds the ${mb} MB cap`;
 }
@@ -1316,8 +1411,9 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   // optional (DDR Task 9):
   //   • magic-byte sniff → true type ∈ {png,jpg,gif,webp}; a header lie or an
   //     SVG (script-bearing vector) is rejected — bytes decide, name is ignored.
-  //   • ≤ 10 MB ceiling (assets get their OWN cap; never routed through the 1 MB
-  //     SVG-text gate in saveAnnotations).
+  //   • per-category ceiling ({@link ASSET_MAX_BYTES} for images; assets get
+  //     their OWN cap; never routed through the 1 MB SVG-text gate in
+  //     saveAnnotations).
   //   • content-addressed name `assets/<sha8-of-bytes>.<ext>` → identical drops
   //     dedupe → a malicious canvas can't fill the disk with N copies of one
   //     image, and orphan-on-delete is safe (shared content survives).
@@ -1331,8 +1427,8 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
    * 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
+   * not a few MB). Sniffs the type from the head, applies the CATEGORY cap while
+   * streaming (image {@link ASSET_MAX_BYTES} · 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.
@@ -1482,6 +1578,10 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     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']);
+    // feature-ai-media-generation Phase 2 — generated audio (ElevenLabs music /
+    // SFX / voiceover) is content-addressed under assets/ like any other media;
+    // surface it in the picker so a generated track can be dropped into an EDL.
+    const AUD = new Set(['.mp3', '.wav', '.m4a', '.aac', '.flac', '.oga', '.opus']);
     let entries: string[] = [];
     try {
       entries = await readdir(assetsDir);
@@ -1491,7 +1591,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     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;
+      const kind = IMG.has(ext) ? 'image' : VID.has(ext) ? 'video' : AUD.has(ext) ? 'audio' : null;
       if (!kind) continue;
       let size = 0;
       let mtimeMs = 0;
@@ -1512,6 +1612,253 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     return { ok: true, assets: out.slice(0, 500) };
   }
 
+  // feature-ai-media-generation (Task 1.2) — read a content-addressed source
+  // asset's bytes + authoritative (magic-byte-SNIFFED, not extension-trusted)
+  // mime, for the image-edit / image-to-video generation flows (Nano Banana
+  // maskless edit reads the source into an inlineData part). The provider adapter
+  // never touches the filesystem — the generation route wires this onto
+  // AdapterContext.readSourceAsset. Contained to <designRoot>/assets/ (an lstat
+  // isFile guard defeats a planted symlink, mirroring listAssets); returns null
+  // for an unknown / traversing / oversized path. Capped at ASSET_MAX_BYTES so a
+  // huge source can't be buffered into RAM before an outbound provider POST.
+  async function readAssetBytes(rel: unknown): Promise<{ bytes: Uint8Array; mime: string } | null> {
+    if (typeof rel !== 'string' || !rel.startsWith('assets/')) return null;
+    const name = rel.slice('assets/'.length);
+    if (
+      !name ||
+      name.includes('/') ||
+      name.includes('\\') ||
+      name.includes('..') ||
+      name.startsWith('_')
+    )
+      return null;
+    const assetsDir = path.join(paths.designRoot, 'assets');
+    const fileAbs = path.join(assetsDir, name);
+    // Containment backstop — the name is validated above; assert the join anyway.
+    if (path.resolve(fileAbs) !== path.join(path.resolve(assetsDir), name)) return null;
+    try {
+      const st = await lstat(fileAbs);
+      if (!st.isFile() || st.size > ASSET_MAX_BYTES) return null;
+    } catch {
+      return null;
+    }
+    const bytes = new Uint8Array(await readFile(fileAbs));
+    const info = sniffAssetType(bytes);
+    if (!info) return null; // not a recognised raster/video/audio — reject
+    const mime =
+      info.ext === 'jpg'
+        ? 'image/jpeg'
+        : info.category === 'image'
+          ? `image/${info.ext}`
+          : info.category === 'video'
+            ? `video/${info.ext}`
+            : `audio/${info.ext}`;
+    return { bytes, mime };
+  }
+
+  // feature-ai-media-generation (Task 2.6, DDR-164) — write a caption SIDECAR
+  // (SRT/VTT text) next to a content-addressed source asset, so a CLOUD STT
+  // result (ElevenLabs Scribe / Groq) lands in the SAME place the local whisper
+  // path writes it: `assets/<sha8>.srt` beside `assets/<sha8>.<ext>`. Local +
+  // cloud subtitles therefore live at one predictable path (the EDL caption
+  // track / a video-comp `<track>` reads `assets/<sha8>.srt`). The caption text
+  // is NOT run through the media magic-byte store (it isn't media) — it is a
+  // versioned text sidecar, mirroring `.meta.json` / `.annotations.svg`.
+  //
+  // Contained to <designRoot>/assets/ exactly like readAssetBytes: the source
+  // must be a validated `assets/<sha8>.<ext>` name, the format is allowlisted,
+  // and the text is byte-capped. Returns the sidecar rel path or null on a bad
+  // source / format.
+  async function writeCaptionSidecar(
+    sourceRel: unknown,
+    format: unknown,
+    text: unknown
+  ): Promise<{ ok: boolean; path?: string; error?: string }> {
+    if (typeof sourceRel !== 'string' || !sourceRel.startsWith('assets/'))
+      return { ok: false, error: 'source must be an assets/<sha8>.<ext> path' };
+    const srcName = sourceRel.slice('assets/'.length);
+    if (
+      !srcName ||
+      srcName.includes('/') ||
+      srcName.includes('\\') ||
+      srcName.includes('..') ||
+      srcName.startsWith('_')
+    )
+      return { ok: false, error: 'invalid source asset name' };
+    const fmt = format === 'vtt' ? 'vtt' : format === 'srt' ? 'srt' : null;
+    if (!fmt) return { ok: false, error: 'format must be srt or vtt' };
+    if (typeof text !== 'string' || !text.trim()) return { ok: false, error: 'empty caption text' };
+    if (text.length > 4 * 1024 * 1024) return { ok: false, error: 'caption text too large' };
+
+    // Strip the source extension → `<sha8>` (or the whole name if none), append
+    // the caption format. A dotless source name keeps its whole name as the base.
+    const dot = srcName.lastIndexOf('.');
+    const base = dot > 0 ? srcName.slice(0, dot) : srcName;
+    const outName = `${base}.${fmt}`;
+    const assetsDir = path.join(paths.designRoot, 'assets');
+    const fileAbs = path.join(assetsDir, outName);
+    if (path.resolve(fileAbs) !== path.join(path.resolve(assetsDir), outName))
+      return { ok: false, error: 'resolved sidecar path escapes assets dir' };
+    try {
+      await mkdir(assetsDir, { recursive: true });
+      await Bun.write(fileAbs, text);
+      return { ok: true, path: `assets/${outName}` };
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : 'sidecar write failed' };
+    }
+  }
+
+  // feature-ai-media-generation (Task 2.5, DDR-164) — write the AUDIO INTENT
+  // sidecar (`assets/<sha8>.audio.json`) next to a generated audio asset: the
+  // durable, semantic "what was this audio FOR" index that reuse-before-you-pay
+  // searches. Byte-content-addressing already dedups identical outputs; this adds
+  // the "do we already have a warm lo-fi loop?" lookup. Contained to assets/ like
+  // the caption sidecar; the intent is inert non-secret metadata.
+  async function writeAudioIntent(
+    assetRel: unknown,
+    meta: { kind?: string; prompt?: string; provider?: string; model?: string; at?: string }
+  ): Promise<{ ok: boolean; path?: string; error?: string }> {
+    if (typeof assetRel !== 'string' || !assetRel.startsWith('assets/'))
+      return { ok: false, error: 'asset must be an assets/<sha8>.<ext> path' };
+    const name = assetRel.slice('assets/'.length);
+    if (
+      !name ||
+      name.includes('/') ||
+      name.includes('\\') ||
+      name.includes('..') ||
+      name.startsWith('_')
+    )
+      return { ok: false, error: 'invalid asset name' };
+    const dot = name.lastIndexOf('.');
+    const base = dot > 0 ? name.slice(0, dot) : name;
+    const outName = `${base}.audio.json`;
+    const assetsDir = path.join(paths.designRoot, 'assets');
+    const fileAbs = path.join(assetsDir, outName);
+    if (path.resolve(fileAbs) !== path.join(path.resolve(assetsDir), outName))
+      return { ok: false, error: 'resolved sidecar path escapes assets dir' };
+    const record = {
+      asset: assetRel,
+      kind: meta.kind,
+      prompt: typeof meta.prompt === 'string' ? meta.prompt.slice(0, 8000) : undefined,
+      provider: meta.provider,
+      model: meta.model,
+      at: meta.at ?? new Date().toISOString(),
+    };
+    try {
+      await mkdir(assetsDir, { recursive: true });
+      await Bun.write(fileAbs, `${JSON.stringify(record, null, 2)}\n`);
+      return { ok: true, path: `assets/${outName}` };
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : 'intent write failed' };
+    }
+  }
+
+  // feature-ai-media-generation (Task 2.5) — search the project's OWN generated
+  // audio by intent (keyword overlap against the recorded prompt/kind), so the
+  // reuse-first path can offer an existing track before paying for a new
+  // generation. Reads the `assets/<sha8>.audio.json` sidecars; ranks with the
+  // shared pure scorer (generation/audio-library.ts) so local + provider-history
+  // results are comparable. Best-effort — a malformed sidecar is skipped.
+  async function searchAudioLibrary(query: unknown, limit = 10): Promise<AudioMatch[]> {
+    if (typeof query !== 'string' || !query.trim()) return [];
+    const assetsDir = path.join(paths.designRoot, 'assets');
+    let entries: string[];
+    try {
+      entries = await readdir(assetsDir);
+    } catch {
+      return [];
+    }
+    // F2 (ethical-hacker) — an intent sidecar is a peer-synced, hence UNTRUSTED
+    // (DDR-054), file: a hostile branch peer could commit a giant `.audio.json`
+    // or thousands of them to OOM the reader (the F1 RAM-DoS class, on disk). A
+    // real intent record is tiny → cap the per-file read AND the number scanned.
+    const MAX_SIDECAR_BYTES = 256 * 1024;
+    const MAX_SIDECARS = 4000;
+    const candidates: Candidate[] = [];
+    let scanned = 0;
+    for (const name of entries) {
+      if (!name.endsWith('.audio.json')) continue;
+      if (++scanned > MAX_SIDECARS) break;
+      try {
+        const fileAbs = path.join(assetsDir, name);
+        const st = await lstat(fileAbs);
+        if (!st.isFile() || st.size > MAX_SIDECAR_BYTES) continue;
+        const raw = await readFile(fileAbs, 'utf8');
+        const intent = JSON.parse(raw) as Record<string, unknown>;
+        const asset =
+          typeof intent.asset === 'string'
+            ? intent.asset
+            : `assets/${name.replace(/\.audio\.json$/, '')}`;
+        candidates.push({
+          source: 'local',
+          ref: asset,
+          // Sanitize the peer-synced (untrusted) prompt before it can be echoed
+          // into an agent context (F3).
+          text: sanitizeReuseText(intent.prompt),
+          kind: typeof intent.kind === 'string' ? intent.kind : undefined,
+          provider: typeof intent.provider === 'string' ? intent.provider : undefined,
+          at: typeof intent.at === 'string' ? intent.at : undefined,
+        });
+      } catch {
+        /* skip a malformed sidecar */
+      }
+    }
+    return rankMatches(query, candidates, { limit });
+  }
+
+  // Phase 4 (feature-whiteboard-annotation-improvements) — the bundled sticker
+  // catalogue for the StickerPicker. Reads from MAUDE's OWN `STICKERS_DIR`
+  // (paths.ts, DDR-045) — never the served project's designRoot, unlike
+  // listAssets above. A pack directory missing or with an invalid
+  // manifest.json is skipped, not fatal — one bad pack shouldn't blank the
+  // whole picker. MAIN-ORIGIN ONLY at the route layer (the picker is shell UI,
+  // same posture as listAssets/AssetPicker).
+  async function listStickers(): Promise<{ ok: true; packs: StickerPack[] }> {
+    let packDirs: string[] = [];
+    try {
+      const entries = await readdir(STICKERS_DIR, { withFileTypes: true });
+      packDirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    } catch {
+      return { ok: true, packs: [] }; // no bundled stickers in this layout
+    }
+    const packs: StickerPack[] = [];
+    for (const slug of packDirs) {
+      try {
+        const manifestPath = path.join(STICKERS_DIR, slug, 'manifest.json');
+        const raw = await readFile(manifestPath, 'utf8');
+        const manifest = JSON.parse(raw) as {
+          name?: string;
+          author?: string;
+          attributionUrl?: string;
+          license?: string;
+          stickers?: Array<{ file?: string; keywords?: string[] }>;
+        };
+        const stickers: StickerItem[] = (manifest.stickers ?? [])
+          .filter(
+            (s): s is { file: string; keywords?: string[] } =>
+              typeof s.file === 'string' && !!s.file
+          )
+          .map((s) => ({
+            file: s.file,
+            keywords: Array.isArray(s.keywords)
+              ? s.keywords.filter((k) => typeof k === 'string')
+              : [],
+            url: `/_stickers/${slug}/${encodeURIComponent(s.file)}`,
+          }));
+        packs.push({
+          slug,
+          name: manifest.name ?? slug,
+          author: manifest.author ?? '',
+          attributionUrl: manifest.attributionUrl ?? '',
+          license: manifest.license ?? '',
+          stickers,
+        });
+      } catch {}
+    }
+    packs.sort((a, b) => a.name.localeCompare(b.name));
+    return { ok: true, packs };
+  }
+
   // Phase 31 follow-up — persist an image pasted straight from the clipboard into
   // the ACP composer (a screenshot has no path yet), so the chip can point Claude
   // at a real file to Read. Sibling of saveAsset, but:
@@ -1519,13 +1866,17 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   //     the versioned `assets/`; pasted screenshots are ephemeral, not canvas media.
   //   • returns an ABSOLUTE path — Claude runs with its own cwd, so a project-
   //     relative string could miss; an absolute path always resolves.
-  // Same load-bearing caps as saveAsset (magic-byte sniff → no SVG/script, 10 MB,
-  // content-addressed name, shared session write budget). MAIN-ORIGIN ONLY at the
-  // route layer (the untrusted canvas can't reach it).
+  // Same load-bearing caps as saveAsset (magic-byte sniff → no SVG/script,
+  // ASSET_MAX_BYTES, content-addressed name, shared session write budget).
+  // MAIN-ORIGIN ONLY at the route layer (the untrusted canvas can't reach it).
   async function saveChatAttachment(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: 'attachment exceeds the 10 MB cap' };
+      return {
+        ok: false,
+        status: 413,
+        error: `attachment exceeds the ${Math.round(ASSET_MAX_BYTES / (1024 * 1024))} MB cap`,
+      };
     }
     const kind = sniffImageType(bytes);
     if (!kind) {
@@ -2009,6 +2360,8 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     canvas?: unknown;
     id?: unknown;
     text?: unknown;
+    occurrence?: unknown;
+    before?: unknown;
   }): Promise<EditOpResult> {
     const r = resolveCanvasAbs(input.canvas);
     if (!r.ok) return r;
@@ -2017,7 +2370,23 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     if (typeof input.text !== 'string') return { ok: false, status: 400, error: 'text required' };
     if (input.text.length > 5000) return { ok: false, status: 413, error: 'text too long' };
     const text = input.text;
-    return suppressedEdit(r.abs, () => runEditText(r.abs, id, text), 'edit failed');
+    // Optional context for editing `{variable}` text (unified-text-editing
+    // follow-up): which rendered instance, and its pre-edit text — both used
+    // only to target the right source string; a bad/absent value just makes an
+    // unresolvable expression edit fail loud (route to /design:edit).
+    const occurrence =
+      typeof input.occurrence === 'number' &&
+      Number.isInteger(input.occurrence) &&
+      input.occurrence >= 0
+        ? input.occurrence
+        : undefined;
+    const before =
+      typeof input.before === 'string' && input.before.length <= 5000 ? input.before : undefined;
+    return suppressedEdit(
+      r.abs,
+      () => runEditText(r.abs, id, text, { occurrence, before }),
+      'edit failed'
+    );
   }
 
   async function editAttr(input: {
@@ -2347,10 +2716,12 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
   }
 
-  /** Insert a synthesized element (div/text/image) relative to `refId`. */
+  /** Insert a synthesized element (div/text/image) relative to `refId`, or —
+   * empty-artboard fallback — as a direct child of `artboardId`. */
   async function insertElementOp(input: {
     canvas?: unknown;
     refId?: unknown;
+    artboardId?: unknown;
     position?: unknown;
     kind?: unknown;
     src?: unknown;
@@ -2361,14 +2732,30 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     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)) {
+    const hasRefId = typeof input.refId === 'string' && input.refId.trim() !== '';
+    const hasArtboardId = typeof input.artboardId === 'string' && input.artboardId.trim() !== '';
+    if (hasRefId === hasArtboardId) {
+      return { ok: false, status: 400, error: 'provide exactly one of refId / artboardId' };
+    }
+    const refId = hasRefId ? (input.refId as string).trim() : '';
+    if (hasRefId && !CD_ID_RE.test(refId)) {
       return { ok: false, status: 400, error: 'invalid reference data-cd-id' };
     }
+    const artboardId = hasArtboardId ? (input.artboardId as string).trim() : '';
+    if (hasArtboardId && !/^[A-Za-z][\w-]{0,63}$/.test(artboardId)) {
+      return { ok: false, status: 400, error: 'invalid artboard id' };
+    }
     const position = input.position;
     if (typeof position !== 'string' || !MOVE_POSITIONS.has(position)) {
       return { ok: false, status: 400, error: 'invalid position' };
     }
+    if (hasArtboardId && position !== 'inside-start' && position !== 'inside-end') {
+      return {
+        ok: false,
+        status: 400,
+        error: 'artboardId insert requires inside-start/inside-end',
+      };
+    }
     const kind = input.kind;
     if (kind !== 'div' && kind !== 'text' && kind !== 'image') {
       return { ok: false, status: 400, error: 'invalid kind (div|text|image)' };
@@ -2383,10 +2770,18 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
         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 res = hasArtboardId
+        ? await insertElementIntoArtboard(
+            r.abs,
+            artboardId,
+            position as 'inside-start' | 'inside-end',
+            kind as InsertKind,
+            { src }
+          )
+        : 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);
@@ -2510,6 +2905,137 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
   }
 
+  /** Toggle an artboard's Hug/Fixed height sizing mode (CSS-panel control). */
+  async function setArtboardHugOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    fixed?: unknown;
+    freezeHeight?: 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' };
+    }
+    if (typeof input.fixed !== 'boolean') {
+      return { ok: false, status: 400, error: 'fixed (boolean) required' };
+    }
+    const fixed = input.fixed;
+    const freezeHeight = Number.isFinite(Number(input.freezeHeight))
+      ? Math.max(64, Math.min(8192, Math.round(Number(input.freezeHeight))))
+      : 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 setArtboardHug(r.abs, artboardId, fixed, freezeHeight);
+      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-set-artboard-hug');
+      } 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 : 'set-artboard-hug failed',
+      };
+    }
+  }
+
+  const ARTBOARD_LAYOUT_VALUES = new Set(['block', 'flex-col', 'flex-row', 'grid']);
+
+  /** Set artboard "more settings" — background / padding / layout / gap. */
+  async function setArtboardStyleOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    background?: unknown;
+    padding?: unknown;
+    layout?: unknown;
+    gap?: 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 patch: {
+      background?: string | null;
+      padding?: number | null;
+      layout?: string | null;
+      gap?: number | null;
+    } = {};
+    if ('background' in input) {
+      if (input.background === null) patch.background = null;
+      else if (typeof input.background === 'string' && input.background.length <= 256) {
+        patch.background = input.background;
+      } else {
+        return { ok: false, status: 400, error: 'invalid background' };
+      }
+    }
+    if ('layout' in input) {
+      if (input.layout === null) patch.layout = null;
+      else if (typeof input.layout === 'string' && ARTBOARD_LAYOUT_VALUES.has(input.layout)) {
+        patch.layout = input.layout;
+      } else {
+        return { ok: false, status: 400, error: 'invalid layout' };
+      }
+    }
+    const clampBoxDim = (v: unknown): number | null | undefined => {
+      if (v === null) return null;
+      if (v === undefined) return undefined;
+      return Number.isFinite(Number(v)) ? Math.max(0, Math.min(512, Math.round(Number(v)))) : NaN;
+    };
+    if ('padding' in input) {
+      const p = clampBoxDim(input.padding);
+      if (Number.isNaN(p)) return { ok: false, status: 400, error: 'invalid padding' };
+      patch.padding = p;
+    }
+    if ('gap' in input) {
+      const g = clampBoxDim(input.gap);
+      if (Number.isNaN(g)) return { ok: false, status: 400, error: 'invalid gap' };
+      patch.gap = g;
+    }
+    if (Object.keys(patch).length === 0) {
+      return { ok: false, status: 400, error: 'no style props given' };
+    }
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      await setArtboardStyle(r.abs, artboardId, 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-set-artboard-style');
+      } 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 : 'set-artboard-style failed',
+      };
+    }
+  }
+
   /** Duplicate an element (Cmd+D) — insert a copy as the next sibling. */
   async function duplicateElementOp(input: {
     canvas?: unknown;
@@ -2853,6 +3379,14 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     // instead of unconditionally designSystems[0]. Populated from the canvas
     // groups below; returned on the payload and folded into the client cfg.
     const canvasDesignSystems: Record<string, string> = {};
+    // DDR-174 (T15) — surface a canvas's `.meta.json` `kind` in the file tree
+    // when it's a value the user should notice at a glance (today: only
+    // `reconstructed-experimental`, so this map stays empty on every project
+    // that hasn't run `/design:import --reconstruct`). Piggybacks on the same
+    // `loadCanvasMeta` call the DDR-093 DS-map loop below already makes for
+    // non-path-owned (`ui/`) canvases — no extra I/O for the common case.
+    const canvasKinds: Record<string, string> = {};
+    const NOTABLE_KINDS = new Set(['reconstructed-experimental']);
     const defaultDs = cfg.defaultDesignSystem || cfg.designSystems?.[0]?.name || 'project';
     // A file under `system/<folder>/` belongs to the DS that owns that folder —
     // path-authoritative, because specimens/ui_kits rarely carry a sidecar
@@ -2926,6 +3460,8 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
           const meta = await loadCanvasMeta(fp);
           const declared = meta?.designSystem;
           dsName = typeof declared === 'string' && declared.trim() ? declared : defaultDs;
+          const kind = meta?.kind;
+          if (typeof kind === 'string' && NOTABLE_KINDS.has(kind)) canvasKinds[fp] = kind;
         }
         canvasDesignSystems[fp] = dsName;
       }
@@ -2990,6 +3526,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       designRoot: paths.designRel,
       groups,
       canvasDesignSystems,
+      canvasKinds,
     };
   }
 
@@ -3208,6 +3745,11 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     saveAnnotations,
     saveAsset,
     listAssets,
+    readAssetBytes,
+    writeCaptionSidecar,
+    writeAudioIntent,
+    searchAudioLibrary,
+    listStickers,
     saveAssetFromStream,
     saveChatAttachment,
     resolveChatAttachment,
@@ -3228,6 +3770,8 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     insertElementOp,
     insertArtboardOp,
     resizeArtboardOp,
+    setArtboardHugOp,
+    setArtboardStyleOp,
     deleteArtboardOp,
     duplicateElementOp,
     editScopeOp,