@byokit/ui 0.0.0-stage → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## Unreleased
+
+- 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,310 @@
-# 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 '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/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`).
+
+```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 |
+| Types | `Phase`, `SignInView`, `AccountView`, `UseSignIn`, `Route`, `RouteChoice`, `RouteCode`, `PairPhase`, `Role`, `DeviceKind`, `LinkStatus`; `RouteKind` from `@byokit/ui/route` |
+
+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).
+
+## 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 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.
+
+`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.
+
+`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`.
+
+## Pairing words
+
+Pairing with `@byokit/link`, 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/link`](../link).
+- 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.

package/dist/approvals.d.ts

@@ -0,0 +1,47 @@
+import { type Store } from './follow.ts';
+/** One approval as the OpenClaw kit reports it. */
+export type Approval = {
+    id: string;
+    source: 'gate' | 'exec' | 'plugin' | 'question';
+    member: string;
+    sessionKey?: string;
+    tool?: string;
+    summary: string;
+    input?: unknown;
+    at: number;
+    /** When the computer stops waiting and says no by itself. */
+    expires: number;
+};
+/** An `oc.events` frame: an approval added or resolved, or any other event (ignored here). */
+export type ApprovalFrame = {
+    event: string;
+    change?: 'added' | 'resolved';
+    approval?: Approval;
+};
+export type ApprovalsAction = ApprovalFrame | {
+    type: 'set';
+    list: Approval[];
+} | {
+    type: 'tick';
+    now: number;
+};
+export declare function approvalsStep(list: Approval[], a: ApprovalsAction): Approval[];
+/** The question for one approval, in the kit's own sentence (`@byokit/openclaw/device`'s `words` fits). */
+export declare const approvalWords: (a: Approval, words: (key: "approval.ask", vars: {
+    helper: string;
+    summary: string;
+}) => string, helper: string) => string;
+/** What `approvalsStore` needs from a device client: `openclawDevice(link)` fits. */
+export type ApprovalsSource = {
+    approvals(): Promise<Approval[]>;
+    events(): AsyncIterable<ApprovalFrame>;
+};
+export type FollowOptions = {
+    retryMs?: number;
+    now?: () => number;
+};
+/**
+ * The approvals still waiting, live: listed once the event stream is open (so nothing falls between the two), then
+ * added and resolved from its frames, and each dropped as it expires. Opened again after the link comes back.
+ */
+export declare function approvalsStore(source: ApprovalsSource, { retryMs, now }?: FollowOptions): Store<Approval[]>;