@kabmo-labs/kabmo 0.5.3 → 0.6.1

package/src/client/components/common/window-controls/index.test.tsx

@@ -0,0 +1,113 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The window controls, rendered only for a shell that has none of its own.
+ *
+ * Three properties are what this suite exists for, and each fails as a button
+ * that looks fine and does nothing:
+ *
+ * 1. **Nothing in a browser.** There is no shell, so `window.__kabmoCall` does
+ *    not exist and a click would be a no-op behind a control that appears to
+ *    work.
+ * 2. **Nothing on macOS**, whose traffic lights are the system's — a second set
+ *    drawn by the page would be two close buttons for one window.
+ * 3. **A click issues the shell's own verb.** The window state lives in the
+ *    shell, so the only observable here is the command that crossed the bridge.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { WindowControls } from '@/client/components/common/window-controls';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+
+type Shell = {
+  __kabmoCall?: (method: string, params?: Record<string, unknown>) => Promise<unknown>;
+  __kabmoDesktop?: Record<string, unknown>;
+};
+
+const scope = () => globalThis as unknown as { window?: Shell };
+
+let win: Window;
+let container: HTMLElement;
+let calls: string[];
+
+function mount(identity: Record<string, unknown> | null, withBridge: boolean) {
+  calls = [];
+  const shellWindow = win as unknown as Shell;
+  if (withBridge) {
+    shellWindow.__kabmoCall = async (method) => {
+      calls.push(method);
+      return null;
+    };
+  } else {
+    delete shellWindow.__kabmoCall;
+  }
+  if (identity) shellWindow.__kabmoDesktop = identity;
+  else delete shellWindow.__kabmoDesktop;
+
+  win.document.body.innerHTML = '';
+  container = win.document.createElement('div') as unknown as HTMLElement;
+  win.document.body.appendChild(container as never);
+  act(() => {
+    render(h(WindowControls, {}), container);
+  });
+}
+
+const buttons = () => Array.from(container.querySelectorAll('button'));
+
+describe('WindowControls', () => {
+  beforeEach(() => {
+    win = new Window({ url: 'http://127.0.0.1:3000/' });
+    installDomGlobals(win as never);
+  });
+
+  afterEach(() => {
+    restoreDomGlobals();
+    delete scope().window;
+  });
+
+  test('three buttons, each with an accessible name', () => {
+    mount({ platform: 'windows', shellVersion: '0.1.0', overlayTitlebar: true, windowControls: true }, true);
+    const labels = buttons().map((button) => button.getAttribute('aria-label'));
+    expect(labels).toEqual(['Minimize', 'Maximize', 'Close']);
+    // An icon-only control with no title is a tooltip-less button.
+    expect(buttons().every((button) => Boolean(button.getAttribute('title')))).toBe(true);
+  });
+
+  test('a click issues the shell’s own verb', () => {
+    mount({ platform: 'windows', shellVersion: '0.1.0', overlayTitlebar: true, windowControls: true }, true);
+    for (const button of buttons()) {
+      act(() => {
+        button.dispatchEvent(new win.MouseEvent('click', { bubbles: true }) as never);
+      });
+    }
+    expect(calls).toEqual(['window_minimize', 'window_maximize', 'window_close']);
+  });
+
+  /** The label follows the click, so a maximised window does not say "Maximize". */
+  test('the maximize button reads Restore after a click', () => {
+    mount({ platform: 'windows', shellVersion: '0.1.0', overlayTitlebar: true, windowControls: true }, true);
+    const maximize = buttons()[1];
+    expect(maximize.getAttribute('aria-label')).toBe('Maximize');
+    act(() => {
+      maximize.dispatchEvent(new win.MouseEvent('click', { bubbles: true }) as never);
+    });
+    expect(buttons()[1].getAttribute('aria-label')).toBe('Restore');
+  });
+
+  /** A bridge that is missing must not throw out of a click handler. */
+  test('a click without a bridge is inert', () => {
+    mount(null, false);
+    expect(() => {
+      act(() => {
+        buttons()[0].dispatchEvent(new win.MouseEvent('click', { bubbles: true }) as never);
+      });
+    }).not.toThrow();
+    expect(calls).toEqual([]);
+  });
+});

