ompchamber 1.0.0 → 1.2.0

package/src/shared/lib/chat/text-file.ts

@@ -0,0 +1,148 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Deciding whether a file's contents are text, and what language to fence them
+ * under, from the file itself rather than from its metadata.
+ *
+ * Split out of `attachments.ts` because it is the one part of classification
+ * that reads BYTES: everything else there works from `name`/`type`/`size`,
+ * which is what a replayed attachment has.
+ */
+
+/**
+ * Extensions treated as inline-able text when the browser reports no useful
+ * MIME type. `File.type` is empty for many code files, so the extension is the
+ * only signal — a dropped `script.py` used to attach without its contents ever
+ * reaching the prompt.
+ */
+export const TEXT_FILE_EXTENSIONS: Record<string, true> = {
+  txt: true,
+  text: true,
+  md: true,
+  markdown: true,
+  mdx: true,
+  json: true,
+  jsonc: true,
+  yaml: true,
+  yml: true,
+  toml: true,
+  ini: true,
+  env: true,
+  csv: true,
+  tsv: true,
+  log: true,
+  xml: true,
+  html: true,
+  htm: true,
+  css: true,
+  scss: true,
+  less: true,
+  js: true,
+  mjs: true,
+  cjs: true,
+  jsx: true,
+  ts: true,
+  mts: true,
+  cts: true,
+  tsx: true,
+  py: true,
+  rb: true,
+  go: true,
+  rs: true,
+  java: true,
+  kt: true,
+  kts: true,
+  swift: true,
+  c: true,
+  h: true,
+  cc: true,
+  cpp: true,
+  cxx: true,
+  hpp: true,
+  hh: true,
+  cs: true,
+  php: true,
+  pl: true,
+  lua: true,
+  r: true,
+  sql: true,
+  sh: true,
+  bash: true,
+  zsh: true,
+  fish: true,
+  ps1: true,
+  bat: true,
+  cmd: true,
+  dockerfile: true,
+  makefile: true,
+  gitignore: true,
+  editorconfig: true,
+  diff: true,
+  patch: true,
+};
+
+/** MIME types the browser reports for text-ish files it does know. */
+export function isTextMimeType(type: string): boolean {
+  if (!type) return false;
+  if (type === 'text/plain' || type === 'text/markdown') return true;
+  return type.startsWith('text/')
+    || type === 'application/json'
+    || type === 'application/xml'
+    || type === 'application/x-yaml'
+    || type === 'application/yaml'
+    || type === 'application/javascript'
+    || type === 'application/x-sh'
+    || type === 'application/sql'
+    || type.endsWith('+json')
+    || type.endsWith('+xml');
+}
+
+/** Bytes sampled to decide whether an unclassified file is text. */
+const SNIFF_BYTES = 4096;
+
+/**
+ * Whether an unclassified file's own bytes read as text.
+ *
+ * Some hosts hand over a file whose name and MIME say nothing useful: a
+ * promised-file drag from another app arrives as `document` with an empty type,
+ * and an opaque download as `application/octet-stream`. Deciding from the name
+ * alone left those attached but never inlined — the chip rendered, the model saw
+ * nothing.
+ *
+ * Three signals, because control-character density alone misses a short binary:
+ * a NUL byte (no text encoding this app handles contains one), an invalid UTF-8
+ * sequence (a lone continuation or lead byte), and the control-character ratio
+ * a browser applies to a Blob. `TextDecoder` in fatal mode is the cheapest
+ * correct UTF-8 validator available.
+ */
+export async function looksLikeTextFile(
+  file: Pick<File, 'slice'>,
+  /**
+   * Bytes already read while the drop's permission was live. A dropped file
+   * cannot be `slice()`d after that window closes, so the sniff is served from
+   * the primed read where one exists. See `file-reads.ts`.
+   */
+  primed?: Uint8Array,
+): Promise<boolean> {
+  try {
+    const bytes = primed ?? new Uint8Array(await file.slice(0, SNIFF_BYTES).arrayBuffer());
+    if (bytes.length === 0) return false;
+    if (bytes.includes(0)) return false;
+    try {
+      new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    } catch {
+      return false;
+    }
+    let control = 0;
+    for (const byte of bytes) {
+      if (byte < 9 || (byte > 13 && byte < 32)) control += 1;
+    }
+    return control / bytes.length <= 0.3;
+  } catch {
+    return false;
+  }
+}
+

