mlx-bun 0.0.10 → 0.0.12

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

@@ -0,0 +1,159 @@
+// 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.
+//
+// Model picker (plan §5.6, §9 Phase 2): makes the nav model label
+// (#nav-model, previously a dead <span> with no click handler) open a
+// popover of every downloaded model from GET /library, each with its own
+// fit verdict computed on THIS Mac (`assessment`, from src/fit.ts) — not a
+// generic heuristic like LM Studio's. Investigated: there is no in-process
+// model reload/swap path anywhere in src/server.ts or src/cli.ts (grepped
+// for reload/swapModel/switchModel/loadModel — none exist; the runtime is
+// one model per process by design, same as mlx-lm). So rows offer a
+// copy-able `mlx-bun serve <id>` restart command instead of faking a live
+// swap — live swap is Phase 3's Hub item (docs/design/web-chat-redesign.md
+// §9 Phase 3 "Model Hub"), not invented here.
+
+import { $, setModelPopClose, openHubFromModelPicker } from "./shell";
+import { api } from "./api";
+import { esc } from "./markdown";
+
+export interface LibraryRow {
+  repo_id: string;
+  model_type: string;
+  size_bytes: number;
+  quant_bits: number | null;
+  vision: boolean;
+  supported: boolean;
+  support_tier: "targeted" | "generic" | null;
+  serving: boolean;
+  assessment: { fits: boolean; max_safe_context: number; predicted_decode_tps: number } | null;
+}
+
+function gb(n: number): string { return (n / 2 ** 30).toFixed(1) + " GB"; }
+
+/** Three-tier verdict from the server's honest {fits, predicted_decode_tps}
+ *  (src/fit.ts) — LM Studio's green/yellow/red convention layered on our own
+ *  per-machine numbers, not a second prediction model. green: fits with
+ *  headroom (≥10 tok/s decode — comfortably interactive); yellow: fits but
+ *  slow (<10 tok/s — usable, sluggish); red: doesn't fit the memory budget;
+ *  null: no assessment (unreadable config). Exported so renderRow and any
+ *  future caller share one threshold instead of two copies drifting apart. */
+export function fitVerdict(a: LibraryRow["assessment"]): "green" | "yellow" | "red" | null {
+  if (!a) return null;
+  if (!a.fits) return "red";
+  return a.predicted_decode_tps >= 10 ? "green" : "yellow";
+}
+
+function pickModel(models: LibraryRow[]): LibraryRow[] {
+  // Supported models first (unsupported ones can still be listed so a user
+  // understands "this exists on disk but mlx-bun can't serve it" rather
+  // than it silently vanishing), each group sorted by repo id for a stable,
+  // scannable order — /library itself has no ordering guarantee.
+  return [...models].sort((a, b) => {
+    if (a.serving !== b.serving) return a.serving ? -1 : 1;
+    if (a.supported !== b.supported) return a.supported ? -1 : 1;
+    return a.repo_id.localeCompare(b.repo_id);
+  });
+}
+
+function renderRow(m: LibraryRow): string {
+  const verdict = fitVerdict(m.assessment);
+  const dot = verdict ? '<span class="mp-fit-dot ' + verdict + '" aria-hidden="true"></span>' : '<span class="mp-fit-dot" aria-hidden="true" style="background:var(--dimmer)"></span>';
+  const name = m.repo_id.split("/").pop() || m.repo_id;
+  const quant = m.quant_bits ? m.quant_bits + "-bit" : "unquantized";
+  const metaBits = [gb(m.size_bytes), quant];
+  if (m.vision) metaBits.push("vision");
+  if (!m.supported) metaBits.push("unsupported model family");
+  const tpsBit = m.assessment && m.assessment.fits
+    ? m.assessment.predicted_decode_tps.toFixed(0) + " tok/s predicted"
+    : m.assessment ? "doesn't fit this Mac's memory" : "fit unknown";
+  const servingTag = m.serving ? '<div class="mp-serving-tag">● currently serving</div>' : "";
+  const cmd = "mlx-bun serve " + m.repo_id;
+  const cmdRow = m.serving || !m.supported
+    ? ""
+    : '<div class="mp-cmd"><code>' + esc(cmd) + '</code><button type="button" class="mp-copy" data-cmd="' + esc(cmd) + '">Copy</button></div>';
+  return (
+    '<div class="mp-row' + (m.serving ? " serving" : "") + '">' +
+      dot +
+      '<div class="mp-main">' +
+        '<div class="mp-name" title="' + esc(m.repo_id) + '">' + esc(name) + "</div>" +
+        '<div class="mp-meta">' + esc(metaBits.join(" · ")) + " · " + esc(tpsBit) + "</div>" +
+        servingTag + cmdRow +
+      "</div>" +
+    "</div>"
+  );
+}
+
+/** Pure render of the popover body from a /library response. Exported for
+ *  tests/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 {
+  const browseRow = '<button type="button" class="mp-browse-hub" id="model-pop-browse">Browse models…</button>';
+  if (!models.length) {
+    return '<div class="mp-empty">No models downloaded yet. Use <code>mlx-bun get &lt;repo-id&gt;</code> to fetch one, ' +
+      "or browse Hugging Face below.</div>" + browseRow;
+  }
+  const rows = pickModel(models).map(renderRow).join("");
+  return (
+    rows +
+    '<div class="mp-foot-note">Fit is predicted for THIS Mac (src/fit.ts), not a generic guess. ' +
+    "Switching the served model restarts the process — there's no live " +
+    "in-process swap yet; copy the command above and restart.</div>" +
+    browseRow
+  );
+}
+
+async function refreshModelPop(): Promise<void> {
+  const body = $("model-pop-body");
+  if (!body) return;
+  body.innerHTML = '<div class="mp-empty">Loading…</div>';
+  try {
+    const d = await api("/library");
+    const models = ((d as { models?: LibraryRow[] }).models) || [];
+    body.innerHTML = renderModelPopBodyHtml(models);
+    body.querySelectorAll<HTMLButtonElement>(".mp-copy").forEach((btn) => {
+      btn.onclick = () => {
+        const cmd = btn.dataset.cmd || "";
+        if (navigator.clipboard) {
+          navigator.clipboard.writeText(cmd).then(() => {
+            const prev = btn.textContent; btn.textContent = "Copied";
+            setTimeout(() => { btn.textContent = prev; }, 1200);
+          }).catch(() => {});
+        }
+      };
+    });
+    const browseBtn = body.querySelector<HTMLButtonElement>("#model-pop-browse");
+    if (browseBtn) {
+      browseBtn.onclick = () => {
+        setModelPopOpen(false);
+        if (openHubFromModelPicker) openHubFromModelPicker();
+      };
+    }
+  } catch {
+    body.innerHTML = '<div class="mp-empty">Could not reach the server.</div>';
+  }
+}
+
+let modelPopOpen = false;
+function setModelPopOpen(open: boolean): void {
+  if (open === modelPopOpen) return;
+  modelPopOpen = open;
+  $("model-pop").classList.toggle("open", open);
+  $("nav-model").setAttribute("aria-expanded", String(open));
+  if (open) refreshModelPop();
+}
+export function closeModelPop(): void { setModelPopOpen(false); }
+export function isModelPopOpen(): boolean { return modelPopOpen; }
+
+/** Wire the nav model button + popover. Escape/click-away follow the same
+ *  pattern as the sampling popover (setSamplingPopoverClose) — see
+ *  shell.ts's closeTopOverlay, extended to check this popover too. */
+export function initModelPicker(): void {
+  const btn = $("nav-model");
+  if (!btn) return;
+  btn.onclick = (e) => { e.stopPropagation(); setModelPopOpen(!modelPopOpen); };
+  $("model-pop").addEventListener("click", (e) => e.stopPropagation());
+  document.addEventListener("click", () => setModelPopOpen(false));
+  setModelPopClose(closeModelPop);
+}

