ompchamber 1.0.0 → 1.1.0

package/src/client/hooks/chat/timeline/deferred-model.test.ts

@@ -0,0 +1,219 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A composer model/thinking pick made while a turn is streaming must not reach
+ * the live session: omp applies `set_model` to the RUNNING turn, so pushing it
+ * immediately re-targets the answer in flight (verified against omp's RPC
+ * handler and by driving a live session — one run answered its first turn on
+ * the old model and its next turns on the new one).
+ *
+ * The pick is held and pushed right before the next prompt instead. These run
+ * against a real DOM (happy-dom) because the hooks are Preact hooks: the
+ * modules below are imported inside `beforeAll`, after those globals exist,
+ * since Preact binds its environment at evaluation time.
+ */
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import type { h as PreactH, render as PreactRender } from 'preact';
+import type { act as PreactAct } from 'preact/test-utils';
+import type { useChatTimelineActions as UseChatTimelineActions, ChatTimelineActionsResult } from '@/client/hooks/chat/timeline/actions';
+import type { ComposerModelPick, DeferredModelStore } from '@/client/hooks/chat/timeline/deferred-model';
+import { flushDeferredPick } from '@/client/hooks/chat/timeline/deferred-model';
+import type { OmpAgentHandle } from '@/shared/types';
+
+let useChatTimelineActions: typeof UseChatTimelineActions;
+let h: typeof PreactH;
+let render: typeof PreactRender;
+let act: typeof PreactAct;
+
+let container: HTMLElement;
+
+interface Harness {
+  calls: string[];
+  deferred: { current: ComposerModelPick | null };
+  actions: ChatTimelineActionsResult;
+}
+
+/** A recording agent handle plus the calls it received. */
+function makeAgent() {
+  const calls: string[] = [];
+  const agent = {
+    setModel: async (provider: string, modelId: string) => { calls.push(`set_model:${provider}/${modelId}`); },
+    setThinkingLevel: async (level: string) => { calls.push(`set_thinking_level:${level}`); },
+  } as unknown as OmpAgentHandle;
+  return { calls, agent };
+}
+
+/** Mounts the real hook and records every model/thinking RPC it pushes. */
+async function mountActions(isGenerating: boolean, stashed: ComposerModelPick | null): Promise<Harness> {
+  const deferred: { current: ComposerModelPick | null } = { current: stashed };
+  const { calls, agent } = makeAgent();
+
+  const captured: ChatTimelineActionsResult[] = [];
+  const Probe = () => {
+    captured.push(useChatTimelineActions({
+      inputValue: '',
+      setInputValue: () => {},
+      setInputAttachments: () => {},
+      isGenerating,
+      isOmpSession: true,
+      sessionId: '01a0ca36-f3be-7252-a95c-3d45d180c539',
+      appSettings: {},
+      messageQueue: [],
+      enqueueMessage: () => {},
+      removeMessage: () => {},
+      executeSend: async () => {},
+      steerOmpAgent: async () => {},
+      ompAgent: agent,
+      abortControllerRef: { current: null },
+      setGenerating: () => {},
+      stopHoldRef: { current: false },
+      persistMessages: () => {},
+      setLocalMessages: () => {},
+      pendingComposerModelRef: { current: null },
+      pendingThinkingLevelRef: { current: null },
+      composerModelRef: { current: null },
+      deferredComposerPickRef: deferred,
+      accessModeRef: { current: 'yolo' },
+      setSearchParams: () => {},
+    }));
+    return null;
+  };
+  await act(async () => {
+    render(h(Probe, {}), container);
+  });
+  // The handlers fire-and-forget their RPC, so let the microtask chain settle.
+  for (let i = 0; i < 10; i++) await Promise.resolve();
+  return { calls, deferred, actions: captured[captured.length - 1] };
+}
+
+/** The DOM surface this file installs for Preact to render into. */
+function domGlobals(win: Window): Record<string, unknown> {
+  return {
+    window: win,
+    document: win.document,
+    navigator: win.navigator,
+    Node: win.Node,
+    Element: win.Element,
+    HTMLElement: win.HTMLElement,
+  };
+}
+
+const installed: Record<string, unknown> = {};
+const displaced: Record<string, unknown> = {};
+
+beforeAll(async () => {
+  const win = new Window({ url: 'http://localhost' });
+  for (const [key, value] of Object.entries(domGlobals(win))) {
+    displaced[key] = (globalThis as Record<string, unknown>)[key];
+    installed[key] = value;
+    (globalThis as Record<string, unknown>)[key] = value;
+  }
+  ({ useChatTimelineActions } = await import('@/client/hooks/chat/timeline/actions'));
+  ({ h, render } = await import('preact'));
+  ({ act } = await import('preact/test-utils'));
+});
+
+// Every test file shares one process, so the globals go back the way they were.
+afterAll(() => {
+  for (const key of Object.keys(installed)) {
+    if (displaced[key] === undefined) delete (globalThis as Record<string, unknown>)[key];
+    else (globalThis as Record<string, unknown>)[key] = displaced[key];
+  }
+});
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+
+describe('composer model/thinking picks during a stream', () => {
+  test('a mid-stream model pick sends no RPC and is stashed', async () => {
+    const { calls, deferred, actions } = await mountActions(true, null);
+    actions.handleModelChange('kenari', 'deepseek-v4-pro');
+
+    expect(calls).toEqual([]);
+    expect(deferred.current).toEqual({ provider: 'kenari', modelId: 'deepseek-v4-pro' });
+  });
+
+  test('a mid-stream thinking pick sends no RPC and is stashed', async () => {
+    const { calls, deferred, actions } = await mountActions(true, null);
+    actions.handleThinkingLevelChange('high');
+
+    expect(calls).toEqual([]);
+    expect(deferred.current).toEqual({ thinkingLevel: 'high' });
+  });
+
+  test('model then thinking mid-stream both survive to the next prompt', async () => {
+    const { calls, deferred, actions } = await mountActions(true, null);
+    actions.handleModelChange('kenari', 'deepseek-v4-pro');
+    actions.handleThinkingLevelChange('max');
+
+    expect(calls).toEqual([]);
+    expect(deferred.current).toEqual({ provider: 'kenari', modelId: 'deepseek-v4-pro', thinkingLevel: 'max' });
+  });
+
+  test('an idle pick reaches the session immediately', async () => {
+    const { calls, deferred, actions } = await mountActions(false, null);
+    actions.handleModelChange('kenari', 'deepseek-v4-pro');
+    actions.handleThinkingLevelChange('high');
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+
+    expect(calls).toEqual(['set_model:kenari/deepseek-v4-pro', 'set_thinking_level:high']);
+    expect(deferred.current).toBeNull();
+  });
+
+  test('an idle model pick leaves a stashed thinking level pending', async () => {
+    const { calls, deferred, actions } = await mountActions(false, { thinkingLevel: 'high' });
+    actions.handleModelChange('kenari', 'deepseek-v4-pro');
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+
+    // The level was never applied here, so it must still wait for the next
+    // prompt rather than being dropped or pushed now.
+    expect(calls).toEqual(['set_model:kenari/deepseek-v4-pro']);
+    expect(deferred.current).toEqual({ thinkingLevel: 'high' });
+  });
+
+  test("'auto' thinking is never pushed onto the live session", async () => {
+    const { calls, deferred, actions } = await mountActions(false, null);
+    actions.handleThinkingLevelChange('auto');
+
+    expect(calls).toEqual([]);
+    expect(deferred.current).toBeNull();
+  });
+});
+
+describe('flushing a pick onto the session', () => {
+  test('pushes the stashed model and thinking level, then clears the slot', async () => {
+    const { calls, agent } = makeAgent();
+    const store: DeferredModelStore = { current: { provider: 'kenari', modelId: 'deepseek-v4-pro', thinkingLevel: 'max' } };
+
+    await flushDeferredPick(agent, store);
+
+    expect(calls).toEqual(['set_model:kenari/deepseek-v4-pro', 'set_thinking_level:max']);
+    expect(store.current).toBeNull();
+  });
+
+  test("a stashed 'auto' level is not pushed as a concrete level", async () => {
+    const { calls, agent } = makeAgent();
+    const store: DeferredModelStore = { current: { provider: 'kenari', modelId: 'deepseek-v4-pro', thinkingLevel: 'auto' } };
+
+    await flushDeferredPick(agent, store);
+
+    expect(calls).toEqual(['set_model:kenari/deepseek-v4-pro']);
+    expect(store.current).toBeNull();
+  });
+
+  test('flushing an empty slot sends nothing', async () => {
+    const { calls, agent } = makeAgent();
+    const store: DeferredModelStore = { current: null };
+
+    await flushDeferredPick(agent, store);
+
+    expect(calls).toEqual([]);
+  });
+});