package/src/client/components/common/window-controls/index.tsx

@@ -0,0 +1,66 @@
+import { useState } from 'preact/hooks';
+import { Minus, Square, X } from 'lucide-preact';
+
+/**
+ * The window's own controls, for a shell that has none.
+ *
+ * The macOS shell keeps the system's traffic lights (a `fullSizeContentView`
+ * window over a transparent title bar), so the page draws nothing. The Windows
+ * shell is borderless, and its webview is an HWND — no host element can be
+ * painted over it — so the three buttons the system would draw have to come from
+ * the page. `drawsWindowControls()` is what says which shell this is; the buttons
+ * exist only there, and a browser tab never renders them.
+ *
+ * Two decisions:
+ *
+ * - **The glyphs are Lucide's, not the OS's.** Windows draws its own caption
+ *   buttons at a size and weight that a web font cannot reproduce, so pretending
+ *   to would look almost right — the worst outcome. These read as the app's
+ *   chrome, which is what they are.
+ * - **Close is the only one with a destructive hover.** A red fill on minimise
+ *   would make a harmless action look dangerous.
+ *
+ * Every button is `aria-label`ed and titled: an icon-only control with no
+ * accessible name is unreachable by keyboard and invisible to a screen reader.
+ */
+export function WindowControls() {
+  const [maximised, setMaximised] = useState(false);
+  const call = (method: 'window_minimize' | 'window_maximize' | 'window_close') => {
+    void window.__kabmoCall?.(method).catch(() => undefined);
+    // The shell owns the state; this only keeps the glyph honest between the
+    // click and the window's own resize notification.
+    if (method === 'window_maximize') setMaximised((value) => !value);
+  };
+
+  return (
+    <div className="flex items-stretch h-10 -mr-1 titlebar-no-drag" role="group" aria-label="Window controls">
+      <button
+        type="button"
+        onClick={() => call('window_minimize')}
+        title="Minimize"
+        aria-label="Minimize"
+        className="w-11 inline-flex items-center justify-center text-ink/60 hover:bg-ink/10 hover:text-ink transition-colors cursor-pointer"
+      >
+        <Minus size={14} />
+      </button>
+      <button
+        type="button"
+        onClick={() => call('window_maximize')}
+        title={maximised ? 'Restore' : 'Maximize'}
+        aria-label={maximised ? 'Restore' : 'Maximize'}
+        className="w-11 inline-flex items-center justify-center text-ink/60 hover:bg-ink/10 hover:text-ink transition-colors cursor-pointer"
+      >
+        <Square size={12} />
+      </button>
+      <button
+        type="button"
+        onClick={() => call('window_close')}
+        title="Close (Alt+F4)"
+        aria-label="Close"
+        className="w-11 inline-flex items-center justify-center text-ink/60 hover:bg-error hover:text-paper transition-colors cursor-pointer"
+      >
+        <X size={15} />
+      </button>
+    </div>
+  );
+}

package/src/client/components/layout/desktop-layout/LeftColumn.tsx

@@ -46,7 +46,7 @@ import { SettingsModal } from '@/client/components/settings/LazyModal';
 import { SessionSidebarFooter } from '@/client/components/layout/session-sidebar/Footer';
 import { SessionSidebarHeader } from '@/client/components/layout/session-sidebar/Header';
 import { ToastStack } from '@/client/components/common/ToastStack';
-import { useAndroidDownload } from '@/client/hooks/ui/updates/android-download';
+import { useShellOffer } from '@/client/hooks/ui/updates/shell-download';
 import { useKabmoEvent } from '@/client/hooks/ui/window-event';
 import { useToasts } from '@/client/hooks/ui/toasts';
 import { useUpdates } from '@/client/hooks/ui/updates';
