@1agh/maude 0.45.1 → 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/generation/whisper-models.test.ts

@@ -125,7 +125,9 @@ describe('downloadWhisperModel', () => {
       headers: new Headers(),
       body: new Response(new Uint8Array(1)).body,
     })) as unknown as typeof fetch;
-    await expect(downloadWhisperModel('tiny', () => {})).rejects.toThrow(/off huggingface\.co/);
+    await expect(downloadWhisperModel('tiny', () => {})).rejects.toThrow(
+      /off the allowed HF hosts/
+    );
     expect(existsSync(join(whisperModelsDir(), 'ggml-tiny.bin'))).toBe(false);
   });
 
@@ -140,6 +142,31 @@ describe('downloadWhisperModel', () => {
     const path = await downloadWhisperModel('tiny', () => {});
     expect(existsSync(path)).toBe(true);
   });
+
+  test("accepts a redirect that lands on HF's Xet CDN (xethub.hf.co)", async () => {
+    const bytes = new Uint8Array(512);
+    globalThis.fetch = (async () => ({
+      url: 'https://cas-bridge.xethub.hf.co/repos/x/ggml-tiny.bin',
+      ok: true,
+      headers: new Headers({ 'content-length': String(bytes.byteLength) }),
+      body: new Response(bytes).body,
+    })) as unknown as typeof fetch;
+    const path = await downloadWhisperModel('tiny', () => {});
+    expect(existsSync(path)).toBe(true);
+  });
+
+  test('rejects a lookalike host that merely contains an allowed apex', async () => {
+    globalThis.fetch = (async () => ({
+      url: 'https://xethub.hf.co.evil.example/ggml-tiny.bin',
+      ok: true,
+      headers: new Headers(),
+      body: new Response(new Uint8Array(1)).body,
+    })) as unknown as typeof fetch;
+    await expect(downloadWhisperModel('tiny', () => {})).rejects.toThrow(
+      /off the allowed HF hosts/
+    );
+    expect(existsSync(join(whisperModelsDir(), 'ggml-tiny.bin'))).toBe(false);
+  });
 });
 
 describe('registry integrity', () => {

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

@@ -81,6 +81,18 @@ export const WHISPER_MODELS: readonly WhisperModelDescriptor[] = [
 const MODEL_HOST = 'https://huggingface.co';
 const MODEL_REPO_PATH = '/ggerganov/whisper.cpp/resolve/main';
 
+// Apex domains a model-download redirect is allowed to land on. `huggingface.co`
+// is the classic Git-LFS CDN; `xethub.hf.co` is HF's newer Xet storage backend,
+// which several repos (incl. ggerganov/whisper.cpp) have been migrated to — its
+// edge nodes (e.g. `cas-bridge.xethub.hf.co`) are a different apex entirely, not
+// a subdomain of huggingface.co. Anchored subdomain match only (never
+// `includes()`), so `xethub.hf.co.evil.com` / `evilxethub.hf.co` still reject.
+const ALLOWED_REDIRECT_APEXES = ['huggingface.co', 'xethub.hf.co'] as const;
+
+function isAllowedRedirectHost(hostname: string): boolean {
+  return ALLOWED_REDIRECT_APEXES.some((apex) => hostname === apex || hostname.endsWith(`.${apex}`));
+}
+
 /** The fixed, non-interpolated download URL for a model (SSRF-safe — the file
  *  comes from the frozen registry above, never from a request). */
 export function whisperModelUrl(m: WhisperModelDescriptor): string {
@@ -163,7 +175,9 @@ export function resolveWhisperModel(preferId?: string): string | null {
  * (Task 2.7). Egress discipline: the URL is derived from the FROZEN registry
  * (initial host is always huggingface.co, asserted https + fixed host); the
  * redirect the HF blob store issues is followed but the FINAL hop is re-asserted
- * https + a `*.huggingface.co` host (ethical-hacker Finding 2); the body is
+ * https + a host on `ALLOWED_REDIRECT_APEXES` (`*.huggingface.co` for the
+ * classic LFS CDN, `*.xethub.hf.co` for HF's newer Xet storage backend —
+ * ethical-hacker Finding 2 plus the Xet-migration follow-up); the body is
  * size-capped per-chunk to the model's expected size (+20% margin) before it can
  * fill the disk; written to a `.part` temp and atomically renamed so a
  * partial/aborted download never looks complete. Pass an AbortSignal (a timeout)
@@ -190,15 +204,16 @@ export async function downloadWhisperModel(
   const tmpPath = `${finalPath}.part`;
 
   const cap = Math.ceil(m.sizeMB * 1.2) * 1024 * 1024; // expected size + 20% margin
-  // huggingface.co 302-redirects model blobs to its own LFS CDN, so we must
-  // follow — but re-assert the FINAL hop is still https + a huggingface.co host
-  // (ethical-hacker Finding 2): an open-redirect/on-path must not land the fetch
-  // on an arbitrary host. A wall-clock timeout is layered by the caller's signal.
+  // huggingface.co 302-redirects model blobs to its own LFS/Xet CDN, so we must
+  // follow — but re-assert the FINAL hop is still https + a host on
+  // ALLOWED_REDIRECT_APEXES (ethical-hacker Finding 2): an open-redirect/on-path
+  // must not land the fetch on an arbitrary host. A wall-clock timeout is
+  // layered by the caller's signal.
   const res = await fetch(url, { signal, redirect: 'follow' });
   try {
     const finalUrl = new URL(res.url || url);
-    if (finalUrl.protocol !== 'https:' || !/(^|\.)huggingface\.co$/.test(finalUrl.hostname))
-      throw new Error(`model download redirected off huggingface.co (${finalUrl.hostname})`);
+    if (finalUrl.protocol !== 'https:' || !isAllowedRedirectHost(finalUrl.hostname))
+      throw new Error(`model download redirected off the allowed HF hosts (${finalUrl.hostname})`);
   } catch (err) {
     if (err instanceof Error && err.message.startsWith('model download redirected')) throw err;
     throw new Error('model download resolved to an invalid URL');