package/src/client/hooks/chat/timeline/deferred-model.ts

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Composer model/thinking picks that must NOT reach the live session yet.
+ *
+ * omp applies `set_model` / `set_thinking_level` to the RUNNING turn: the next
+ * LLM call inside the stream (the one after a tool result) goes out on the new
+ * model, so a pick made while an answer streams visibly re-targets that answer
+ * mid-flight. A composer pick is intent for the NEXT prompt, so while a turn is
+ * running it is stashed here and pushed to the session right before the next
+ * prompt the composer starts (plain send, steer, or queued delivery).
+ *
+ * The slot holds only what has NOT reached the session yet, so a pick applied
+ * directly (idle composer) clears exactly the fields it applied — a stashed
+ * thinking level survives a later model change instead of being resurrected
+ * over it.
+ *
+ * Verified against omp's RPC handler: `set_model` resolves the model and calls
+ * the session's `setModel` immediately — nothing defers it to a turn boundary.
+ */
+
+import type { OmpAgentHandle } from '@/shared/types';
+
+/** Fields a composer pick can carry; each handler owns its own. */
+export interface ComposerModelPick {
+  provider?: string;
+  modelId?: string;
+  thinkingLevel?: string;
+}
+
+/** Mutable slot the timeline hook owns; the composer and send paths share it. */
+export interface DeferredModelStore {
+  current: ComposerModelPick | null;
+}
+
+/**
+ * Slot that never holds a pick, for composers with no stream to defer against
+ * (the New Chat modal): every guard reads it as "nothing pending", so their
+ * adoption behaviour stays exactly as it was.
+ */
+export const NO_PENDING_PICK: DeferredModelStore = { current: null };
+
+/** A pick that names a model must name both halves of it. */
+function hasModel(pick: ComposerModelPick): pick is ComposerModelPick & { provider: string; modelId: string } {
+  return Boolean(pick.provider && pick.modelId);
+}
+
+/**
+ * Record a pick made while a turn is streaming. Merged over the previous stash
+ * so a model pick and a later thinking pick both survive to the next prompt.
+ */
+export function stashComposerPick(store: DeferredModelStore, pick: ComposerModelPick): void {
+  store.current = { ...store.current, ...pick };
+}
+
+/**
+ * Drop the fields a pick just applied directly, keeping any still-pending ones.
+ * Without this, a stashed pick would be flushed over the newer selection on the
+ * next send and silently revert the user's latest choice.
+ */
+export function consumeComposerPick(store: DeferredModelStore, pick: ComposerModelPick): void {
+  const pending = store.current;
+  if (!pending) return;
+  const next: ComposerModelPick = { ...pending };
+  if (pick.provider || pick.modelId) {
+    delete next.provider;
+    delete next.modelId;
+  }
+  if (pick.thinkingLevel) delete next.thinkingLevel;
+  store.current = next.provider || next.modelId || next.thinkingLevel ? next : null;
+}
+
+/**
+ * Push a pick onto the live session. `thinkingLevel: 'auto'` means "leave omp's
+ * level alone" — the same rule the send path applies — so it is skipped rather
+ * than translated into a concrete level.
+ */
+export async function applyComposerPick(agent: OmpAgentHandle, pick: ComposerModelPick): Promise<void> {
+  if (hasModel(pick)) await agent.setModel(pick.provider, pick.modelId);
+  if (pick.thinkingLevel && pick.thinkingLevel !== 'auto') await agent.setThinkingLevel(pick.thinkingLevel);
+}
+
+/** Push the stashed pick (if any) onto the session and clear the slot. */
+export async function flushDeferredPick(agent: OmpAgentHandle, store: DeferredModelStore): Promise<void> {
+  const pick = store.current;
+  if (!pick) return;
+  store.current = null;
+  await applyComposerPick(agent, pick);
+}

