@kabmo-labs/kabmo 0.8.0 → 0.9.0

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

@@ -66,91 +66,52 @@
  *                             from another conversation is never restored
  * - chat.draft                string
  * - chat.draftAttachments     attachment metadata array
+ *
+ * The module is three files, because one had passed the per-file ceiling: this
+ * one owns the PUBLIC API (read, write, load, migrate) and what a write means;
+ * `cache.ts` owns the storage (the maps, the LRU order, the idle TTL, the dirty
+ * flag); `merge.ts` owns the write counter and the "which copy wins when a blob
+ * lands" decision. The maps live only in `cache.ts`, so "is this session dirty"
+ * and "drop this session" cannot be answered from two places that disagree.
  */
 
 import { notifySessionKey, notifySessionReplaced } from '@/shared/lib/workspace/session-state/listeners';
+import {
+  clearDirty,
+  dropEntry,
+  dropPersistTimer,
+  entryForWrite,
+  evictIfNeeded,
+  isDirty,
+  lastAccess,
+  markDirty,
+  readEntry,
+  setPersistTimer,
+  stampAccess,
+  touchEntry,
+  writeEntry,
+} from '@/shared/lib/workspace/session-state/cache';
+import {
+  currentWriteSeq,
+  forgetWrites,
+  keysWrittenAfter,
+  mergeStoredBlob,
+  noteWrite,
+} from '@/shared/lib/workspace/session-state/merge';
 
 type SessionState = Record<string, unknown>;
 
-const cache = new Map<string, SessionState>();
-/** Epoch ms of the last user-driven access per session (get/set/hydrate). */
-const lastTouched = new Map<string, number>();
-const dirtySessions = new Map<string, boolean>();
-const persistTimers = new Map<string, ReturnType<typeof setTimeout>>();
-
 const PERSIST_DEBOUNCE_MS = 600;
 
