@byokit/ui 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.7.0 (2026-10-12)
+
+- Dependency update: pins @byokit/accounts 0.22.0.
+
+- FEAT: Add `useAccounts` and `useModelPicker` to `@byokit/ui` (with the `accountsSource`/`cliSource` one-line-per-member adapters): live rows with `refresh()`, a failing room leaving only its row `Room left unknown`, a `remove()` landing mid-refresh still dropping the row, and a picker whose `select()` marks the selection at once and keeps it across refreshes. The openclaw adapter stays pending O14.
+- FEAT: Add `accountRows`, `rowsOf`, `nameSuggestions` and the `AccountsSource`, `AccountRow`, `Account` and `Room` types (also `@byokit/ui/accounts`, no React): one plain-words row per account (`ChatGPT · Work` / `Plus · 72% left this week`), honest words for every sign-in state, `low` at or below 20%, a `sign_in`/`wait` action, and untaken account-name suggestions from an email's local part that never put an email in a title.
+- FEAT: `herdrTreeView` groups carry `project`, the workspace folder's own name without the tab label, so rows can name an agent (computer, project, agent) without internal tab labels.
+- FEAT: Browser sign-in sheet and live panel views: `signInSheetView(request, { name, holder })` gives the sentence, buttons and chat chip for each request state; `signInsStore(oc)` keeps requests live from sign-in pings; `livePanelView(state)` says when to draw frames, take input, show "Reconnecting…" or ask to confirm an unexpected address. Typed structurally against `@byokit/openclaw` spec 5.17.
+- FEAT: Add `connectView(routes, step)`, `connectStep`, `signInFor` (also `@byokit/ui/connect`, no React) and `useConnect`: every account route the kits list, grouped as Plans (offered by default), Pay per use, On this computer, Your own server, Cloud account, Other ways to connect, and Speech, search and media, each row with plain billing, method and readiness words. Billing decides the group, so no API, cloud, local, server or unknown-billing row is ever in Plans; key routes reuse `keyView`, sign-in routes hand `useSignIn` their row.
+- FEAT: Add `modelPicker` and `bestMoveTarget` to `@byokit/ui/accounts` (no React, no Node): the run picker with the `Auto — most room left` row carrying the pick's own reason, one plain row per account with its model rows and the selection marked, unavailable rows with a typed why and `until`, Auto disabled with a typed reason when no account can be named, and the Auto-ordered account a running session should move to (`Move to Work` / `Couldn't move to Work`).
+- FEAT: plain pairing words for the phone page: `connectedWords(hostName, url?, kind?)` renders the connected line with the route just dialled (`Connected to Kitchen computer - same Wi-Fi.`), `routeShort(route)` gives the inline label, and `pairErrorWords(error)` reads a failed pairing as expired, wrong-code or the link's own sentence from @byokit/link's error code.
+- FEAT: `describeRoute` labels in plain words: `Same Wi-Fi`, `Temporary public link`, `Away from home` (this kit's relay address) and `Your own server`. No route, choice or status sentence carries an address, a protocol name or relay jargon.
+- The PWA example's account card now runs on the shared views: `accountRows`/`modelPicker` from `@byokit/ui/accounts` draw the rows and the run picker (Auto carries its own reason, a signed-out pick shows `Sign in first` and runs nothing), and `bestMoveTarget`/`moveWords` suggest the roomier account when the chosen one is low.
+- `@byokit/ui-core` is now published as `@byokit/ui`, with the same API and the same entries (`.`, `./phase`, `./route`, `./link`, `./kits`, `./steps`, `./connect`); its earlier versions are the `@byokit/ui-core` releases below. **Deprecated:** the `@byokit/ui-core` name; it stays published as a shim that re-exports this package through 0.7.x and is removed in 0.8.0.
+- Accept OpenClaw's admitted/thinking progress frames structurally without changing the existing run reducer's rendered state.
+
+- Dependency update: pins @byokit/accounts 0.21.0.
+
 - Run views accept structured-output failures and display the kit’s plain validation message.
 
 ## 0.6.0 (2026-10-01)

package/README.md

@@ -12,7 +12,7 @@ pairing sheet, the link's status, the route a phone takes home, and a runtime ki
 app keeps its own look. Everything except the React hooks is framework-free.</p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/docs/images/pwa-2-code.png" width="240" alt="A phone-width page titled 'byokit in a browser' reading 'Signing in to ChatGPT…' and 'On the ChatGPT page, type this code:', the code WDJB-MJHT in large letters, an 'Open ChatGPT' link and a Cancel button." />
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/docs/images/pwa-2-code.png" width="240" alt="A phone-width page titled Umer's AI plans, with the ChatGPT card reading 'Signing in to ChatGPT…' and 'On the ChatGPT page, type this code:', the code MOCK-10001 in large letters, 'Code expires in 14:59', and Open ChatGPT and Cancel buttons." />
   <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/2-compare.png" width="240" alt="A phone-width page titled 'Agents' with a 'Pair this phone' card reading 'Check your computer shows these two words, then say yes there.' above the words 'coast comet'." />
 </p>
 
@@ -35,7 +35,7 @@ npm install @byokit/ui
 ```
 
 React is an optional peer dependency, needed only for the hooks (`useSignIn`, `useRun`, `useApprovals`,
-`useHerdrTree`, `useBlocked`).
+`useHerdrTree`, `useBlocked`, `useConnect`, `useAccounts`, `useModelPicker`).
 
 ```ts
 import { phaseOf, stepOf } from '@byokit/ui/phase';
@@ -123,11 +123,13 @@ export function useChatGptSheet() {
 | `useRun`, `useApprovals`, `useHerdrTree`, `useBlocked` | React hooks over those stores |
 | `connectView(routes, step?)`, `connectStep(step, action)` | Every account route the kits list, grouped by how the person pays, with the picked row and its key card |
 | `signInFor(view, { read, start?, cancel })`, `useConnect({ routes, read, start?, cancel })` | `useSignIn`'s options for the picked sign-in row; the hook holds the step |
-| Types | `Phase`, `SignInView`, `AccountView`, `UseSignIn`, `Route`, `RouteChoice`, `RouteCode`, `PairPhase`, `Role`, `DeviceKind`, `LinkStatus`; `RouteKind` from `@byokit/ui/route` |
+| `accountRows(accounts, room, now)`, `rowsOf(source, now)`, `nameSuggestions(email, taken, provider?)` | One plain-words row per account (`ChatGPT · Work` / `Plus · 72% left this week`), the honest words for every sign-in state, and untaken account-name suggestions |
+| `useAccounts(source)`, `useModelPicker(source, initial?)` | React hooks: the rows live with `refresh()` and `remove()` (a failing room leaves only its row unknown; a mid-refresh remove still drops it), and the run picker with `select()` keeping the caller's selection across refreshes; `accountsSource(accounts, member, room?)` and `cliSource(cli, room?)` fill the source with one line per member (the openclaw adapter stays pending O14) |
+| Types | `Phase`, `SignInView`, `AccountView`, `UseSignIn`, `Route`, `RouteChoice`, `RouteCode`, `PairPhase`, `Role`, `DeviceKind`, `LinkStatus`; `RouteKind` from `@byokit/ui/route`; `Account`, `AccountRow`, `AccountAction`, `AccountsSource`, `Billing`, `Room`, `RoomSpan`, `SignInState` from `@byokit/ui/accounts` |
 
 Entry points: `@byokit/ui` (everything, including the React hooks), `@byokit/ui/phase`,
-`@byokit/ui/route`, `@byokit/ui/link`, `@byokit/ui/kits`, `@byokit/ui/steps` and
-`@byokit/ui/connect` (no React dependency).
+`@byokit/ui/route`, `@byokit/ui/link`, `@byokit/ui/kits`, `@byokit/ui/steps`,
+`@byokit/ui/connect` and `@byokit/ui/accounts` (no React dependency).
 
 ## Sign-in phases
 
@@ -152,14 +154,14 @@ into the phase to draw:
 ## Routes
 
 `describeRoute(url, kind?)` (also `@byokit/ui/route`, no React) names the route a dial address takes, for a
-pairing or settings screen. Pass `tailscale`, `direct`, `private`, or `lan` when known (map reach's `tailscale-direct`
-to `direct`); without provenance, 100.64/10 reads as a private network rather than assumed to be Tailscale, and the
-other home ranges read as same Wi-Fi.
+pairing or settings screen. Pass `tailscale`, `direct`, `private`, or `lan` when known (map
+[`@byokit/discover`](../discover)'s `tailscale-direct` to `direct`); without provenance, 100.64/10 reads as a private
+network rather than assumed to be Tailscale, and the other home ranges read as same Wi-Fi.
 
 `routeChoices()` (same entry, no React) is the one word table for the onboarding route list: `{ code, title,
-sentence, needs }` per route in recommendation order, a superset of reach's `Via` (it also covers the temporary
-public link and your own server, which reach does not probe). Reach's `recommend()` takes `sentence` and
-`needs` from here and only adds availability.
+sentence, needs }` per route in recommendation order, a superset of `@byokit/discover`'s `Via` (it also covers the
+temporary public link and your own server, which `reach()` there does not probe). `recommend()` from the same package
+takes `sentence` and `needs` from here and only adds availability.
 
 `connectedWords(hostName, url?, kind?)` (same entry) is 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.`)
@@ -210,9 +212,60 @@ A key route's `chosen.key` is the existing `keyView` card, labelled for its bill
 `useConnect({ routes, read, start?, cancel })` holds the step in React and returns the view with `pick`, `back`,
 `act` and `signIn`, the options to pass to `useSignIn` in a sheet keyed by `chosen.row.key`.
 
+## Account rows
+
+`accountRows(accounts, room, now)` (also `@byokit/ui/accounts`, no React) turns a list of accounts and a room reading
+into one plain row each: the provider and the person's own name for the account (`ChatGPT · Work`), then the plan and
+the room left (`Plus · 72% left this week`). A row also carries `state`, `billing`, `low` (room left at or below 20%,
+exactly 20 included, never true for an unknown room) and, when it helps, an `action`: `sign_in` for a signed-out or
+lapsed account, `wait` plus the `until` refill time for a resting one. `accountRows` reads only the fields it names,
+so a credential on an account never reaches a row. A row that is not ready shows its own honest words ("Checking…",
+"Cooling down", "Not signed in", "Sign in again", "Not in your plan") instead of the room.
+
+`AccountsSource` is the shape an app fills from its own back end — `accounts()` and `room(account)` — and `rowsOf(source, now)`
+awaits both and builds the same rows; `@byokit/accounts` `list()` and a room reading fit it with one line per member.
+`nameSuggestions(email, taken, provider?)` offers up to three untaken account names from an email's local part
+(deduped case-insensitively against `taken`), falling back to the provider's name; the email itself is never offered.
+
+```ts
+import { accountRows, nameSuggestions, type Account, type Room } from '@byokit/ui/accounts';
+
+declare const list: () => readonly Account[];
+declare const reading: (account: Account) => Room;
+const rows = accountRows(list(), reading, Date.now());
+// rows → [{ title: 'ChatGPT · Work', detail: 'Plus · 72% left this week', state: 'ready', low: false, ... }]
+console.log(nameSuggestions('umer@example.com', rows.map((r) => r.title)));
+```
+
+In React, `useAccounts(source)` keeps those rows live (`refresh()` re-reads; `remove(id)` removes through
+the back end and drops the row even mid-refresh), and `useModelPicker(source)` keeps the run picker live
+(`select()` marks the selection at once and keeps it across refreshes). `accountsSource(accounts, member,
+room?)` fills the source from a live `@byokit/accounts` member and `cliSource(cli, room?)` from a live
+`cliAccounts()` kit, each with one line per member; the openclaw adapter stays pending O14:
+
+```ts
+import { accountsSource, cliSource, useAccounts, useModelPicker } from '@byokit/ui';
+import type { Accounts } from '@byokit/accounts';
+import { cliAccounts } from '@byokit/accounts/cli';
+import type { Account, Room } from '@byokit/ui/accounts';
+
+declare const accounts: Accounts<any, number>;
+declare const cli: ReturnType<typeof cliAccounts>;
+declare const reading: (account: Account) => Room;
+const fromMember = accountsSource(accounts, 1, reading);
+const fromCli = cliSource(cli, reading);
+
+export function useAccountList() {
+  return useAccounts(fromCli); // { rows, ready, error, refresh, remove }
+}
+export function useRunPicker() {
+  return useModelPicker(fromMember); // { rows, picker, selection, ready, error, select, refresh, remove }
+}
+```
+
 ## Pairing words
 
-Pairing with `@byokit/link`, from `@byokit/ui/link` (no React either):
+Pairing with `@byokit/pair` (published as `@byokit/link` up to 0.8.x), from `@byokit/ui/link` (no React either):
 
 - `qrMatrix(offer.text, { border }?)`: the pairing QR as rows of dark and light modules, with its quiet border
   (2 unless given), to draw in any UI.
@@ -293,7 +346,7 @@ with the device client made once (`useMemo(() => herdrDevice(link), [link])`).
 ## Links
 
 - [byokit](../../README.md): the monorepo and its other packages, including
-  [`@byokit/accounts`](../accounts) and [`@byokit/link`](../link).
+  [`@byokit/accounts`](../accounts) and [`@byokit/pair`](../pair).
 - Examples: [`examples/pwa`](../../examples/pwa) (sign-in phases in a browser),
   [`examples/herdr-kit`](../../examples/herdr-kit) (pairing words and `herdrStore` from a phone browser),
   [`examples/expo`](../../examples/expo) (React Native).

package/dist/accounts.d.ts

@@ -0,0 +1,148 @@
+export type Billing = 'subscription' | 'api' | 'local' | 'free' | 'unknown';
+export type SignInState = 'ready' | 'signing' | 'resting' | 'signed_out' | 'needs_again' | 'not_included';
+export type RoomSpan = 'session' | 'week' | 'month' | 'tightest';
+/** A room-left reading, restated structurally from `@byokit/accounts` (multi.ts): a known percentage or 'unknown'. */
+export type Room = {
+    left: number;
+    span: RoomSpan;
+    resetsAt?: number;
+    at?: number;
+} | {
+    left: 'unknown';
+    at?: number;
+};
+/** One account as `@byokit/accounts` `list()` reports it; only these fields are read, extra ones (a token included) are ignored. */
+export type Account = {
+    id: string;
+    provider: string;
+    name: string;
+    label?: string;
+    state: SignInState;
+    billing: Billing;
+    plan?: string;
+    until?: number;
+};
+/** What an app supplies: the accounts it lists and one room reading per account. `AccountsSource` is the seam between
+ *  any back end and these rows; an at-most-one-line-per-member adapter fits it. */
+export type AccountsSource = {
+    accounts: () => Promise<readonly Account[]> | readonly Account[];
+    room: (account: Account) => Promise<Room> | Room;
+};
+export type AccountAction = 'sign_in' | 'wait';
+export type AccountRow = {
+    id: string;
+    title: string;
+    detail: string;
+    state: SignInState;
+    billing: Billing;
+    /** Room left is at or below 20%: true at exactly 20, false above it or when the room is unknown. */
+    low: boolean;
+    /** What the person can do: sign in again, or wait for a resting account to refill. Absent when nothing helps. */
+    action?: AccountAction;
+    /** A resting account's next refill, epoch milliseconds. */
+    until?: number;
+};
+/** One row per account, reading one room per account; a missing or throwing reading is 'Room left unknown'. */
+export declare function accountRows(accounts: readonly Account[], room: (account: Account) => Room, now: number): AccountRow[];
+/** `accountRows` over an `AccountsSource`: the app's own `accounts()` and `room()`, awaited; a failing room reads unknown. */
+export declare function rowsOf(source: AccountsSource, now: number): Promise<AccountRow[]>;
+/** Untaken names an app can offer for a new account, from the email's local part (never the email itself), else the
+ *  provider's name. Dedupes case-insensitively against `taken`; up to three. */
+export declare function nameSuggestions(email: string | undefined, taken: readonly string[], provider?: string): string[];
+/** Why one of an account's models cannot be used right now, restated from `@byokit/accounts` (multi.ts). */
+export type ModelWhy = 'plan' | 'resting' | 'signed_out';
+/** One model as `@byokit/accounts` `models()` lists it: a strong/fast tier, whether it can run, and, when it can't, why. */
+export type ModelInfo = {
+    id: string;
+    name: string;
+    tier?: 'strong' | 'fast';
+    available: boolean;
+    why?: ModelWhy;
+    until?: number;
+};
+/** What a run asks for, restated structurally: an account (or `default`/`auto`) and one model. */
+export type RunSelection = {
+    account: string | 'default' | 'auto';
+    model?: string;
+};
+/** Why Auto named (or could not name) an account, restated from `@byokit/accounts` `resolveSelection`. */
+export type PickWhy = 'chosen' | 'default' | 'first_ready' | 'only' | 'most_room' | 'earlier_reset' | 'list_order' | 'no_reading' | 'refills_first';
+/** Why an account cannot be used, as Auto judges it, restated from `@byokit/accounts` `Considered`. */
+export type PickOut = 'state' | 'resting' | 'billing' | 'model' | 'provider';
+/** One account's line in the pick's explanation; only the id, the why and the refill time are read here. */
+type ConsideredRow = {
+    id: string;
+    out?: PickOut;
+    until?: number;
+};
+/** `@byokit/accounts` `resolveSelection`/`pick`, restated structurally: what Auto chose, or why it could not. */
+export type Pick = {
+    ok: true;
+    account: Account;
+    model: string;
+    how: 'chosen' | 'default' | 'auto';
+    why: PickWhy;
+    reason: string;
+    considered?: readonly ConsideredRow[];
+} | {
+    ok: false;
+    code: 'none' | 'not_included' | 'unknown_account';
+    reason: string;
+    considered?: readonly ConsideredRow[];
+};
+/** One model row under an account, marked `selected` when it is the run's model. */
+export type PickerModel = ModelInfo & {
+    selected: boolean;
+};
+/** One picker row: the `Auto — most room left` row first, then one per account in list order. */
+export type PickerRow = {
+    /** `'auto'`, or the account id. */
+    key: string;
+    kind: 'auto' | 'account';
+    /** `Auto — most room left`, or the account's own plain title (`ChatGPT · Work`). */
+    title: string;
+    /** Auto's own reason in words on the Auto row; an account row's why, or its status when it can be used. */
+    detail: string;
+    /** True for the one row the run is set to use. */
+    selected: boolean;
+    /** True when the row cannot be chosen; only Auto, when it has no account to name. */
+    disabled: boolean;
+    /** Why Auto is disabled, typed from the pick's failure code; present only when `disabled`. */
+    disabledReason?: 'none' | 'not_included' | 'unknown_account';
+    /** Why the account cannot be used right now: a sign-in problem, a rest, per-use billing, a missing model, or
+     *  another service. Absent when it can be used. */
+    out?: PickOut;
+    /** A resting account's next refill, epoch milliseconds. */
+    until?: number;
+    /** This account's models, each marked when it is the run's model; empty for the Auto row. */
+    models: PickerModel[];
+};
+/** What a run or settings sheet draws: the rows, the named selection, and what it resolves to. */
+export type PickerView = {
+    rows: PickerRow[];
+    /** Exactly what `sel.account` named: `'auto'` or an account id. */
+    selection: string;
+    /** True when the selection resolves to a usable account and model. */
+    ok: boolean;
+    /** The account the run uses, when `ok`. */
+    account?: string;
+    /** The model the run uses, when `ok`. */
+    model?: string;
+};
+/** The one sentence a Move sheet shows: `Move to Work` after a tap, `Couldn't move to Work` after a refusal. */
+export declare function moveWords(name: string, moved?: boolean): string;
+/**
+ * The picker rows for a run selection, with the selection marked: the `Auto — most room left` row carrying Auto's
+ * own `pick.reason`, then one row per account with its model rows and, when it cannot be used, Auto's why and
+ * `until`. `auto` is the pick `@byokit/accounts` `resolveSelection` made for `{ account: 'auto' }`; a signed-out
+ * explicit pick is shown as `Sign in first` and never replaced by another account.
+ */
+export declare function modelPicker(accounts: readonly Account[], models: Record<string, readonly ModelInfo[]>, sel: RunSelection, auto: Pick, now?: number): PickerView;
+/**
+ * The account a running session should move to, or undefined when there is nowhere better to go: `@byokit/accounts`
+ * `chooseAccount`'s own winner (`moveToAccount` carries the session there). Nothing to move to with one account,
+ * with only signed-out peers, when nobody has room left, or when the list is API keys only; the current account is
+ * never named back to itself. `now` defaults to the current time, as `accountRows` does.
+ */
+export declare function bestMoveTarget(accounts: readonly Account[], room: Record<string, Room>, current: string, now?: number): string | undefined;
+export {};

