@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/client/hooks/ui/updates/index.ts

@@ -0,0 +1,254 @@
+/**
+ * Live update state: the check that reports what is available, and the apply
+ * that runs it.
+ *
+ * The apply is a POST whose response is an SSE stream, not a JSON body. An
+ * `omp update` or a Kabmo install runs for minutes; a buffered response
+ * left the console with a spinner and nothing else until it finished, and
+ * discarded the command output the server had already collected. Every frame
+ * the stream carries is folded into `progress`, which survives the modal being
+ * closed — the hook lives on the sidebar, so leaving the dialog no longer hides
+ * the run.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+import { readSseStream } from '@/shared/lib/chat/read-sse';
+import { appendUpdateLog, type UpdateLogState } from '@/shared/lib/updates/progress';
+import { readServerIdentity, waitForServerRestart, RESTART_WAIT_TIMEOUT_MS, type RestartWatchDeps, type ServerIdentity } from '@/client/hooks/ui/updates/restart';
+import type { UpdateApplyResult, UpdateCheckResult, UpdateTarget } from '@/shared/types/updates';
+
+export interface UseUpdatesResult {
+  info: UpdateCheckResult | null;
+  checking: boolean;
+  applying: UpdateTarget | null;
+  /** Log of the run in flight (or the last one), null before any apply. */
+  progress: UpdateLogState | null;
+  error: string | null;
+  hasUpdate: boolean;
+  check: () => Promise<void>;
+  apply: (target: UpdateTarget) => Promise<UpdateApplyResult | null>;
+}
+
+export interface UseUpdatesOptions {
+  /**
+   * Clock/network seam for the post-update restart watch. Injected because the
+   * cases that matter — a replacement that never comes up, an abort — cannot be
+   * produced on demand by a live server.
+   */
+  restart?: RestartWatchDeps;
+}
+
+function responseMessage(payload: unknown, fallback: string): string {
+  if (typeof payload !== 'object' || payload === null) return fallback;
+
+  if ('error' in payload && typeof payload.error === 'string') return payload.error;
+  if ('message' in payload && typeof payload.message === 'string') return payload.message;
+  return fallback;
+}
+
+export function isUpdateApplyResult(payload: unknown): payload is UpdateApplyResult {
+  if (typeof payload !== 'object' || payload === null) return false;
+
+  return (
+    'success' in payload && typeof payload.success === 'boolean' &&
+    'target' in payload && (payload.target === 'kabmo' || payload.target === 'omp') &&
+    'manual' in payload && typeof payload.manual === 'boolean' &&
+    'message' in payload && typeof payload.message === 'string'
+  );
+}
+
+export function useUpdates(options: UseUpdatesOptions = {}): UseUpdatesResult {
+  const { restart: restartDeps } = options;
+  const [info, setInfo] = useState<UpdateCheckResult | null>(null);
+  const [checking, setChecking] = useState(false);
+  const [applying, setApplying] = useState<UpdateTarget | null>(null);
+  const [progress, setProgress] = useState<UpdateLogState | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const inFlightCheckRef = useRef<Promise<void> | null>(null);
+  const didAutoCheckRef = useRef(false);
+  const applyAbortRef = useRef<AbortController | null>(null);
+
+  const check = useCallback(() => {
+    if (inFlightCheckRef.current) return inFlightCheckRef.current;
+
+    const request = (async () => {
+      setChecking(true);
+      setError(null);
+
+      try {
+        const response = await fetch('/api/updates/check');
+        const payload: unknown = await response.json();
+        if (!response.ok) {
+          throw new Error(responseMessage(payload, `Update check failed (HTTP ${response.status})`));
+        }
+        setInfo(payload as UpdateCheckResult);
+      } catch (cause) {
+        setError(cause instanceof Error ? cause.message : 'Unable to check for updates.');
+      } finally {
+        setChecking(false);
+        inFlightCheckRef.current = null;
+      }
+    })();
+
+    inFlightCheckRef.current = request;
+    return request;
+  }, []);
+
+  const apply = useCallback(async (target: UpdateTarget): Promise<UpdateApplyResult | null> => {
+    setApplying(target);
+    setProgress({ lines: [], pending: '', truncated: false });
+    setError(null);
+
+    const controller = new AbortController();
+    applyAbortRef.current = controller;
+    // The fold is mirrored in a local so each frame is one setState, rather
+    // than a read-modify-write against the previous render's state.
+    let log: UpdateLogState = { lines: [], pending: '', truncated: false };
+    // A holder rather than a bare `let`: the result is assigned from inside the
+    // SSE frame callback, which TypeScript's control-flow analysis cannot see,
+    // so a narrowed `null` would be read back here as a value that can never be
+    // set.
+    const applied: { result: UpdateApplyResult | null } = { result: null };
+    // Who is serving this page BEFORE the run. Only a Kabmo update can
+    // replace that process, and the replacement is recognised by answering with
+    // a different `pid`/`startedAt` — so the baseline has to be read while the
+    // old process is still the one answering.
+    let before: ServerIdentity | null = null;
+    // Set when this call ends by navigating to the restarted server. The
+    // spinner stays on: the page is being replaced, and a dialog that flashed
+    // back to idle first would read as "finished" over a navigation still in
+    // flight.
+    let navigating = false;
+
+    try {
+      if (target === 'kabmo') before = await readServerIdentity(restartDeps);
+
+      const response = await fetch('/api/updates/apply', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'text/event-stream' },
+        body: JSON.stringify({ target }),
+        signal: controller.signal,
+      });
+
+      if (!response.ok && !(response.headers.get('content-type') ?? '').includes('text/event-stream')) {
+        const payload: unknown = await response.json().catch(() => null);
+        const message = responseMessage(payload, `Update failed (HTTP ${response.status})`);
+        // 409 is the server saying another run holds the slot. That is a state,
+        // not a failure of this request, so it is reported by toast alone: an
+        // error state would replace the update rows with a block the user
+        // cannot act on, and its Retry only re-checks.
+        if (response.status === 409) return { success: false, target, manual: false, message };
+        throw new Error(message);
+      }
+
+      await readSseStream(
+        response,
+        (event, data) => {
+          if (event === 'line') {
+            log = appendUpdateLog(log, JSON.parse(data) as string);
+            setProgress(log);
+            return;
+          }
+          if (event === 'stage') {
+            // A stage is its own line: the updater's heading and the output
+            // under it must not be glued into one line.
+            log = appendUpdateLog(log, `${JSON.parse(data) as string}\n`);
+            setProgress(log);
+            return;
+          }
+          if (event === 'result') {
+            const payload: unknown = JSON.parse(data);
+            if (isUpdateApplyResult(payload)) {
+              applied.result = payload;
+              // A finished run's output is not a report to come back to. An
+              // update that worked said everything it had to say in its toast,
+              // and an install log left standing is noise the next time the
+              // dialog is opened. A run that FAILED keeps its output: the
+              // reason is in those lines, and the toast carries only a summary.
+              if (payload.success) setProgress(null);
+            }
+          }
+        },
+        controller.signal,
+      );
+
+      const result = applied.result;
+      if (controller.signal.aborted) return result;
+
+      // An armed restart means this page is still being served by the process
+      // whose build was just replaced: re-checking would read the OLD version
+      // back, and reloading right now would fetch the old bundle. So the page
+      // waits for the replacement and then reloads into it — which is the whole
+      // point of updating from the console, since the new build only runs after
+      // a navigation.
+      if (result?.restarting) {
+        // Appended, not replaced: the install output is what a failed restart
+        // has to be read against, and a dialog that swapped it for one line
+        // would erase the only record of what ran.
+        log = appendUpdateLog(log, 'Update installed — waiting for the server to restart on this port…\n');
+        setProgress(log);
+        const outcome = await waitForServerRestart(before, { ...restartDeps, signal: controller.signal });
+        if (outcome === 'restarted') {
+          // The page is going away, so the applying spinner must not be cleared
+          // first: a dialog that flashed back to idle would read as "finished"
+          // over a navigation the user is still waiting on.
+          navigating = true;
+          window.location.reload();
+          return result;
+        }
+        // An abort is the panel going away with the run — the same null the
+        // other abort path returns, so no caller toasts into a torn-down view.
+        if (outcome === 'aborted') return null;
+        if (outcome === 'timeout') {
+          const seconds = Math.round(RESTART_WAIT_TIMEOUT_MS / 1000);
+          return {
+            ...result,
+            restarting: false,
+            message: `${result.message} The server did not come back within ${seconds} seconds — reload this page once it is up.`,
+          };
+        }
+        return result;
+      }
+
+      await check();
+      return result;
+    } catch (cause) {
+      if (controller.signal.aborted) return null;
+      const message = cause instanceof Error ? cause.message : 'Unable to apply the update.';
+      setError(message);
+      // Returned rather than swallowed: the caller's toast is the only surface
+      // the user sees, and a generic "could not be completed" would hide a
+      // refusal the server explained — an update already running, in the case
+      // that matters most, because a reload has just erased this panel's own
+      // record that one was.
+      return { success: false, target, manual: false, message };
+    } finally {
+      // A navigating call leaves `applying` set: the spinner is the only thing
+      // telling the user the console is still working, and it is cleared by the
+      // reload itself.
+      if (!navigating && applyAbortRef.current === controller) {
+        applyAbortRef.current = null;
+        setApplying(null);
+      }
+    }
+  }, [check, restartDeps]);
+
+  useEffect(() => {
+    if (didAutoCheckRef.current) return;
+    didAutoCheckRef.current = true;
+    void check();
+  }, [check]);
+
+  useEffect(() => () => applyAbortRef.current?.abort(), []);
+
+  return {
+    info,
+    checking,
+    applying,
+    progress,
+    error,
+    hasUpdate: Boolean(info?.kabmo.updateAvailable || info?.omp.updateAvailable),
+    check,
+    apply,
+  };
+}

