@byokit/ui 0.0.0-stage → 0.7.0

package/dist/connect.d.ts

@@ -0,0 +1,92 @@
+import WORDS from './words.json';
+import { keyView, type KeyAction, type KeyState } from './key.ts';
+import type { UseSignIn } from './useSignIn.ts';
+export type Billing = 'subscription' | 'api' | 'local' | 'free' | 'unknown';
+export type Via = 'browser' | 'code' | 'paste' | 'key' | 'session' | 'setup_token' | 'cli' | 'plan_key' | 'cloud' | 'local' | 'endpoint';
+export type Readiness = 'ready' | 'needs_binary' | 'needs_plugin' | 'needs_host' | 'needs_client' | 'unsupported_platform' | 'no_upstream_flow';
+/** One route as any kit's `routes()` lists it, restated structurally (D3): `@byokit/accounts` and
+ *  `@byokit/openclaw` route views fit as they are. Only these fields are read, so nothing else (a credential
+ *  included) can reach the view. */
+export type ConnectRoute = {
+    /** openclaw's is optional; a row without one is keyed `<provider>:<via>`. */
+    id?: string;
+    provider: string;
+    name?: string;
+    company?: string;
+    via: Via;
+    billing: Billing;
+    /** accounts: `'default' | 'explicit'`; openclaw: `offerPolicy` plus its legacy ready-only boolean `offer`. */
+    offer?: 'default' | 'explicit' | boolean;
+    offerPolicy?: 'default' | 'explicit';
+    /** openclaw: `services` marks speech, search, media and other non-chat rows. */
+    group?: 'models' | 'services';
+    upstream?: {
+        surface: 'accounts' | 'openclaw' | 'herdr';
+    };
+    readiness: Readiness;
+};
+export type ConnectGroupId = 'plans' | 'perUse' | 'local' | 'server' | 'cloud' | 'other' | 'services';
+/** What choosing a row leads to: a sign-in sheet (`useSignIn`), a key card (`keyView`), the app's own setup form
+ *  (cloud account, local model, server address and its billing), or the reason it cannot be used here. */
+export type ConnectDoes = 'signin' | 'key' | 'setup' | 'unavailable';
+export type ConnectRow = {
+    /** Unique across kits: `<surface>/<id>`. */
+    key: string;
+    id: string;
+    provider: string;
+    surface?: 'accounts' | 'openclaw' | 'herdr';
+    name: string;
+    company: string;
+    via: Via;
+    billing: Billing;
+    group: ConnectGroupId;
+    /** Offered by default: a ready subscription row. Never true for any other billing. */
+    offered: boolean;
+    ready: boolean;
+    readiness: Readiness;
+    does: ConnectDoes;
+    /** Plain words: how it is paid for, how you sign in, and whether it works here. */
+    billingWords: string;
+    method: string;
+    status: string;
+};
+export type ConnectGroup = {
+    id: ConnectGroupId;
+    title: string;
+    note: string;
+    rows: ConnectRow[];
+};
+export type ConnectStep = {
+    at: 'list';
+} | {
+    at: 'route';
+    key: string;
+    entry: KeyState;
+};
+export type ConnectAction = {
+    type: 'pick';
+    key: string;
+} | {
+    type: 'back';
+} | KeyAction;
+export type ConnectView = {
+    groups: ConnectGroup[];
+    /** The picked row and, for a key route, its key card. Undefined on the list or when the row is gone. */
+    chosen?: {
+        row: ConnectRow;
+        key?: ReturnType<typeof keyView>;
+    };
+};
+export type ConnectWords = typeof WORDS;
+export declare function connectStep(step: ConnectStep, action: ConnectAction): ConnectStep;
+/** Every route, grouped in a fixed order (empty groups left out), rows in the kits' own order. */
+export declare function connectView(routes: readonly ConnectRoute[], step?: ConnectStep, words?: ConnectWords): ConnectView;
+/** What the app does for the picked row, given that row; credentials go straight from the app to its kit. */
+export type UseConnectSignIn = Omit<UseSignIn, 'read' | 'start' | 'cancel'> & {
+    read: (row: ConnectRow) => ReturnType<UseSignIn['read']>;
+    start?: (row: ConnectRow, body?: Parameters<NonNullable<UseSignIn['start']>>[0]) => Promise<unknown>;
+    cancel: (row: ConnectRow) => Promise<unknown>;
+};
+/** `useSignIn`'s options for the chosen sign-in row, or undefined for any other step. Draw the sheet as its own
+ *  component keyed by `chosen.row.key` so a new pick starts with fresh sign-in state. */
+export declare function signInFor(view: ConnectView, o: UseConnectSignIn): UseSignIn | undefined;