package/src/client/hooks/chat/timeline/index.ts

@@ -8,6 +8,7 @@ import { useChatTimelineScroll } from '@/client/hooks/chat/timeline/scroll';
 import { useTimelineAutoScroll } from '@/client/hooks/chat/timeline/auto-scroll';
 import { useChatTimelineActions } from '@/client/hooks/chat/timeline/actions';
 import { useChatTimelineSend } from '@/client/hooks/chat/timeline/send';
+import type { ComposerModelPick } from '@/client/hooks/chat/timeline/deferred-model';
 import { useSessionLoad } from '@/client/hooks/chat/timeline/session-load';
 import { useBrowserPageContextInsert } from '@/client/hooks/chat/timeline/browser-context';
 import { cancelStreamingCoalescer, createOmpAgentCallbacks } from '@/shared/lib/chat/timeline/omp-callbacks';
@@ -148,6 +149,15 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
   // Live mirror of the composer's model/thinking pick: the enqueue path
   // snapshots it onto queued items so auto-delivery replays those settings.
   const composerModelRef = useRef<{ provider: string; modelId: string; thinkingLevel: string } | null>(null);
+  // Picks made WHILE a turn streams: held here so they cannot re-target the
+  // answer in flight (omp applies set_model to the running turn), and pushed
+  // onto the session right before the next prompt.
+  const deferredComposerPickRef = useRef<ComposerModelPick | null>(null);
+  // A stashed pick belongs to ONE session's next prompt: carrying it across a
+  // switch would silently re-target the session the user just opened.
+  useEffect(() => {
+    deferredComposerPickRef.current = null;
+  }, [sessionId]);
 
   // Access-control mode is a global, persisted user preference (unlike the
   // per-session model/thinking picks): it hydrates from appSettings at first
