ompchamber 3.0.0 → 3.1.0

package/src/shared/lib/ui/key-binding.test.ts

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The chord matcher every shortcut in the app shares.
+ *
+ * Two failures are silent and both are covered here: matching on `event.key`
+ * (which never fires on macOS, where Option produces a different character), and
+ * a label that disagrees with the stroke it describes. The matcher is also
+ * platform-guarded, so a chord from the other platform must not fire.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  bindingFor,
+  describeStroke,
+  matchesStroke,
+  printableKey,
+  resolveBinding,
+  strokeOf,
+  type KeyBinding,
+  type KeyboardEventLike,
+} from '@/shared/lib/ui/key-binding';
+
+type Command = 'open' | 'save' | 'redo';
+
+const BINDINGS: readonly KeyBinding<Command>[] = [
+  { command: 'open', label: 'Open', mac: { code: 'KeyO', meta: true }, other: { code: 'KeyO', ctrl: true } },
+  { command: 'save', label: 'Save', mac: { code: 'KeyS', meta: true, shift: true }, other: { code: 'KeyS', ctrl: true, shift: true } },
+  {
+    command: 'redo',
+    label: 'Redo',
+    mac: { code: 'KeyZ', meta: true, shift: true },
+    other: { code: 'KeyZ', ctrl: true, shift: true },
+    windows: { code: 'KeyY', ctrl: true },
+  },
+];
+
+function key(code: string, keyName: string, modifiers: Partial<KeyboardEventLike> = {}): KeyboardEventLike {
+  return { code, key: keyName, metaKey: false, ctrlKey: false, altKey: false, shiftKey: false, ...modifiers };
+}
+
+describe('matchesStroke', () => {
+  test('requires the exact modifier set', () => {
+    const stroke = { code: 'KeyF', meta: true };
+    expect(matchesStroke(stroke, key('KeyF', 'f', { metaKey: true }))).toBe(true);
+    expect(matchesStroke(stroke, key('KeyF', 'f', { metaKey: true, shiftKey: true }))).toBe(false);
+    expect(matchesStroke(stroke, key('KeyF', 'f', { ctrlKey: true }))).toBe(false);
+  });
+
+  test('reads the physical key, not the character it produces', () => {
+    // macOS reports ⌥⌘C as `Ç`; a `key`-based test would never fire there.
+    expect(matchesStroke({ code: 'KeyC', meta: true, alt: true }, key('KeyC', 'Ç', { metaKey: true, altKey: true }))).toBe(true);
+  });
+});
+
+describe('strokeOf', () => {
+  test('picks the platform’s own chord', () => {
+    expect(strokeOf(BINDINGS[0], true)).toEqual({ code: 'KeyO', meta: true });
+    expect(strokeOf(BINDINGS[0], false)).toEqual({ code: 'KeyO', ctrl: true });
+  });
+
+  test('uses the Windows override only where it exists', () => {
+    // Windows redoes with Ctrl+Y while Linux keeps Ctrl+Shift+Z; one `other`
+    // stroke cannot express both.
+    expect(strokeOf(BINDINGS[2], false)).toEqual({ code: 'KeyZ', ctrl: true, shift: true });
+  });
+});
+
+describe('resolveBinding', () => {
+  test('returns the command a chord names', () => {
+    expect(resolveBinding(BINDINGS, key('KeyO', 'o', { metaKey: true }), true)).toBe('open');
+    expect(resolveBinding(BINDINGS, key('KeyO', 'o', { ctrlKey: true }), false)).toBe('open');
+  });
+
+  test('a chord from the other platform never fires', () => {
+    expect(resolveBinding(BINDINGS, key('KeyO', 'o', { ctrlKey: true }), true)).toBeNull();
+    expect(resolveBinding(BINDINGS, key('KeyO', 'o', { metaKey: true }), false)).toBeNull();
+  });
+
+  test('an unbound chord resolves to nothing', () => {
+    expect(resolveBinding(BINDINGS, key('KeyQ', 'q', { metaKey: true }), true)).toBeNull();
+  });
+});
+
+describe('bindingFor', () => {
+  test('finds the binding a tooltip needs to label', () => {
+    expect(bindingFor(BINDINGS, 'save')?.label).toBe('Save');
+    expect(bindingFor(BINDINGS, 'open')?.mac).toEqual({ code: 'KeyO', meta: true });
+  });
+});
+
+describe('printableKey and describeStroke', () => {
+  test('prints the physical key the way a reader expects', () => {
+    expect(printableKey('KeyC')).toBe('C');
+    expect(printableKey('Digit1')).toBe('1');
+    expect(printableKey('Slash')).toBe('/');
+    expect(printableKey('BracketLeft')).toBe('[');
+    expect(printableKey('ArrowUp')).toBe('ArrowUp');
+    expect(printableKey('F3')).toBe('F3');
+  });
+
+  test('mac chords render without separators, others with plus signs', () => {
+    expect(describeStroke({ code: 'KeyC', meta: true, alt: true }, true)).toBe('⌥⌘C');
+    expect(describeStroke({ code: 'KeyC', alt: true }, false)).toBe('Alt+C');
+    expect(describeStroke({ code: 'Slash', ctrl: true }, false)).toBe('Ctrl+/');
+  });
+
+  test('modifier order is stable, so two labels for one chord cannot differ', () => {
+    expect(describeStroke({ code: 'ArrowDown', meta: true, alt: true, shift: true }, true)).toBe('⌥⇧⌘ArrowDown');
+  });
+});

