@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/client/hooks/editor/use-scroll-restore.ts

@@ -32,7 +32,7 @@
  *   overwrite the position this hook exists to keep.
  */
 
-import { useCallback, useContext, useLayoutEffect, useRef } from 'preact/hooks';
+import { useCallback, useContext, useEffect, useLayoutEffect, useRef } from 'preact/hooks';
 import { SessionStateContext } from '@/client/hooks/workspace/session-state/context';
 import { getSessionValue, setSessionKey } from '@/shared/lib/workspace/session-state/store';
 import {
@@ -52,6 +52,29 @@ const SAVE_DEBOUNCE_MS = 150;
 /** Scroll deltas below this are rounding, not a move. */
 const NOISE_PX = 1;
 
+/**
+ * The cancel hook of every restore currently armed, by scroller.
+ *
+ * A pending restore REPLAYS while the document settles, and it re-applies
+ * through a `ResizeObserver` — which can fire BEFORE the scroll event a
+ * programmatic reveal causes. Measured: an outline jump scrolled a 2 520-line
+ * file to 34 695 px and the observer wrote the stored 0 back 375 ms later, so
+ * the caret moved and the view stayed at the top.
+ *
+ * An explicit reveal therefore has to CANCEL the restore rather than race it,
+ * and the surface that scrolls is the one that knows. This registry is that
+ * hand-off: keyed by the element, so a caller needs no reference to the hook
+ * instance that armed it (the surface owns the scroller; the panel owns the
+ * hook).
+ */
+const armedRestores = new Map<HTMLElement, () => void>();
+
+/** Stop a pending restore of `element` — a reveal wins over a remembered offset. */
+export function cancelScrollRestore(element: HTMLElement | null): void {
+  if (!element) return;
+  armedRestores.get(element)?.();
+}
+
 /** What a caller attaches to its scroll container. */
 export interface ScrollRestoreBinding {
   ref: (element: HTMLElement | null) => void;
@@ -67,6 +90,16 @@ export interface UseScrollRestoreOptions {
   ready?: boolean;
   /** The session-state slot to read/write; the editor column's by default. */
   slot?: string;
+  /**
+   * The element to restore, for a caller that does not own a `ref` on it.
+   *
+   * The code surface's scroller belongs to CodeMirror (`view.scrollDOM`) and
+   * exists only after the view mounts, so the surface reports it through
+   * `onScroller` and the caller passes it here. `undefined` means "this caller
+   * uses `ref`"; `null` means "the element is not there yet", which re-arms the
+   * restore on the next render that has one.
+   */
+  element?: HTMLElement | null;
 }
 
 export function useScrollRestore({
@@ -74,6 +107,7 @@ export function useScrollRestore({
   surface,
   ready = true,
   slot = SCROLL_POSITIONS_KEY,
+  element: providedElement,
 }: UseScrollRestoreOptions): ScrollRestoreBinding {
   // Read OPTIONALLY: the shared diff views also draw a chat tool card, and a
   // caller may mount one without the provider. A null context makes the whole
@@ -100,6 +134,37 @@ export function useScrollRestore({
    * whose height is still growing then stayed where the clamp left it.
    */
   const writingRef = useRef(false);
+  /**
+   * What the element's `scrollTop` was at the last observation, so a scroll
+   * event that moves it WITHOUT anyone assigning can be recognised as the
+   * browser's own anchoring rather than the reader's.
+   *
+   * This is the bug the e2e spec found on CI and could not explain: returning to
+   * a long file landed the reader on line 99 instead of line 70, and the wrong
+   * offset was then persisted. Measured in the browser: the restore wrote 1255,
+   * the document's real height arrived a frame later (5796 → 7232), and
+   * CodeMirror re-anchored — `scrollTop` became 1777 with no assignment from
+   * this hook. That produced a `scroll` event, the handler below compared it
+   * against `restoredTopRef` (1255), read a 522px delta, and treated it as the
+   * reader's own scroll: the pending restore was dropped, and the anchored
+   * value became what got stored. The reader moved 29 lines for opening a tab.
+   *
+   * An anchoring correction is not a reader. It is re-applied like any other
+   * height change, because the target offset is the one the session recorded.
+   */
+  const observedTopRef = useRef(0);
+  /**
+   * Whether the reader has DONE something since the last scroll event — the
+   * only thing that separates their scroll from the browser's own.
+   *
+   * Every way a reader scrolls a code surface starts with an input event: a
+   * wheel, a key (arrows, PageDown, Home/End), a pointer press on the scrollbar
+   * or a drag-select, a touch. CodeMirror re-anchoring starts with none, so a
+   * `scroll` with no input behind it is the document settling. The flag is
+   * cleared by the scroll it explains, so the next unattributed move is read as
+   * anchoring again.
+   */
+  const readerIntentRef = useRef(false);
   /** The last offset the READER produced, persisted on the way out. */
   const lastTopRef = useRef<number | null>(null);
   const saveTimerRef = useRef<ReturnType<typeof setTimeout>>();
@@ -113,13 +178,17 @@ export function useScrollRestore({
       pendingRef.current = null;
       return;
     }
-    if (Math.abs(element.scrollTop - pending.top) < NOISE_PX) return;
+    if (Math.abs(element.scrollTop - pending.top) < NOISE_PX) {
+      observedTopRef.current = element.scrollTop;
+      return;
+    }
     writingRef.current = true;
     element.scrollTop = pending.top;
     writingRef.current = false;
     // Read back: the document may be shorter than the target, and the clamped
     // value is what an asynchronous scroll event will report.
     restoredTopRef.current = element.scrollTop;
+    observedTopRef.current = element.scrollTop;
   }, []);
 
   const attach = useCallback(
@@ -152,9 +221,23 @@ export function useScrollRestore({
       // because the event may arrive synchronously (during the assignment) or
       // on a later frame (against the value the write landed on).
       if (writingRef.current) return;
+      // Moved with nobody assigning AND no reader input behind it: CodeMirror
+      // re-anchoring after the document's real height landed. NOT the reader —
+      // re-applying the recorded offset is what keeps them where they were. See
+      // `observedTopRef` for the measurement.
+      const moved = Math.abs(top - observedTopRef.current) >= NOISE_PX;
+      observedTopRef.current = top;
+      if (moved && !readerIntentRef.current) {
+        applyPending();
+        return;
+      }
       if (Math.abs(top - restoredTopRef.current) < NOISE_PX * 2) return;
       pendingRef.current = null;
     }
+    observedTopRef.current = top;
+    // The input this scroll belongs to has now been accounted for; the next
+    // unattributed move is anchoring again.
+    readerIntentRef.current = false;
     lastTopRef.current = top;
     clearTimeout(saveTimerRef.current);
     saveTimerRef.current = setTimeout(() => {
@@ -162,14 +245,47 @@ export function useScrollRestore({
       const value = lastTopRef.current;
       if (value !== null) persist(value);
     }, SAVE_DEBOUNCE_MS);
-  }, [persist, tabKey]);
+  }, [applyPending, persist, tabKey]);
+
+  // A provided element is not a React-rendered node, so its scroll events have
+  // to be wired here: the caller has no `onScroll` prop to hang them on. The
+  // ref path keeps the caller's own `onScroll`.
+  useEffect(() => {
+    if (!providedElement) return;
+    const listener = () => onScroll();
+    providedElement.addEventListener('scroll', listener, { passive: true });
+    return () => providedElement.removeEventListener('scroll', listener);
+  }, [providedElement, onScroll]);
+
+  // What counts as the reader having scrolled, for `readerIntentRef`. Wired on
+  // the element AND the window, because a keydown goes to the focused editor
+  // while a wheel over the gutter goes to the window's capture phase.
+  useEffect(() => {
+    const element = providedElement ?? elementRef.current;
+    if (!element) return;
+    const note = () => {
+      readerIntentRef.current = true;
+    };
+    const types = ['wheel', 'keydown', 'pointerdown', 'touchstart'] as const;
+    for (const type of types) element.addEventListener(type, note, { passive: true });
+    window.addEventListener('keydown', note, { passive: true });
+    return () => {
+      for (const type of types) element.removeEventListener(type, note);
+      window.removeEventListener('keydown', note);
+    };
+  }, [providedElement]);
 
   // A layout effect so the restore lands in the same frame the tab paints — a
   // passive effect would show the document's head for one frame first.
   useLayoutEffect(() => {
     pendingRef.current = null;
     lastTopRef.current = null;
+    readerIntentRef.current = false;
     let observer: ResizeObserver | null = null;
+    // A provided element WINS over the ref: the caller handed us the element it
+    // wants restored, and a stale ref from the other surface of the same tab
+    // must not be restored instead.
+    if (providedElement !== undefined) elementRef.current = providedElement;
     const element = elementRef.current;
 
     if (ready && storeReady && tabKey && element) {
@@ -179,6 +295,9 @@ export function useScrollRestore({
       // of it. "No stored offset" means the top, and the top is where they go.
       const top = readScrollTop(getSessionValue<ScrollPositions>(sessionId, slot), tabKey, surface);
       pendingRef.current = { top, until: performance.now() + RESTORE_WINDOW_MS };
+      armedRestores.set(element, () => {
+        pendingRef.current = null;
+      });
       applyPending();
       // The document's own height is what moves after this commit (measurement,
       // a width animation, spacers landing), so its growth is what re-applies.
@@ -190,6 +309,7 @@ export function useScrollRestore({
     }
 
     return () => {
+      if (element) armedRestores.delete(element);
       observer?.disconnect();
       clearTimeout(saveTimerRef.current);
       saveTimerRef.current = undefined;
@@ -203,7 +323,7 @@ export function useScrollRestore({
     };
     // `applyPending`/`persist` are stable, and re-running this effect restarts
     // the restore — which is exactly what a tab or surface change needs.
-  }, [ready, storeReady, tabKey, surface, sessionId, slot, applyPending, persist]);
+  }, [ready, storeReady, tabKey, surface, sessionId, slot, applyPending, persist, providedElement]);
 
   return { ref: attach, onScroll };
 }

package/src/client/hooks/editor/use-search-reveal.ts

@@ -29,7 +29,7 @@
 import { useEffect, useMemo, useState } from 'preact/hooks';
 import { useSyncExternalStore } from 'preact/compat';
 
-import { findMatches, lineStartOffset, matchIndexAtOrAfter } from '@/shared/lib/code/editor/find';
+import { findMatches, lineStartOffset, matchIndexAtOrAfter } from '@/shared/lib/code/editor/find-scan';
 import {
   getSearchReveal,
   setSearchReveal,

package/src/client/hooks/ui/long-press.test.ts

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Long press: the only way a finger reaches a Files-panel row's menu.
+ *
+ * Three rules are load-bearing and each was a way the gesture would misbehave
+ * on a phone:
+ *
+ * 1. **A press that MOVES is a scroll.** The tree is a scroller, and a hold that
+ *    begins a flick must cancel — otherwise every scroll that starts on a row
+ *    opens a menu.
+ * 2. **The click the same gesture produces is swallowed.** Lifting the finger
+ *    after the menu opened would otherwise also toggle the folder it opened for;
+ *    the platform raises both events for one gesture and marks neither.
+ * 3. **It is inert without a finger.** A desktop holding its primary button down
+ *    is a drag, and a mouse already has a right button.
+ *
+ * Time is driven, never slept through: a 450 ms hold is a real wait, and the
+ * hook's decisions are all about WHICH event arrives, never about how long the
+ * test took.
+ */
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+import { useLongPress, type LongPressHandlers } from '@/client/hooks/ui/long-press';
+
+let win: Window;
+let container: HTMLElement;
+let handlers: LongPressHandlers | null = null;
+const fired: Array<{ x: number; y: number }> = [];
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  win = new Window({ url: 'http://localhost' });
+  installDomGlobals(win);
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  fired.length = 0;
+  handlers = null;
+});
+
+afterEach(() => {
+  render(null, container);
+  container.remove();
+  restoreDomGlobals();
+  vi.useRealTimers();
+});
+
+/** Mount the hook; `enabled` is what a touch device decides. */
+async function mount(enabled: boolean): Promise<void> {
+  const Probe = () => {
+    handlers = useLongPress({ enabled, onLongPress: (x, y) => fired.push({ x, y }) });
+    return null;
+  };
+  await act(async () => {
+    render(h(Probe, {}), container);
+  });
+}
+
+/** A touch event carrying one finger at `(x, y)`. */
+function touch(type: string, x: number, y: number): globalThis.TouchEvent {
+  const event = new win.Event(type, { bubbles: true, cancelable: true }) as unknown as globalThis.TouchEvent;
+  Object.defineProperty(event, 'touches', { value: type === 'touchend' || type === 'touchcancel' ? [] : [{ clientX: x, clientY: y }] });
+  return event;
+}
+
+/** Advance the hook's own timer, without waiting on a real clock. */
+async function holdFor(ms: number): Promise<void> {
+  await act(async () => {
+    vi.advanceTimersByTime(ms);
+  });
+}
+
+describe('useLongPress', () => {
+  test('a hold fires at the press point', async () => {
+    await mount(true);
+
+    await act(async () => {
+      handlers!.onTouchStart(touch('touchstart', 40, 80));
+    });
+    await holdFor(520);
+
+    expect(fired).toEqual([{ x: 40, y: 80 }]);
+  });
+
+  test('a press released before the threshold never fires', async () => {
+    await mount(true);
+
+    await act(async () => {
+      handlers!.onTouchStart(touch('touchstart', 40, 80));
+    });
+    await act(async () => {
+      handlers!.onTouchEnd();
+    });
+    await holdFor(520);
+
+    expect(fired).toEqual([]);
+  });
+
+  test('a press that MOVES is a scroll, not a press', async () => {
+    await mount(true);
+
+    await act(async () => {
+      handlers!.onTouchStart(touch('touchstart', 40, 80));
+      // Past the slop: the first few pixels of a flick arrive immediately, and
+      // a menu that opened on them would make the tree unscrollable.
+      handlers!.onTouchMove(touch('touchmove', 40, 140));
+    });
+    await holdFor(520);
+
+    expect(fired).toEqual([]);
+  });
+
+  test('a small drift inside the slop still counts as a hold', async () => {
+    await mount(true);
+
+    await act(async () => {
+      handlers!.onTouchStart(touch('touchstart', 40, 80));
+      handlers!.onTouchMove(touch('touchmove', 42, 83));
+    });
+    await holdFor(520);
+
+    expect(fired).toHaveLength(1);
+  });
+
+  test('a cancelled press never fires', async () => {
+    await mount(true);
+
+    await act(async () => {
+      handlers!.onTouchStart(touch('touchstart', 40, 80));
+      handlers!.onTouchCancel();
+    });
+    await holdFor(520);
+
+    expect(fired).toEqual([]);
+  });
+
+  test('the click after a fired press is consumed exactly once', async () => {
+    await mount(true);
+
+    await act(async () => {
+      handlers!.onTouchStart(touch('touchstart', 40, 80));
+    });
+    await holdFor(520);
+
+    // The first click belongs to the gesture that opened the menu; a second
+    // click is the user's own and must work.
+    expect(handlers!.consume()).toBe(true);
+    expect(handlers!.consume()).toBe(false);
+  });
+
+  test('no press means nothing to consume', async () => {
+    await mount(true);
+
+    expect(handlers!.consume()).toBe(false);
+  });
+
+  test('it is inert without a finger', async () => {
+    await mount(false);
+
+    await act(async () => {
+      handlers!.onTouchStart(touch('touchstart', 40, 80));
+    });
+    await holdFor(520);
+
+    expect(fired).toEqual([]);
+  });
+});

package/src/client/hooks/ui/long-press.ts

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Long press, for the surfaces that have no right-click.
+ *
+ * A phone's Files panel offered no way to reach a row's context menu: the menu
+ * opens on `contextmenu`, which a touch device only raises after a press that
+ * the browser has already claimed for something else — a native drag (the row
+ * is a drag source) or a text selection of the whole panel. Measured on a
+ * phone: holding a file row selected the tree's text and started a drag ghost,
+ * and no menu ever appeared.
+ *
+ * Three rules make this usable rather than a second way to break the panel:
+ *
+ * - **A press that MOVES is a scroll, not a press.** The tree is a scroller, and
+ *   a hold that begins a scroll must cancel — otherwise every flick that starts
+ *   on a row opens a menu. The threshold is small (`SLOP_PX`) because the first
+ *   few pixels of a scroll arrive within the same tick.
+ * - **A fired press suppresses the CLICK it would otherwise produce.** Lifting
+ *   the finger after the menu opened would otherwise also toggle the folder the
+ *   menu was opened for. The caller asks `consume()` from its click handler,
+ *   which is the only place the two can be told apart — the platform raises both
+ *   events for one gesture and does not mark either.
+ * - **It is inert without a touch device.** A mouse already has a right button,
+ *   and a desktop holding its primary button down over a row is a drag.
+ *
+ * The handler is deliberately not `onContextMenu`-based: some Android builds DO
+ * raise `contextmenu` after a hold, and the browser's own press has already
+ * started a selection by then, so the menu would open over a half-selected tree.
+ */
+
+import { useCallback, useEffect, useRef } from 'preact/hooks';
+
+/** How long a press must be held before it counts. */
+const LONG_PRESS_MS = 450;
+/** Movement that turns a press into a scroll, in CSS pixels. */
+const SLOP_PX = 8;
+/** How long a fired press keeps suppressing the click it produces. */
+const CLICK_SUPPRESS_MS = 700;
+
+export interface LongPressOptions {
+  /** False on a device with a pointer: the right button already does this. */
+  enabled: boolean;
+  /** Where the press landed, in viewport coordinates — a menu anchor. */
+  onLongPress: (x: number, y: number) => void;
+}
+
+export interface LongPressHandlers {
+  onTouchStart: (event: globalThis.TouchEvent) => void;
+  onTouchMove: (event: globalThis.TouchEvent) => void;
+  onTouchEnd: () => void;
+  onTouchCancel: () => void;
+  /**
+   * True exactly once after a press fired, so the caller's click handler can
+   * ignore the click the same gesture produces.
+   */
+  consume: () => boolean;
+}
+
+export function useLongPress({ enabled, onLongPress }: LongPressOptions): LongPressHandlers {
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const originRef = useRef<{ x: number; y: number } | null>(null);
+  const firedAtRef = useRef(0);
+  /** The latest callback, so a re-render never leaves a stale one armed. */
+  const handlerRef = useRef(onLongPress);
+  handlerRef.current = onLongPress;
+
+  const cancel = useCallback(() => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    originRef.current = null;
+  }, []);
+
+  useEffect(() => cancel, [cancel]);
+
+  return {
+    onTouchStart: (event) => {
+      if (!enabled) return;
+      const touch = event.touches[0];
+      if (!touch) return;
+      cancel();
+      originRef.current = { x: touch.clientX, y: touch.clientY };
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        const origin = originRef.current;
+        originRef.current = null;
+        if (!origin) return;
+        firedAtRef.current = Date.now();
+        handlerRef.current(origin.x, origin.y);
+      }, LONG_PRESS_MS);
+    },
+    onTouchMove: (event) => {
+      const origin = originRef.current;
+      const touch = event.touches[0];
+      if (!origin || !touch) return;
+      if (Math.abs(touch.clientX - origin.x) > SLOP_PX || Math.abs(touch.clientY - origin.y) > SLOP_PX) cancel();
+    },
+    onTouchEnd: cancel,
+    onTouchCancel: cancel,
+    consume: () => {
+      if (firedAtRef.current === 0) return false;
+      const recent = Date.now() - firedAtRef.current < CLICK_SUPPRESS_MS;
+      firedAtRef.current = 0;
+      return recent;
+    },
+  };
+}

package/src/client/hooks/ui/settings-modal.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The desktop layout's settings modal: whether it is open, which category it
+ * opens on, and whether a provider dialog follows.
+ *
+ * A hook because two different triggers drive it — the sidebar footer's button
+ * and the `omp:open-settings` window event (dispatched by the model dropdown,
+ * the phone's footer and any plugin) — and the event carries the category it
+ * wants. Stated once, the two paths cannot open the same modal on different
+ * screens.
+ */
+
+import { useState } from 'preact/hooks';
+import { useKabmoEvent } from '@/client/hooks/ui/window-event';
+import type { SettingsCategoryId } from '@/shared/types';
+
+export interface SettingsModalState {
+  isOpen: boolean;
+  category: SettingsCategoryId;
+  /** The "add provider" dialog opens on top of the modal's Providers screen. */
+  autoOpenAddProvider: boolean;
+  open: (category?: SettingsCategoryId, autoOpenAdd?: boolean) => void;
+  close: () => void;
+}
+
+export function useSettingsModal(): SettingsModalState {
+  const [isOpen, setOpen] = useState(false);
+  const [category, setCategory] = useState<SettingsCategoryId>('appearance');
+  const [autoOpenAddProvider, setAutoOpenAddProvider] = useState(false);
+
+  const open = (next?: SettingsCategoryId, autoOpenAdd = false) => {
+    setCategory(next ?? 'appearance');
+    setAutoOpenAddProvider(autoOpenAdd);
+    setOpen(true);
+  };
+
+  useKabmoEvent('omp:open-settings', (event) => {
+    const detail = (event as CustomEvent<{ category?: SettingsCategoryId; autoOpenAdd?: boolean }>).detail;
+    open(detail?.category, Boolean(detail?.autoOpenAdd));
+  });
+
+  return {
+    isOpen,
+    category,
+    autoOpenAddProvider,
+    open,
+    close: () => {
+      setOpen(false);
+      setAutoOpenAddProvider(false);
+    },
+  };
+}

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

@@ -6,8 +6,10 @@
 import { describe, expect, test } from 'bun:test';
 
 import {
+  desktopShellFromIdentity,
   parseShellRelease,
   shellDownloadLabel,
+  shellDownloadShortLabel,
   shellFromBootstrap,
   shellReleasePath,
   shouldOfferShellDownload,
@@ -19,6 +21,7 @@ const RELEASE = {
   url: 'https://github.com/kabmo-labs/kabmo/releases/download/v1.2.3/Kabmo-1.2.3-android.apk',
   latest: '1.2.3',
   releaseUrl: 'https://github.com/kabmo-labs/kabmo/releases/tag/v1.2.3',
+  direct: true,
 };
 
 const UPDATE: ShellDownload = { ...RELEASE, kind: 'update', platform: 'android' };
@@ -155,3 +158,75 @@ describe('shellReleasePath', () => {
     expect(shellReleasePath('ios')).toBe('/api/updates/ios');
   });
 });
+
+describe('the desktop shells', () => {
+  test('each desktop shell reads its own route, with an explicit kind', () => {
+    // ONE route with a required `kind`, so no absence can silently mean a
+    // platform — the reason the mobile pair has two routes.
+    expect(shellReleasePath('macos')).toBe('/api/updates/desktop?kind=macos');
+    expect(shellReleasePath('windows')).toBe('/api/updates/desktop?kind=windows');
+    expect(shellReleasePath('linux')).toBe('/api/updates/desktop?kind=linux');
+  });
+
+  test('a desktop shell offers an update when it is behind', () => {
+    // The reported gap: an installed desktop app that is behind had no way to
+    // learn it, because nothing in the console read its version.
+    expect(shouldOfferShellDownload('macos', '0.1.0', null, RELEASE)).toEqual({
+      ...RELEASE,
+      kind: 'update',
+      platform: 'macos',
+    });
+    expect(shouldOfferShellDownload('windows', '0.1.0', null, RELEASE)?.platform).toBe('windows');
+    expect(shouldOfferShellDownload('linux', '0.1.0', null, RELEASE)?.platform).toBe('linux');
+  });
+
+  test('a desktop shell that is current, or ahead, offers nothing', () => {
+    expect(shouldOfferShellDownload('macos', '1.2.3', null, RELEASE)).toBeNull();
+    expect(shouldOfferShellDownload('macos', '1.3.0', null, RELEASE)).toBeNull();
+  });
+
+  test('a desktop BROWSER is offered nothing', () => {
+    // A desktop app is installed by hand from the release page; a tab that
+    // advertised one would be a button for a product the reader did not ask for.
+    expect(shouldOfferShellDownload('macos', null, false, RELEASE)).toBeNull();
+    expect(shouldOfferShellDownload('windows', undefined, undefined, RELEASE)).toBeNull();
+  });
+
+  test('the label names the desktop platform', () => {
+    const update: ShellDownload = { ...RELEASE, kind: 'update', platform: 'linux' };
+    expect(shellDownloadLabel(update)).toBe('Update Kabmo 1.2.3 for Linux');
+    expect(shellDownloadShortLabel(update)).toBe('Update Linux');
+  });
+
+  test('the short label keeps the mobile spellings', () => {
+    expect(shellDownloadShortLabel(UPDATE)).toBe('Update APK');
+    expect(shellDownloadShortLabel(INSTALL)).toBe('Get APK');
+    expect(shellDownloadShortLabel({ ...UPDATE, platform: 'ios' })).toBe('Update app');
+  });
+});
+
+describe('desktopShellFromIdentity', () => {
+  test('reads the bridge identity the shell injects', () => {
+    expect(desktopShellFromIdentity({ platform: 'macos', shellVersion: '0.2.0' })).toEqual({
+      platform: 'macos',
+      version: '0.2.0',
+      arch: null,
+    });
+    expect(desktopShellFromIdentity({ platform: 'windows', shellVersion: '0.2.0' })?.platform).toBe('windows');
+    expect(desktopShellFromIdentity({ platform: 'linux', shellVersion: '0.2.0' })?.platform).toBe('linux');
+  });
+
+  test('is null in a browser, and for an identity with no version', () => {
+    expect(desktopShellFromIdentity(null)).toBeNull();
+    expect(desktopShellFromIdentity(undefined)).toBeNull();
+    expect(desktopShellFromIdentity({ platform: 'macos' })).toBeNull();
+    expect(desktopShellFromIdentity({ shellVersion: '0.2.0' })).toBeNull();
+  });
+
+  test('an unknown platform is not compared against a published artifact', () => {
+    // A newer shell reporting a fourth platform must not be matched to a file
+    // nobody publishes.
+    expect(desktopShellFromIdentity({ platform: 'beos', shellVersion: '1.0.0' })).toBeNull();
+    expect(desktopShellFromIdentity({ platform: 'android', shellVersion: '1.0.0' })).toBeNull();
+  });
+});