package/dist/connect.js

@@ -0,0 +1,74 @@
+// "Connect an AI account" as headless view state: every route the kits list (D18), grouped by how the person pays,
+// with plain words for the billing, the method and whether it works here. Plans come first and are the only rows
+// offered by default; every other row is listed and used only when the person picks it. Nothing here names a
+// provider: groups and words come from each row's billing, method and readiness alone. Framework-free.
+import WORDS from './words.json' with { type: 'json' };
+import { keyStep, keyView } from "./key.js";
+const ORDER = ['plans', 'perUse', 'local', 'server', 'cloud', 'other', 'services'];
+const SIGNIN = ['browser', 'code', 'paste', 'session', 'cli'];
+const KEY = ['key', 'plan_key', 'setup_token'];
+const fill = (s, r) => s.replace(/\{(name|company)\}/g, (_, k) => r[k]);
+/** Cloud, server and local methods are always explicit and go to their own groups; then billing decides: only a
+ *  subscription row named default is a plan, so an API, free or unknown row never lands in Plans whatever its
+ *  `offer` says. */
+function groupOf(r) {
+    if (r.group === 'services')
+        return 'services';
+    if (r.via === 'cloud')
+        return 'cloud';
+    if (r.via === 'endpoint')
+        return 'server';
+    if (r.via === 'local')
+        return 'local';
+    const byDefault = r.offer === 'default' || r.offerPolicy === 'default' || r.offer === true;
+    if (r.billing === 'subscription' && byDefault)
+        return 'plans';
+    if (r.billing === 'local')
+        return 'local';
+    if (r.billing === 'api')
+        return 'perUse';
+    return 'other';
+}
+function rowOf(r, w) {
+    const name = r.name || r.provider, company = r.company || name, id = r.id ?? `${r.provider}:${r.via}`;
+    const group = groupOf(r);
+    const ready = r.readiness === 'ready';
+    const billing = r.via === 'endpoint' ? w['billing.server'] : r.via === 'local' ? w['billing.local'] : w[`billing.${r.billing}`];
+    return {
+        key: `${r.upstream?.surface ?? ''}/${id}`, id, provider: r.provider,
+        ...(r.upstream ? { surface: r.upstream.surface } : {}),
+        name, company, via: r.via, billing: r.billing, group,
+        offered: group === 'plans' && ready, ready, readiness: r.readiness,
+        does: !ready ? 'unavailable' : SIGNIN.includes(r.via) ? 'signin' : KEY.includes(r.via) ? 'key' : 'setup',
+        billingWords: fill(billing, { name, company }), method: w[`via.${r.via}`], status: w[`ready.${r.readiness}`],
+    };
+}
+export function connectStep(step, action) {
+    if (action.type === 'pick')
+        return { at: 'route', key: action.key, entry: 'entry' };
+    if (action.type === 'back')
+        return { at: 'list' };
+    return step.at === 'route' ? { ...step, entry: keyStep(step.entry, action) } : step;
+}
+/** Every route, grouped in a fixed order (empty groups left out), rows in the kits' own order. */
+export function connectView(routes, step = { at: 'list' }, words = WORDS) {
+    const rows = routes.map((r) => rowOf(r, words));
+    const groups = ORDER.map((id) => ({ id, title: words[`connect.${id}`], note: words[`connect.${id}.note`], rows: rows.filter((r) => r.group === id) }))
+        .filter((g) => g.rows.length);
+    const row = step.at === 'route' ? rows.find((r) => r.key === step.key) : undefined;
+    if (!row || step.at !== 'route')
+        return { groups };
+    if (row.does !== 'key')
+        return { groups, chosen: { row } };
+    const label = words[row.group === 'plans' ? 'key.label.plan' : row.billing === 'api' ? 'key.label.perUse' : 'key.label.other'];
+    return { groups, chosen: { row, key: keyView(step.entry, (k) => (k === 'key.label' ? label : words[k])) } };
+}
+/** `useSignIn`'s options for the chosen sign-in row, or undefined for any other step. Draw the sheet as its own
+ *  component keyed by `chosen.row.key` so a new pick starts with fresh sign-in state. */
+export function signInFor(view, o) {
+    const row = view.chosen?.row;
+    if (row?.does !== 'signin')
+        return undefined;
+    const { read, start, cancel, ...rest } = o;
+    return { ...rest, read: () => read(row), cancel: () => cancel(row), ...(start ? { start: (body) => start(row, body) } : {}) };
+}