package/src/shared/lib/ui/key-binding.ts

@@ -0,0 +1,143 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One chord matcher for every shortcut in the app.
+ *
+ * The editor's find bar, the editor's own commands and the panel shortcuts all
+ * have to answer the same question — "is this event this chord?" — and they
+ * must answer it identically or the same physical key means different things
+ * depending on which surface has focus. They also have to *describe* it
+ * identically: a tooltip that reads `⌥⌘C` while the binding listens for
+ * something else is worse than an unlabeled button, and the command palette
+ * lists the very same strings.
+ *
+ * Matching is on `event.code`, not `event.key`: with Option held, macOS reports
+ * the character the combination produces (`⌥⌘C` arrives as `Ç`), so a
+ * `key`-based test silently never fires on the platform most of these
+ * shortcuts are copied from.
+ */
+
+import { isMacPlatform, isWindowsPlatform } from '@/shared/lib/util/platform';
+
+export interface KeyStroke {
+  /** `KeyboardEvent.code`, e.g. `KeyC`, `ArrowUp`, `Slash`, `Digit1`. */
+  code: string;
+  meta?: boolean;
+  ctrl?: boolean;
+  alt?: boolean;
+  shift?: boolean;
+}
+
+/** The subset of a keyboard event the matcher reads, so a test can fake one. */
+export interface KeyboardEventLike {
+  code: string;
+  key: string;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  altKey: boolean;
+  shiftKey: boolean;
+}
+
+export interface KeyBinding<Command extends string> {
+  command: Command;
+  /** What the palette and the tooltips call this command. */
+  label: string;
+  /** Chord on macOS. */
+  mac: KeyStroke;
+  /** Chord on Windows and Linux. */
+  other: KeyStroke;
+  /**
+   * Windows-only override. VS Code redoes with `Ctrl+Y` on Windows while Linux
+   * keeps `Ctrl+Shift+Z`, which one `other` stroke cannot express.
+   */
+  windows?: KeyStroke;
+}
+
+export function matchesStroke(stroke: KeyStroke, event: KeyboardEventLike): boolean {
+  return (
+    stroke.code === event.code &&
+    Boolean(stroke.meta) === event.metaKey &&
+    Boolean(stroke.ctrl) === event.ctrlKey &&
+    Boolean(stroke.alt) === event.altKey &&
+    Boolean(stroke.shift) === event.shiftKey
+  );
+}
+
+/** The chord a binding resolves to on the current platform. */
+export function strokeOf<C extends string>(binding: KeyBinding<C>, isMac: boolean): KeyStroke {
+  if (isMac) return binding.mac;
+  if (binding.windows && isWindowsPlatform()) return binding.windows;
+  return binding.other;
+}
+
+/**
+ * Codes whose printed name is not their `KeyboardEvent.code` suffix. Kept as a
+ * table because the alternative — a chain of `if`s — is what makes a label
+ * drift from the key it names.
+ */
+const KEY_LABEL_BY_CODE: Record<string, string> = {
+  Slash: '/',
+  Backslash: '\\',
+  Comma: ',',
+  Period: '.',
+  Semicolon: ';',
+  Quote: "'",
+  Backquote: '`',
+  Minus: '-',
+  Equal: '=',
+  BracketLeft: '[',
+  BracketRight: ']',
+  Space: 'Space',
+  Enter: 'Enter',
+  Escape: 'Esc',
+  Backspace: 'Backspace',
+  Delete: 'Del',
+  Tab: 'Tab',
+};
+
+/** `⌥⌘C` on macOS, `Alt+C` elsewhere. */
+export function describeStroke(stroke: KeyStroke, isMac: boolean): string {
+  const parts: string[] = [];
+  if (stroke.ctrl) parts.push(isMac ? '⌃' : 'Ctrl');
+  if (stroke.alt) parts.push(isMac ? '⌥' : 'Alt');
+  if (stroke.shift) parts.push(isMac ? '⇧' : 'Shift');
+  if (stroke.meta) parts.push(isMac ? '⌘' : 'Win');
+  parts.push(printableKey(stroke.code));
+  return isMac ? parts.join('') : parts.join('+');
+}
+
+/** The printed name of a physical key: `KeyC` → `C`, `Slash` → `/`, `ArrowUp` → `ArrowUp`. */
+export function printableKey(code: string): string {
+  if (KEY_LABEL_BY_CODE[code]) return KEY_LABEL_BY_CODE[code];
+  if (code.startsWith('Key')) return code.slice(3);
+  if (code.startsWith('Digit')) return code.slice(5);
+  return code;
+}
+
+/** The label a binding's shortcut gets in a tooltip or the palette. */
+export function describeBinding<C extends string>(binding: KeyBinding<C>, isMac: boolean = isMacPlatform()): string {
+  return describeStroke(strokeOf(binding, isMac), isMac);
+}
+
+/** The command `event` invokes, or null when no binding claims it. */
+export function resolveBinding<C extends string>(
+  bindings: readonly KeyBinding<C>[],
+  event: KeyboardEventLike,
+  isMac: boolean = isMacPlatform(),
+): C | null {
+  for (const binding of bindings) {
+    if (matchesStroke(strokeOf(binding, isMac), event)) return binding.command;
+  }
+  return null;
+}
+
+/** The binding for a command, for a call site that knows what it wants to label. */
+export function bindingFor<C extends string>(
+  bindings: readonly KeyBinding<C>[],
+  command: C,
+): KeyBinding<C> | undefined {
+  return bindings.find((binding) => binding.command === command);
+}

