mlx-bun 0.0.10 → 0.0.12

package/src/web/src/status.ts

@@ -0,0 +1,300 @@
+// GENERATED-ADJACENT source module — part of the src/web/src/* split (plan
+// §7/§9 Phase 2). Built into src/web/app.js by scripts/build-web.ts.
+//
+// STATUS CONTROLLER — ported dashboard (poll /stats + /v1/models + /fit +
+// /library + /downloads). Behavior-identical port of the original
+// controllers.status IIFE in app.html.
+
+import { $, gb, mb, num } from "./shell";
+import { esc } from "./markdown";
+
+interface DownloadRow {
+  repoId: string;
+  state: "active" | "done" | "error";
+  totalBytes: number;
+  receivedBytes: number;
+  bytesPerSec?: number;
+  currentFile?: string;
+  filesDone: number;
+  filesTotal: number;
+  startedAt: number;
+  error?: string;
+}
+
+interface LibraryModel {
+  repo_id: string;
+  size_bytes: number;
+  serving?: boolean;
+  supported?: boolean;
+  model_type?: string;
+  vision?: boolean;
+  assessment?: {
+    fits?: boolean;
+    max_safe_context?: number;
+    predicted_decode_tps?: number;
+  };
+}
+
+interface SkuRow {
+  sku: string;
+  ram_gb: number;
+  fits: boolean;
+  max_context: number;
+  decode_tps: number;
+}
+
+export function createStatusController() {
+  let timer: ReturnType<typeof setInterval> | null = null, libTimer: ReturnType<typeof setInterval> | null = null, fitLoaded = false;
+  const dlRates: Record<string, { bytes: number; t: number }> = {};
+  // Library staleness (web-ui-pass-plan.md #3): /library is server-cached for
+  // 30s, but the client used to fetch it exactly once per page load
+  // (gated on `fitLoaded`) — a quantize job finishing, a fresh download
+  // landing, or a manual drop into the HF cache never showed up without a
+  // hard reload. Poll it independently on a ~15s cadence while this view is
+  // visible (started in enter()/stopped in leave(), same as the main tick).
+
+  async function tick(): Promise<void> {
+    try {
+      const [stats, models] = await Promise.all([
+        fetch("/stats").then((r) => r.json()),
+        fetch("/v1/models").then((r) => r.json()),
+      ]);
+      const m = models.data && models.data[0];
+      $("st-model-id").textContent = (m && m.id) || "—";
+      const a = stats.admission || {};
+      $("st-model-meta").textContent = num(m && m.context_window) + " token window · weights " + gb(a.weights_bytes);
+      $("st-safe-ctx").textContent = num(a.max_safe_context);
+
+      $("st-weights").textContent = gb(a.weights_bytes);
+      $("st-usable").textContent = gb(a.usable_bytes);
+      $("st-budget").textContent = a.memory_budget_bytes ? gb(a.memory_budget_bytes) : "off";
+      $("st-mem-bar").style.width = a.usable_bytes ? Math.min(100, 100 * a.weights_bytes / a.usable_bytes) + "%" : "0%";
+
+      const pc = stats.prompt_cache || {};
+      const lookups = (pc.hits || 0) + (pc.misses || 0);
+      $("st-pc-hits").textContent = lookups ? Math.round(100 * pc.hits / lookups) + "%" : "no lookups";
+      $("st-pc-entries").textContent = num(pc.entries);
+      $("st-pc-bytes").textContent = mb(pc.bytes) + " / " + mb(pc.max_bytes);
+      $("st-pc-bar").style.width = pc.max_bytes ? Math.min(100, 100 * pc.bytes / pc.max_bytes) + "%" : "0%";
+
+      const rs = stats.response_store || {};
+      $("st-rs-entries").textContent = num(rs.entries);
+      $("st-rs-bytes").textContent = mb(rs.bytes) + " / " + mb(rs.max_bytes);
+      $("st-rs-ttl").textContent = rs.ttl_ms ? (rs.ttl_ms / 60000) + " min" : "—";
+      $("st-rs-bar").style.width = rs.max_bytes ? Math.min(100, 100 * rs.bytes / rs.max_bytes) + "%" : "0%";
+
+      const kv = stats.kv_quant || {};
+      $("st-kv-mode").innerHTML = "<code>" + esc(kv.mode || "—") + "</code>";
+      const att = kv.attention;
+      $("st-kv-layers").innerHTML = Object.entries(kv.layers || {})
+        .map(([k, v]) => '<div class="kv"><b>' + esc(k) + ' layers</b><span class="num">' + esc(v) + "</span></div>").join("") +
+        (att ? '<div class="kv"><b>attention</b><span class="num">' + esc(att.global) + " global · " + esc(att.sliding_window) + " sliding</span></div>" : "");
+
+      const glm = stats.glm52;
+      const expert = glm && glm.expert_runtime;
+      const expertCard = $("st-glm-expert-card");
+      expertCard.style.display = glm ? "" : "none";
+      if (glm) {
+        const rate = (d: { hits?: number; misses?: number } | null | undefined): string => {
+          const total = (d?.hits || 0) + (d?.misses || 0);
+          return total ? (100 * (d?.hits || 0) / total).toFixed(1) + "%" : "—";
+        };
+        const turn = expert && expert.last_turn;
+        $("st-glm-main-hit").textContent = rate(turn?.main?.demand);
+        $("st-glm-main-read").textContent = turn?.main?.demand
+          ? gb(turn.main.demand.readBytes) : "—";
+        $("st-glm-mtp-hit").textContent = rate(turn?.mtp?.demand);
+        $("st-glm-mtp-read").textContent = turn?.mtp?.demand
+          ? gb(turn.mtp.demand.readBytes) : "—";
+        const main = expert?.main_residency;
+        const mtp = expert?.mtp_residency;
+        $("st-glm-residency").textContent = main
+          ? "resident slots main " + num(main.resident + main.pinned) +
+            " / " + num(main.resident + main.pinned + main.working) +
+            (mtp ? " · MTP " + num(mtp.resident + mtp.pinned) +
+              " / " + num(mtp.resident + mtp.pinned + mtp.working) : "")
+          : "expert runtime telemetry unavailable";
+      }
+
+      await loadDownloads();
+      if (!fitLoaded) { await loadFit(); await loadLibrary(); }
+      if (stats.server && stats.server.started_at) {
+        const up = (Date.now() - stats.server.started_at) / 1000;
+        $("st-uptime").textContent = up < 90 ? Math.round(up) + "s" : up < 5400 ? Math.round(up / 60) + "m" : (up / 3600).toFixed(1) + "h";
+      }
+      $("st-updated").textContent = new Date().toLocaleTimeString();
+    } catch {
+      /* nav pill already reflects connectivity; leave last-good values on screen */
+    }
+  }
+
+  async function loadDownloads(): Promise<void> {
+    let downloads: DownloadRow[] | undefined;
+    try { ({ downloads } = await fetch("/downloads").then((r) => r.json())); } catch { return; }
+    const card = $("st-dl-card");
+    if (!downloads || downloads.length === 0) { card.style.display = "none"; return; }
+    card.style.display = "";
+    const order = downloads.slice().sort((a, b) =>
+      (a.state === "active" ? 0 : 1) - (b.state === "active" ? 0 : 1) || b.startedAt - a.startedAt);
+    $("st-dl-list").innerHTML = order.map((d) => {
+      const pct = d.totalBytes ? Math.min(100, 100 * d.receivedBytes / d.totalBytes) : 0;
+      let detail: string, barCls = "";
+      if (d.state === "active") {
+        let bps = d.bytesPerSec || 0;
+        if (!bps) {
+          const prev = dlRates[d.repoId], now = performance.now();
+          if (prev && now > prev.t) bps = (d.receivedBytes - prev.bytes) / ((now - prev.t) / 1000);
+          dlRates[d.repoId] = { bytes: d.receivedBytes, t: now };
+        }
+        const speed = bps > 0 ? " · " + mb(bps) + "/s · ~" + Math.max(1, Math.round((d.totalBytes - d.receivedBytes) / bps / 60)) + " min left" : "";
+        detail = gb(d.receivedBytes) + " / " + gb(d.totalBytes) + " · " + pct.toFixed(0) + "%" + speed +
+          (d.currentFile ? " · <code>" + esc(d.currentFile) + "</code>" : "");
+        barCls = "warm";
+      } else if (d.state === "done") {
+        detail = gb(d.totalBytes) + ' · <span style="color:var(--green);font-weight:600">complete</span>';
+      } else {
+        detail = '<span style="color:var(--red);font-weight:600">error</span> · ' + esc(d.error || "");
+      }
+      return '<div style="padding:10px 0">' +
+        '<div class="kv" style="border:none"><b>' + esc(d.repoId) + "</b>" +
+        '<span class="num">' + d.filesDone + "/" + d.filesTotal + " files</span></div>" +
+        '<div style="font-size:13.5px;color:var(--dim)" class="num">' + detail + "</div>" +
+        '<div class="meter ' + barCls + '"><i style="width:' + pct + '%"></i></div></div>';
+    }).join("");
+  }
+
+  async function loadLibrary(): Promise<void> {
+    let models: LibraryModel[] | undefined;
+    try { ({ models } = await fetch("/library").then((r) => r.json())); } catch { return; }
+    if (!models) return;
+    $("st-lib-body").innerHTML = models.slice()
+      .sort((a, b) => (b.serving ? 1 : 0) - (a.serving ? 1 : 0) || b.size_bytes - a.size_bytes)
+      .map((m) => {
+        const a = m.assessment;
+        let status: string;
+        if (m.serving) status = '<span style="color:var(--blue);font-weight:700">SERVING</span>';
+        else if (!m.supported) status = '<span style="color:var(--dimmer)">unsupported (' + esc(m.model_type) + ")</span>";
+        else if (a && a.fits) status = '<span style="color:var(--green);font-weight:600">fits</span>';
+        else status = '<span style="color:var(--red);font-weight:600">too big</span>';
+        // web-ui-pass-plan.md #20: max_safe_context is meaningful whenever
+        // it's > 0, even when `fits` is false at the library's default 8192
+        // probe context — e.g. a model that doesn't fit at 8192 tokens but
+        // does fit at a smaller context still gets a real number here rather
+        // than an uninformative "—". predicted_decode_tps stays gated on
+        // `fits` since it's only computed for the fitting case server-side.
+        const safeCtx = m.supported && a && (a.max_safe_context ?? 0) > 0 ? num(a.max_safe_context) : "—";
+        return "<tr" + (m.serving ? ' class="you"' : "") + "><td>" + esc(m.repo_id) +
+          (m.vision ? ' · <span style="color:var(--dim)">vision</span>' : "") +
+          '</td><td class="num">' + gb(m.size_bytes) + "</td><td>" + status + "</td>" +
+          '<td class="num">' + safeCtx + "</td>" +
+          '<td class="num">' + (m.supported && a && a.fits ? (a.predicted_decode_tps ?? 0).toFixed(0) + " tok/s" : "—") + "</td></tr>";
+      }).join("");
+  }
+
+  async function loadFit(): Promise<void> {
+    interface FitResponse {
+      report?: {
+        fits?: boolean;
+        weights_bytes?: number; kv_bytes?: number; transient_bytes?: number;
+        total_bytes?: number; usable_bytes?: number; predicted_decode_tps?: number;
+      };
+      measured_decode_tps?: number;
+      typical_decode_tps?: number;
+      typical_context_tokens?: number;
+      context_tokens?: number;
+      machine?: { ram_bytes?: number; bandwidth_gbs?: number; chip?: string };
+      sku_matrix_ctx?: number;
+      sku_matrix?: SkuRow[];
+      glm52?: {
+        artifact_disk_bytes?: number | null;
+        main_expert_slab_bytes?: number;
+        mtp_expert_slab_bytes?: number;
+        direct_oracle_warm_decode_tps?: number;
+        aspirational_decode_tps?: number;
+      };
+    }
+    let f: FitResponse;
+    try { f = await fetch("/fit").then((r) => r.json()); } catch { return; }
+    fitLoaded = true;
+    const r = f.report || {};
+    const tps = (value: number): string => value < 1 ? value.toFixed(2) : value.toFixed(1);
+    if (f.measured_decode_tps) {
+      $("st-tps").textContent = tps(f.measured_decode_tps);
+      $("st-tps").closest(".card")!.querySelector("h3")!.textContent = "Decode · measured";
+      $("st-tps-cap").textContent = f.glm52
+        ? "quality-preserving warm · direct oracle " +
+          tps(f.glm52.direct_oracle_warm_decode_tps || 0) +
+          " · aspiration " + tps(f.glm52.aspirational_decode_tps || 0)
+        : "mlx-bun benchmark on this machine · predicted " +
+          tps(f.typical_decode_tps || 0) + " at " + num(f.typical_context_tokens) + " ctx";
+    } else if (f.typical_decode_tps) {
+      $("st-tps").textContent = f.typical_decode_tps.toFixed(1);
+      $("st-tps-cap").textContent = "at " + num(f.typical_context_tokens) + " context · " + (r.predicted_decode_tps || 0).toFixed(1) + " tok/s at the " + num(f.context_tokens) + " max (full-KV reads)";
+    } else {
+      $("st-tps").textContent = (r.predicted_decode_tps || 0).toFixed(1);
+    }
+    $("st-m-ram").textContent = gb(f.machine && f.machine.ram_bytes);
+    $("st-m-bw").textContent = (f.machine && f.machine.bandwidth_gbs || "—") + " GB/s";
+    $("st-m-fits").innerHTML = r.fits ? '<span style="color:var(--green);font-weight:700">FITS</span>' : '<span style="color:var(--red);font-weight:700">DOES NOT FIT</span>';
+    $("st-fit-ctx").textContent = num(f.context_tokens);
+    document.querySelectorAll<HTMLElement>("[data-glm-fit]").forEach((row) => {
+      row.style.display = f.glm52 ? "" : "none";
+    });
+    $("st-f-weights-label").textContent = f.glm52 ? "resident weights" : "weights";
+    $("st-f-transient-label").textContent = f.glm52 ? "other reserves" : "transient";
+    $("st-f-artifact").textContent = f.glm52?.artifact_disk_bytes
+      ? gb(f.glm52.artifact_disk_bytes) : "registry unavailable";
+    $("st-f-main-slab").textContent = gb(f.glm52?.main_expert_slab_bytes);
+    $("st-f-mtp-slab").textContent = gb(f.glm52?.mtp_expert_slab_bytes);
+    $("st-f-weights").textContent = gb(r.weights_bytes);
+    $("st-f-kv").textContent = gb(r.kv_bytes);
+    $("st-f-transient").textContent = gb(r.transient_bytes);
+    $("st-f-total").textContent = gb(r.total_bytes) + " / " + gb(r.usable_bytes);
+    $("st-fit-bar").style.width = r.usable_bytes ? Math.min(100, 100 * (r.total_bytes ?? 0) / r.usable_bytes) + "%" : "0%";
+
+    $("st-sku-ctx").textContent = num(f.sku_matrix_ctx);
+    const myRam = Math.round((f.machine && f.machine.ram_bytes || 0) / 2 ** 30);
+    const myChip = (f.machine && f.machine.chip) || null;
+    const rows = f.sku_matrix || [];
+    let youIdx = rows.findIndex((row) => myChip && row.sku === myChip && row.ram_gb === myRam);
+    if (youIdx < 0 && myChip) {
+      let best = Infinity;
+      rows.forEach((row, i) => { if (row.sku === myChip && Math.abs(row.ram_gb - myRam) < best) { best = Math.abs(row.ram_gb - myRam); youIdx = i; } });
+    }
+    if (youIdx < 0) youIdx = rows.findIndex((row) => row.ram_gb === myRam);
+    $("st-sku-body").innerHTML = rows.map((row, i) => {
+      const you = i === youIdx;
+      const dimCls = row.fits ? "num" : "num fit-no";
+      return "<tr" + (you ? ' class="you"' : "") + "><td>" + esc(row.sku) + (you ? " · <b>this machine</b>" : "") +
+        '</td><td class="num">' + row.ram_gb + " GB</td>" +
+        '<td class="' + (row.fits ? "fit-yes" : "fit-no") + '">' + (row.fits ? "fits" : "no") + "</td>" +
+        '<td class="' + dimCls + '">' + (row.max_context > 0 ? num(row.max_context) : "0 — weights alone don’t fit") + "</td>" +
+        '<td class="' + dimCls + '">' + (row.decode_tps > 0 ? "~" + tps(row.decode_tps) + " tok/s" : "—") + "</td></tr>";
+    }).join("");
+  }
+
+  return {
+    init() {
+      // trigger scroll reveals once mounted
+      const page = $("status-page");
+      requestAnimationFrame(() => page.classList.add("lit"));
+      page.classList.add("lit");
+    },
+    enter() {
+      tick();
+      timer = setInterval(tick, 2000);
+      loadLibrary();
+      libTimer = setInterval(loadLibrary, 15_000);
+    },
+    leave() {
+      if (timer) clearInterval(timer); timer = null;
+      if (libTimer) clearInterval(libTimer); libTimer = null;
+    },
+    // Exposed so a quantize job's `done` event (this same controller's own
+    // quantize flow, see controllers.quantize below) can force an immediate
+    // refresh instead of waiting up to 15s — the server invalidates its
+    // /library cache the moment the job completes (server.ts onComplete),
+    // so an immediate re-fetch is guaranteed fresh, not a race.
+    refreshLibrary: loadLibrary,
+  };
+}

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

