@byokit/ui 0.0.0-stage → 0.7.0

package/dist/phase.d.ts

@@ -0,0 +1,23 @@
+export type Phase = 'opening' | 'waiting' | 'code' | 'done' | 'work' | 'cancelled' | 'busy' | 'expired' | 'failed' | 'offline';
+/** A sign-in in progress, as `@byokit/accounts` `view()` reports it. */
+export type SignInView = {
+    state: 'waiting' | 'done' | 'failed';
+    via?: 'browser' | 'code';
+    url?: string;
+    code?: string;
+    error?: string;
+    why?: string;
+};
+/** One account as the app's back end reports it; `work` is set when the sign-in is a work plan. */
+export type AccountView = {
+    ready?: boolean;
+    work?: string | boolean;
+    signIn?: SignInView | null;
+};
+export declare function phaseOf(a: AccountView | null, { offline, cancelled, keepWork }?: {
+    offline?: boolean | undefined;
+    cancelled?: boolean | undefined;
+    keepWork?: boolean | undefined;
+}): Phase;
+/** Where the three-step progress bar ("Open", "Say yes", "Done") stands. */
+export declare const stepOf: (p: Phase) => 0 | 1 | 3;

package/dist/phase.js

@@ -0,0 +1,21 @@
+export function phaseOf(a, { offline = false, cancelled = false, keepWork = false } = {}) {
+    const s = a?.signIn;
+    if (offline)
+        return 'offline';
+    if (cancelled)
+        return 'cancelled';
+    if (a?.ready)
+        return a.work && !keepWork ? 'work' : 'done';
+    if (s?.state === 'waiting')
+        return s.code ? 'code' : s.url ? 'waiting' : 'opening';
+    if (s?.state === 'failed') {
+        if (s.why === 'busy')
+            return 'busy';
+        if (s.why === 'declined')
+            return 'cancelled';
+        return s.why === 'expired' || s.why === 'tooLong' || /expired|too long/i.test(s.error ?? '') ? 'expired' : 'failed';
+    }
+    return 'opening';
+}
+/** Where the three-step progress bar ("Open", "Say yes", "Done") stands. */
+export const stepOf = (p) => (p === 'done' || p === 'work' ? 3 : p === 'waiting' || p === 'code' ? 1 : 0);

package/dist/route.d.ts

@@ -0,0 +1,28 @@
+export type Route = 'Tailscale' | 'Temporary public link' | 'Same Wi-Fi' | 'Private network' | 'Away from home' | 'Your own server';
+export type RouteKind = 'tailscale' | 'private' | 'lan' | 'direct';
+/** An onboarding route code. A superset of reach's `Via`: reach has no Cloudflare or own-server route. */
+export type RouteCode = 'tailscale' | 'tailscale-direct' | 'private' | 'lan' | 'cloudflare' | 'external';
+/** One onboarding route in everyday words: the list title, the sentence under it, and what it needs first. */
+export type RouteChoice = {
+    code: RouteCode;
+    /** The list title, e.g. `Same Wi-Fi`. */
+    title: string;
+    /** One everyday sentence saying what it gives, e.g. where it works. */
+    sentence: string;
+    /** What has to be true first, in words, e.g. which app to install. */
+    needs: string;
+};
+/**
+ * Every onboarding route in everyday words, in recommendation order. The one word table: reach's `recommend()`
+ * takes `sentence` and `needs` from here and only adds availability, so the order and the copy live in one place.
+ */
+export declare function routeChoices(): RouteChoice[];
+/** The route `url` takes, or undefined when it isn't a URL. Loopback is the page on the computer itself, so it reads
+ *  as the same-network route; this kit's `/link/v1/…` away address reads as away from home, whatever its host. */
+export declare function describeRoute(url: string | undefined, kind?: RouteKind): Route | undefined;
+/** The route as words inside a connected line (`same Wi-Fi`): lowercase, so a consumer renders one sentence
+ *  (`Connected to Kitchen computer - ${routeShort(route)}.`). Tailscale keeps its capital: it is a name. */
+export declare function routeShort(route: Route | undefined): string | undefined;
+/** The connected line a consumer renders: the computer with the route just dialled
+ *  (`Connected to Kitchen computer - same Wi-Fi.`), or plain (`Connected to Kitchen computer.`) with no route. */
+export declare function connectedWords(hostName: string, url: string | undefined, kind?: RouteKind): string;

