@kabmo-labs/kabmo 0.5.2 → 0.6.0

package/src/client/hooks/settings/model-roles.ts

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Model-role state for the OMP Engine panel: the live `modelRoles` map, the
+ * stored presets, and the catalog the role dropdowns offer.
+ *
+ * Extracted from `OmpSettings` because it is a self-contained store with its own
+ * three writes, and because the panel file was crossing the per-file ceiling.
+ * The load is still driven by the panel (it fetches everything in one
+ * `Promise.all` so a single spinner covers the whole screen), so this hook
+ * exposes `applyPayload` for that fetch and `reload` for a standalone refresh.
+ *
+ * Every write answers with the WHOLE list/map from the server and is adopted
+ * verbatim: the route normalizes (blank selectors dropped, the map written
+ * whole), so the panel shows what config.yml and the table actually hold rather
+ * than an optimistic guess that can drift.
+ */
+
+import { useCallback, useState } from 'preact/hooks';
+import type { ModelRoleCandidate, ModelRolePreset } from '@/shared/types/model-roles';
+
+export interface ModelRoleState {
+  roles: Record<string, string>;
+  presets: ModelRolePreset[];
+  candidates: ModelRoleCandidate[];
+  candidatesError: string | null;
+  /** The last write's refusal (omp's or the table's own sentence), cleared on the next write. */
+  writeError: string | null;
+  clearWriteError: () => void;
+  /** Adopt the `GET /api/model-roles` payload (the panel's combined load). */
+  applyPayload: (data: unknown) => void;
+  /** Replace the whole map — a single role edit and applying a preset both. */
+  writeRoles: (roles: Record<string, string>) => Promise<boolean>;
+  savePreset: (name: string, roles: Record<string, string>) => Promise<boolean>;
+  updatePreset: (preset: ModelRolePreset) => Promise<boolean>;
+  deletePreset: (preset: ModelRolePreset) => Promise<boolean>;
+}
+
+function readRoles(data: unknown): Record<string, string> | null {
+  if (typeof data !== 'object' || data === null || !('roles' in data)) return null;
+  const roles = data.roles;
+  if (typeof roles !== 'object' || roles === null || Array.isArray(roles)) return null;
+  return Object.fromEntries(
+    Object.entries(roles).filter((entry): entry is [string, string] => typeof entry[1] === 'string'),
+  );
+}
+
+/** The server's own refusal sentence, when the payload carries one. */
+function errorText(data: unknown): string | null {
+  if (typeof data !== 'object' || data === null || !('error' in data)) return null;
+  return typeof data.error === 'string' ? data.error : null;
+}
+
+export function useModelRoles(onSaved: (key: string) => void): ModelRoleState {
+  const [roles, setRoles] = useState<Record<string, string>>({});
+  const [presets, setPresets] = useState<ModelRolePreset[]>([]);
+  const [candidates, setCandidates] = useState<ModelRoleCandidate[]>([]);
+  const [candidatesError, setCandidatesError] = useState<string | null>(null);
+  const [writeError, setWriteError] = useState<string | null>(null);
+
+  const clearWriteError = useCallback(() => setWriteError(null), []);
+
+  const applyPayload = useCallback((data: unknown) => {
+    const nextRoles = readRoles(data);
+    if (nextRoles) setRoles(nextRoles);
+    if (typeof data !== 'object' || data === null) return;
+    if ('presets' in data && Array.isArray(data.presets)) setPresets(data.presets as ModelRolePreset[]);
+    if ('candidates' in data && Array.isArray(data.candidates)) setCandidates(data.candidates as ModelRoleCandidate[]);
+    if ('candidatesError' in data) {
+      setCandidatesError(typeof data.candidatesError === 'string' ? data.candidatesError : null);
+    }
+  }, []);
+
+  const writeRoles = useCallback(async (next: Record<string, string>): Promise<boolean> => {
+    // The previous map, so a refusal puts the rows back: leaving the optimistic
+    // draft on screen after config.yml rejected it would show a role assignment
+    // that does not exist, and the next edit would build on it.
+    const previous = roles;
+    setRoles(next);
+    setWriteError(null);
+    try {
+      const res = await fetch('/api/model-roles', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ roles: next }),
+      });
+      const data: unknown = await res.json();
+      const stored = readRoles(data);
+      if (stored) setRoles(stored);
+      const ok = typeof data === 'object' && data !== null && 'success' in data && data.success === true;
+      if (ok) onSaved('role-map');
+      else {
+        setRoles(previous);
+        setWriteError(errorText(data) ?? 'The role write was refused');
+      }
+      return ok;
+    } catch (err) {
+      console.error('Failed to save model roles:', err);
+      setRoles(previous);
+      setWriteError(err instanceof Error ? err.message : String(err));
+      return false;
+    }
+  }, [onSaved, roles]);
+
+  /** Save/update/delete a preset; every answer carries the whole preset list. */
+  const writePreset = useCallback(async (init: RequestInit, query = ''): Promise<boolean> => {
+    setWriteError(null);
+    try {
+      const res = await fetch(`/api/model-roles${query}`, init);
+      const data: unknown = await res.json();
+      if (typeof data === 'object' && data !== null && 'presets' in data && Array.isArray(data.presets)) {
+        setPresets(data.presets as ModelRolePreset[]);
+      }
+      const ok = typeof data === 'object' && data !== null && 'success' in data && data.success === true;
+      if (!ok) setWriteError(errorText(data) ?? 'The preset write was refused');
+      return ok;
+    } catch (err) {
+      console.error('Failed to save model role preset:', err);
+      setWriteError(err instanceof Error ? err.message : String(err));
+      return false;
+    }
+  }, []);
+
+  const savePreset = useCallback((name: string, map: Record<string, string>) => writePreset({
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ preset: { name, roles: map } }),
+  }), [writePreset]);
+
+  const updatePreset = useCallback((preset: ModelRolePreset) => writePreset({
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ preset: { id: preset.id, name: preset.name, roles: preset.roles } }),
+  }), [writePreset]);
+
+  const deletePreset = useCallback((preset: ModelRolePreset) => writePreset({
+    method: 'DELETE',
+  }, `?id=${encodeURIComponent(preset.id)}`), [writePreset]);
+
+  return {
+    roles,
+    presets,
+    candidates,
+    candidatesError,
+    writeError,
+    clearWriteError,
+    applyPayload,
+    writeRoles,
+    savePreset,
+    updatePreset,
+    deletePreset,
+  };
+}

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

