@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/client/hooks/ui/updates/shell-update.test.ts

@@ -0,0 +1,140 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The desktop self-update's client half.
+ *
+ * Two facts are pinned here and both were decisions rather than accidents:
+ *
+ * 1. **Which offers the shell can install itself** — a FILE (`direct`) in a
+ *    DESKTOP shell. An Android offer installs through `PackageInstaller` (its own
+ *    path), an iOS one cannot install at all, and a browser has no shell to ask.
+ * 2. **A failure is reported, never swallowed.** The shell's own sentence is what
+ *    a user can act on, and a run that reported success before the shell said so
+ *    would be a lie about an app that is still on the old build.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { canSelfUpdate, useShellUpdate } from '@/client/hooks/ui/updates/shell-update';
+import type { ShellDownload } from '@/client/hooks/ui/updates/shell-download';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+
+const DESKTOP: ShellDownload = {
+  url: 'https://x/Kabmo-1.2.3-mac-arm64.zip',
+  latest: '1.2.3',
+  releaseUrl: 'https://x/app',
+  direct: true,
+  kind: 'update',
+  platform: 'macos',
+};
+
+const PAGE: ShellDownload = { ...DESKTOP, url: 'https://x/app', direct: false };
+
+let container: HTMLElement;
+
+/** Install (or remove) a bridge on the page. */
+function bridge(call: ((method: string, params?: Record<string, unknown>) => Promise<unknown>) | null): void {
+  const page = globalThis as unknown as { window: { __kabmoCall?: unknown } };
+  if (call) page.window.__kabmoCall = call;
+  else delete page.window.__kabmoCall;
+}
+
+beforeAll(() => {
+  installDomGlobals(new Window({ url: 'http://localhost' }));
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  act(() => render(null, container));
+  bridge(null);
+});
+
+afterAll(() => {
+  container.remove();
+  restoreDomGlobals();
+});
+
+describe('canSelfUpdate', () => {
+  test('a direct desktop offer inside the shell is installable', () => {
+    bridge(async () => null);
+    expect(canSelfUpdate(DESKTOP)).toBe(true);
+    expect(canSelfUpdate({ ...DESKTOP, platform: 'windows' })).toBe(true);
+    expect(canSelfUpdate({ ...DESKTOP, platform: 'linux' })).toBe(true);
+  });
+
+  test('a release PAGE is not installable, whatever the platform', () => {
+    bridge(async () => null);
+    // The console could not name a file, so there is nothing to hand the shell.
+    expect(canSelfUpdate(PAGE)).toBe(false);
+  });
+
+  test('the mobile shells keep their own paths', () => {
+    bridge(async () => null);
+    // Android installs through PackageInstaller, iOS cannot install at all.
+    expect(canSelfUpdate({ ...DESKTOP, platform: 'android' })).toBe(false);
+    expect(canSelfUpdate({ ...DESKTOP, platform: 'ios' })).toBe(false);
+  });
+
+  test('a browser has no shell to ask', () => {
+    bridge(null);
+    expect(canSelfUpdate(DESKTOP)).toBe(false);
+  });
+
+  test('an absent offer is not installable', () => {
+    bridge(async () => null);
+    expect(canSelfUpdate(null)).toBe(false);
+    expect(canSelfUpdate(undefined)).toBe(false);
+  });
+});
+
+describe('useShellUpdate', () => {
+  /** A harness that exposes the hook's state and its one action. */
+  function Harness({ run }: { run: boolean }) {
+    const state = useShellUpdate();
+    if (run && state.phase === 'idle') void state.apply(DESKTOP);
+    return h('span', { id: 'state' }, `${state.phase}:${state.message ?? ''}`);
+  }
+
+  async function mount(run: boolean): Promise<string> {
+    await act(async () => {
+      render(h(Harness, { run }), container);
+    });
+    for (let i = 0; i < 20; i += 1) await act(async () => {});
+    return container.querySelector('#state')?.textContent ?? '';
+  }
+
+  test('passes the offer to the shell, and reports its own sentence', async () => {
+    const calls: { method: string; params?: Record<string, unknown> }[] = [];
+    bridge(async (method, params) => {
+      calls.push({ method, params });
+      return { success: true, version: '1.2.3', message: 'Kabmo 1.2.3 installed — restarting.', relaunching: true };
+    });
+
+    expect(await mount(true)).toBe('done:Kabmo 1.2.3 installed — restarting.');
+    expect(calls).toEqual([
+      { method: 'update_apply', params: { url: DESKTOP.url, version: DESKTOP.latest } },
+    ]);
+  });
+
+  test('a refused update keeps the shell’s reason', async () => {
+    // The shell verified the bytes and declined: "the downloaded file is not a
+    // signed Kabmo build" is the only thing that tells a user what to do next.
+    bridge(async () => ({ success: false, message: 'The downloaded file is not a signed Kabmo build.' }));
+
+    expect(await mount(true)).toBe('error:The downloaded file is not a signed Kabmo build.');
+  });
+
+  test('a shell that cannot answer is reported rather than assumed to have worked', async () => {
+    bridge(async () => {
+      throw new Error('Unknown shell command: update_apply');
+    });
+
+    expect(await mount(true)).toBe('error:Unknown shell command: update_apply');
+  });
+});

