@byokit/ui 0.0.0-stage → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+## 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)
+
+
+
+- API key (billed per use): framework-free `keyStep` and `keyView` entry-card states and plain billing/error words, without keeping a credential in view state.
+
+## 0.5.0 (2026-10-01)
+
+
+
+- `routeChoices()`: every onboarding route (`tailscale`, `tailscale-direct`, `private`, `lan`, plus `cloudflare`
+  and `external`) in everyday words (`{ code, title, sentence, needs }`), in recommendation order. The one word
+  table reach's `recommend()` draws `sentence` and `needs` from.
+
+## 0.4.0 (2026-09-30)
+
+- `@byokit/ui-core/steps` (no React): `stepsView(steps)` turns the caller's own steps into the rows a stepper or
+  inline checks draw (`{ id, state: todo | checking | ok | failed, words, fix }`, same in a terminal and on a
+  phone); `stepsText(rows, { title })` draws the same rows as text lines for a terminal. Step ids stay
+  caller-defined, and a failed step without its own `fix` says "Try again."
+
+## 0.3.0 (2026-09-30)
+
+- FIX: pairing links parse on React Native, where `URL.canParse` is missing and `hostname` is empty for `ws://`:
+  `describeRoute` reads the scheme and host itself.
+- `@byokit/ui-core/kits` (no React): view state for the runtime kits, typed structurally against
+  `@byokit/openclaw/device` and `@byokit/herdr/device` so neither kit is a dependency. Reducers `runStep`,
+  `approvalsStep` and `herdrStep`; views `runView` (the reply, the tool at work, and how a run ended in the kit's own
+  sentence), `approvalWords`, `herdrTreeView`, `agentIn` and `blockedView`; live stores `runStore`, `approvalsStore`
+  (listed once the event stream is open, dropped as each approval expires) and `herdrStore` (one `hd.events` stream
+  per device however many views watch it; a waiting agent's revision follows the tree, so an answer is never stale).
+  Stores reopen their stream soon after the link comes back (a stopped or refused link included, after its `retry()`)
+  and stop for good once the pairing is removed.
+- React hooks `useRun`, `useApprovals`, `useHerdrTree` and `useBlocked` over those stores, for React and React Native.
+- `qrMatrix(text, { border })` takes the quiet border in modules (2 unless given, as before), and `qrText(text,
+  { border })` draws the same QR as half-block text rows for a terminal, so a setup script shows a code a phone can scan.
+- `consentWords` and `pairingView` take an optional `device` (`phone`, or `browser`, which opens the pairing link
+  instead of scanning) and one app sentence (`detail`) after the title.
+- `useSignIn` works without `start`: when something else starts the sign-in, the sheet only watches, and nothing
+  begins as it opens.
+
+## 0.2.0
+
+- `@byokit/ui-core/link`: `qrMatrix`, `consentWords`, `pairingView` and `linkWords` for pairing with `@byokit/link` in any UI.
+
+## 0.1.1
+
+- The Apache-2.0 LICENSE ships in the tarball.
+
+## 0.1.0
+
+- Headless sign-in state and plain-words copy for any UI.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,363 @@
-# Temporary Holding Version
+<h1 align="center">@byokit/ui</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@byokit/ui"><img alt="npm" src="https://img.shields.io/npm/v/@byokit/ui?style=flat&label=npm" /></a>
+  <a href="https://github.com/umeranjum17/byokit/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/umeranjum17/byokit/ci.yml?style=flat&branch=main" /></a>
+  <a href="LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/badge/license-Apache--2.0-666?style=flat" /></a>
+</p>
+
+<p align="center"><strong>Headless sign-in, pairing and runtime-kit state, in plain words, for any UI.</strong><br/>
+It turns what your back end reports into the phase to draw and the sentence to show: a "Sign in with …" sheet, a
+pairing sheet, the link's status, the route a phone takes home, and a runtime kit's runs, approvals and agents. Your
+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 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>
+
+<p align="center"><sub>Left: the <code>code</code> phase from <code>phaseOf()</code>, drawn by <a href="../../examples/pwa">examples/pwa</a> against the mock OpenAI sign-in. Right: <code>pairingView()</code>'s <code>compare</code> words, drawn by <a href="../../examples/herdr-kit">examples/herdr-kit</a>.</sub></p>
+
+## Install
+
+```sh
+npm install @byokit/ui
+```
+
+[![npm](https://img.shields.io/npm/v/@byokit/ui?style=flat&label=)](https://www.npmjs.com/package/@byokit/ui) · [Latest release](https://github.com/umeranjum17/byokit/releases?q=ui-v) · [All releases](https://github.com/umeranjum17/byokit/releases)
+
+Migrating from `@byokit/ui-core`? See the [deprecated shim's migration guide](../ui-core/README.md#migrate).
+
+## Quickstart
+
+```sh
+npm install @byokit/ui
+```
+
+React is an optional peer dependency, needed only for the hooks (`useSignIn`, `useRun`, `useApprovals`,
+`useHerdrTree`, `useBlocked`, `useConnect`, `useAccounts`, `useModelPicker`).
+
+```ts
+import { phaseOf, stepOf } from '@byokit/ui/phase';
+import { describeRoute } from '@byokit/ui/route';
+import { consentWords, linkWords, pairingView, qrMatrix } from '@byokit/ui/link';
+
+// What the back end reports: a sign-in waiting on a typed code.
+const phase = phaseOf({ ready: false, signIn: { state: 'waiting', via: 'code', code: 'ABCD-1234' } });
+console.log(phase, stepOf(phase));
+console.log(phaseOf({ ready: true, work: true }));
+console.log(phaseOf({ signIn: { state: 'failed', why: 'busy' } }));
+
+console.log(describeRoute('wss://home.tail1234.ts.net/link'));
+console.log(describeRoute('ws://100.101.102.103:7777'));
+
+console.log(consentWords({ hostName: 'Kitchen computer', role: 'control' }));
+console.log(pairingView({ phase: 'compare', hostName: 'Kitchen computer', words: 'coast comet' }));
+console.log(linkWords('offline', 'Kitchen computer'));
+console.log(qrMatrix('hello').length, 'rows');
+```
+
+Output from running it with Node:
+
+```text
+code 1
+work
+busy
+Tailscale
+Private network
+Pair with Kitchen computer? This device will be able to see and change things on it, until you remove it there.
+{
+  phase: 'compare',
+  title: 'Check Kitchen computer shows these two words, then say yes there.',
+  words: 'coast comet'
+}
+Can't reach Kitchen computer right now. This device keeps trying by itself.
+25 rows
+```
+
+In React, `useSignIn` drives the whole sheet from three calls to your back end:
+
+```ts
+import { useSignIn } from '@byokit/ui';
+import type { AccountView } from '@byokit/ui';
+
+// Your back end's routes; the hook only needs these three calls.
+declare const api: {
+  account(): Promise<AccountView | null>;
+  signIn(body?: { via?: 'code'; fresh?: boolean }): Promise<unknown>;
+  cancel(): Promise<unknown>;
+};
+
+export function useChatGptSheet() {
+  const s = useSignIn({ read: () => api.account(), start: (b) => api.signIn(b), cancel: () => api.cancel() });
+  // s.phase: what to draw. s.code / s.url: what to show. s.start({ via: 'code' }): "Having trouble? Use a code instead".
+  // s.cancel(), s.close(), s.keepWork(): the sheet's buttons. Leave `start` out when something else starts the
+  // sign-in: the sheet then only watches, and nothing begins as it opens.
+  return s;
+}
+```
+
+## API at a glance
+
+| Export | What it does |
+|---|---|
+| `phaseOf(account, { offline, cancelled, keepWork })` | The sign-in phase to draw, from an `@byokit/accounts` `view()` plus whether the account is signed in |
+| `stepOf(phase)` | Where the three-step progress bar ("Open", "Say yes", "Done") stands |
+| `useSignIn({ read, start?, cancel, offline?, ms?, pinned? })` | React hook: starts the sign-in as the sheet opens, polls, and handles cancel, close, keep-work and "use a code instead"; without `start` it only watches and nothing begins |
+| `describeRoute(url, kind?)` | Names the route a dial address takes, for a pairing or settings screen |
+| `routeShort(route)` | The route as words inside a connected line (`same Wi-Fi`) |
+| `connectedWords(hostName, url?, kind?)` | The connected line to render (`Connected to Kitchen computer - same Wi-Fi.`), plain with no route |
+| `routeChoices()` | Every onboarding route in everyday words (`{ code, title, sentence, needs }`), in recommendation order |
+| `qrMatrix(text, { border }?)` | The pairing QR as rows of dark and light modules, with its quiet border (2 unless given) |
+| `qrText(text, { border }?)` | The same QR as half-block text rows for a terminal |
+| `consentWords({ hostName, role, device?, detail? })` | The question before pairing |
+| `pairingView({ phase, hostName?, words?, error?, device?, detail? })` | The pairing sheet's title and words for each phase |
+| `linkWords(status, hostName)` | The link's status in one sentence |
+| `pairErrorWords(error)` | A failed pairing as `expired`, `wrong` or the link's own sentence |
+| `stepsView(steps)` | The stepper rows to draw, from the caller's own step ids and states |
+| `stepsText(rows, { title })` | The same rows as text lines for a terminal |
+| `runStore(oc)`, `runView(state, { words, name })` | One run: the reply streaming in, the tool at work, how it ended in the kit's words |
+| `approvalsStore(oc)`, `approvalWords(a, words, helper)` | The approvals waiting for a yes, live, each gone when answered or expired |
+| `herdrStore(hd)`, `herdrTreeView(tree)`, `blockedView(state)` | Herdr's agents by where they run, and the ones waiting for an answer, live |
+| `signInsStore(oc)`, `signInSheetView(request, { name, holder })`, `livePanelView(state)` | The browser sign-in sheet (sentence, buttons, chat chip) and live panel for the OpenClaw kit's handoff |
+| `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 |
+| `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`,
+`@byokit/ui/connect` and `@byokit/ui/accounts` (no React dependency).
+
+## Sign-in phases
+
+`phaseOf()` turns what your back end reports (an `@byokit/accounts` `view()` plus whether the account is signed in)
+into the phase to draw:
+
+| Phase | Meaning |
+|---|---|
+| `opening` | getting the provider's page or a code ready |
+| `waiting` | say yes on the provider's page |
+| `code` | type this code on the provider's page instead |
+| `done` | signed in, and it works |
+| `work` | signed in with a work plan: offer a personal one |
+| `cancelled` | declined on the page, or cancelled here |
+| `busy` | something else on this computer is signing in |
+| `expired` | the page or code ran out of time |
+| `failed` | anything else, with a plain sentence |
+| `offline` | the home computer isn't answering |
+
+`phaseOf()` and `stepOf()` also come from `@byokit/ui/phase`, which has no React dependency.
+
+## 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
+[`@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 `@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.`)
+when there is no route to name.
+
+```ts
+import { routeChoices } from '@byokit/ui/route';
+
+console.log(routeChoices().map((c) => `${c.title}: ${c.sentence}`));
+```
+
+## Connect an account
+
+`connectView(routes, step?)` (also `@byokit/ui/connect`, no React) draws the "Connect an AI account" list from
+the routes the kits discover (D18 in `docs/runtime-kits.md`): pass `@byokit/accounts` `routes(host)` and
+`@byokit/openclaw` `routes(facts)` together, unfiltered. Every route is listed, unavailable ones too, in these groups
+(empty ones left out):
+
+| Group | Rows | Offered by default |
+|---|---|---|
+| Plans | subscription and plan-key routes the kit offers by default | yes, when ready |
+| Pay per use | API-billed routes | no, only when picked |
+| On this computer | local runtimes | no |
+| Your own server | endpoint routes; the person says how it is paid for | no |
+| Cloud account | cloud credentials | no |
+| Other ways to connect | free or unknown billing ("Billing set by …") | no |
+| Speech, search and media | non-chat services | no |
+
+Billing decides the group, never the route's `offer` alone: an API, cloud, local, server, free or unknown row can
+never sit among Plans. Each row has `billingWords` ("Uses your ChatGPT plan", "Charged per use to your OpenAI
+account"), `method` ("Sign in with a code") and `status` (a sentence per readiness), plus `offered`, `ready` and
+`does`: `signin`, `key`, `setup` (the app's own cloud, local or server form) or `unavailable`. The view copies only
+these fields, so a credential on a route never reaches it; nothing in it names a provider.
+
+```ts
+import { connectStep, connectView, signInFor } from '@byokit/ui/connect';
+import { routes } from '@byokit/accounts';
+
+declare const api: { account(id: string): Promise<null>; signIn(id: string, body?: object): Promise<void>; cancel(id: string): Promise<void> };
+const step = connectStep({ at: 'list' }, { type: 'pick', key: 'accounts/openai:code' });
+const view = connectView(routes({ platform: 'browser' }), step);
+// view.groups → the list; view.chosen.row.does === 'signin' → draw the sign-in sheet:
+const options = signInFor(view, { read: (row) => api.account(row.id), start: (row, body) => api.signIn(row.id, body), cancel: (row) => api.cancel(row.id) });
+```
+
+A key route's `chosen.key` is the existing `keyView` card, labelled for its billing ("Key from your plan" or "Key
+(charged per use)"); submit the input straight to the kit and dispatch only `{ type: 'result', result }`.
+`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/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.
+- `qrText(offer.text, { border }?)`: the same QR as half-block text rows, so `console.log` in a setup script shows a
+  code a phone can scan.
+- `consentWords({ hostName, role, device?, detail? })`: the question before pairing ("Pair with Kitchen computer? This device
+  will be able to see and change things on it, until you remove it there."). `device` names the pairing side when it
+  isn't the app (`phone`, or `browser` for the web pairing link); `detail` adds one app sentence after.
+- `pairingView({ phase, hostName, words, error, device?, detail? })`: scan, compare the two words, waiting for a yes, paired, failed.
+- `linkWords(status, hostName)`: the link's status in one sentence.
+
+## Stepper rows
+
+`stepsView()` (also `@byokit/ui/steps`, no React) turns the caller's own steps into the rows a stepper or
+inline checks draw, so a terminal and a phone show the same words. Each step keeps the id its caller chose, the
+state it is in (`todo`, `checking`, `ok`, `failed`), the plain words to show, and the one next action when it
+failed. `stepsText()` draws the same rows as text lines for a terminal; a phone draws the rows in its own list.
+A failed step without its own `fix` says "Try again."
+
+```ts
+import { stepsText, stepsView } from '@byokit/ui/steps';
+
+// Onboarding "Checking this computer": ids are the app's own, states come from its probes.
+const rows = stepsView([
+  { id: 'runner', state: 'ok', label: 'Agent runner', detail: 'ready' },
+  { id: 'agents', state: 'ok', label: 'Agents found', detail: 'Claude Code (signed in) · Codex (needs sign-in)' },
+  { id: 'wifi', state: 'ok', label: 'Wi-Fi', detail: 'this computer is at 192.168.1.144' },
+  { id: 'tailscale', state: 'todo', label: 'Tailscale', detail: 'not installed on this computer' },
+]);
+console.log(stepsText(rows, { title: 'Checking this computer' }));
+
+// "Setting up" reuses the same rows with its own ids; a failed check names its fix:
+console.log(stepsView([
+  { id: 'serve', state: 'failed', label: 'muxr', detail: 'not answering', fix: "muxr didn't start. Press r to retry." },
+])[0]);
+```
+
+Output from running it with Node:
+
+```text
+Checking this computer
+  ✓ Agent runner: ready
+  ✓ Agents found: Claude Code (signed in) · Codex (needs sign-in)
+  ✓ Wi-Fi: this computer is at 192.168.1.144
+  ○ Tailscale: not installed on this computer
+{
+  id: 'serve',
+  state: 'failed',
+  words: 'muxr: not answering',
+  fix: "muxr didn't start. Press r to retry."
+}
+```
+
+## Runtime kits' state
+
+Runtime kits' state, from `@byokit/ui/kits` (no React), typed to fit `@byokit/openclaw/device` and
+`@byokit/herdr/device` as they are:
+
+- Runs: `runStore(oc)` with `send(message)` and `stop()`; `runView(state, { words, name })` gives the reply so far, the
+  tool at work and, for a failed run, the kit's sentence (`words` from `@byokit/openclaw/device`, `name` "ChatGPT").
+  OpenClaw's `started` and `thinking` frames are accepted without changing the reply, tools or rendered state;
+  the running phase begins at `send`, not Gateway acceptance.
+- Approvals: `approvalsStore(oc)` keeps the waiting list live (each leaves when answered anywhere or when it expires);
+  `approvalWords(approval, words, 'Your helper')` asks the question.
+- Herdr: `herdrStore(hd)` keeps the tree and the agents waiting for an answer live from one stream;
+  `herdrTreeView(tree)` groups the agents by where they run, with the status the kit's `agentWords` takes;
+  `blockedView(state)` names each waiting agent.
+- Browser sign-in (`@byokit/openclaw` spec 5.17): `signInsStore(oc)` keeps the requests live from sign-in pings;
+  `signInSheetView(request, { name, holder })` gives the sentence (a kit word key and its values), the buttons and the
+  chat chip, which reads "entered" until a verified sign-in; `livePanelView(state)` says when to draw frames, take
+  input, show "Reconnecting…", or ask to confirm an address the person didn't expect. Watching asks the helper nothing.
+- Each store is `{ get, subscribe }`: draw from `get()` in any UI; the first `subscribe` starts following, the last
+  unsubscribe stops. `runStep`, `approvalsStep` and `herdrStep` are the reducers underneath.
+
+In React or React Native: `useRun(oc, { words, name })`, `useApprovals(oc)`, `useHerdrTree(hd)` and `useBlocked(hd)`,
+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/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).
+- [CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](../../NOTICE).
+
+`@byokit/ui/kits` also exports `keyStep(state, action)` and `keyView(state, words)` for an explicit
+**API key (billed per use)** entry card. States are `entry`, `checking`, `ok`, `invalid`, `not_included`;
+actions are `submit`, `edit`, and `result` with the kit's add-key outcome. Supply the OpenClaw kit's `words`
+function for the label and sentences. These views never contain the entered key; submit it directly to the host
+and clear the input afterwards.