@@ -0,0 +1,157 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  parseShellRelease,
+  shellDownloadLabel,
+  shellFromBootstrap,
+  shellReleasePath,
+  shouldOfferShellDownload,
+  type ShellDownload,
+} from '@/client/hooks/ui/updates/shell-download';
+
+/** The published release every case compares against. */
+const RELEASE = {
+  url: 'https://github.com/kabmo-labs/kabmo/releases/download/v1.2.3/kabmo-android-v1.2.3.apk',
+  latest: '1.2.3',
+  releaseUrl: 'https://github.com/kabmo-labs/kabmo/releases/tag/v1.2.3',
+};
+
+const UPDATE: ShellDownload = { ...RELEASE, kind: 'update', platform: 'android' };
+const INSTALL: ShellDownload = { ...RELEASE, kind: 'install', platform: 'android' };
+
+describe('parseShellRelease', () => {
+  test('reads a complete payload', () => {
+    expect(parseShellRelease(RELEASE)).toEqual(RELEASE);
+  });
+
+  test('refuses a payload with no artifact', () => {
+    // The route answers this on a failed probe. A version without a URL would be
+    // a button that downloads nothing.
+    expect(parseShellRelease({ url: null, latest: '1.2.3', releaseUrl: null })).toBeNull();
+    expect(parseShellRelease({ url: 'https://x/a.apk', latest: null, releaseUrl: null })).toBeNull();
+  });
+
+  test('refuses a non-object', () => {
+    expect(parseShellRelease(null)).toBeNull();
+    expect(parseShellRelease('nope')).toBeNull();
+    expect(parseShellRelease({})).toBeNull();
+  });
+
+  test('keeps a missing releaseUrl as null', () => {
+    expect(parseShellRelease({ url: 'https://x/a.apk', latest: '1.0.0' })?.releaseUrl).toBeNull();
+  });
+});
+
+describe('the offer inside the installed shell', () => {
+  test('offers an UPDATE when a newer build is published', () => {
+    expect(shouldOfferShellDownload('android', '1.2.2', true, RELEASE)).toEqual(UPDATE);
+    expect(shouldOfferShellDownload('ios', '1.2.2', null, RELEASE)).toEqual({
+      ...RELEASE,
+      kind: 'update',
+      platform: 'ios',
+    });
+  });
+
+  test('offers nothing when the shell is already current', () => {
+    expect(shouldOfferShellDownload('android', '1.2.3', true, RELEASE)).toBeNull();
+    expect(shouldOfferShellDownload('ios', '1.2.3', null, RELEASE)).toBeNull();
+  });
+
+  test('offers nothing when the shell is ahead', () => {
+    // A sideloaded build newer than the published asset: downloading it would be
+    // a downgrade.
+    expect(shouldOfferShellDownload('android', '1.3.0', true, RELEASE)).toBeNull();
+  });
+
+  test('offers nothing when the probe failed', () => {
+    expect(shouldOfferShellDownload('android', '1.0.0', true, null)).toBeNull();
+  });
+});
+
+describe('the offer to an Android browser', () => {
+  test('offers an INSTALL, because there is no installed version to compare', () => {
+    // The reported gap: a reader on Chrome or Brave for Android was told
+    // nothing, and the shell is exactly what they do not know exists.
+    expect(shouldOfferShellDownload('android', null, true, RELEASE)).toEqual(INSTALL);
+  });
+
+  test('offers an install even when the published APK is older than some build', () => {
+    // Nothing is installed here, so "newer than" has no left-hand side — the
+    // published asset is simply what the button names.
+    expect(shouldOfferShellDownload('android', undefined, true, { ...RELEASE, latest: '0.0.1' })).toEqual({
+      ...INSTALL,
+      latest: '0.0.1',
+    });
+  });
+
+  test('offers nothing when no APK is published', () => {
+    expect(shouldOfferShellDownload('android', null, true, null)).toBeNull();
+  });
+
+  test('an iOS browser is offered nothing, because an IPA cannot be installed there', () => {
+    // iOS has no sideload-by-URL path. Offering a download to a Safari tab on an
+    // iPhone would be a button that cannot do what it says.
+    expect(shouldOfferShellDownload('ios', null, true, RELEASE)).toBeNull();
+    expect(shouldOfferShellDownload('ios', undefined, undefined, RELEASE)).toBeNull();
+  });
+});
+
+describe('everywhere else', () => {
+  test('a desktop browser is offered nothing', () => {
+    // An APK cannot be installed there, and the app's own update badge already
+    // covers the server.
+    expect(shouldOfferShellDownload('android', null, false, RELEASE)).toBeNull();
+    expect(shouldOfferShellDownload('android', null, null, RELEASE)).toBeNull();
+    expect(shouldOfferShellDownload('android', null, undefined, RELEASE)).toBeNull();
+    expect(shouldOfferShellDownload('android', '', false, RELEASE)).toBeNull();
+  });
+
+  test('the shell token alone is enough, even if the wider flag is missing', () => {
+    // `isAndroid` is derived from the same UA, so a stale bootstrap that predates
+    // the field must not silently drop the update offer.
+    expect(shouldOfferShellDownload('android', '1.2.2', false, RELEASE)).toEqual(UPDATE);
+    expect(shouldOfferShellDownload('android', '1.2.2', undefined, RELEASE)).toEqual(UPDATE);
+  });
+});
+
+describe('shellDownloadLabel', () => {
+  test('names the verb the reader needs, and the platform', () => {
+    expect(shellDownloadLabel(UPDATE)).toBe('Update Kabmo 1.2.3 for Android');
+    expect(shellDownloadLabel(INSTALL)).toBe('Install Kabmo 1.2.3 for Android');
+    expect(shellDownloadLabel({ ...UPDATE, platform: 'ios' })).toBe('Update Kabmo 1.2.3 for iOS');
+  });
+});
+
+describe('shellFromBootstrap', () => {
+  test('reads whichever token the request carried', () => {
+    expect(shellFromBootstrap({ shellVersion: '0.5.0' })).toEqual({ platform: 'android', version: '0.5.0' });
+    expect(shellFromBootstrap({ iosShellVersion: '0.1.0' })).toEqual({ platform: 'ios', version: '0.1.0' });
+  });
+
+  test('is null in a browser, and for an absent bootstrap', () => {
+    expect(shellFromBootstrap({ shellVersion: null, iosShellVersion: null })).toBeNull();
+    expect(shellFromBootstrap({})).toBeNull();
+    expect(shellFromBootstrap(undefined)).toBeNull();
+  });
+
+  test('prefers the Android token when both are present', () => {
+    // A UA carrying both is crafted rather than observed; one shell has to win,
+    // and the one whose platform also has a browser offer is the safer answer.
+    expect(shellFromBootstrap({ shellVersion: '0.5.0', iosShellVersion: '0.1.0' })).toEqual({
+      platform: 'android',
+      version: '0.5.0',
+    });
+  });
+});
+
+describe('shellReleasePath', () => {
+  test('is one endpoint per shell', () => {
+    expect(shellReleasePath('android')).toBe('/api/updates/android');
+    expect(shellReleasePath('ios')).toBe('/api/updates/ios');
+  });
+});

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