package/src/client/hooks/ui/updates/shell-update.ts

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Installing a desktop shell's own update, from the console.
+ *
+ * ## Why the shell does the work
+ *
+ * A page cannot replace the executable it runs inside, and a browser download
+ * leaves a file in a folder the user has to find and open. So the button asks
+ * the SHELL (`update_apply` over the bridge), and the shell downloads, verifies,
+ * replaces and relaunches. What this hook owns is only the part a page can own:
+ * the run's state, and reporting the outcome where the user clicked.
+ *
+ * ## Why it is a hook rather than a function at the call site
+ *
+ * Both sidebars draw this control and each one unmounts at a different moment (a
+ * phone closes the drawer, a desktop swaps sessions). The state has to live with
+ * the control that shows it, and the two must report the SAME vocabulary — so the
+ * phases and their sentences are here, not in either footer.
+ *
+ * ## A failure is always a sentence
+ *
+ * The shell sends its own reason ("the downloaded file is not a signed Kabmo
+ * build", "the installer refused with code 5"), which is the only thing that can
+ * tell a user what to do next. Nothing here replaces it with a generic failure,
+ * and nothing reports success before the shell said so.
+ */
+
+import { useCallback, useRef, useState } from 'preact/hooks';
+import {
+  applyShellUpdate,
+  bridgeError,
+  isDesktopShell,
+  type ShellUpdateOutcome,
+} from '@/client/lib/desktop/bridge';
+import type { ShellDownload } from '@/client/hooks/ui/updates/shell-download';
+
+/** What the control is doing right now. */
+export type ShellUpdatePhase = 'idle' | 'working' | 'done' | 'error';
+
+export interface ShellUpdateState {
+  phase: ShellUpdatePhase;
+  /** The shell's own sentence, for `done` and `error`. */
+  message: string | null;
+}
+
+export interface UseShellUpdateResult extends ShellUpdateState {
+  /** Run the update this offer names. */
+  apply: (download: ShellDownload) => Promise<void>;
+  /**
+   * Forget the last run, back to `idle`.
+   *
+   * The dialog calls this when it OPENS: a run that failed last time must not greet
+   * the user with its old refusal the next time they press the control.
+   */
+  reset: () => void;
+  /** True while a run is in flight, so the control can disable itself. */
+  working: boolean;
+}
+
+/**
+ * Whether this offer is something the shell can install by itself.
+ *
+ * Two facts, and both are required. The artifact must be a FILE (`direct`), and
+ * the page must be inside the desktop shell that can install it — an Android
+ * shell installs through `PackageInstaller` and iOS cannot install at all, so
+ * neither belongs to this path. A browser on a desktop gets neither, because
+ * there is no shell to ask.
+ */
+export function canSelfUpdate(download: ShellDownload | null | undefined): boolean {
+  if (!download) return false;
+  if (!download.direct) return false;
+  if (download.platform === 'android' || download.platform === 'ios') return false;
+  return isDesktopShell();
+}
+
+export function useShellUpdate(): UseShellUpdateResult {
+  const [state, setState] = useState<ShellUpdateState>({ phase: 'idle', message: null });
+  // A second click while the shell is replacing itself would be a second
+  // installer beside the first, so the run is claimed by a ref rather than by
+  // the render state — a fast double click lands before the state is read.
+  const running = useRef(false);
+
+  const apply = useCallback(async (download: ShellDownload) => {
+    if (running.current) return;
+    running.current = true;
+    setState({ phase: 'working', message: null });
+
+    try {
+      const outcome: ShellUpdateOutcome = await applyShellUpdate(download.url, download.latest);
+      setState({
+        phase: outcome.success ? 'done' : 'error',
+        // The shell's sentence is the report. `?? null` rather than a fallback
+        // string: a shell that answered nothing has said nothing, and inventing
+        // "Update failed" over it would hide that.
+        message: outcome.message ?? null,
+      });
+    } catch (cause) {
+      // A refused command (an older shell with no `update_apply`) lands here,
+      // and its own message says so.
+      setState({ phase: 'error', message: bridgeError(cause) });
+    } finally {
+      running.current = false;
+    }
+  }, []);
+
+  const reset = useCallback(() => {
+    // A run in flight is NOT resettable: the shell is already replacing itself, and
+    // reporting `idle` over it would re-arm a control whose second press would start
+    // a second installer.
+    if (running.current) return;
+    setState({ phase: 'idle', message: null });
+  }, []);
+
+  return { ...state, apply, reset, working: state.phase === 'working' };
+}

package/src/client/hooks/workspace/diff-file.ts

@@ -1,5 +1,4 @@
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
-import type { DiffContentMode } from '@/client/components/workspace/diff-panel/Toolbar';
 
 interface UseFileDiffOptions {
   filePath: string;
@@ -7,11 +6,14 @@ interface UseFileDiffOptions {
   isStaged: boolean;
   repo: string;
   root?: string;
-  contentMode: DiffContentMode;
 }
 
 export interface FileDiffState {
   rawDiff: string;
+  /** The document before the change (HEAD, or the index for an unstaged read). */
+  oldContent: string;
+  /** The document after it (the working file). */
+  newContent: string;
   currentStatus: string;
   currentStaged: boolean;
   isLoading: boolean;
@@ -31,8 +33,10 @@ export interface FileDiffState {
  * earlier read overwriting a newer one, and a dependency on the staged/status
  * copies re-keying the callback and firing a fetch per render.
  */
-export function useFileDiff({ filePath, status, isStaged, repo, root, contentMode }: UseFileDiffOptions): FileDiffState {
+export function useFileDiff({ filePath, status, isStaged, repo, root }: UseFileDiffOptions): FileDiffState {
   const [rawDiff, setRawDiff] = useState<string>('');
+  const [oldContent, setOldContent] = useState<string>('');
+  const [newContent, setNewContent] = useState<string>('');
   const [currentStatus, setCurrentStatus] = useState<string>(status);
   const [currentStaged, setCurrentStaged] = useState<boolean>(isStaged);
   const [isLoading, setIsLoading] = useState<boolean>(true);
@@ -62,11 +66,9 @@ export function useFileDiff({ filePath, status, isStaged, repo, root, contentMod
         staged: staged ? '1' : '0',
         repo: repo || '.',
       });
-      // `fullContext=1` makes git emit the whole file rather than the hunks.
-      // Only the user's own toggle changes it, so it is safe as a callback
-      // dependency (unlike the staged/status copies above, which the action
-      // path updates while a fetch of its own is already in flight).
-      if (contentMode === 'full') params.set('fullContext', '1');
+      // No `fullContext`: the panel renders both SIDES of the file now, and
+      // how much of them is shown is a client-side collapse. Asking the server
+      // for the whole file as a patch would be a second answer to that question.
       if (statusForFetch) params.set('status', statusForFetch);
       if (root) params.set('root', root);
 
@@ -74,6 +76,8 @@ export function useFileDiff({ filePath, status, isStaged, repo, root, contentMod
       const data = (await res.json().catch(() => null)) as {
         success?: boolean;
         diff?: string;
+        oldContent?: string;
+        newContent?: string;
         status?: string;
         staged?: boolean;
         error?: string;
@@ -83,6 +87,11 @@ export function useFileDiff({ filePath, status, isStaged, repo, root, contentMod
       if (seq !== fetchSeqRef.current) return;
       if (data?.success) {
         setRawDiff(data.diff || '');
+        // Both sides travel on every read: the merge view compares documents,
+        // and a whitespace fold has to be applied to the ORIGINAL, not to the
+        // patch (see `foldWhitespaceOnly`).
+        setOldContent(data.oldContent ?? '');
+        setNewContent(data.newContent ?? '');
         if (data.status) {
           statusRef.current = data.status;
           setCurrentStatus(data.status);
@@ -100,7 +109,7 @@ export function useFileDiff({ filePath, status, isStaged, repo, root, contentMod
     } finally {
       if (seq === fetchSeqRef.current) setIsLoading(false);
     }
-  }, [filePath, repo, root, contentMode]);
+  }, [filePath, repo, root]);
 
   useEffect(() => {
     setCurrentStatus(status);
@@ -124,5 +133,15 @@ export function useFileDiff({ filePath, status, isStaged, repo, root, contentMod
     }
   }, []);
 
-  return { rawDiff, currentStatus, currentStaged, isLoading, errorMessage, fetchDiff, adoptState };
+  return {
+    rawDiff,
+    oldContent,
+    newContent,
+    currentStatus,
+    currentStaged,
+    isLoading,
+    errorMessage,
+    fetchDiff,
+    adoptState,
+  };
 }

package/src/client/hooks/workspace/diff-git-actions.ts

@@ -0,0 +1,147 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The diff panel's git writes, and the conflict-marker read behind its banner.
+ *
+ * Split out of the panel because these are the only parts of it that talk to
+ * the server: the panel used to fire and forget (`fetcher.submit` + an
+ * optimistic flip + a 300ms timer), which made a rejected action
+ * indistinguishable from a successful one — the badge flipped and the diff
+ * silently stayed put. Every write here AWAITS its answer and reports the
+ * server's own reason.
+ *
+ * `revert` is the server's name for "restore this file from the index", and it
+ * is the one that handles the untracked case (there the file is removed).
+ * Sending `discard`, which no handler matched, returned `{success: true}` for
+ * doing nothing at all.
+ */
+
+import { useCallback, useEffect, useState } from 'preact/hooks';
+import type { ConflictMarkers } from '@/shared/lib/fs/git-unmerged';
+
+export interface DiffGitActions {
+  /** A write is in flight; the toolbar locks its actions. */
+  isBusy: boolean;
+  /** The server's refusal, or a transport failure, as a sentence. */
+  error: string | null;
+  /** The conflict sides' labels from the file's own markers (`{}` when none). */
+  markers: ConflictMarkers;
+  dismissError: () => void;
+  /** Stage or unstage this path, then re-read the diff at the new side. */
+  stageUnstage: () => Promise<void>;
+  /** Take one side of a conflict (or only stage a resolved file with `''`). */
+  resolve: (side: 'ours' | 'theirs' | '') => Promise<void>;
+  /** Restore this file from the index — the untracked case removes it. */
+  revert: () => Promise<void>;
+}
+
+export interface DiffGitActionsArgs {
+  filePath: string;
+  repo: string;
+  root?: string;
+  /** The status the panel currently believes (`UU`, `M`, …). */
+  status: string;
+  staged: boolean;
+  /** The panel is showing a conflicted file, so its marker labels are read. */
+  conflicted: boolean;
+  /** Adopt a state change the server confirmed. */
+  adoptState: (patch: { staged: boolean }) => void;
+  /** Re-read the diff, optionally at the other side of the index. */
+  fetchDiff: (options?: { staged: boolean }) => Promise<void>;
+  /** Something on disk changed, so the workspace panels should refresh. */
+  onFileSaved?: () => void;
+}
+
+export function useDiffGitActions(args: DiffGitActionsArgs): DiffGitActions {
+  const { filePath, repo, root, staged, conflicted, adoptState, fetchDiff, onFileSaved } = args;
+  const [isBusy, setIsBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [markers, setMarkers] = useState<ConflictMarkers>({});
+
+  const run = useCallback(
+    async (fields: Record<string, string>): Promise<boolean> => {
+      const fd = new FormData();
+      for (const [key, value] of Object.entries(fields)) fd.set(key, value);
+      fd.set('repo', repo || '.');
+      if (root) fd.set('root', root);
+      try {
+        const res = await fetch('/api/fs/git', { method: 'POST', body: fd });
+        const data = (await res.json().catch(() => null)) as { success?: boolean; error?: string } | null;
+        if (!res.ok || !data?.success) {
+          setError(data?.error || `Request failed (HTTP ${res.status})`);
+          return false;
+        }
+        setError(null);
+        return true;
+      } catch (err: unknown) {
+        setError(err instanceof Error ? err.message : 'Request failed');
+        return false;
+      }
+    },
+    [repo, root],
+  );
+
+  /** One write, its busy flag, and the refresh every action ends with. */
+  const write = useCallback(
+    async (fields: Record<string, string>, after: () => Promise<void>): Promise<void> => {
+      setIsBusy(true);
+      try {
+        if (!(await run(fields))) return;
+        await after();
+      } finally {
+        setIsBusy(false);
+      }
+    },
+    [run],
+  );
+
+  // The marker labels are fetched when the file turns out to be conflicted, and
+  // re-fetched when the path changes. Keyed on the path and the status so a
+  // resolve (which changes the status away from `UU`) clears the banner.
+  useEffect(() => {
+    if (!conflicted) {
+      setMarkers({});
+      return;
+    }
+    let cancelled = false;
+    const params = new URLSearchParams({ conflictMarkers: '1', file: filePath, repo: repo || '.' });
+    if (root) params.set('root', root);
+    void fetch(`/api/fs/git?${params.toString()}`)
+      .then((res) => res.json() as Promise<{ markers?: ConflictMarkers }>)
+      .then((body) => {
+        if (!cancelled) setMarkers(body.markers ?? {});
+      })
+      .catch(() => {
+        if (!cancelled) setMarkers({});
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [conflicted, filePath, repo, root]);
+
+  return {
+    isBusy,
+    error,
+    markers,
+    dismissError: () => setError(null),
+    stageUnstage: () =>
+      write({ actionType: staged ? 'unstage' : 'stage', file: filePath }, async () => {
+        adoptState({ staged: !staged });
+        onFileSaved?.();
+        await fetchDiff({ staged: !staged });
+      }),
+    resolve: (side) =>
+      write({ actionType: 'resolve_conflict', file: filePath, ...(side ? { side } : {}) }, async () => {
+        onFileSaved?.();
+        await fetchDiff();
+      }),
+    revert: () =>
+      write({ actionType: 'revert', file: filePath }, async () => {
+        onFileSaved?.();
+        await fetchDiff();
+      }),
+  };
+}

package/src/client/hooks/workspace/editor-view.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The desktop editor column's WIDTH mode, read and written through the session
+ * slot every surface follows.
+ *
+ * Two surfaces read it — the layout (which collapses the columns) and both
+ * toolbars (which draw the mode buttons) — so it goes through
+ * `useSharedSessionState`: `useSessionState` hands each caller a private copy,
+ * and a copy would leave the diff toolbar showing `normal` after the editor
+ * toolbar entered compact view. A private copy is right for state one component
+ * owns; this one is a decision two toolbars and the layout share.
+ *
+ * The stored mode only means anything while the editor column is OPEN. With it
+ * closed the chat is the only thing on screen, and honouring the mode would
+ * leave a blank workspace; the effective mode is therefore DERIVED rather than
+ * written back, so closing and reopening the column returns the user to the
+ * width they chose.
+ */
+
+import { useSharedSessionState } from '@/client/hooks/workspace/session-state';
+import {
+  DEFAULT_EDITOR_VIEW_MODE,
+  EDITOR_VIEW_MODE_KEY,
+  editorViewHides,
+  isEditorViewMode,
+  type EditorViewMode,
+} from '@/shared/lib/workspace/editor-view-mode';
+
+export interface EditorViewLayout {
+  /** The mode in force, after the editor-open guard. */
+  mode: EditorViewMode;
+  /** The chat column is collapsed and the editor takes its width. */
+  chatHidden: boolean;
+  /** The session sidebar is collapsed as well (full view only). */
+  sidebarHidden: boolean;
+  /** Enter a mode, or return to `normal` — see `toggledEditorViewMode`. */
+  setMode: (next: EditorViewMode) => void;
+  /** Leave `full` for `compact`: the chat stays hidden, the sidebar returns. */
+  revealSidebar: () => void;
+}
+
+export function useEditorViewLayout(editorOpen: boolean): EditorViewLayout {
+  const [stored, setMode] = useSharedSessionState<EditorViewMode>(EDITOR_VIEW_MODE_KEY, DEFAULT_EDITOR_VIEW_MODE);
+  const mode: EditorViewMode = editorOpen && isEditorViewMode(stored) ? stored : DEFAULT_EDITOR_VIEW_MODE;
+
+  return {
+    mode,
+    chatHidden: editorViewHides(mode, 'chat'),
+    sidebarHidden: editorViewHides(mode, 'sidebar'),
+    setMode,
+    // Only `full` hides the sidebar, so only `full` has anything to step back
+    // from. A caller that asks for the sidebar (the navbar's own toggle) must be
+    // able to call this unconditionally: turning `normal` into `compact` would
+    // hide the chat for a user who only wanted their sidebar back.
+    revealSidebar: () => setMode((previous) => (previous === 'full' ? 'compact' : previous)),
+  };
+}

package/src/client/hooks/workspace/file-tabs.test.ts

@@ -26,6 +26,8 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
 import { Window } from 'happy-dom';
 import type { h as PreactH, render as PreactRender } from 'preact';
+import type { ComponentChildren } from 'preact';
+import type { ComponentType } from 'preact/compat';
 import type { act as PreactAct } from 'preact/test-utils';
 import type { useFileTabs as UseFileTabsHook } from '@/client/hooks/workspace/file-tabs';
 import type { OpenFileInput } from '@/client/hooks/workspace/file-tabs';
@@ -44,7 +46,11 @@ const SESSION = 'new-file-tabs';
 const nativeFetch = Bun.fetch;
 
 let container: HTMLElement;
+/** The provider component, kept so a case can re-render with a different root. */
+let SessionStateProvider: ComponentType<{ sessionId: string; children: ComponentChildren }>;
 let handleOpenFile: ((file: OpenFileInput) => void) | null = null;
+/** The mounted probe, so a re-render can hand it another root. */
+let Probe: ComponentType<{ rootPath: string | null }>;
 let openedFiles: OpenedFile[] = [];
 let activeFileId: number | string | null = null;
 
@@ -56,23 +62,35 @@ async function settle() {
   }
 }
 
+/** Re-render the mounted tree with a different workspace root. */
+async function setRoot(rootPath: string | null): Promise<void> {
+  await act(async () => {
+    render(
+      h(SessionStateProvider, { sessionId: SESSION, children: h(Probe, { rootPath }) }),
+      container,
+    );
+  });
+  await settle();
+}
+
 /** Mount the hook inside the provider, with `stored` as the session's blob. */
-async function mount(stored: Record<string, unknown> = {}) {
+async function mount(stored: Record<string, unknown> = {}, root: string | null = ROOT) {
   globalThis.fetch = (async () => ({
     ok: true,
     json: async () => ({ sessionId: SESSION, state: stored }),
     text: async () => JSON.stringify({ sessionId: SESSION, state: stored }),
   })) as unknown as typeof fetch;
-  const { SessionStateProvider } = await import('@/client/components/common/session-state-provider/index');
-  const Probe = () => {
-    const tabs = useFileTabs(ROOT, SESSION);
+  const provider = await import('@/client/components/common/session-state-provider/index');
+  SessionStateProvider = provider.SessionStateProvider as typeof SessionStateProvider;
+  Probe = ({ rootPath }: { rootPath: string | null }) => {
+    const tabs = useFileTabs(rootPath, SESSION);
     handleOpenFile = tabs.handleOpenFile;
     openedFiles = tabs.openedFiles;
     activeFileId = tabs.activeFileId;
     return null;
   };
   await act(async () => {
-    render(h(SessionStateProvider, { sessionId: SESSION, children: h(Probe, {}) }), container);
+    render(h(SessionStateProvider, { sessionId: SESSION, children: h(Probe, { rootPath: root }) }), container);
   });
   await settle();
 }
@@ -147,6 +165,45 @@ describe('useFileTabs open resolution', () => {
     expect(activeFileId).toBe(fileTabId('src/a.ts'));
   });
 
+  /**
+   * A root that is not known yet must not close the tabs.
+   *
+   * `activeProjectPath` is derived from the sidebar's folder list, which is empty
+   * for a beat on every load and again whenever the structure topic
+   * re-subscribes. Treating that `null` as a root CHANGE wiped the file the user
+   * had just clicked, and the editor drew "Select a file to open" over it — the
+   * rare e2e failure this pins.
+   */
+  test('a transiently unknown root does not wipe the open tabs', async () => {
+    await mount();
+    await act(async () => {
+      handleOpenFile?.(explorerPayload('src/a.ts'));
+    });
+    await settle();
+    expect(openedFiles).toHaveLength(1);
+
+    // The folder list drops out and comes back — the same workspace.
+    await setRoot(null);
+    await setRoot(ROOT);
+
+    expect(openedFiles).toHaveLength(1);
+    expect(activeFileId).toBe('src/a.ts');
+  });
+
+  test('a DIFFERENT root closes the previous workspace’s tabs', async () => {
+    await mount();
+    await act(async () => {
+      handleOpenFile?.(explorerPayload('src/a.ts'));
+    });
+    await settle();
+    expect(openedFiles).toHaveLength(1);
+
+    await setRoot('/other');
+
+    expect(openedFiles).toHaveLength(0);
+    expect(activeFileId).toBeNull();
+  });
+
   test('reopening under the computed id activates the tab rather than adding one', async () => {
     await mount();