package/src/web/src/palette.ts

@@ -0,0 +1,346 @@
+// Command palette (Cmd/Ctrl+K) — plan §9 Phase 3, beat-matrix Axis 10
+// "Command palette" row: ChatGPT/Claude's universal "do anything" entry
+// point. Built 100% via createElement (zero app.html markup — a parallel
+// agent owns chat.ts/app.html this wave); its own CSS is injected once via
+// shell.ts's injectStyles() the same way the panel it opens (hub.ts) has
+// its markup live in app.html but this module can't add any of its own.
+//
+// Actions call EXPORTED functions from the modules that own the behavior
+// (newChat/copyLastResponse via controllers.chat — the same
+// loosely-typed-registry indirection shell.ts's own global keydown sweep
+// and finetune.ts already use to reach chat.ts without a direct import;
+// openMemPanel/openHubPanel are plain exports; theme/developer-mode toggles
+// are plain exports; thinking-toggle and session-open reuse the existing
+// DOM click handlers chat.ts/sessions.ts already wired, via a `.click()` on
+// the real control — never a copy of chat.ts's logic).
+//
+// Full-text "Search messages" delegates to the same GET /api/sessions/search
+// endpoint sessions.ts's sidebar fallback uses (src/serve/session-search.ts)
+// — one server-side implementation, two presentations.
+
+import { controllers, currentRoute, el, injectStyles, isDeveloperMode, setDeveloperMode, setPaletteClose, setPaletteIsOpen, setPaletteOpen, setTheme, trapFocus, type FocusTrap } from "./shell";
+import { openSessionRowByPath, exportSession } from "./sessions";
+import { openMemPanel } from "./memory-panel";
+import { openHubPanel } from "./hub";
+import { api } from "./api";
+
+/* ────────────────────────────────────────────────────────────────────
+   Action model
+   ──────────────────────────────────────────────────────────────────── */
+
+interface PaletteAction {
+  id: string;
+  label: string;
+  hint?: string;
+  /** Actions that only make sense on the chat route are hidden elsewhere
+   *  (matching the existing Cmd/Ctrl+Shift+O/C guards in shell.ts). */
+  chatOnly?: boolean;
+  run(): void | Promise<void>;
+}
+
+/** Pure: the static action list, independent of any live session data —
+ *  independently testable (tests/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[] {
+  return [
+    {
+      id: "new-chat", label: "New chat", hint: "⌘⇧O", chatOnly: true,
+      run() { const fn = controllers.chat && controllers.chat.newChat as (() => void) | undefined; fn && fn(); },
+    },
+    {
+      id: "toggle-thinking", label: "Toggle thinking", chatOnly: true,
+      run() { const btn = document.getElementById("chat-think"); if (btn) btn.click(); },
+    },
+    {
+      id: "toggle-theme", label: "Toggle theme",
+      run() {
+        const order = ["auto", "dark", "light"];
+        const active = document.querySelector<HTMLButtonElement>("#theme-toggle button.active");
+        const cur = (active && active.dataset.themeChoice) || "auto";
+        const next = order[(order.indexOf(cur) + 1) % order.length]!;
+        setTheme(next);
+      },
+    },
+    {
+      id: "toggle-developer", label: "Toggle Developer mode",
+      run() { setDeveloperMode(!isDeveloperMode()); },
+    },
+    {
+      id: "open-memory", label: "Open Memory panel",
+      run() { openMemPanel(); },
+    },
+    {
+      id: "browse-models", label: "Browse models (Hub)",
+      run() { openHubPanel(); },
+    },
+    {
+      id: "open-shortcuts", label: "Open shortcut sheet",
+      run() {
+        const btn = document.getElementById("nav-shortcuts");
+        if (btn) btn.click();
+      },
+    },
+    {
+      id: "export-chat", label: "Export this chat", chatOnly: true,
+      async run() {
+        const activeRow = document.querySelector<HTMLElement>("#chat-sessions .sess.active");
+        if (!activeRow || !activeRow.dataset.path) return;
+        const title = activeRow.querySelector(".stitle")?.textContent || "chat";
+        await exportSession(activeRow.dataset.path, title, "md");
+      },
+    },
+  ];
+}
+
+/** Fuzzy-ish filter: every character of `query` (in order, case-insensitive)
+ *  must appear as a subsequence of the candidate string. Pure. Matches the
+ *  lightweight "fuzzy-filterable" bar the task calls for — not a scored
+ *  fuzzy-match algorithm, a simple subsequence test, which is what every
+ *  Cmd+K palette's basic case actually needs. */
+export function fuzzyMatch(query: string, candidate: string): boolean {
+  const q = query.toLowerCase();
+  const c = candidate.toLowerCase();
+  if (!q) return true;
+  let qi = 0;
+  for (let ci = 0; ci < c.length && qi < q.length; ci++) {
+    if (c[ci] === q[qi]) qi++;
+  }
+  return qi === q.length;
+}
+
+/* ────────────────────────────────────────────────────────────────────
+   Row shapes for the two dynamic sections (session titles / message hits)
+   ──────────────────────────────────────────────────────────────────── */
+
+interface SessionRowRef { path: string; title: string; }
+interface MessageHit { sessionPath: string; sessionTitle: string; snippet: string; }
+
+type PaletteEntry =
+  | { kind: "action"; action: PaletteAction }
+  | { kind: "session"; row: SessionRowRef }
+  | { kind: "message"; hit: MessageHit };
+
+/* ────────────────────────────────────────────────────────────────────
+   Panel chrome
+   ──────────────────────────────────────────────────────────────────── */
+
+let overlay: HTMLElement | null = null;
+let input: HTMLInputElement | null = null;
+let listEl: HTMLElement | null = null;
+let trap: FocusTrap | null = null;
+let selectedIndex = 0;
+let entries: PaletteEntry[] = [];
+let searchSeq = 0;
+let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+
+const STYLE_ID = "mlxbun-palette-style";
+const DEBOUNCE_MS = 200;
+
+function injectPaletteStyles(): void {
+  injectStyles(STYLE_ID, `
+#palette-overlay{position:fixed;inset:0;z-index:900;display:none;
+  align-items:flex-start;justify-content:center;padding-top:12vh;
+  background:rgba(0,0,0,.45);backdrop-filter:blur(2px);}
+#palette-overlay.open{display:flex;}
+@media (prefers-reduced-motion:no-preference){
+  #palette-overlay.open .palette-box{animation:palette-in .15s ease-out;}
+}
+@keyframes palette-in{from{opacity:0;transform:translateY(-6px) scale(.98);}to{opacity:1;transform:none;}}
+.palette-box{width:min(560px,92vw);max-height:70vh;display:flex;flex-direction:column;
+  background:var(--bg,#000);border:1px solid var(--hairline-strong,rgba(255,255,255,.28));
+  border-radius:14px;box-shadow:0 20px 60px rgba(0,0,0,.5);overflow:hidden;}
+.palette-input-row{border-bottom:1px solid var(--hairline,rgba(255,255,255,.14));padding:4px 4px;}
+#palette-input{width:100%;box-sizing:border-box;background:transparent;border:0;outline:0;
+  color:var(--ink,#fff);font-size:15px;padding:12px 14px;}
+#palette-input::placeholder{color:var(--dimmer,#515154);}
+.palette-list{overflow-y:auto;flex:1;padding:6px;}
+.palette-section-hdr{font-size:11px;color:var(--dim,#86868b);text-transform:uppercase;
+  letter-spacing:.04em;padding:8px 10px 4px;}
+.palette-row{display:flex;align-items:center;justify-content:space-between;gap:8px;
+  padding:9px 10px;border-radius:8px;cursor:pointer;color:var(--ink,#fff);font-size:13.5px;}
+.palette-row:hover,.palette-row.active{background:var(--card-hover,rgba(255,255,255,.08));}
+.palette-row .prow-label{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+.palette-row .prow-snippet{color:var(--dim,#86868b);font-size:11.5px;overflow:hidden;
+  text-overflow:ellipsis;white-space:nowrap;margin-top:1px;}
+.palette-row .prow-main{min-width:0;flex:1;}
+.palette-row .prow-hint{color:var(--dimmer,#515154);font-size:11px;font-family:var(--mono,monospace);
+  flex:0 0 auto;}
+.palette-empty{color:var(--dim,#86868b);font-size:13px;padding:16px 10px;text-align:center;}
+.palette-row mark{background:rgba(255,214,10,.35);color:inherit;border-radius:2px;}
+`);
+}
+
+export function isPaletteOpen(): boolean {
+  return !!overlay && overlay.classList.contains("open");
+}
+
+export function closePalette(): void {
+  if (!overlay) return;
+  overlay.classList.remove("open");
+  if (trap) trap.restore();
+}
+
+export function openPalette(): void {
+  ensureBuilt();
+  if (!overlay || !input || !trap) return;
+  trap.capture();
+  overlay.classList.add("open");
+  input.value = "";
+  refreshResults("");
+  setTimeout(() => input && input.focus(), 20);
+}
+
+function ensureBuilt(): void {
+  if (overlay) return;
+  injectPaletteStyles();
+  overlay = el("div", "", document.body);
+  overlay.id = "palette-overlay";
+  overlay.setAttribute("role", "dialog");
+  overlay.setAttribute("aria-modal", "true");
+  overlay.setAttribute("aria-label", "Command palette");
+
+  const box = el("div", "palette-box", overlay);
+  const inputRow = el("div", "palette-input-row", box);
+  input = el("input", "", inputRow);
+  input.id = "palette-input";
+  input.type = "text";
+  input.placeholder = "Type a command or search…";
+  input.autocomplete = "off";
+  input.spellcheck = false;
+  listEl = el("div", "palette-list", box);
+  listEl.setAttribute("role", "listbox");
+
+  overlay.addEventListener("click", (e) => { if (e.target === overlay) closePalette(); });
+  input.addEventListener("input", () => {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    const q = input!.value;
+    debounceTimer = setTimeout(() => refreshResults(q), DEBOUNCE_MS);
+  });
+  input.addEventListener("keydown", onKeydown);
+
+  trap = trapFocus(overlay, isPaletteOpen);
+}
+
+function onKeydown(e: KeyboardEvent): void {
+  if (e.key === "ArrowDown") { e.preventDefault(); move(1); return; }
+  if (e.key === "ArrowUp") { e.preventDefault(); move(-1); return; }
+  if (e.key === "Enter") { e.preventDefault(); activate(selectedIndex); return; }
+  // Escape is handled by shell.ts's global closeTopOverlay sweep (this
+  // module registers isOpen/close via setPaletteIsOpen/setPaletteClose in
+  // ensureBuilt() above) — no bespoke Escape listener needed here.
+}
+
+function move(delta: number): void {
+  if (!entries.length) return;
+  selectedIndex = (selectedIndex + delta + entries.length) % entries.length;
+  renderRows();
+  const activeEl = listEl?.querySelector(".palette-row.active");
+  if (activeEl) activeEl.scrollIntoView({ block: "nearest" });
+}
+
+function activate(index: number): void {
+  const entry = entries[index];
+  if (!entry) return;
+  if (entry.kind === "action") { closePalette(); entry.action.run(); return; }
+  if (entry.kind === "session") { closePalette(); openSessionRowByPath(entry.row.path); return; }
+  if (entry.kind === "message") { closePalette(); openSessionRowByPath(entry.hit.sessionPath); return; }
+}
+
+/* ────────────────────────────────────────────────────────────────────
+   Results: static actions (fuzzy-filtered) + session title matches +
+   full-text message matches (debounced server round trip).
+   ──────────────────────────────────────────────────────────────────── */
+
+function matchingActions(query: string): PaletteAction[] {
+  const onChat = currentRoute() === "chat";
+  return staticActions()
+    .filter((a) => (onChat || !a.chatOnly))
+    .filter((a) => fuzzyMatch(query, a.label));
+}
+
+function matchingSessionRows(query: string): SessionRowRef[] {
+  const rows = document.querySelectorAll<HTMLElement>("#chat-sessions .sess");
+  const out: SessionRowRef[] = [];
+  rows.forEach((row) => {
+    const title = row.querySelector(".stitle")?.textContent || "New chat";
+    const path = row.dataset.path;
+    if (!path) return;
+    if (fuzzyMatch(query, title)) out.push({ path, title });
+  });
+  return out.slice(0, 6);
+}
+
+async function refreshResults(query: string): Promise<void> {
+  selectedIndex = 0;
+  const q = query.trim();
+  const actionEntries: PaletteEntry[] = matchingActions(q).map((action) => ({ kind: "action", action }));
+  const sessionEntries: PaletteEntry[] = q ? matchingSessionRows(q).map((row) => ({ kind: "session", row })) : [];
+  entries = [...actionEntries, ...sessionEntries];
+  renderRows();
+
+  if (!q || q.length < 2) return;
+  const seq = ++searchSeq;
+  const d = await api("/api/sessions/search?q=" + encodeURIComponent(q)).catch(() => ({ ok: false } as { ok: boolean }));
+  if (seq !== searchSeq) return; // superseded by a newer keystroke
+  if (input && input.value.trim() !== q) return;
+  const body = d as { ok: boolean; results?: Array<{ sessionPath: string; sessionTitle: string; matches: Array<{ snippet: string }> }> };
+  if (!body.ok || !body.results || !body.results.length) return;
+  const messageEntries: PaletteEntry[] = body.results.slice(0, 6).map((r) => ({
+    kind: "message",
+    hit: { sessionPath: r.sessionPath, sessionTitle: r.sessionTitle, snippet: r.matches[0]?.snippet || "" },
+  }));
+  entries = [...actionEntries, ...sessionEntries, ...messageEntries];
+  renderRows();
+}
+
+function esc(s: unknown): string {
+  return String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" } as Record<string, string>)[c]!);
+}
+
+function renderRows(): void {
+  if (!listEl) return;
+  if (!entries.length) {
+    listEl.innerHTML = '<div class="palette-empty">No matching commands or chats.</div>';
+    return;
+  }
+  listEl.innerHTML = "";
+  let sawActionHdr = false, sawSessionHdr = false, sawMessageHdr = false;
+  entries.forEach((entry, i) => {
+    if (entry.kind === "action" && !sawActionHdr) { el("div", "palette-section-hdr", listEl!).textContent = "Commands"; sawActionHdr = true; }
+    if (entry.kind === "session" && !sawSessionHdr) { el("div", "palette-section-hdr", listEl!).textContent = "Chats"; sawSessionHdr = true; }
+    if (entry.kind === "message" && !sawMessageHdr) { el("div", "palette-section-hdr", listEl!).textContent = "In messages"; sawMessageHdr = true; }
+
+    const row = el("div", "palette-row" + (i === selectedIndex ? " active" : ""), listEl!);
+    row.setAttribute("role", "option");
+    row.dataset.index = String(i);
+    if (entry.kind === "action") {
+      row.innerHTML =
+        '<div class="prow-main"><div class="prow-label">' + esc(entry.action.label) + '</div></div>' +
+        (entry.action.hint ? '<span class="prow-hint">' + esc(entry.action.hint) + '</span>' : "");
+    } else if (entry.kind === "session") {
+      row.innerHTML = '<div class="prow-main"><div class="prow-label">' + esc(entry.row.title) + '</div></div>';
+    } else {
+      row.innerHTML =
+        '<div class="prow-main"><div class="prow-label">' + esc(entry.hit.sessionTitle) + '</div>' +
+        '<div class="prow-snippet">' + esc(entry.hit.snippet) + '</div></div>';
+    }
+    row.addEventListener("click", () => activate(i));
+    row.addEventListener("mousemove", () => { if (selectedIndex !== i) { selectedIndex = i; renderRows(); } });
+  });
+}
+
+/** Wire the palette module: styles + registered callbacks so shell.ts's
+ *  Cmd/Ctrl+K binding and Escape sweep can reach it. Call once at boot
+ *  (main.ts), same lifecycle as initHubPanel()/initMemoryPanel(). Building
+ *  the DOM itself is deferred to the first open (ensureBuilt(), called from
+ *  openPalette()) so a browser session that never opens the palette pays
+ *  zero DOM cost for it — consistent with the other overlays' lazy-init
+ *  posture is NOT how they work today (they build eagerly at init()), but
+ *  this module has no app.html anchor element to hang an eager build off
+ *  of, so lazy-on-first-open is the natural shape here instead. */
+export function initPalette(): void {
+  setPaletteClose(closePalette);
+  setPaletteIsOpen(isPaletteOpen);
+  setPaletteOpen(openPalette);
+}

package/src/web/src/protocol.ts

@@ -0,0 +1,62 @@
+// 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 };
+
+/** 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 {
+  log?: (e: Extract<JobEvent, { type: "log" }>) => void;
+  stage?: (e: Extract<JobEvent, { type: "stage" }>) => void;
+  metric?: (e: Extract<JobEvent, { type: "metric" }>) => void;
+  done?: (e: Extract<JobEvent, { type: "done" }>) => void;
+  failed?: (e: Extract<JobEvent, { type: "failed" }>) => void;
+  error?: () => void;
+}
+
+/** Generic envelope every /api/* JSON endpoint returns on success or
+ *  failure (api() in api.ts unwraps {error:{message}} to a plain string —
+ *  see the doc-comment there). Individual endpoints add their own fields
+ *  on top via intersection at the call site; this is just the shared base. */
+export interface ApiEnvelope {
+  ok?: boolean;
+  error?: string;
+  message?: string;
+  [key: string]: unknown;
+}