ompchamber 1.0.0 → 1.2.0

package/src/shared/lib/workspace/panel-widths.test.ts

@@ -5,37 +5,63 @@
 
 import { describe, expect, test } from 'bun:test';
 
-import { mergePanelWidths, normalizePanelWidths } from '@/shared/lib/workspace/panel-widths';
+import {
+  HANDLE_WIDTH,
+  MIN_CHAT_PANEL_WIDTH,
+  mergePanelWidths,
+  normalizePanelWidths,
+  resolvePanelWidth,
+} from '@/shared/lib/workspace/panel-widths';
 
 describe('normalizePanelWidths', () => {
   test('keeps every panel slot from a current blob', () => {
     const raw = {
       left: 342,
-      editor: 620,
-      diff: 900,
-      right: { files: 300, browser: 804 },
+      editor: { px: 620, fraction: 0.54 },
+      diff: { fraction: 0.6 },
+      right: { files: { px: 300, fraction: 0.26 }, browser: { px: 804 } },
     };
 
     expect(normalizePanelWidths(raw, 'files')).toEqual(raw);
   });
 
+  test('reads a bare number as the px-only shape and keeps it for conversion', () => {
+    // Blobs written before fractions existed: the pixel width must survive so
+    // the layout can convert it once the group's area is known.
+    const widths = normalizePanelWidths({ left: 342, editor: 620, right: { files: 300 } }, 'files');
+
+    expect(widths).toEqual({ left: 342, editor: { px: 620 }, right: { files: { px: 300 } } });
+  });
+
   test('adopts a legacy shared right width into the view that was open', () => {
     const widths = normalizePanelWidths({ left: 342, editor: 620, right: 1091 }, 'browser');
 
-    expect(widths.right).toEqual({ browser: 1091 });
+    expect(widths.right).toEqual({ browser: { px: 1091 } });
     expect(widths.left).toBe(342);
-    expect(widths.editor).toBe(620);
+    expect(widths.editor).toEqual({ px: 620 });
+  });
+
+  test('drops an out-of-range fraction instead of trusting it', () => {
+    // A fraction is a share of the area, so 0 and >1 are meaningless; the px
+    // fallback in the same slot survives, and a slot left with neither unit
+    // disappears rather than being kept as an empty object.
+    const widths = normalizePanelWidths(
+      { editor: { px: 620, fraction: 1.25 }, diff: { fraction: 0 }, right: { files: { fraction: -0.5 } } },
+      'files',
+    );
+
+    expect(widths).toEqual({ editor: { px: 620 } });
   });
 
   test('drops unusable entries instead of trusting the blob', () => {
     // `chat` is an obsolete slot — the chat column is the filler now — and a
     // blob written before that must not resurrect it.
     const widths = normalizePanelWidths(
-      { left: -10, chat: 700, editor: 620.4, diff: null, right: { files: 0, bogus: 300, git: 260 } },
+      { left: -10, chat: 700, editor: { px: 620.4 }, diff: null, right: { files: { px: 0 }, bogus: 300, git: { px: 260 } } },
       'files',
     );
 
-    expect(widths).toEqual({ editor: 620, right: { git: 260 } });
+    expect(widths).toEqual({ editor: { px: 620 }, right: { git: { px: 260 } } });
   });
 
   test('tolerates a missing or malformed blob', () => {
@@ -48,25 +74,94 @@ describe('mergePanelWidths', () => {
   test('merging one view keeps every other remembered width', () => {
     const stored = {
       left: 342,
-      editor: 620,
-      diff: 900,
-      right: { files: 300, git: 260 },
+      editor: { px: 620, fraction: 0.54 },
+      diff: { fraction: 0.6 },
+      right: { files: { px: 300, fraction: 0.26 }, git: { px: 260 } },
     };
 
-    const merged = mergePanelWidths(stored, { right: { browser: 804 } });
+    const merged = mergePanelWidths(stored, { right: { browser: { px: 804, fraction: 0.7 } } });
 
-    expect(merged.right).toEqual({ files: 300, git: 260, browser: 804 });
+    expect(merged.right).toEqual({
+      files: { px: 300, fraction: 0.26 },
+      git: { px: 260 },
+      browser: { px: 804, fraction: 0.7 },
+    });
     expect(merged.left).toBe(342);
-    expect(merged.editor).toBe(620);
-    expect(merged.diff).toBe(900);
+    expect(merged.editor).toEqual({ px: 620, fraction: 0.54 });
+    expect(merged.diff).toEqual({ fraction: 0.6 });
+  });
+
+  test('a patch adds a unit without discarding the one already stored', () => {
+    // A drag reports px + fraction together, but the conversion pass reports a
+    // fraction alone; it must not erase the px fallback it was derived from.
+    const merged = mergePanelWidths({ editor: { px: 620 } }, { editor: { fraction: 0.54 } });
+
+    expect(merged.editor).toEqual({ px: 620, fraction: 0.54 });
   });
 
   test('a resized panel replaces only its own slot', () => {
     const merged = mergePanelWidths(
-      { left: 300, editor: 620, diff: 900, right: { files: 300 } },
-      { editor: 480 },
+      { left: 300, editor: { px: 620 }, diff: { px: 900 }, right: { files: { px: 300 } } },
+      { editor: { px: 480, fraction: 0.4 } },
     );
 
-    expect(merged).toEqual({ left: 300, editor: 480, diff: 900, right: { files: 300 } });
+    expect(merged).toEqual({
+      left: 300,
+      editor: { px: 480, fraction: 0.4 },
+      diff: { px: 900 },
+      right: { files: { px: 300 } },
+    });
+  });
+});
+
+describe('resolvePanelWidth', () => {
+  const base = {
+    defaultFraction: 0.6,
+    defaultPx: 600,
+    min: 320,
+    siblingMin: 0,
+    handleCount: 0,
+  };
+
+  test('opens at its default share of the measured area', () => {
+    expect(resolvePanelWidth({ ...base, available: 1000 })).toBe(600);
+  });
+
+  test('falls back to the pixel width before the area is known', () => {
+    // Not zero: a panel whose area has not been measured yet must still render
+    // at the width it is supposed to open at.
+    expect(resolvePanelWidth({ ...base, available: null })).toBe(600);
+    expect(resolvePanelWidth({ ...base, available: null, stored: { px: 512 } })).toBe(512);
+  });
+
+  test('a px-only value holds its pixel width; only a fraction follows the area', () => {
+    // The conversion is an identity (`px / available * available`), which is
+    // the point: a pixel value someone chose is honoured as written rather than
+    // being rescaled behind their back. It stops following the window only
+    // until that slot is dragged once, which stores a fraction alongside it.
+    expect(resolvePanelWidth({ ...base, available: 1000, stored: { px: 480 } })).toBe(480);
+    expect(resolvePanelWidth({ ...base, available: 2000, stored: { px: 480 } })).toBe(480);
+    // With both units stored, the fraction is what the panel follows.
+    expect(resolvePanelWidth({ ...base, available: 2000, stored: { px: 480, fraction: 0.24 } })).toBe(480);
+    expect(resolvePanelWidth({ ...base, available: 2000, stored: { px: 480, fraction: 0.3 } })).toBe(600);
+  });
+
+  test('a stored fraction beats the default share', () => {
+    // 0.45 of 1000 is 450: above the 320 floor and below the 0.6 default, so
+    // the result can only come from the stored fraction.
+    expect(resolvePanelWidth({ ...base, available: 1000, stored: { px: 480, fraction: 0.45 } })).toBe(450);
+  });
+
+  test('the ceiling leaves the chat its floor, the siblings theirs, and the handles their width', () => {
+    const available = 2000;
+    const expected = available - MIN_CHAT_PANEL_WIDTH - 320 - 2 * HANDLE_WIDTH;
+
+    expect(resolvePanelWidth({ ...base, available, siblingMin: 320, handleCount: 2, stored: { fraction: 0.9 } })).toBe(expected);
+  });
+
+  test('the floor wins over a ceiling squeezed below it', () => {
+    // A window too narrow for the chat floor, a sibling and this panel: the
+    // panel keeps its minimum and the row clips, rather than collapsing.
+    expect(resolvePanelWidth({ ...base, available: 400, siblingMin: 320, handleCount: 2 })).toBe(320);
   });
 });

package/src/shared/lib/workspace/panel-widths.ts

@@ -8,75 +8,192 @@
  * like a reset. The chat column is the group's filler — flexbox sizes it — so
  * it has no remembered width, only a floor it may not be pushed below.
  *
- * Sizes are pixels — the unit the panel constraints are written in — and are
- * persisted as `app_settings.desktopLayoutSizes`.
+ * Two units, deliberately:
+ *
+ * - The **sidebar** is pixels. It holds a session list, which does not get more
+ *   useful on a wider monitor, and OpenChamber's sidebar is pixels too.
+ * - The **editor and right panels** are a *share of the group's available
+ *   area*. A pixel width is only right on the display it was dragged on; a
+ *   fraction follows a window resize. A remembered pixel value is kept
+ *   alongside as the fallback for the window before the area is measured and
+ *   for blobs written before the fraction existed.
+ *
+ * Sizes persist as `app_settings.desktopLayoutSizes`.
  */
 import { isRightPanelType, type RightPanelType } from '@/shared/lib/workspace/right-panels';
 
 /** The editor panel keeps a separate width while a diff tab is active. */
 export type EditorWidthMode = 'editor' | 'diff';
 
+/**
+ * A panel width in both units. `fraction` is authoritative once the group's
+ * area is known; `px` is what the panel falls back to before then, and what a
+ * blob written before fractions existed carries.
+ */
+export interface PanelWidth {
+  px?: number;
+  fraction?: number;
+}
+
 export interface PanelWidths {
-  /** Session sidebar. */
+  /** Session sidebar. Pixels only — it does not scale with the window. */
   left?: number;
   /** Editor panel while a source file tab is active. */
-  editor?: number;
+  editor?: PanelWidth;
   /** Editor panel while a diff tab is active. */
-  diff?: number;
+  diff?: PanelWidth;
   /** Right panel, keyed by the activity-bar view it currently shows. */
-  right?: Partial<Record<RightPanelType, number>>;
+  right?: Partial<Record<RightPanelType, PanelWidth>>;
 }
 
-/** Fallbacks for panels that have never been resized. */
-export const DEFAULT_PANEL_WIDTHS: Record<EditorWidthMode | 'left', number> = {
-  left: 268,
+/**
+ * Fraction each editor mode opens at, and the px width used before the group's
+ * area is known. The diff fraction matches OpenChamber's `diff` surface (3/5);
+ * its px fallback stays wider than the source editor's because `SplitView`
+ * states a 700px floor of its own, so anything below it scrolls sideways.
+ */
+export const DEFAULT_EDITOR_FRACTIONS: Record<EditorWidthMode, number> = {
+  editor: 0.6,
+  diff: 0.6,
+};
+
+export const DEFAULT_EDITOR_WIDTHS: Record<EditorWidthMode, number> = {
   editor: 600,
-  // Side-by-side diffs need both halves readable at once: `SplitView` states a
-  // 700px floor of its own, so anything below it scrolls sideways on open.
   diff: 720,
 };
 
+/** Fallback for the sidebar, which has no fraction. */
+export const DEFAULT_LEFT_PANEL_WIDTH = 280;
+
 /**
  * Panel floors and ceilings. The sidebar ceiling and the chat floor are a pair:
  * `MIN_CHAT_PANEL_WIDTH` is what stops the workspace stack from eating the
- * conversation, and it is also why the sidebar cannot open past 520 and still
- * leave the editor (300) and a browser view (320) room on a 1440px display.
+ * conversation, and it is also why the sidebar cannot open past 500 and still
+ * leave the editor (320) and a browser view (320) room on a 1440px display.
+ *
+ * `MIN_EDITOR_PANEL_WIDTH` matches the shared right-panel floor so the two
+ * panels cannot disagree about the narrowest width the same content is shown
+ * at.
  */
-export const MIN_LEFT_PANEL_WIDTH = 200;
-export const MAX_LEFT_PANEL_WIDTH = 520;
-export const MIN_CHAT_PANEL_WIDTH = 420;
-export const MIN_EDITOR_PANEL_WIDTH = 300;
-export const MAX_EDITOR_PANEL_WIDTH = 1200;
+export const MIN_LEFT_PANEL_WIDTH = 264;
+export const MAX_LEFT_PANEL_WIDTH = 500;
+export const MIN_CHAT_PANEL_WIDTH = 400;
+export const MIN_EDITOR_PANEL_WIDTH = 320;
+
+/** Draggable separator width in px (`w-[3px]` in `ResizeHandle`). */
+export const HANDLE_WIDTH = 3;
+
+/** How much of a drag may re-apply the real width, in ms. */
+export const RESIZE_FOLLOW_INTERVAL_MS = 100;
+
+export interface ResolveWidthArgs {
+  /** Remembered width for this slot, if the user ever resized it. */
+  stored?: PanelWidth;
+  /** Fraction this slot opens at when nothing was remembered. */
+  defaultFraction: number;
+  /** px this slot opens at before the area is known. */
+  defaultPx: number;
+  /** Measured area of the group, or null before the observer reports. */
+  available: number | null;
+  min: number;
+  /** Floors the other fixed panels in the same group must keep. */
+  siblingMin: number;
+  /** Separators in the group, which also consume width. */
+  handleCount: number;
+}
 
-function pixelWidth(value: unknown): number | undefined {
+/**
+ * Resolve one panel's width in px.
+ *
+ * The ceiling is dynamic — `available − chat floor − the other panels' floors`
+ * — rather than a fixed number, because a fixed one either wastes a large
+ * monitor or eats the chat on a small one. Both the editor and the right panel
+ * compete for the same budget, so whichever renders first takes its share and
+ * the other gets what is left; the caller passes `siblingMin` to say which.
+ *
+ * Without a measured area there is no budget to divide, so the stored or
+ * default pixel width is used unchanged.
+ */
+export function resolvePanelWidth(args: ResolveWidthArgs): number {
+  const { stored, defaultFraction, defaultPx, available, min, siblingMin, handleCount } = args;
+
+  if (available === null || available <= 0) return Math.max(min, Math.round(stored?.px ?? defaultPx));
+
+  const ceiling = Math.max(
+    min,
+    Math.floor(available - MIN_CHAT_PANEL_WIDTH - siblingMin - handleCount * HANDLE_WIDTH),
+  );
+
+  // A remembered fraction wins. A px-only value is honoured as written — the
+  // conversion below is an identity, deliberately: a pixel width someone chose
+  // is not silently rescaled, and it starts following the window only once that
+  // slot is dragged, which stores a fraction beside it. Reading rather than
+  // rewriting the stored blob is also what keeps a session's own widths from
+  // being clobbered by the global seed before that session's blob has loaded.
+  const fraction = stored?.fraction
+    ?? (stored?.px != null ? Math.min(1, stored.px / available) : defaultFraction);
+  const wanted = Math.round(fraction * available);
+
+  return Math.min(Math.max(wanted, min), ceiling);
+}
+
+function panelWidth(value: unknown): PanelWidth | undefined {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) && value > 0 ? { px: Math.round(value) } : undefined;
+  }
+  if (!value || typeof value !== 'object') return undefined;
+
+  const source = value as Record<string, unknown>;
+  const px = Number.isFinite(source.px) && (source.px as number) > 0 ? Math.round(source.px as number) : undefined;
+  const fraction = Number.isFinite(source.fraction) && (source.fraction as number) > 0 && (source.fraction as number) <= 1
+    ? (source.fraction as number)
+    : undefined;
+
+  if (px === undefined && fraction === undefined) return undefined;
+  return { ...(px !== undefined ? { px } : {}), ...(fraction !== undefined ? { fraction } : {}) };
+}
+
+function sidebarWidth(value: unknown): number | undefined {
   return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.round(value) : undefined;
 }
 
 /**
- * Coerce a stored blob into the current shape. Blobs written before per-view
- * widths held the right panel as a single number shared by every view; that
- * number belongs to whichever view was open when it was written, so it seeds
- * `legacyView` alone instead of being copied onto all eight.
+ * Coerce a stored blob into the current shape.
+ *
+ * Three older shapes are accepted, because a user's layout must survive the
+ * upgrade rather than silently reset:
+ *
+ * - a bare number is the px-only shape this app shipped before fractions;
+ * - a single number under `right` is older still, holding one width shared by
+ *   every view — it belongs to whichever view was open when it was written, so
+ *   it seeds `legacyView` alone instead of being copied onto all eight;
+ * - an unknown `right` key is dropped rather than trusted.
+ *
+ * Nothing is converted to a fraction here: this function is pure and the
+ * conversion needs the group's measured area. The layout performs it once the
+ * area is known (see `usePanelWidths`).
  */
 export function normalizePanelWidths(raw: unknown, legacyView: RightPanelType): PanelWidths {
   if (!raw || typeof raw !== 'object') return {};
   const source = raw as Record<string, unknown>;
 
   const widths: PanelWidths = {};
-  for (const key of ['left', 'editor', 'diff'] as const) {
-    const value = pixelWidth(source[key]);
+  const left = sidebarWidth(source.left);
+  if (left !== undefined) widths.left = left;
+  for (const key of ['editor', 'diff'] as const) {
+    const value = panelWidth(source[key]);
     if (value !== undefined) widths[key] = value;
   }
 
-  const right: Partial<Record<RightPanelType, number>> = {};
+  const right: Partial<Record<RightPanelType, PanelWidth>> = {};
   if (source.right && typeof source.right === 'object') {
     for (const [view, value] of Object.entries(source.right as Record<string, unknown>)) {
       if (!isRightPanelType(view)) continue;
-      const size = pixelWidth(value);
+      const size = panelWidth(value);
       if (size !== undefined) right[view] = size;
     }
   } else {
-    const legacy = pixelWidth(source.right);
+    const legacy = panelWidth(source.right);
     if (legacy !== undefined) right[legacyView] = legacy;
   }
   if (Object.keys(right).length > 0) widths.right = right;
@@ -84,9 +201,23 @@ export function normalizePanelWidths(raw: unknown, legacyView: RightPanelType):
   return widths;
 }
 
-/** Fold a freshly measured patch over the stored widths (one level deep for `right`). */
+/**
+ * Fold a freshly measured patch over the stored widths (one level deep for
+ * `right`, and within a slot for its two units — a fraction patch must not
+ * discard the px fallback it was derived from).
+ */
 export function mergePanelWidths(current: PanelWidths, patch: PanelWidths): PanelWidths {
   const next: PanelWidths = { ...current, ...patch };
-  if (patch.right) next.right = { ...current.right, ...patch.right };
+  if (patch.right) {
+    const right: Partial<Record<RightPanelType, PanelWidth>> = { ...current.right };
+    for (const [view, value] of Object.entries(patch.right)) {
+      if (!isRightPanelType(view) || !value) continue;
+      right[view] = { ...current.right?.[view], ...value };
+    }
+    next.right = right;
+  }
+  for (const key of ['editor', 'diff'] as const) {
+    if (patch[key]) next[key] = { ...current[key], ...patch[key] };
+  }
   return next;
 }

package/src/shared/lib/workspace/right-panels.ts

@@ -1,6 +1,7 @@
 /**
- * Right developer panel catalog: the activity-bar views, the width each one
- * opens at, and the floor at which its content starts to clip.
+ * Right developer panel catalog: the activity-bar views, the share of the
+ * group's available area each one opens at, and the floor at which its content
+ * clips.
  *
  * The list lives here rather than in the activity bar component so the layout
  * can key one remembered width per view (`panel-widths.ts`) and validate a
@@ -21,36 +22,74 @@ export const RIGHT_PANEL_TYPES = [
 
 export type RightPanelType = (typeof RIGHT_PANEL_TYPES)[number];
 
-/** Width (px) a view opens at the first time it is shown. */
+/**
+ * Share of the group's available area a view takes the first time it is shown.
+ *
+ * A fraction rather than a pixel width is what lets a panel follow a window
+ * resize instead of holding a number that was only right on the display it was
+ * dragged on. Where OpenChamber ships the same surface its `defaultWidthFraction`
+ * is reused verbatim; the rest are derived.
+ *
+ * - `files` is the file tree *alone*. OpenChamber's 3/5 `file` surface holds a
+ *   tree **and** an editor column, so its fraction is not ours to borrow — their
+ *   tree-only column is 200–480px, which is what this 0.22 approximates at a
+ *   1440-class viewport.
+ * - `search` matches `files`: both are single narrow columns of rows.
+ * - `usage` has no OpenChamber counterpart; 0.48 keeps the pixel default it
+ *   shipped with.
+ * - `context`, `git`, `terminal` and both browsers take OpenChamber's values.
+ */
+export const DEFAULT_RIGHT_PANEL_FRACTIONS: Record<RightPanelType, number> = {
+  context: 0.45,
+  files: 0.22,
+  search: 0.22,
+  git: 0.4,
+  // 80 columns at the terminal's 12px Fira Code (≈7.2px/char) need ≈600px.
+  terminal: 0.6,
+  'user-browser': 0.45,
+  browser: 0.45,
+  usage: 0.48,
+};
+
+/**
+ * Width (px) a view opens at before the group's area has been measured. Kept at
+ * the values these views shipped with, so the first paint is unchanged and a
+ * window that never reports an area still opens sensibly.
+ */
 export const DEFAULT_RIGHT_PANEL_WIDTHS: Record<RightPanelType, number> = {
+  context: 536,
   files: 268,
   search: 268,
   git: 268,
-  // 80 columns at the terminal's 12px Fira Code (≈7.2px/char) need ≈600px
-  // before the scrollbar; the old 536 landed at ≈74 columns and wrapped.
   terminal: 640,
-  context: 536,
   'user-browser': 804,
   browser: 804,
   usage: 536,
 };
 
-/** Minimum width (px) each view needs before its toolbar or list breaks. */
+/**
+ * Minimum width (px) each view needs before its toolbar or list breaks.
+ *
+ * Per view, not one shared floor: a file tree reads fine at 200 while a shell
+ * does not, and OpenChamber draws the same line (its tree-only column floors at
+ * 200, its shared panel at 320). A uniform floor would either clip the tree or
+ * force every view to shell width.
+ */
 export const MIN_RIGHT_PANEL_WIDTHS: Record<RightPanelType, number> = {
   files: 200,
   search: 200,
+  // The commit graph is a fixed-width gutter plus a message column.
   git: 260,
-  // A 200px terminal is ≈27 columns — below every shell's assumption; 320
-  // holds a two-pane TUI or a git log with the graph.
+  // A 320px terminal is ≈27 columns — below every shell's assumption, but the
+  // point where a two-pane TUI or a git log with the graph still reads.
   terminal: 320,
+  // Telemetry charts and tables need room before they wrap.
   context: 420,
   'user-browser': 320,
   browser: 320,
   usage: 420,
 };
 
-export const MAX_RIGHT_PANEL_WIDTH = 1200;
-
 /** Guards a persisted or URL-provided view id before it keys a width. */
 export function isRightPanelType(value: unknown): value is RightPanelType {
   return typeof value === 'string' && (RIGHT_PANEL_TYPES as readonly string[]).includes(value);

package/src/shared/lib/workspace/session-state/store.ts

@@ -12,6 +12,9 @@
  * Key namespace contract (dot-prefixed by owning panel):
  * - layout.activeRightPanel   RightPanelType
  * - layout.showRightPanel     boolean
+ * - layout.showLeftPanel      boolean
+ * - layout.userToggledEditor  boolean | null (null = follow whether a file is open)
+ * - layout.panelWidths        PanelWidths (per-panel widths, seeded from app_settings.desktopLayoutSizes)
  * - layout.openedFiles        editor file entries array
  * - layout.activeFileId       number | null
  * - editor.previewMode        Record<fileId, boolean>

package/src/shared/types/btw.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * BTW (side question) domain types.
+ *
+ * A BTW topic is an independent question plus its explicit follow-ups, run
+ * against the parent session's context but never appended to its transcript —
+ * the same contract omp's own `/btw` implements in the TUI. The server is the
+ * source of truth for a session's topics; the panel renders the state it is
+ * sent and streams answer text through `btw_delta` frames.
+ */
+
+/** Lifecycle of one question/answer pair inside a topic. */
+export type BtwTurnStatus = 'running' | 'complete' | 'cancelled' | 'failed' | 'interrupted';
+
+/** Model a topic's side conversation runs on — the parent session's model,
+ *  captured when the topic was created (omp's `/btw` uses the active model). */
+export interface BtwModel {
+  provider: string;
+  id: string;
+  /** Display name reported by the running side session (`DeepSeek-V4.1-Flash`). */
+  name?: string;
+}
+
+/** One question and its answer inside a topic. */
+export interface BtwTurn {
+  index: number;
+  question: string;
+  answer: string;
+  status: BtwTurnStatus;
+  createdAt: number;
+  updatedAt: number;
+}
+
+/** A side conversation scoped to one chamber session. */
+export interface BtwTopic {
+  id: string;
+  sessionId: string;
+  /** The first question, used as the topic's label in history. */
+  title: string;
+  createdAt: number;
+  updatedAt: number;
+  model?: BtwModel;
+  /** Set once the topic was promoted into the chat as a session of its own. */
+  promotedSessionId?: string;
+  turns: BtwTurn[];
+}
+
+/** A session's whole BTW view. */
+export interface BtwState {
+  topics: BtwTopic[];
+  /** Topic with a question in flight; at most one per session, because a
+   *  session runs one side conversation at a time. */
+  runningTopicId: string | null;
+}
+
+/** Server → client frames on `/api/btw/:sessionId/*` (WS and SSE alike). */
+export type BtwFrame =
+  | { type: 'connected'; sessionId: string }
+  | { type: 'btw_state'; state: BtwState }
+  | { type: 'btw_delta'; topicId: string; turnIndex: number; text: string }
+  | { type: 'btw_error'; topicId: string | null; message: string };