@kabmo-labs/kabmo 0.1.0 → 0.3.0

package/src/client/hooks/chat/timeline/scroll.test.ts

@@ -17,179 +17,37 @@
  *    pinned (a prepended window, a late Shiki/mermaid/image layout), so a jump
  *    target measured a frame earlier — or at open time — was stranded.
  *
- * Runs against a real DOM (happy-dom) because these are Preact hooks; geometry
- * is faked on the container, since happy-dom does no layout.
+ * The reading-back hysteresis is its own file (`scroll-reading-back.test.ts`),
+ * because the two halves of that contract — the composer shrinking and the
+ * threshold that releases it — are a different feature from the follow gate.
  */
 
 import { afterAll, beforeAll, describe, expect, jest as fakeTimers, test } from 'bun:test';
-import { Window } from 'happy-dom';
-import type { h as PreactH, render as PreactRender } from 'preact';
-import type { act as PreactAct } from 'preact/test-utils';
-import type { useChatTimelineScroll as UseScroll, ChatTimelineScrollResult } from '@/client/hooks/chat/timeline/scroll';
-import type { useTimelineAutoScroll as UseAuto } from '@/client/hooks/chat/timeline/auto-scroll';
-import type { ChatMessageData } from '@/shared/types';
+import type { ScrollProbe } from '@/client/hooks/chat/timeline/scroll-probe.test-util';
 