@@ -0,0 +1,92 @@
+// GENERATED-ADJACENT source module — part of the src/web/src/* split (plan
+// §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.
+
+/** 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;
+export type RouteId = (typeof ROUTE_IDS)[number];
+
+/** A non-route overlay/panel the assistant can navigate to or spotlight
+ *  within. Opening one of these does not change location.hash. */
+export const VIEW_IDS = ["memory-panel", "hub-panel", "settings", "adapters-panel"] as const;
+export type ViewId = (typeof VIEW_IDS)[number];
+
+export function isRouteId(v: string): v is RouteId {
+  return (ROUTE_IDS as readonly string[]).includes(v);
+}
+export function isViewId(v: string): v is ViewId {
+  return (VIEW_IDS as readonly string[]).includes(v);
+}
+
+/** Human labels for routes, used in the "unknown route" tool-error message
+ *  and nowhere else — kept tiny on purpose. */
+export const ROUTE_LABELS: Record<RouteId, string> = {
+  chat: "Chat",
+  quantize: "Quantize",
+  finetune: "Fine-tune",
+  dataset: "Build Dataset",
+  status: "Status",
+};
+
+/** A curated spotlight target: a stable id -> the selector to highlight +
+ *  a human label for the popover title, plus which route/view it lives on
+ *  (spotlight_ui navigates there first if the browser isn't already on it).
+ *  This is the "catalog target" resolution path in resolve-spotlight.ts's
+ *  terms — the fallback when ref/label/selector don't resolve from the live
+ *  DOM or the last uiSnapshot. Anchors added to app.html via data-spotlight
+ *  in this same wave; ids are stable and boring (element id minus "chat-"
+ *  prefix noise where it reads fine either way). */
+export interface SpotlightTarget {
+  selector: string;
+  label: string;
+  route?: RouteId;
+  view?: ViewId;
+}
+
+export const SPOTLIGHT_TARGETS: Record<string, SpotlightTarget> = {
+  composer: { selector: "#chat-box", label: "Message box", route: "chat" },
+  send: { selector: "#chat-send", label: "Send", route: "chat" },
+  "new-chat": { selector: "#chat-new", label: "New chat", route: "chat" },
+  "session-search": { selector: "#chat-sess-search", label: "Search chats", route: "chat" },
+  "sampling-pill": { selector: "#chat-sampling", label: "Sampling", route: "chat" },
+  "prompt-pill": { selector: "#chat-sysprompt", label: "System prompt", route: "chat" },
+  "adapter-select": { selector: "#chat-adapter", label: "LoRA adapter", route: "chat" },
+  "memory-entry": { selector: "#chat-memory-entry", label: "Memory", route: "chat" },
+  "developer-toggle": { selector: "#nav-developer", label: "Developer toggle" },
+  "model-picker": { selector: "#nav-model", label: "Active model" },
+  "hub-browse": { selector: "#model-pop-browse", label: "Browse models", view: "hub-panel" },
+  "quantize-source": { selector: "#q-model", label: "Source model", route: "quantize" },
+  "finetune-base": { selector: "#f-model", label: "Base model", route: "finetune" },
+};
+
+export function getSpotlightTarget(id: string): SpotlightTarget | null {
+  return SPOTLIGHT_TARGETS[id] ?? null;
+}
+
+/** Resolve a free-form route/page string (either a bare route id or a
+ *  "#/route" hash) the way navigate_app's tool param is described to the
+ *  model. Returns null for anything not in ROUTE_IDS. */
+export function resolveRouteId(routeOrPage: string): RouteId | null {
+  const bare = routeOrPage.trim().replace(/^#\/?/, "");
+  return isRouteId(bare) ? bare : null;
+}

package/src/web/sw.js

@@ -0,0 +1,71 @@
+// mlx-bun service worker — SHELL ONLY, not offline chat.
+//
+// Scope (plan §9 Phase 3, beat-matrix Axis 10 "PWA installability"):
+// installability + instant shell load. The app is useless without the
+// local inference server actually running (every chat turn is a live
+// WebSocket to this same origin's model process), so caching API/WS
+// traffic would be actively misleading — a "successful" cached response
+// with no model behind it. This worker therefore caches exactly the
+// static shell files needed to paint the UI instantly on repeat visits,
+// and explicitly does NOT intercept /api/*, /v1/*, /ws/*, /downloads, or
+// any other dynamic route — those always go straight to the network,
+// cache-worker or not.
+//
+// Strategy: cache-first for the shell assets below (instant paint from
+// cache, revalidate in the background), network-first fallthrough for
+// everything else (a cache miss or a non-shell request just fetches
+// normally, same as if this worker didn't exist).
+//
+// Versioned by CACHE_NAME so a deploy invalidates old shells; bump the
+// suffix here if the shell file set changes.
+const CACHE_NAME = "mlxbun-shell-v1";
+const SHELL_FILES = [
+  "/",
+  "/assets/app.js",
+  "/assets/hljs.js",
+  "/assets/hljs.css",
+];
+
+self.addEventListener("install", (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => cache.addAll(SHELL_FILES)).then(() => self.skipWaiting()),
+  );
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches.keys()
+      .then((names) => Promise.all(names.filter((n) => n !== CACHE_NAME).map((n) => caches.delete(n))))
+      .then(() => self.clients.claim()),
+  );
+});
+
+self.addEventListener("fetch", (event) => {
+  const req = event.request;
+  // Only ever handle GET; never intercept the WebSocket upgrade or any
+  // mutating request.
+  if (req.method !== "GET") return;
+
+  const url = new URL(req.url);
+  // Same-origin only, and only the exact shell files — everything else
+  // (including /api/*, /v1/*, /downloads, /curves, /dag, and any future
+  // route) falls through to the network untouched. This is the load-
+  // bearing line: it's what keeps "offline chat" from silently
+  // half-working with stale data instead of failing honestly.
+  if (url.origin !== self.location.origin || !SHELL_FILES.includes(url.pathname)) return;
+
+  event.respondWith(
+    caches.match(req).then((cached) => {
+      const network = fetch(req)
+        .then((res) => {
+          if (res && res.ok) caches.open(CACHE_NAME).then((cache) => cache.put(req, res.clone()));
+          return res;
+        })
+        .catch(() => cached); // offline and nothing cached yet — let it reject naturally
+      // Cache-first: serve the cached shell instantly if we have it, and
+      // still revalidate in the background so the next load picks up a
+      // rebuilt app.js. No cache yet (first visit) -> wait on the network.
+      return cached || network;
+    }),
+  );
+});