@@ -0,0 +1,220 @@
+/**
+ * What the sidebar should offer for a native shell, and why.
+ *
+ * TWO DIFFERENT OFFERS, from two different facts:
+ *
+ * - **`update`** — this page is running inside the shell (`shellVersion` from
+ *   the bootstrap) and a newer build is published. An up-to-date shell offers
+ *   nothing: a button that downloads the build already installed is worse than
+ *   no button.
+ * - **`install`** — this page is an Android BROWSER (Chrome, Brave, Firefox) and
+ *   an APK is published. The reader may not know a native shell exists, and
+ *   telling them is the whole point of the offer; there is no installed version
+ *   to compare against, so the newest published one is what it names.
+ *
+ * There is NO iOS install offer. An IPA cannot be installed from a page the way
+ * an APK can — iOS has no sideload-by-URL path — so a browser on an iPhone is
+ * offered nothing, and only an installed iOS shell ever sees this control.
+ *
+ * A desktop browser gets neither: an APK cannot be installed there, and the
+ * app's own update badge already covers the server.
+ *
+ * The probe is lazy: it runs only when a shell token or an Android device is
+ * present, so a console that can never show the button makes no request for it.
+ * ONE hook for both shells, because the decision table is identical and only the
+ * artifact, the endpoint and the platform word differ.
+ */
+
+import { useEffect, useState } from 'preact/hooks';
+import { isNewer } from '@/shared/lib/updates/semver';
+import type { ShellKind } from '@/shared/lib/updates/shell-ua';
+
+/** Which shell the offer is for. */
+export type ShellPlatform = ShellKind;
+
+/** Which offer this is — the two carry different wording. */
+export type ShellOfferKind = 'update' | 'install';
+
+export interface ShellDownload {
+  /** The artifact to download. */
+  url: string;
+  /** The version that artifact ships. */
+  latest: string;
+  /** The release page, for a "what changed" link. */
+  releaseUrl: string | null;
+  /** An update to an installed shell, or a first install from a browser. */
+  kind: ShellOfferKind;
+  /** Which shell this offer is for. */
+  platform: ShellPlatform;
+}
+
+interface ReleasePayload {
+  url?: unknown;
+  latest?: unknown;
+  releaseUrl?: unknown;
+}
+
+/** The platform's own name, as the label says it. */
+const PLATFORM_NAMES: Record<ShellPlatform, string> = {
+  android: 'Android',
+  ios: 'iOS',
+};
+
+/**
+ * Read the release payload defensively.
+ *
+ * The route answers `{url: null, latest: null, releaseUrl: null}` on a failed
+ * probe, so a shape check that only looks at the version would offer a button
+ * with no link.
+ */
+export function parseShellRelease(payload: unknown): Omit<ShellDownload, 'kind' | 'platform'> | null {
+  if (typeof payload !== 'object' || payload === null) return null;
+  const body = payload as ReleasePayload;
+  if (typeof body.url !== 'string' || !body.url) return null;
+  if (typeof body.latest !== 'string' || !body.latest) return null;
+  return {
+    url: body.url,
+    latest: body.latest,
+    releaseUrl: typeof body.releaseUrl === 'string' ? body.releaseUrl : null,
+  };
+}
+
+/**
+ * The offer, or null.
+ *
+ * `version` is null in every browser — that is what makes the two branches
+ * mutually exclusive — and `onAndroid` is the wider fact that admits a browser
+ * ON ANDROID. Both come from the bootstrap rather than a client-side UA sniff:
+ * the server already parsed them for the very request that served the page.
+ *
+ * An `install` needs no version comparison, because nothing is installed. It
+ * does require a published artifact: `release` being null is a failed probe, and
+ * a button the console cannot back with a link must not appear.
+ */
+export function shouldOfferShellDownload(
+  platform: ShellPlatform,
+  version: string | null | undefined,
+  onAndroid: boolean | null | undefined,
+  release: Omit<ShellDownload, 'kind' | 'platform'> | null,
+): ShellDownload | null {
+  if (!release) return null;
+
+  // Inside the shell: an update, and only when one exists.
+  if (version) {
+    return isNewer(release.latest, version) ? { ...release, kind: 'update', platform } : null;
+  }
+
+  // A browser on an Android device: the app is something to install. iOS has no
+  // equivalent — an IPA cannot be installed from a page — so the platform is
+  // part of this test, not only the label.
+  if (platform === 'android' && onAndroid) return { ...release, kind: 'install', platform };
+
+  return null;
+}
+
+/**
+ * The wording of the offer, in one place.
+ *
+ * Both layouts draw this control and they must say the same thing: an installed
+ * shell that is behind is an UPDATE, and a browser on Android is an INSTALL —
+ * "Download" for both would leave a first-time reader unsure whether they
+ * already have the app. The version is in the label because the artifact is a
+ * specific build, not "the app".
+ */
+export function shellDownloadLabel(download: ShellDownload): string {
+  const verb = download.kind === 'update' ? 'Update' : 'Install';
+  return `${verb} Kabmo ${download.latest} for ${PLATFORM_NAMES[download.platform]}`;
+}
+
+/** The endpoint that answers for one shell. */
+export function shellReleasePath(platform: ShellPlatform): string {
+  return `/api/updates/${platform}`;
+}
+
+/**
+ * Which shell this page is running inside, from the bootstrap.
+ *
+ * The Android token wins when both are somehow present: the two shells are
+ * different devices, and a UA carrying both is crafted rather than observed.
+ */
+export function shellFromBootstrap(bootstrap: {
+  shellVersion?: string | null;
+  iosShellVersion?: string | null;
+} | undefined): { platform: ShellPlatform; version: string } | null {
+  if (bootstrap?.shellVersion) return { platform: 'android', version: bootstrap.shellVersion };
+  if (bootstrap?.iosShellVersion) return { platform: 'ios', version: bootstrap.iosShellVersion };
+  return null;
+}
+
+/**
+ * Fetch the published artifact and decide what to offer.
+ *
+ * `fetchImpl` is a seam for the tests: the cases that matter (no release, a
+ * failed probe, a version equal to the installed one) cannot be produced by a
+ * live GitHub call.
+ */
+export function useShellDownload(
+  platform: ShellPlatform,
+  version: string | null | undefined,
+  onAndroid: boolean | null | undefined,
+  fetchImpl: typeof fetch = fetch,
+): ShellDownload | null {
+  const [release, setRelease] = useState<Omit<ShellDownload, 'kind' | 'platform'> | null>(null);
+  const wanted = Boolean(version) || (platform === 'android' && Boolean(onAndroid));
+
+  useEffect(() => {
+    if (!wanted) return;
+
+    let cancelled = false;
+    void (async () => {
+      try {
+        const response = await fetchImpl(shellReleasePath(platform));
+        if (!response.ok) return;
+        const payload: unknown = await response.json();
+        if (!cancelled) setRelease(parseShellRelease(payload));
+      } catch {
+        // A probe that cannot answer is a button that must not appear.
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [wanted, platform, fetchImpl]);
+
+  return shouldOfferShellDownload(platform, version, onAndroid, release);
+}
+
+/**
+ * The offer for whichever shell this page is running inside — or the Android
+ * install offer for a browser on that platform.
+ *
+ * The single entry point both sidebar layouts call, so the two cannot disagree
+ * about which shell they are in or which endpoint they read. It reads the
+ * bootstrap the SERVER wrote for this request rather than sniffing the UA
+ * client-side, because the server already parsed it for the very response that
+ * carried the page.
+ */
+export function useShellOffer(fetchImpl: typeof fetch = fetch): ShellDownload | null {
+  const bootstrap = typeof window === 'undefined' ? undefined : window.__OMP_BOOTSTRAP__;
+  const shell = shellFromBootstrap(bootstrap);
+  return useShellDownload(
+    shell?.platform ?? 'android',
+    shell?.version ?? null,
+    bootstrap?.isAndroid,
+    fetchImpl,
+  );
+}
+
+/**
+ * The short form the phone's footer prints, where the label has no room.
+ *
+ * It names the OFFER, and for Android it names the file type because that is
+ * what a reader recognises (`APK` is the thing they will see in Downloads). An
+ * iOS update is an IPA, which nobody installs by hand — the shell finishes the
+ * install itself — so the platform word is the honest one there.
+ */
+export function shellDownloadShortLabel(download: ShellDownload): string {
+  if (download.platform === 'ios') return 'Update app';
+  return download.kind === 'update' ? 'Update APK' : 'Get APK';
+}

package/src/client/hooks/workspace/keybindings.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The workspace shortcuts, bound once for the desktop layout.
+ *
+ * Extracted from the layout because it is a self-contained decision — a chord
+ * mapped to one of four column/settings toggles — that has nothing to do with
+ * what the layout renders. `⌘S` is deliberately absent: the editor owns it, and
+ * binding it twice would save the file twice.
+ */
+
+import { useWindowEvent } from '@/client/hooks/ui/window-event';
+import { resolveBinding } from '@/shared/lib/ui/key-binding';
+import { WORKSPACE_KEY_BINDINGS } from '@/shared/lib/workspace/keymap';
+
+export interface WorkspaceKeybindingTargets {
+  showEditor: boolean;
+  /** Whether the editor column has anything to open on to. */
+  editorHasContent: boolean;
+  toggleSidebar: () => void;
+  toggleEditor: () => void;
+  toggleRightPanel: () => void;
+  openSettings: () => void;
+}
+
+export function useWorkspaceKeybindings(targets: WorkspaceKeybindingTargets): void {
+  useWindowEvent('keydown', (event) => {
+    const command = resolveBinding(WORKSPACE_KEY_BINDINGS, event);
+    if (!command) return;
+    if (command === 'saveFile') return;
+    // The toggle is the only way to REACH a takeover while the column is
+    // closed, since the rail lives inside the column: with nothing to open on
+    // to there would be no column at all.
+    if (command === 'toggleEditorPanel' && !targets.showEditor && !targets.editorHasContent) return;
+    event.preventDefault();
+    if (command === 'toggleSidebar') targets.toggleSidebar();
+    else if (command === 'toggleEditorPanel') targets.toggleEditor();
+    else if (command === 'toggleRightPanel') targets.toggleRightPanel();
+    else if (command === 'openSettings') targets.openSettings();
+  });
+}

package/src/client/hooks/workspace/open-panel.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The desktop half of `omp:open-panel`: turn a panel key into a visible column.
+ *
+ * The COLUMN is the user's placement, read from the dock state, never a choice
+ * the caller makes: the same panel may sit on the left dock, in the right
+ * column or in the editor column, and a plugin that named one would break the
+ * moment the user moved it. Each handler therefore does what the rail's own
+ * button does — select the view AND open its column — because a selection made
+ * while the column is collapsed is a click that changed nothing on screen.
+ *
+ * The phone does not use this: its drawers are SCREENS, and which one can reach
+ * a panel is a different question (`phoneDrawerForPanel`).
+ */
+
+import { useKabmoEvent } from '@/client/hooks/ui/window-event';
+import type { LeftDockState } from '@/shared/lib/workspace/left-dock';
+import { panelSideOf } from '@/shared/lib/workspace/left-dock';
+import { OPEN_PANEL_EVENT, type OpenPanelDetail } from '@/shared/lib/workspace/panel-open';
+
+export interface OpenPanelTargets {
+  /** The dock state the placement is read from. */
+  dock: LeftDockState;
+  onLeft: (panelKey: string) => void;
+  onEditor: (panelKey: string) => void;
+  onRight: (panelKey: string) => void;
+}
+
+export function useOpenPanelRequest(targets: OpenPanelTargets): void {
+  useKabmoEvent(OPEN_PANEL_EVENT, (event) => {
+    const panelKey = (event as CustomEvent<OpenPanelDetail>).detail?.panelKey;
+    if (!panelKey) return;
+    const side = panelSideOf(panelKey, targets.dock);
+    if (side === 'left') targets.onLeft(panelKey);
+    else if (side === 'editor') targets.onEditor(panelKey);
+    else targets.onRight(panelKey);
+  });
+}