@byokit/ui 0.0.0-stage → 0.6.0

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,9 @@
+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';

package/dist/index.js

@@ -0,0 +1,9 @@
+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";

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];
+}

package/dist/phase.d.ts

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

package/dist/phase.js

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

package/dist/route.d.ts

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

package/dist/route.js

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

package/dist/run.d.ts

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

package/dist/run.js

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