package/dist/route.js

@@ -0,0 +1,118 @@
+/**
+ * Every onboarding route in everyday words, in recommendation order. The one word table: reach's `recommend()`
+ * takes `sentence` and `needs` from here and only adds availability, so the order and the copy live in one place.
+ */
+export function routeChoices() {
+    return [
+        {
+            code: 'tailscale',
+            title: 'Tailscale — works anywhere',
+            sentence: 'Your phone reaches this computer from anywhere.',
+            needs: 'The free Tailscale app on this computer and your phone, signed in to the same account.',
+        },
+        {
+            code: 'tailscale-direct',
+            title: 'Tailscale — direct (phone app only)',
+            sentence: 'Same as above without Tailscale Serve. Pick this if Serve is already used on this computer for something else.',
+            needs: 'The free Tailscale app on this computer and your phone, signed in to the same account. No Serve setup.',
+        },
+        {
+            code: 'private',
+            title: 'Private network you already use (NetBird, WireGuard, ZeroTier)',
+            sentence: 'Pick this if this computer and phone are already on one.',
+            needs: 'This computer and your phone on the same private network.',
+        },
+        {
+            code: 'lan',
+            title: 'Same Wi-Fi',
+            sentence: 'Easiest. Works while your phone is on the same Wi-Fi as this computer. Nothing else to install.',
+            needs: 'Your phone on the same Wi-Fi as this computer.',
+        },
+        {
+            code: 'cloudflare',
+            title: 'Temporary public link (Cloudflare)',
+            sentence: 'Works anywhere without a VPN, but the link changes when it restarts.',
+            needs: 'cloudflared installed on this computer.',
+        },
+        {
+            code: 'external',
+            title: 'Your own server',
+            sentence: "For people who already run their own secure server. You'll paste its address next.",
+            needs: 'A stable server address you manage.',
+        },
+    ];
+}
+const privateIp = (host) => /^(?:127\.|10\.|192\.168\.|172\.(?:1[6-9]|2\d|3[01])\.|100\.(?:6[4-9]|[78]\d|9\d|1[01]\d|12[0-7])\.)/.test(host);
+const ipv4 = (host) => /^(?:\d{1,3}\.){3}\d{1,3}$/.test(host) && host.split('.').every((part) => +part <= 255);
+/** The scheme, host and path of a `scheme://authority…` address, without touching `URL`: the React Native polyfill has no
+ *  `URL.canParse`, and leaves `hostname` empty for that scheme. */
+function schemeHost(url) {
+    const m = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/([^\/?#]*)([^?#]*)/.exec(url);
+    if (!m)
+        return undefined;
+    let host = m[2];
+    if (!host)
+        return undefined;
+    const at = host.lastIndexOf('@');
+    if (at >= 0)
+        host = host.slice(at + 1);
+    if (host.startsWith('[')) {
+        const end = host.indexOf(']');
+        if (end < 0)
+            return undefined;
+        host = host.slice(1, end);
+    }
+    else {
+        const colon = host.indexOf(':');
+        if (colon >= 0)
+            host = host.slice(0, colon);
+    }
+    host = host.toLowerCase();
+    if (!host)
+        return undefined;
+    return { scheme: m[1].toLowerCase(), hostname: host, path: m[3] ?? '' };
+}
+/** The route `url` takes, or undefined when it isn't a URL. Loopback is the page on the computer itself, so it reads
+ *  as the same-network route; this kit's `/link/v1/…` away address reads as away from home, whatever its host. */
+export function describeRoute(url, kind) {
+    if (url === undefined)
+        return undefined;
+    const parsed = schemeHost(url);
+    if (!parsed)
+        return undefined;
+    const { scheme, hostname, path } = parsed;
+    if (kind === 'tailscale' || kind === 'direct' || hostname.endsWith('.ts.net'))
+        return 'Tailscale';
+    if (kind === 'private')
+        return 'Private network';
+    if (kind === 'lan')
+        return 'Same Wi-Fi';
+    if (hostname.endsWith('.trycloudflare.com'))
+        return 'Temporary public link';
+    if ((scheme === 'ws' || scheme === 'wss') && path.startsWith('/link/v1/'))
+        return 'Away from home';
+    if ((scheme === 'ws' || scheme === 'wss') && ipv4(hostname) && privateIp(hostname)) {
+        return hostname.startsWith('100.') ? 'Private network' : 'Same Wi-Fi';
+    }
+    if ((scheme === 'ws' || scheme === 'wss') && (hostname === 'localhost' || hostname === '::1'))
+        return 'Same Wi-Fi';
+    return 'Your own server';
+}
+/** The route as words inside a connected line (`same Wi-Fi`): lowercase, so a consumer renders one sentence
+ *  (`Connected to Kitchen computer - ${routeShort(route)}.`). Tailscale keeps its capital: it is a name. */
+export function routeShort(route) {
+    return route === undefined ? undefined : {
+        'Tailscale': 'Tailscale',
+        'Temporary public link': 'a temporary public link',
+        'Same Wi-Fi': 'same Wi-Fi',
+        'Private network': 'a private network',
+        'Away from home': 'away from home',
+        'Your own server': 'your own server',
+    }[route];
+}
+/** The connected line a consumer renders: the computer with the route just dialled
+ *  (`Connected to Kitchen computer - same Wi-Fi.`), or plain (`Connected to Kitchen computer.`) with no route. */
+export function connectedWords(hostName, url, kind) {
+    const short = routeShort(describeRoute(url, kind));
+    return short ? `Connected to ${hostName} - ${short}.` : `Connected to ${hostName}.`;
+}

package/dist/run.d.ts

@@ -0,0 +1,95 @@
+import { type Store } from './follow.ts';
+export type RunEvent = {
+    type: 'started';
+} | {
+    type: 'thinking';
+    tokens: number;
+} | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool';
+    name: string;
+    phase: 'start' | 'end';
+};
+export type RunEnd = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    aborted: true;
+} | {
+    ok: false;
+    kind: 'signed-out' | 'resting' | 'plan' | 'network' | 'other' | 'output';
+    until?: number;
+    message: string;
+};
+/** One frame of the run stream: an event, then one `end`. */
+export type RunFrame = RunEvent | {
+    type: 'end';
+    end: RunEnd;
+};
+export type RunPhase = 'idle' | 'running' | 'done' | 'stopped' | 'failed';
+export type RunState = {
+    phase: RunPhase;
+    /** The reply so far (cumulative), the final reply once done. */
+    text: string;
+    /** Every tool the run used, in the order it started them; `done` once it finished. */
+    tools: {
+        name: string;
+        done: boolean;
+    }[];
+    end?: RunEnd;
+    /** The host's own words when the stream ended without an end (e.g. this device may not run). */
+    error?: string;
+};
+export type RunAction = RunFrame | {
+    type: 'start';
+} | {
+    type: 'stop';
+} | {
+    type: 'error';
+    message: string;
+};
+export declare const RUN_IDLE: RunState;
+export declare function runStep(s: RunState, a: RunAction): RunState;
+/** The kit's sentences a failed run needs (`@byokit/openclaw/device`'s `words` fits). */
+export type RunWords = (key: 'member.signedOut' | 'member.resting' | 'member.plan' | 'member.network' | 'member.output', vars: {
+    name: string;
+    time: string;
+}) => string;
+export type RunWordsOptions = {
+    words: RunWords;
+    /** Who answers, as the person knows it: "ChatGPT". */
+    name: string;
+    /** How to say the time a resting plan is back; defaults to the device's short local time. */
+    time?: (ms: number) => string;
+};
+/** What to draw: the reply, the tool at work (if any), and the sentence for how it ended ('' when there is none). */
+export declare function runView(s: RunState, { words, name, time }: RunWordsOptions): {
+    phase: RunPhase;
+    text: string;
+    tools: {
+        name: string;
+        done: boolean;
+    }[];
+    /** The tool running right now, the latest one started. */
+    tool: string | undefined;
+    words: string;
+};
+/** What `runStore` needs from a device client: `openclawDevice(link)` fits. */
+export type RunSource = {
+    run(message: string, o?: {
+        sessionKey?: string;
+    }): AsyncIterable<RunFrame>;
+};
+/**
+ * One run at a time from a device: `send` starts one (stopping any still streaming), `stop` stops listening to it.
+ * Stopping here does not abort the run on the computer; pair it with the device's `abort(sessionKey)` for that.
+ */
+export declare function runStore(source: RunSource): Store<RunState> & {
+    send(message: string, o?: {
+        sessionKey?: string;
+    }): void;
+    stop(): void;
+};