-let useChatTimelineScroll: typeof UseScroll;
-let useTimelineAutoScroll: typeof UseAuto;
-let h: typeof PreactH;
-let render: typeof PreactRender;
-let act: typeof PreactAct;
-
-let win: Window;
-const scrolled: Array<{ top: number; behavior?: ScrollBehavior }> = [];
-const geometry = { top: 0, height: 5000, viewport: 500 };
-
-/** Observe what the hook asks for; 'instant' also lands (a smooth scroll would
- *  animate in a browser, so the fake keeps it as a recorded intent only). */
-function applyTop(el: HTMLDivElement, value: number) {
-  geometry.top = Math.max(0, Math.min(value, geometry.height - geometry.viewport));
-  // The global `Event` the hook's listener expects: happy-dom's, installed
-  // into globalThis in beforeAll.
-  el.dispatchEvent(new Event('scroll'));
-}
-
-function installScroller(el: HTMLDivElement) {
-  Object.defineProperty(el, 'scrollHeight', { get: () => geometry.height, configurable: true });
-  Object.defineProperty(el, 'clientHeight', { get: () => geometry.viewport, configurable: true });
-  Object.defineProperty(el, 'scrollTop', {
-    get: () => geometry.top,
-    set: (value: number) => applyTop(el, value),
-    configurable: true,
-  });
-  Object.defineProperty(el, 'scrollTo', {
-    value: (options: { top: number; behavior?: ScrollBehavior }) => {
-      scrolled.push(options);
-      if (options.behavior !== 'smooth') applyTop(el, options.top);
-    },
-    configurable: true,
-  });
-}
-
-/** ResizeObserver the tests drive by hand — the hook rebuilds one per content
- *  node, so the last instance of the current mount is the live one. */
-class StubResizeObserver {
-  static instances: StubResizeObserver[] = [];
-  static latest(): StubResizeObserver { return StubResizeObserver.instances[StubResizeObserver.instances.length - 1]; }
-  constructor(private readonly callback: () => void) {
-    StubResizeObserver.instances.push(this);
-  }
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-  fire() { this.callback(); }
-}
-
-/** Frame callbacks the hook's observer deferred; index 0 is handle 1. */
-const pendingFrames: Array<(() => void) | null> = [];
-
-/**
- * Drain the deferred frames. The resize-driven pin is deliberately NOT applied
- * inside the ResizeObserver delivery — a layout write there makes the browser
- * re-run its observers in the same frame, and past its depth limit it reports
- * "ResizeObserver loop completed with undelivered notifications." — so a test
- * that fires an observer has to let the frame it scheduled run before the
- * geometry it asserts on has been applied.
- */
-async function flushFrames() {
-  for (let i = 0; i < pendingFrames.length; i++) {
-    const callback = pendingFrames[i];
-    pendingFrames[i] = null;
-    if (!callback) continue;
-    await act(async () => { callback(); });
-  }
-  pendingFrames.length = 0;
-}
-
-interface ProbeProps {
-  sessionId: string;
-  messages: ChatMessageData[];
-  /** Holder owned by ONE test: a stale tree can only write its own hook result. */
-  holder: { current: ChatTimelineScrollResult | null };
-}
-
-function Probe(props: ProbeProps) {
-  const scroll = useChatTimelineScroll({});
-  useTimelineAutoScroll({
-    sessionId: props.sessionId,
-    messages: props.messages,
-    scrollRef: scroll.scrollRef,
-    jumpToBottom: scroll.jumpToBottom,
-    enabled: true,
-  });
-  props.holder.current = scroll;
-  return h('div', { ref: scroll.scrollRef, onScroll: scroll.handleScroll },
-    h('div', { ref: scroll.contentRef }));
-}
-
-interface ProbeHandle {
-  holder: { current: ChatTimelineScrollResult | null };
-  node: HTMLDivElement;
-  el: HTMLDivElement;
-}
-
-const message = (id: string) => ({ id, role: 'user', content: id } as unknown as ChatMessageData);
-
-/** Fresh mount, own container: `follow`, the jump counter and the observers are
- *  per-hook state, so sharing them across tests would hide the behaviour. */
-async function mountProbe(sessionId: string, messages: ChatMessageData[]): Promise<ProbeHandle> {
-  const holder: ProbeHandle['holder'] = { current: null };
-  const node = document.createElement('div');
-  document.body.appendChild(node);
-  await act(async () => { render(h(Probe, { sessionId, messages, holder }), node); });
-  const el = holder.current!.scrollRef.current!;
-  installScroller(el);
-  return { holder, node, el };
-}
-
-/** Re-render with new props: a session switch, then that session's history. */
-async function updateProbe(probe: ProbeHandle, sessionId: string, messages: ChatMessageData[]) {
-  await act(async () => {
-    render(h(Probe, { sessionId, messages, holder: probe.holder }), probe.node);
-  });
-}
-
-async function unmountProbe(probe: ProbeHandle) {
-  await act(async () => { render(null, probe.node); });
-  probe.node.remove();
-}
+let p: ScrollProbe;
 
 beforeAll(async () => {
-  win = new Window({ url: 'http://localhost' });
-  for (const key of ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'Event'] as const) {
-    (globalThis as Record<string, unknown>)[key] = (win as unknown as Record<string, unknown>)[key];
-  }
-  (globalThis as Record<string, unknown>).ResizeObserver = StubResizeObserver;
-  // The hook defers its resize-driven pin by one frame, and happy-dom's own rAF
-  // never runs without a real event loop, so the queue is drained by hand:
-  // `flushFrames()` runs whatever a delivery scheduled.
-  (globalThis as Record<string, unknown>).requestAnimationFrame = (cb: () => void) => pendingFrames.push(cb);
-  (globalThis as Record<string, unknown>).cancelAnimationFrame = (handle: number) => {
-    pendingFrames[handle - 1] = null;
-  };
-  // Static imports cannot work here: Preact binds its environment at module
-  // evaluation time, so the modules below must load after those DOM globals.
-  ({ useChatTimelineScroll } = await import('@/client/hooks/chat/timeline/scroll'));
-  ({ useTimelineAutoScroll } = await import('@/client/hooks/chat/timeline/auto-scroll'));
-  ({ h, render } = await import('preact'));
-  ({ act } = await import('preact/test-utils'));
+  // Dynamic: the harness installs the DOM globals BEFORE Preact and the hooks
+  // evaluate, which a static import would pre-empt (see the harness header).
+  const { setupScrollProbe } = await import('@/client/hooks/chat/timeline/scroll-probe.test-util');
+  p = await setupScrollProbe();
 });
 
 afterAll(() => {
-  for (const key of ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'Event', 'ResizeObserver']) {
-    delete (globalThis as Record<string, unknown>)[key];
-  }
+  p.teardown();
 });
 
 describe('timeline scroll', () => {
   test('opening a session jumps to the tail even after the user scrolled up', async () => {
-    scrolled.length = 0;
-    geometry.top = 0;
-    geometry.height = 5000;
-    const probe = await mountProbe('a', [message('a1')]);
+    p.scrolled.length = 0;
+    p.geometry.top = 0;
+    p.geometry.height = 5000;
+    const probe = await p.mountProbe('a', [p.message('a1')]);
     const scroll = () => probe.holder.current!;
 
-    await updateProbe(probe, 'a', [message('a1'), message('a2')]);
-    expect(probe.el.scrollTop).toBe(geometry.height - geometry.viewport);
+    await p.updateProbe(probe, 'a', [p.message('a1'), p.message('a2')]);
+    expect(probe.el.scrollTop).toBe(p.geometry.height - p.geometry.viewport);
 
     // The user reads back — follow disengages, and that state outlives the
     // session it was set in.
@@ -198,123 +56,123 @@ describe('timeline scroll', () => {
 
     // Session switch: the container paints empty first (the skeleton), the
     // committed history lands a commit later.
-    await updateProbe(probe, 'b', []);
-    scrolled.length = 0;
-    await updateProbe(probe, 'b', [message('b1')]);
+    await p.updateProbe(probe, 'b', []);
+    p.scrolled.length = 0;
+    await p.updateProbe(probe, 'b', [p.message('b1')]);
 
     expect(scroll().followRef.current).toBe(true);
-    expect(scrolled.length).toBe(1);
-    expect(scrolled[0].behavior).toBe('instant');
-    expect(scrolled[0].top).toBe(geometry.height);
-    expect(probe.el.scrollTop).toBe(geometry.height - geometry.viewport);
-    await unmountProbe(probe);
+    expect(p.scrolled.length).toBe(1);
+    expect(p.scrolled[0].behavior).toBe('instant');
+    expect(p.scrolled[0].top).toBe(p.geometry.height);
+    expect(probe.el.scrollTop).toBe(p.geometry.height - p.geometry.viewport);
+    await p.unmountProbe(probe);
   });
 
   test('a stream chunk may not move an unpinned viewport, a jump may', async () => {
-    scrolled.length = 0;
-    geometry.top = 0;
-    geometry.height = 5000;
-    const probe = await mountProbe('a', [message('a1')]);
+    p.scrolled.length = 0;
+    p.geometry.top = 0;
+    p.geometry.height = 5000;
+    const probe = await p.mountProbe('a', [p.message('a1')]);
     const scroll = () => probe.holder.current!;
 
-    await act(async () => { scroll().jumpToBottom('instant'); });
+    await p.act(() => { scroll().jumpToBottom('instant'); });
     expect(scroll().followRef.current).toBe(true);
-    expect(probe.el.scrollTop).toBe(geometry.height - geometry.viewport);
+    expect(probe.el.scrollTop).toBe(p.geometry.height - p.geometry.viewport);
     expect(scroll().jumpCountRef.current).toBe(1);
     expect(scroll().jumpActiveRef.current).toBe(true);
 
     // The user reads back. A stream chunk must not yank the viewport down...
     probe.el.scrollTop = 100;
     expect(scroll().followRef.current).toBe(false);
-    scrolled.length = 0;
-    await act(async () => { scroll().scrollToBottom('smooth'); });
-    expect(scrolled.length).toBe(0);
+    p.scrolled.length = 0;
+    await p.act(() => { scroll().scrollToBottom('smooth'); });
+    expect(p.scrolled.length).toBe(0);
 
     // ...while the explicit jump bypasses the gate and re-engages it.
-    await act(async () => { scroll().jumpToBottom('instant'); });
-    expect(scrolled.length).toBe(1);
+    await p.act(() => { scroll().jumpToBottom('instant'); });
+    expect(p.scrolled.length).toBe(1);
     expect(scroll().followRef.current).toBe(true);
-    expect(probe.el.scrollTop).toBe(geometry.height - geometry.viewport);
+    expect(probe.el.scrollTop).toBe(p.geometry.height - p.geometry.viewport);
     expect(scroll().jumpCountRef.current).toBe(2);
-    await unmountProbe(probe);
+    await p.unmountProbe(probe);
   });
 
   test('the jump guard releases so history paging is not blocked for good', async () => {
-    scrolled.length = 0;
-    geometry.top = 0;
-    geometry.height = 5000;
-    const probe = await mountProbe('a', [message('a1')]);
+    p.scrolled.length = 0;
+    p.geometry.top = 0;
+    p.geometry.height = 5000;
+    const probe = await p.mountProbe('a', [p.message('a1')]);
     const scroll = () => probe.holder.current!;
 
     fakeTimers.useFakeTimers();
-    await act(async () => { scroll().jumpToBottom('instant'); });
+    await p.act(() => { scroll().jumpToBottom('instant'); });
     expect(scroll().jumpActiveRef.current).toBe(true);
 
-    await act(async () => { fakeTimers.advanceTimersByTime(1000); });
+    await p.act(() => { fakeTimers.advanceTimersByTime(1000); });
     expect(scroll().jumpActiveRef.current).toBe(false);
     fakeTimers.useRealTimers();
-    await unmountProbe(probe);
+    await p.unmountProbe(probe);
   });
 
   test('content growing while pinned re-pins the tail; while reading it does not', async () => {
-    scrolled.length = 0;
-    geometry.top = 0;
-    geometry.height = 5000;
-    const probe = await mountProbe('a', [message('a1')]);
+    p.scrolled.length = 0;
+    p.geometry.top = 0;
+    p.geometry.height = 5000;
+    const probe = await p.mountProbe('a', [p.message('a1')]);
     const scroll = () => probe.holder.current!;
 
-    await updateProbe(probe, 'a', [message('a1')]);
-    expect(probe.el.scrollTop).toBe(geometry.height - geometry.viewport);
+    await p.updateProbe(probe, 'a', [p.message('a1')]);
+    expect(probe.el.scrollTop).toBe(p.geometry.height - p.geometry.viewport);
 
     // A prepended window / a late layout: the tail moved down by 800px.
-    geometry.height += 800;
-    const observer = StubResizeObserver.latest();
-    scrolled.length = 0;
-    await act(async () => { observer.fire(); });
+    p.geometry.height += 800;
+    const observer = p.StubResizeObserver.latest();
+    p.scrolled.length = 0;
+    await p.act(() => { observer.fire(); });
     // The delivery itself writes nothing — that is the loop fix.
-    expect(scrolled.length).toBe(0);
-    await flushFrames();
-    expect(scrolled.length).toBe(1);
-    expect(scrolled[0].behavior).toBe('instant');
-    expect(probe.el.scrollTop).toBe(geometry.height - geometry.viewport);
+    expect(p.scrolled.length).toBe(0);
+    await p.flushFrames();
+    expect(p.scrolled.length).toBe(1);
+    expect(p.scrolled[0].behavior).toBe('instant');
+    expect(probe.el.scrollTop).toBe(p.geometry.height - p.geometry.viewport);
 
     // Reading back: the same growth must leave the viewport alone.
     probe.el.scrollTop = 400;
-    scrolled.length = 0;
-    geometry.height += 800;
-    await act(async () => { StubResizeObserver.latest().fire(); });
-    await flushFrames();
-    expect(scrolled.length).toBe(0);
+    p.scrolled.length = 0;
+    p.geometry.height += 800;
+    await p.act(() => { p.StubResizeObserver.latest().fire(); });
+    await p.flushFrames();
+    expect(p.scrolled.length).toBe(0);
     expect(probe.el.scrollTop).toBe(400);
     expect(scroll().followRef.current).toBe(false);
-    await unmountProbe(probe);
+    await p.unmountProbe(probe);
   });
 
   test('a delivery storm collapses to one pin, and none of them writes inside the delivery', async () => {
-    scrolled.length = 0;
-    geometry.top = 0;
-    geometry.height = 5000;
-    const probe = await mountProbe('a', [message('a1')]);
+    p.scrolled.length = 0;
+    p.geometry.top = 0;
+    p.geometry.height = 5000;
+    const probe = await p.mountProbe('a', [p.message('a1')]);
 
-    await updateProbe(probe, 'a', [message('a1')]);
-    scrolled.length = 0;
+    await p.updateProbe(probe, 'a', [p.message('a1')]);
+    p.scrolled.length = 0;
 
     // A panel-width transition delivers a new box every frame. Each delivery
     // used to write `scrollTop` synchronously, which is what made the browser
     // re-run its observers within the frame and eventually report a
     // ResizeObserver loop; the deferred pin coalesces the whole burst into one.
-    const observer = StubResizeObserver.latest();
-    geometry.height += 800;
-    await act(async () => { observer.fire(); });
-    geometry.height += 800;
-    await act(async () => { observer.fire(); });
-    geometry.height += 800;
-    await act(async () => { observer.fire(); });
-    expect(scrolled.length).toBe(0);
-
-    await flushFrames();
-    expect(scrolled.length).toBe(1);
-    expect(probe.el.scrollTop).toBe(geometry.height - geometry.viewport);
-    await unmountProbe(probe);
+    const observer = p.StubResizeObserver.latest();
+    p.geometry.height += 800;
+    await p.act(() => { observer.fire(); });
+    p.geometry.height += 800;
+    await p.act(() => { observer.fire(); });
+    p.geometry.height += 800;
+    await p.act(() => { observer.fire(); });
+    expect(p.scrolled.length).toBe(0);
+
+    await p.flushFrames();
+    expect(p.scrolled.length).toBe(1);
+    expect(probe.el.scrollTop).toBe(p.geometry.height - p.geometry.viewport);
+    await p.unmountProbe(probe);
   });
 });

package/src/client/hooks/chat/timeline/scroll.ts

@@ -33,6 +33,20 @@ import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
 /** Distance from the tail, in pixels, that still counts as "at the bottom". */
 const FOLLOW_BOTTOM_THRESHOLD_PX = 100;
 
+/**
+ * How much further back the reader must be for a phone composer to give its
+ * height back, on top of {@link FOLLOW_BOTTOM_THRESHOLD_PX}.
+ *
+ * This is hysteresis, and it is load-bearing: shrinking the composer grows the
+ * scroller's viewport by the height it gave back (68 → 44px, i.e. 24px), which
+ * by itself moves the reader 24px CLOSER to the tail. Without the margin a
+ * reader sitting just past the threshold would shrink the box, land inside the
+ * threshold, restore it, and land outside it again — a loop that re-renders the
+ * composer forever. The margin exceeds the give-back, so a compaction can never
+ * cross back over the restore threshold on its own.
+ */
+const COMPACT_TRIGGER_PX = FOLLOW_BOTTOM_THRESHOLD_PX + 64;
+
 /** How long a bottom jump counts as settling. The scroll handler reads "the
  *  viewport is at the top, fetch older history" from geometry, and a jump that
  *  STARTS at the top (the button, on a session scrolled back to its head)
@@ -51,6 +65,14 @@ export interface ChatTimelineScrollResult {
   /** Attach to the timeline's inner content wrapper so its growth is observed. */
   contentRef: (node: HTMLDivElement | null) => void;
   showScrollBottom: boolean;
+  /**
+   * The reader is back through the transcript, with hysteresis: it engages
+   * further from the tail than {@link showScrollBottom} does and releases at
+   * the same distance, so a surface that CHANGES SIZE in response cannot
+   * oscillate around the threshold. A phone composer uses it to give its height
+   * back to the conversation.
+   */
+  readingBack: boolean;
   /** Streaming auto-scroll gates on this: pinned to the tail = true. */
   followRef: RefObject<boolean>;
   /** Bottom jumps issued so far. A paging request stamps its viewport anchor
@@ -82,6 +104,11 @@ export function useChatTimelineScroll(options: ChatTimelineScrollOptions = {}):
   const scrollRef = useRef<HTMLDivElement>(null);
   const [contentNode, setContentNode] = useState<HTMLDivElement | null>(null);
   const [showScrollBottom, setShowScrollBottom] = useState(false);
+  // Hysteretic twin of `showScrollBottom` (see `ChatTimelineScrollResult`): it
+  // engages past `COMPACT_TRIGGER_PX` and releases at
+  // `FOLLOW_BOTTOM_THRESHOLD_PX`, so a consumer that resizes itself in
+  // response cannot flip the flag back and forth.
+  const [readingBack, setReadingBack] = useState(false);
   // True while the viewport is (or should stay) pinned to the tail. A ref, not
   // state: scroll chunks read it every frame and a flip must not re-render.
   const followRef = useRef(true);
@@ -111,7 +138,12 @@ export function useChatTimelineScroll(options: ChatTimelineScrollOptions = {}):
   const syncFollowBottom = useCallback(() => {
     const el = scrollRef.current;
     if (!el) return;
-    setShowScrollBottom(el.scrollHeight - el.scrollTop - el.clientHeight >= FOLLOW_BOTTOM_THRESHOLD_PX);
+    const distance = el.scrollHeight - el.scrollTop - el.clientHeight;
+    setShowScrollBottom(distance >= FOLLOW_BOTTOM_THRESHOLD_PX);
+    // Two thresholds, one direction each: engaged further back, released at
+    // the tail. The setter is called with the SAME value on every scroll that
+    // does not cross one of them, and React bails out of that render.
+    setReadingBack((wasReading) => (wasReading ? distance >= FOLLOW_BOTTOM_THRESHOLD_PX : distance >= COMPACT_TRIGGER_PX));
   }, []);
 
   const handleScroll = useCallback(() => {
@@ -216,6 +248,7 @@ export function useChatTimelineScroll(options: ChatTimelineScrollOptions = {}):
     scrollRef,
     contentRef,
     showScrollBottom,
+    readingBack,
     followRef,
     jumpCountRef,
     jumpActiveRef,

package/src/client/hooks/ui/media-query.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Whether the viewport is at least `px` wide, subscribed.
+ *
+ * The phone header decides from this whether its controls fit in the row or
+ * have to fold into a `⋯` menu, and that decision cannot be a CSS breakpoint:
+ * the row's contents are COMPONENTS (a reload button, a sign-out control that
+ * only exists when a password is set, plugin header slots), and a class that
+ * hides one of them leaves it mounted and focusable while invisible. A hook
+ * returns a boolean the caller branches on, so a folded control is not
+ * rendered at all.
+ *
+ * Subscribed rather than read once, for the reason `useTouchDevice` is: a phone
+ * rotates, a desktop window is dragged, and a split-screen tablet changes width
+ * without a reload.
+ */
+
+import { useEffect, useState } from 'preact/hooks';
+
+export function useViewportAtLeast(px: number): boolean {
+  const query = `(min-width: ${px}px)`;
+  const [matches, setMatches] = useState(() =>
+    typeof window === 'undefined' ? false : window.matchMedia(query).matches,
+  );
+
+  useEffect(() => {
+    const media = window.matchMedia(query);
+    const update = () => setMatches(media.matches);
+    // The query can change while the effect is not subscribed — a render that
+    // happened before the media query existed — so read it once on the way in.
+    update();
+    media.addEventListener('change', update);
+    return () => media.removeEventListener('change', update);
+  }, [query]);
+
+  return matches;
+}

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

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  androidDownloadLabel,
+  parseAndroidRelease,
+  shouldOfferAndroidDownload,
+  type AndroidDownload,
+} from '@/client/hooks/ui/updates/android-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: AndroidDownload = { ...RELEASE, kind: 'update' };
+const INSTALL: AndroidDownload = { ...RELEASE, kind: 'install' };
+
+describe('parseAndroidRelease', () => {
+  test('reads a complete payload', () => {
+    expect(parseAndroidRelease(RELEASE)).toEqual(RELEASE);
+  });
+
+  test('refuses a payload with no asset', () => {
+    // The route answers this on a failed probe. A version without a URL would be
+    // a button that downloads nothing.
+    expect(parseAndroidRelease({ url: null, latest: '1.2.3', releaseUrl: null })).toBeNull();
+    expect(parseAndroidRelease({ url: 'https://x/a.apk', latest: null, releaseUrl: null })).toBeNull();
+  });
+
+  test('refuses a non-object', () => {
+    expect(parseAndroidRelease(null)).toBeNull();
+    expect(parseAndroidRelease('nope')).toBeNull();
+    expect(parseAndroidRelease({})).toBeNull();
+  });
+
+  test('keeps a missing releaseUrl as null', () => {
+    expect(parseAndroidRelease({ url: 'https://x/a.apk', latest: '1.0.0' })?.releaseUrl).toBeNull();
+  });
+});
+
+describe('the offer inside the installed app', () => {
+  test('offers an UPDATE when a newer APK is published', () => {
+    expect(shouldOfferAndroidDownload('1.2.2', true, RELEASE)).toEqual(UPDATE);
+  });
+
+  test('offers nothing when the app is already current', () => {
+    expect(shouldOfferAndroidDownload('1.2.3', true, RELEASE)).toBeNull();
+  });
+
+  test('offers nothing when the app is ahead', () => {
+    // A sideloaded build newer than the published asset: downloading it would be
+    // a downgrade.
+    expect(shouldOfferAndroidDownload('1.3.0', true, RELEASE)).toBeNull();
+  });
+
+  test('offers nothing when the probe failed', () => {
+    expect(shouldOfferAndroidDownload('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(shouldOfferAndroidDownload(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(shouldOfferAndroidDownload(undefined, true, { ...RELEASE, latest: '0.0.1' })).toEqual({
+      ...INSTALL,
+      latest: '0.0.1',
+    });
+  });
+
+  test('offers nothing when no APK is published', () => {
+    expect(shouldOfferAndroidDownload(null, true, null)).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(shouldOfferAndroidDownload(null, false, RELEASE)).toBeNull();
+    expect(shouldOfferAndroidDownload(null, null, RELEASE)).toBeNull();
+    expect(shouldOfferAndroidDownload(null, undefined, RELEASE)).toBeNull();
+    expect(shouldOfferAndroidDownload('', 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(shouldOfferAndroidDownload('1.2.2', false, RELEASE)).toEqual(UPDATE);
+    expect(shouldOfferAndroidDownload('1.2.2', undefined, RELEASE)).toEqual(UPDATE);
+  });
+});
+
+describe('androidDownloadLabel', () => {
+  test('names the verb the reader needs', () => {
+    expect(androidDownloadLabel(UPDATE)).toBe('Update Kabmo 1.2.3 for Android');
+    expect(androidDownloadLabel(INSTALL)).toBe('Install Kabmo 1.2.3 for Android');
+  });
+});