package/dist/follow.d.ts

@@ -0,0 +1,17 @@
+export type Stop = () => void;
+/** A view any UI can draw from: the current state, and a way to hear each change (the returned function stops). */
+export type Store<T> = {
+    get(): T;
+    subscribe(fn: (state: T) => void): () => void;
+};
+type Live = {
+    hold(it: AsyncIterator<unknown>): void;
+    stopped(): boolean;
+    ok(): void;
+};
+export declare function retrying(attempt: (live: Live) => Promise<void>, retryMs: number): Stop;
+/** A store that follows its source only while someone listens: the first listener starts it, the last one stops it. */
+export declare function store<T>(initial: T, follow: (set: (state: T) => void) => Stop): Store<T> & {
+    set(state: T): void;
+};
+export {};

package/dist/follow.js

@@ -0,0 +1,72 @@
+// Keeping a live view going over a link: a view's event stream ends whenever the link drops or the host restarts, so
+// it opens again after a pause until the view stops or the pairing is gone for good. Framework-free.
+// Only a removed pairing never comes back; a stopped or refused link comes back with its `retry()`.
+const final = (e) => typeof e === 'object' && e !== null && e.code === 'removed';
+// ponytail: the pause doubles from 250 ms up to `retryMs` while tries fail, and starts short again once one works;
+// the link paces its own reconnects, so a stream only reopens into a link that is either back (it works, soon after
+// the link does) or still away (it fails at once, cheaply).
+export function retrying(attempt, retryMs) {
+    let stopped = false;
+    let pause = 0;
+    let current;
+    let timer;
+    let wake;
+    const live = {
+        hold: (it) => { current = it; if (stopped)
+            void it.return?.(); },
+        stopped: () => stopped,
+        ok: () => { pause = 0; },
+    };
+    void (async () => {
+        while (!stopped) {
+            try {
+                await attempt(live);
+            }
+            catch (e) {
+                if (final(e))
+                    return;
+            }
+            current = undefined;
+            if (stopped)
+                return;
+            pause = Math.min(pause ? pause * 2 : 250, retryMs);
+            await new Promise((resolve) => { wake = resolve; timer = setTimeout(resolve, pause); });
+        }
+    })();
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearTimeout(timer);
+        wake?.();
+        void current?.return?.();
+    };
+}
+/** A store that follows its source only while someone listens: the first listener starts it, the last one stops it. */
+export function store(initial, follow) {
+    let state = initial;
+    let stop;
+    const listeners = new Set();
+    const set = (next) => {
+        if (next === state)
+            return;
+        state = next;
+        for (const fn of [...listeners])
+            fn(state);
+    };
+    return {
+        get: () => state,
+        set,
+        subscribe: (fn) => {
+            listeners.add(fn);
+            stop ??= follow(set);
+            return () => {
+                if (!listeners.delete(fn) || listeners.size > 0)
+                    return;
+                const s = stop;
+                stop = undefined;
+                s?.();
+            };
+        },
+    };
+}