package/dist/run.js

@@ -0,0 +1,85 @@
+// One agent run as a person sees it: the reply streaming in, the tools it uses, and how it ended in plain words.
+// Framework-free; typed structurally against `@byokit/openclaw/device`'s `run()`, so nothing here imports a kit.
+//   idle      nothing sent yet          running   the reply is streaming in
+//   done      the reply is complete     stopped   stopped before the end (here, or aborted on the computer)
+//   failed    it ended with a problem: `words` says which, in the kit's own sentence
+import { store } from "./follow.js";
+export const RUN_IDLE = { phase: 'idle', text: '', tools: [] };
+export function runStep(s, a) {
+    if (a.type === 'start')
+        return { phase: 'running', text: '', tools: [] };
+    if (s.phase !== 'running')
+        return s; // a finished run hears nothing more
+    switch (a.type) {
+        case 'started':
+        case 'thinking': return s;
+        case 'text': return { ...s, text: a.text };
+        case 'tool': {
+            if (a.phase === 'start')
+                return { ...s, tools: [...s.tools, { name: a.name, done: false }] };
+            const at = s.tools.findIndex((t) => t.name === a.name && !t.done);
+            return at < 0 ? s : { ...s, tools: s.tools.map((t, i) => (i === at ? { ...t, done: true } : t)) };
+        }
+        case 'end': {
+            const tools = s.tools.map((t) => (t.done ? t : { ...t, done: true }));
+            if (a.end.ok)
+                return { phase: 'done', text: a.end.text || s.text, tools, end: a.end };
+            return { ...s, phase: 'aborted' in a.end ? 'stopped' : 'failed', tools, end: a.end };
+        }
+        case 'error': return { ...s, phase: 'failed', error: a.message };
+        case 'stop': return { ...s, phase: 'stopped' };
+    }
+}
+const KEY = { 'signed-out': 'member.signedOut', resting: 'member.resting', plan: 'member.plan', network: 'member.network', output: 'member.output' };
+const clock = (ms) => new Date(ms).toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });
+/** What to draw: the reply, the tool at work (if any), and the sentence for how it ended ('' when there is none). */
+export function runView(s, { words, name, time = clock }) {
+    const end = s.end && !s.end.ok && 'kind' in s.end ? s.end : undefined;
+    const said = end && end.kind !== 'other'
+        ? words(KEY[end.kind], { name, time: end.until === undefined ? 'later' : time(end.until) })
+        : s.error ?? '';
+    return {
+        phase: s.phase, text: s.text, tools: s.tools,
+        /** The tool running right now, the latest one started. */
+        tool: s.tools.filter((t) => !t.done).pop()?.name,
+        words: said,
+    };
+}
+/**
+ * One run at a time from a device: `send` starts one (stopping any still streaming), `stop` stops listening to it.
+ * Stopping here does not abort the run on the computer; pair it with the device's `abort(sessionKey)` for that.
+ */
+export function runStore(source) {
+    const s = store(RUN_IDLE, () => () => { });
+    let current;
+    const send = (message, o) => {
+        current?.();
+        let stopped = false;
+        let it;
+        const step = (a) => { if (!stopped)
+            s.set(runStep(s.get(), a)); };
+        current = () => {
+            if (stopped)
+                return;
+            step({ type: 'stop' });
+            stopped = true;
+            void it?.return?.();
+        };
+        step({ type: 'start' });
+        void (async () => {
+            try {
+                it = source.run(message, o)[Symbol.asyncIterator]();
+                for (let r = await it.next(); !r.done && !stopped; r = await it.next())
+                    step(r.value);
+                step({ type: 'stop' }); // the stream ended without an end frame
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                // A stream the link cut ends with the link's bare reason ('unreachable'), not words: the run stopped here,
+                // and the link's own status says why.
+                step(/^[a-z][a-z-]*$/.test(message) ? { type: 'stop' } : { type: 'error', message });
+            }
+        })();
+    };
+    return { get: s.get, subscribe: s.subscribe, send, stop: () => current?.() };
+}