package/src/client/hooks/ui/updates/restart.test.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Recognising the REPLACEMENT server after an update.
+ *
+ * The console may only reload once the process serving it has been replaced —
+ * reloading earlier fetches the OLD bundle back from the process that is still
+ * exiting, and never reloading leaves the user on a stale page. Identity, not a
+ * timer, is what "replaced" means, so these cases pin the identity rules:
+ * a different pid or start time is the new process, a failed probe is not an
+ * answer, and a baseline that could not be read falls back to the uptime
+ * evidence the update's own duration makes safe.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  isReplacement,
+  parseServerIdentity,
+  readServerIdentity,
+  REPLACEMENT_MAX_UPTIME_S,
+  waitForServerRestart,
+  type ServerIdentity,
+} from '@/client/hooks/ui/updates/restart';
+
+const OLD: ServerIdentity = { pid: 100, startedAt: '2026-10-15T00:00:00.000Z', uptime: 3600 };
+
+/** A health responder that hands out one payload per call. */
+function healthFetch(payloads: Array<unknown | Error>): { fetch: typeof fetch; calls: () => number } {
+  let index = 0;
+  const impl = (async () => {
+    const next = payloads[Math.min(index, payloads.length - 1)];
+    index += 1;
+    if (next instanceof Error) throw next;
+    if (next === null) return new Response('{}', { status: 503 });
+    return Response.json(next);
+  }) as unknown as typeof fetch;
+  return { fetch: impl, calls: () => index };
+}
+
+/** No real waiting: the loop is what is under test, not the clock. */
+const noSleep = async (): Promise<void> => {};
+
+describe('parseServerIdentity', () => {
+  test('reads the three fields identity is decided from', () => {
+    expect(parseServerIdentity({ pid: 42, startedAt: 'x', uptime: 1.5 })).toEqual({ pid: 42, startedAt: 'x', uptime: 1.5 });
+  });
+
+  test('a payload naming neither a pid nor a start time identifies nothing', () => {
+    // Treating it as an identity would make every later probe look like a match.
+    expect(parseServerIdentity({ ok: true })).toBeNull();
+    expect(parseServerIdentity(null)).toBeNull();
+    expect(parseServerIdentity('nope')).toBeNull();
+  });
+
+  test('a start time alone is enough, and a pid alone is enough', () => {
+    expect(parseServerIdentity({ startedAt: 'x' })).toEqual({ pid: null, startedAt: 'x', uptime: null });
+    expect(parseServerIdentity({ pid: 7 })).toEqual({ pid: 7, startedAt: null, uptime: null });
+  });
+});
+
+describe('isReplacement', () => {
+  test('a different pid is the replacement', () => {
+    expect(isReplacement(OLD, { pid: 200, startedAt: OLD.startedAt, uptime: 1 })).toBe(true);
+  });
+
+  test('the same pid with a new start time is the replacement', () => {
+    // A recycled pid is still a different process, and its start time says so.
+    expect(isReplacement(OLD, { pid: 100, startedAt: '2026-10-15T01:00:00.000Z', uptime: 1 })).toBe(true);
+  });
+
+  test('the same process answering again is not', () => {
+    expect(isReplacement(OLD, { pid: 100, startedAt: OLD.startedAt, uptime: 3700 })).toBe(false);
+  });
+
+  test('with no baseline, only a young process counts', () => {
+    expect(isReplacement(null, { pid: 1, startedAt: 'x', uptime: REPLACEMENT_MAX_UPTIME_S })).toBe(true);
+    expect(isReplacement(null, { pid: 1, startedAt: 'x', uptime: REPLACEMENT_MAX_UPTIME_S + 1 })).toBe(false);
+    // No uptime to judge by: never claim a restart happened.
+    expect(isReplacement(null, { pid: 1, startedAt: 'x', uptime: null })).toBe(false);
+  });
+});
+
+describe('readServerIdentity', () => {
+  test('a refused or failed probe is null, never an identity', async () => {
+    const refused = healthFetch([null]);
+    expect(await readServerIdentity({ fetch: refused.fetch })).toBeNull();
+
+    const thrown = healthFetch([new Error('connection refused')]);
+    expect(await readServerIdentity({ fetch: thrown.fetch })).toBeNull();
+  });
+
+  test('a payload with no identity is null even when the request succeeded', async () => {
+    const { fetch: impl } = healthFetch([{ ok: true, version: '1.0.0' }]);
+    expect(await readServerIdentity({ fetch: impl })).toBeNull();
+  });
+});
+
+describe('waitForServerRestart', () => {
+  test('resolves once a different process answers, ignoring the old one still serving', async () => {
+    const { fetch: impl, calls } = healthFetch([OLD, { pid: 200, startedAt: '2026-10-15T02:00:00.000Z', uptime: 0.4 }]);
+    const outcome = await waitForServerRestart(OLD, { fetch: impl, sleep: noSleep });
+    expect(outcome).toBe('restarted');
+    expect(calls()).toBe(2);
+  });
+
+  test('a port that answers nothing yet is not a replacement', async () => {
+    // The old server exits and the port is briefly unbound; that gap is the
+    // whole reason this polls instead of reloading on the result frame.
+    const { fetch: impl } = healthFetch([new Error('refused'), OLD, { pid: 300, startedAt: 'z', uptime: 0.1 }]);
+    expect(await waitForServerRestart(OLD, { fetch: impl, sleep: noSleep })).toBe('restarted');
+  });
+
+  test('the same process answering forever is a timeout', async () => {
+    const { fetch: impl } = healthFetch([OLD]);
+    const outcome = await waitForServerRestart(OLD, { fetch: impl, sleep: noSleep, timeoutMs: 0 });
+    expect(outcome).toBe('timeout');
+  });
+
+  test('an aborted wait reports itself instead of claiming a restart', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const { fetch: impl } = healthFetch([OLD]);
+    expect(await waitForServerRestart(OLD, { fetch: impl, sleep: noSleep, signal: controller.signal })).toBe('aborted');
+  });
+});