package/dist/herdr.d.ts

@@ -0,0 +1,103 @@
+import { type Store } from './follow.ts';
+export type AgentStatus = 'idle' | 'working' | 'blocked' | 'done' | 'unknown';
+export type HerdrAgent = {
+    kind?: string;
+    name?: string;
+    status: AgentStatus;
+    revision: number;
+    launchPending?: boolean;
+    interactiveReady?: boolean;
+};
+/** The tree as the Herdr kit reports it. */
+export type HerdrTree = {
+    connected: boolean;
+    workspaces: {
+        id: string;
+        label: string;
+        tabs: {
+            id: string;
+            label: string;
+            panes: {
+                id: string;
+                cwd?: string;
+                agent?: HerdrAgent;
+            }[];
+        }[];
+    }[];
+};
+/** An agent waiting for an answer, as the Herdr kit reports it; `revision` goes back with the answer. */
+export type BlockedAgent = {
+    paneId: string;
+    workspaceId: string;
+    tabId: string;
+    kind?: string;
+    revision: number;
+    prompt: string;
+    since: number;
+};
+/** One `hd.events` frame. */
+export type HerdrFrame = {
+    type: 'snapshot';
+    snapshot: HerdrTree;
+} | {
+    type: 'blocked';
+    change: 'added' | 'resolved';
+    blocked: BlockedAgent;
+} | {
+    type: 'raw';
+    line: string;
+};
+export type HerdrAction = HerdrFrame | {
+    type: 'listed';
+    blocked: BlockedAgent[];
+};
+/** `tree` is null until the computer first says what it has. */
+export type HerdrState = {
+    tree: HerdrTree | null;
+    blocked: BlockedAgent[];
+};
+export declare const HERDR_EMPTY: HerdrState;
+export declare function herdrStep(s: HerdrState, a: HerdrAction): HerdrState;
+/** An agent as a list row: its status is what the kit's `agentWords` takes ('starting' while it launches). */
+export type AgentRow = {
+    paneId: string;
+    name: string;
+    kind?: string;
+    status: AgentStatus | 'starting';
+    agent: HerdrAgent;
+};
+/** The agents grouped by where they run ("project · tab"), tabs without an agent left out. `project` is the
+ *  folder's own name alone, for rows that name the agent without the tab's internal label. */
+export declare function herdrTreeView(tree: HerdrTree | null): {
+    workspaceId: string;
+    tabId: string;
+    project: string;
+    where: string;
+    agents: AgentRow[];
+}[];
+/** The agent in one pane, if that pane has one. */
+export declare function agentIn(tree: HerdrTree | null, paneId: string | undefined): AgentRow | undefined;
+/** The waiting agents, each with the name to show for it. */
+export declare const blockedView: (s: HerdrState) => {
+    name: string;
+    paneId: string;
+    workspaceId: string;
+    tabId: string;
+    kind?: string;
+    revision: number;
+    prompt: string;
+    since: number;
+}[];
+/** What `herdrStore` needs from a device client: `herdrDevice(link)` fits. */
+export type HerdrSource = {
+    blocked(): Promise<BlockedAgent[]>;
+    events(): AsyncIterable<HerdrFrame>;
+};
+/**
+ * The tree and the waiting agents, live from one `hd.events` stream per device however many views watch it: the
+ * tree from its frames, the waiting list read once the stream is open and then kept by its frames. Opened again
+ * after the link comes back.
+ */
+export declare function herdrStore(source: HerdrSource, { retryMs }?: {
+    retryMs?: number;
+}): Store<HerdrState>;

package/dist/herdr.js

