@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,110 @@
+/**
+ * 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
+ * stored blob without importing UI. It is also the single source of the views'
+ * *order*: the desktop activity bar, the desktop panel stack and the phone's
+ * tab bar all render from it, so the two layouts cannot drift apart.
+ */
+export const RIGHT_PANEL_TYPES = [
+  'context',
+  'files',
+  'search',
+  'git',
+  // Beside Source Control: a wiki is read off the same remote and the same
+  // repo pick, so the two are one pair in the bar rather than one at each end.
+  'wiki',
+  'terminal',
+  'user-browser',
+  'browser',
+  'usage',
+  'todo',
+  // Beside Todos: both are the SESSION's own state rather than the working
+  // tree's, and both stay reachable for a session running outside every
+  // registered workspace.
+  'plan',
+] as const;
+
+export type RightPanelType = (typeof RIGHT_PANEL_TYPES)[number];
+
+/**
+ * The box an activity-bar mark is drawn in, on BOTH layouts.
+ *
+ * One constant rather than a literal per call site, because the two layouts drew
+ * a plugin's mark at different sizes (`size={16}` on the desktop bar, `size={14}`
+ * on the phone's tab strip) while every built-in view's icon is `<… size={16} />`
+ * in the shared meta table. A plugin's button was therefore 12.5% smaller than
+ * its neighbours on the phone, and matching them meant editing two files that had
+ * no reason to disagree.
+ */
+export const PANEL_MARK_SIZE = 16;
+
+/**
+ * Share of the group's available area the right panel opens at.
+ *
+ * ONE default for every view, not a per-view table. The right panel is half of
+ * a COUPLED pair with the editor (`panel-widths.ts`): they share a combined
+ * budget and each is capped, so the editor's default and this one must sum to
+ * the pair's default (0.4 + 0.3 = 0.7). A per-view fraction would break that
+ * sum — a 0.6 terminal beside a 0.4 editor is 1.0 — so the views differ only by
+ * their floor (`MIN_RIGHT_PANEL_WIDTHS`) and their remembered width, which a
+ * drag still stores per view.
+ */
+export const DEFAULT_RIGHT_PANEL_FRACTION = 0.3;
+
+/**
+ * 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,
+  terminal: 640,
+  'user-browser': 804,
+  browser: 804,
+  usage: 536,
+  todo: 384,
+  wiki: 600,
+  plan: 600,
+};
+
+/**
+ * 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 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,
+  // Below this a task line wraps to three words a row.
+  todo: 280,
+  // The page list needs its 208px beside a readable measure; under 420 the two
+  // columns collapse into a drill-down.
+  wiki: 420,
+  // Same two-column reader as the wiki, so the same floor.
+  plan: 420,
+};
+
+/** 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/schema-migrations.ts

@@ -0,0 +1,19 @@
+import type { DbClient } from '@/server/lib/db/client';
+
+async function addColumn(db: DbClient, statement: string): Promise<void> {
+  try {
+    await db.exec(statement);
+  } catch (error) {
+    return;
+  }
+}
+
+export async function migrateWorkspaceFolderColumns(db: DbClient): Promise<void> {
+  await addColumn(db, 'ALTER TABLE workspace_folders ADD COLUMN is_expanded BOOLEAN DEFAULT 0;');
+  await addColumn(db, 'ALTER TABLE workspace_folders ADD COLUMN project_path TEXT;');
+  await addColumn(db, 'ALTER TABLE workspace_folders ADD COLUMN is_pinned BOOLEAN DEFAULT 0;');
+  await addColumn(db, "ALTER TABLE workspace_folders ADD COLUMN model TEXT DEFAULT 'Not selected';");
+  await addColumn(db, "ALTER TABLE workspace_folders ADD COLUMN accent_color TEXT DEFAULT '';");
+  await addColumn(db, "ALTER TABLE workspace_folders ADD COLUMN icon TEXT DEFAULT 'default';");
+  await addColumn(db, 'ALTER TABLE workspace_folders ADD COLUMN custom_icon_url TEXT;');
+}

package/src/shared/lib/workspace/scroll-positions.test.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The offset map's three rules, each of which fails silently in the app:
+ *
+ * - the TOP is the absence of an entry, so a reader who scrolled back to line 1
+ *   does not leave a `0` per tab in the session's blob for good;
+ * - a write that does not move the value returns the SAME object, because every
+ *   `setSessionKey` notifies every follower of the slot;
+ * - the prune drops only the tabs that are no longer open — a tab id is a hash
+ *   of a path, so a kept entry for a closed tab is a stale position that the
+ *   next open of that file would apply.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  dropScrollPosition,
+  readScrollTop,
+  writeScrollTop,
+  type ScrollPositions,
+} from '@/shared/lib/workspace/scroll-positions';
+
+describe('readScrollTop', () => {
+  test('an absent map, tab or surface reads as the top', () => {
+    expect(readScrollTop(undefined, '7', 'code')).toBe(0);
+    expect(readScrollTop({}, '7', 'code')).toBe(0);
+    expect(readScrollTop({ '7': { unified: 120 } }, '7', 'code')).toBe(0);
+    expect(readScrollTop({ '8': { code: 120 } }, '7', 'code')).toBe(0);
+  });
+
+  test('a stored offset comes back, and a non-finite one is treated as absent', () => {
+    expect(readScrollTop({ '7': { code: 420 } }, '7', 'code')).toBe(420);
+    expect(readScrollTop({ '7': { code: Number.NaN } }, '7', 'code')).toBe(0);
+    expect(readScrollTop({ '7': { code: -5 } }, '7', 'code')).toBe(0);
+  });
+
+  test('the two surfaces of one tab are separate documents', () => {
+    const positions: ScrollPositions = { '7': { code: 420, rendered: 40 } };
+    expect(readScrollTop(positions, '7', 'code')).toBe(420);
+    expect(readScrollTop(positions, '7', 'rendered')).toBe(40);
+  });
+});
+
+describe('writeScrollTop', () => {
+  test('sets one surface and leaves the others alone', () => {
+    const before: ScrollPositions = { '7': { code: 100, rendered: 20 }, '8': { code: 5 } };
+    const after = writeScrollTop(before, '7', 'code', 300);
+    expect(after).toEqual({ '7': { code: 300, rendered: 20 }, '8': { code: 5 } });
+    expect(before).toEqual({ '7': { code: 100, rendered: 20 }, '8': { code: 5 } });
+  });
+
+  test('an unchanged value returns the input, so no write is scheduled', () => {
+    const before: ScrollPositions = { '7': { code: 100 } };
+    expect(writeScrollTop(before, '7', 'code', 100)).toBe(before);
+    expect(writeScrollTop(undefined, '7', 'code', 0)).toEqual({});
+  });
+
+  test('a scroll back to the top REMOVES the entry, and the tab with it', () => {
+    const oneSurface = writeScrollTop({ '7': { code: 100, rendered: 20 } }, '7', 'code', 0);
+    expect(oneSurface).toEqual({ '7': { rendered: 20 } });
+    const noSurfaces = writeScrollTop(oneSurface, '7', 'rendered', 0);
+    expect(noSurfaces).toEqual({});
+    expect('7' in noSurfaces).toBe(false);
+  });
+});
+
+describe('dropScrollPosition', () => {
+  test('removes one tab and leaves the others alone', () => {
+    const before: ScrollPositions = { '1': { code: 10 }, '2': { code: 20 } };
+    expect(dropScrollPosition(before, '1')).toEqual({ '2': { code: 20 } });
+    expect(before).toEqual({ '1': { code: 10 }, '2': { code: 20 } });
+  });
+
+  test('a tab with no entry returns the input, so no write is scheduled', () => {
+    const before: ScrollPositions = { '1': { code: 10 } };
+    expect(dropScrollPosition(before, '9')).toBe(before);
+    expect(dropScrollPosition(undefined, '9')).toEqual({});
+  });
+});

package/src/shared/lib/workspace/scroll-positions.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Where each tab was left scrolled.
+ *
+ * The editor column keeps ONE scroll container per surface and swaps the
+ * document inside it on a tab switch, so the browser clamps the shared scroller
+ * to the height of the document now in it — returning to a long file landed at
+ * line 1. These offsets are what puts the reader back, and they live in the
+ * session's own UI state so a reload restores them too.
+ *
+ * Stored as `{ [tabKey]: { [surface]: px } }` — one entry per tab AND per
+ * surface, because the same tab scrolled in its rendered view and in its source
+ * is two different documents: a markdown preview and its code share neither a
+ * line nor a height, so one offset cannot serve both.
+ *
+ * A tab at the top of a document carries NO entry: the top is the absence of a
+ * value, not a stored `0`, which is what keeps the map from filling with rows
+ * that say nothing.
+ */
+
+/**
+ * Which surface of a tab the offset belongs to: `code`/`rendered` for a file
+ * tab (the eye toggle), `unified`/`split` for a diff (the two row shapes).
+ */
+export type ScrollSurface = 'code' | 'rendered' | 'unified' | 'split';
+
+/** Offsets per tab key, then per surface. */
+export type ScrollPositions = Record<string, Partial<Record<ScrollSurface, number>>>;
+
+/** The session-state slot these live in (see the key namespace in the store). */
+export const SCROLL_POSITIONS_KEY = 'editor.scrollPositions';
+
+/**
+ * The phone editor's own slot.
+ *
+ * It is keyed by PATH (it shows one file at a time and has no tab ids) while the
+ * desktop column is keyed by tab id, and two key spaces in one map is what makes
+ * the desktop's prune — "drop the offsets of tabs that are no longer open" —
+ * delete an entry the phone still needs. Separate slots keep the two owners from
+ * reaching into each other's entries. Nothing prunes this one: it is bounded by
+ * the files opened in one session, and each entry is a single number.
+ */
+export const MOBILE_SCROLL_POSITIONS_KEY = 'editor.mobileScrollPositions';
+
+/** The stored offset for one tab+surface; `0` (the top) when nothing was stored. */
+export function readScrollTop(positions: ScrollPositions | undefined, tabKey: string, surface: ScrollSurface): number {
+  const top = positions?.[tabKey]?.[surface];
+  return typeof top === 'number' && Number.isFinite(top) && top > 0 ? top : 0;
+}
+
+/**
+ * A new map with one offset set — or the INPUT, unchanged, when the value did
+ * not move. Callers compare identity, so a scroll that ends where it started
+ * costs no write and no persist.
+ *
+ * An offset of `0` (or less) REMOVES the entry, per the rule above: a reader who
+ * scrolled back to the top has nothing to remember, and keeping the zero would
+ * leave a row per tab for the life of the session.
+ */
+export function writeScrollTop(
+  positions: ScrollPositions | undefined,
+  tabKey: string,
+  surface: ScrollSurface,
+  top: number,
+): ScrollPositions {
+  const current = positions?.[tabKey]?.[surface];
+  if (current === top) return positions ?? {};
+  if (top <= 0) {
+    if (current === undefined) return positions ?? {};
+    const surfaces = { ...positions?.[tabKey] };
+    delete surfaces[surface];
+    const next = { ...positions };
+    if (Object.keys(surfaces).length === 0) delete next[tabKey];
+    else next[tabKey] = surfaces;
+    return next;
+  }
+  return { ...positions, [tabKey]: { ...positions?.[tabKey], [surface]: top } };
+}
+
+/**
+ * Drop ONE tab's offsets — a new map, or the input unchanged when the tab had
+ * none.
+ *
+ * Called where a tab actually closes (and where the workspace switch closes
+ * every tab), never from an effect watching the open list. That distinction is
+ * load-bearing: an effect sees the list at moments that are not user actions —
+ * before the session's blob has restored the tabs, and while a workspace switch
+ * is mid-flight — and pruning against a transiently empty list deleted every
+ * stored position on the way in (measured: the offset persisted, then came back
+ * as `{}` after a reload).
+ */
+export function dropScrollPosition(positions: ScrollPositions | undefined, tabKey: string): ScrollPositions {
+  if (!positions || !(tabKey in positions)) return positions ?? {};
+  const next = { ...positions };
+  delete next[tabKey];
+  return next;
+}

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

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Who is watching a session-state slot.
+ *
+ * `useSessionState` hands every caller a private copy, so two components reading
+ * the same key never observe each other's writes — right for state a component
+ * owns alone (a draft, a panel width), wrong for a surface that must FOLLOW a
+ * value it does not own (the Source Control dot tracking the repo the git panel
+ * picked, the phone's tab bar). Those subscribe here and re-read through
+ * `getSessionValue`; the store publishes on every write — `setSessionKey`, a
+ * blob arriving, a migrate, a delete.
+ *
+ * Separate from the store so both modules stay readable: this is a plain
+ * observer bus with no notion of what a slot holds.
+ */
+
+/** Listeners per session, then per slot (`ALL_SLOTS` = every slot of it). */
+const listeners = new Map<string, Map<string, Set<() => void>>>();
+
+/** Bucket name for a listener that follows every slot of a session. */
+const ALL_SLOTS = '*';
+
+/**
+ * Listen for writes to one slot of one session, from ANY component.
+ *
+ * `key` omitted listens to every slot of the session (what a blob arriving
+ * changes at once). Returns the unsubscribe.
+ */
+export function subscribeSessionKey(sessionId: string | null, key: string | null, listener: () => void): () => void {
+  if (!sessionId) return () => {};
+  const slot = key ?? ALL_SLOTS;
+  let slots = listeners.get(sessionId);
+  if (!slots) {
+    slots = new Map();
+    listeners.set(sessionId, slots);
+  }
+  let bucket = slots.get(slot);
+  if (!bucket) {
+    bucket = new Set();
+    slots.set(slot, bucket);
+  }
+  bucket.add(listener);
+  return () => {
+    bucket.delete(listener);
+    if (bucket.size === 0) slots.delete(slot);
+    if (slots.size === 0) listeners.delete(sessionId);
+  };
+}
+
+/** Fire one bucket, tolerating listeners that unsubscribe while notified. */
+function notifyBucket(bucket: Set<() => void> | undefined): void {
+  if (!bucket) return;
+  for (const listener of [...bucket]) listener();
+}
+
+/** Fire the listeners of one slot, or of every slot when `key` is omitted. */
+export function notifySessionKey(sessionId: string, key?: string): void {
+  const slots = listeners.get(sessionId);
+  if (!slots) return;
+  if (key === undefined) {
+    for (const bucket of [...slots.values()]) notifyBucket(bucket);
+    return;
+  }
+  notifyBucket(slots.get(key));
+  notifyBucket(slots.get(ALL_SLOTS));
+}