package/src/client/hooks/ui/updates/restart.ts

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Waiting for the server that answered an update to be REPLACED.
+ *
+ * The update route arms a detached `kabmo restart --port <port>` and
+ * answers first (`RESTART_GRACE_MS`, 1.2 s). So when the result says
+ * `restarting`, the page is still being served by the process whose build was
+ * just replaced: reloading immediately would fetch the OLD bundle back from the
+ * server that has not exited yet, and the user would see the previous version
+ * with no indication that anything went wrong. The page therefore has to wait
+ * for the replacement and only then reload.
+ *
+ * Identity is what "replaced" means, never a timer: `GET /api/health` reports
+ * the serving process's `pid` and `startedAt`, both read before the update
+ * starts, so the new process is the one that answers with a DIFFERENT pair.
+ * A timer would either reload into the dying process (too short) or leave the
+ * user on a stale page after the new one is already up (too long).
+ *
+ * The polling, the clock and the network read are injected, because the only
+ * interesting cases are "the old process still answers", "nothing answers", and
+ * "a different process answers" — none of which a live server can be made to
+ * produce on demand in a unit test.
+ */
+
+/** The facts that identify the process answering `GET /api/health`. */
+export interface ServerIdentity {
+  pid: number | null;
+  startedAt: string | null;
+  /** Seconds since that process started, as `/api/health` reports it. */
+  uptime: number | null;
+}
+
+/** How often the console asks whether the replacement is up. */
+export const RESTART_POLL_INTERVAL_MS = 500;
+
+/**
+ * Ceiling on the whole wait. A restart is a SIGTERM (escalated to SIGKILL after
+ * 5 s) followed by a fresh boot, so anything past this is not a slow start.
+ */
+export const RESTART_WAIT_TIMEOUT_MS = 30_000;
+
+/** One probe's own timeout, so a hung socket cannot stall the loop. */
+export const RESTART_PROBE_TIMEOUT_MS = 2_000;
+
+/**
+ * How young a process has to be to count as the replacement when the baseline
+ * could not be read. The update itself runs for minutes, so the process serving
+ * this page is far older than this by the time a result arrives.
+ */
+export const REPLACEMENT_MAX_UPTIME_S = 15;
+
+export type RestartWatchOutcome = 'restarted' | 'timeout' | 'aborted';
+
+export interface RestartWatchDeps {
+  fetch?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  intervalMs?: number;
+  /** Ceiling on the whole wait. */
+  timeoutMs?: number;
+  /** Ceiling on one probe's own request. */
+  probeTimeoutMs?: number;
+  /**
+   * Stops the wait. Checked between probes, and the probe in flight is bounded
+   * by its own `probeTimeoutMs`, so an abort lands within that ceiling.
+   */
+  signal?: AbortSignal;
+}
+
+/** A `/api/health` payload, narrowed to the fields identity is read from. */
+export function parseServerIdentity(payload: unknown): ServerIdentity | null {
+  if (typeof payload !== 'object' || payload === null) return null;
+  const record = payload as Record<string, unknown>;
+  const pid = typeof record.pid === 'number' && Number.isFinite(record.pid) ? record.pid : null;
+  const startedAt = typeof record.startedAt === 'string' && record.startedAt.length > 0 ? record.startedAt : null;
+  const uptime = typeof record.uptime === 'number' && Number.isFinite(record.uptime) ? record.uptime : null;
+  // A payload naming neither a pid nor a start time identifies nothing, and
+  // treating it as an identity would make every later probe look like a match.
+  if (pid === null && startedAt === null) return null;
+  return { pid, startedAt, uptime };
+}
+
+/**
+ * Whether `current` is a process OTHER than the one `before` describes.
+ *
+ * With a baseline, any disagreement on pid or start time is the replacement —
+ * a restarted process is never the same process. Without one (the health read
+ * before the update failed), a young uptime is the only evidence available, and
+ * it is evidence the update's own duration makes safe: the run takes minutes,
+ * so a process a few seconds old cannot be the one that started it.
+ */
+export function isReplacement(before: ServerIdentity | null, current: ServerIdentity): boolean {
+  if (!before) return current.uptime !== null && current.uptime <= REPLACEMENT_MAX_UPTIME_S;
+  if (before.pid !== null && current.pid !== null && before.pid !== current.pid) return true;
+  if (before.startedAt !== null && current.startedAt !== null && before.startedAt !== current.startedAt) return true;
+  return false;
+}
+
+/** The serving process's identity, or null when it cannot be read. */
+export async function readServerIdentity(deps: RestartWatchDeps = {}): Promise<ServerIdentity | null> {
+  const fetchImpl = deps.fetch ?? fetch;
+  try {
+    const response = await fetchImpl('/api/health', {
+      headers: { accept: 'application/json' },
+      cache: 'no-store',
+      signal: AbortSignal.timeout(deps.probeTimeoutMs ?? RESTART_PROBE_TIMEOUT_MS),
+    });
+    if (!response.ok) return null;
+    return parseServerIdentity(await response.json());
+  } catch {
+    return null;
+  }
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  const { promise, resolve } = Promise.withResolvers<void>();
+  setTimeout(resolve, ms);
+  return promise;
+}
+
+/**
+ * Poll until a process other than `before` answers, the deadline passes, or
+ * `signal` aborts. A failed probe is EXPECTED here — the old server is exiting
+ * and the port is briefly unbound — so only a successful, different answer
+ * counts as the replacement.
+ */
+export async function waitForServerRestart(
+  before: ServerIdentity | null,
+  deps: RestartWatchDeps = {},
+): Promise<RestartWatchOutcome> {
+  const fetchImpl = deps.fetch ?? fetch;
+  const sleep = deps.sleep ?? defaultSleep;
+  const now = deps.now ?? (() => Date.now());
+  const interval = deps.intervalMs ?? RESTART_POLL_INTERVAL_MS;
+  const deadline = now() + (deps.timeoutMs ?? RESTART_WAIT_TIMEOUT_MS);
+
+  for (;;) {
+    if (deps.signal?.aborted) return 'aborted';
+
+    const current = await readServerIdentity({ fetch: fetchImpl, probeTimeoutMs: deps.probeTimeoutMs });
+    if (current && isReplacement(before, current)) return 'restarted';
+
+    if (now() >= deadline) return 'timeout';
+    await sleep(interval);
+  }
+}

