cursedbelt 4.6.0 → 5.0.0

package/scripts/styleAreas.ts

@@ -419,7 +419,6 @@ const resolveRelative = (fromFile: string, specifier: string): string | null =>
 	const base = `/${stack.join('/')}`.replace(/\.js$/, '');
 	if (SOURCE.test(base)) return base;
 	for (const candidate of [`${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}/index.tsx`]) {
-		// biome-ignore lint/nursery/noAwaitInLoop: synchronous existence check, no await here
 		if (Bun.file(candidate).size > 0) return candidate;
 	}
 	return null;
@@ -442,7 +441,7 @@ export const buildGraph = async (): Promise<Map<string, string[]>> => {
 			for (const match of text.matchAll(SPECIFIER)) {
 				const target = resolveRelative(file, match[1] as string);
 				// Outside `src/react` is outside every area — the utility scan never sees it.
-				if (target && target.startsWith(`${REACT_DIR}/`) && !SPEC.test(target)) out.add(target);
+				if (target?.startsWith(`${REACT_DIR}/`) && !SPEC.test(target)) out.add(target);
 			}
 			graph.set(file, [...out]);
 		}),

package/src/barrelsReachNoOptionalPeer.spec.ts

@@ -92,14 +92,17 @@ const NO_STATIC_OPTIONAL_PEERS = [
   },
 ] as const;
 