@@ -229,7 +239,7 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
     seedSession,
     pendingComposerModelRef,
     pendingThinkingLevelRef,
-    composerModelRef,
+    deferredComposerPickRef,
     accessModeRef,
     abortControllerRef,
     setInputValue,
@@ -274,6 +284,7 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
     pendingComposerModelRef,
     pendingThinkingLevelRef,
     composerModelRef,
+    deferredComposerPickRef,
     accessModeRef,
     setSearchParams,
   });
@@ -321,6 +332,7 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
     accessMode,
     handleAccessModeChange,
     composerModelRef,
+    deferredComposerPickRef,
     extensionDialogs,
     resolveExtensionDialog,
     respondToExtensionUi: ompAgent.respondToExtensionUi,

package/src/client/hooks/chat/timeline/send.ts

@@ -17,6 +17,7 @@ import type { ApprovalMode } from '@/shared/lib/omp/config/access-mode';
 import { streamChatResponse } from '@/client/hooks/chat/stream';
 import type { SessionSeed } from '@/client/hooks/chat/timeline/session-load';
 import { buildPromptText } from '@/client/hooks/chat/timeline/prompt-text';
+import { flushDeferredPick, type DeferredModelStore } from '@/client/hooks/chat/timeline/deferred-model';
 import { isTextAttachmentFile } from '@/shared/lib/chat/attachments';
 import { createMockStreamCallbacks } from '@/shared/lib/chat/timeline/stream-callbacks';
 import { PHASE_VERBS } from '@/shared/lib/chat/timeline/tool-phrases';