package/src/shared/lib/chat/timeline/omp-callbacks.ts

@@ -16,36 +16,14 @@ import type { Dispatch, SetStateAction } from 'preact/compat';
 import type { ChatMessageData, ExtensionUiDialogRequest, IncomingExtensionUiRequest, OmpAgentCallbacks } from '@/shared/types';
 import { triggerChatCompletionSound } from '@/client/hooks/ui/notification-sound';
 import { isNoticeRow } from '@/shared/lib/chat/notice-row';
-import { createRafBatch } from '@/shared/lib/chat/timeline/stream-raf';
+import {
+  bindStreamingCoalescer,
+  disposeStreamingCoalescer,
+  flushStreamingUpdates,
+  queueStreamingUpdate,
+} from '@/shared/lib/chat/timeline/stream-coalescer';
 import { PHASE_VERBS } from '@/shared/lib/chat/timeline/tool-phrases';
 
-// omp emits one message_update per model chunk, each carrying that message's
-// FULL accumulated content, so a burst only needs the newest payload per
-// message id. This batch commits at most once per animation frame; the terminal
-// frame flushes synchronously first so the last chunk is never dropped.
-// `apply`/`afterFlush` delegate through module vars because the callbacks
-// factory re-runs on every render.
-let applyMessageUpdater: Dispatch<SetStateAction<ChatMessageData[]>> = () => {};
-let scrollAfterFlush: () => void = () => {};
-
-const messageBatch = createRafBatch<ChatMessageData[]>(
-  updater => applyMessageUpdater(updater),
-  () => scrollAfterFlush(),
-);
-
-/** Apply any coalesced update, then invalidate its scheduled frame. */
-export function disposeStreamingCoalescer(): void {
-  messageBatch.flush();
-  messageBatch.cancel();
-}
-
-/** Drop coalesced updates without applying them — a session switch discards
- *  the previous session's queued `message_update` frames so they cannot leak
- *  into the freshly cleared timeline of the next session. */
-export function cancelStreamingCoalescer(): void {
-  messageBatch.cancel();
-}
-
 export interface OmpAgentCallbacksDeps {
   setGenerating: (v: boolean) => void;
   setGeneratingVerb: (v: string) => void;
@@ -91,8 +69,7 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
     withdrawExtensionDialog,
   } = deps;
 