@@ -95,10 +95,7 @@ export function LeftColumn({
   const [infoOpen, setInfoOpen] = useState(false);
   const updates = useUpdates();
   const { toasts, pushToast, dismissToast } = useToasts();
-  const androidDownload = useAndroidDownload(
-    window.__OMP_BOOTSTRAP__?.shellVersion,
-    window.__OMP_BOOTSTRAP__?.isAndroid,
-  );
+  const shellDownload = useShellOffer();
 
   // The update popup's "Update now" hands the run to the About modal, which owns
   // the live output. The column owns both, so a view switch cannot lose them.
@@ -151,7 +148,7 @@ export function LeftColumn({
           <SessionSidebarFooter
             onSettings={() => setSettingsOpen(true)}
             onInfo={() => setInfoOpen(true)}
-            androidDownload={androidDownload}
+            shellDownload={shellDownload}
             updateAvailable={updates.hasUpdate}
             onUpdateClick={() => {
               setInfoOpen(true);

package/src/client/components/layout/desktop-layout/TopNavbar.tsx

@@ -1,4 +1,5 @@
-import { Loader2, MoreHorizontal, PanelLeft } from 'lucide-preact';
+import { useRef, useState } from 'preact/hooks';
+import { Loader2, MoreHorizontal, PanelLeft, ServerCog } from 'lucide-preact';
 import { HeaderControls } from '@/client/components/common/header-controls';
 import { BrandWordmark } from '@/client/components/common/brand-wordmark';
 import { StreamStatusDot } from '@/client/components/common/StreamStatusDot';
@@ -8,6 +9,12 @@ import { useSessionRenaming } from '@/client/hooks/workspace/renaming-sessions';
 import type { AgentStreamStatus } from '@/shared/lib/chat/omp/status';
 import { withChord } from '@/client/lib/ui/with-chord';
 import { titlebarPaddingLeft, titlebarPaddingRight } from '@/shared/lib/ui/titlebar';
+import { ServerSwitcher } from '@/client/components/common/server-switcher';
+import { useDesktopServers } from '@/client/hooks/desktop/servers';
+import { isDesktopShell } from '@/client/lib/desktop/bridge';
+import { dragRegionProps, drawsWindowControls, titlebarInsetLeft } from '@/client/lib/desktop/titlebar';
+import { WindowControls } from '@/client/components/common/window-controls';
+import { useOnClickOutside } from '@/client/hooks/ui/on-click-outside';
 
 interface TopNavbarProps {
   sessionTitle: string | null;
@@ -55,15 +62,29 @@ export function TopNavbar({
   // sidebar row may be scrolled out of view — so the header says the wait is
   // happening even when the row that started it is not on screen.
   const renaming = useSessionRenaming(sessionId);
+  // The shell's server control: which server this window is on, and how to
+  // change it. Absent in a browser — there is no shell to control there, and a
+  // button that opened onto "not available" would never work.
+  const shell = isDesktopShell();
+  const [serverPanelOpen, setServerPanelOpen] = useState(false);
+  const serverPanelRef = useRef<HTMLDivElement>(null);
+  const servers = useDesktopServers(serverPanelOpen);
+  const activeServer =
+    servers.state?.entries.find((entry) => entry.id === servers.state?.activeId) ??
+    servers.state?.detected.find((entry) => entry.url === servers.state?.activeUrl) ??
+    null;
+  useOnClickOutside(serverPanelRef, () => setServerPanelOpen(false));
+
   const hasSessionActions = Boolean(
     sessionActions && (sessionActions.onRename || sessionActions.onRenameWithAi || sessionActions.onArchive || sessionActions.onDelete)
   );
   return (
-    <header 
+    <header
       className="h-10 flex-shrink-0 border-b border-ink/10 bg-paper flex items-center justify-between z-20 titlebar-drag-region select-none"
+      {...dragRegionProps()}
       style={{
         // The sidebar's own header carries the left inset while it is open.
-        paddingLeft: !showLeftPanel ? titlebarPaddingLeft('1rem') : undefined,
+        paddingLeft: !showLeftPanel ? titlebarInsetLeft(titlebarPaddingLeft('1rem')) : undefined,
         paddingRight: titlebarPaddingRight('1rem'),
       }}
     >
@@ -142,6 +163,37 @@ export function TopNavbar({
       <div className="flex items-center space-x-3 titlebar-no-drag">
         {/* One cluster, one order, shared with the phone's header. Each layout
             passes only what it has; the order is stated in `HeaderControls`. */}
+        {shell && (
+          <div className="relative" ref={serverPanelRef}>
+            <button
+              type="button"
+              onClick={() => setServerPanelOpen((open) => !open)}
+              title={
+                activeServer
+                  ? `Server: ${activeServer.label} — ${activeServer.running ? 'running' : 'stopped'}`
+                  : 'Choose a server'
+              }
+              aria-label="Servers"
+              aria-haspopup="dialog"
+              aria-expanded={serverPanelOpen}
+              className="flex items-center gap-1.5 rounded px-1.5 py-1 text-ink/60 hover:text-ink hover:bg-ink/10 transition-colors cursor-pointer"
+            >
+              <ServerCog size={16} />
+              {activeServer && (
+                <span className="max-w-[120px] truncate text-[11px] font-medium text-ink/70">
+                  {activeServer.label}
+                </span>
+              )}
+              <span
+                className={`w-1.5 h-1.5 rounded-full ${
+                  activeServer?.running ? 'bg-success' : 'bg-ink/25'
+                }`}
+                aria-hidden="true"
+              />
+            </button>
+            <ServerSwitcher open={serverPanelOpen} onClose={() => setServerPanelOpen(false)} />
+          </div>
+        )}
         <HeaderControls
           layout="desktop"
           sessionId={sessionId ?? null}
@@ -151,6 +203,10 @@ export function TopNavbar({
           onToggleEditor={onToggleEditor}
           onSwitchToMobile={onSwitchToMobile}
         />
+        {/* The Windows shell is borderless and its webview is an HWND, so the
+            system's caption buttons cannot be drawn over it — the page owns
+            them there. Absent on macOS, whose traffic lights are the system's. */}
+        {drawsWindowControls() && <WindowControls />}
       </div>
 
       {menu.anchor && sessionActions && (

package/src/client/components/layout/desktop-layout/index.tsx

@@ -16,13 +16,13 @@ import { useSidebarData } from '@/client/hooks/chat/omp/session-list';
 import { MIN_LEFT_PANEL_WIDTH } from '@/shared/lib/workspace/sidebar-width';
 import { MIN_LEFT_DOCK_PLUGIN_WIDTH } from '@/shared/lib/workspace/left-dock-width';
 import { SESSIONS_VIEW_ID } from '@/shared/lib/workspace/left-dock';
+import { useOpenPanelRequest } from '@/client/hooks/workspace/open-panel';
 import { useLeftDock, useLeftDockWidth } from '@/client/hooks/workspace/left-dock';
 import { useLeftDockView } from '@/client/components/workspace/plugin-panel/catalog';
 import type { EditorWidthMode } from '@/shared/lib/workspace/panel-widths';
-import { useKabmoEvent, useWindowEvent } from '@/client/hooks/ui/window-event';
+import { useKabmoEvent } from '@/client/hooks/ui/window-event';
+import { useWorkspaceKeybindings } from '@/client/hooks/workspace/keybindings';
 import { PluginBootstrap } from '@/client/lib/plugins/bootstrap';
-import { WORKSPACE_KEY_BINDINGS } from '@/shared/lib/workspace/keymap';
-import { resolveBinding } from '@/shared/lib/ui/key-binding';
 import { useToasts } from '@/client/hooks/ui/toasts';
 import type { EditorDropResult } from '@/client/hooks/editor/use-editor-drop';
 import { ToastStack } from '@/client/components/common/ToastStack';
@@ -158,32 +158,20 @@ export function DesktopLayout({ sessionId, onSwitchToMobile, appSettings = {} }:
       }
     : undefined;
 
-  /**
-   * The workspace shortcuts, from the shared keymap so the toggles' tooltips
-   * name the bound chord. `⌘S` is absent: the editor owns it, and binding it
-   * twice would save the file twice.
-   */
-  useWindowEvent('keydown', (e) => {
-    const command = resolveBinding(WORKSPACE_KEY_BINDINGS, e);
-    if (!command) return;
-    if (command === 'saveFile') return;
-    if (command === 'toggleEditorPanel' && !showEditor) {
-      // The editor panel needs something to show — a file or a takeover — and
-      // `showEditor` already folds in the user's own toggle.
-      // The toggle is also the only way to REACH a takeover while the column is
-      // closed, since the rail lives inside the column: with no file and no
-      // takeover there would be nothing to open on to, and with one there is.
-      if (openedFiles.length === 0 && !activeEditorPanelKey && editorTakeovers.length === 0) return;
-    }
-    e.preventDefault();
-    if (command === 'toggleSidebar') setShowLeftPanel((previous) => !previous);
-    else if (command === 'toggleEditorPanel') setUserToggledEditor((previous) => !(previous ?? showEditor));
-    else if (command === 'toggleRightPanel') setShowRightPanel((previous) => !previous);
-    else if (command === 'openSettings') {
+  // The workspace shortcuts, from the shared keymap so the toggles' tooltips
+  // name the bound chord. `⌘S` is absent: the editor owns it, and binding it
+  // twice would save the file twice.
+  useWorkspaceKeybindings({
+    showEditor,
+    editorHasContent,
+    toggleSidebar: () => setShowLeftPanel((previous) => !previous),
+    toggleEditor: () => setUserToggledEditor((previous) => !(previous ?? showEditor)),
+    toggleRightPanel: () => setShowRightPanel((previous) => !previous),
+    openSettings: () => {
       setSettingsCategory('appearance');
       setAutoOpenAddProvider(false);
       setSettingsOpen((previous) => !previous);
-    }
+    },
   });
 
   // Global event listener for settings triggers
@@ -210,6 +198,26 @@ export function DesktopLayout({ sessionId, onSwitchToMobile, appSettings = {} }:
   const handleToggleRightPanel = () => setShowRightPanel(!showRightPanel);
   const handleToggleEditor = () => setUserToggledEditor(!showEditor);
 
+  // A panel asked to be shown from somewhere that is not its own rail — a
+  // plugin's navbar readout (`app.headerPanel({ opensPanel })`). Where it lives
+  // is the USER's placement, so the handler resolves the column from the dock
+  // state and opens it; see `useOpenPanelRequest`.
+  useOpenPanelRequest({
+    dock,
+    onLeft: (panelKey) => {
+      setActiveLeftView(panelKey);
+      setShowLeftPanel(true);
+    },
+    onEditor: (panelKey) => {
+      setActiveEditorPanelKey(panelKey);
+      setUserToggledEditor(true);
+    },
+    onRight: (panelKey) => {
+      setActiveRightPanel(panelKey);
+      setShowRightPanel(true);
+    },
+  });
+
   return (
     <div
       data-testid="app-root"

package/src/client/components/layout/session-sidebar/Footer.tsx

@@ -1,16 +1,16 @@
 import { Download, Info, Settings } from 'lucide-preact';
 import {
-  androidDownloadLabel,
-  type AndroidDownload,
-} from '@/client/hooks/ui/updates/android-download';
+  shellDownloadLabel,
+  type ShellDownload,
+} from '@/client/hooks/ui/updates/shell-download';
 
 interface SessionSidebarFooterProps {
   onSettings: () => void;
   onInfo: () => void;
   updateAvailable?: boolean;
   onUpdateClick?: () => void;
-  /** The APK to offer, or null. Set inside the app (an update) or on an Android browser (an install). */
-  androidDownload?: AndroidDownload | null;
+  /** The native-shell artifact to offer, or null. Set inside a shell (an update) or on an Android browser (an install). */
+  shellDownload?: ShellDownload | null;
 }
 
 /**
@@ -23,7 +23,7 @@ interface SessionSidebarFooterProps {
  * is unreachable by keyboard"). It is also what lets a browser spec address
  * these controls by role and name instead of by their position in the DOM.
  */
-export function SessionSidebarFooter({ onSettings, onInfo, updateAvailable, onUpdateClick, androidDownload }: SessionSidebarFooterProps) {
+export function SessionSidebarFooter({ onSettings, onInfo, updateAvailable, onUpdateClick, shellDownload }: SessionSidebarFooterProps) {
   return (
     <div className="h-10 px-3 border-t border-ink/10 flex items-center justify-between text-ink/60 shrink-0">
       <div className="flex space-x-1">
@@ -45,17 +45,17 @@ export function SessionSidebarFooter({ onSettings, onInfo, updateAvailable, onUp
         >
           <Info size={16} />
         </button>
-        {androidDownload && (
+        {shellDownload && (
           // Next to About. Two reasons to be here, and the label says which:
-          // an installed APK that is behind (an update), or an Android browser
+          // an installed shell that is behind (an update), or an Android browser
           // whose reader may not know the shell exists (an install). A desktop
-          // browser gets neither — see `useAndroidDownload`.
+          // browser and an iOS browser get neither — see `useShellDownload`.
           <a
-            href={androidDownload.url}
+            href={shellDownload.url}
             target="_blank"
             rel="noopener noreferrer"
-            title={androidDownloadLabel(androidDownload)}
-            aria-label={androidDownloadLabel(androidDownload)}
+            title={shellDownloadLabel(shellDownload)}
+            aria-label={shellDownloadLabel(shellDownload)}
             className="p-1 rounded hover:text-ink hover:bg-ink/5 cursor-pointer transition-colors"
           >
             <Download size={16} />

package/src/client/components/layout/session-sidebar/Header.tsx

@@ -3,6 +3,7 @@ import { BrandWordmark } from '@/client/components/common/brand-wordmark';
 import { StreamStatusDot } from '@/client/components/common/StreamStatusDot';
 import { withChord } from '@/client/lib/ui/with-chord';
 import { titlebarPaddingLeft } from '@/shared/lib/ui/titlebar';
+import { dragRegionProps, titlebarInsetLeft } from '@/client/lib/desktop/titlebar';
 import type { AgentStreamStatus } from '@/shared/lib/chat/omp/status';
 
 /**
@@ -28,9 +29,10 @@ export function SessionSidebarHeader({
 }) {
   const label = withChord('toggleSidebar', 'Collapse Sidebar');
   return (
-    <div 
+    <div
       className="h-10 flex-shrink-0 flex items-center justify-between px-4 border-b border-ink/10 titlebar-drag-region select-none"
-      style={{ paddingLeft: titlebarPaddingLeft('1rem') }}
+      {...dragRegionProps()}
+      style={{ paddingLeft: titlebarInsetLeft(titlebarPaddingLeft('1rem')) }}
     >
       {/* The stream indicator badges the wordmark's top-right corner, the
           same placement the phone's header uses — it reads as part of the

package/src/client/components/mobile/LayoutWrapper.tsx

@@ -20,6 +20,10 @@ import { useEditorDrop, type EditorDropResult } from '@/client/hooks/editor/use-
 import { EditorDropOverlay } from '@/client/components/workspace/editor/EditorDropOverlay';
 import { PluginBootstrap } from '@/client/lib/plugins/bootstrap';
 import { mobileEditorFileFrom, type MobileEditorFile } from '@/client/components/mobile/open-file-payload';
+import { useLeftDock } from '@/client/hooks/workspace/left-dock';
+import { useSessionStateContext } from '@/client/hooks/workspace/session-state/context';
+import { setSessionKey } from '@/shared/lib/workspace/session-state/store';
+import { OPEN_PANEL_EVENT, phoneDrawerForPanel, type OpenPanelDetail } from '@/shared/lib/workspace/panel-open';
 
 interface MobileLayoutWrapperProps {
   onDesktopToggle?: () => void;
@@ -30,6 +34,11 @@ export type MobileScreen = 'main' | 'session' | 'right';
 
 export function MobileLayoutWrapper({ onDesktopToggle, appSettings = {} }: MobileLayoutWrapperProps) {
   const { folders } = useSidebarData();
+  // The placement state the panel-open event resolves against, and the session
+  // the tab it writes belongs to — read once here rather than per drawer,
+  // because the drawer that receives the selection is not mounted yet.
+  const dock = useLeftDock();
+  const { sessionId: stateSessionId } = useSessionStateContext();
   const [searchParams, setSearchParams] = useSearchParams();
   const sessionParam = searchParams.get('sessionId');
   const sessionId = sessionParam ? (Number.isNaN(Number(sessionParam)) ? sessionParam : Number(sessionParam)) : null;
@@ -135,6 +144,33 @@ export function MobileLayoutWrapper({ onDesktopToggle, appSettings = {} }: Mobil
   // transcript opens behind the drawer and the tap reads as a no-op.
   useKabmoEvent('omp:view-subagent', () => setCurrentScreen('main'));
 
+  /**
+   * A plugin's navbar readout asking for its own panel.
+   *
+   * A phone has no rail, so "show this panel" is two decisions: which DRAWER can
+   * reach it, and which chip inside that drawer is the view. Both are answered
+   * from the placement state (`phoneDrawerForPanel`), never from the panel's
+   * slot — a panel placed on the left is drawn by the RIGHT drawer while the
+   * rail is off, and naming the drawer from the slot would open one that does
+   * not list it.
+   *
+   * The tab is written through the session store rather than through a prop:
+   * the drawer mounts on this screen change and reads the stored tab, so the
+   * selection has to be in the store before it mounts. An `editor`-slot
+   * takeover resolves to null — the phone has no editor column — and the click
+   * then does nothing rather than opening a drawer that cannot show it.
+   */
+  useKabmoEvent(OPEN_PANEL_EVENT, (event) => {
+    const panelKey = (event as CustomEvent<OpenPanelDetail>).detail?.panelKey;
+    if (!panelKey) return;
+    const drawer = phoneDrawerForPanel(panelKey, dock);
+    if (!drawer) return;
+    // The phone's two drawers are SCREENS, not columns: the session screen
+    // draws the left dock and the right screen draws the panel drawer.
+    setSessionKey(stateSessionId, drawer === 'left' ? 'layout.mobileLeftPanel' : 'layout.mobileRightPanel', panelKey);
+    setCurrentScreen(drawer === 'left' ? 'session' : 'right');
+  });
+
   // Settings requests (e.g. the model dropdown asking for Settings → Providers
   // when no provider is configured) arrive on the same global channel the
   // desktop layout listens on. SettingsModal itself only reads the payload and

package/src/client/components/mobile/RightSidebar.tsx

@@ -4,7 +4,7 @@ import { usePanelCatalog, type PanelBodyProps } from '@/client/components/worksp
 import { PanelHostProvider } from '@kabmo-labs/kabmo-ui';
 import { useGitStatus } from '@/client/hooks/workspace/git-status';
 import { useResolvedRepo } from '@/client/hooks/workspace/repo-scope';
-import { useSessionState } from '@/client/hooks/workspace/session-state';
+import { useSharedSessionState } from '@/client/hooks/workspace/session-state';
 import { useLeftDock } from '@/client/hooks/workspace/left-dock';
 import { SESSIONS_VIEW_ID } from '@/shared/lib/workspace/left-dock';
 import { phoneRightPanels } from '@/shared/lib/workspace/mobile-dock';
@@ -45,7 +45,7 @@ export function MobileRightSidebar({
   // back on the Search view re-ran a query that can hold thousands of hits, and
   // the user never asked for a search. Restoring the tab they left also keeps
   // the phone and the desktop on the same view.
-  const [activeTab, setActiveTab] = useSessionState<string>('layout.mobileRightPanel', 'files');
+  const [activeTab, setActiveTab] = useSharedSessionState<string>('layout.mobileRightPanel', 'files');
   // ONE catalog, the same one the desktop bars read, and deliberately `all`:
   // a phone has ONE drawer, so a plugin panel the user placed on the left must
   // stay reachable here — reading only the right column would make placing a

package/src/client/components/mobile/SessionSidebar.tsx

@@ -3,7 +3,7 @@ import { MobileSessionHeader } from '@/client/components/mobile/mobile-session-s
 import { MobileSessionToolbar } from '@/client/components/mobile/mobile-session-sidebar/Toolbar';
 import { MobileSessionList } from '@/client/components/mobile/mobile-session-sidebar/List';
 import { MobileSessionFooter } from '@/client/components/mobile/mobile-session-sidebar/Footer';
-import { useAndroidDownload } from '@/client/hooks/ui/updates/android-download';
+import { useShellOffer } from '@/client/hooks/ui/updates/shell-download';
 import { useOnClickOutside } from '@/client/hooks/ui/on-click-outside';
 import { useKabmoEvent } from '@/client/hooks/ui/window-event';
 import { useToasts } from '@/client/hooks/ui/toasts';
@@ -83,12 +83,9 @@ export function MobileSessionSidebar({
   const scheduledCount = useScheduledTaskCount();
   const [aboutOpen, setAboutOpen] = useState(false);
   const updates = useUpdates();
-  // An update inside the APK, an install on an Android browser, nothing
-  // elsewhere — see `useAndroidDownload`.
-  const androidDownload = useAndroidDownload(
-    window.__OMP_BOOTSTRAP__?.shellVersion,
-    window.__OMP_BOOTSTRAP__?.isAndroid,
-  );
+  // An update inside a native shell, an install on an Android browser, nothing
+  // elsewhere — see `useShellOffer`.
+  const shellDownload = useShellOffer();
   const { toasts, pushToast, dismissToast } = useToasts();
   const cancelWait = useCancelWait(pushToast);
   useWaitingDispatch({ onNotice: pushToast });
@@ -298,7 +295,7 @@ export function MobileSessionSidebar({
       <MobileSessionFooter
         onSettings={() => window.dispatchEvent(new CustomEvent('omp:open-settings', { detail: {} }))}
         onAbout={() => setAboutOpen(true)}
-        androidDownload={androidDownload}
+        shellDownload={shellDownload}
         onDesktopToggle={onDesktopToggle}
         updateAvailable={updates.hasUpdate}
         onUpdateClick={() => {

package/src/client/components/mobile/mobile-session-sidebar/Footer.tsx

@@ -1,17 +1,18 @@
 import { Download, Info, Monitor, Settings } from 'lucide-preact';
 import packageJson from '@/../package.json';
 import {
-  androidDownloadLabel,
-  type AndroidDownload,
-} from '@/client/hooks/ui/updates/android-download';
+  shellDownloadLabel,
+  shellDownloadShortLabel,
+  type ShellDownload,
+} from '@/client/hooks/ui/updates/shell-download';
 
 interface MobileSessionFooterProps {
   onSettings: () => void;
   onAbout: () => void;
   updateAvailable?: boolean;
   onUpdateClick?: () => void;
-  /** The APK to offer, or null. Set inside the app (an update) or on an Android browser (an install). */
-  androidDownload?: AndroidDownload | null;
+  /** The native-shell artifact to offer, or null. Set inside a shell (an update) or on an Android browser (an install). */
+  shellDownload?: ShellDownload | null;
   /** Switch the app to the desktop layout for this page session only. The
    *  choice is not persisted, so the next load re-detects the device. */
   onDesktopToggle?: () => void;
@@ -23,7 +24,7 @@ export function MobileSessionFooter({
   updateAvailable,
   onUpdateClick,
   onDesktopToggle,
-  androidDownload,
+  shellDownload,
 }: MobileSessionFooterProps) {
   return (
     <div
@@ -47,7 +48,7 @@ export function MobileSessionFooter({
           <Info size={14} />
           <span>About</span>
         </button>
-        {androidDownload && (
+        {shellDownload && (
           // Directly after About, matching the desktop footer. An `<a>`, not a
           // button: the download is the browser's (or the WebView's) job, and
           // `target="_blank"` hands it to the system browser so the console is
@@ -55,17 +56,19 @@ export function MobileSessionFooter({
           //
           // The visible word is the OFFER, not the file type: `APK` told a
           // reader what the bytes are but not what the control does, and on a
-          // browser it is the only place the native shell is ever mentioned.
+          // browser it is the only place the native shell is ever mentioned. An
+          // iOS update is an IPA, so the word names the platform instead of a
+          // file extension.
           <a
-            href={androidDownload.url}
+            href={shellDownload.url}
             target="_blank"
             rel="noopener noreferrer"
-            title={androidDownloadLabel(androidDownload)}
-            aria-label={androidDownloadLabel(androidDownload)}
+            title={shellDownloadLabel(shellDownload)}
+            aria-label={shellDownloadLabel(shellDownload)}
             className="flex items-center space-x-1 hover:text-ink transition-colors"
           >
             <Download size={14} />
-            <span>{androidDownload.kind === 'update' ? 'Update APK' : 'Get APK'}</span>
+            <span>{shellDownloadShortLabel(shellDownload)}</span>
           </a>
         )}
         {onDesktopToggle && (