@kabmo-labs/kabmo 0.7.0 → 0.9.0

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

@@ -1,12 +1,11 @@
 /**
- * What the sidebar should offer for a native shell, and why.
+ * What the console 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.
+ * - **`update`** — this page is running inside the shell 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
@@ -16,18 +15,26 @@
  * 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.
+ * There is NO desktop BROWSER offer either, but there IS a desktop SHELL one: a
+ * desktop app is installed by hand from the release page, so nothing in a tab
+ * should advertise it — while an installed app that is behind has exactly the
+ * same problem the mobile pair had, and used to have no way to learn it.
  *
- * 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.
+ * The probe is lazy: it runs only when an installed shell (a bootstrap token, or
+ * a bridge identity) or an Android device is present, so a console that can
+ * never show the button makes no request for it. ONE hook for every shell,
+ * 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';
+import { parseShellArch, type ShellArch } from '@/shared/lib/updates/shell-arch';
+import {
+  isDesktopShellKind,
+  type DesktopShellKind,
+  type ShellKind,
+} from '@/shared/lib/updates/shell-ua';
 
 /** Which shell the offer is for. */
 export type ShellPlatform = ShellKind;
@@ -36,7 +43,15 @@ export type ShellPlatform = ShellKind;
 export type ShellOfferKind = 'update' | 'install';
 
 export interface ShellDownload {
-  /** The artifact to download. */
+  /**
+   * What the control points at.
+   *
+   * The artifact itself for the mobile pair (an APK the shell installs, an IPA
+   * the release page explains), and for a desktop shell EITHER its own
+   * per-architecture artifact (when it reported `arch`) or the RELEASE PAGE (when
+   * it did not). `direct` says which, and that is what decides between a button
+   * and a link.
+   */
   url: string;
   /** The version that artifact ships. */
   latest: string;
@@ -46,18 +61,31 @@ export interface ShellDownload {
   kind: ShellOfferKind;
   /** Which shell this offer is for. */
   platform: ShellPlatform;
+  /**
+   * True when `url` is the artifact itself, so the SHELL can install it.
+   *
+   * False means `url` is the release page: the console cannot name one file
+   * (a desktop shell that did not report its architecture), so the offer is a
+   * link a human follows. That distinction is what decides between an `<a>` and
+   * a button that drives `update_apply`.
+   */
+  direct: boolean;
 }
 
 interface ReleasePayload {
   url?: unknown;
   latest?: unknown;
   releaseUrl?: unknown;
+  direct?: unknown;
 }
 
 /** The platform's own name, as the label says it. */
 const PLATFORM_NAMES: Record<ShellPlatform, string> = {
   android: 'Android',
   ios: 'iOS',
+  macos: 'macOS',
+  windows: 'Windows',
+  linux: 'Linux',
 };
 
 /**
@@ -76,6 +104,10 @@ export function parseShellRelease(payload: unknown): Omit<ShellDownload, 'kind'
     url: body.url,
     latest: body.latest,
     releaseUrl: typeof body.releaseUrl === 'string' ? body.releaseUrl : null,
+    // Absent means "not installable": a shell that cannot install the bytes must
+    // fall back to the link rather than to a button that would download into
+    // nowhere.
+    direct: body.direct === true,
   };
 }
 
@@ -126,8 +158,20 @@ export function shellDownloadLabel(download: ShellDownload): string {
   return `${verb} Kabmo ${download.latest} for ${PLATFORM_NAMES[download.platform]}`;
 }
 
-/** The endpoint that answers for one shell. */
-export function shellReleasePath(platform: ShellPlatform): string {
+/**
+ * The endpoint that answers for one shell.
+ *
+ * The desktop trio shares ONE route with an explicit `kind`, so no absence can
+ * silently mean a platform — the reason the mobile pair has two.
+ */
+export function shellReleasePath(platform: ShellPlatform, arch: ShellArch | null = null): string {
+  if (isDesktopShellKind(platform)) {
+    // The arch is what makes the answer a FILE rather than a page. A shell that
+    // did not report one still asks, and still gets the page that lists every
+    // architecture — the offer is then a link, which is the honest fallback.
+    const base = `/api/updates/desktop?kind=${platform}`;
+    return arch ? `${base}&arch=${arch}` : base;
+  }
   return `/api/updates/${platform}`;
 }
 
@@ -146,6 +190,34 @@ export function shellFromBootstrap(bootstrap: {
   return null;
 }
 
+/**
+ * Which DESKTOP shell this page is running inside, from the bridge identity.
+ *
+ * The desktop trio reports itself over `window.__kabmoDesktop` rather than the
+ * User-Agent, because a desktop app is not downloaded from the console and the
+ * server has nothing to parse per request. The identity is injected at document
+ * start, before the page's own scripts, so this answers on the FIRST paint.
+ *
+ * An identity whose `platform` is not one of the three is not a desktop shell
+ * this build knows how to update — a newer shell reporting a fourth platform
+ * must not be compared against an artifact nobody publishes.
+ */
+export function desktopShellFromIdentity(identity: {
+  platform?: string;
+  shellVersion?: string;
+  arch?: string;
+} | null | undefined): { platform: DesktopShellKind; version: string; arch: ShellArch | null } | null {
+  if (!identity?.platform || !identity.shellVersion) return null;
+  if (!isDesktopShellKind(identity.platform)) return null;
+  return {
+    platform: identity.platform,
+    version: identity.shellVersion,
+    // A shell too old to report one keeps working: the offer degrades to the
+    // release page instead of disappearing.
+    arch: parseShellArch(identity.arch),
+  };
+}
+
 /**
  * Fetch the published artifact and decide what to offer.
  *
@@ -158,9 +230,25 @@ export function useShellDownload(
   version: string | null | undefined,
   onAndroid: boolean | null | undefined,
   fetchImpl: typeof fetch = fetch,
+  arch: ShellArch | null = null,
 ): ShellDownload | null {
-  const [release, setRelease] = useState<Omit<ShellDownload, 'kind' | 'platform'> | null>(null);
+  /**
+   * The answer, TAGGED with the platform it was read for.
+   *
+   * A bare payload is not enough: this hook is called with a different platform
+   * when a page's shell changes (a desktop identity arriving, a spawn adoption),
+   * and an untagged answer would be compared against the new platform's version
+   * — offering an Android APK to a Mac for one render.
+   */
+  const [answer, setAnswer] = useState<{
+    key: string;
+    release: Omit<ShellDownload, 'kind' | 'platform'> | null;
+  } | null>(null);
   const wanted = Boolean(version) || (platform === 'android' && Boolean(onAndroid));
+  // The question this hook is asking, arch included: two windows on one console
+  // differ only by architecture, and an answer read for the other one is not an
+  // answer.
+  const key = `${platform}:${arch ?? ''}`;
 
   useEffect(() => {
     if (!wanted) return;
@@ -168,10 +256,10 @@ export function useShellDownload(
     let cancelled = false;
     void (async () => {
       try {
-        const response = await fetchImpl(shellReleasePath(platform));
+        const response = await fetchImpl(shellReleasePath(platform, arch));
         if (!response.ok) return;
         const payload: unknown = await response.json();
-        if (!cancelled) setRelease(parseShellRelease(payload));
+        if (!cancelled) setAnswer({ key, release: parseShellRelease(payload) });
       } catch {
         // A probe that cannot answer is a button that must not appear.
       }
@@ -180,29 +268,64 @@ export function useShellDownload(
     return () => {
       cancelled = true;
     };
-  }, [wanted, platform, fetchImpl]);
+  }, [wanted, key, platform, arch, fetchImpl]);
 
+  // A stale answer belongs to the question it was read for, not this one.
+  const release = answer?.key === key ? answer.release : null;
   return shouldOfferShellDownload(platform, version, onAndroid, release);
 }
 
+/** The bridge identity a desktop shell injects before the page's first script. */
+export interface DesktopIdentity {
+  platform?: string;
+  shellVersion?: string;
+}
+
+function readDesktopIdentity(): DesktopIdentity | null {
+  if (typeof window === 'undefined') return null;
+  // `window.__kabmoDesktop` is declared by `lib/desktop/bridge` — the same
+  // object the shell injects, so this reads the shell's own contract rather
+  // than re-declaring its shape here.
+  return window.__kabmoDesktop ?? null;
+}
+
 /**
  * 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.
+ * bootstrap the SERVER wrote for this request (and, for a desktop shell, the
+ * identity the shell injected) rather than sniffing the UA client-side, because
+ * the server already parsed it for the very response that carried the page.
+ *
+ * `desktop` is a parameter so the tests can drive the bridge identity without a
+ * real shell; production reads it from `window.__kabmoDesktop`.
  */
-export function useShellOffer(fetchImpl: typeof fetch = fetch): ShellDownload | null {
+export function useShellOffer(
+  fetchImpl: typeof fetch = fetch,
+  desktop: DesktopIdentity | null = readDesktopIdentity(),
+): ShellDownload | null {
   const bootstrap = typeof window === 'undefined' ? undefined : window.__OMP_BOOTSTRAP__;
-  const shell = shellFromBootstrap(bootstrap);
+  const mobile = shellFromBootstrap(bootstrap);
+  const fromBridge = desktopShellFromIdentity(desktop);
+
+  // The desktop identity is checked FIRST and is authoritative when present: a
+  // desktop shell never carries a mobile UA token, and a page that somehow had
+  // both is in the desktop app, whose version is the one being compared.
+  //
+  // ONE call, with the resolved platform — never two conditional calls. A hook
+  // behind an `if` changes the hook order between renders, which React/Preact
+  // treats as a different component.
+  const platform = fromBridge?.platform ?? mobile?.platform ?? 'android';
+  const version = fromBridge?.version ?? mobile?.version ?? null;
+
   return useShellDownload(
-    shell?.platform ?? 'android',
-    shell?.version ?? null,
-    bootstrap?.isAndroid,
+    platform,
+    version,
+    fromBridge ? null : bootstrap?.isAndroid,
     fetchImpl,
+    fromBridge?.arch ?? null,
   );
 }
 
@@ -212,9 +335,11 @@ export function useShellOffer(fetchImpl: typeof fetch = fetch): ShellDownload |
  * 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.
+ * install itself — so the platform word is the honest one there. A desktop
+ * update opens the release page, so it names the platform too.
  */
 export function shellDownloadShortLabel(download: ShellDownload): string {
   if (download.platform === 'ios') return 'Update app';
+  if (isDesktopShellKind(download.platform)) return `Update ${PLATFORM_NAMES[download.platform]}`;
   return download.kind === 'update' ? 'Update APK' : 'Get APK';
 }

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

@@ -0,0 +1,213 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `useShellOffer` — the one hook both sidebars call.
+ *
+ * The pure decision table is pinned next door; what this file covers is the
+ * WIRING, which is where the reported bug lived: an APK two versions behind a
+ * running server drew no button, and no unit test of `shouldOfferShellDownload`
+ * could have seen it, because the hook never asked the server at all.
+ *
+ * Three facts it reads, and each has been wrong at some point:
+ *
+ * 1. the MOBILE shell's version, from the bootstrap the server wrote for this
+ *    request (the `KabmoAndroid/<v>` token);
+ * 2. the DESKTOP shell's version, from the bridge identity injected before the
+ *    first script — a desktop app carries no UA token;
+ * 3. the release itself, fetched from the shell's own route, with the desktop
+ *    trio sharing one endpoint and an explicit `kind`.
+ */
+
+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 { useShellOffer } from '@/client/hooks/ui/updates/shell-download';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+
+let container: HTMLElement;
+
+/** The payload every route answers in these cases. */
+const RELEASE = {
+  url: 'https://github.com/kabmo-labs/kabmo/releases/download/v0.7.0/Kabmo-0.6.0-android.apk',
+  latest: '0.6.0',
+  releaseUrl: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.7.0',
+  direct: true,
+};
+
+function Harness({ fetchImpl }: { fetchImpl: typeof fetch }) {
+  const offer = useShellOffer(fetchImpl);
+  return h('span', { id: 'offer' }, offer ? `${offer.kind}:${offer.platform}:${offer.latest}` : 'none');
+}
+
+/** A fetch double that answers the release payload and records the URLs asked. */
+function stubFetch(asked: string[]) {
+  return (async (input: string | URL | Request) => {
+    asked.push(String(input));
+    return { ok: true, json: async () => RELEASE } as Response;
+  }) as unknown as typeof fetch;
+}
+
+async function mount(fetchImpl: typeof fetch): Promise<string> {
+  await act(async () => {
+    render(h(Harness, { fetchImpl }), container);
+  });
+  // The probe is an effect: let its promise settle and re-render.
+  for (let i = 0; i < 20; i += 1) await act(async () => {});
+  return container.querySelector('#offer')?.textContent ?? '';
+}
+
+/** Install a bootstrap and (optionally) a bridge identity on the page. */
+function shell(options: { bootstrap?: Record<string, unknown>; desktop?: Record<string, unknown> }): void {
+  const page = globalThis as unknown as {
+    window: {
+      __OMP_BOOTSTRAP__?: Record<string, unknown>;
+      __kabmoDesktop?: Record<string, unknown>;
+    };
+  };
+  delete page.window.__OMP_BOOTSTRAP__;
+  delete page.window.__kabmoDesktop;
+  if (options.bootstrap) page.window.__OMP_BOOTSTRAP__ = options.bootstrap;
+  if (options.desktop) page.window.__kabmoDesktop = options.desktop;
+}
+
+beforeAll(() => {
+  installDomGlobals(new Window({ url: 'http://localhost' }));
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  act(() => render(null, container));
+  shell({});
+});
+
+afterAll(() => {
+  container.remove();
+  restoreDomGlobals();
+});
+
+describe('the Android shell', () => {
+  test('offers an update when the APK is behind the published asset', async () => {
+    // The reported incident: server v0.7.0, APK v0.5.0, published 0.6.0, and
+    // the sidebar drew nothing because the probe answered `null`.
+    shell({ bootstrap: { shellVersion: '0.5.0', isAndroid: true } });
+    const asked: string[] = [];
+
+    expect(await mount(stubFetch(asked))).toBe('update:android:0.6.0');
+    expect(asked, 'the Android route').toEqual(['/api/updates/android']);
+  });
+
+  test('offers nothing when the APK is the published build', async () => {
+    shell({ bootstrap: { shellVersion: '0.6.0', isAndroid: true } });
+    expect(await mount(stubFetch([]))).toBe('none');
+  });
+
+  test('offers an INSTALL to a browser on Android, and nothing on a desktop browser', async () => {
+    shell({ bootstrap: { isAndroid: true } });
+    expect(await mount(stubFetch([]))).toBe('install:android:0.6.0');
+
+    shell({ bootstrap: { isAndroid: false } });
+    expect(await mount(stubFetch([]))).toBe('none');
+  });
+});
+
+describe('the iOS shell', () => {
+  test('reads its own token and its own route', async () => {
+    shell({ bootstrap: { iosShellVersion: '0.1.0' } });
+    const asked: string[] = [];
+
+    expect(await mount(stubFetch(asked))).toBe('update:ios:0.6.0');
+    expect(asked).toEqual(['/api/updates/ios']);
+  });
+
+  test('an iOS browser is offered nothing, because an IPA cannot be installed from a page', async () => {
+    shell({ bootstrap: {} });
+    expect(await mount(stubFetch([]))).toBe('none');
+  });
+});
+
+describe('the desktop shells', () => {
+  test('reads the version from the bridge and the route from the kind', async () => {
+    // No bootstrap token at all: a desktop app reports itself over the bridge,
+    // and the console had no way to read it before this.
+    shell({ desktop: { platform: 'macos', shellVersion: '0.1.0', overlayTitlebar: true } });
+    const asked: string[] = [];
+
+    expect(await mount(stubFetch(asked))).toBe('update:macos:0.6.0');
+    expect(asked).toEqual(['/api/updates/desktop?kind=macos']);
+  });
+
+  test('each desktop shell asks for its own kind', async () => {
+    for (const platform of ['windows', 'linux'] as const) {
+      shell({ desktop: { platform, shellVersion: '0.1.0' } });
+      const asked: string[] = [];
+      await mount(stubFetch(asked));
+      expect(asked, platform).toEqual([`/api/updates/desktop?kind=${platform}`]);
+    }
+  });
+
+  test('a current desktop build offers nothing', async () => {
+    shell({ desktop: { platform: 'windows', shellVersion: '0.6.0' } });
+    expect(await mount(stubFetch([]))).toBe('none');
+  });
+
+  test('a browser on a desktop is offered nothing', async () => {
+    shell({ bootstrap: { isAndroid: false } });
+    expect(await mount(stubFetch([]))).toBe('none');
+  });
+
+  test('the desktop identity wins over a mobile token, because that is the shell asking', async () => {
+    // A page cannot carry both in practice, and if it somehow did the desktop
+    // app is the process whose version is being compared.
+    shell({
+      bootstrap: { shellVersion: '0.1.0', isAndroid: true },
+      desktop: { platform: 'linux', shellVersion: '0.1.0' },
+    });
+    expect(await mount(stubFetch([]))).toBe('update:linux:0.6.0');
+  });
+
+  /**
+   * A shell that reports its architecture asks for THAT machine's artifact.
+   *
+   * Without it the console can only answer the release page — every desktop
+   * artifact is per-architecture — so the offer is a link a human follows instead
+   * of an update the shell installs.
+   */
+  test('reports the arch, so the answer is a file rather than a page', async () => {
+    shell({ desktop: { platform: 'macos', shellVersion: '0.1.0', arch: 'arm64' } });
+    const asked: string[] = [];
+
+    await mount(stubFetch(asked));
+    expect(asked).toEqual(['/api/updates/desktop?kind=macos&arch=arm64']);
+  });
+
+  test('a shell with no arch still asks, and gets the page', async () => {
+    // An older shell must keep working: the offer degrades to the release page
+    // instead of disappearing.
+    shell({ desktop: { platform: 'macos', shellVersion: '0.1.0' } });
+    const asked: string[] = [];
+
+    await mount(stubFetch(asked));
+    expect(asked).toEqual(['/api/updates/desktop?kind=macos']);
+  });
+
+  test('a refused probe draws no button', async () => {
+    shell({ desktop: { platform: 'macos', shellVersion: '0.1.0' } });
+    const refusing = (async () => ({ ok: false, json: async () => ({}) }) as Response) as unknown as typeof fetch;
+    expect(await mount(refusing)).toBe('none');
+  });
+
+  test('a payload with no artifact draws no button', async () => {
+    shell({ desktop: { platform: 'macos', shellVersion: '0.1.0' } });
+    const empty = (async () =>
+      ({
+        ok: true,
+        json: async () => ({ url: null, latest: null, releaseUrl: null }),
+      }) as Response) as unknown as typeof fetch;
+    expect(await mount(empty)).toBe('none');
+  });
+});

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');
+  });
+});