@1agh/maude 0.45.2 → 0.46.0

package/apps/studio/exporters/png.ts

@@ -12,6 +12,7 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import JSZip from 'jszip';
+import { CSS_DPI } from '../print/units.ts';
 import { exportShimPath, runShim } from './_runtime.ts';
 import {
   canvasShellUrl,
@@ -27,7 +28,8 @@ import type { Target } from './scope.ts';
 const PNG_PLAYWRIGHT = exportShimPath('_png-playwright.mjs');
 
 interface CaptureOptions {
-  scale?: 1 | 2 | 3;
+  /** Fully-resolved Playwright deviceScaleFactor — see resolveDeviceScale. */
+  scale?: number;
   timeoutSec?: number;
 }
 
@@ -42,6 +44,44 @@ export function clampScale(raw: unknown): 1 | 2 | 3 {
   return 2;
 }
 
+/** feature-2-print-artboards T4 — supported DPI presets (Adobe-conventional
+ *  print ladder). Exported for unit coverage. */
+export const DPI_PRESETS = [96, 150, 300, 600] as const;
+export type DpiPreset = (typeof DPI_PRESETS)[number];
+
+/** Coerce an arbitrary `options.dpi` to the nearest supported preset, or
+ *  `undefined` when absent/invalid (caller then falls back to `scale`). */
+export function clampDpi(raw: unknown): DpiPreset | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return undefined;
+  let best: DpiPreset = DPI_PRESETS[0];
+  let bestDelta = Math.abs(n - best);
+  for (const preset of DPI_PRESETS) {
+    const delta = Math.abs(n - preset);
+    if (delta < bestDelta) {
+      best = preset;
+      bestDelta = delta;
+    }
+  }
+  return best;
+}
+
+/**
+ * The Playwright `deviceScaleFactor` for a capture — `dpi` (physical print
+ * resolution) wins when present, else the legacy 1×/2×/3× UI preset.
+ * `dpi/96` because authoring is at CSS px @96dpi (print/units.ts CSS_DPI) —
+ * this is the ONE place outside that module allowed to divide by 96 (a
+ * device-scale-factor derivation, not an mm→px conversion, so it's exempt
+ * from the T1 single-source `25.4` lint guard, but stays in lockstep with
+ * CSS_DPI by importing it rather than hardcoding 96 again).
+ */
+export function resolveDeviceScale(options: ExportOptions): number {
+  const dpi = clampDpi(options.dpi);
+  if (dpi !== undefined) return dpi / CSS_DPI;
+  return clampScale(options.scale);
+}
+
 async function captureElement(
   target: Extract<Target, { kind: 'element' }>,
   ctx: ExportContext,
@@ -112,8 +152,10 @@ export async function run(
   const captureOpts: CaptureOptions = {
     // Default 2× — a single-scale PNG was uselessly small (item 1). The dialog
     // sends an explicit scale; this default covers direct API / curl callers.
-    // Clamped to the 1–3 preset range; the shim re-clamps deviceScaleFactor ≤ 4.
-    scale: clampScale(options.scale),
+    // feature-2-print-artboards T4 — `options.dpi` (96/150/300/600) wins over
+    // the legacy 1–3 preset when present; the shim re-clamps deviceScaleFactor
+    // ≤ 8 and guards oversized output (see _png-playwright.mjs).
+    scale: resolveDeviceScale(options),
     timeoutSec: (options.timeoutSec as number | undefined) ?? 8,
   };
 

package/apps/studio/footage/schema.ts

@@ -150,6 +150,10 @@ export interface FootageAnalysis {
   summary?: string;
   /** Cross-cutting tags ("rebrand", "exterior", "people"). */
   tags?: string[];
+  /** Optional audio/speech note — gist + language of what is said, filled ONLY when
+   *  an orchestrator (e.g. /design:video-analyze) hands the analyst a transcript.
+   *  Absent for the default vision-only path (e.g. /design:reel). */
+  speech?: string;
 }
 
 /** An optional graphic overlay laid over a beat (title card / lower-third / logo). */
@@ -437,7 +441,18 @@ export function validateFootageAnalysis(input: unknown): ValidationResult {
   assertKeys(
     errors,
     input,
-    ['version', 'asset', 'durationSec', 'width', 'height', 'keyframes', 'shots', 'summary', 'tags'],
+    [
+      'version',
+      'asset',
+      'durationSec',
+      'width',
+      'height',
+      'keyframes',
+      'shots',
+      'summary',
+      'tags',
+      'speech',
+    ],
     'root'
   );
   if ('version' in input && input.version != null && typeof input.version !== 'number')
@@ -449,6 +464,7 @@ export function validateFootageAnalysis(input: unknown): ValidationResult {
   intGe(errors, input, 'keyframes', 0, 'root');
   str(errors, input, 'summary', 4000, 'root');
   strArray(errors, input, 'tags', 64, 'root');
+  str(errors, input, 'speech', 4000, 'root');
 
   const dur = typeof input.durationSec === 'number' ? input.durationSec : Infinity;
   if ('shots' in input && input.shots != null) {

package/apps/studio/generation/gemma-models.ts

@@ -0,0 +1,224 @@
+// generation/gemma-models.ts — managed local Gemma-4 MLX models for the `gemma`
+// tier of `maude design smart-frames` (feature-scene-aware-keyframes). The
+// "one-click Gemma scout" story, mirroring whisper-models.ts — but with three
+// real differences from whisper:
+//
+//   1. Apple-Silicon only. The scout runs through mlx-vlm (a Python package); the
+//      model is useless without it. So the download is GATED on `mlxVlmAvailable`.
+//   2. Multi-file HF snapshot, not a single .bin. mlx-vlm resolves a model from the
+//      standard HuggingFace hub cache, so we download THERE (via huggingface_hub,
+//      a transitive dep of mlx-vlm) rather than a Maude-private cache — otherwise
+//      mlx-vlm wouldn't find it. "downloaded" = the snapshot is in the HF cache.
+//   3. The RUNTIME (mlx-vlm itself) is a manual `pip install` the app can't do for
+//      you — the Settings card says so and only the MODEL half is one click.
+//
+// This module owns the registry + availability probes + the HF-cache-aware
+// downloaded check + resolve. The download SPAWN lives here (it shells the mlx
+// Python's huggingface_hub); the http route wraps it with progress state, next to
+// the other provider egress.
+
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export interface GemmaModelDescriptor {
+  /** Stable id used by the pref + route. */
+  id: string;
+  /** The mlx-community HF repo (also the `--model` mlx-vlm resolves). */
+  repo: string;
+  /** Pinned commit SHA — the download fetches THIS revision, never floating `main`,
+   *  so a poisoned-main / namespace-reuse push can't land arbitrary model files
+   *  (DDR-183 supply-chain finding; the whisper baseline pins exact file URLs). */
+  revision: string;
+  label: string;
+  /** Approximate on-disk size (consent copy). */
+  sizeMB: number;
+  note: string;
+}
+
+// Curated allowlist of Gemma-4 MLX scout models. `repo` + `revision` are the frozen
+// download target (never user input). e4b is the default (better beats); e2b is the
+// small, fast option for lower-RAM Macs. Revisions pinned 2026-07-16.
+export const GEMMA_MODELS: readonly GemmaModelDescriptor[] = [
+  {
+    id: 'gemma-4-e4b-it-4bit',
+    repo: 'mlx-community/gemma-4-e4b-it-4bit',
+    revision: '475b9088d29754a3379866cf5aeb6b41acd313c2',
+    label: 'Gemma 4 E4B (4-bit)',
+    sizeMB: 3300,
+    note: 'The recommended scout — best semantic beats. ~3.3 GB. Needs an Apple-Silicon Mac + mlx-vlm.',
+  },
+  {
+    id: 'gemma-4-e2b-it-4bit',
+    repo: 'mlx-community/gemma-4-e2b-it-4bit',
+    revision: '238767527555cb75a05732a84dff5d6ba0dd6809',
+    label: 'Gemma 4 E2B (4-bit)',
+    sizeMB: 1900,
+    note: 'Smaller/faster, coarser beats. ~1.9 GB. Good for 16 GB Macs.',
+  },
+];
+
+export function getGemmaModel(id: unknown): GemmaModelDescriptor | null {
+  return GEMMA_MODELS.find((m) => m.id === id) ?? null;
+}
+
+/** The HuggingFace hub cache dir mlx-vlm resolves models from (HF_HOME-aware). */
+export function hfHubDir(): string {
+  const hfHome = process.env.HF_HOME;
+  if (hfHome && hfHome.length > 0) return join(hfHome, 'hub');
+  const base = process.env.XDG_CACHE_HOME || join(homedir(), '.cache');
+  return join(base, 'huggingface', 'hub');
+}
+
+/** HF snapshot dir name for a repo: `models--<org>--<name>`. */
+function repoCacheDir(repo: string): string {
+  return join(hfHubDir(), `models--${repo.replace('/', '--')}`);
+}
+
+/** A model counts as downloaded when its HF snapshot dir has a non-empty snapshot. */
+export function gemmaModelDownloaded(m: GemmaModelDescriptor): boolean {
+  const snaps = join(repoCacheDir(m.repo), 'snapshots');
+  try {
+    if (!existsSync(snaps)) return false;
+    for (const rev of readdirSync(snaps)) {
+      const revDir = join(snaps, rev);
+      try {
+        if (statSync(revDir).isDirectory() && readdirSync(revDir).length > 0) return true;
+      } catch {
+        /* skip */
+      }
+    }
+  } catch {
+    /* not downloaded */
+  }
+  return false;
+}
+
+export interface GemmaModelStatus extends GemmaModelDescriptor {
+  downloaded: boolean;
+}
+
+export function listGemmaModels(): GemmaModelStatus[] {
+  return GEMMA_MODELS.map((m) => ({ ...m, downloaded: gemmaModelDownloaded(m) }));
+}
+
+/** Resolve a Python that can `import mlx_vlm` (honors $MAUDE_MLX_PYTHON), or null. */
+export function resolveMlxPython(): string | null {
+  const candidates = [process.env.MAUDE_MLX_PYTHON, 'python3', 'python'].filter(
+    Boolean
+  ) as string[];
+  for (const py of candidates) {
+    const r = spawnSync(py, ['-c', 'import mlx_vlm'], { stdio: 'ignore' });
+    if (r.status === 0) return py;
+  }
+  return null;
+}
+
+// Availability probes spawn subprocesses (importing mlx_vlm can take hundreds of ms
+// to seconds). The GET /_api/generate/keyframe-model route is un-CSRF-gated (correct
+// for a read), so a cross-origin drive-by could hammer it and stall the single-
+// threaded Bun event loop on synchronous spawns (security-auditor DDR-183 finding).
+// Memoize with a short TTL: DoS-bounded to at most one probe per PROBE_TTL_MS
+// regardless of request rate, while still picking up a mid-session `pip install` /
+// PATH change within the TTL.
+const PROBE_TTL_MS = 30_000;
+const probeCache = new Map<string, { at: number; value: boolean }>();
+
+function cachedProbe(key: string, compute: () => boolean): boolean {
+  const now = Date.now();
+  const hit = probeCache.get(key);
+  if (hit && now - hit.at < PROBE_TTL_MS) return hit.value;
+  const value = compute();
+  probeCache.set(key, { at: now, value });
+  return value;
+}
+
+export function mlxVlmAvailable(): boolean {
+  return cachedProbe('mlx', () => resolveMlxPython() !== null);
+}
+
+export function ffmpegAvailable(): boolean {
+  return cachedProbe('ffmpeg', () => {
+    const finder = process.platform === 'win32' ? 'where' : 'which';
+    return (
+      spawnSync(finder, ['ffmpeg'], { stdio: 'ignore' }).status === 0 &&
+      spawnSync(finder, ['ffprobe'], { stdio: 'ignore' }).status === 0
+    );
+  });
+}
+
+/**
+ * Download a Gemma model into the HF hub cache via huggingface_hub (a transitive
+ * dep of mlx-vlm, so it's present whenever the scout can actually run). We delegate
+ * to Python rather than reimplement multi-file HF snapshot download + LFS/Xet
+ * redirect handling in TS — the repo id is frozen (never user input), the runtime
+ * is pinned to the mlx Python, and the route is loopback + same-origin only.
+ * Progress is coarse (tqdm on stderr → a heartbeat), which the route surfaces as an
+ * in-flight state. Rejects if mlx-vlm/Python is absent (you couldn't run the model
+ * anyway) or the process exits non-zero.
+ */
+export function downloadGemmaModel(
+  id: string,
+  onProgress: (received: number, total: number) => void,
+  signal?: AbortSignal
+): Promise<void> {
+  const m = getGemmaModel(id);
+  if (!m) return Promise.reject(new Error(`unknown gemma model: ${id}`));
+  const py = resolveMlxPython();
+  if (!py)
+    return Promise.reject(
+      new Error(
+        'mlx-vlm not installed — the Gemma scout needs an Apple-Silicon Mac + `pip install mlx-vlm`.'
+      )
+    );
+
+  // Refuse a steered HF endpoint (mirror/redirect) — the whisper path pins the host;
+  // huggingface_hub otherwise honors HF_ENDPOINT/HF_HUB_ENDPOINT. Keep the pull on
+  // the canonical hub (DDR-183 supply-chain finding).
+  const endpoint = process.env.HF_ENDPOINT || process.env.HF_HUB_ENDPOINT;
+  if (endpoint && !/^https:\/\/huggingface\.co\/?$/.test(endpoint))
+    return Promise.reject(new Error(`refusing model download: HF endpoint steered to ${endpoint}`));
+
+  const total = m.sizeMB * 1024 * 1024;
+  return new Promise((resolve, reject) => {
+    // snapshot_download(repo, revision=<pinned sha>) — repo AND revision are from the
+    // frozen registry (never user input), passed as argv (not interpolated into -c).
+    const child = spawn(
+      py,
+      [
+        '-c',
+        'import sys; from huggingface_hub import snapshot_download; snapshot_download(sys.argv[1], revision=sys.argv[2])',
+        m.repo,
+        m.revision,
+      ],
+      {
+        stdio: ['ignore', 'ignore', 'pipe'],
+        env: { ...process.env, HF_HUB_DISABLE_TELEMETRY: '1' },
+      }
+    );
+    let received = 0;
+    const onAbort = () => child.kill('SIGTERM');
+    signal?.addEventListener('abort', onAbort, { once: true });
+    // tqdm writes percentage lines to stderr; use them as a coarse heartbeat.
+    child.stderr?.on('data', (buf: Buffer) => {
+      const s = buf.toString();
+      const pct = /(\d{1,3})%/.exec(s);
+      if (pct) received = Math.min(total, Math.round((Number(pct[1]) / 100) * total));
+      onProgress(received, total);
+    });
+    child.on('error', (err) => {
+      signal?.removeEventListener('abort', onAbort);
+      reject(err);
+    });
+    child.on('close', (code) => {
+      signal?.removeEventListener('abort', onAbort);
+      if (code === 0 && gemmaModelDownloaded(m)) {
+        onProgress(total, total);
+        resolve();
+      } else {
+        reject(new Error(`gemma model download failed (exit ${code})`));
+      }
+    });
+  });
+}

package/apps/studio/generation/prefs.ts

@@ -20,6 +20,16 @@ export function isTranscriptionProvider(v: unknown): v is TranscriptionProvider
   return typeof v === 'string' && (TRANSCRIPTION_PROVIDERS as readonly string[]).includes(v);
 }
 
+/** Scene-aware keyframe engines (feature-scene-aware-keyframes) — the tier the
+ *  `gemma` scout → `ffmpeg` scene-detect → `blind` Chromium fallback ladder runs
+ *  in. `auto` self-detects installed deps. */
+export const KEYFRAME_ENGINES = ['auto', 'gemma', 'ffmpeg', 'blind'] as const;
+export type KeyframeEngine = (typeof KEYFRAME_ENGINES)[number];
+
+export function isKeyframeEngine(v: unknown): v is KeyframeEngine {
+  return typeof v === 'string' && (KEYFRAME_ENGINES as readonly string[]).includes(v);
+}
+
 function configPath(repoRoot: string): string {
   return join(repoRoot, '.design', 'config.json');
 }
@@ -80,3 +90,36 @@ export async function writeTranscriptionProvider(
   await Bun.write(configPath(repoRoot), `${JSON.stringify(next, null, 2)}\n`);
   return true;
 }
+
+/** The current scene-aware keyframe engine preference, or 'auto' (the default). */
+export function readKeyframeEngine(repoRoot: string): KeyframeEngine {
+  const cfg = readConfig(repoRoot);
+  const gen = cfg.generation as Record<string, unknown> | undefined;
+  const kf = gen?.keyframes as Record<string, unknown> | undefined;
+  return isKeyframeEngine(kf?.engine) ? (kf?.engine as KeyframeEngine) : 'auto';
+}
+
+/**
+ * Persist the keyframe-engine choice into `.design/config.json`, preserving every
+ * other field (same additive-merge + fail-closed-on-corrupt discipline as the
+ * transcription writer).
+ */
+export async function writeKeyframeEngine(repoRoot: string, engine: string): Promise<boolean> {
+  if (!isKeyframeEngine(engine)) throw new Error(`invalid keyframe engine: ${engine}`);
+  const p = configPath(repoRoot);
+  if (existsSync(p)) {
+    try {
+      JSON.parse(readFileSync(p, 'utf8'));
+    } catch {
+      throw new Error(
+        '.design/config.json is present but not valid JSON — fix it before changing generation prefs (refusing to overwrite it)'
+      );
+    }
+  }
+  const cfg = readConfig(repoRoot);
+  const gen = (cfg.generation as Record<string, unknown>) ?? {};
+  const keyframes = (gen.keyframes as Record<string, unknown>) ?? {};
+  const next = { ...cfg, generation: { ...gen, keyframes: { ...keyframes, engine } } };
+  await Bun.write(configPath(repoRoot), `${JSON.stringify(next, null, 2)}\n`);
+  return true;
+}

package/apps/studio/http.ts

@@ -40,6 +40,12 @@ import {
   sanitizeReuseText,
 } from './generation/audio-library.ts';
 import { localizeGenAsset } from './generation/download.ts';
+import {
+  downloadGemmaModel,
+  ffmpegAvailable,
+  listGemmaModels,
+  mlxVlmAvailable,
+} from './generation/gemma-models.ts';
 import { type GenerationJobQueue, GenerationQueueFullError } from './generation/jobs.ts';
 import {
   configuredProviders,
@@ -49,8 +55,11 @@ import {
   setProviderKey,
 } from './generation/keys.ts';
 import {
+  isKeyframeEngine,
   isTranscriptionProvider,
+  readKeyframeEngine,
   readTranscriptionProvider,
+  writeKeyframeEngine,
   writeTranscriptionProvider,
 } from './generation/prefs.ts';
 import {
@@ -691,6 +700,12 @@ export function createHttp(
     error?: string;
   } | null = null;
 
+  // feature-scene-aware-keyframes — in-flight Gemma-model download state, polled by
+  // the Settings "Scene-aware keyframes" card via GET /_api/generate/keyframe-model.
+  // Closure-scoped: one server, one download.
+  let keyframeDownload: { id: string; received: number; total: number; error?: string } | null =
+    null;
+
   // Cache invalidation — when canvas-lib changes, every cached canvas bundle
   // is stale because canvas-lib is inlined into each one via the resolver
   // plugin. Drop the whole cache so the next request rebuilds with the fresh
@@ -2421,6 +2436,98 @@ export function createHttp(
       );
     },
 
+    '/_api/set-artboard-kind': async (req: Request) => {
+      // feature-1-artboard-kinds-foundation, T8. POST { canvas, artboardId,
+      // kind: 'digital'|'print'|'web'|'video'|null } → api.setArtboardKindOp.
+      // `null` clears the explicit prop back to the implicit default. Whole-
+      // file undo seq. MAIN-ORIGIN ONLY; same gate pair as set-artboard-style
+      // (the kind-switch surfaces — context menu, Inspector — are shell UI,
+      // never reachable from the untrusted canvas origin).
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      const body = await readJson<{
+        canvas?: unknown;
+        artboardId?: unknown;
+        kind?: unknown;
+      }>(req, 2 * 1024);
+      if (!body) return new Response('body required', { status: 400 });
+      const result = await api.setArtboardKindOp(body);
+      if (!result.ok) {
+        return Response.json(
+          { ok: false, error: result.error },
+          { status: result.status, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      return Response.json(
+        { ok: true, seq: result.seq },
+        { status: 200, headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
+    '/_api/set-artboard-guides': async (req: Request) => {
+      // feature-1-artboard-kinds-foundation, T5. POST { canvas, artboardId,
+      // guides: {...}|null } → api.setArtboardGuidesOp. REPLACE-whole-prop
+      // (see applySetArtboardGuides doc comment) — the caller sends the full
+      // merged object, not a delta. MAIN-ORIGIN ONLY; same gate pair as
+      // set-artboard-style.
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      const body = await readJson<{
+        canvas?: unknown;
+        artboardId?: unknown;
+        guides?: unknown;
+      }>(req, 8 * 1024);
+      if (!body) return new Response('body required', { status: 400 });
+      const result = await api.setArtboardGuidesOp(body);
+      if (!result.ok) {
+        return Response.json(
+          { ok: false, error: result.error },
+          { status: result.status, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      return Response.json(
+        { ok: true, seq: result.seq },
+        { status: 200, headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
+    '/_api/set-artboard-print': async (req: Request) => {
+      // feature-2-print-artboards T2. POST { canvas, artboardId, print:
+      // {paper, orientation?, bleedMm?, marginsMm?}|null } → api.setArtboardPrintOp.
+      // REPLACE-whole-prop (see applySetArtboardPrint's own doc comment) — the
+      // caller sends the full merged object, not a delta. MAIN-ORIGIN ONLY;
+      // same gate pair as set-artboard-guides (Inspector picker is shell UI,
+      // never reachable from the untrusted canvas origin).
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      const body = await readJson<{
+        canvas?: unknown;
+        artboardId?: unknown;
+        print?: unknown;
+      }>(req, 2 * 1024);
+      if (!body) return new Response('body required', { status: 400 });
+      const result = await api.setArtboardPrintOp(body);
+      if (!result.ok) {
+        return Response.json(
+          { ok: false, error: result.error },
+          { status: result.status, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      return Response.json(
+        { ok: true, seq: result.seq },
+        { status: 200, headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
     '/_api/delete-artboard': async (req: Request) => {
       // Delete an artboard by its `id` prop (Backspace / context-menu on a frame).
       // POST { canvas, artboardId } → api.deleteArtboardOp (removes the
@@ -2942,20 +3049,38 @@ export function createHttp(
         return new Response('local request required (DNS-rebinding guard)', { status: 403 });
       if (req.method === 'GET') {
         return Response.json(
-          { transcriptionProvider: readTranscriptionProvider(ctx.paths.repoRoot) },
+          {
+            transcriptionProvider: readTranscriptionProvider(ctx.paths.repoRoot),
+            keyframeEngine: readKeyframeEngine(ctx.paths.repoRoot),
+          },
           { headers: { 'Cache-Control': 'no-store' } }
         );
       }
       if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
       if (!sameOriginWrite(req))
         return new Response('cross-origin write rejected', { status: 403 });
-      const body = await readJson<{ transcriptionProvider?: unknown }>(req, 4 * 1024);
-      const provider = body?.transcriptionProvider;
-      if (!isTranscriptionProvider(provider))
-        return new Response('transcriptionProvider must be whisper|elevenlabs|groq', {
-          status: 400,
-        });
+      const body = await readJson<{ transcriptionProvider?: unknown; keyframeEngine?: unknown }>(
+        req,
+        4 * 1024
+      );
+      // The panel POSTs ONE pref at a time (transcription engine OR keyframe engine).
       try {
+        if ('keyframeEngine' in (body ?? {})) {
+          const engine = body?.keyframeEngine;
+          if (!isKeyframeEngine(engine))
+            return new Response('keyframeEngine must be auto|gemma|ffmpeg|blind', { status: 400 });
+          await writeKeyframeEngine(ctx.paths.repoRoot, engine);
+          reloadConfig(ctx);
+          return Response.json(
+            { keyframeEngine: engine },
+            { headers: { 'Cache-Control': 'no-store' } }
+          );
+        }
+        const provider = body?.transcriptionProvider;
+        if (!isTranscriptionProvider(provider))
+          return new Response('transcriptionProvider must be whisper|elevenlabs|groq', {
+            status: 400,
+          });
         await writeTranscriptionProvider(ctx.paths.repoRoot, provider);
         reloadConfig(ctx);
         return Response.json(
@@ -3177,6 +3302,87 @@ export function createHttp(
       );
     },
 
+    // feature-scene-aware-keyframes — managed local Gemma-4 MLX scout models: GET
+    // lists the registry + which are downloaded + any in-flight download + the two
+    // availability signals (mlx-vlm runtime, ffmpeg) the Settings card needs to say
+    // which tier will run; POST {id} downloads one via huggingface_hub (gated on
+    // mlx-vlm being installed — the model is useless without it). MAIN-ORIGIN ONLY.
+    '/_api/generate/keyframe-model': async (req: Request) => {
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      if (req.method === 'GET') {
+        // The GET builds availability by spawning subprocesses (import mlx_vlm is
+        // heavy). Gate it same-origin so a cross-origin no-cors flood can't drive a
+        // spawn-storm against the loopback server (DDR-183 security finding — the
+        // sibling audio-search GET added this guard for the same reason). The probes
+        // are also TTL-cached in gemma-models.ts as defence-in-depth.
+        if (!sameOriginRead(req))
+          return new Response('cross-origin read rejected', { status: 403 });
+        return Response.json(
+          {
+            models: listGemmaModels(),
+            downloading: keyframeDownload,
+            mlxVlmAvailable: mlxVlmAvailable(),
+            ffmpegAvailable: ffmpegAvailable(),
+          },
+          { headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      if (req.method === 'DELETE') {
+        // Free a wedged download slot (a stalled HF connection) without waiting out
+        // the 60-min abort timeout (DDR-183 F4). Same-origin write-gated.
+        if (!sameOriginWrite(req))
+          return new Response('cross-origin write rejected', { status: 403 });
+        keyframeDownload = null;
+        return Response.json({ cancelled: true }, { headers: { 'Cache-Control': 'no-store' } });
+      }
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      if (!mlxVlmAvailable())
+        return new Response(
+          'mlx-vlm not installed — the Gemma scout needs an Apple-Silicon Mac + `pip install mlx-vlm`.',
+          {
+            status: 400,
+          }
+        );
+      const body = await readJson<{ id?: unknown }>(req, 4 * 1024);
+      const id = typeof body?.id === 'string' ? body.id : '';
+      if (!listGemmaModels().some((m) => m.id === id))
+        return new Response('unknown model id', { status: 400 });
+      if (keyframeDownload && !keyframeDownload.error)
+        return new Response(`a download is already in progress (${keyframeDownload.id})`, {
+          status: 409,
+        });
+      keyframeDownload = { id, received: 0, total: 0 };
+      void downloadGemmaModel(
+        id,
+        (received, total) => {
+          if (keyframeDownload && keyframeDownload.id === id) {
+            keyframeDownload.received = received;
+            keyframeDownload.total = total;
+          }
+        },
+        AbortSignal.timeout(60 * 60_000) // multi-GB snapshots on a slow link
+      )
+        .then(() => {
+          if (keyframeDownload?.id === id) keyframeDownload = null;
+        })
+        .catch((err) => {
+          if (keyframeDownload?.id === id)
+            keyframeDownload = {
+              id,
+              received: keyframeDownload.received,
+              total: keyframeDownload.total,
+              error: err instanceof Error ? err.message : 'download failed',
+            };
+        });
+      return Response.json(
+        { started: id },
+        { status: 202, headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
     '/_canvas-state': async (req: Request) => {
       const url = new URL(req.url);
       if (req.method === 'GET') {