package/src/shared/lib/util/platform.test.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The platform sniffing the shortcut labels depend on.
+ *
+ * A wrong answer here is not cosmetic: the label and the binding are derived
+ * from the same predicate, so a mis-detected platform names a chord that does
+ * not fire. The server case matters too — these modules are imported by both
+ * bundles, and touching `navigator` unguarded would throw during SSR.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+
+import { isMacPlatform, isWindowsPlatform } from '@/shared/lib/util/platform';
+
+const displaced = (globalThis as Record<string, unknown>).navigator;
+
+function withPlatform(platform: string) {
+  (globalThis as Record<string, unknown>).navigator = { platform };
+}
+
+afterAll(() => {
+  if (displaced === undefined) delete (globalThis as Record<string, unknown>).navigator;
+  else (globalThis as Record<string, unknown>).navigator = displaced;
+});
+
+describe('isMacPlatform', () => {
+  test('recognises every Apple platform the app runs on', () => {
+    for (const platform of ['MacIntel', 'Macintosh', 'iPhone', 'iPad', 'iPod']) {
+      withPlatform(platform);
+      expect(isMacPlatform()).toBe(true);
+    }
+  });
+
+  test('is false elsewhere', () => {
+    for (const platform of ['Win32', 'Win64', 'Linux x86_64', 'Linux armv8l']) {
+      withPlatform(platform);
+      expect(isMacPlatform()).toBe(false);
+    }
+  });
+
+  test('reports false rather than throwing without a navigator', () => {
+    // Shared modules are imported by the server bundle too.
+    delete (globalThis as Record<string, unknown>).navigator;
+    expect(isMacPlatform()).toBe(false);
+    expect(isWindowsPlatform()).toBe(false);
+  });
+});
+
+describe('isWindowsPlatform', () => {
+  test('recognises the Windows spellings', () => {
+    for (const platform of ['Win32', 'Win64', 'Windows']) {
+      withPlatform(platform);
+      expect(isWindowsPlatform()).toBe(true);
+    }
+  });
+
+  test('is false on mac and Linux', () => {
+    for (const platform of ['MacIntel', 'Linux x86_64']) {
+      withPlatform(platform);
+      expect(isWindowsPlatform()).toBe(false);
+    }
+  });
+
+  test('does not match a platform that merely contains “win”', () => {
+    // `Darwin` contains `win`; a substring test without the case rule would
+    // report every macOS machine as Windows and pick the Ctrl+Y redo chord.
+    withPlatform('Darwin');
+    expect(isWindowsPlatform()).toBe(false);
+  });
+});
+
+describe('mac and Windows are mutually exclusive', () => {
+  beforeAll(() => {
+    withPlatform('MacIntel');
+  });
+
+  test('no platform reports both', () => {
+    for (const platform of ['MacIntel', 'Win32', 'Linux x86_64', 'iPhone']) {
+      withPlatform(platform);
+      expect(isMacPlatform() && isWindowsPlatform()).toBe(false);
+    }
+  });
+});