-// Bounded LRU cache: cap the number of sessions kept in memory so the tab
-// doesn't grow unboundedly as the user visits more sessions.
-const MAX_CACHED_SESSIONS = 10;
-/** A session whose last user access is older than this is evicted regardless
- *  of the size cap, so stale per-session UI state (drafts, panel layouts)
- *  stops occupying memory 10 minutes after the user last opened it. */
-const SESSION_IDLE_TTL_MS = 10 * 60 * 1000;
-
-/**
- * Reorder a cache entry to the end of the Map's iteration order (the
- * most-recently-used position) via delete-then-set. Map.set on an existing
- * key updates the value but keeps its original position, so the explicit
- * delete is required for true LRU semantics.
- */
-function touchCacheEntry(sessionId: string): void {
-  const value = cache.get(sessionId);
-  if (value !== undefined) {
-    cache.delete(sessionId);
-    cache.set(sessionId, value);
-  }
-  lastTouched.set(sessionId, Date.now());
-}
-
-/**
- * Evict the oldest clean sessions until the cache is within bounds.
- *
- * Dirty-safety rule: a session with unsaved writes (`dirtySessions.get(id) ===
- * true`) must never be evicted, or the user's drafts and editor state would be
- * silently lost. If every candidate is dirty (or is the protected id currently
- * being written), stop evicting rather than lose data.
- *
- * Entries idle past SESSION_IDLE_TTL_MS are evicted first — even when the
- * cache is under the size cap — so long-unused sessions drop out on schedule.
- */
-function evictIfNeeded(protectedId: string | null): void {
-  const now = Date.now();
-  const evict = (id: string): void => {
-    cache.delete(id);
-    dirtySessions.delete(id);
-    lastTouched.delete(id);
-    const timer = persistTimers.get(id);
-    if (timer) {
-      clearTimeout(timer);
-      persistTimers.delete(id);
-    }
-  };
-  // TTL pass: safe to skip only while the timer still holds the unsaved state
-  // or the session is the one currently being written.
-  for (const [id, touched] of lastTouched) {
-    if (now - touched <= SESSION_IDLE_TTL_MS) continue;
-    if (id === protectedId) continue;
-    if (dirtySessions.get(id)) continue;
-    evict(id);
-  }
-  while (cache.size > MAX_CACHED_SESSIONS) {
-    let evicted = false;
-    for (const id of cache.keys()) {
-      if (id === protectedId) continue;
-      if (dirtySessions.get(id)) continue;
-      evict(id);
-      evicted = true;
-      break;
-    }
-    if (!evicted) break;
-  }
+/** Evict past the cap, dropping this session's write history with it. */
+function evictNow(protectedId: string | null): void {
+  evictIfNeeded(protectedId, forgetWrites);
 }
 
 export function getSessionValue<T>(sessionId: string | null, key: string): T | undefined {
   if (!sessionId) return undefined;
-  touchCacheEntry(sessionId);
-  return cache.get(sessionId)?.[key] as T | undefined;
+  touchEntry(sessionId);
+  return readEntry(sessionId)?.[key] as T | undefined;
 }
 
 /**
@@ -166,18 +127,20 @@ export function getSessionValue<T>(sessionId: string | null, key: string): T | u
  */
 export function getSessionState(sessionId: string | null): Readonly<Record<string, unknown>> | undefined {
   if (!sessionId) return undefined;
-  return cache.get(sessionId);
+  return readEntry(sessionId);
 }
 
 export function setSessionKey(sessionId: string | null, key: string, value: unknown): void {
   if (!sessionId) return;
-  const state = cache.get(sessionId) ?? {};
-  state[key] = value;
-  cache.set(sessionId, state);
-  touchCacheEntry(sessionId);
-  dirtySessions.set(sessionId, true);
+  // Mutated IN PLACE, never copied: `useSessionState` compares the store's entry
+  // against its own copy by IDENTITY to decide whether a fresher write exists,
+  // and a copy per write made every reader see a different object for one slot.
+  entryForWrite(sessionId)[key] = value;
+  touchEntry(sessionId);
+  markDirty(sessionId);
+  noteWrite(sessionId, key);
   schedulePersist(sessionId);
-  evictIfNeeded(sessionId);
+  evictNow(sessionId);
   notifySessionKey(sessionId, key);
 }
 
@@ -188,22 +151,25 @@ export function setSessionKey(sessionId: string | null, key: string, value: unkn
  */
 export function clearSessionKey(sessionId: string | null, key: string): void {
   if (!sessionId) return;
-  const state = cache.get(sessionId);
+  const state = readEntry(sessionId);
   if (!state || !(key in state)) return;
-  delete state[key];
-  touchCacheEntry(sessionId);
-  dirtySessions.set(sessionId, true);
+  delete (state as SessionState)[key];
+  touchEntry(sessionId);
+  markDirty(sessionId);
+  // A DELETE is a write: a blob that still carries the key must not bring it
+  // back (a retired key cleared on this side would return from the other tab's
+  // older snapshot).
+  noteWrite(sessionId, key);
   schedulePersist(sessionId);
   notifySessionKey(sessionId, key);
 }
 
 function schedulePersist(sessionId: string): void {
-  const existing = persistTimers.get(sessionId);
-  if (existing) clearTimeout(existing);
-  persistTimers.set(
+  dropPersistTimer(sessionId);
+  setPersistTimer(
     sessionId,
     setTimeout(() => {
-      persistTimers.delete(sessionId);
+      dropPersistTimer(sessionId);
       void persistSession(sessionId);
     }, PERSIST_DEBOUNCE_MS),
   );
@@ -211,9 +177,9 @@ function schedulePersist(sessionId: string): void {
 
 async function persistSession(sessionId: string): Promise<void> {
   if (typeof window === 'undefined' || !sessionId) return;
-  if (!dirtySessions.get(sessionId)) return;
-  dirtySessions.set(sessionId, false);
-  const state = cache.get(sessionId) ?? {};
+  if (!isDirty(sessionId)) return;
+  clearDirty(sessionId);
+  const state = readEntry(sessionId) ?? {};
   try {
     await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/state`, {
       method: 'POST',
@@ -222,18 +188,14 @@ async function persistSession(sessionId: string): Promise<void> {
     });
   } catch (err) {
     console.warn('session-state persist failed:', err);
-    dirtySessions.set(sessionId, true);
+    markDirty(sessionId);
   }
 }
 
 /** Immediately persist any pending writes for a session (used on switch). */
 export function flushSession(sessionId: string | null): Promise<void> {
   if (!sessionId || typeof window === 'undefined') return Promise.resolve();
-  const timer = persistTimers.get(sessionId);
-  if (timer) {
-    clearTimeout(timer);
-    persistTimers.delete(sessionId);
-  }
+  dropPersistTimer(sessionId);
   return persistSession(sessionId);
 }
 
@@ -241,27 +203,34 @@ export function flushSession(sessionId: string | null): Promise<void> {
 export async function loadSession(sessionId: string): Promise<void> {
   if (!sessionId) return;
   if (typeof window === 'undefined') return;
+  /**
+   * The write counter as of the moment the read STARTED.
+   *
+   * Everything written after this is newer than the response, because the
+   * response describes the row as it was when the request arrived. Two
+   * mechanisms are needed and neither is sufficient alone: `dirtySessions`
+   * covers a write whose persist has not landed yet, while this covers one that
+   * already persisted — at which point the dirty flag is clear and a stale
+   * response would otherwise be adopted wholesale. Measured: a file opened
+   * during the first `/state` read came back with `layout.openedFiles` gone.
+   */
+  const startedAt = currentWriteSeq();
   try {
     const res = await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/state`);
     if (res.ok) {
       const data = (await res.json()) as { state?: SessionState };
       const incoming = data.state && typeof data.state === 'object' ? data.state : {};
-      const existing = cache.get(sessionId) ?? {};
-      // Only keys written locally while the fetch was in flight win over the
-      // stored blob. Merging the WHOLE local cache over the blob (the old
-      // behavior) resurrected stale values on every tab: a second browser
-      // opening the session had cached the pre-write blob, and its stale
-      // copy clobbered another tab's fresh writes — queue items written in
-      // one tab never appeared in the other.
-      const dirty = dirtySessions.get(sessionId) === true;
-      const merged = dirty ? { ...incoming, ...existing } : incoming;
-      cache.set(sessionId, merged);
-      touchCacheEntry(sessionId);
+      const existing = readEntry(sessionId) ?? {};
+      writeEntry(
+        sessionId,
+        mergeStoredBlob(incoming, existing, keysWrittenAfter(sessionId, startedAt), isDirty(sessionId)),
+      );
+      touchEntry(sessionId);
     }
   } catch (err) {
     console.warn('session-state load failed:', err);
   }
-  evictIfNeeded(sessionId);
+  evictNow(sessionId);
   // The blob replaces every slot at once, so a follower that read the store
   // before it arrived (no pick yet) has to re-read — including a private copy
   // held by `useSessionState`, which does not follow per-slot writes.
@@ -272,9 +241,9 @@ export async function loadSession(sessionId: string): Promise<void> {
 /** Seed the cache synchronously (e.g. from SSR-provided data). */
 export function hydrateSession(sessionId: string | null, state: SessionState): void {
   if (!sessionId) return;
-  cache.set(sessionId, { ...(cache.get(sessionId) ?? {}), ...state });
-  touchCacheEntry(sessionId);
-  evictIfNeeded(sessionId);
+  writeEntry(sessionId, { ...(readEntry(sessionId) ?? {}), ...state });
+  touchEntry(sessionId);
+  evictNow(sessionId);
   notifySessionKey(sessionId);
   notifySessionReplaced(sessionId);
 }
@@ -285,12 +254,12 @@ export function hydrateSession(sessionId: string | null, state: SessionState): v
  * its last open is within SESSION_IDLE_TTL_MS.
  */
 export function recordSessionOpen(sessionId: string | null): void {
-  if (sessionId) lastTouched.set(sessionId, Date.now());
+  if (sessionId) stampAccess(sessionId);
 }
 
 /** Epoch ms of the user's last open of this session in this tab, if any. */
 export function getLastOpenedAt(sessionId: string): number | undefined {
-  return lastTouched.get(sessionId);
+  return lastAccess(sessionId);
 }
 
 /**
@@ -302,14 +271,8 @@ export function getLastOpenedAt(sessionId: string): number | undefined {
  * the delete and resurrect the state.
  */
 export function forgetSession(sessionId: string): void {
-  const timer = persistTimers.get(sessionId);
-  if (timer) {
-    clearTimeout(timer);
-    persistTimers.delete(sessionId);
-  }
-  cache.delete(sessionId);
-  dirtySessions.delete(sessionId);
-  lastTouched.delete(sessionId);
+  dropEntry(sessionId);
+  forgetWrites(sessionId);
   notifySessionKey(sessionId);
   notifySessionReplaced(sessionId);
 }
@@ -319,15 +282,14 @@ export function forgetSession(sessionId: string): void {
  * by a spawn, then discard the transient slot.
  */
 export function migrateSessionState(fromId: string, toId: string): void {
-  const from = cache.get(fromId);
-  if (from) cache.set(toId, { ...from, ...(cache.get(toId) ?? {}) });
-  touchCacheEntry(toId);
-  dirtySessions.set(toId, true);
+  const from = readEntry(fromId);
+  if (from) writeEntry(toId, { ...from, ...(readEntry(toId) ?? {}) });
+  touchEntry(toId);
+  markDirty(toId);
   schedulePersist(toId);
-  cache.delete(fromId);
-  dirtySessions.delete(fromId);
-  lastTouched.delete(fromId);
-  evictIfNeeded(toId);
+  dropEntry(fromId);
+  forgetWrites(fromId);
+  evictNow(toId);
   // The adopted slot gained the whole transient state; the transient one lost it.
   notifySessionKey(toId);
   notifySessionKey(fromId);

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

@@ -0,0 +1,124 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The desktop workspace group's three panel widths, resolved from one place.
+ *
+ * `WorkspacePanels` used to compute these inline, which was correct but made the
+ * component's own contract hard to read and impossible to unit-test: every rule
+ * here — the two-call order, the pair caps, the leftover width a collapsed chat
+ * hands the editor — is arithmetic over values the caller already has.
+ *
+ * Pure: no hooks, no DOM. The caller measures the group and reads the stored
+ * widths; this module decides what those mean.
+ */
+
+import {
+  DEFAULT_EDITOR_FRACTIONS,
+  DEFAULT_EDITOR_WIDTHS,
+  HANDLE_WIDTH,
+  MIN_EDITOR_PANEL_WIDTH,
+  panelFraction,
+  pairMaxSize,
+  resolvePanelWidth,
+  type EditorWidthMode,
+  type PanelWidths,
+} from '@/shared/lib/workspace/panel-widths';
+import { DEFAULT_RIGHT_PANEL_FRACTION } from '@/shared/lib/workspace/right-panels';
+
+export interface WorkspacePanelWidthsArgs {
+  /** Measured area of the group, or null before the observer reports. */
+  available: number | null;
+  /** This session's remembered widths. */
+  panelWidths: PanelWidths;
+  /** Which slot the editor column is using (a diff wants more room). */
+  editorWidthMode: EditorWidthMode;
+  /** The right panel's active view, whose slot and defaults apply. */
+  activeRightPanel: string;
+  /** The active view's own defaults and floor, when it has them. */
+  activePanel?: { defaultFraction?: number; defaultWidth?: number; minWidth?: number };
+  showEditor: boolean;
+  showRightPanel: boolean;
+  /** The chat column is collapsed, so it holds no floor and no pair share. */
+  chatHidden: boolean;
+}
+
+export interface WorkspacePanelWidths {
+  right: number;
+  editor: number;
+  /** Drag ceilings; `undefined` before the group is measured. */
+  editorMax: number | undefined;
+  rightMax: number | undefined;
+  /** Separators actually rendered, which also consume width. */
+  handleCount: number;
+  /** The right panel's floor, which the drag ceiling also reserves. */
+  rightMin: number;
+}
+
+export function resolveWorkspacePanelWidths(args: WorkspacePanelWidthsArgs): WorkspacePanelWidths {
+  const { available, panelWidths, editorWidthMode, activeRightPanel, activePanel, showEditor, showRightPanel, chatHidden } = args;
+
+  // The separator before the editor is gone while the chat is collapsed: there
+  // is nothing on its left to transfer width to, and the drag's neighbour walk
+  // skips a collapsed panel, so it would render a handle that does nothing.
+  const handleCount = (showEditor && !chatHidden ? 1 : 0) + (showRightPanel ? 1 : 0);
+  const rightMin = activePanel?.minWidth ?? MIN_EDITOR_PANEL_WIDTH;
+
+  // The editor and the right panel are a COUPLED pair: the right panel is
+  // resolved first, reserving the editor's WANTED share (the editor has no
+  // result yet), and the editor then reserves the right panel's ACTUAL width.
+  // That asymmetry is deliberate — an editor asking for more than its default
+  // makes the right panel give way first, and the pair still sums to the total.
+  const editorFraction = panelFraction(panelWidths[editorWidthMode], DEFAULT_EDITOR_FRACTIONS[editorWidthMode], available);
+  const editorReservePx = available != null && available > 0 ? Math.round(editorFraction * available) : 0;
+
+  const right = resolvePanelWidth({
+    stored: panelWidths.right?.[activeRightPanel],
+    defaultFraction: activePanel?.defaultFraction ?? DEFAULT_RIGHT_PANEL_FRACTION,
+    defaultPx: activePanel?.defaultWidth ?? MIN_EDITOR_PANEL_WIDTH,
+    available,
+    min: rightMin,
+    pairReservePx: showEditor ? editorReservePx : 0,
+    // The editor has not been resolved yet, so only its floor can be reserved.
+    siblingWidth: showEditor ? MIN_EDITOR_PANEL_WIDTH : 0,
+    handleCount,
+    chatHidden,
+  });
+
+  // With the chat collapsed the editor takes everything the right panel and the
+  // separators do not. Resolving from its remembered FRACTION would leave the
+  // freed width as an empty gap, which is the opposite of what the mode
+  // promises; the remembered width is untouched, so leaving restores it.
+  const editor = chatHidden
+    ? Math.max(
+        MIN_EDITOR_PANEL_WIDTH,
+        available != null && available > 0
+          ? Math.floor(available - (showRightPanel ? right : 0) - handleCount * HANDLE_WIDTH)
+          : DEFAULT_EDITOR_WIDTHS[editorWidthMode],
+      )
+    : resolvePanelWidth({
+        stored: panelWidths[editorWidthMode],
+        defaultFraction: DEFAULT_EDITOR_FRACTIONS[editorWidthMode],
+        defaultPx: DEFAULT_EDITOR_WIDTHS[editorWidthMode],
+        available,
+        min: MIN_EDITOR_PANEL_WIDTH,
+        pairReservePx: showRightPanel ? right : 0,
+        siblingWidth: showRightPanel ? right : 0,
+        handleCount,
+      });
+
+  return {
+    right,
+    editor,
+    // `resolvePanelWidth` caps what it HANDS to `defaultSize`, but a separator
+    // drag bypasses it — the resizer transfers pixels between two panels clamped
+    // only by their own `maxSize`. Each max is its own cap and the pair total
+    // minus the sibling's FLOOR (it gives way down to its minimum mid-drag).
+    editorMax: pairMaxSize({ available, siblingMin: rightMin, siblingOpen: showRightPanel, chatHidden }),
+    rightMax: pairMaxSize({ available, siblingMin: MIN_EDITOR_PANEL_WIDTH, siblingOpen: showEditor, chatHidden }),
+    handleCount,
+    rightMin,
+  };
+}

package/src/shared/types/realtime.ts

@@ -32,3 +32,32 @@ export interface SidebarStatusEntry {
 
 /** `sidebar:status` — keyed by session id. Absent id means "no volatile fields". */
 export type SidebarStatusPayload = Record<string, SidebarStatusEntry>;
+
+/**
+ * One live session's row fields that can still move between turn boundaries.
+ *
+ * Exactly two, and the list is closed on purpose: everything else about a row
+ * (title, folder, cwd, worktree, archived) only changes on a STRUCTURAL event
+ * that publishes the structure for its own reason. These two are the ones a
+ * run advances mid-turn — the transcript appends, and a subagent's transcript
+ * appears beside it (which is what lights the row's roster chevron).
+ */
+export interface SidebarActivityEntry {
+  /** Newest transcript entry's ISO timestamp — the row's age and its
+   *  `LATEST_SESSION` position. */
+  updatedAt?: string;
+  /** Whether the session has any subagent transcript on disk. */
+  hasSubagents?: boolean;
+}
+
+/**
+ * `sidebar:activity` — session id → the live fields above, for the sessions
+ * with a run in flight.
+ *
+ * Only a running session can move between turn boundaries, so an id that is
+ * absent here simply keeps what the structure gave it. Both sides read the same
+ * sources (the newest JSONL entry's own `timestamp`, and the subagent
+ * transcript directory), so the client merges field by field and lets the
+ * newer stamp win.
+ */
+export type SidebarActivityPayload = Record<string, SidebarActivityEntry>;

package/src/shared/types/settings/state.ts

@@ -48,6 +48,16 @@ export interface SettingsState {
    * cannot render a broken editor, only a different one.
    */
   editorFont: string;
+  /**
+   * Colour theme for the code editor, INDEPENDENT of `theme` above.
+   *
+   * `auto` (the default) keeps the editor on the app palette. Any other value
+   * is a Shiki theme id from `EDITOR_THEMES` — the editor then paints its own
+   * surface, gutter, selection and tokens while the console around it keeps the
+   * app palette. `resolveEditorTheme` treats an id this build no longer ships
+   * as `auto`, so a downgrade renders the app palette rather than half a theme.
+   */
+  editorTheme: string;
   /** Generate a session title from the first run. omp suppresses its
    *  own auto-titling under `--mode rpc-ui` (PI_NO_TITLE), so without this a
    *  Kabmo session keeps its `New Session - <timestamp>` placeholder. Asked