-const OPTIONAL_PEERS = new Set(
-  Object.entries(
+const OPTIONAL_PEERS = new Set([
+  ...Object.entries(
     (pkg as { peerDependenciesMeta?: Record<string, { optional?: boolean }> })
       .peerDependenciesMeta ?? {},
   )
     .filter(([, meta]) => meta?.optional === true)
     .map(([name]) => name),
-);
+  // Optional in every sense but npm's (task 2087): declared in `unpeered`, not peered only
+  // because npm cannot resolve them. The barrel must not reach them statically either.
+  ...Object.keys((pkg as { unpeered?: { packages?: Record<string, string> } }).unpeered?.packages ?? {}),
+]);
 
 /**
  * `import x from "pkg"` · `export … from "pkg"` · the side-effect-only `import "pkg";`.

package/src/bundlerOnlyEntries.spec.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'bun:test';
+import { existsSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import pkg from '../package.json';
+
+/**
+ * `bundlerOnly.subpaths` in `package.json` is EXACTLY the set of export subpaths whose
+ * built graph imports a stylesheet — in both directions.
+ *
+ * Task 2087: every cursedbelt publish runs `tools/proveInstall.ts`, and Node refused 12 of its
+ * entries with `ERR_UNKNOWN_FILE_EXTENSION ".css"`. That is by design (a component that ships
+ * its own stylesheet needs a bundler), but a proof that is red on every publish trains people to
+ * ignore it. The fix is an excuse the package DECLARES rather than one the tool grants globally —
+ * and a declaration only stays true if something re-derives it. This does: every subpath is
+ * bundled with its packages external, and a subpath counts when its output has a CSS sibling (its
+ * own `.css` imports) or imports a package's `.css` (`@vidstack/…/theme.css`). A new CSS import
+ * on an undeclared subpath is red here, before it is red in a publish; a declared subpath that
+ * stopped importing CSS is red too, so the excuse cannot outlive its reason.
+ */
+
+const REPO = fileURLToPath(new URL('..', import.meta.url));
+
+type Reason = 'css' | 'directoryImport';
+const declared = (reason: Reason): string[] =>
+  [...((pkg as { bundlerOnly?: Record<Reason, string[]> }).bundlerOnly?.[reason] ?? [])].sort();
+
+/** A deep specifier into a package with NO `exports` map, naming a directory — Node ESM refuses it. */
+const isDirectoryImport = (specifier: string): boolean => {
+  const parts = specifier.split('/');
+  const n = specifier.startsWith('@') ? 2 : 1;
+  if (parts.length <= n) return false;
+  const name = parts.slice(0, n).join('/');
+  const manifest = `${REPO}node_modules/${name}/package.json`;
+  if (!existsSync(manifest) || JSON.parse(readFileSync(manifest, 'utf8')).exports) return false;
+  const target = `${REPO}node_modules/${specifier}`;
+  return existsSync(target) && statSync(target).isDirectory();
+};
+
+const SPECIFIER = /\bfrom\s*["']([^"'\n]+)["']|^\s*import\s*["']([^"'\n]+)["'];?\s*$/gm;
+
+async function measure(): Promise<Record<Reason, string[]>> {
+  const entries = Object.entries(pkg.exports as Record<string, unknown>).flatMap(([subpath, target]) => {
+    const source = (target as { source?: string }).source;
+    return source && /\.tsx?$/.test(source) ? [[subpath, source.replace(/^\.\//, '')] as const] : [];
+  });
+  const outdir = `${process.env.TMPDIR ?? '/tmp'}/cursedbelt-bundler-only-${process.pid}`;
+  try {
+    const result = await Bun.build({
+      entrypoints: entries.map(([, source]) => `${REPO}${source}`),
+      root: REPO,
+      target: 'bun',
+      packages: 'external',
+      outdir,
+    });
+    if (!result.success) throw new Error(`could not bundle — a check that cannot measure is not a pass:\n${result.logs.join('\n')}`);
+    const emitted = new Set(result.outputs.map((o) => o.path));
+    const out: Record<Reason, string[]> = { css: [], directoryImport: [] };
+    for (const [subpath, source] of entries) {
+      const js = `${outdir}/${source.replace(/\.tsx?$/, '.js')}`;
+      const code = readFileSync(js, 'utf8');
+      const specifiers = [...code.matchAll(SPECIFIER)].map((m) => (m[1] ?? m[2]) as string);
+      if (emitted.has(js.replace(/\.js$/, '.css')) || specifiers.some((s) => s.endsWith('.css'))) out.css.push(subpath);
+      if (specifiers.some((s) => !s.startsWith('.') && isDirectoryImport(s))) out.directoryImport.push(subpath);
+    }
+    out.css.sort();
+    out.directoryImport.sort();
+    return out;
+  } finally {
+    rmSync(outdir, { recursive: true, force: true });
+  }
+}
+
+describe('bundlerOnly', () => {
+  it('declares exactly the subpaths that import a stylesheet, and exactly those that reach a directory import', async () => {
+    const measured = await measure();
+    // The measurement must have seen the cases it exists for, or it measured nothing.
+    expect(measured.css).toContain('./react/media');
+    expect(measured.directoryImport).toContain('./react/disk-usage');
+    for (const reason of ['css', 'directoryImport'] as const) {
+      expect({
+        reason,
+        undeclared: measured[reason].filter((s) => !declared(reason).includes(s)),
+        stale: declared(reason).filter((s) => !measured[reason].includes(s)),
+      }).toEqual({ reason, undeclared: [], stale: [] });
+    }
+  });
+
+  it('names only subpaths that exist', () => {
+    const exported = Object.keys(pkg.exports as Record<string, unknown>);
+    for (const reason of ['css', 'directoryImport'] as const) expect(declared(reason).filter((s) => !exported.includes(s))).toEqual([]);
+  });
+});
+
+describe('unpeered', () => {
+  it('is disjoint from peerDependencies — a package is peered or unpeered, never both', () => {
+    const unpeered = Object.keys((pkg as { unpeered?: { packages?: Record<string, string> } }).unpeered?.packages ?? {});
+    expect(unpeered.length).toBeGreaterThan(0);
+    const peers = Object.keys((pkg as { peerDependencies?: Record<string, string> }).peerDependencies ?? {});
+    expect(unpeered.filter((name) => peers.includes(name))).toEqual([]);
+  });
+});

package/src/declaredImports.spec.ts

@@ -20,6 +20,10 @@ const declared = new Set([
   pkg.name,
   ...Object.keys((pkg as { dependencies?: Record<string, string> }).dependencies ?? {}),
   ...Object.keys((pkg as { peerDependencies?: Record<string, string> }).peerDependencies ?? {}),
+  // `unpeered` — imported by a subpath, declared, and kept OUT of peerDependencies only
+  // because npm cannot resolve them beside this package's own peers (task 2087; the block says
+  // why for each).
+  ...Object.keys((pkg as { unpeered?: { packages?: Record<string, string> } }).unpeered?.packages ?? {}),
 ]);
 const builtin = new Set(builtinModules);
 

package/src/optionalPeersTable.spec.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from 'bun:test';
+import { readFileSync, rmSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import pkg from '../package.json';
+
+/**
+ * 🔴 `docs/API-REFERENCE.md`'s "What you install" table is the ONE place an importing app learns
+ * that `cursedbelt/react/charts` needs `recharts` — and this spec is what keeps it true.
+ *
+ * Task 104 (2026-09-17): *"`cursedbelt/react/charts` hard-fails the build without `recharts`,
+ * and the error names a `__vite-optional-peer-dep` module rather than the package."* The fix is
+ * one install; the cost was entirely in not knowing. The table says what to install, but it was
+ * hand-written — and measured the day this spec arrived it had already missed a subpath:
+ * `./react/media-gallery` statically reaches `@glideapps/glide-data-grid`, `@vidstack/react` and
+ * `marked`, and no row said so. (`peers-by-subpath.json` died of exactly this — task 272.)
+ *
+ * So: every public `./react/*` subpath is bundled with its packages left external, the OPTIONAL
+ * peers each one imports STATICALLY are read out of the bundle, and each must be named in that
+ * subpath's row of the table. A static optional peer is the case that breaks a build; a lazy
+ * `await import()` one breaks only the feature that loads it, and is the documented shape to
+ * copy, so it is not required here (a row may still name it).
+ *
+ * A row names a peer when its second cell carries the name in backticks, or a `@scope/*` set
+ * that covers it (the `@codemirror/*` set).
+ */
+
+const REPO = fileURLToPath(new URL('..', import.meta.url));
+const DOC = `${REPO}docs/API-REFERENCE.md`;
+const HEADING = '### What you install, and what you don\'t';
+
+const OPTIONAL = new Set([
+  ...Object.entries(
+    (pkg as { peerDependenciesMeta?: Record<string, { optional?: boolean }> }).peerDependenciesMeta ??
+      {},
+  )
+    .filter(([, meta]) => meta?.optional === true)
+    .map(([name]) => name),
+  // `unpeered` (task 2087): optional peers npm cannot resolve, so not in peerDependencies —
+  // an app still has to install them, so the table still has to name them.
+  ...Object.keys((pkg as { unpeered?: { packages?: Record<string, string> } }).unpeered?.packages ?? {}),
+]);
+
+/** Same matcher as `barrelsReachNoOptionalPeer.spec.ts` — anchored on `from`, never on a dynamic import. */
+const STATIC_SPECIFIER = /\bfrom\s*["']([^"'\n]+)["']|^\s*import\s*["']([^"'\n]+)["'];?\s*$/gm;
+
+const packageOf = (specifier: string): string => {
+  const parts = specifier.split('/');
+  return (specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0]) ?? specifier;
+};
+
+/** `./react/charts` → the optional peers its bundle imports statically. */
+async function staticOptionalPeersBySubpath(): Promise<Map<string, string[]>> {
+  const entries = Object.entries(pkg.exports as Record<string, unknown>).flatMap(([subpath, target]) => {
+    const source = (target as { source?: string }).source;
+    return subpath.startsWith('./react/') && source && /\.tsx?$/.test(source) ? [[subpath, source] as const] : [];
+  });
+  const outdir = `${process.env.TMPDIR ?? '/tmp'}/cursedbelt-optional-peers-${process.pid}`;
+  try {
+    const result = await Bun.build({
+      entrypoints: entries.map(([, source]) => `${REPO}${source.replace(/^\.\//, '')}`),
+      root: `${REPO}src`,
+      target: 'bun',
+      packages: 'external',
+      outdir,
+    });
+    if (!result.success) throw new Error(`could not bundle the subpaths — a check that cannot measure is not a pass:\n${result.logs.join('\n')}`);
+    const out = new Map<string, string[]>();
+    for (const [subpath, source] of entries) {
+      const emitted = `${outdir}/${source.replace(/^\.\/src\//, '').replace(/\.tsx?$/, '.js')}`;
+      const text = readFileSync(emitted, 'utf8');
+      const found = new Set<string>();
+      for (const m of text.matchAll(STATIC_SPECIFIER)) {
+        const specifier = m[1] ?? m[2];
+        if (specifier && !specifier.startsWith('.') && OPTIONAL.has(packageOf(specifier))) found.add(packageOf(specifier));
+      }
+      out.set(subpath, [...found].sort());
+    }
+    return out;
+  } finally {
+    rmSync(outdir, { recursive: true, force: true });
+  }
+}
+
+/** The table's rows: every `cursedbelt/react/<name>` its first cell names (`…/y` continues the last), → its second cell. */
+export function tableRows(markdown: string): Map<string, string> {
+  const start = markdown.indexOf(HEADING);
+  if (start < 0) throw new Error(`${DOC} has no "${HEADING}" section — the table this spec keeps honest is gone`);
+  const rows = new Map<string, string>();
+  for (const line of markdown.slice(start).split('\n').slice(1)) {
+    if (line.startsWith('#')) break;
+    if (!line.startsWith('|')) continue;
+    const [first = '', second = ''] = line.split('|').slice(1, 3);
+    for (const m of first.matchAll(/`cursedbelt\/(react\/[\w/-]+)`/g)) rows.set(`./${m[1]}`, second);
+    for (const m of first.matchAll(/`…\/([\w-]+)`/g)) rows.set(`./react/${m[1]}`, second);
+  }
+  return rows;
+}
+
+/** Does this cell name `peer` — literally, or through a `@scope/*` set? */
+export function names(cell: string, peer: string): boolean {
+  if (cell.includes(`\`${peer}\``)) return true;
+  const scope = peer.startsWith('@') ? peer.split('/')[0] : null;
+  return scope !== null && cell.includes(`\`${scope}/*\``);
+}
+
+describe("the docs' what-you-install table", () => {
+  it('🔴 fails on a subpath whose static optional peer no row names — the task-104 shape', () => {
+    const rows = tableRows(`${HEADING}\n| import this | also \`bun add\` this |\n| --- | --- |\n| \`cursedbelt/react/code-editor\` | the \`@codemirror/*\` set |\n`);
+    expect(names(rows.get('./react/code-editor') ?? '', '@codemirror/view')).toBe(true);
+    expect(rows.get('./react/charts')).toBeUndefined();
+    expect(names('`marked`', 'recharts')).toBe(false);
+  });
+
+  it('names every optional peer each ./react/* subpath imports statically', async () => {
+    const rows = tableRows(readFileSync(DOC, 'utf8'));
+    const bySubpath = await staticOptionalPeersBySubpath();
+    // The measurement must have seen the case this exists for, or it measured nothing.
+    expect(bySubpath.get('./react/charts')).toContain('recharts');
+    const missing: string[] = [];
+    for (const [subpath, peers] of bySubpath) {
+      for (const peer of peers) {
+        if (!names(rows.get(subpath) ?? '', peer)) missing.push(`cursedbelt/${subpath.slice(2)} → ${peer}`);
+      }
+    }
+    expect(missing, `add these to the table in ${DOC}`).toEqual([]);
+  });
+});

package/src/react/chat/index.ts

@@ -6,6 +6,14 @@ export { MessageScroller, type MessageScrollerProps } from './MessageScroller.js
 export { MessageThread, type MessageThreadProps } from './MessageThread.js';
 export { PresenceRoster, type PresenceRosterProps } from './PresenceRoster.js';
 export { StatusMarker, type StatusMarkerProps } from './StatusMarker.js';
+export {
+  PRESENCE_RETRY_MS,
+  type PresenceEntryLike,
+  type PresenceSubscription,
+  presenceUsers,
+  type UsePresenceOptions,
+  usePresence,
+} from './usePresence.js';
 export type {
   ChatAttachment,
   ChatAuthor,

package/src/react/chat/usePresence.spec.tsx

@@ -0,0 +1,138 @@
+import { describe, expect, test } from 'bun:test';
+import { act, render } from '@testing-library/react';
+import { PresenceRoster } from './PresenceRoster.js';
+import { presenceUsers, usePresence } from './usePresence.js';
+
+/** A socket the test drives by hand: `open()`, `snapshot(rows)`, `drop()`. */
+class FakeSocket extends EventTarget {
+  static made: FakeSocket[] = [];
+  closed = false;
+  constructor(readonly url: string) {
+    super();
+    FakeSocket.made.push(this);
+  }
+  open() {
+    this.dispatchEvent(new Event('open'));
+  }
+  snapshot(rows: unknown, event = 'presence') {
+    const message = new MessageEvent('message', { data: JSON.stringify({ event, data: rows }) });
+    this.dispatchEvent(message);
+  }
+  drop() {
+    this.dispatchEvent(new Event('close'));
+  }
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.dispatchEvent(new Event('close'));
+  }
+}
+
+const NAMES: Record<string, string> = { u1: 'Ada', u2: 'Brian', me: 'Me' };
+
+function Harness({ enabled = true }: { enabled?: boolean }) {
+  const { users, connected } = usePresence({
+    channel: 'rooms',
+    enabled,
+    selfId: 'me',
+    resolveUser: (id) => ({ name: NAMES[id] }),
+    retryMs: [5],
+    location: { protocol: 'https:', host: 'roms.example' },
+    createSocket: (url) => new FakeSocket(url) as unknown as WebSocket,
+  });
+  return (
+    <div>
+      <span data-testid='state'>{connected ? 'on' : 'off'}</span>
+      <span data-testid='names'>{users.map((u) => u.name).join(',')}</span>
+      <PresenceRoster users={users} />
+    </div>
+  );
+}
+
+const last = () => FakeSocket.made[FakeSocket.made.length - 1] as FakeSocket;
+
+describe('presenceUsers', () => {
+  test('one row per user (the earliest tab), arrival order, without the viewer', () => {
+    const users = presenceUsers(
+      [
+        { userId: 'u2', connectedAt: 30 },
+        { userId: 'me', connectedAt: 1 },
+        { userId: 'u1', connectedAt: 20 },
+        { userId: 'u2', connectedAt: 10 },
+      ],
+      'me',
+      (id) => ({ name: NAMES[id] }),
+    );
+    expect(users).toEqual([
+      { id: 'u2', isOnline: true, name: 'Brian' },
+      { id: 'u1', isOnline: true, name: 'Ada' },
+    ]);
+  });
+
+  test("a row's own name wins over the resolver, and a malformed row is skipped", () => {
+    const users = presenceUsers([{ userId: 'u1', name: 'Ada L.' }, { userId: '' } as never, null as never], null, () => ({ name: 'x' }));
+    expect(users).toEqual([{ id: 'u1', isOnline: true, name: 'Ada L.' }]);
+  });
+});
+
+describe('usePresence', () => {
+  test('connects to /ws/<channel> over wss, and a join and a leave redraw the roster', () => {
+    FakeSocket.made = [];
+    const { getByTestId } = render(<Harness />);
+    expect(last().url).toBe('wss://roms.example/ws/rooms');
+    expect(getByTestId('state').textContent).toBe('off');
+
+    act(() => last().open());
+    expect(getByTestId('state').textContent).toBe('on');
+
+    act(() => last().snapshot([{ userId: 'me', connectedAt: 1 }, { userId: 'u1', connectedAt: 2 }]));
+    expect(getByTestId('names').textContent).toBe('Ada');
+
+    act(() => last().snapshot([{ userId: 'me', connectedAt: 1 }, { userId: 'u1', connectedAt: 2 }, { userId: 'u2', connectedAt: 3 }]));
+    expect(getByTestId('names').textContent).toBe('Ada,Brian');
+
+    act(() => last().snapshot([{ userId: 'me', connectedAt: 1 }, { userId: 'u2', connectedAt: 3 }]));
+    expect(getByTestId('names').textContent).toBe('Brian');
+
+    // Another channel's frame is not a presence snapshot.
+    act(() => last().snapshot([{ userId: 'u9' }], 'chat:message'));
+    expect(getByTestId('names').textContent).toBe('Brian');
+  });
+
+  test('🔴 a dropped socket empties the roster, then reconnects and refills it', async () => {
+    FakeSocket.made = [];
+    const { getByTestId } = render(<Harness />);
+    act(() => last().open());
+    act(() => last().snapshot([{ userId: 'u1', connectedAt: 2 }]));
+    expect(getByTestId('names').textContent).toBe('Ada');
+
+    const first = last();
+    act(() => first.drop());
+    expect(getByTestId('state').textContent).toBe('off');
+    expect(getByTestId('names').textContent).toBe('');
+
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 30));
+    });
+    expect(FakeSocket.made.length).toBe(2);
+    expect(last()).not.toBe(first);
+    act(() => last().open());
+    act(() => last().snapshot([{ userId: 'u2', connectedAt: 5 }]));
+    expect(getByTestId('state').textContent).toBe('on');
+    expect(getByTestId('names').textContent).toBe('Brian');
+  });
+
+  test('disabled opens no socket; unmount closes it and does not reconnect', async () => {
+    FakeSocket.made = [];
+    const off = render(<Harness enabled={false} />);
+    expect(FakeSocket.made.length).toBe(0);
+    off.unmount();
+
+    const on = render(<Harness />);
+    act(() => last().open());
+    on.unmount();
+    expect(last().closed).toBe(true);
+    await new Promise((r) => setTimeout(r, 30));
+    expect(FakeSocket.made.length).toBe(1);
+  });
+});