package/src/shared/lib/util/platform.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Platform sniffing for the surfaces that label a keyboard shortcut.
+ *
+ * The labels ("⌘F" vs "Ctrl+F") and the modifiers they match have to come from
+ * one place: a shortcut that is documented as ⌘F but only bound to Ctrl+F is
+ * worse than an unlabeled one. `navigator.platform` is deprecated in favour of
+ * `userAgentData.platform`, but the replacement is Chromium-only — and these
+ * checks only choose a modifier label, so the deprecated source is the one that
+ * answers on every engine. Guarded for the server, where `navigator` does not
+ * exist (shared modules are imported by both bundles).
+ */
+
+export function isMacPlatform(): boolean {
+  return typeof navigator !== 'undefined' && /(Mac|iPhone|iPod|iPad)/i.test(navigator.platform);
+}
+
+/**
+ * Anchored, because the unanchored form is wrong: `/Win/i` matches `Darwin`,
+ * which would report every macOS machine as Windows. (Measured: the redo chord
+ * then resolves to Ctrl+Y on a Mac — latent only because every call site checks
+ * `isMacPlatform` first.)
+ */
+export function isWindowsPlatform(): boolean {
+  return typeof navigator !== 'undefined' && /^Win/i.test(navigator.platform);
+}

package/src/shared/lib/workspace/keymap.test.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The workspace shortcuts.
+ *
+ * The table is what the panel tooltips read, so what matters is that every
+ * binding is unique on a platform (a duplicate silently shadows one of them) and
+ * that the chords are ones a browser or a text field does not already own —
+ * binding ⌘W or ⌘T here would break the tab, and ⌘A would break every selection
+ * in the app.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { WORKSPACE_KEY_BINDINGS } from '@/shared/lib/workspace/keymap';
+import { resolveBinding, strokeOf, type KeyboardEventLike } from '@/shared/lib/ui/key-binding';
+
+function key(code: string, modifiers: Partial<KeyboardEventLike> = {}): KeyboardEventLike {
+  return { code, key: code, metaKey: false, ctrlKey: false, altKey: false, shiftKey: false, ...modifiers };
+}
+
+/** Chords the browser or the OS owns; binding one would break the app. */
+const RESERVED: Record<string, true> = {
+  KeyW: true,
+  KeyT: true,
+  KeyN: true,
+  KeyQ: true,
+  KeyA: true,
+  KeyR: true,
+  KeyP: true,
+};
+
+describe('WORKSPACE_KEY_BINDINGS', () => {
+  test('every binding carries a label and both platforms', () => {
+    for (const binding of WORKSPACE_KEY_BINDINGS) {
+      expect(binding.label.length).toBeGreaterThan(0);
+      expect(binding.mac.code.length).toBeGreaterThan(0);
+      expect(binding.other.code.length).toBeGreaterThan(0);
+    }
+  });
+
+  test('no binding claims a chord the browser already owns', () => {
+    for (const binding of WORKSPACE_KEY_BINDINGS) {
+      expect(RESERVED[binding.mac.code]).toBeUndefined();
+    }
+  });
+
+  test('no two commands claim the same chord on a platform', () => {
+    for (const isMac of [true, false]) {
+      const seen: Record<string, string> = {};
+      for (const binding of WORKSPACE_KEY_BINDINGS) {
+        const stroke = strokeOf(binding, isMac);
+        const id = `${stroke.code}|${stroke.meta ? 'm' : ''}${stroke.ctrl ? 'c' : ''}${stroke.alt ? 'a' : ''}${stroke.shift ? 's' : ''}`;
+        expect(`${binding.command} vs ${seen[id]}`).toBe(`${binding.command} vs undefined`);
+        seen[id] = binding.command;
+      }
+    }
+  });
+
+  test('the panel toggles resolve from their own chords', () => {
+    expect(resolveBinding(WORKSPACE_KEY_BINDINGS, key('KeyB', { metaKey: true }), true)).toBe('toggleSidebar');
+    expect(resolveBinding(WORKSPACE_KEY_BINDINGS, key('KeyJ', { metaKey: true }), true)).toBe('toggleEditorPanel');
+    expect(resolveBinding(WORKSPACE_KEY_BINDINGS, key('KeyJ', { metaKey: true, altKey: true }), true)).toBe('toggleRightPanel');
+  });
+
+  test('⌘J and ⌥⌘J are different commands, not the same one twice', () => {
+    // The alt modifier is the only thing separating the editor and right panels.
+    const plain = resolveBinding(WORKSPACE_KEY_BINDINGS, key('KeyJ', { metaKey: true }), true);
+    const withAlt = resolveBinding(WORKSPACE_KEY_BINDINGS, key('KeyJ', { metaKey: true, altKey: true }), true);
+
+    expect(plain).not.toBe(withAlt);
+  });
+
+  test('save is bound here but deliberately not handled by the layout', () => {
+    // The editor panel owns ⌘S (it is the only surface with a buffer); this
+    // binding exists so a tooltip can name the chord.
+    expect(resolveBinding(WORKSPACE_KEY_BINDINGS, key('KeyS', { metaKey: true }), true)).toBe('saveFile');
+  });
+});

