@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/client/components/common/header-controls/shell-chrome.test.tsx

@@ -0,0 +1,272 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The shell chrome the shared cluster must carry, on BOTH layouts.
+ *
+ * Two bugs reached a user, and both are invisible in a browser:
+ *
+ * 1. **`app-region` inherits.** WebView2's own spec says the property inherits,
+ *    and Chromium 152 began enforcing it. So a header marked `app-region: drag`
+ *    turns every descendant into a drag handle — and a drag handle swallows the
+ *    click, silently. The desktop navbar wrapped this cluster in a
+ *    `titlebar-no-drag` div and the PHONE's header did not, so on Windows every
+ *    control in a phone-width window (reload, context, sign out, the right
+ *    panel, `⋯`) looked right and did nothing.
+ * 2. **The page-drawn caption buttons lived in one layout.** A desktop shell
+ *    window can be narrower than `App`'s 768px breakpoint — all three shells
+ *    allow a 720px window — so a Windows/Linux window resized down switches to
+ *    the phone layout, which drew no close/minimise/maximise at all and had no
+ *    native title bar behind them.
+ *
+ * Both are asserted on the RENDERED tree, because both were a call site's
+ * omission: a test reading the component's source would have passed while the
+ * phone stayed broken. macOS is covered too — it keeps its own traffic lights,
+ * so the page must draw no second set.
+ */
+
+import { afterAll, 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 { definePluginApp } from '@kabmo-labs/kabmo-sdk/app';
+import { HeaderControls } from '@/client/components/common/header-controls';
+import { SessionStateProvider } from '@/client/components/common/session-state-provider/index';
+import { registerPluginBundle, resetPluginSlots } from '@/client/lib/plugins/slots';
+import { primeAuthState } from '@/client/hooks/ui/auth';
+import { resetRealtimeClient } from '@/shared/lib/realtime/client';
+import { invalidateModelsCache } from '@/shared/lib/models/client';
+import { sessionTelemetryTopic, TOPIC_PANELS } from '@/shared/lib/realtime/protocol';
+import type { PanelRegistryPayload, SessionContextTelemetry } from '@/shared/types';
+import { startRealtimeTestServer, type RealtimeTestServer } from '@/test-support/realtime-server';
+import { installDomGlobals, pristineWebSocket, restoreDomGlobals } from '@/test-support/pristine-globals';
+import type { TopicResolver } from '@/server/lib/realtime/hub.server';
+
+const SESSION = 'session-shell-chrome';
+const nativeFetch = Bun.fetch;
+const Noop = () => null;
+
+let container: HTMLElement;
+let server: RealtimeTestServer;
+
+const PANELS: PanelRegistryPayload = {
+  panels: [{ pluginId: 'demo', name: 'Demo', version: '1.0.0', appUrl: '/api/panels/bundle/demo.js' }],
+  marketplaces: [],
+  errors: [],
+  plugins: [{ pluginId: 'demo', name: 'Demo', version: '1.0.0', isPackage: true, built: true, enabled: true, bundled: false, gitOrigin: null }],
+  catalog: [],
+  disabledPanels: [],
+  gitStatus: {},
+  autoUpdate: false,
+  syncBlocked: {},
+};
+
+function telemetry(): SessionContextTelemetry {
+  return {
+    sessionId: SESSION,
+    sessionTitle: 'Shell',
+    modelId: 'kenari/deepseek-v4-1-flash',
+    modelName: 'deepseek-v4-1-flash',
+    timestamp: 'today',
+    contextUsed: 12_000,
+    contextLimit: 100_000,
+    contextPercent: 12,
+    messagesCount: 3,
+    userCount: 1,
+    assistantCount: 2,
+    totalCost: 0.01,
+    costFormatted: '$0.01',
+    cacheHitAverage: 90,
+    lastMessage: { input: 10, output: 4, reasoning: 0, cacheRead: 2, cacheWrite: 0, cacheHitPercent: 16.6 },
+    distribution: { userTokens: 1, userPercent: 25, assistantTokens: 1, assistantPercent: 25, toolTokens: 1, toolPercent: 25, otherTokens: 1, otherPercent: 25 },
+    rawMessages: [],
+  };
+}
+
+/** The shell's two globals, which the DOM's own `window` type does not declare. */
+type Shell = {
+  __kabmoCall?: (method: string, params?: Record<string, unknown>) => Promise<unknown>;
+  __kabmoDesktop?: Record<string, unknown>;
+};
+
+
+const WINDOWS = { platform: 'windows', shellVersion: '0.1.0', overlayTitlebar: true, windowControls: true };
+const MACOS = { platform: 'macos', shellVersion: '0.1.0', overlayTitlebar: true, trafficLightInset: '5rem' };
+
+/** Install a shell identity for one case; `afterEach` removes it. */
+function withShell(identity: Record<string, unknown> | null) {
+  // The shell's globals are not in the DOM's `window` type; one cast, at the seam.
+  const shell = window as unknown as Shell;
+  shell.__kabmoCall = async () => null;
+  if (identity) shell.__kabmoDesktop = identity;
+  else delete shell.__kabmoDesktop;
+}
+
+beforeEach(async () => {
+  invalidateModelsCache();
+  const panels: TopicResolver = async () => PANELS;
+  const telemetryTopic: TopicResolver = async () => telemetry();
+  server = await startRealtimeTestServer(new Map<string, TopicResolver>([
+    [TOPIC_PANELS, panels],
+    [sessionTelemetryTopic(SESSION), telemetryTopic],
+  ]));
+  installDomGlobals(new Window({ url: `http://127.0.0.1:${server.port}` }));
+  const target = globalThis as unknown as Record<string, unknown>;
+  target.WebSocket = pristineWebSocket;
+  target.fetch = async (input: unknown) => {
+    const json = (body: unknown) => new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+    const url = String(input);
+    if (url.includes('/api/sessions/')) return json({ state: {} });
+    if (url.includes('/api/telemetry/context')) return json({ telemetry: telemetry() });
+    if (url.includes('/api/models')) return json({ modelList: [], connectedProviders: [] });
+    return json({});
+  };
+  resetPluginSlots();
+  registerPluginBundle('demo', {
+    default: definePluginApp((app) => app.headerPanel({ id: 'h', title: 'Demo Stats', component: Noop })),
+  });
+  primeAuthState(true, true);
+});
+
+afterEach(() => {
+  if (container) {
+    render(null, container);
+    container.remove();
+  }
+  resetPluginSlots();
+  resetRealtimeClient();
+  server?.stop();
+  (globalThis as unknown as Record<string, unknown>).fetch = nativeFetch;
+  const shell = window as unknown as Shell;
+  delete shell.__kabmoDesktop;
+  delete shell.__kabmoCall;
+});
+
+afterAll(() => {
+  restoreDomGlobals();
+});
+
+async function settle(): Promise<void> {
+  await server.waitForTopic(TOPIC_PANELS, (value) => value !== null);
+  await server.waitForTopic(sessionTelemetryTopic(SESSION), (value) => value !== null);
+  for (let i = 0; i < 10; i += 1) await act(async () => {});
+}
+
+/** Every control in the cluster, by its accessible name. */
+function controlNames(): string[] {
+  const names: string[] = [];
+  for (const element of container.querySelectorAll('button, [title]')) {
+    const label = element.getAttribute('aria-label') ?? element.getAttribute('title') ?? '';
+    names.push(label.replace(/ \([^)]*\)$/, ''));
+  }
+  return names;
+}
+
+async function mount(layout: 'desktop' | 'mobile', width: number): Promise<void> {
+  Object.defineProperty(window, 'innerWidth', { value: width, configurable: true, writable: true });
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    render(
+      h(SessionStateProvider, {
+        sessionId: SESSION,
+        children: h(HeaderControls, {
+          layout,
+          sessionId: SESSION,
+          showRightPanel: layout === 'desktop',
+          onToggleRightPanel: () => {},
+        }),
+      }),
+      container,
+    );
+  });
+  await settle();
+}
+
+function unmount(): void {
+  render(null, container);
+  container.remove();
+  container = undefined as unknown as HTMLElement;
+}
+
+/** A desktop shell window is allowed to be 720px — below the 768px breakpoint. */
+const SHELL_MIN_WIDTH = 720;
+const PHONE_WIDTH = 390;
+
+describe('shell chrome', () => {
+  test('the cluster marks itself no-drag on both layouts', async () => {
+    for (const [layout, width] of [['desktop', 1024], ['mobile', PHONE_WIDTH]] as const) {
+      await mount(layout, width);
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.className).toContain('titlebar-no-drag');
+      unmount();
+    }
+  });
+
+  test('a Windows shell draws the caption buttons on both layouts', async () => {
+    withShell(WINDOWS);
+    for (const [layout, width] of [['desktop', 1024], ['mobile', PHONE_WIDTH]] as const) {
+      await mount(layout, width);
+      const names = controlNames();
+      expect(names).toContain('Minimize');
+      expect(names).toContain('Maximize');
+      expect(names).toContain('Close');
+      unmount();
+    }
+  });
+
+  /**
+   * The case the bug was actually reported for: a Windows window at the shell's
+   * own minimum width, which the app renders with the PHONE layout.
+   */
+  test('a Windows window at its minimum width still has its caption buttons', async () => {
+    withShell(WINDOWS);
+    await mount('mobile', SHELL_MIN_WIDTH);
+    const names = controlNames();
+    expect(names).toContain('Close');
+    expect(names).toContain('Minimize');
+  });
+
+  test('a macOS shell draws no caption buttons of its own', async () => {
+    withShell(MACOS);
+    await mount('desktop', 1024);
+    const names = controlNames();
+    expect(names).not.toContain('Minimize');
+    expect(names).not.toContain('Close');
+  });
+
+  /** A browser tab has no shell, so a caption button would be a dead control. */
+  test('a browser draws no caption buttons', async () => {
+    withShell(null);
+    await mount('desktop', 1024);
+    expect(controlNames()).not.toContain('Close');
+  });
+
+  /**
+   * The caption buttons issue the shell's own verbs, from the phone layout too.
+   *
+   * A button that reaches the DOM but never calls the bridge is the same dead
+   * control in a different disguise.
+   */
+  test('a caption click reaches the bridge from the phone layout', async () => {
+    const calls: string[] = [];
+    withShell(WINDOWS);
+    ;(window as unknown as Shell).__kabmoCall = async (method) => {
+      calls.push(method);
+      return null;
+    };
+    await mount('mobile', PHONE_WIDTH);
+    const close = Array.from(container.querySelectorAll('button'))
+      .find((button) => button.getAttribute('aria-label') === 'Close') as HTMLElement;
+    expect(close).toBeTruthy();
+    await act(async () => {
+      close.click();
+    });
+    expect(calls).toContain('window_close');
+  });
+});