package/src/react/chat/usePresence.ts

@@ -0,0 +1,185 @@
+import { buildChannelSocketUrl, parseWsMessage, type WsLocation } from 'cursedbelt-core/ws-wire';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { PresenceUser } from './types.js';
+
+/**
+ * Who else is here — the CLIENT half of presence, so `PresenceRoster` has something to render.
+ *
+ * Task 078 (owner, 2026-09-19: *"show which other users are on apps"*). The library shipped the
+ * view (`PresenceRoster`) and the server (`cursedbelt-server`'s `createWsHub` with
+ * `presence: true`, whose `getPresence(channel)` is one `{ userId, connectedAt }` row per live
+ * client) and nothing in between — so the roster sat exported with zero consumers, and the one
+ * app that shows presence (`apps/family`, `src/live.ts`) hand-rolled its own socket. This is that
+ * socket, generalised: open `/ws/<channel>`, take every `presence` snapshot the channel
+ * broadcasts, and reconnect with a capped backoff when the socket drops.
+ *
+ * The server side a channel needs is one line in its lifecycle hooks:
+ *
+ *     onConnect: (_c, hub) => hub.broadcast('rooms', 'presence', hub.getPresence('rooms')),
+ *     onDisconnect: (_c, hub) => hub.broadcast('rooms', 'presence', hub.getPresence('rooms')),
+ *
+ * ── What it does with a snapshot ─────────────────────────────────────────────────────────
+ *  · ONE row per user, not per tab — the same person in three tabs is one avatar — keeping the
+ *    earliest `connectedAt`, so the roster's order is "who arrived first" and stable.
+ *  · `selfId` drops the viewer: the roster is who ELSE is here.
+ *  · `resolveUser` turns an id into a name/avatar; the hub deliberately ships only the id (its
+ *    `PresenceEntry` is the "business-safe view" of a client). A row may also carry `name` /
+ *    `avatarUrl` itself, for a channel that broadcasts richer rows.
+ *
+ * ── A dropped socket is an EMPTY roster, not a stale one ─────────────────────────────────
+ * On close the users go to `[]` and `connected` to false until the next snapshot. Showing the
+ * last list while disconnected would tell the viewer someone is here who may have left an hour
+ * ago; an empty strip is merely less informative. Same choice as family's `useLiveTree`.
+ */
+
+/** One presence row as a hub channel broadcasts it (`cursedbelt-server`'s `PresenceEntry`). */
+export interface PresenceEntryLike {
+  userId: string;
+  connectedAt?: number;
+  name?: string;
+  avatarUrl?: string;
+}
+
+export interface UsePresenceOptions {
+  /** The hub channel (`/ws/<channel>`) whose snapshots to follow. */
+  channel: string;
+  /** Room within the channel (`?room=`), when the channel is roomed. */
+  roomId?: string;
+  /** Off ⇒ no socket at all (e.g. signed out). Default true. */
+  enabled?: boolean;
+  /** The viewer's own id — left out of the roster. */
+  selfId?: string | null;
+  /** Name and avatar for an id the snapshot does not carry them for. */
+  resolveUser?: (userId: string) => { name?: string; avatarUrl?: string } | undefined;
+  /** The frame event carrying the snapshot. Default `'presence'`. */
+  event?: string;
+  /** Reconnect backoff, capped at its last entry. */
+  retryMs?: readonly number[];
+  /** Test/SSR seams. Default `window.location` and the global `WebSocket`. */
+  location?: WsLocation;
+  createSocket?: (url: string) => WebSocket;
+}
+
+export interface PresenceSubscription {
+  /** Everybody else on the channel now — pass straight to `<PresenceRoster users={…}>`. */
+  users: PresenceUser[];
+  /** Is the socket open? A closed one also means `users` is `[]`. */
+  connected: boolean;
+}
+
+/** Backoff, capped. A tab left open overnight must not hammer the box. */
+export const PRESENCE_RETRY_MS = [500, 1_000, 2_000, 5_000, 10_000, 30_000] as const;
+
+/**
+ * Collapse a snapshot to one {@link PresenceUser} per user, earliest arrival first, without
+ * `selfId`. Pure — the hook's whole judgement, exported so it is tested without a socket.
+ */
+export function presenceUsers(
+  rows: readonly PresenceEntryLike[],
+  selfId?: string | null,
+  resolveUser?: UsePresenceOptions['resolveUser'],
+): PresenceUser[] {
+  const byUser = new Map<string, PresenceEntryLike>();
+  for (const row of rows) {
+    if (!row || typeof row.userId !== 'string' || row.userId === '') continue;
+    if (selfId != null && row.userId === selfId) continue;
+    const seen = byUser.get(row.userId);
+    if (!seen || (row.connectedAt ?? Infinity) < (seen.connectedAt ?? Infinity)) byUser.set(row.userId, row);
+  }
+  return [...byUser.values()]
+    .sort((a, b) => (a.connectedAt ?? Infinity) - (b.connectedAt ?? Infinity))
+    .map((row) => {
+      const resolved = resolveUser?.(row.userId);
+      const name = row.name ?? resolved?.name;
+      const avatarUrl = row.avatarUrl ?? resolved?.avatarUrl;
+      return {
+        id: row.userId,
+        isOnline: true,
+        ...(name !== undefined ? { name } : {}),
+        ...(avatarUrl !== undefined ? { avatarUrl } : {}),
+      };
+    });
+}
+
+/** The rows in a snapshot frame: the hub's bare array, or `{ users }` / `{ peers }` / `{ presence }`. */
+function rowsOf(data: unknown): PresenceEntryLike[] | null {
+  if (Array.isArray(data)) return data as PresenceEntryLike[];
+  if (data && typeof data === 'object') {
+    for (const key of ['users', 'peers', 'presence'] as const) {
+      const value = (data as Record<string, unknown>)[key];
+      if (Array.isArray(value)) return value as PresenceEntryLike[];
+    }
+  }
+  return null;
+}
+
+export function usePresence(options: UsePresenceOptions): PresenceSubscription {
+  const {
+    channel,
+    roomId,
+    enabled = true,
+    selfId = null,
+    resolveUser,
+    event = 'presence',
+    retryMs = PRESENCE_RETRY_MS,
+    location,
+    createSocket,
+  } = options;
+  const [rows, setRows] = useState<PresenceEntryLike[]>([]);
+  const [connected, setConnected] = useState(false);
+  // The seams and backoff are read through a ref so an inline lambda or array literal in the
+  // caller does not tear the socket down on every render.
+  const seams = useRef({ location, createSocket, retryMs });
+  seams.current = { location, createSocket, retryMs };
+
+  useEffect(() => {
+    const loc = seams.current.location ?? (typeof window !== 'undefined' ? window.location : undefined);
+    if (!enabled || !loc) return;
+    let closed = false;
+    let attempt = 0;
+    let retry: ReturnType<typeof setTimeout> | null = null;
+    let socket: WebSocket | null = null;
+
+    const open = () => {
+      if (closed) return;
+      const url = buildChannelSocketUrl(channel, roomId, loc);
+      const make = seams.current.createSocket ?? ((u: string) => new WebSocket(u));
+      const ws = make(url);
+      socket = ws;
+      ws.addEventListener('open', () => {
+        attempt = 0;
+        setConnected(true);
+      });
+      ws.addEventListener('message', (message) => {
+        const frame = parseWsMessage(String((message as MessageEvent).data));
+        if (!frame || frame.event !== event) return;
+        const next = rowsOf(frame.data);
+        if (next) setRows(next);
+      });
+      ws.addEventListener('close', () => {
+        setConnected(false);
+        setRows([]);
+        if (closed) return;
+        const steps = seams.current.retryMs;
+        const wait = steps[Math.min(attempt, steps.length - 1)] ?? 30_000;
+        attempt += 1;
+        retry = setTimeout(open, wait);
+      });
+      // An `error` is always followed by a `close`; reconnecting from both would schedule two.
+      ws.addEventListener('error', () => ws.close());
+    };
+
+    open();
+    return () => {
+      closed = true;
+      if (retry) clearTimeout(retry);
+      socket?.close();
+      socket = null;
+      setConnected(false);
+      setRows([]);
+    };
+  }, [enabled, channel, roomId, event]);
+
+  const users = useMemo(() => presenceUsers(rows, selfId, resolveUser), [rows, selfId, resolveUser]);
+  return { users, connected };
+}