package/src/web/vendor/README.md

@@ -0,0 +1,61 @@
+# src/web/vendor/ — vendored, no-CDN web assets
+
+Assets here are bundled locally and served same-origin by `src/server.ts`
+(`GET /assets/<name>`, `with { type: "text" }` import — same pattern as
+`src/web/app.html` itself). Nothing in this app loads a script or
+stylesheet from a CDN; this directory is where that tradeoff lives.
+
+## hljs.js — syntax highlighting
+
+`hljs.js` is [highlight.js](https://github.com/highlightjs/highlight.js)
+(BSD-3-Clause, license text in `hljs-LICENSE`) core engine + a curated
+language set: javascript/typescript, python, bash/shell, json, html/xml,
+css, c/cpp, rust, go, sql, yaml, markdown, diff, plaintext. Registered
+languages expose themselves as `class="language-<name>"` on `<code>`
+elements — see `mdCodeBlock()` and `highlightIn()` in `app.html`.
+
+To rebuild (e.g. to bump the version or change the language set):
+
+```sh
+mkdir /tmp/hljs-build && cd /tmp/hljs-build
+npm init -y
+npm install highlight.js@<version> --no-save
+```
+
+Write an `entry.js` that imports `highlight.js/lib/core` and
+`highlight.js/lib/languages/<lang>` for each language you want, calling
+`hljs.registerLanguage(name, lang)` for each (see mlx-bun's own build log /
+commit that introduced this file for the exact entry.js used), then:
+
+```sh
+globalThis.hljs = hljs;   # inside entry.js, after registering
+bun build ./entry.js --minify --outfile=hljs.bundle.js
+```
+
+Prepend a short license/provenance header comment (BSD-3-Clause,
+upstream URL, rebuild instructions — copy the one already at the top of
+`hljs.js`) and copy the result over `src/web/vendor/hljs.js`.
+
+**Size discipline:** the hygiene gate (`scripts/check-hygiene.ts`) fails
+any tracked file over 1 MB unless it's on the explicit allowlist. The
+current bundle (core + 14 languages) is ~83 KB — comfortably under the
+cap. If you add enough languages to bust 1 MB, either trim the language
+list or add a justified, size-capped `ALLOW` entry in
+`scripts/check-hygiene.ts` (see the existing entries there for the
+pattern) — don't silently let it grow past the cap.
+
+`hljs-theme.css` is NOT generated from highlight.js's stock themes — it's
+hand-written, mapping the standard `hljs-*` token classes onto mlx-bun's
+own design tokens (see the file's own header comment) so code blocks match
+the app's palette in both light and dark.
+
+## KaTeX (math) — deliberately not vendored
+
+Investigated for the same treatment; skipped. KaTeX's CSS depends on its
+own bundled math font (`dist/fonts/`, ~60 files / ~1.1 MB of woff2/woff/ttf)
+for correct glyph metrics — there's no clean "system font fallback" path
+that renders math correctly. Vendoring it would mean adding ~1 MB of
+binary font files, which the hygiene gate is specifically designed to keep
+out of this repo (see `scripts/check-hygiene.ts`'s header). Needs the
+build-step/asset-hosting decision from `docs/design/web-chat-redesign.md`
+§7 before it's worth revisiting.

package/src/web/vendor/hljs-LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2006, Ivan Sagalaev.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/src/web/vendor/hljs-theme.css

@@ -0,0 +1,59 @@
+/* Vendored highlight.js theme, hand-derived from mlx-bun's own design
+ * tokens (see the :root / [data-theme="light"] blocks in src/web/app.html)
+ * rather than one of highlight.js's stock themes — keeps code-block colors
+ * on the same palette as the rest of the app in both themes. Code blocks
+ * deliberately keep a dark chrome in BOTH themes (see app.html's
+ * --code-bg/--code-ink comment), so this stylesheet targets a fixed dark
+ * surface rather than swapping with [data-theme="light"] itself; only the
+ * accent hues are shared with the live token set.
+ *
+ * Applies to `.bubble pre code.hljs` (see the highlightIn() hook in
+ * app.html) — every `<span class="hljs-*">` produced by the vendored
+ * hljs.js bundle (src/web/vendor/hljs.js, BSD-3-Clause, see its header).
+ */
+
+.bubble pre code.hljs{ display:block; }
+
+.hljs-comment,
+.hljs-quote{ color:#86868b; font-style:italic; }
+
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-subst,
+.hljs-doctag{ color:#ff375f; }
+
+.hljs-string,
+.hljs-regexp,
+.hljs-addition,
+.hljs-attr,
+.hljs-meta-string{ color:#30d158; }
+
+.hljs-number,
+.hljs-literal,
+.hljs-deletion{ color:#ff9f0a; }
+
+.hljs-title,
+.hljs-title.function_,
+.hljs-title.class_,
+.hljs-section{ color:#64d2ff; }
+
+.hljs-type,
+.hljs-class .hljs-title,
+.hljs-built_in{ color:#bf5af2; }
+
+.hljs-name,
+.hljs-tag,
+.hljs-selector-id,
+.hljs-selector-class{ color:#0a84ff; }
+
+.hljs-variable,
+.hljs-template-variable,
+.hljs-attribute{ color:#ffd60a; }
+
+.hljs-symbol,
+.hljs-bullet,
+.hljs-link,
+.hljs-meta{ color:#5e5ce6; }
+
+.hljs-emphasis{ font-style:italic; }
+.hljs-strong{ font-weight:700; }