package/dist/accounts.js

@@ -0,0 +1,175 @@
+// One row per account, in plain words: the provider and the person's own name for it, then the plan and the room
+// left, or the honest reason it is not usable right now. Framework-free and portable: it reads only the fields it
+// names (D3), so no credential on an account ever reaches a row. `AccountsSource` is the shape an app fills from its
+// own back end; @byokit/accounts `list()` and a room reading fit it with at most one line per member.
+import WORDS from './words.json' with { type: 'json' };
+const UNKNOWN = { left: 'unknown' };
+const LOW_AT = 20;
+const roomWords = (r) => r.left === 'unknown' ? WORDS['account.room.unknown'] : WORDS[`account.room.${r.span}`].replace('{left}', `${Math.round(r.left)}%`);
+const planLabel = (plan) => (plan ? plan.charAt(0).toUpperCase() + plan.slice(1) : '');
+/** 'ChatGPT · Work', or just the provider's own name when the account keeps it. An email is never used as a name. */
+function titleOf(a) {
+    const provider = a.label || a.provider;
+    const name = a.name && !a.name.includes('@') && a.name.toLowerCase() !== provider.toLowerCase() ? a.name : '';
+    return name ? `${provider} · ${name}` : provider;
+}
+/** A resting account whose refill time has passed reads as ready again, exactly as the Auto chooser treats it. */
+const refilled = (a, now) => a.state === 'resting' && typeof a.until === 'number' && a.until <= now;
+function rowOf(a, room, now) {
+    const state = refilled(a, now) ? 'ready' : a.state;
+    const title = titleOf(a);
+    if (state === 'ready') {
+        const words = roomWords(room);
+        return { id: a.id, title, detail: a.plan && room.left !== 'unknown' ? `${planLabel(a.plan)} · ${words}` : words, state, billing: a.billing,
+            low: room.left !== 'unknown' && room.left <= LOW_AT };
+    }
+    if (state === 'resting') {
+        return { id: a.id, title, detail: WORDS['account.resting'], state, billing: a.billing, low: false, action: 'wait',
+            ...(typeof a.until === 'number' ? { until: a.until } : {}) };
+    }
+    const action = state === 'signed_out' || state === 'needs_again' ? 'sign_in' : undefined;
+    return { id: a.id, title, detail: WORDS[`account.${state}`], state, billing: a.billing, low: false, ...(action ? { action } : {}) };
+}
+/** One row per account, reading one room per account; a missing or throwing reading is 'Room left unknown'. */
+export function accountRows(accounts, room, now) {
+    return accounts.map((a) => {
+        let r = UNKNOWN;
+        try {
+            r = room(a) ?? UNKNOWN;
+        }
+        catch {
+            r = UNKNOWN;
+        }
+        return rowOf(a, r, now);
+    });
+}
+/** `accountRows` over an `AccountsSource`: the app's own `accounts()` and `room()`, awaited; a failing room reads unknown. */
+export async function rowsOf(source, now) {
+    const accounts = await source.accounts();
+    const rooms = new Map();
+    for (const a of accounts) {
+        try {
+            rooms.set(a.id, (await source.room(a)) ?? UNKNOWN);
+        }
+        catch {
+            rooms.set(a.id, UNKNOWN);
+        }
+    }
+    return accountRows(accounts, (a) => rooms.get(a.id) ?? UNKNOWN, now);
+}
+/** Untaken names an app can offer for a new account, from the email's local part (never the email itself), else the
+ *  provider's name. Dedupes case-insensitively against `taken`; up to three. */
+export function nameSuggestions(email, taken, provider = 'Account') {
+    const used = new Set(taken.map((t) => t.trim().toLowerCase()).filter(Boolean));
+    const local = email?.split('@')[0]?.split(/[._-]+/).find(Boolean) ?? '';
+    const base = (local ? local.charAt(0).toUpperCase() + local.slice(1).toLowerCase() : provider).slice(0, 64) || provider;
+    const out = [];
+    for (let n = 1; out.length < 3 && n < 100; n++) {
+        const name = n === 1 ? base : `${base} ${n}`;
+        if (!used.has(name.toLowerCase())) {
+            out.push(name);
+            used.add(name.toLowerCase());
+        }
+    }
+    return out;
+}
+/** An account is usable when it is ready, or resting with its refill time already passed, exactly as a row reads. */
+const usableNow = (a, now) => a.state === 'ready' || refilled(a, now);
+/** The one sentence a Move sheet shows: `Move to Work` after a tap, `Couldn't move to Work` after a refusal. */
+export function moveWords(name, moved = true) {
+    return WORDS[moved ? 'move.to' : 'move.failed'].replace('{name}', name);
+}
+/**
+ * The picker rows for a run selection, with the selection marked: the `Auto — most room left` row carrying Auto's
+ * own `pick.reason`, then one row per account with its model rows and, when it cannot be used, Auto's why and
+ * `until`. `auto` is the pick `@byokit/accounts` `resolveSelection` made for `{ account: 'auto' }`; a signed-out
+ * explicit pick is shown as `Sign in first` and never replaced by another account.
+ */
+export function modelPicker(accounts, models, sel, auto, now = Date.now()) {
+    const considered = new Map((auto.considered ?? []).map((r) => [r.id, r]));
+    let account;
+    let model;
+    if (sel.account === 'auto') {
+        if (auto.ok) {
+            account = auto.account.id;
+            model = auto.model;
+        }
+    }
+    else {
+        const chosen = accounts.find((a) => a.id === sel.account);
+        if (chosen && usableNow(chosen, now)) {
+            const available = (models[chosen.id] ?? []).filter((m) => m.available);
+            const pick = sel.model && available.some((m) => m.id === sel.model) ? sel.model : available[0]?.id;
+            if (pick) {
+                account = chosen.id;
+                model = pick;
+            }
+        }
+    }
+    const rows = [{
+            key: 'auto', kind: 'auto', title: WORDS['picker.auto'], detail: auto.reason,
+            selected: sel.account === 'auto', disabled: !auto.ok, ...(auto.ok ? {} : { disabledReason: auto.code }), models: [],
+        }];
+    for (const a of accounts) {
+        const isSelected = sel.account === a.id;
+        const why = considered.get(a.id);
+        const out = why?.out ?? (usableNow(a, now) ? undefined : a.state === 'resting' ? 'resting' : 'state');
+        const rowModels = (models[a.id] ?? []).map((m) => ({ ...m, selected: a.id === account && m.id === model && m.available }));
+        rows.push({
+            key: a.id, kind: 'account', title: titleOf(a), detail: out ? WORDS[`picker.out.${out}`] : '', selected: isSelected, disabled: false,
+            ...(out ? { out } : {}), ...(out && why?.until !== undefined ? { until: why.until } : {}), models: rowModels,
+        });
+    }
+    const ok = account !== undefined && model !== undefined;
+    return { rows, selection: sel.account, ok, ...(ok ? { account, model } : {}) };
+}
+const MOVE_DAY_MS = 24 * 60 * 60 * 1000;
+const TIER_ORDER = { room: 0, unknown: 1, exhausted: 2 };
+/**
+ * Auto's winner among `accounts`, mirroring `@byokit/accounts` `chooseAccount` (multi.ts): subscriptions only, most
+ * room, unknown above exhausted, earliest reset then list order. Used by `bestMoveTarget`, and cross-checked against
+ * the real chooser over `fixtures/conformance/auto-pick-typescript.json`.
+ */
+function autoCandidate(accounts, room, now) {
+    const rows = accounts.map((a) => {
+        const r = room(a);
+        const age = typeof r.at === 'number' ? Math.max(0, now - r.at) : 'unknown';
+        const stale = typeof age === 'number' && age > MOVE_DAY_MS;
+        const left = r.left === 'unknown' || typeof r.left !== 'number' || stale ? 'unknown' : Math.max(0, Math.min(100, r.left));
+        let out;
+        if (a.state === 'resting' && typeof a.until === 'number' && a.until > now)
+            out = 'resting';
+        else if (a.state !== 'ready' && !(a.state === 'resting' && typeof a.until === 'number' && a.until <= now))
+            out = 'state';
+        else if (a.billing !== 'subscription')
+            out = 'billing';
+        const reset = r.left !== 'unknown' && typeof r.resetsAt === 'number' ? r.resetsAt : undefined;
+        const tier = left === 'unknown' ? 'unknown' : left > 0 || (reset !== undefined && reset <= now) ? 'room' : 'exhausted';
+        return { account: a, tier, left, ...(out ? { out } : {}), ...(reset !== undefined ? { resetsAt: reset } : {}) };
+    });
+    const ranked = rows.filter((c) => !c.out).sort((x, y) => {
+        const tier = TIER_ORDER[x.tier] - TIER_ORDER[y.tier];
+        if (tier)
+            return tier;
+        if (x.tier === 'unknown')
+            return 0;
+        if (x.tier === 'room' && x.left !== y.left)
+            return Number(y.left) - Number(x.left);
+        const rx = x.resetsAt ?? Infinity;
+        const ry = y.resetsAt ?? Infinity;
+        return rx === ry ? 0 : rx < ry ? -1 : 1;
+    });
+    return ranked[0];
+}
+/**
+ * The account a running session should move to, or undefined when there is nowhere better to go: `@byokit/accounts`
+ * `chooseAccount`'s own winner (`moveToAccount` carries the session there). Nothing to move to with one account,
+ * with only signed-out peers, when nobody has room left, or when the list is API keys only; the current account is
+ * never named back to itself. `now` defaults to the current time, as `accountRows` does.
+ */
+export function bestMoveTarget(accounts, room, current, now = Date.now()) {
+    const pick = autoCandidate(accounts, (a) => room[a.id] ?? { left: 'unknown' }, now);
+    if (!pick || pick.account.id === current || pick.tier === 'exhausted')
+        return undefined;
+    return pick.account.id;
+}