@@ -0,0 +1,88 @@
+// Herdr's agents as a person sees them: the tree (where each agent is, and how it is doing) and the agents waiting
+// for an answer, kept current from one `hd.events` stream. Framework-free; typed structurally against
+// `@byokit/herdr/device`, so nothing here imports the kit.
+import { retrying, store } from "./follow.js";
+export const HERDR_EMPTY = { tree: null, blocked: [] };
+export function herdrStep(s, a) {
+    if (a.type === 'snapshot') {
+        // A still-waiting agent can move on to a new revision with no question frame; the tree carries it, and the
+        // answer must go back with the current one.
+        const blocked = s.blocked.map((b) => {
+            const revision = agentIn(a.snapshot, b.paneId)?.agent.revision;
+            return revision === undefined || revision === b.revision ? b : { ...b, revision };
+        });
+        return { tree: a.snapshot, blocked: blocked.some((b, i) => b !== s.blocked[i]) ? blocked : s.blocked };
+    }
+    if (a.type === 'listed')
+        return { ...s, blocked: a.blocked };
+    if (a.type !== 'blocked')
+        return s;
+    const rest = s.blocked.filter((b) => b.paneId !== a.blocked.paneId);
+    if (a.change === 'resolved')
+        return rest.length === s.blocked.length ? s : { ...s, blocked: rest };
+    const at = s.blocked.findIndex((b) => b.paneId === a.blocked.paneId);
+    return { ...s, blocked: at < 0 ? [...s.blocked, a.blocked] : s.blocked.map((b, i) => (i === at ? a.blocked : b)) };
+}
+const row = (paneId, agent) => ({
+    paneId, name: agent.name ?? agent.kind ?? 'Agent', kind: agent.kind,
+    status: agent.launchPending ? 'starting' : agent.status, agent,
+});
+// A workspace labelled with its folder reads as the folder's own name.
+const place = (label) => label.split('/').filter(Boolean).pop() ?? label;
+/** The agents grouped by where they run ("project · tab"), tabs without an agent left out. `project` is the
+ *  folder's own name alone, for rows that name the agent without the tab's internal label. */
+export function herdrTreeView(tree) {
+    return (tree?.workspaces ?? []).flatMap((w) => w.tabs.map((t) => ({
+        workspaceId: w.id, tabId: t.id, project: place(w.label), where: `${place(w.label)} · ${t.label}`,
+        agents: t.panes.flatMap((p) => (p.agent ? [row(p.id, p.agent)] : [])),
+    }))).filter((g) => g.agents.length > 0);
+}
+/** The agent in one pane, if that pane has one. */
+export function agentIn(tree, paneId) {
+    for (const w of tree?.workspaces ?? [])
+        for (const t of w.tabs)
+            for (const p of t.panes) {
+                if (p.id === paneId)
+                    return p.agent ? row(p.id, p.agent) : undefined;
+            }
+    return undefined;
+}
+/** The waiting agents, each with the name to show for it. */
+export const blockedView = (s) => s.blocked.map((b) => ({ ...b, name: agentIn(s.tree, b.paneId)?.name ?? b.kind ?? 'Agent' }));
+const shared = new WeakMap();
+/**
+ * The tree and the waiting agents, live from one `hd.events` stream per device however many views watch it: the
+ * tree from its frames, the waiting list read once the stream is open and then kept by its frames. Opened again
+ * after the link comes back.
+ */
+export function herdrStore(source, { retryMs = 2000 } = {}) {
+    const known = shared.get(source);
+    if (known)
+        return known;
+    const made = store(HERDR_EMPTY, (set) => {
+        let s = made.get();
+        const apply = (a) => set(s = herdrStep(s, a));
+        return retrying(async (live) => {
+            const it = source.events()[Symbol.asyncIterator]();
+            live.hold(it);
+            try {
+                const r = await it.next(); // the first frame is the tree, sent once the stream is open
+                if (r.done || live.stopped())
+                    return;
+                const listed = await source.blocked(); // frames meanwhile wait in the stream, applied after the list
+                if (live.stopped())
+                    return;
+                apply(r.value);
+                apply({ type: 'listed', blocked: listed });
+                live.ok();
+                for (let r = await it.next(); !r.done && !live.stopped(); r = await it.next())
+                    apply(r.value);
+            }
+            finally {
+                void it.return?.();
+            }
+        }, retryMs);
+    });
+    shared.set(source, made);
+    return made;
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { phaseOf, stepOf, type AccountView, type Phase, type SignInView } from './phase.ts';
+export { connectedWords, describeRoute, routeChoices, routeShort, type Route, type RouteChoice, type RouteCode } from './route.ts';
+export { useSignIn, type UseSignIn } from './useSignIn.ts';
+export { stepsText, stepsView, type StepInput, type StepRow, type StepState } from './steps.ts';
+export { consentWords, linkWords, pairErrorWords, pairingView, qrMatrix, qrText, type DeviceKind, type LinkStatus, type PairPhase, type Role } from './link.ts';
+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

@@ -0,0 +1,11 @@
+export { phaseOf, stepOf } from "./phase.js";
+export { connectedWords, describeRoute, routeChoices, routeShort } from "./route.js";
+export { useSignIn } from "./useSignIn.js";
+export { stepsText, stepsView } from "./steps.js";
+export { consentWords, linkWords, pairErrorWords, pairingView, qrMatrix, qrText } from "./link.js";
+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/key.d.ts

@@ -0,0 +1,19 @@
+/** A key-entry card never holds a credential: the host submits the input directly to kit.addKey. */
+export type KeyState = 'entry' | 'checking' | 'ok' | 'invalid' | 'not_included';
+export type KeyAction = {
+    type: 'submit';
+} | {
+    type: 'edit';
+} | {
+    type: 'result';
+    result: 'ok' | 'invalid' | 'not_included';
+};
+export type KeyWords = (key: 'key.label' | 'key.entry' | 'key.checking' | 'key.ok' | 'key.invalid' | 'key.notIncluded') => string;
+export declare function keyStep(state: KeyState, action: KeyAction): KeyState;
+export declare function keyView(state: KeyState, words: KeyWords): {
+    state: KeyState;
+    label: string;
+    message: string;
+    busy: boolean;
+    editable: boolean;
+};

package/dist/key.js

@@ -0,0 +1,12 @@
+export function keyStep(state, action) {
+    if (action.type === 'submit')
+        return 'checking';
+    if (action.type === 'edit')
+        return 'entry';
+    return state === 'checking' ? action.result : state;
+}
+export function keyView(state, words) {
+    const keys = { entry: 'key.entry', checking: 'key.checking', ok: 'key.ok', invalid: 'key.invalid', not_included: 'key.notIncluded' };
+    return { state, label: words('key.label'), message: words(keys[state]), busy: state === 'checking',
+        editable: state === 'entry' || state === 'invalid' };
+}

package/dist/kits.d.ts

@@ -0,0 +1,6 @@
+export { RUN_IDLE, runStep, runStore, runView, type RunAction, type RunEnd, type RunEvent, type RunFrame, type RunPhase, type RunSource, type RunState, type RunWords, type RunWordsOptions } from './run.ts';
+export { approvalsStep, approvalsStore, approvalWords, type Approval, type ApprovalFrame, type ApprovalsAction, type ApprovalsSource, type FollowOptions } from './approvals.ts';
+export { HERDR_EMPTY, agentIn, blockedView, herdrStep, herdrStore, herdrTreeView, type AgentRow, type AgentStatus, type BlockedAgent, type HerdrAction, type HerdrAgent, type HerdrFrame, type HerdrSource, type HerdrState, type HerdrTree } from './herdr.ts';
+export type { Store } from './follow.ts';
+export { keyStep, keyView, type KeyAction, type KeyState, type KeyWords } from './key.ts';
+export { livePanelView, signInSheetView, signInsStore, type BrowserFrame, type LivePanel, type LiveState, type SignInAction, type SignInRequest, type SignInSheet, type SignInsSource, type SignInVars, type SignInWordKey } from './browser.ts';

package/dist/kits.js

@@ -0,0 +1,7 @@
+// View state for the runtime kits, with no React: reducers, views and live stores any UI can draw from (plain DOM,
+// React, React Native). The hooks in `@byokit/ui` read the same stores.
+export { RUN_IDLE, runStep, runStore, runView } from "./run.js";
+export { approvalsStep, approvalsStore, approvalWords } from "./approvals.js";
+export { HERDR_EMPTY, agentIn, blockedView, herdrStep, herdrStore, herdrTreeView } from "./herdr.js";
+export { keyStep, keyView } from "./key.js";
+export { livePanelView, signInSheetView, signInsStore } from "./browser.js";

package/dist/link.d.ts

@@ -0,0 +1,48 @@
+/** The QR for a pairing offer's text (`offer().text` from @byokit/link) as rows of dark (true) and light modules, with
+ *  the quiet border scanners need. Draw each true as a filled square in any UI: View grid, canvas, SVG or terminal.
+ *  `border` is that quiet border in modules, 2 unless given. */
+export declare const qrMatrix: (text: string, opts?: {
+    border?: number;
+}) => boolean[][];
+/** The same QR as text rows for a terminal: each line draws two module rows as half blocks (`█` both dark, `▀` top
+ *  only, `▄` bottom only), so `console.log(qrText(offer.text))` in setup scripts shows a code a phone can scan. */
+export declare function qrText(text: string, opts?: {
+    border?: number;
+}): string;
+/** What a pairing grants: `control` changes things on the computer, `view` only sees them. */
+export type Role = 'control' | 'view';
+/** Which device is pairing: a phone holding the app, or a browser that opened the pairing link. */
+export type DeviceKind = 'phone' | 'browser';
+/** The question before pairing: which computer, what this device may do, and for how long. `device` names the
+ *  pairing side when it isn't the app ("This browser …"), `detail` adds one app sentence after ("It can also …"). */
+export declare function consentWords(o: {
+    hostName: string;
+    role: Role;
+    device?: DeviceKind;
+    detail?: string;
+}): string;
+/** The pairing sheet's phases: `scan` the QR (or type the code), `compare` the two words with the computer, `waiting`
+ *  for a yes there, `paired`, or `failed` with the link's own sentence. */
+export type PairPhase = 'scan' | 'compare' | 'waiting' | 'paired' | 'failed';
+export declare function pairingView(o: {
+    phase: PairPhase;
+    hostName?: string;
+    words?: string;
+    error?: string;
+    device?: DeviceKind;
+    detail?: string;
+}): {
+    phase: PairPhase;
+    title: string;
+    words?: string;
+};
+/** A failed pairing as words for the phone's error line: `expired` when the code ran out (get a new one), `wrong`
+ *  when it didn't match (check and retry), else the link's own sentence. Reads @byokit/link's error `code` when it is
+ *  there (`wrong-code`, `expired`), else the message, so every path lands in the same plain words. */
+export declare function pairErrorWords(error: unknown): {
+    kind: 'expired' | 'wrong' | 'other';
+    words: string;
+};
+/** The link's status (`LinkStatus` from @byokit/link) as one sentence. */
+export type LinkStatus = 'connecting' | 'online' | 'offline' | 'refused' | 'removed';
+export declare function linkWords(status: LinkStatus, hostName?: string): string;

package/dist/link.js

@@ -0,0 +1,63 @@
+// What a pairing and a link put in front of a person, framework-free: the QR to show, the consent before pairing, the
+// two words to compare and the link's status, each in plain words. Pairs with @byokit/link.
+import { encode } from 'uqr';
+/** The QR for a pairing offer's text (`offer().text` from @byokit/link) as rows of dark (true) and light modules, with
+ *  the quiet border scanners need. Draw each true as a filled square in any UI: View grid, canvas, SVG or terminal.
+ *  `border` is that quiet border in modules, 2 unless given. */
+export const qrMatrix = (text, opts) => encode(text, { ecc: 'M', border: opts?.border ?? 2 }).data;
+/** The same QR as text rows for a terminal: each line draws two module rows as half blocks (`█` both dark, `▀` top
+ *  only, `▄` bottom only), so `console.log(qrText(offer.text))` in setup scripts shows a code a phone can scan. */
+export function qrText(text, opts) {
+    const m = qrMatrix(text, opts);
+    const rows = [];
+    for (let y = 0; y < m.length; y += 2) {
+        const top = m[y], bottom = m[y + 1] ?? [];
+        rows.push(top.map((dark, x) => {
+            const below = bottom[x] ?? false;
+            return dark ? (below ? '█' : '▀') : (below ? '▄' : ' ');
+        }).join('').replace(/\s+$/, ''));
+    }
+    return rows.join('\n');
+}
+const deviceWords = (device) => device === 'phone' ? 'This phone' : device === 'browser' ? 'This browser' : 'This device';
+/** The question before pairing: which computer, what this device may do, and for how long. `device` names the
+ *  pairing side when it isn't the app ("This browser …"), `detail` adds one app sentence after ("It can also …"). */
+export function consentWords(o) {
+    const may = o.role === 'control' ? 'see and change things on it' : 'see it, but not change anything';
+    const base = `Pair with ${o.hostName}? ${deviceWords(o.device)} will be able to ${may}, until you remove it there.`;
+    return o.detail ? `${base} ${o.detail}` : base;
+}
+export function pairingView(o) {
+    const name = o.hostName || 'your computer';
+    const title = (s) => (o.detail ? `${s} ${o.detail}` : s);
+    switch (o.phase) {
+        case 'scan': return { phase: o.phase, title: title(o.device === 'browser'
+                ? `Open the pairing link on ${name}, or type the code it shows.`
+                : `Scan the code on ${name}, or type the code it shows.`) };
+        case 'compare': return { phase: o.phase, title: title(`Check ${name} shows these two words, then say yes there.`), words: o.words };
+        case 'waiting': return { phase: o.phase, title: title(`Waiting for you to say yes on ${name}.`), words: o.words };
+        case 'paired': return { phase: o.phase, title: title(`${deviceWords(o.device)} is paired with ${name}.`) };
+        case 'failed': return { phase: o.phase, title: title(o.error || "Pairing didn't finish. Try again.") };
+    }
+}
+/** A failed pairing as words for the phone's error line: `expired` when the code ran out (get a new one), `wrong`
+ *  when it didn't match (check and retry), else the link's own sentence. Reads @byokit/link's error `code` when it is
+ *  there (`wrong-code`, `expired`), else the message, so every path lands in the same plain words. */
+export function pairErrorWords(error) {
+    const code = typeof error === 'object' && error !== null && 'code' in error ? String(error.code) : '';
+    const message = error instanceof Error ? error.message : String(error ?? '');
+    if (code === 'expired' || (code !== 'wrong-code' && /run out|expired/i.test(message)))
+        return { kind: 'expired', words: 'That pairing code has run out. Show a new one on your computer.' };
+    if (code === 'wrong-code' || /isn't a pairing code|didn't match|wrong/i.test(message))
+        return { kind: 'wrong', words: "That code didn't match. Check it, or show a new one on your computer." };
+    return { kind: 'other', words: message || "Pairing didn't finish. Try again." };
+}
+export function linkWords(status, hostName = 'your computer') {
+    return {
+        connecting: `Connecting to ${hostName}…`,
+        online: `Connected to ${hostName}.`,
+        offline: `Can't reach ${hostName} right now. This device keeps trying by itself.`,
+        refused: `${hostName} didn't let this device in. Pair it again there.`,
+        removed: `This device was removed on ${hostName}.`,
+    }[status];
+}