mlx-bun 0.0.13 → 0.3.0

package/src/vision/video-frames.ts

@@ -0,0 +1,148 @@
+// Video file → RGB frames via the AVFoundation sidecar (PLAN 14w) — the
+// video twin of the audio path's afconvert doctrine: macOS-native codecs
+// (H.264/HEVC/ProRes/…), zero vendored decoders. The sidecar
+// (src/native/frame_extract.swift, shipped as `mlx-bun-frame-extract` beside
+// the binary and in the native pack) samples frames at fps=2 with
+// zero-tolerance timestamps — mirroring mlx-vlm's do_sample_frames — and
+// writes PNGs that decode through the SAME fast-png path as image inputs.
+//
+// Resolution order (afconvert needs none of this because /usr/bin ships it;
+// our extractor is the missing CLI face on Apple's decoder):
+//   MLX_BUN_FRAME_EXTRACT env → beside the executable (release bundle) →
+//   the native-pack cache → dist-native (dev tree) → compile-on-demand from
+//   src/native (from-source installs with Xcode CLT; cached in dist-native).
+
+import { existsSync, mkdirSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { nativePackDir } from "../native-pack";
+import { decodeImage, type RGBImage } from "./preprocess";
+import { runtimeValue } from "../runtime-config";
+
+export const VIDEO_SAMPLE_FPS = 2;
+export const VIDEO_MAX_FRAMES = 768; // Qwen3VLVideoProcessor max_frames
+
+const BIN = "mlx-bun-frame-extract";
+
+/** Memoize the PROMISE, not the result: a second video request arriving
+ *  while the first compile is in flight must await the same compile, not
+ *  observe a half-set cache and spuriously report the sidecar missing. */
+let devCompile: Promise<string | null> | null = null;
+
+/** Compile the sidecar from the repo tree (dev/from-source convenience —
+ *  needs swiftc from the Xcode CLT). Null when the source or toolchain is
+ *  unavailable. */
+function compileFromSource(): Promise<string | null> {
+  devCompile ??= (async () => {
+    const src = join(import.meta.dir, "..", "native", "frame_extract.swift");
+    if (!existsSync(src)) return null;
+    const out = join(import.meta.dir, "..", "..", "dist-native", BIN);
+    try {
+      mkdirSync(dirname(out), { recursive: true });
+      const proc = Bun.spawn(["swiftc", "-O", src, "-o", out], {
+        stdout: "ignore", stderr: "pipe",
+      });
+      if ((await proc.exited) === 0 && existsSync(out)) return out;
+    } catch {
+      // no swiftc — resolver returns null and serving 400s with the reason
+    }
+    return null;
+  })();
+  return devCompile;
+}
+
+/** Locate (or dev-compile) the extractor; null ⟹ video input unavailable
+ *  on this install (surfaced as a clear 400, never a crash). */
+export async function resolveFrameExtract(): Promise<string | null> {
+  const explicit = runtimeValue("MLX_BUN_FRAME_EXTRACT");
+  if (explicit) return explicit;
+  const candidates = [
+    join(dirname(process.execPath), BIN),
+    join(nativePackDir(), BIN),
+    join(import.meta.dir, "..", "..", "dist-native", BIN),
+  ];
+  for (const c of candidates) if (existsSync(c)) return c;
+  return compileFromSource();
+}
+
+/** Decode a video container to sampled RGB frames. Throws with the
+ *  sidecar's diagnostic on failure (the serve layer surfaces it as a 400,
+ *  the afconvert pattern — timeout kill included). */
+export async function extractVideoFrames(
+  bytes: Uint8Array,
+  opts: { fps?: number; maxFrames?: number } = {},
+): Promise<RGBImage[]> {
+  const bin = await resolveFrameExtract();
+  if (!bin)
+    throw new Error(
+      "video input needs the frame-extraction sidecar (mlx-bun-frame-extract) " +
+      "— ships beside the release binary and in the native pack; from a " +
+      "source tree it compiles on first use via the Xcode CLT (swiftc)",
+    );
+  const base = join(tmpdir(), `mlx-bun-video-${randomUUID()}`);
+  // AVFoundation infers the container from the path EXTENSION — sniff the
+  // ISO-BMFF `ftyp` box (mp4/mov share it; the `qt  ` major brand is
+  // QuickTime) so the temp file opens. Unknown magic defaults to .mp4.
+  const isFtyp = bytes.length >= 12 &&
+    bytes[4] === 0x66 && bytes[5] === 0x74 && bytes[6] === 0x79 && bytes[7] === 0x70;
+  const brand = isFtyp
+    ? String.fromCharCode(bytes[8]!, bytes[9]!, bytes[10]!, bytes[11]!)
+    : "";
+  const ext = brand.startsWith("qt") ? "mov" : "mp4";
+  const inPath = `${base}.${ext}`;
+  const outDir = `${base}.frames`;
+  try {
+    // Inside the try so a part-way write failure (ENOSPC on a large clip)
+    // still hits the finally's cleanup instead of stranding the temp file.
+    await Bun.write(inPath, bytes);
+    const proc = Bun.spawn(
+      [
+        bin, inPath, outDir,
+        String(opts.fps ?? VIDEO_SAMPLE_FPS),
+        String(opts.maxFrames ?? VIDEO_MAX_FRAMES),
+      ],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    // Decoding is fast (hardware) but long clips take real time; a hung
+    // decoder must not pin the request forever — kill → nonzero → 400.
+    const killer = setTimeout(() => proc.kill(), 120_000);
+    const exit = await proc.exited;
+    clearTimeout(killer);
+    if (exit !== 0) {
+      const err = (await new Response(proc.stderr).text()).trim();
+      throw new Error(
+        `video decode failed (frame-extract exit ${exit}): ` +
+        `${err.split("\n").at(-1) || "unknown error"} — supported containers: ` +
+        `whatever AVFoundation decodes on this macOS (mp4/mov H.264/HEVC/ProRes/…)`,
+      );
+    }
+    const head = (await new Response(proc.stdout).text()).trim();
+    const n = Number(/^N (\d+)/.exec(head)?.[1] ?? 0);
+    if (!n) throw new Error(`video decode produced no frames (${head})`);
+    // Aggregate decoded-RGB budget (belt over the sidecar's 1024px
+    // longest-edge cap): a valid low-bitrate clip must not balloon into
+    // gigabytes of frame buffers before preprocessing.
+    const w = Number(/W (\d+)/.exec(head)?.[1] ?? 0);
+    const hh = Number(/H (\d+)/.exec(head)?.[1] ?? 0);
+    const DECODED_BUDGET = 1536 * 1024 * 1024; // 1.5 GiB
+    if (n * w * hh * 3 > DECODED_BUDGET)
+      throw new Error(
+        `video decodes to ${(n * w * hh * 3 / 1024 / 1024).toFixed(0)} MB of ` +
+        `frames (${n} × ${w}x${hh}) — over the ${DECODED_BUDGET / 1024 / 1024} MB ` +
+        `budget; send a shorter or smaller clip`,
+      );
+    const frames: RGBImage[] = [];
+    for (let i = 0; i < n; i++) {
+      const f = join(outDir, `frame-${String(i).padStart(4, "0")}.png`);
+      frames.push(await decodeImage(new Uint8Array(await Bun.file(f).arrayBuffer())));
+    }
+    return frames;
+  } finally {
+    await Promise.allSettled([
+      rm(inPath, { force: true }),
+      rm(outDir, { recursive: true, force: true }),
+    ]);
+  }
+}

package/src/web/app.html

@@ -1216,7 +1216,7 @@
 <!-- PWA installability (plan §9 Phase 3, beat-matrix Axis 10): manifest +
      inline SVG icon (src/web/manifest.webmanifest, src/web/icon.svg — no
      binary PNGs, per the hygiene gate; some browsers won't render an SVG
-     app icon and that's an accepted tradeoff, see features-matrix.md).
+     app icon and that's an accepted tradeoff, see docs/reference/server-config.md).
      theme-color matches the app's --bg token so the OS chrome doesn't
      flash a mismatched color on launch. -->
 <link rel="manifest" href="/manifest.webmanifest">

package/src/web/app.js

@@ -1,7 +1,7 @@
 // GENERATED — do not edit by hand.
 // Source: src/web/src/*.ts (entrypoint main.ts). To regenerate:
 //   bun scripts/build-web.ts
-// tests/web-build.test.ts enforces that this file matches the source.
+// tests/using/web-build.test.ts enforces that this file matches the source.
 // src/web/src/api.ts
 async function api(path, opts) {
   const { body, ...rest } = opts || {};
@@ -2892,11 +2892,13 @@ function initMemoryPanel() {
   maybeShowConsentCard();
 }
 
+// src/contracts/pi.ts
+var APP_ROUTE_IDS = ["chat", "quantize", "finetune", "dataset", "status"];
+
 // src/web/src/ui-catalog.ts
-var ROUTE_IDS = ["chat", "quantize", "finetune", "dataset", "status"];
 var VIEW_IDS = ["memory-panel", "hub-panel", "settings", "adapters-panel"];
 function isRouteId(v) {
-  return ROUTE_IDS.includes(v);
+  return APP_ROUTE_IDS.includes(v);
 }
 function isViewId(v) {
   return VIEW_IDS.includes(v);
@@ -3496,15 +3498,21 @@ function createChatController() {
       t0: performance.now(),
       tFirst: 0,
       tokens: 0,
+      settled: false,
       blockState: { blocks: [] },
       scheduleText: () => {},
       scheduleThinking: () => {},
       citations: pendingCitations
     };
     pendingCitations = [];
-    curAssistant.scheduleText = makeFrameScheduler(() => renderBlocksIncremental(curAssistant.textNode, curAssistant.text, curAssistant.blockState), atBottom, stick);
-    curAssistant.scheduleThinking = makeFrameScheduler(() => {
-      curAssistant.thinkBody.textContent = curAssistant.thinking;
+    const assistant = curAssistant;
+    assistant.scheduleText = makeFrameScheduler(() => {
+      if (!assistant.settled)
+        renderBlocksIncremental(assistant.textNode, assistant.text, assistant.blockState);
+    }, atBottom, stick);
+    assistant.scheduleThinking = makeFrameScheduler(() => {
+      if (!assistant.settled)
+        assistant.thinkBody.textContent = assistant.thinking;
     }, atBottom, stick);
     stick(true);
   }
@@ -3670,6 +3678,7 @@ function createChatController() {
   function finishStreaming(a) {
     if (!a)
       return;
+    a.settled = true;
     const previewIdx = captureCanvasViewStates(a.textNode);
     a.textNode.innerHTML = mdToHtml(a.text);
     restoreCanvasViewStates(a.textNode, previewIdx);

package/src/web/src/adapters-panel.ts

@@ -9,9 +9,9 @@
 // docs/reference/server-api.md), with compatible-graying and a why-not
 // tooltip. Actions: mount, select, unselect, and stack two compatible
 // adapters as "a+b" — resolveSpec/injectAdapter already support composite
-// ids end to end (proved in tests/pi-web.test.ts's stacking test; the
+// ids end to end (proved in tests/research/pi-web.test.ts's stacking test; the
 // shape-validated mount is proved against real weights in the
-// MLX_BUN_TEST_LORA=1-gated tests/lora.test.ts).
+// MLX_BUN_TEST_LORA=1-gated tests/parity/lora.test.ts).
 //
 // Single source of SELECTION state, not a single fetch: composer.ts's quick
 // <select> and this table each hit /v1/adapters(+/available) independently
@@ -158,7 +158,7 @@ export function renderAdapterRow(
 }
 
 /** Full table body: a stack-mode toggle + composed-spec bar (when picks
- *  exist), then one section of rows. Exported so tests/web-app.test.ts can
+ *  exist), then one section of rows. Exported so tests/using/web-app.test.ts can
  *  exercise esc() discipline without a live DOM/network. */
 export function renderAdaptersBodyHtml(state: AdaptersPanelState): string {
   if (!state.available.length) {

package/src/web/src/assistant.ts

@@ -1,3 +1,5 @@
+import type { UiSnapshotElement, UiSnapshot, WizardStep } from "../../contracts/pi";
+export type { UiSnapshotElement, UiSnapshot, WizardStep } from "../../contracts/pi";
 // GENERATED-ADJACENT source module — part of the src/web/src/* split (plan
 // §6.6 "the app-aware assistant", §9 Phase 3, beat matrix Axis 12). Built
 // into src/web/app.js by scripts/build-web.ts.
@@ -26,42 +28,6 @@
 
 import { getSpotlightTarget, isViewId, ROUTE_LABELS, type RouteId, type ViewId } from "./ui-catalog";
 
-/* ────────────────────────────────────────────────────────────────────
-   1. SEE — the structured DOM snapshot
-   ──────────────────────────────────────────────────────────────────── */
-
-export interface UiSnapshotElement {
-  ref: string;
-  tag: string;
-  label: string;
-  kind: "interactive" | "region";
-  role?: string;
-  selector: string;
-  spotlightId?: string;
-}
-
-export interface UiSnapshot {
-  route: string;
-  capturedAt: string;
-  elements: UiSnapshotElement[];
-}
-
-/** Process-state fields layered onto the snapshot (§6.6 "the snapshot
- *  carries process state, not just elements") — wizard step for the
- *  quantize/finetune/dataset wizards, when the current route has one.
- *  Derived by reading the DOM the step indicator already renders
- *  (markdown.ts's renderSteps into #q-steps/#f-steps/#d-steps + the
- *  [data-qstep]/[data-fstep]/[data-dstep] visibility toggle quantize.ts/
- *  finetune.ts/dataset.ts already do) rather than adding a callback hook to
- *  those three controllers — zero behavior change to files outside this
- *  wave's scope, and the DOM IS the source of truth those controllers
- *  already write to. */
-export interface WizardStep {
-  index: number;
-  count: number;
-  label: string;
-}
-
 const STEP_CONTAINER_BY_ROUTE: Partial<Record<RouteId, string>> = {
   quantize: "q-steps",
   finetune: "f-steps",

package/src/web/src/chat.ts

@@ -10,15 +10,15 @@
 // typed, checkable seams between these concerns).
 //
 // Typed WS contract (plan §9 Phase 2 item 2): ClientMessage/ServerMessage
-// and the history/session shapes are imported TYPE-ONLY from ../../pi-web
+// and the history/session shapes are imported TYPE-ONLY from ../../contracts/pi
 // so this module (and the whole bundle) contains zero server code — the
 // bundler errors on bun:ffi if a value import ever sneaks in here, which is
 // the intended guard (see scripts/build-web.ts).
 
 import type {
   ClientMessage, HistoryItem, ReadyGenDefaults, ServerMessage, SessionListItem,
-} from "../../pi-web";
-import type { Lane } from "../../serve/lane-registry";
+} from "../../contracts/pi";
+import type { Lane } from "../../contracts/pi";
 import {
   $, el, toast, currentRoute, closeDrawer,
   storedCodingToolsPreference, renderCodingToolsState, renderToolApprovals,
@@ -44,7 +44,7 @@ import { isRouteId } from "./ui-catalog";
 
 /* ────────────────────────────────────────────────────────────────────
    Chat-with-files RAG v1 — Sources panel (plan §9 Phase 3, beat matrix
-   Axis 5). Pure HTML builder so tests/web-app.test.ts can exercise the
+   Axis 5). Pure HTML builder so tests/using/web-app.test.ts can exercise the
    esc() discipline directly, same reasoning as renderAdapterOptionsHtml
    etc. in composer.ts.
    ──────────────────────────────────────────────────────────────────── */
@@ -142,6 +142,7 @@ interface AssistantMsgState {
   t0: number;
   tFirst: number;
   tokens: number;
+  settled: boolean;
   blockState: BlockState;
   scheduleText: () => void;
   scheduleThinking: () => void;
@@ -373,7 +374,7 @@ export function createChatController() {
     const meta = el("div", "meta", m);
     curAssistant = {
       m, bubble, thinkBox, thinkBody, textNode, cursor, meta, tools: new Map(),
-      text: "", thinking: "", t0: performance.now(), tFirst: 0, tokens: 0,
+      text: "", thinking: "", t0: performance.now(), tFirst: 0, tokens: 0, settled: false,
       // Block-memoization state (see renderBlocksIncremental) for the main
       // markdown text stream, plus a shared rAF scheduler so a burst of
       // deltas within one frame (e.g. spec-decode emitting several tokens
@@ -390,11 +391,16 @@ export function createChatController() {
     // Consumed — a later turn with no RAG'd attachments must not inherit
     // this turn's citation set (see the pendingCitations declaration above).
     pendingCitations = [];
-    curAssistant.scheduleText = makeFrameScheduler(
-      () => renderBlocksIncremental(curAssistant!.textNode, curAssistant!.text, curAssistant!.blockState),
+    const assistant = curAssistant;
+    assistant.scheduleText = makeFrameScheduler(
+      () => {
+        if (!assistant.settled) renderBlocksIncremental(assistant.textNode, assistant.text, assistant.blockState);
+      },
       atBottom, stick);
-    curAssistant.scheduleThinking = makeFrameScheduler(
-      () => { curAssistant!.thinkBody.textContent = curAssistant!.thinking; },
+    assistant.scheduleThinking = makeFrameScheduler(
+      () => {
+        if (!assistant.settled) assistant.thinkBody.textContent = assistant.thinking;
+      },
       atBottom, stick);
     stick(true);
   }
@@ -612,6 +618,7 @@ export function createChatController() {
    *  directly on the full string. */
   function finishStreaming(a: AssistantMsgState | null): void {
     if (!a) return;
+    a.settled = true;
     // Preserve any Canvas Preview toggle the user made mid-stream (Principle
     // 9: this full non-memoized re-render must not throw away user
     // interaction state) — mdCodeBlock always emits qualifying fences back

package/src/web/src/composer.ts

@@ -10,8 +10,8 @@
 // the original single IIFE), but every WS send goes through a callback
 // passed in from chat.ts, which owns the actual WebSocket.
 
-import type { ReadyGenDefaults, SamplingOverrides } from "../../pi-web";
-import type { Lane } from "../../serve/lane-registry";
+import type { ReadyGenDefaults, SamplingOverrides } from "../../contracts/pi";
+import type { Lane } from "../../contracts/pi";
 import { api } from "./api";
 import type { ApiEnvelope } from "./protocol";
 import {
@@ -200,7 +200,7 @@ function escHtml(s: unknown): string {
 
 /** Pure: builds the <option> markup for the adapter <select> from the
  *  /v1/adapters/available list. Split out from refreshAdapters() (which
- *  does the fetch + DOM write) so tests/web-app.test.ts can exercise the
+ *  does the fetch + DOM write) so tests/using/web-app.test.ts can exercise the
  *  esc() discipline on this template directly without a DOM or network —
  *  every interpolated field (id, rank, path, base_model) must be escaped,
  *  since adapter ids/paths are user-controlled (on-disk directory names). */
@@ -719,7 +719,7 @@ export function renderLane(lane: Lane | undefined): void {
    already resolves, so the agent's memory tools pick it up naturally, same
    as in the vault's own prose). No vault -> files-only picker. Pure
    query-detection/insertion helpers below are unit-tested directly
-   (tests/web-app.test.ts); DOM wiring (initMentionPicker) owns the
+   (tests/using/web-app.test.ts); DOM wiring (initMentionPicker) owns the
    picker's open/close/keyboard-nav state.
    ──────────────────────────────────────────────────────────────────── */
 

package/src/web/src/hub.ts

@@ -119,7 +119,7 @@ function localRowHtml(m: HubLocalRow): string {
 }
 
 /** Pure render, exported for esc()-discipline + empty-state tests
- *  (tests/web-app.test.ts, mirroring renderModelPopBodyHtml's pattern). */
+ *  (tests/using/web-app.test.ts, mirroring renderModelPopBodyHtml's pattern). */
 export function renderHubLocalHtml(models: HubLocalRow[]): string {
   if (!models.length) {
     return '<div class="hub-empty">No models downloaded yet — search Hugging Face below to get one.</div>';

package/src/web/src/memory-panel.ts

@@ -394,7 +394,7 @@ export async function refreshSidebarEntry(): Promise<void> {
 // by a literal list rather than an import: this module must stay
 // server-code-free (bundler-enforced, see chat.ts's header comment), so it
 // can't import a value from src/memory/tools.ts even though the identifiers
-// are the same. tests/web-app.test.ts cross-checks this list against the
+// are the same. tests/using/web-app.test.ts cross-checks this list against the
 // real export so drift is caught at test time instead of silently.
 export const MEMORY_CHIP_TOOL_NAMES = [
   "memory_resolve", "memory_category", "memory_read", "memory_section",

package/src/web/src/model-picker.ts

@@ -85,7 +85,7 @@ function renderRow(m: LibraryRow): string {
 }
 
 /** Pure render of the popover body from a /library response. Exported for
- *  tests/web-app.test.ts's esc() discipline check (repo ids are
+ *  tests/using/web-app.test.ts's esc() discipline check (repo ids are
  *  user-controlled HF strings — the same class of interpolation hazard
  *  finding #15 flagged for the adapter dropdown). */
 export function renderModelPopBodyHtml(models: LibraryRow[]): string {

package/src/web/src/palette.ts

@@ -39,7 +39,7 @@ interface PaletteAction {
 }
 
 /** Pure: the static action list, independent of any live session data —
- *  independently testable (tests/web-app.test.ts asserts labels/ids without
+ *  independently testable (tests/using/web-app.test.ts asserts labels/ids without
  *  needing a DOM). Session rows and message-search hits are appended
  *  dynamically in refreshResults() below, not part of this list. */
 export function staticActions(): PaletteAction[] {

package/src/web/src/protocol.ts

@@ -1,47 +1,11 @@
-// Shared frontend-only protocol shapes that don't already live on the
-// server side as exported types. The WS contract itself (ClientMessage /
-// ServerMessage / HistoryItem / SessionListItem / ReadyGenDefaults) is
-// imported type-only from ../../pi-web — see chat.ts. This file only holds
-// shapes with no server-side export to anchor to (e.g. the SSE job-stream
-// events, which live as a doc-comment in app.html today, not a type).
-//
-// Pointer comment for the server side: src/web/src/protocol.ts mirrors the
-// SSE line protocol documented at the jobStream() call site (api.ts) —
-// keep the two adjacent if the job event shape changes server-side
-// (scripts/ that emit `data:` lines for /api/jobs/:id/stream).
-
-/** One line of the /api/jobs/:id/stream SSE protocol (JSON per `data:` line). */
-export type JobEvent =
-  | { type: "log"; line: string }
-  | {
-      type: "stage";
-      stage: string;
-      progress?: number;
-      message?: string;
-      output_dir?: string;
-      adapter_path?: string;
-      // Dataset-generation-specific row counts (present on the dataset
-      // builder's job stream only; absent/ignored for quantize/finetune).
-      n_train?: number;
-      n_valid?: number;
-    }
-  | {
-      type: "metric";
-      kind: "train" | "val";
-      step: number;
-      loss: number;
-      learning_rate?: number;
-      tokens_per_sec?: number;
-      progress?: number;
-      message?: string;
-    }
-  | { type: "done"; n_train?: number; n_valid?: number }
-  | { type: "failed"; error?: string };
+import type { JobEvent } from "../../contracts/jobs";
+export type { JobEvent } from "../../contracts/jobs";
 
 /** Handlers passed to jobStream(); each key is an optional callback for the
  *  matching JobEvent variant, plus an `error` callback for the EventSource's
  *  own onerror (transport failure, not a `failed` protocol event). */
 export interface JobStreamHandlers {
+  started?: (e: Extract<JobEvent, { type: "started" }>) => void;
   log?: (e: Extract<JobEvent, { type: "log" }>) => void;
   stage?: (e: Extract<JobEvent, { type: "stage" }>) => void;
   metric?: (e: Extract<JobEvent, { type: "metric" }>) => void;

package/src/web/src/sessions.ts

@@ -20,7 +20,7 @@
 // wires each rendered `.sess` row's click to `onOpen` below — this just
 // finds and clicks the right row instead of duplicating that send()).
 
-import type { SessionListItem } from "../../pi-web";
+import type { SessionListItem } from "../../contracts/pi";
 import { $, el, injectStyles } from "./shell";
 import { api } from "./api";
 

package/src/web/src/ui-catalog.ts

@@ -2,28 +2,14 @@
 // §7/§9 Phase 3, §6.6 "app-aware assistant"). Built into src/web/app.js by
 // scripts/build-web.ts.
 //
-// The frontend half of the app-aware assistant's route/spotlight catalog.
-// Mirrors PortfolioManager's ui-catalog.json pattern (client/src/lib/
-// ui-catalog.ts + server/src/agent/ui-catalog.ts, read together with
-// server/src/agent/portfolio-tools.ts as the reference implementation) but
-// inlined as a TS module (not a shared JSON file) since mlx-bun's server and
-// browser bundles are separate build outputs (scripts/build-web.ts vs bun's
-// own TS execution) with no shared-JSON-import convention today — pi-web.ts
-// mirrors ROUTE_IDS/SPOTLIGHT_TARGETS as plain string arrays for its own
-// server-side validation (navigate_app/spotlight_ui reject anything not in
-// that list BEFORE touching the browser) so route validity is checked at
-// both ends without a build-time shared asset.
-//
-// Keep this list's ROUTE_IDS in sync with shell.ts's ROUTES tuple (chat,
-// quantize, finetune, dataset, status) plus the Developer-only overlays that
-// aren't hash-routes (memory panel, hub panel, settings) — those are
-// `view`s, not `route`s (see UiContext.view below), reached by opening an
-// overlay rather than changing the URL hash.
+// Shared route IDs keep browser navigation and server validation in agreement.
+// Spotlight selectors and overlay IDs belong to the browser.
 
 /** A hash-routed page (shell.ts's Route union, minus "routes" — the DAG
  *  diagram tab isn't a useful assistant destination and is itself
  *  feature-detected/hidden when unavailable). */
-export const ROUTE_IDS = ["chat", "quantize", "finetune", "dataset", "status"] as const;
+import { APP_ROUTE_IDS as ROUTE_IDS } from "../../contracts/pi";
+export { ROUTE_IDS };
 export type RouteId = (typeof ROUTE_IDS)[number];
 
 /** A non-route overlay/panel the assistant can navigate to or spotlight

package/src/web-assets.ts

@@ -0,0 +1,47 @@
+// Embedded web app — the unified SPA (chat / quantize / finetune /
+// dataset / status). `with { type: "text" }` inlines the file in both
+// `bun run` and the compiled single binary. bun-types types *.html
+// imports as HTMLBundle (the html loader), but the text attribute makes
+// the runtime value a string — hence the double cast.
+import appHtml from "./web/app.html" with { type: "text" };
+import curveDesignerHtml from "./lab/curve/curve-designer.html" with { type: "text" };
+// Vendored, no-CDN static assets referenced by app.html (convention: any
+// self-contained JS/CSS too big to inline gets `with { type: "text" }`
+// imported here and served under /assets/<name>; see src/web/vendor/README
+// for how hljs.js was built). Add new vendored assets the same way.
+import hljsJs from "./web/vendor/hljs.js" with { type: "text" };
+import hljsCss from "./web/vendor/hljs-theme.css" with { type: "text" };
+// The frontend bundle (plan §7/§9 Phase 2 module split): GENERATED from
+// src/web/src/*.ts by `bun scripts/build-web.ts` — see that file's header
+// and tests/using/web-build.test.ts (the freshness gate). Same
+// with { type: "text" } + /assets/<name> pattern as the vendored assets
+// above; app.html's <script defer src="/assets/app.js"> loads it.
+import appJs from "./web/app.js" with { type: "text" };
+// PWA installability (plan §9 Phase 3, beat-matrix Axis 10): a manifest +
+// a single inline SVG icon (no binary PNGs — the hygiene gate forbids
+// tracked binary files; some browsers won't show an SVG app icon, which is
+// an accepted tradeoff, see docs/reference/server-config.md) + a shell-
+// only service worker. Same with { type: "text" } + /assets/<name>-shaped
+// pattern as the vendored assets above; see src/web/sw.js's header for why
+// it deliberately does NOT cache API/WS traffic.
+import manifestWebmanifest from "./web/manifest.webmanifest" with { type: "text" };
+import iconSvg from "./web/icon.svg" with { type: "text" };
+import swJs from "./web/sw.js" with { type: "text" };
+const APP_PAGE = appHtml as unknown as string;
+const HLJS_JS = hljsJs as unknown as string;
+const HLJS_CSS = hljsCss as unknown as string;
+const APP_JS = appJs as unknown as string;
+const MANIFEST_WEBMANIFEST = manifestWebmanifest as unknown as string;
+const ICON_SVG = iconSvg as unknown as string;
+const SW_JS = swJs as unknown as string;
+const CURVE_PAGE = curveDesignerHtml as unknown as string;
+export const STATIC_ROUTE_ASSETS = {
+  appPage: APP_PAGE,
+  appJs: APP_JS,
+  hljsJs: HLJS_JS,
+  hljsCss: HLJS_CSS,
+  manifest: MANIFEST_WEBMANIFEST,
+  iconSvg: ICON_SVG,
+  serviceWorker: SW_JS,
+  curvePage: CURVE_PAGE,
+};