package/dist/index.d.ts

@@ -7,3 +7,5 @@ export * from './kits.ts';
 export { useApprovals, useBlocked, useHerdrTree, useRun } from './useKits.ts';
 export { connectStep, connectView, signInFor, type ConnectAction, type ConnectDoes, type ConnectGroup, type ConnectGroupId, type ConnectRoute, type ConnectRow, type ConnectStep, type ConnectView, type ConnectWords, type UseConnectSignIn } from './connect.ts';
 export { useConnect, type UseConnect } from './useConnect.ts';
+export { accountRows, nameSuggestions, rowsOf, type Account, type AccountAction, type AccountRow, type AccountsSource, type Billing, type Room, type RoomSpan, type SignInState } from './accounts.ts';
+export { accountsSource, cliSource, useAccounts, useModelPicker, type AccountHooksSource, type CliAccounts, type MemberAccounts, type ModelPickerSource, type UseAccounts, type UseModelPicker } from './useAccounts.ts';

package/dist/index.js

@@ -7,3 +7,5 @@ export * from "./kits.js";
 export { useApprovals, useBlocked, useHerdrTree, useRun } from "./useKits.js";
 export { connectStep, connectView, signInFor } from "./connect.js";
 export { useConnect } from "./useConnect.js";
+export { accountRows, nameSuggestions, rowsOf } from "./accounts.js";
+export { accountsSource, cliSource, useAccounts, useModelPicker } from "./useAccounts.js";

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/words.json

