@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/shared/lib/markdown/sanitize.ts

@@ -0,0 +1,191 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * DOMPurify sanitizer for rendered markdown HTML.
+ *
+ * The assistant is allowed to produce HTML but we never execute it: raw HTML
+ * tags are stripped by default (DOMPurify default profile) while KaTeX's
+ * MathML nodes are preserved via ADD_TAGS/ADD_ATTR. Sanitization is
+ * client-only — in a non-DOM (SSR) environment we return the input unchanged
+ * and let the browser dev server apply it on the client.
+ */
+
+import DOMPurify, { type Config } from 'dompurify';
+import { DIRECTIVE_ATTRS_ATTR, DIRECTIVE_BLOCK_CLASS, DIRECTIVE_NAME_ATTR } from '@/shared/lib/markdown/directives';
+
+const KATEX_MATHML_TAGS = [
+  'math',
+  'annotation',
+  'annotation-xml',
+  'semantics',
+  'mrow',
+  'mi',
+  'mn',
+  'mo',
+  'mspace',
+  'ms',
+  'mtext',
+  'mroot',
+  'mfrac',
+  'msqrt',
+  'mstyle',
+  'merror',
+  'mpadded',
+  'mphantom',
+  'mtable',
+  'mtr',
+  'mtd',
+  'mlabeledtr',
+  'munder',
+  'mover',
+  'munderover',
+  'msup',
+  'msub',
+  'msubsup',
+  'mtext',
+  'mtd',
+  'menclose',
+];
+
+/** Whether KaTeX output is present — extends the allowlist for MathML. */
+function hasKatex(html: string): boolean {
+  return /class="[^"]*katex/.test(html);
+}
+
+/** Inline SVG icons emitted by the marked code-block copy button. */
+const COPY_ICON_TAGS = ['svg', 'path', 'polyline', 'rect', 'circle', 'line'];
+const COPY_ICON_ATTRS = [
+  'viewBox', 'd', 'points', 'x', 'y', 'x1', 'y1', 'x2', 'y2',
+  'width', 'height', 'rx', 'ry', 'cx', 'cy', 'r',
+  'fill', 'stroke', 'stroke-width', 'stroke-linecap', 'stroke-linejoin',
+  'xmlns', 'aria-hidden', 'aria-label',
+];
+
+/** Mermaid diagram SVG shapes, text, edges, and metadata attributes. */
+const MERMAID_TAGS = [
+  'svg', 'g', 'line', 'path', 'rect', 'circle', 'ellipse', 'polygon', 'polyline',
+  'text', 'tspan', 'title', 'desc', 'marker', 'defs', 'style', 'use', 'symbol',
+  'foreignObject', 'html', 'head', 'body', 'div', 'span', 'p', 'br', 'img',
+];
+const MERMAID_ATTRS = [
+  'id', 'class', 'style', 'transform', 'viewBox', 'width', 'height', 'xmlns',
+  'x', 'y', 'x1', 'y1', 'x2', 'y2', 'cx', 'cy', 'r', 'rx', 'ry', 'd', 'points',
+  'fill', 'stroke', 'stroke-width', 'stroke-dasharray', 'stroke-dashoffset',
+  'stroke-linecap', 'stroke-linejoin', 'stroke-opacity', 'fill-opacity', 'opacity',
+  'font-family', 'font-size', 'font-weight', 'font-style', 'text-anchor',
+  'dominant-baseline', 'alignment-baseline', 'text-decoration', 'direction',
+  'marker-end', 'marker-start', 'marker-mid', 'markerWidth', 'markerHeight',
+  'refX', 'refY', 'orient', 'markerUnits', 'preserveAspectRatio', 'version',
+  'dx', 'dy', 'dy1', 'dy2', 'rowspan', 'colspan', 'start', 'aria-roledescription',
+  'aria-describedby', 'role', 'aria-hidden', 'aria-label', 'data-mermaid-theme',
+  'overflow', 'visibility', 'rel', 'src', 'alt',
+];
+const MERMAID_URI_ATTRS = ['href', 'xlink:href'];
+
+function buildMermaidConfig(hasUri: boolean): Config {
+  return {
+    USE_PROFILES: { html: true, svg: true, svgFilters: true },
+    ADD_TAGS: MERMAID_TAGS,
+    ADD_ATTR: [...MERMAID_ATTRS, ...(hasUri ? MERMAID_URI_ATTRS : [])],
+    HTML_INTEGRATION_POINTS: { 'annotation-xml': true, foreignobject: true },
+  };
+}
+
+/**
+ * Sanitize a rendered markdown HTML string. Strips scripts/event handlers and
+ * unknown tags (default profile) so assistant HTML is escaped, not executed.
+ * KaTeX MathML + the code-copy icon SVG are preserved when present.
+ */
+export function sanitizeHtml(html: string): string {
+  if (!html) return html;
+  if (typeof window === 'undefined' || !window.document) return html;
+
+  const hasSvgIcon = /<svg[^>]*>/.test(html);
+  const hasMathPlaceholder = html.includes('math-pending');
+  // A plugin directive's placeholder rides on the same allowlist shape as the
+  // math placeholders: DOMPurify strips an unknown `data-*` attribute unless it
+  // is listed, and a stripped name means the client cannot tell which plugin
+  // claims the fence — the block would stay a code block forever.
+  const hasDirective = html.includes(DIRECTIVE_BLOCK_CLASS);
+  const config = hasKatex(html) || hasSvgIcon || hasMathPlaceholder || hasDirective
+    ? {
+        USE_PROFILES: { html: true, mathMl: true } as const,
+        ADD_TAGS: [...KATEX_MATHML_TAGS, ...(hasSvgIcon ? COPY_ICON_TAGS : [])],
+        ADD_ATTR: [
+          'aria-hidden',
+          'aria-label',
+          'encoding',
+          'nonce',
+          // Math placeholders carry the TeX source and display flag for the
+          // lazy KaTeX pass; DOMPurify strips unknown data-* attributes unless
+          // they are listed here.
+          'data-math',
+          'data-math-display',
+          ...(hasDirective ? [DIRECTIVE_NAME_ATTR, DIRECTIVE_ATTRS_ATTR, 'data-hydrated'] : []),
+          ...(hasSvgIcon ? COPY_ICON_ATTRS : []),
+        ],
+      }
+    : { USE_PROFILES: { html: true } as const };
+
+  try {
+    return DOMPurify.sanitize(html, config);
+  } catch {
+    return html;
+  }
+}
+
+/**
+ * Sanitize a mermaid-rendered SVG string. Mermaid with `securityLevel:
+ * 'strict'` already strips scripts and event handlers, but defense in depth:
+ * DOMPurify with an SVG allowlist tuned for mermaid output keeps diagram
+ * shapes/text/edges while dropping anything outside it. Returns the input
+ * unchanged in non-DOM (SSR) environments.
+ */
+export function sanitizeMermaidSvg(svg: string): string {
+  if (!svg) return svg;
+  if (typeof window === 'undefined' || !window.document) return svg;
+
+  const hasUri = /href/.test(svg);
+  try {
+    return DOMPurify.sanitize(svg, buildMermaidConfig(hasUri));
+  } catch {
+    return svg;
+  }
+}
+
+/**
+ * Sanitize a KaTeX-rendered HTML fragment before it is injected via innerHTML.
+ *
+ * `sanitizeHtml` already allows the MathML profile when the *parsed markdown*
+ * contains KaTeX classes, but lazy math rendering injects after that pass, so
+ * the generated fragment is sanitized separately.
+ *
+ * `class` MUST be allowed: KaTeX's visual layout is entirely class-driven
+ * (`.katex`, `.katex-mathml`, `.katex-html`), and DOMPurify drops attributes it
+ * has not been told about. Without it the wrapper spans are stripped and only
+ * bare MathML survives, which renders unstyled.
+ */
+export function sanitizeKatexHtml(html: string): string {
+  if (!html) return html;
+  if (typeof window === 'undefined' || !window.document) return html;
+
+  // DOMPurify drops a bare root-level <span>, which would strip KaTeX's outer
+  // `.katex` wrapper — the element every layout rule in katex.css hangs off.
+  // Wrapping the fragment keeps the parser from discarding it; the wrapper is
+  // removed again afterwards so only the KaTeX markup is injected.
+  const wrapped = `<div data-katex-wrap>${html}</div>`;
+  try {
+    const clean = DOMPurify.sanitize(wrapped, {
+      USE_PROFILES: { html: true, mathMl: true },
+      ADD_ATTR: ['class', 'aria-hidden', 'encoding', 'style', 'data-katex-wrap'],
+    } as Config);
+    const host = document.createElement('div');
+    host.innerHTML = clean;
+    return host.querySelector('[data-katex-wrap]')?.innerHTML ?? clean;
+  } catch {
+    return html;
+  }
+}

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

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The scroll container around every rendered table.
+ *
+ * A table with long unbreakable cells (paths, hashes, URLs) is wider than the
+ * message box it sits in — an auto-layout table cannot be narrowed below its
+ * columns' min-content width, so `width: 100%` is a floor, not a ceiling — and
+ * the chat timeline's scroller is `overflow-x-hidden`, which clipped its right
+ * columns with no way to reach them. `renderMarkdown` therefore emits a
+ * `.md-table-scroll` wrapper (styled in `tailwind.css`) whose own `overflow-x`
+ * is what scrolls.
+ *
+ * Two things have to hold for that to work, and neither is visible from the CSS
+ * alone: the wrapper must be emitted for EVERY table, and it must survive
+ * `sanitizeHtml` — DOMPurify drops anything its profile does not know, and a
+ * stripped `<div>`/`class` would leave the table clipped exactly as before.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import type { renderMarkdown as RenderMarkdown } from '@/shared/lib/markdown/marked';
+import type { sanitizeHtml as SanitizeHtml } from '@/shared/lib/markdown/sanitize';
+
+let renderMarkdown: typeof RenderMarkdown;
+let sanitizeHtml: typeof SanitizeHtml;
+/** Read from the module rather than spelled here: the renderer and the CSS are
+ *  the only two places that class name may exist. */
+let tableScrollClass: string;
+
+const displaced: Record<string, unknown> = {};
+const installed: Record<string, unknown> = {};
+
+beforeAll(async () => {
+  const win = new Window({ url: 'http://localhost' });
+  for (const [key, value] of Object.entries({
+    window: win,
+    document: win.document,
+    Node: win.Node,
+    Element: win.Element,
+    HTMLElement: win.HTMLElement,
+  })) {
+    displaced[key] = (globalThis as Record<string, unknown>)[key];
+    installed[key] = value;
+    (globalThis as Record<string, unknown>)[key] = value;
+  }
+  // Dynamic because this is a load-ORDER boundary, not a module selection:
+  // `sanitize.ts` binds DOMPurify at module scope, so a static import would run
+  // before these DOM globals exist and bind the sanitizer to a window-less
+  // environment (where `sanitizeHtml` returns its input unsanitized).
+  ({ renderMarkdown, TABLE_SCROLL_CLASS: tableScrollClass } = await import('@/shared/lib/markdown/marked'));
+  ({ sanitizeHtml } = await import('@/shared/lib/markdown/sanitize'));
+});
+
+// The runner shares one process: a leaked happy-dom window would send every
+// later file down a browser code path.
+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];
+  }
+});
+
+const WIDE_TABLE = [
+  '| endpoint | payload |',
+  '| --- | --- |',
+  '| `/api/settings/usage?refresh=1` | `a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90` |',
+].join('\n');
+
+/**
+ * An answer-shaped message: leading prose, then the table. The prose is not
+ * decoration — the sanitizer's happy-dom path unwraps the FIRST root element of
+ * a fragment (verified there: `<div>x</div>` sanitizes to `x`, while Chromium
+ * keeps it), so a fixture that opened on the table would drop the very wrapper
+ * under test for a harness reason rather than a product one.
+ */
+const withProse = (markdown: string) => `Here is the report.\n\n${markdown}`;
+
+/** Render + sanitize, then parse the result into a real DOM. */
+function renderToDom(markdown: string, allowHtml = false): HTMLElement {
+  const host = document.createElement('div');
+  host.className = 'prose-content';
+  host.innerHTML = sanitizeHtml(renderMarkdown(markdown, { allowHtml }));
+  return host;
+}
+
+describe('markdown table scroll container', () => {
+  test('the parser wraps a table in the scroll container', () => {
+    const raw = renderMarkdown(WIDE_TABLE);
+    expect(raw.startsWith(`<div class="${tableScrollClass}"><table>`)).toBe(true);
+    // The table must be the wrapper's CHILD: the scroll rule is applied to the
+    // wrapper, so a sibling arrangement would leave `overflow-x` on nothing.
+    expect(raw.endsWith('</table>\n</div>')).toBe(true);
+  });
+
+  test('the wrapper survives sanitization with its class', () => {
+    const host = renderToDom(withProse(WIDE_TABLE));
+    const wrapper = host.querySelector<HTMLElement>(`.${tableScrollClass}`);
+
+    expect(wrapper).not.toBeNull();
+    // A stripped class is the failure this pins: the node alone is not enough,
+    // since the scroll rule is keyed on the class name.
+    expect(wrapper?.className).toBe(tableScrollClass);
+    expect(wrapper?.firstElementChild?.tagName).toBe('TABLE');
+  });
+
+  test('the table keeps marked\'s own markup inside the wrapper', () => {
+    const host = renderToDom(withProse(WIDE_TABLE));
+    const wrapper = host.querySelector<HTMLElement>(`.${tableScrollClass}`);
+    expect(wrapper?.querySelector('th')?.textContent).toBe('endpoint');
+    expect(wrapper?.querySelectorAll('td')).toHaveLength(2);
+    expect(wrapper?.querySelector('code.inline-code')?.textContent).toBe('/api/settings/usage?refresh=1');
+  });
+
+  test('every table gets its own wrapper', () => {
+    const host = renderToDom(withProse(`${WIDE_TABLE}\n\ntext between\n\n${WIDE_TABLE}`));
+    expect(host.querySelectorAll(`.${tableScrollClass}`)).toHaveLength(2);
+    expect(host.querySelectorAll('table')).toHaveLength(2);
+    expect(host.textContent).toContain('text between');
+  });
+
+  test('a document previews table is wrapped the same way', () => {
+    // The editor preview and the wiki reader render through the same pipeline
+    // with `allowHtml` on; the wrapper must not be an agent-output-only branch.
+    const host = renderToDom(withProse(WIDE_TABLE), true);
+    expect(host.querySelectorAll(`.${tableScrollClass}`)).toHaveLength(1);
+  });
+
+  test('prose without a table stays unwrapped', () => {
+    const host = renderToDom('plain **text** and `code`');
+    expect(host.querySelector(`.${tableScrollClass}`)).toBeNull();
+  });
+});

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

