@1agh/maude 0.43.0 → 0.44.0

package/apps/studio/api.ts

@@ -34,9 +34,17 @@ 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';
 
@@ -257,6 +265,29 @@ 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[] }>;
@@ -441,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;
@@ -588,7 +635,7 @@ export interface AssetListing {
   path: string;
   name: string;
   ext: string;
-  kind: 'image' | 'video';
+  kind: 'image' | 'video' | 'audio';
   size: number;
   mtimeMs: number;
 }
@@ -1531,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);
@@ -1540,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;
@@ -1561,6 +1612,200 @@ 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
@@ -2660,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;
@@ -3003,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
@@ -3076,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;
       }
@@ -3140,6 +3526,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       designRoot: paths.designRel,
       groups,
       canvasDesignSystems,
+      canvasKinds,
     };
   }
 
@@ -3358,6 +3745,10 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     saveAnnotations,
     saveAsset,
     listAssets,
+    readAssetBytes,
+    writeCaptionSidecar,
+    writeAudioIntent,
+    searchAudioLibrary,
     listStickers,
     saveAssetFromStream,
     saveChatAttachment,
@@ -3379,6 +3770,8 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     insertElementOp,
     insertArtboardOp,
     resizeArtboardOp,
+    setArtboardHugOp,
+    setArtboardStyleOp,
     deleteArtboardOp,
     duplicateElementOp,
     editScopeOp,

package/apps/studio/bin/_audio-search.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env bun
+// _audio-search.mjs — internal shim behind `maude design audio-search` (DDR-062).
+// Reuse-before-you-pay for AUDIO (Task 2.5): before generating a new music/SFX/VO
+// track, search the project's OWN generated audio (intent sidecars) AND — when
+// ElevenLabs is configured — the user's re-downloadable History (free, already
+// paid), and prefer an existing suitable track over spending credits.
+//
+// The search + reuse run SERVER-SIDE (the key is resolved by the sidecar, never
+// handed to this CLI), so this verb is a pure fetch to the running dev server's
+// privileged /_api/generate/audio-search + /_api/generate/audio-reuse routes —
+// exactly like generate.sh. No client-side inference.
+//
+// Usage:
+//   audio-search.mjs --query "<text>" [--root <repo>] [--reuse <historyId>] [--json]
+//
+// Default: print ranked candidates (local assets + ElevenLabs history).
+// --reuse <historyId>: re-download that history item into assets/<sha8>.mp3 (NO
+//   credit) and print the localized path (for $(...) capture).
+//
+// Stdout (last line, --reuse): the localized `/assets/<sha8>.mp3` path.
+// Exit: 0 ok / 1 server problem / 2 bad args / 3 search/reuse failed.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => argv[++i];
+    if (a === '--query' || a === '-q') out.query = next();
+    else if (a === '--root') out.root = next();
+    else if (a === '--reuse') out.reuse = next();
+    else if (a === '--json') out.json = true;
+    else if (a === '--help' || a === '-h') out.help = true;
+    else if (!out.query && !a.startsWith('-')) out.query = a; // bare positional query
+  }
+  return out;
+}
+
+function resolvePort(repo) {
+  const serverPath = join(repo, '.design', '_server.json');
+  if (!existsSync(serverPath)) {
+    process.stderr.write(
+      'audio-search: no _server.json (start the dev server first: maude design server-up)\n'
+    );
+    process.exit(1);
+  }
+  try {
+    const port = JSON.parse(readFileSync(serverPath, 'utf8'))?.port;
+    if (port) return port;
+  } catch {
+    /* fall through */
+  }
+  process.stderr.write(`audio-search: could not read a port from ${serverPath}\n`);
+  process.exit(1);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || (!args.query && !args.reuse)) {
+    process.stderr.write(
+      'usage: maude design audio-search --query "<text>" [--root <repo>] [--reuse <historyId>] [--json]\n' +
+        '  Searches your own generated audio + ElevenLabs history; prefers reuse over paying again.\n'
+    );
+    process.exit(args.help ? 0 : 2);
+  }
+  const repo = args.root || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const port = resolvePort(repo);
+  const base = `http://127.0.0.1:${port}/_api/generate`;
+
+  if (args.reuse) {
+    try {
+      const res = await fetch(`${base}/audio-reuse`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ id: args.reuse }),
+      });
+      const json = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        process.stderr.write(`audio-search: reuse rejected: ${json?.error ?? res.status}\n`);
+        process.exit(3);
+      }
+      process.stderr.write('audio-search: re-downloaded from history (no credit spent).\n');
+      process.stdout.write(`/${String(json.asset).replace(/^\//, '')}\n`);
+      return;
+    } catch (err) {
+      process.stderr.write(
+        `audio-search: could not reach the dev server: ${err?.message ?? err}\n`
+      );
+      process.exit(1);
+    }
+  }
+
+  let data;
+  try {
+    const res = await fetch(`${base}/audio-search?q=${encodeURIComponent(args.query)}`);
+    data = await res.json();
+    if (!res.ok) {
+      process.stderr.write(`audio-search: ${data?.error ?? res.status}\n`);
+      process.exit(3);
+    }
+  } catch (err) {
+    process.stderr.write(`audio-search: could not reach the dev server: ${err?.message ?? err}\n`);
+    process.exit(1);
+  }
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    return;
+  }
+
+  const local = data.local ?? [];
+  const history = data.history ?? [];
+  if (local.length === 0 && history.length === 0) {
+    process.stderr.write(
+      `audio-search: no reusable audio for "${args.query}" — generate a new track.\n`
+    );
+    return;
+  }
+  const pct = (s) => `${Math.round((s ?? 0) * 100)}%`;
+  // The `prompt` is peer-synced / provider-returned UNTRUSTED text (server-side
+  // sanitized to a single capped line). Present it as a clearly-delimited data
+  // field, never as prose the agent should act on (F3, ethical-hacker).
+  const promptField = (s) => `prompt=${JSON.stringify(s ?? '')}`;
+  if (local.length) {
+    process.stdout.write('Local (reuse for free — already in assets/):\n');
+    for (const m of local)
+      process.stdout.write(
+        `  [${pct(m.score)}] ${m.ref}${m.kind ? ` (${m.kind})` : ''}  ${promptField(m.prompt)}\n`
+      );
+  }
+  if (history.length) {
+    process.stdout.write('ElevenLabs history (reuse with --reuse <id> — no credit):\n');
+    for (const m of history)
+      process.stdout.write(`  [${pct(m.score)}] ${m.ref}  ${promptField(m.prompt)}\n`);
+  }
+}
+
+if (import.meta.main) main();