package/src/client/hooks/ui/window-chrome.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The client's writer for the PWA window chrome. `shared/lib/theme/chrome.ts`
+ * owns WHY the color is not simply the canvas.
+ *
+ * Two writers hand out that meta tag and they have to agree: the SSR shell
+ * writes it into the served document, and this module re-writes it whenever a
+ * fact behind it moves — the palette (a settings change) or the surface (the
+ * layout mode, a manual layout switch, the login screen). The server's own two
+ * facts (user agent, authentication) are baked into the document, so `main.tsx`
+ * seeds this module from the bootstrap BEFORE the first theme write; without
+ * that seed a phone repaints the tag with the desktop's color for a frame.
+ */
+
+import { DEFAULT_THEME_ID, resolveTheme } from '@/shared/lib/theme/catalog';
+import { windowChromeColor } from '@/shared/lib/theme/chrome';
+
+/** The palette last applied to the document. */
+let themeId: string = DEFAULT_THEME_ID;
+/** The layout on screen; `App` keeps this in step. */
+let isMobile = false;
+/** Whether the login screen is up; `App` keeps this in step. */
+let authRequired = false;
+
+function write(): void {
+  if (typeof document === 'undefined') return;
+  const content = windowChromeColor(resolveTheme(themeId), { isMobile, authRequired });
+  document.querySelector('meta[name="theme-color"]')?.setAttribute('content', content);
+}
+
+/**
+ * Seed the two surface facts from the server-rendered bootstrap, before the
+ * first theme write. Deliberately does not write: the shell already carries the
+ * server's own verdict, and `initDocumentTheme()` repaints immediately after.
+ */
+export function primeWindowChrome(mode: { isMobile: boolean; authRequired: boolean }): void {
+  isMobile = mode.isMobile;
+  authRequired = mode.authRequired;
+}
+
+/** Point the chrome at `id`'s palette and repaint — the theme writer's half. */
+export function applyWindowChrome(id: string): void {
+  themeId = id;
+  write();
+}
+
+/** Report the layout on screen. Repaints only when the color actually moves. */
+export function setWindowChromeLayout(next: boolean): void {
+  if (isMobile === next) return;
+  isMobile = next;
+  write();
+}
+
+/** Report whether the login screen is up. Repaints only when it moves. */
+export function setWindowChromeAuthRequired(next: boolean): void {
+  if (authRequired === next) return;
+  authRequired = next;
+  write();
+}