@@ -44,5 +44,23 @@
     "key.checking": "Checking your key…",
     "key.ok": "Your key is ready. It is used only when you choose this option.",
     "key.invalid": "This key could not be saved. Check it and try again.",
-    "key.notIncluded": "This option is not available here."
+    "key.notIncluded": "This option is not available here.",
+    "account.signing": "Checking…",
+    "account.resting": "Cooling down",
+    "account.signed_out": "Not signed in",
+    "account.needs_again": "Sign in again",
+    "account.not_included": "Not in your plan",
+    "account.room.unknown": "Room left unknown",
+    "account.room.session": "{left} left this session",
+    "account.room.week": "{left} left this week",
+    "account.room.month": "{left} left this month",
+    "account.room.tightest": "{left} left for now",
+    "picker.auto": "Auto — most room left",
+    "picker.out.state": "Sign in first",
+    "picker.out.resting": "Taking a break",
+    "picker.out.billing": "Pay per use, so picked only when you choose it",
+    "picker.out.model": "Doesn't include this run's model",
+    "picker.out.provider": "A different service",
+    "move.to": "Move to {name}",
+    "move.failed": "Couldn't move to {name}"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/ui",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Headless sign-in, pairing and runtime-kit view state for any UI, plus plain-words copy.",
   "license": "Apache-2.0",
   "type": "module",
@@ -40,6 +40,10 @@
     "./connect": {
       "types": "./dist/connect.d.ts",
       "default": "./dist/connect.js"
+    },
+    "./accounts": {
+      "types": "./dist/accounts.d.ts",
+      "default": "./dist/accounts.js"
     }
   },
   "files": [
@@ -58,8 +62,11 @@
     }
   },
   "devDependencies": {
+    "@byokit/accounts": "0.22.0",
     "@types/react": "^19.3.0",
-    "react": "^19.3.0"
+    "@types/react-test-renderer": "^19.3.0",
+    "react": "^19.3.0",
+    "react-test-renderer": "^19.3.0"
   },
   "publishConfig": {
     "access": "public"