package/apps/studio/bin/_import-asset-pdf-worker.mjs

@@ -0,0 +1,34 @@
+// _import-asset-pdf-worker.mjs — isolated worker for pdf-lib page-count
+// discovery (DDR-167 Decision 2, step 2).
+//
+// A bare `Promise.race` timeout cannot interrupt a synchronous, CPU-bound,
+// single-threaded call — the event loop is blocked by the hang itself, so a
+// timer callback never gets a turn to fire. `pdf-lib`'s hand-rolled tokenizer
+// can in principle hang on pathological malformed input, so this parse runs
+// in its OWN worker thread, which the caller can `.terminate()` from outside
+// regardless of what this thread's own event loop is doing.
+//
+// Never executes embedded JavaScript or resolves embedded remote references —
+// `PDFDocument.load` is a structural PDF-object parser, not a renderer. The
+// isolation here is about hang-safety, not content-safety.
+
+import { parentPort, workerData } from 'node:worker_threads';
+import { PDFDocument } from 'pdf-lib';
+
+async function main() {
+  try {
+    const bytes = new Uint8Array(workerData.buffer);
+    const doc = await PDFDocument.load(bytes, {
+      // Never attempt to resolve/repair encrypted or malformed structure —
+      // fail loud rather than silently coping with adversarial input.
+      ignoreEncryption: false,
+      throwOnInvalidObject: false,
+      updateMetadata: false,
+    });
+    parentPort.postMessage({ ok: true, pageCount: doc.getPageCount() });
+  } catch (err) {
+    parentPort.postMessage({ ok: false, error: String(err?.message ?? err) });
+  }
+}
+
+main();