@@ -0,0 +1,255 @@
+/**
+ * Server-side access to the models.dev catalog (https://models.dev/api.json):
+ * a mapping of provider slug → model id → { name, attachment, reasoning,
+ * tool_call, limit.context/output, cost.input/output }. Used as the metadata
+ * fallback for provider models whose listing endpoint (/v1/models) only
+ * returns bare ids. Cached in-process for 1 hour with graceful degradation —
+ * catalog failures never fail the caller.
+ */
+
+const CATALOG_URL = 'https://models.dev/api.json';
+const CATALOG_TTL_MS = 60 * 60 * 1000;
+const CATALOG_TIMEOUT_MS = 8_000;
+
+export interface CatalogModelInfo {
+  name?: string;
+  attachment?: boolean;
+  reasoning?: boolean;
+  tool_call?: boolean;
+  /** Canonical model id that other provider listings reference. */
+  canonical_model_id?: string;
+  limit?: { context?: number; output?: number };
+  cost?: { input?: number; output?: number; cache_read?: number; cache_write?: number };
+}
+
+type ModelsDevCatalog = Record<string, { models?: Record<string, CatalogModelInfo> }>;
+
+export interface CatalogLoadOptions {
+  timeoutMs?: number;
+  /**
+   * When true, a failed fetch or malformed payload throws instead of
+   * degrading to cached/empty data — callers that surface an error envelope
+   * (pricing) opt in.
+   */
+  strict?: boolean;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __kabmoModelsDevCatalog: { data: ModelsDevCatalog; expiresAt: number } | undefined;
+}
+
+export async function loadModelsDevCatalog(options: CatalogLoadOptions = {}): Promise<ModelsDevCatalog> {
+  const { timeoutMs = CATALOG_TIMEOUT_MS, strict = false } = options;
+  const cached = globalThis.__kabmoModelsDevCatalog;
+  if (cached && cached.expiresAt > Date.now()) return cached.data;
+  try {
+    const response = await fetch(CATALOG_URL, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok) {
+      if (strict) throw new Error(`models.dev responded ${response.status}`);
+      return cached?.data ?? {};
+    }
+    const data = await response.json() as ModelsDevCatalog;
+    if (!data || typeof data !== 'object') {
+      if (strict) throw new Error('models.dev payload is not an object');
+      return cached?.data ?? {};
+    }
+    globalThis.__kabmoModelsDevCatalog = { data, expiresAt: Date.now() + CATALOG_TTL_MS };
+    return data;
+  } catch (error) {
+    if (strict) throw error;
+    return cached?.data ?? {};
+  }
+}
+
+/** Minimum prefix-match score to accept (100 = exact at segment level). */
+const PREFIX_SCORE_THRESHOLD = 70;
+
+/** Minimum number of leading hyphen-segments that must match exactly. */
+const MIN_SEGMENTS_MATCH = 2;
+
+/**
+ * Strip a `:variant` suffix from a model id, e.g.
+ * `deepseek-v4-flash-0731:netra` → `deepseek-v4-flash-0731`.
+ */
+function stripVariant(modelId: string): string {
+  const colon = modelId.indexOf(':');
+  return colon >= 0 ? modelId.slice(0, colon) : modelId;
+}
+
+/**
+ * Normalize version dots to dashes: `v3.1` → `v3-1`.
+ */
+function normalizeVersion(modelId: string): string {
+  return modelId.replace(/\b(\d+)\.(\d+)\b/g, '$1-$2');
+}
+
+/**
+ * Prefix-based similarity: compare hyphen-segments from the start,
+ * penalizing each mismatching segment by 20, then each extra segment
+ * on the longer side by 10. Returns 0–100.
+ */
+function calculatePrefixScore(modelA: string, modelB: string): number {
+  const partsA = modelA.split('-');
+  const partsB = modelB.split('-');
+  const minLen = Math.min(partsA.length, partsB.length);
+  const maxLen = Math.max(partsA.length, partsB.length);
+  for (let i = 0; i < minLen; i++) {
+    if (partsA[i] !== partsB[i]) {
+      const mismatchPenalty = Math.max(0, 100 - i * 20);
+      return Math.max(0, mismatchPenalty);
+    }
+  }
+  // All compared segments match — penalise only extra length
+  return Math.max(0, 100 - (maxLen - minLen) * 10);
+}
+
+/**
+ * Convert a lowercase-kebab model name to PascalCase
+ * (e.g. "deepseek-v4-flash-0731" → "DeepSeek-V4-Flash-0731").
+ */
+function toPascalCase(name: string): string {
+  return name.split('-').map(seg => seg.charAt(0).toUpperCase() + seg.slice(1)).join('-');
+}
+
+/**
+ * Look up a model in the catalog using progressive matching levels:
+ *
+ * 1. **Exact** — model id as-is, with and without `:variant` suffix
+ * 2. **Provider + model name** — match `providerKey/modelName` after normalising
+ * 3. **Model name only** — match the bare model name (ignore provider)
+ * 4. **Prefix scoring** — hyphen-segment prefix match with minimum threshold
+ *
+ * When a catalog entry carries a `canonical_model_id` it is used as the
+ * authoritative canonical match — the first entry with a matching
+ * canonical id wins.
+ */
+export function findCatalogModel(
+  catalog: ModelsDevCatalog,
+  providerSlug: string | undefined,
+  modelId: string,
+): { info: CatalogModelInfo; providerKey: string } | null {
+  const cleanId = stripVariant(modelId);
+  const modelName = cleanId.includes('/') ? cleanId.split('/').pop()! : cleanId;
+  const normName = normalizeVersion(modelName);
+
+  // --- Level 1: Exact match ---
+  for (const id of [modelId, cleanId]) {
+    const candidates = new Set<string>();
+    if (providerSlug) candidates.add(providerSlug);
+    const slash = cleanId.indexOf('/');
+    if (slash >= 0) candidates.add(cleanId.slice(0, slash));
+
+    for (const providerKey of candidates) {
+      const info = catalog[providerKey]?.models?.[id];
+      if (info) return { info, providerKey };
+    }
+
+    // Fallback: check canonical_model_id across ALL providers
+    const canon = findByCanonicalId(catalog, id);
+    if (canon) return canon;
+  }
+
+  // --- Level 2: Provider + model name match ---
+  if (providerSlug || cleanId.includes('/')) {
+    const prov = providerSlug ?? cleanId.split('/')[0];
+    for (const candidateName of [modelName, normName]) {
+      const info = catalog[prov]?.models?.[candidateName];
+      if (info) return { info, providerKey: prov };
+
+      // Also check PascalCase variants (e.g. deepseek-ai/DeepSeek-V4-Flash-0731)
+      const pascal = toPascalCase(candidateName);
+      if (pascal !== candidateName) {
+        const pascalInfo = catalog[prov]?.models?.[pascal];
+        if (pascalInfo) return { info: pascalInfo, providerKey: prov };
+      }
+    }
+
+    // Fallback: canonical match on the normalised name
+    const canon = findByCanonicalId(catalog, modelName) ?? findByCanonicalId(catalog, normName);
+    if (canon) return canon;
+  }
+
+  // --- Level 3: Model name only (ignore provider, case-insensitive) ---
+  const modelNameLower = modelName.toLowerCase();
+  const normLower = normalizeVersion(modelNameLower);
+
+  const level3Names: string[] = [modelNameLower, normLower];
+  const pascal = toPascalCase(modelName);
+  if (pascal !== modelName) level3Names.push(pascal);
+
+  for (const name of level3Names) {
+    for (const [, providerData] of Object.entries(catalog)) {
+      const models = providerData?.models || {};
+      for (const [modelKey, modelData] of Object.entries(models)) {
+        const devModel = modelKey.split('/').pop()!;
+        if (devModel === name) {
+          return { info: modelData, providerKey: resolveProviderKey(catalog, modelKey) };
+        }
+      }
+    }
+  }
+
+  // --- Level 4: Prefix scoring ---
+  const nameForScoring = normalizeVersion(modelNameLower);
+  let bestMatch: { info: CatalogModelInfo; providerKey: string } | null = null;
+  let bestScore = 0;
+
+  for (const [providerKey, providerData] of Object.entries(catalog)) {
+    const models = providerData?.models || {};
+    for (const [modelKey, modelData] of Object.entries(models)) {
+      const devModel = modelKey.split('/').pop()!.toLowerCase();
+      const score = calculatePrefixScore(nameForScoring, normalizeVersion(devModel));
+      if (score > bestScore && score >= PREFIX_SCORE_THRESHOLD) {
+        // At least MIN_SEGMENTS_MATCH leading segments must match exactly
+        const inputParts = nameForScoring.split('-');
+        const devParts = normalizeVersion(devModel).split('-');
+        let segmentsMatch = 0;
+        for (let i = 0; i < Math.min(inputParts.length, devParts.length); i++) {
+          if (inputParts[i] === devParts[i]) segmentsMatch++;
+          else break;
+        }
+        if (segmentsMatch >= MIN_SEGMENTS_MATCH) {
+          bestScore = score;
+          bestMatch = { info: modelData, providerKey };
+        }
+      }
+    }
+  }
+
+  return bestMatch;
+}
+
+/**
+ * Return the provider key for a catalog model key.
+ * "deepseek-ai/DeepSeek-V4-Flash-0731" → "deepseek-ai".
+ */
+function resolveProviderKey(catalog: ModelsDevCatalog, modelKey: string): string {
+  const slash = modelKey.indexOf('/');
+  if (slash >= 0) return modelKey.slice(0, slash);
+  // Bare key — find which provider owns it
+  for (const [pk, pd] of Object.entries(catalog)) {
+    if (pd?.models?.[modelKey]) return pk;
+  }
+  return modelKey;
+}
+
+/**
+ * Search every provider for a model entry whose `canonical_model_id` matches
+ * the given model id (either full id or the bare model name).
+ */
+function findByCanonicalId(
+  catalog: ModelsDevCatalog,
+  modelId: string,
+): { info: CatalogModelInfo; providerKey: string } | null {
+  const bareName = modelId.includes('/') ? modelId.split('/').pop()! : modelId;
+  for (const [providerKey, providerData] of Object.entries(catalog)) {
+    const models = providerData?.models || {};
+    for (const [, modelData] of Object.entries(models)) {
+      if (modelData.canonical_model_id === modelId || modelData.canonical_model_id === bareName) {
+        return { info: modelData, providerKey };
+      }
+    }
+  }
+  return null;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared client for GET /api/models. Dedupes concurrent callers onto a single
+ * in-flight request and caches the result for 60s (mirroring the server-side
+ * cache TTL), so mounting ChatInput + ModelDropdown together costs one fetch.
+ */
+
+import type { AIModelOption, ModelsData } from '@/shared/types';
+import { realtimeClient } from '@/shared/lib/realtime/client';
+import { TOPIC_MODELS } from '@/shared/lib/realtime/protocol';
+
+const CACHE_TTL_MS = 60_000;
+
+/** GET /api/models response: ModelsData (real mode) + mock-mode extras. */
+export type ModelsResponse = ModelsData & { selectedModel?: AIModelOption };
+
+let inFlight: Promise<ModelsResponse> | null = null;
+let cached: { data: ModelsResponse; expiresAt: number } | null = null;
+
+export function fetchModelsData(): Promise<ModelsResponse> {
+  if (cached && cached.expiresAt > Date.now()) return Promise.resolve(cached.data);
+  if (inFlight) return inFlight;
+
+  inFlight = fetch('/api/models')
+    .then((res) => (res.ok ? res.json() : Promise.reject(new Error(`GET /api/models failed: ${res.status}`))))
+    .then((data: ModelsResponse) => {
+      cached = { data, expiresAt: Date.now() + CACHE_TTL_MS };
+      return data;
+    })
+    .finally(() => {
+      inFlight = null;
+    });
+
+  return inFlight;
+}
+
+export function invalidateModelsCache(): void {
+  cached = null;
+}
+
+/**
+ * Drop the local cache so the next read goes to the server.
+ *
+ * The server republishes the `models` topic on the same write (see
+ * `invalidateModelsCaches`), so every consumer — this tab and every other —
+ * re-reads from one signal rather than from a local event.
+ */
+export function notifyModelsUpdated(): void {
+  cached = null;
+}
+
+/**
+ * Observe the `models` topic. The callback fires when the catalog changed, so
+ * the caller can re-project its own view from `fetchModelsData`.
+ */
+export function subscribeModelsUpdated(handler: () => void): () => void {
+  return realtimeClient.subscribe(TOPIC_MODELS, handler);
+}

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

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Catalog model identity.
+ *
+ * A model id is NOT unique on its own: the omp registry exposes the same id
+ * through several providers (`deepseek-v4-flash` exists under both `deepseek`
+ * and `kenari`, `deepseek-v4-pro` likewise, …). Keying a lookup, a selection or
+ * a mutation on the id alone resolves to whichever provider comes first —
+ * hovering one row highlights the other provider's row, and toggling a
+ * favourite or a thinking preset mutates the wrong model.
+ *
+ * `modelKey` is the single composite identity every lookup/map/React key must
+ * agree on, so the pieces cannot drift apart.
+ */
+export function modelKey(model: { provider: string; id: string } | null | undefined): string {
+  return model ? `${model.provider}:${model.id}` : '';
+}