-  applyMessageUpdater = setLocalMessages;
-  scrollAfterFlush = () => scrollToBottom('smooth');
+  bindStreamingCoalescer(setLocalMessages, () => scrollToBottom('smooth'));
 
   return {
     onAgentStart: () => {
@@ -152,7 +129,7 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
       if (msg.role !== 'user' && !isNoticeRow(msg)) optimisticUserIdRef.current = null;
       // Queue for the next frame, collapsing same-message bursts to the newest
       // full-content frame; scroll runs once per rendered frame.
-      messageBatch.queue(prev => {
+      queueStreamingUpdate(prev => {
         const placeholderId = aiPlaceholderIdRef.current;
         // Notice rows (e.g. background job done, system alerts) are appended in
         // arrival order — the timeline renders state as-is, so omp's own write
@@ -237,7 +214,7 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
       }
       // Apply any coalesced update before the terminal frame so the last chunk
       // is never dropped and the end always runs after it.
-      messageBatch.flush();
+      flushStreamingUpdates();
       if (msg.role !== 'user') optimisticUserIdRef.current = null;
       setLocalMessages(prev => {
         const placeholderId = aiPlaceholderIdRef.current;
@@ -345,6 +322,15 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
         return [...prev, row];
       });
     },
+    // omp renamed the session — the auto-title generation the chamber asks for
+    // after a settled run, a `/rename`, or an RPC set_session_name. The slot
+    // write is in place, so the title is already on disk: refresh the metadata
+    // the navbar/context panel read, and signal the sidebar (whose scan cache
+    // is keyed on file mtime, which a fixed-width in-place write cannot move).
+    onSessionTitleChanged: () => {
+      const sid = adoptedSessionIdRef.current ?? sessionIdRef.current;
+      if (sid) refreshSessionMeta(sid);
+    },
     onNotice: (_level, message) => {
       console.info('OMP notice:', message);
     },

package/src/shared/lib/chat/timeline/stream-coalescer.ts

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Frame coalescer for the live agent stream.
+ *
+ * omp emits one `message_update` per model chunk, each carrying that message's
+ * FULL accumulated content, so a burst only needs the newest payload per
+ * message id. This batches at most one commit per animation frame; the terminal
+ * frame flushes synchronously first so the last chunk is never dropped.
+ *
+ * The sink is a module-level singleton bound once per callbacks factory run
+ * (`bindStreamingCoalescer`), because that factory re-runs on every render
+ * while the batch's scheduled frame must survive across renders. Split out of
+ * omp-callbacks.ts so that file stays under the repo's per-file size ceiling.
+ */
+
+import type { Dispatch, SetStateAction } from 'preact/compat';
+import type { ChatMessageData } from '@/shared/types';
+import { createRafBatch } from '@/shared/lib/chat/timeline/stream-raf';
+
+let applyMessageUpdater: Dispatch<SetStateAction<ChatMessageData[]>> = () => {};
+let scrollAfterFlush: () => void = () => {};
+
+const messageBatch = createRafBatch<ChatMessageData[]>(
+  updater => applyMessageUpdater(updater),
+  () => scrollAfterFlush(),
+);
+
+/** Point the batch at the current render's state setter and scroll hook. */
+export function bindStreamingCoalescer(
+  apply: Dispatch<SetStateAction<ChatMessageData[]>>,
+  afterFlush: () => void,
+): void {
+  applyMessageUpdater = apply;
+  scrollAfterFlush = afterFlush;
+}
+
+/** Queue a coalesced update for the next animation frame, keyed per message. */
+export function queueStreamingUpdate(
+  updater: (prev: ChatMessageData[]) => ChatMessageData[],
+  key: string,
+): void {
+  messageBatch.queue(updater, key);
+}
+
+/** Apply any queued update synchronously (terminal frames call this first so
+ *  the last chunk is never dropped). */
+export function flushStreamingUpdates(): void {
+  messageBatch.flush();
+}
+
+/** Apply any coalesced update, then invalidate its scheduled frame. */
+export function disposeStreamingCoalescer(): void {
+  messageBatch.flush();
+  messageBatch.cancel();
+}
+
+/** Drop coalesced updates without applying them — a session switch discards
+ *  the previous session's queued `message_update` frames so they cannot leak
+ *  into the freshly cleared timeline of the next session. */
+export function cancelStreamingCoalescer(): void {
+  messageBatch.cancel();
+}

package/src/shared/lib/chat/timeline/turns.ts

@@ -8,8 +8,15 @@
  * rewind endpoint: identifying raw composer input and deciding whether a
  * JSONL-derived user turn and a stored DB-copy turn are the same request
  * (omp rewrites delivered prompts, so equality is not enough).
+ *
+ * The jump rail also reads from here: it lists user turns of the FULL session
+ * (`/api/chat/:id/turns`) and from the mounted window, and both build the same
+ * tooltip preview, so the truncation length is shared rather than duplicated.
  */
 
+/** Longest prompt excerpt a rail tooltip renders. */
+export const TURN_PREVIEW_CHARS = 220;
+
 /** Whether a stored content string is raw composer input (slash command or
  *  @mention) rather than the prompt omp actually delivered. */
 export function isRawComposerInput(content: string): boolean {

package/src/shared/lib/fs/file-kind.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * File-kind classification shared by the server read routes and every client
+ * viewer (desktop editor, mobile editor, chat tool panels).
+ *
+ * A raster image is not text: decoding its bytes as UTF-8 yields replacement
+ * characters, so the editor used to paint a PNG as mojibake. The extension is
+ * the only signal available before reading the file, and it is the same signal
+ * the Files panel already uses to pick an icon — keeping it in one module means
+ * the reader, the icon, and the viewer can never disagree about which files are
+ * pictures.
+ *
+ * SVG is deliberately absent: it is editable XML text and stays on the
+ * syntax-highlighted code path.
+ */
+export const IMAGE_MIME_BY_EXT: Record<string, string> = {
+  png: 'image/png',
+  apng: 'image/apng',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  jfif: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  avif: 'image/avif',
+  bmp: 'image/bmp',
+  ico: 'image/x-icon',
+  tif: 'image/tiff',
+  tiff: 'image/tiff',
+};
+
+/** Lower-cased extension of a path or name, query/fragment/line suffix removed. */
+export function getFileExtension(filePath: string | undefined | null): string {
+  if (!filePath) return '';
+  const clean = filePath.split('?')[0].split('#')[0].split(/[/\\]/).pop() ?? '';
+  const dot = clean.lastIndexOf('.');
+  return dot > 0 ? clean.slice(dot + 1).toLowerCase() : '';
+}
+
+/**
+ * MIME type for a raster image path, or null when the extension is not one.
+ * Null is the "treat as text" answer, so every caller branches on this single
+ * check instead of re-deriving the extension list.
+ */
+export function getImageMimeType(filePath: string | undefined | null): string | null {
+  return IMAGE_MIME_BY_EXT[getFileExtension(filePath)] ?? null;
+}

package/src/shared/lib/fs/paths.ts

@@ -1,5 +1,5 @@
 /**
- * Path formatting for the Files panel's copy actions.
+ * Path helpers shared by the Files panel and every surface that opens a file.
  *
  * `/api/fs/dir` emits every entry as a path relative to the listing's base
  * directory — the workspace root, or the selected nested repo — and reports
@@ -7,7 +7,25 @@
  * two halves; a relative path on its own is not resolvable outside the panel
  * (the client-side `rootPath` may be `~`-relative, rejected by the server, or
  * absent entirely in mock mode).
+ *
+ * `buildFsRawUrl` is the byte-stream counterpart of that same scoping: it is
+ * what an image tab points its `<img>` at, so the file it names is the file
+ * the tab names, nested repo included.
+ */
+
+/**
+ * URL of one file's raw bytes through `/api/fs/raw`, carrying the same scope
+ * (`root`, nested `repo`) as `/api/fs/read` so an image opened from a nested
+ * repo resolves to the file the tab names. `repo: '.'` is omitted: the server
+ * treats an absent repo as the scoped root.
  */
+export function buildFsRawUrl(file: { path: string; root?: string; repo?: string }): string {
+  const params = new URLSearchParams({ path: file.path });
+  if (file.root) params.set('root', file.root);
+  if (file.repo && file.repo !== '.') params.set('repo', file.repo);
+  return `/api/fs/raw?${params.toString()}`;
+}
+
 export function toAbsolutePath(baseDir: string | null | undefined, relPath: string): string {
   // `/`- and `./`-prefixed raws are stripped; a dot-file name (`.env`) is not a prefix.
   const rel = relPath.replace(/^(?:\.?[/\\])+/, '').replace(/[/\\]+$/, '');

package/src/shared/lib/markdown/math.test.ts

@@ -20,16 +20,19 @@
  * they are no-ops everywhere else.
  */
 
-import { beforeAll, describe, expect, test } from 'bun:test';
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
 import { Window } from 'happy-dom';
 
 let hydrateMathBlocks: typeof import('@/shared/lib/markdown/katex').hydrateMathBlocks;
 let renderMarkdown: typeof import('@/shared/lib/markdown/marked').renderMarkdown;
 let sanitizeHtml: typeof import('@/shared/lib/markdown/sanitize').sanitizeHtml;
 
+const displaced: Record<string, unknown> = {};
+const installed: Record<string, unknown> = {};
+
 beforeAll(async () => {
   const win = new Window({ url: 'http://localhost' });
-  Object.assign(globalThis, {
+  for (const [key, value] of Object.entries({
     window: win,
     document: win.document,
     MutationObserver: win.MutationObserver,
@@ -37,7 +40,11 @@ beforeAll(async () => {
     Element: win.Element,
     HTMLElement: win.HTMLElement,
     NodeFilter: win.NodeFilter,
-  });
+  })) {
+    displaced[key] = (globalThis as Record<string, unknown>)[key];
+    installed[key] = value;
+    (globalThis as Record<string, unknown>)[key] = value;
+  }
   // Dynamic import is required here, not stylistic: `sanitize.ts` binds
   // DOMPurify at module scope, which captures the DOM globals present at
   // evaluation time. A static import would run before the happy-dom globals
@@ -47,6 +54,16 @@ beforeAll(async () => {
   ({ sanitizeHtml } = await import('@/shared/lib/markdown/sanitize'));
 });
 
+// Every test file shares one process, so the globals go back the way they were:
+// the fold in `agent-events.ts` branches on `typeof window`, and a leaked DOM
+// window would take its browser path with a `CustomEvent` from another realm.
+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];
+  }
+});
+
 /** Render markdown and mount it exactly as `MarkdownRenderer` does. */
 function mount(content: string): HTMLElement {
   const host = document.createElement('div');

package/src/shared/lib/models/preferences.test.ts

@@ -0,0 +1,131 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The preference rules are shared verbatim by the server (which persists the
+ * arrays) and the picker (which applies them optimistically), so these lock the
+ * behaviour both sides read back: composite keys, most-recent-first order, and
+ * the five-entry cap.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  EMPTY_MODEL_PREFERENCES,
+  RECENT_MODELS_LIMIT,
+  applyModelPreferences,
+  filterKnownKeys,
+  readModelPreferences,
+  recordRecentKey,
+  toggleFavoriteKey,
+} from '@/shared/lib/models/preferences';
+import type { AIModelOption } from '@/shared/types';
+
+describe('toggleFavoriteKey', () => {
+  test('adds an unknown key at the end and removes a known one', () => {
+    expect(toggleFavoriteKey(['a:1'], 'b:2')).toEqual(['a:1', 'b:2']);
+    expect(toggleFavoriteKey(['a:1', 'b:2'], 'a:1')).toEqual(['b:2']);
+  });
+
+  test('keys on provider + id, so the same id under another provider is a separate favorite', () => {
+    // The registry serves `deepseek-v4-pro` from both `deepseek` and `kenari`.
+    // An id-only list would unstar both rows when either is clicked.
+    const favorites = toggleFavoriteKey([], 'deepseek:deepseek-v4-pro');
+    expect(toggleFavoriteKey(favorites, 'kenari:deepseek-v4-pro')).toEqual([
+      'deepseek:deepseek-v4-pro',
+      'kenari:deepseek-v4-pro',
+    ]);
+  });
+});
+
+describe('recordRecentKey', () => {
+  test('moves a re-picked model to the front instead of duplicating it', () => {
+    expect(recordRecentKey(['a:1', 'b:2', 'c:3'], 'b:2')).toEqual(['b:2', 'a:1', 'c:3']);
+  });
+
+  test('caps the list at five, evicting the oldest entry', () => {
+    const full = ['a:1', 'b:2', 'c:3', 'd:4', 'e:5'];
+    const next = recordRecentKey(full, 'f:6');
+
+    expect(next).toHaveLength(RECENT_MODELS_LIMIT);
+    expect(next[0]).toBe('f:6');
+    expect(next).not.toContain('e:5');
+  });
+
+  test('re-picking inside a full list keeps the other four', () => {
+    const full = ['a:1', 'b:2', 'c:3', 'd:4', 'e:5'];
+    expect(recordRecentKey(full, 'c:3')).toEqual(['c:3', 'a:1', 'b:2', 'd:4', 'e:5']);
+  });
+});
+
+describe('readModelPreferences', () => {
+  test('reads a well-formed pair', () => {
+    expect(readModelPreferences({ favorites: ['a:1'], recentKeys: ['b:2'] }))
+      .toEqual({ favorites: ['a:1'], recentKeys: ['b:2'] });
+  });
+
+  test('drops non-string entries and caps an over-long recent list', () => {
+    const raw = {
+      favorites: ['a:1', 7, null, ''],
+      recentKeys: ['a:1', 'b:2', 'c:3', 'd:4', 'e:5', 'f:6', 'g:7'],
+    };
+
+    expect(readModelPreferences(raw)).toEqual({
+      favorites: ['a:1'],
+      recentKeys: ['a:1', 'b:2', 'c:3', 'd:4', 'e:5'],
+    });
+  });
+
+  test('an absent or malformed row yields empty rails', () => {
+    expect(readModelPreferences(null)).toEqual(EMPTY_MODEL_PREFERENCES);
+    expect(readModelPreferences('nonsense')).toEqual(EMPTY_MODEL_PREFERENCES);
+    expect(readModelPreferences({ favorites: 'not-a-list' })).toEqual(EMPTY_MODEL_PREFERENCES);
+  });
+});
+
+describe('filterKnownKeys', () => {
+  test('drops keys the registry no longer serves', () => {
+    // A model removed from models.yml, or every model of a disconnected
+    // provider, must not hold a slot in the five-entry rail.
+    const known = new Set(['a:1', 'c:3']);
+    expect(filterKnownKeys(['a:1', 'gone:9', 'c:3'], known)).toEqual(['a:1', 'c:3']);
+  });
+
+  test('pruning before a write frees the slot instead of merely hiding it', () => {
+    // The rail reads at most five entries. A stale key left in the stored array
+    // occupies one of them across every reload, so the user sees four models
+    // and the fifth pick appears to do nothing.
+    const stored = ['gone:9', 'a:1', 'b:2', 'c:3', 'd:4'];
+    const pruned = recordRecentKey(filterKnownKeys(stored, new Set(['a:1', 'b:2', 'c:3', 'd:4', 'e:5'])), 'e:5');
+
+    expect(pruned).toEqual(['e:5', 'a:1', 'b:2', 'c:3', 'd:4']);
+    expect(pruned).toHaveLength(RECENT_MODELS_LIMIT);
+  });
+});
+
+describe('applyModelPreferences', () => {
+  const rows: AIModelOption[] = [
+    { id: '1', name: 'One', provider: 'a' },
+    { id: '2', name: 'Two', provider: 'a', isFavorite: true },
+    { id: '3', name: 'Three', provider: 'b' },
+  ];
+
+  test('lights only the rows named by the stored key list', () => {
+    const applied = applyModelPreferences(rows, { favorites: ['b:3'], recentKeys: [] });
+
+    // Truthiness is the contract the star reads: a registry row has no
+    // `isFavorite` field at all, so `false` and `undefined` both mean "unlit".
+    expect(applied.map((m) => Boolean(m.isFavorite))).toEqual([false, false, true]);
+  });
+
+  test('leaves already-correct rows identical so only the changed row re-renders', () => {
+    const applied = applyModelPreferences(rows, { favorites: [], recentKeys: [] });
+
+    expect(applied[0]).toBe(rows[0]);
+    expect(applied[2]).toBe(rows[2]);
+    expect(applied[1]).not.toBe(rows[1]);
+    expect(applied[1].isFavorite).toBe(false);
+  });
+});

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

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Favorite + recent model preferences, keyed by the composite `provider:id`
+ * identity (`modelKey`). A model id alone is not unique — the omp registry
+ * serves the same id from several providers — so an id-keyed favorite list
+ * lights up every provider's row and records the wrong "recent".
+ *
+ * Pure list operations only: the server persists the arrays (one
+ * `app_settings` row) and the picker applies them optimistically, so both
+ * sides MUST agree on the ordering and the cap. Keeping the rules here is what
+ * makes them agree — a second copy in the route or the hook would drift.
+ */
+
+import type { AIModelOption, ModelPreferences } from '@/shared/types';
+import { modelKey } from '@/shared/lib/models/identity';
+
+/** How many last-used models the RECENT rail holds. */
+export const RECENT_MODELS_LIMIT = 5;
+
+/** Used before the first write, and when a payload carries no preferences. */
+export const EMPTY_MODEL_PREFERENCES: ModelPreferences = { favorites: [], recentKeys: [] };
+
+/** Add or remove one key; the relative order of the survivors is untouched. */
+export function toggleFavoriteKey(favorites: readonly string[], key: string): string[] {
+  return favorites.includes(key)
+    ? favorites.filter((entry) => entry !== key)
+    : [...favorites, key];
+}
+
+/**
+ * Move a key to the front of the recents, de-duplicated and capped. Re-picking
+ * a model must not leave a second copy behind — the rail would then show the
+ * same model twice and the cap would evict a genuinely older entry.
+ */
+export function recordRecentKey(
+  recentKeys: readonly string[],
+  key: string,
+  limit: number = RECENT_MODELS_LIMIT,
+): string[] {
+  return [key, ...recentKeys.filter((entry) => entry !== key)].slice(0, Math.max(1, limit));
+}
+
+/**
+ * Drop keys the live registry no longer offers — a model removed from
+ * models.yml, or every model of a provider the user disconnected. Without this
+ * a stale key holds one of the five recent slots forever, so a rail that looks
+ * empty is hiding real entries behind keys nothing can render.
+ */
+export function filterKnownKeys(keys: readonly string[], known: ReadonlySet<string>): string[] {
+  return keys.filter((key) => known.has(key));
+}
+
+/** Parse a persisted preferences row without trusting the JSON shape. */
+export function readModelPreferences(value: unknown): ModelPreferences {
+  const source = typeof value === 'object' && value !== null ? value as Record<string, unknown> : {};
+  const strings = (input: unknown): string[] =>
+    Array.isArray(input) ? input.filter((entry): entry is string => typeof entry === 'string' && entry.length > 0) : [];
+  return {
+    favorites: strings(source.favorites),
+    recentKeys: strings(source.recentKeys).slice(0, RECENT_MODELS_LIMIT),
+  };
+}
+
+/**
+ * Stamp the favorite flag onto a catalog list. The registry carries no
+ * favorites of its own — it is a read-only view of omp's config — so the picker
+ * learns which rows are starred from the preference store, never from the
+ * catalog's own `isFavorite` (that is MOCK seed data).
+ *
+ * The comparison is by truthiness, not identity: a registry row has no
+ * `isFavorite` field at all, so an `undefined !== false` test would rebuild
+ * every row on every load and re-render the whole panel. Rows whose star state
+ * already reads correctly are returned untouched.
+ */
+export function applyModelPreferences(
+  models: AIModelOption[],
+  preferences: ModelPreferences,
+): AIModelOption[] {
+  const favorites = new Set(preferences.favorites);
+  return models.map((model) => {
+    const isFavorite = favorites.has(modelKey(model));
+    return Boolean(model.isFavorite) === isFavorite ? model : { ...model, isFavorite };
+  });
+}