package/dist/steps.d.ts

@@ -0,0 +1,25 @@
+export type StepState = 'todo' | 'checking' | 'ok' | 'failed';
+/** One step as its caller reports it: `label` names the check ("Agent runner"), `detail` says how it stands
+ *  ("ready", "not installed on this computer"), and `fix` is the one next action when it fails. Ids are the
+ *  caller's own; nothing here knows any app's steps. */
+export type StepInput = {
+    id: string;
+    state: StepState;
+    label: string;
+    detail?: string;
+    fix?: string;
+};
+/** One row to draw: `words` is the plain sentence, `fix` the next action ("" until the step fails). */
+export type StepRow = {
+    id: string;
+    state: StepState;
+    words: string;
+    fix: string;
+};
+/** Turn the caller's steps into the rows to draw, in order. A failed step without its own `fix` says "Try again." */
+export declare function stepsView(steps: StepInput[]): StepRow[];
+/** The same rows as text lines for a terminal: `✓` done, `…` checking, `○` waiting, `✗` failed with its fix.
+ *  A phone draws the rows itself; this keeps the terminal showing the same words. */
+export declare function stepsText(rows: StepRow[], opts?: {
+    title?: string;
+}): string;

package/dist/steps.js

@@ -0,0 +1,16 @@
+/** Turn the caller's steps into the rows to draw, in order. A failed step without its own `fix` says "Try again." */
+export function stepsView(steps) {
+    return steps.map((s) => ({
+        id: s.id,
+        state: s.state,
+        words: s.detail ? `${s.label}: ${s.detail}` : s.label,
+        fix: s.state === 'failed' ? (s.fix || 'Try again.') : '',
+    }));
+}
+const mark = { ok: '✓', checking: '…', todo: '○', failed: '✗' };
+/** The same rows as text lines for a terminal: `✓` done, `…` checking, `○` waiting, `✗` failed with its fix.
+ *  A phone draws the rows itself; this keeps the terminal showing the same words. */
+export function stepsText(rows, opts) {
+    const lines = rows.map((r) => `  ${mark[r.state]} ${r.words}${r.state === 'failed' && r.fix ? ` ${r.fix}` : ''}`);
+    return opts?.title ? `${opts.title}\n${lines.join('\n')}` : lines.join('\n');
+}