package/src/client/hooks/ui/window-event.ts

@@ -0,0 +1,55 @@
+import { useEffect, useRef } from 'preact/hooks';
+
+/**
+ * Event-listener hooks. Each subscribes once per event type and always calls
+ * the latest handler through a ref, so an inline closure does not tear the
+ * listener down and re-add it on every render.
+ */
+
+type EventTargetLike = Window | Document;
+
+function useEventListener<E extends Event>(
+  target: EventTargetLike,
+  type: string,
+  handler: (event: E) => void,
+  options?: AddEventListenerOptions | boolean,
+) {
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    const listener = (event: Event) => handlerRef.current(event as E);
+    target.addEventListener(type, listener, options);
+    return () => target.removeEventListener(type, listener, options);
+  }, [target, type, options]);
+}
+
+/** Subscribe a `window` listener; the latest handler is always invoked. */
+export function useWindowEvent<K extends keyof WindowEventMap>(
+  type: K,
+  handler: (event: WindowEventMap[K]) => void,
+  options?: AddEventListenerOptions | boolean,
+) {
+  useEventListener<WindowEventMap[K]>(window, type, handler, options);
+}
+
+/** Subscribe a `document` listener; the latest handler is always invoked. */
+export function useDocumentEvent<K extends keyof DocumentEventMap>(
+  type: K,
+  handler: (event: DocumentEventMap[K]) => void,
+  options?: AddEventListenerOptions | boolean,
+) {
+  useEventListener<DocumentEventMap[K]>(document, type, handler, options);
+}
+
+/** Subscribe to a custom `omp:*` window event. */
+export function useKabmoEvent(
+  name: string,
+  handler: (event: Event) => void,
+  options?: AddEventListenerOptions | boolean,
+) {
+  useEventListener<Event>(window, name, handler, options);
+}
+
+/** @deprecated Use `useKabmoEvent`. */
+export const useChamberEvent = useKabmoEvent;

package/src/client/hooks/workspace/available-width.ts

@@ -0,0 +1,33 @@
+import { useEffect, useState } from 'preact/hooks';
+import type { RefObject } from 'preact';
+
+/**
+ * Measure an element's content width and keep it current.
+ *
+ * Panel widths are stored as a share of the group's available area, so the
+ * group has to report that area before any fraction can become pixels. Returns
+ * `null` until the first measurement — callers must treat that as "unknown",
+ * not as zero, or a panel would collapse on its first render.
+ *
+ * `ResizeObserver` is not optional here: the width changes on a window resize,
+ * on a devtools dock, and on a sibling panel being toggled, and none of those
+ * are `window` events.
+ */
+export function useAvailableWidth(ref: RefObject<HTMLElement | null>): number | null {
+  const [available, setAvailable] = useState<number | null>(null);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (!element || typeof ResizeObserver === 'undefined') return;
+
+    const observer = new ResizeObserver(() => {
+      setAvailable(element.clientWidth || null);
+    });
+    observer.observe(element);
+    setAvailable(element.clientWidth || null);
+
+    return () => observer.disconnect();
+  }, [ref]);
+
+  return available;
+}