package/src/client/components/common/shell-update-button/Modal.tsx

@@ -0,0 +1,163 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The shell update's dialog: confirm, install, report.
+ *
+ * ## Why the message lives HERE and not in the footer
+ *
+ * The footer is a row of controls, one of them 24px wide. A sentence like "Kabmo
+ * 0.3.2 installed — restarting" pushed into that row pushed the controls around
+ * and read as a status line for the SIDEBAR rather than for the update the user
+ * just asked for. The control therefore stays a control, and everything a run has
+ * to say — the confirmation before it, the progress during it, the shell's own
+ * refusal after it — is a dialog.
+ *
+ * ## The confirmation is not ceremony
+ *
+ * The click replaces the app the user is looking at and restarts it. That is not
+ * something a 24px glyph should do on a single press with no words, which is why
+ * the first thing the dialog says is what will happen and what will be lost
+ * (nothing but the window: the servers and the session are the console's own
+ * state, and they survive).
+ *
+ * ## Every phase reports the shell's own words
+ *
+ * `done` and `error` print the sentence the SHELL sent. Nothing here invents
+ * "Update failed": a shell that verified the download and declined knows why, and
+ * that reason is the only thing a user can act on.
+ */
+
+import { AlertCircle, Check, Download, Loader2 } from 'lucide-preact';
+import { Modal } from '@/client/components/common/Modal';
+import {
+  shellDownloadLabel,
+  type ShellDownload,
+} from '@/client/hooks/ui/updates/shell-download';
+import type { ShellUpdatePhase } from '@/client/hooks/ui/updates/shell-update';
+
+/**
+ * What the dialog is showing.
+ *
+ * `confirm` is the dialog's own phase, not the hook's: the hook's `idle` means "no
+ * run has happened", and the dialog is only ever open on a run the user is about to
+ * start or one that already ran.
+ */
+export type ShellUpdateModalPhase = ShellUpdatePhase | 'confirm';
+
+interface ShellUpdateModalProps {
+  download: ShellDownload;
+  phase: ShellUpdateModalPhase;
+  message: string | null;
+  onConfirm: () => void;
+  onClose: () => void;
+}
+
+/** What this platform actually does with the artifact, in the platform's terms. */
+function installNote(download: ShellDownload): string {
+  switch (download.platform) {
+    case 'macos':
+      return 'Kabmo downloads the new build, checks its signature and replaces itself. The window reopens on the new version.';
+    case 'windows':
+      return 'Kabmo downloads the new installer and runs it silently. The window closes and reopens on the new version.';
+    case 'linux':
+      return 'Kabmo downloads the new AppImage over the one it is running from and restarts. A package install (.deb / .rpm) cannot replace itself — that build is offered the release page instead.';
+    default:
+      return 'Kabmo installs the new build and restarts.';
+  }
+}
+
+const SECONDARY =
+  'rounded-md border border-ink/20 px-3 py-1.5 text-[11px] font-medium text-ink transition-colors hover:border-ink/40 cursor-pointer';
+const PRIMARY =
+  'inline-flex items-center gap-1.5 rounded-md bg-ink px-3 py-1.5 text-[11px] font-medium text-paper transition-opacity hover:opacity-90 disabled:opacity-60 disabled:cursor-not-allowed cursor-pointer';
+
+export function ShellUpdateModal({ download, phase, message, onConfirm, onClose }: ShellUpdateModalProps) {
+  const label = shellDownloadLabel(download);
+
+  return (
+    <Modal
+      onClose={onClose}
+      maxWidthClass="max-w-sm"
+      header={<h2 className="text-sm font-semibold text-ink">{label}</h2>}
+      footer={
+        <div className="flex items-center justify-end gap-2 px-5 pb-4">
+          {phase === 'confirm' && (
+            <>
+              <button type="button" className={SECONDARY} onClick={onClose}>
+                Cancel
+              </button>
+              <button type="button" className={PRIMARY} onClick={onConfirm}>
+                <Download size={13} />
+                <span>Install update</span>
+              </button>
+            </>
+          )}
+
+          {phase === 'working' && (
+            <button type="button" className={PRIMARY} disabled>
+              <Loader2 size={13} className="animate-spin motion-reduce:animate-none" />
+              <span>Installing…</span>
+            </button>
+          )}
+
+          {phase === 'done' && (
+            <button type="button" className={PRIMARY} onClick={onClose}>
+              <Check size={13} />
+              <span>Close</span>
+            </button>
+          )}
+
+          {phase === 'error' && (
+            <>
+              <button type="button" className={SECONDARY} onClick={onClose}>
+                Close
+              </button>
+              {/* Retry re-runs the SAME offer: the release is still the one the
+                  console read, and a failure here is the shell's download or its
+                  verification, not a stale version. */}
+              <button type="button" className={PRIMARY} onClick={onConfirm}>
+                <Download size={13} />
+                <span>Try again</span>
+              </button>
+            </>
+          )}
+        </div>
+      }
+    >
+      <div className="px-5 py-4 space-y-3 text-[11px] leading-5 text-ink/70">
+        {phase === 'confirm' && (
+          <>
+            <p>{installNote(download)}</p>
+            <p className="text-ink/50">
+              Version {download.latest} · the console keeps running; only this window restarts.
+            </p>
+          </>
+        )}
+
+        {phase === 'working' && (
+          <p className="flex items-center gap-2 text-ink">
+            <Loader2 size={14} className="animate-spin motion-reduce:animate-none" />
+            <span>Downloading and verifying the new build…</span>
+          </p>
+        )}
+
+        {(phase === 'done' || phase === 'error') && (
+          <p
+            role="status"
+            className={`flex items-start gap-2 ${phase === 'error' ? 'text-error' : 'text-ink'}`}
+          >
+            {phase === 'error' ? (
+              <AlertCircle size={14} className="mt-0.5 shrink-0" />
+            ) : (
+              <Check size={14} className="mt-0.5 shrink-0" />
+            )}
+            <span>{message ?? (phase === 'error' ? 'The update failed.' : 'Update installed.')}</span>
+          </p>
+        )}
+      </div>
+    </Modal>
+  );
+}