package/src/react/components/SecretInput.tsx

@@ -1,4 +1,4 @@
-import { type CSSProperties, type ReactNode, useState } from 'react';
+import { type CSSProperties, type KeyboardEvent, type ReactNode, useState } from 'react';
 import { useCopyToClipboard } from '../hooks/useCopyToClipboard.js';
 import { CONTROL_HEIGHT_CLASS, type ControlSize } from '../lib/field.js';
 import { resolveClass, resolveStyle, type StyleableProps } from '../styling.js';
@@ -118,6 +118,11 @@ export interface SecretInputProps extends StyleableProps<SecretInputSlot> {
   'aria-invalid'?: boolean | 'true' | 'false';
   'aria-describedby'?: string;
   autoFocus?: boolean;
+  /** Disable typing while a form submits (the eye stays usable — seeing what you typed is
+   *  harmless while it is in flight). */
+  disabled?: boolean;
+  /** Fires on Enter in THIS field — the login/rotation forms submit from their last field. */
+  onEnter?: (event: KeyboardEvent<HTMLInputElement>) => void;
   className?: string;
   style?: CSSProperties;
   /** Container height on the shared control-height scale (`--control-h-*`, task
@@ -149,6 +154,8 @@ export const SecretInput = ({
   'aria-invalid': ariaInvalid,
   'aria-describedby': ariaDescribedBy,
   autoFocus = false,
+  disabled,
+  onEnter,
   className,
   style,
   classNames,
@@ -199,6 +206,10 @@ export const SecretInput = ({
         value={value}
         readOnly={readOnly}
         onChange={onChange ? (e) => onChange(e.target.value) : undefined}
+        onKeyDown={onEnter ? (e) => {
+          if (e.key === 'Enter') onEnter(e);
+        } : undefined}
+        disabled={disabled}
         placeholder={placeholder}
         aria-label={label}
         aria-invalid={ariaInvalid}