package/dist/useAccounts.d.ts

@@ -0,0 +1,48 @@
+import { type Account, type AccountRow, type AccountsSource, type ModelInfo, type Pick, type PickerView, type Room, type RunSelection } from './accounts.ts';
+/** What the hooks remove through: an `AccountsSource` plus the back end's own removal, when the app allows it. */
+export type AccountHooksSource = AccountsSource & {
+    remove?: (id: string) => Promise<unknown>;
+};
+/** What the picker reads: the rows' source plus one model list per account and Auto's own pick. */
+export type ModelPickerSource = AccountHooksSource & {
+    models: (account: Account) => Promise<readonly ModelInfo[]> | readonly ModelInfo[];
+    auto: () => Promise<Pick> | Pick;
+};
+/** A live `@byokit/accounts` member: `list()`/`models()`/`pick()`/`remove()` fit with one line per member. */
+export type MemberAccounts<M> = {
+    list: (member: M) => Promise<readonly Account[]>;
+    models: (member: M, id: string) => Promise<readonly ModelInfo[]>;
+    pick: (member: M, sel: RunSelection, room?: (account: Account, demand: readonly string[]) => Room | Promise<Room>) => Promise<Pick>;
+    remove: (member: M, id: string) => Promise<unknown>;
+};
+/** A live `cliAccounts()` kit: `list()` fits with one line; `remove` when the app lets the person remove one. */
+export type CliAccounts = {
+    list: () => Promise<readonly Account[]>;
+    remove?: (id: string) => Promise<unknown>;
+};
+/** One line per member: the rows' source (with the picker's models and Auto pick) over a live `Accounts`. */
+export declare function accountsSource<M>(accounts: MemberAccounts<M>, member: M, room?: (account: Account) => Room | Promise<Room>): ModelPickerSource;
+/** One line: the rows' source over a live `cliAccounts()` kit, with each provider's plain name on its rows. */
+export declare function cliSource(cli: CliAccounts, room?: (account: Account) => Room | Promise<Room>): AccountHooksSource;
+export type UseAccounts = {
+    rows: AccountRow[];
+    ready: boolean;
+    error: unknown;
+    refresh: () => Promise<void>;
+    remove: (id: string) => Promise<void>;
+};
+/** The rows live: `refresh()` re-reads the source; the caller's removal of an id sticks across refreshes. */
+export declare function useAccounts(source: AccountHooksSource): UseAccounts;
+export type UseModelPicker = {
+    rows: AccountRow[];
+    picker: PickerView | null;
+    selection: RunSelection;
+    ready: boolean;
+    error: unknown;
+    select: (sel: RunSelection) => void;
+    refresh: () => Promise<void>;
+    remove: (id: string) => Promise<void>;
+};
+/** The run picker live: `select()` marks the selection at once (kept across refreshes); `refresh()` re-reads
+ *  accounts, models and Auto's pick together. `picker` is null until the first refresh resolves. */
+export declare function useModelPicker(source: ModelPickerSource, initial?: RunSelection): UseModelPicker;