package/src/client/components/common/shell-update-button/index.test.tsx

@@ -0,0 +1,251 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The footer control is a CONTROL; every word a run says is in the dialog.
+ *
+ * That split is the whole point of this suite. The footer is a 24px row of glyphs,
+ * and a status sentence pushed into it moved the neighbouring controls and read as
+ * a status line for the SIDEBAR rather than for the update the user just asked for.
+ * So the cases below assert the RENDERED tree in both states, not the module's
+ * constants: a table in a module would pass while the footer rendered something
+ * else.
+ *
+ * Three behaviours are load-bearing and each was a decision:
+ *
+ * 1. **A confirmation comes FIRST.** The click replaces the app and restarts it, so
+ *    a 24px glyph must not do that on a single press with no words.
+ * 2. **`done` and `error` print the SHELL's sentence**, inside the dialog. Nothing
+ *    here invents "Update failed": a shell that verified the download and declined
+ *    knows why, and that reason is the only thing a user can act on.
+ * 3. **A shell that cannot install it gets a LINK**, and the dialog never opens.
+ */
+
+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 { ShellUpdateButton } from '@/client/components/common/shell-update-button';
+import type { ShellDownload } from '@/client/hooks/ui/updates/shell-download';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+
+const DESKTOP: ShellDownload = {
+  url: 'https://github.com/kabmo-labs/kabmo/releases/download/v0.3.2/Kabmo-0.3.2-mac-arm64.zip',
+  latest: '0.3.2',
+  releaseUrl: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.8.0',
+  direct: true,
+  kind: 'update',
+  platform: 'macos',
+};
+
+const PAGE: ShellDownload = { ...DESKTOP, url: 'https://github.com/kabmo-labs/kabmo/releases/tag/v0.8.0', 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;
+}
+
+async function mount(download: ShellDownload): Promise<void> {
+  await act(async () => {
+    render(h(ShellUpdateButton, { download, variant: 'icon' }), container);
+  });
+  for (let i = 0; i < 5; i += 1) await act(async () => {});
+}
+
+/**
+ * The dialog, by its role — the same locator a browser spec would use.
+ *
+ * Queried on `document.body`, not on the render container: the dialog is a PORTAL
+ * (see the component), which is what keeps it out of the footer row's own text.
+ */
+function dialog(): HTMLElement | null {
+  return document.body.querySelector('[role="dialog"]');
+}
+
+/**
+ * Both helpers search the whole body, because the dialog is a PORTAL: its controls
+ * live beside the render container, not inside it. The footer control is inside the
+ * container, which is itself in the body, so one query covers both.
+ */
+function byName(name: string): HTMLElement | null {
+  return document.body.querySelector(`[aria-label="${name}"]`);
+}
+
+function buttonByText(text: string): HTMLElement | null {
+  const buttons = [...document.body.querySelectorAll('button')];
+  return (buttons.find((button) => button.textContent?.trim() === text) as HTMLElement | undefined) ?? null;
+}
+
+async function click(element: HTMLElement | null): Promise<void> {
+  if (!element) throw new Error('nothing to click');
+  await act(async () => {
+    element.click();
+  });
+  for (let i = 0; i < 10; i += 1) await act(async () => {});
+}
+
+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('a shell that can install its own update', () => {
+  test('the dialog is OUTSIDE the footer row, so the row says nothing about a run', async () => {
+    // A dialog rendered inside the footer would put its sentence into the row's own
+    // text content (measured in the browser before the portal: the row read as the
+    // dialog's body). It also has to be a portal for a second reason — the row is a
+    // 24px flex strip, and any `overflow`/`transform` added to it would clip a
+    // `fixed` overlay.
+    bridge(async () => ({ success: true, message: 'ok' }));
+    await mount(DESKTOP);
+    await click(byName('Update Kabmo 0.3.2 for macOS'));
+
+    const modal = document.body.querySelector('[role="dialog"]');
+    expect(modal).not.toBeNull();
+    expect(container.contains(modal)).toBe(false);
+    // The control itself carries no status text in any phase.
+    expect(byName('Update Kabmo 0.3.2 for macOS')?.textContent?.trim()).toBe('');
+  });
+
+  test('draws a button, and opens a CONFIRMATION rather than installing on the press', async () => {
+    const calls: string[] = [];
+    bridge(async (method) => {
+      calls.push(method);
+      return { success: true, version: '0.3.2', message: 'Kabmo 0.3.2 installed — restarting.', relaunching: true };
+    });
+    await mount(DESKTOP);
+
+    const control = byName('Update Kabmo 0.3.2 for macOS');
+    expect(control?.tagName).toBe('BUTTON');
+    // Nothing has been asked of the shell yet — that is the confirmation's job.
+    expect(calls).toEqual([]);
+
+    await click(control);
+    expect(dialog()).not.toBeNull();
+    expect(dialog()?.textContent).toContain('Version 0.3.2');
+    expect(dialog()?.textContent).toContain('replaces itself');
+    // Still nothing: the press opened a dialog, it did not install.
+    expect(calls).toEqual([]);
+  });
+
+  test('installing happens on the dialog’s own button, and the report stays IN the dialog', async () => {
+    const calls: { method: string; params?: Record<string, unknown> }[] = [];
+    bridge(async (method, params) => {
+      calls.push({ method, params });
+      return { success: true, version: '0.3.2', message: 'Kabmo 0.3.2 installed — restarting.', relaunching: true };
+    });
+    await mount(DESKTOP);
+    await click(byName('Update Kabmo 0.3.2 for macOS'));
+    await click(buttonByText('Install update'));
+
+    expect(calls).toEqual([
+      { method: 'update_apply', params: { url: DESKTOP.url, version: '0.3.2' } },
+    ]);
+
+    // The sentence is the SHELL's, and it is inside the dialog.
+    expect(dialog()?.textContent).toContain('Kabmo 0.3.2 installed — restarting.');
+    // …and the footer carries no status line of its own: the control is still a
+    // control, with its own label.
+    expect(byName('Update Kabmo 0.3.2 for macOS')).not.toBeNull();
+  });
+
+  test('a refusal keeps the shell’s reason in the dialog, and offers another try', async () => {
+    bridge(async () => ({ success: false, message: 'The downloaded file is not a signed Kabmo build.' }));
+    await mount(DESKTOP);
+    await click(byName('Update Kabmo 0.3.2 for macOS'));
+    await click(buttonByText('Install update'));
+
+    expect(dialog()?.textContent).toContain('The downloaded file is not a signed Kabmo build.');
+    expect(buttonByText('Try again')).not.toBeNull();
+    expect(buttonByText('Close')).not.toBeNull();
+  });
+
+  test('closing after a failure, then reopening, starts at the confirmation again', async () => {
+    // A dismissed run is not a run: the next press must not greet the user with the
+    // previous attempt's refusal.
+    bridge(async () => ({ success: false, message: 'The download could not be downloaded.' }));
+    await mount(DESKTOP);
+    await click(byName('Update Kabmo 0.3.2 for macOS'));
+    await click(buttonByText('Install update'));
+    await click(buttonByText('Close'));
+    expect(dialog()).toBeNull();
+
+    await click(byName('Update Kabmo 0.3.2 for macOS'));
+    expect(dialog()?.textContent).toContain('Version 0.3.2');
+    expect(dialog()?.textContent).not.toContain('could not be downloaded');
+  });
+
+  test('Cancel closes without asking the shell anything', async () => {
+    const calls: string[] = [];
+    bridge(async (method) => {
+      calls.push(method);
+      return { success: true, message: 'ok' };
+    });
+    await mount(DESKTOP);
+    await click(byName('Update Kabmo 0.3.2 for macOS'));
+    await click(buttonByText('Cancel'));
+
+    expect(dialog()).toBeNull();
+    expect(calls).toEqual([]);
+  });
+});
+
+describe('the phone footer’s variant', () => {
+  test('draws the short label on the same button, and opens the same dialog', async () => {
+    // The two layouts pass different `variant`s because a 24px glyph and a word are
+    // different rows — but they must be the same CONTROL: a link on one layout and a
+    // button on the other is the drift this component exists to prevent.
+    bridge(async () => ({ success: true, version: '0.3.2', message: 'Kabmo 0.3.2 installed — restarting.' }));
+    await act(async () => {
+      render(h(ShellUpdateButton, { download: DESKTOP, variant: 'label' }), container);
+    });
+    for (let i = 0; i < 5; i += 1) await act(async () => {});
+
+    const control = byName('Update Kabmo 0.3.2 for macOS');
+    expect(control?.tagName).toBe('BUTTON');
+    expect(control?.textContent?.trim()).toBe('Update macOS');
+
+    await click(control);
+    expect(dialog()?.textContent).toContain('Version 0.3.2');
+  });
+});
+
+describe('a shell that cannot install it', () => {
+  test('draws a link to the release page, and no dialog', async () => {
+    bridge(async () => null);
+    await mount(PAGE);
+
+    const control = byName('Update Kabmo 0.3.2 for macOS');
+    expect(control?.tagName).toBe('A');
+    expect(control?.getAttribute('href')).toBe(PAGE.url);
+    expect(control?.getAttribute('target')).toBe('_blank');
+
+    await click(control);
+    expect(dialog()).toBeNull();
+  });
+
+  test('a browser draws the link too, because there is no shell to ask', async () => {
+    bridge(null);
+    await mount(DESKTOP);
+
+    expect(byName('Update Kabmo 0.3.2 for macOS')?.tagName).toBe('A');
+    expect(dialog()).toBeNull();
+  });
+});