@@ -51,9 +52,9 @@ export interface ChatTimelineSendDeps {
   /** Global access-control mode (persisted user preference), read at send time
    *  so the spawn-capable requests carry the latest value. */
   accessModeRef: { current: ApprovalMode };
-  /** Live composer model/thinking mirror (written by ChatInput) so enqueue can
-   *  snapshot the selection onto queued items. */
-  composerModelRef: { current: { provider: string; modelId: string; thinkingLevel: string } | null };
+  /** Picks the composer made while a turn was streaming. Pushed onto the
+   *  session here, immediately before the prompt they were meant for. */
+  deferredComposerPickRef: DeferredModelStore;
   abortControllerRef: { current: AbortController | null };
   setInputValue: (v: string) => void;
   setSearchParams: (fn: (prev: URLSearchParams) => URLSearchParams, opts?: { replace?: boolean }) => void;
@@ -91,6 +92,7 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
     seedSession,
     pendingComposerModelRef,
     pendingThinkingLevelRef,
+    deferredComposerPickRef,
     accessModeRef,
     abortControllerRef,
     setInputValue,
@@ -133,10 +135,13 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
 
   // Steer the running omp agent with a fresh prompt (interrupt-and-reply).
   const steerOmpAgent = useCallback(async (text: string, attachments: Attachment[]) => {
+    // A steer IS a new prompt: a pick made during the interrupted turn belongs
+    // to it, so it is pushed before the interrupt-and-reply starts the turn.
+    await flushDeferredPick(ompAgent, deferredComposerPickRef);
     const { promptText, images } = await prepareDeliverable(text, attachments);
     const ok = await ompAgent.sendInterruptAndReply(promptText, images);
     if (!ok) setInputValue(text);
-  }, [ompAgent, prepareDeliverable, setInputValue]);
+  }, [ompAgent, prepareDeliverable, setInputValue, deferredComposerPickRef]);
 
   const executeSend = useCallback(async (
     text: string,
@@ -209,6 +214,12 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
     if (isOmpSession) {
       aiPlaceholderIdRef.current = aiPlaceholderId;
       optimisticUserIdRef.current = userMsgId;
+      // A model/thinking pick made while the previous turn streamed was held
+      // back so it could not re-target that answer. A queued delivery does NOT
+      // own it: that item carries its own snapshot, so the pick stays pending
+      // for the composer's own next prompt instead of being spent — and then
+      // overwritten — by a delivery it was never meant for.
+      if (!modelOverride) await flushDeferredPick(ompAgent, deferredComposerPickRef);
       // Replay the queued snapshot first so the prompt runs on the exact
       // model/thinking the item was queued with.
       if (modelOverride) {
@@ -329,6 +340,6 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
         scrollToBottom,
       })
     );
-  }, [appSettings, folders, isOmpSession, ompAgent, selectedFolderId, sessionId, scrollToBottom, jumpToBottom, persistMessages, seedSession, pendingComposerModelRef, pendingThinkingLevelRef, accessModeRef]);
+  }, [appSettings, folders, isOmpSession, ompAgent, selectedFolderId, sessionId, scrollToBottom, jumpToBottom, persistMessages, seedSession, pendingComposerModelRef, pendingThinkingLevelRef, deferredComposerPickRef, accessModeRef]);
   return { steerOmpAgent, executeSend };
 }

package/src/client/hooks/workspace/available-width.ts

@@ -0,0 +1,33 @@
+import { useEffect, useState } from 'preact/hooks';
+import type { RefObject } from 'preact';
+
+/**
+ * Measure an element's content width and keep it current.
+ *
+ * Panel widths are stored as a share of the group's available area, so the
+ * group has to report that area before any fraction can become pixels. Returns
+ * `null` until the first measurement — callers must treat that as "unknown",
+ * not as zero, or a panel would collapse on its first render.
+ *
+ * `ResizeObserver` is not optional here: the width changes on a window resize,
+ * on a devtools dock, and on a sibling panel being toggled, and none of those
+ * are `window` events.
+ */
+export function useAvailableWidth(ref: RefObject<HTMLElement | null>): number | null {
+  const [available, setAvailable] = useState<number | null>(null);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (!element || typeof ResizeObserver === 'undefined') return;
+
+    const observer = new ResizeObserver(() => {
+      setAvailable(element.clientWidth || null);
+    });
+    observer.observe(element);
+    setAvailable(element.clientWidth || null);
+
+    return () => observer.disconnect();
+  }, [ref]);
+
+  return available;
+}

package/src/client/hooks/workspace/panel-widths.ts

@@ -1,59 +1,56 @@
-import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
-import type { RefObject } from 'preact/compat';
-import { mergePanelWidths, normalizePanelWidths, type PanelWidths } from '@/shared/lib/workspace/panel-widths';
+import { useCallback, useMemo } from 'preact/hooks';
+import {
+  mergePanelWidths,
+  normalizePanelWidths,
+  type PanelWidths,
+} from '@/shared/lib/workspace/panel-widths';
 import type { RightPanelType } from '@/shared/lib/workspace/right-panels';