package/src/shared/lib/workspace/keymap.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The workspace's own shortcuts — the ones that belong to a PANEL rather than
+ * to the text inside it. Kept in a table beside the editor's keymap for the
+ * same reason: the panel toggles carry their chord in a tooltip, and a tooltip
+ * that names a key nobody listens for is a lie.
+ *
+ * These are deliberately few. A global table is where a shortcut goes to
+ * collide with the browser's own (⌘W closes a tab, ⌘T opens one, ⌘N opens a
+ * window) or with a text field the user is typing in — so only chords that are
+ * inert in a text field and unambiguous in this app are bound here.
+ */
+
+import type { KeyBinding } from '@/shared/lib/ui/key-binding';
+
+export type WorkspaceCommand = 'toggleEditorPanel' | 'toggleRightPanel' | 'toggleSidebar' | 'openSettings' | 'saveFile';
+
+export const WORKSPACE_KEY_BINDINGS: readonly KeyBinding<WorkspaceCommand>[] = [
+  // ⌘B / ⌘J are VS Code's own panel toggles.
+  { command: 'toggleSidebar', label: 'Toggle sidebar', mac: { code: 'KeyB', meta: true }, other: { code: 'KeyB', ctrl: true } },
+  { command: 'toggleEditorPanel', label: 'Toggle editor panel', mac: { code: 'KeyJ', meta: true }, other: { code: 'KeyJ', ctrl: true } },
+  { command: 'toggleRightPanel', label: 'Toggle right panel', mac: { code: 'KeyJ', meta: true, alt: true }, other: { code: 'KeyJ', ctrl: true, alt: true } },
+  // ⌘, is the platform's own settings chord (the app already binds it).
+  { command: 'openSettings', label: 'Open settings', mac: { code: 'Comma', meta: true }, other: { code: 'Comma', ctrl: true } },
+  { command: 'saveFile', label: 'Save file', mac: { code: 'KeyS', meta: true }, other: { code: 'KeyS', ctrl: true } },
+];