package/dist/useAccounts.js

@@ -0,0 +1,156 @@
+// Live account rows and the run picker as React hooks over `./accounts.ts`. An app fills an `AccountsSource`
+// (or the fuller `ModelPickerSource`) from its own back end — one line per member — and draws the rows its own
+// way. A failing room leaves only its row unknown; a mid-refresh `remove()` still drops the row. No openclaw
+// adapter yet (pending O14).
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { accountRows, modelPicker, rowsOf } from "./accounts.js";
+const UNKNOWN_ROOM = { left: 'unknown' };
+const CLI_LABEL = { claude: 'Claude', codex: 'Codex', pi: 'Pi' };
+/** One line per member: the rows' source (with the picker's models and Auto pick) over a live `Accounts`. */
+export function accountsSource(accounts, member, room = () => UNKNOWN_ROOM) {
+    return {
+        accounts: () => accounts.list(member),
+        room,
+        models: (a) => accounts.models(member, a.id),
+        auto: () => accounts.pick(member, { account: 'auto' }, room),
+        remove: (id) => accounts.remove(member, id),
+    };
+}
+/** One line: the rows' source over a live `cliAccounts()` kit, with each provider's plain name on its rows. */
+export function cliSource(cli, room = () => UNKNOWN_ROOM) {
+    const remove = cli.remove;
+    return {
+        accounts: async () => (await cli.list()).map((c) => ({ ...c, label: CLI_LABEL[c.provider] ?? c.provider })),
+        room,
+        ...(remove ? { remove: (id) => remove(id) } : {}),
+    };
+}
+/** The rows live: `refresh()` re-reads the source; the caller's removal of an id sticks across refreshes. */
+export function useAccounts(source) {
+    const [rows, setRows] = useState([]);
+    const [ready, setReady] = useState(false);
+    const [error, setError] = useState(undefined);
+    const removed = useRef(new Set());
+    const gen = useRef(0);
+    const refresh = useCallback(async () => {
+        const g = ++gen.current;
+        let next;
+        try {
+            next = await rowsOf(source, Date.now());
+        }
+        catch (e) {
+            if (gen.current === g)
+                setError(e);
+            return;
+        }
+        if (gen.current !== g)
+            return;
+        setRows(next.filter((r) => !removed.current.has(r.id)));
+        setError(undefined);
+        setReady(true);
+    }, [source]);
+    useEffect(() => { void refresh(); }, [refresh]);
+    const remove = useCallback(async (id) => {
+        removed.current.add(id);
+        gen.current++;
+        setRows((prev) => prev.filter((r) => r.id !== id));
+        try {
+            await source.remove?.(id);
+        }
+        catch (e) {
+            removed.current.delete(id);
+            throw e;
+        }
+        await refresh();
+    }, [source, refresh]);
+    return { rows, ready, error, refresh, remove };
+}
+/** The run picker live: `select()` marks the selection at once (kept across refreshes); `refresh()` re-reads
+ *  accounts, models and Auto's pick together. `picker` is null until the first refresh resolves. */
+export function useModelPicker(source, initial = { account: 'auto' }) {
+    const [rows, setRows] = useState([]);
+    const [picker, setPicker] = useState(null);
+    const [selection, setSelection] = useState(initial);
+    const [ready, setReady] = useState(false);
+    const [error, setError] = useState(undefined);
+    const sel = useRef(initial);
+    const cache = useRef(null);
+    const removed = useRef(new Set());
+    const gen = useRef(0);
+    const refresh = useCallback(async () => {
+        const g = ++gen.current;
+        const now = Date.now();
+        let list;
+        try {
+            list = [...(await source.accounts())];
+        }
+        catch (e) {
+            if (gen.current === g)
+                setError(e);
+            return;
+        }
+        const live = list.filter((a) => !removed.current.has(a.id));
+        const rooms = new Map();
+        for (const a of live) {
+            try {
+                rooms.set(a.id, (await source.room(a)) ?? UNKNOWN_ROOM);
+            }
+            catch {
+                rooms.set(a.id, UNKNOWN_ROOM);
+            }
+        }
+        const models = {};
+        for (const a of live) {
+            try {
+                models[a.id] = await source.models(a);
+            }
+            catch {
+                models[a.id] = [];
+            }
+        }
+        let auto;
+        try {
+            auto = await source.auto();
+        }
+        catch (e) {
+            if (gen.current === g)
+                setError(e);
+            return;
+        }
+        if (gen.current !== g)
+            return;
+        cache.current = { accounts: live, models, auto };
+        setRows(accountRows(live, (a) => rooms.get(a.id) ?? UNKNOWN_ROOM, now).filter((r) => !removed.current.has(r.id)));
+        setPicker(modelPicker(live, models, sel.current, auto, now));
+        setError(undefined);
+        setReady(true);
+    }, [source]);
+    useEffect(() => { void refresh(); }, [refresh]);
+    const select = useCallback((next) => {
+        sel.current = next;
+        setSelection(next);
+        const c = cache.current;
+        if (c)
+            setPicker(modelPicker(c.accounts, c.models, next, c.auto, Date.now()));
+    }, []);
+    const remove = useCallback(async (id) => {
+        removed.current.add(id);
+        gen.current++;
+        setRows((prev) => prev.filter((r) => r.id !== id));
+        const c = cache.current;
+        if (c) {
+            const accounts = c.accounts.filter((a) => a.id !== id);
+            cache.current = { ...c, accounts };
+            setPicker(modelPicker(accounts, c.models, sel.current, c.auto, Date.now()));
+        }
+        try {
+            await source.remove?.(id);
+        }
+        catch (e) {
+            removed.current.delete(id);
+            throw e;
+        }
+        await refresh();
+    }, [source, refresh]);
+    return { rows, picker, selection, ready, error, select, refresh, remove };
+}