-import { writeSetting } from '@/shared/lib/settings/client';
+import { useSessionState } from '@/client/hooks/workspace/session-state';
 
-/** A drag commits once, after the pointer is released; this only coalesces. */
-const PERSIST_DEBOUNCE_MS = 500;
+/** Session-state key holding this session's own per-panel widths. */
+const PANEL_WIDTHS_KEY = 'layout.panelWidths';
 
 interface PanelWidthsResult {
   widths: PanelWidths;
-  /** Live widths, for imperative restores that cannot wait on a re-render. */
-  widthsRef: RefObject<PanelWidths>;
-  /** Fold measured panel widths in and persist the merged map. */
+  /** Fold measured panel widths into this session's map. */
   commitWidths: (patch: PanelWidths) => void;
 }
 
 /**
- * Owns the desktop layout's per-panel width map: restored from
- * `app_settings.desktopLayoutSizes`, kept in a ref for resize handlers, and
- * written back (debounced) whenever a panel is resized. One writer for both
- * resizable groups, so neither clobbers the other's widths.
+ * Owns the desktop layout's per-panel width map.
+ *
+ * Widths are **per session**: they live in `session_ui_state` under
+ * `layout.panelWidths`, next to the rest of a session's layout state
+ * (`layout.activeRightPanel`, `layout.showRightPanel`, `layout.openedFiles`), so
+ * switching sessions brings back the layout that session was left in.
+ *
+ * `app_settings.desktopLayoutSizes` is the **seed**: a session that has never
+ * been resized reads it, which is what keeps an existing user's layout across
+ * the upgrade instead of resetting everyone to the defaults. Once a panel is
+ * dragged, the session stores its own map and the seed is no longer consulted
+ * for that session.
+ *
+ * There is deliberately no px→fraction rewrite pass here. Converting a legacy
+ * pixel value is done when a width is *read* (`resolvePanelWidth`), because a
+ * write would have to run before this session's own blob has loaded and would
+ * therefore overwrite it with the seed.
  */
 export function usePanelWidths(
   appSettings: Record<string, any>,
   legacyView: RightPanelType,
 ): PanelWidthsResult {
-  const [widths, setWidths] = useState<PanelWidths>(() =>
-    normalizePanelWidths(appSettings.desktopLayoutSizes, legacyView),
+  const seed = useMemo(
+    () => normalizePanelWidths(appSettings.desktopLayoutSizes, legacyView),
+    [appSettings.desktopLayoutSizes, legacyView],
   );
-  const widthsRef = useRef<PanelWidths>(widths);
-  // Set while a debounced write is pending, which is also the flush condition.
-  const timerRef = useRef<number | undefined>(undefined);
-
-  const saveNow = useCallback(() => {
-    clearTimeout(timerRef.current);
-    timerRef.current = undefined;
-    writeSetting('desktopLayoutSizes', widthsRef.current);
-  }, []);
+  const [widths, setWidths] = useSessionState<PanelWidths>(PANEL_WIDTHS_KEY, seed);
 
   const commitWidths = useCallback(
     (patch: PanelWidths) => {
-      const next = mergePanelWidths(widthsRef.current, patch);
-      widthsRef.current = next;
-      setWidths(next);
-      clearTimeout(timerRef.current);
-      timerRef.current = window.setTimeout(saveNow, PERSIST_DEBOUNCE_MS);
+      setWidths((prev) => mergePanelWidths(prev, patch));
     },
-    [saveNow],
+    [setWidths],
   );
 
-  // The mobile layout unmounts this hook; flush instead of dropping the width
-  // the user just dragged.
-  useEffect(() => () => {
-    if (timerRef.current !== undefined) saveNow();
-  }, [saveNow]);
-
-  return { widths, widthsRef, commitWidths };
+  return { widths, commitWidths };
 }

package/src/server/lib/models/preferences.server.ts

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Persistence for the user's favorite + last-used models.
+ *
+ * Lives apart from the model registry because a favorite is NOT a property of
+ * omp's registry: the catalog the route used to mutate (`omp_models_catalog`)
+ * is a MOCK-only demo list that real mode never reads back, so a star clicked
+ * on a real install was written into a dead row and lost on the next render.
+ * This store is the single source for both modes.
+ *
+ * Keys are composite (`provider:id`) — see `modelKey` — and stale ones are
+ * dropped on read, so a model removed from models.yml cannot hold a slot in the
+ * five-entry recent rail forever.
+ */
+
+import { getDb } from '@/server/db.server';
+import { readSettingsJson, writeSettingsJson } from '@/server/lib/db/settings-store';
+import { isMockMode } from '@/server/mock.server';
+import { INITIAL_MODELS_CATALOG } from '@/client/data/models/catalog';
+import {
+  EMPTY_MODEL_PREFERENCES,
+  RECENT_MODELS_LIMIT,
+  filterKnownKeys,
+  readModelPreferences,
+  recordRecentKey,
+  toggleFavoriteKey,
+} from '@/shared/lib/models/preferences';
+import { modelKey } from '@/shared/lib/models/identity';
+import type { ModelPreferences } from '@/shared/types';
+
+const MODEL_PREFERENCES_KEY = 'omp_model_preferences';
+
+/**
+ * Demo favorites/recents so a `MOCK=true` chamber still opens with the rails
+ * the shipped catalog advertises. Seeded on first read only — from then on the
+ * row is the user's, and the catalog's own flags are ignored.
+ */
+function mockSeedPreferences(): ModelPreferences {
+  return {
+    favorites: INITIAL_MODELS_CATALOG.filter((model) => model.isFavorite).map(modelKey),
+    recentKeys: INITIAL_MODELS_CATALOG.filter((model) => model.isRecent).map(modelKey).slice(0, RECENT_MODELS_LIMIT),
+  };
+}
+
+async function readStoredPreferences(): Promise<ModelPreferences> {
+  const db = await getDb();
+  const raw = await readSettingsJson<unknown>(db, MODEL_PREFERENCES_KEY, null);
+  if (raw === null) return isMockMode() ? mockSeedPreferences() : EMPTY_MODEL_PREFERENCES;
+  return readModelPreferences(raw);
+}
+
+/**
+ * Preferences narrowed to the models the registry actually serves right now —
+ * the shape every loader response carries.
+ */
+export async function readModelPreferencesFor(
+  models: readonly { provider: string; id: string }[],
+): Promise<ModelPreferences> {
+  try {
+    const known = new Set(models.map(modelKey));
+    const stored = await readStoredPreferences();
+    return {
+      favorites: filterKnownKeys(stored.favorites, known),
+      recentKeys: filterKnownKeys(stored.recentKeys, known),
+    };
+  } catch {
+    return EMPTY_MODEL_PREFERENCES;
+  }
+}
+
+/**
+ * Persist a mutation with the stale keys already removed, so a key the registry
+ * dropped cannot sit in the row holding one of the five recent slots. Reading
+ * prunes for display only — without this the slot stayed occupied across
+ * reloads and the RECENT rail silently showed four models instead of five.
+ */
+async function writePreferences(known: ReadonlySet<string>, mutate: (current: ModelPreferences) => ModelPreferences): Promise<ModelPreferences> {
+  const current = await readStoredPreferences();
+  const next = mutate({
+    favorites: filterKnownKeys(current.favorites, known),
+    recentKeys: filterKnownKeys(current.recentKeys, known),
+  });
+  const db = await getDb();
+  await writeSettingsJson(db, MODEL_PREFERENCES_KEY, next);
+  return next;
+}
+
+/** Flip one model's favorite flag, returning the full persisted pair. */
+export async function toggleFavoritePreference(key: string, known: ReadonlySet<string>): Promise<ModelPreferences> {
+  return writePreferences(known, (current) => ({
+    ...current,
+    favorites: toggleFavoriteKey(current.favorites, key),
+  }));
+}
+
+/**
+ * Record a model as last used. Called from the selection action rather than
+ * from a separate endpoint: "the user picked this model" is one event, and a
+ * second request would only add a way for the two to disagree.
+ */
+export async function recordRecentPreference(key: string, known: ReadonlySet<string>): Promise<ModelPreferences> {
+  return writePreferences(known, (current) => ({
+    ...current,
+    recentKeys: recordRecentKey(current.recentKeys, key),
+  }));
+}