package/src/shared/lib/workspace/refresh-cadence.ts

@@ -93,6 +93,15 @@ export const GIT_STATUS_EVENT_THROTTLE_MS = 1_000;
  */
 export const REPO_DISCOVERY_POLL_MS = 1_500;
 
+/**
+ * Coalescing window for the todo panel's event-driven re-read. A run emits
+ * `omp:session-updated` at every turn boundary (which is what follows each tool
+ * call), so this collapses the several signals around one `todo` call into one
+ * request. Tighter than the git window on purpose: the server answers an
+ * unchanged read from a stat, and the panel is watched while the agent works.
+ */
+export const TODO_REFRESH_EVENT_THROTTLE_MS = 400;
+
 /**
  * CDP state/screencast poll. Latency-sensitive — the browser panel streams a
  * live page, so this one stays tight on purpose.

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

@@ -18,6 +18,7 @@ export const RIGHT_PANEL_TYPES = [
   'user-browser',
   'browser',
   'usage',
+  'todo',
 ] as const;
 
 export type RightPanelType = (typeof RIGHT_PANEL_TYPES)[number];
@@ -37,6 +38,7 @@ export type RightPanelType = (typeof RIGHT_PANEL_TYPES)[number];
  * - `search` matches `files`: both are single narrow columns of rows.
  * - `usage` has no OpenChamber counterpart; 0.48 keeps the pixel default it
  *   shipped with.
+ * - `todo` has no OpenChamber counterpart either; 0.3 keeps its pixel default.
  * - `context`, `git`, `terminal` and both browsers take OpenChamber's values.
  */
 export const DEFAULT_RIGHT_PANEL_FRACTIONS: Record<RightPanelType, number> = {
@@ -49,6 +51,9 @@ export const DEFAULT_RIGHT_PANEL_FRACTIONS: Record<RightPanelType, number> = {
   'user-browser': 0.45,
   browser: 0.45,
   usage: 0.48,
+  // A todo list is one column of short rows — narrower than usage, wider than
+  // a file tree, because a task line is a sentence.
+  todo: 0.3,
 };
 
 /**
@@ -65,6 +70,7 @@ export const DEFAULT_RIGHT_PANEL_WIDTHS: Record<RightPanelType, number> = {
   'user-browser': 804,
   browser: 804,
   usage: 536,
+  todo: 384,
 };
 
 /**
@@ -88,6 +94,8 @@ export const MIN_RIGHT_PANEL_WIDTHS: Record<RightPanelType, number> = {
   'user-browser': 320,
   browser: 320,
   usage: 420,
+  // Below this a task line wraps to three words a row.
+  todo: 280,
 };
 
 /** Guards a persisted or URL-provided view id before it keys a width. */

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

@@ -23,7 +23,6 @@
  * - files.expandedPaths       string[]
  * - files.searchQuery         string
  * - files.activeRepo          string
- * - browser.viewportMode      string
  * - browser.zoomLevel         number
  * - userBrowser.history       string[]
  * - userBrowser.historyIndex  number

package/src/shared/types/index.ts

@@ -22,4 +22,5 @@ export * from '@/shared/types/omp/instructions';
 export * from '@/shared/types/omp/subagent';
 export * from '@/shared/types/browser';
 export * from '@/shared/types/updates';
+export * from '@/shared/types/todo';
 export type { RightPanelType } from '@/shared/lib/workspace/right-panels';

package/src/shared/types/todo.ts

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * oh-my-pi's `todo` tool state, as the chamber reads it.
+ *
+ * omp owns this list, not the chamber: the `todo` tool writes a structured
+ * snapshot into the session JSONL (a `toolResult` entry's `details.phases`, or
+ * a `user_todo_edit` custom entry when the operator edits the list by hand), and
+ * every later branch rehydration — resume, rewind, fork, `/btw` — reads the
+ * DEEPEST such snapshot on the active branch back out of it
+ * (`getLatestTodoPhasesFromEntries`). The chamber mirrors exactly that read, so
+ * the panel and the agent's own HUD cannot disagree about what is open.
+ *
+ * The status vocabulary is omp's, including the two states the chamber's chat
+ * timeline never rendered before: `blocked` (waiting on something, with an
+ * optional note) and `abandoned` (deliberately dropped). Both are settled-but-
+ * not-done, which is why `isClosedTodo` — not `status === 'completed'` — is
+ * what any progress counter must use.
+ */
+
+/** Lifecycle state of one todo item (omp's `TodoStatus`). */
+export type TodoStatus = 'pending' | 'in_progress' | 'completed' | 'abandoned' | 'blocked';
+
+/** One task inside a phase. */
+export interface TodoItem {
+  content: string;
+  status: TodoStatus;
+  /** Present on a `blocked` task: what it is waiting for. */
+  blocker?: string;
+  details?: string;
+  notes?: string[];
+}
+
+/** A named group of tasks. */
+export interface TodoPhase {
+  name: string;
+  tasks: TodoItem[];
+}
+
+/** The `todo` op that produced a snapshot; absent on legacy transcript entries. */
+export type TodoOperation =
+  | 'init'
+  | 'start'
+  | 'done'
+  | 'rm'
+  | 'drop'
+  | 'block'
+  | 'unblock'
+  | 'append'
+  | 'view';
+
+/**
+ * Where the snapshot that resolved the list came from. A `toolResult` entry
+ * only exists when the `todo` tool actually ran in this transcript; the
+ * `custom` variant is omp's own durable rehydration record (a hand edit from
+ * the `/todo` command, a HUD reveal, or the auto-complete omp performs when a
+ * subagent matching a task description finishes). The distinction is
+ * diagnostic: "the agent never used todos here" and "the agent used them and
+ * then edited them by hand" look identical without it.
+ */
+export type TodoSnapshotSource = 'toolResult' | 'custom';
+
+/** The resolved todo list for a session, plus the entry that carried it. */
+export interface TodoSnapshot {
+  phases: TodoPhase[];
+  /** Entry id of the snapshot — what a later snapshot has to beat. */
+  sourceEntryId: string;
+  source: TodoSnapshotSource;
+  /** ISO timestamp of the snapshot entry, when it carries one. */
+  updatedAt?: string;
+  /** Op that produced it, when the entry records one. */
+  op?: TodoOperation;
+  /** omp's own storage mode: `session` (durable) or `memory` (no session file). */
+  storage?: 'session' | 'memory';
+}
+
+/** Rolled-up counters over a snapshot's tasks. */
+export interface TodoProgress {
+  total: number;
+  completed: number;
+  /** `completed` + `abandoned` — the pair omp's HUD hides as settled. */
+  closed: number;
+  inProgress: number;
+  pending: number;
+  blocked: number;
+  abandoned: number;
+}
+
+/** One session's todo state as the panel consumes it. */
+export interface SessionTodoState {
+  /** null when this session's transcript holds no committed snapshot. */
+  snapshot: TodoSnapshot | null;
+  /** Roll-up over the snapshot's tasks; all zeros when there is none. */
+  progress: TodoProgress;
+}
+
+/** Wire payload of `GET /api/omp/session-todos`. */
+export interface SessionTodosPayload extends SessionTodoState {
+  sessionId: string;
+  /** ISO timestamp of the read. */
+  generatedAt: string;
+  isMock: boolean;
+  /** Set when the session has no readable transcript (never written, or gone). */
+  error?: string;
+}