package/dist/useConnect.d.ts

@@ -0,0 +1,18 @@
+import { type ConnectAction, type ConnectRoute, type ConnectStep, type ConnectWords, type UseConnectSignIn } from './connect.ts';
+export type UseConnect = UseConnectSignIn & {
+    routes: readonly ConnectRoute[];
+    words?: ConnectWords;
+};
+export declare function useConnect({ routes, words, ...o }: UseConnect): {
+    step: ConnectStep;
+    act: (a: ConnectAction) => void;
+    pick: (key: string) => void;
+    back: () => void;
+    /** Pass to `useSignIn` in a sheet keyed by `chosen.row.key`; undefined unless a ready sign-in row is chosen. */
+    signIn: import("./useSignIn.ts").UseSignIn | undefined;
+    groups: import("./connect.ts").ConnectGroup[];
+    chosen?: {
+        row: import("./connect.ts").ConnectRow;
+        key?: ReturnType<typeof import("./key.ts").keyView>;
+    };
+};

package/dist/useConnect.js

@@ -0,0 +1,17 @@
+// The connect view as a React hook: holds the step, recomputes the view from the routes the app passes, and hands
+// the chosen sign-in row's options to `useSignIn`. Keys never enter it: the app sends the input to its kit and
+// reports only the result.
+import { useState } from 'react';
+import { connectStep, connectView, signInFor } from "./connect.js";
+export function useConnect({ routes, words, ...o }) {
+    const [step, setStep] = useState({ at: 'list' });
+    const view = connectView(routes, step, words);
+    const act = (a) => setStep((s) => connectStep(s, a));
+    return {
+        ...view, step, act,
+        pick: (key) => act({ type: 'pick', key }),
+        back: () => act({ type: 'back' }),
+        /** Pass to `useSignIn` in a sheet keyed by `chosen.row.key`; undefined unless a ready sign-in row is chosen. */
+        signIn: signInFor(view, o),
+    };
+}