@byokit/ui 0.0.0-stage → 0.7.0

package/dist/accounts.d.ts

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

package/dist/accounts.js

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

package/dist/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[]>;

package/dist/approvals.js

@@ -0,0 +1,63 @@
+// What is waiting for a person's yes: the approvals list kept current from the kit's event stream, each dropped when
+// it is answered anywhere or runs out of time. Framework-free; typed structurally against `@byokit/openclaw/device`.
+import { retrying, store } from "./follow.js";
+export function approvalsStep(list, a) {
+    if ('type' in a) {
+        if (a.type === 'set')
+            return a.list;
+        const live = list.filter((x) => x.expires > a.now);
+        return live.length === list.length ? list : live;
+    }
+    if (a.event !== 'approval' || !a.approval)
+        return list;
+    const { id } = a.approval;
+    const rest = list.filter((x) => x.id !== id);
+    if (a.change === 'resolved')
+        return rest.length === list.length ? list : rest;
+    if (a.change !== 'added')
+        return list;
+    const at = list.findIndex((x) => x.id === id);
+    return at < 0 ? [...list, a.approval] : list.map((x, i) => (i === at ? a.approval : x));
+}
+/** The question for one approval, in the kit's own sentence (`@byokit/openclaw/device`'s `words` fits). */
+export const approvalWords = (a, words, helper) => words('approval.ask', { helper, summary: a.summary });
+/**
+ * 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 function approvalsStore(source, { retryMs = 2000, now = Date.now } = {}) {
+    const made = store([], (set) => {
+        let list = made.get();
+        let timer;
+        const apply = (a) => {
+            list = approvalsStep(approvalsStep(list, a), { type: 'tick', now: now() });
+            clearTimeout(timer);
+            if (list.length > 0) {
+                const next = Math.min(...list.map((x) => x.expires)) - now();
+                timer = setTimeout(() => apply({ type: 'tick', now: now() }), Math.min(Math.max(next, 0), 2 ** 31 - 1));
+            }
+            set(list);
+        };
+        apply({ type: 'tick', now: now() }); // what was kept since the last watcher left may have expired meanwhile
+        const stop = retrying(async (live) => {
+            const it = source.events()[Symbol.asyncIterator]();
+            live.hold(it);
+            try {
+                const first = it.next(); // opens the stream before the list is read
+                first.catch(() => { });
+                const listed = await source.approvals();
+                if (live.stopped())
+                    return;
+                apply({ type: 'set', list: listed });
+                live.ok();
+                for (let r = await first; !r.done && !live.stopped(); r = await it.next())
+                    apply(r.value);
+            }
+            finally {
+                void it.return?.();
+            }
+        }, retryMs);
+        return () => { stop(); clearTimeout(timer); };
+    });
+    return made;
+}

package/dist/browser.d.ts

@@ -0,0 +1,101 @@
+import { type Store } from './follow.ts';
+import type { FollowOptions } from './approvals.ts';
+/** One sign-in request as the OpenClaw kit reports it (`NeedSignIn`). */
+export type SignInRequest = {
+    id: string;
+    gen: number;
+    member: string;
+    origin: string;
+    site: string;
+    secure: boolean;
+    firstTime: boolean;
+    agentNote?: string;
+    hints: string[];
+    choices: {
+        kind: 'takeover' | 'not-now' | 'cancel';
+    }[];
+    state: 'waiting' | 'held' | 'checking' | 'parked' | 'settled';
+    settled?: {
+        state: 'verified' | 'entered-unverified' | 'cancelled' | 'expired' | 'failed';
+        reason?: string;
+        resume?: {
+            state: 'pending' | 'accepted' | 'submitted' | 'indeterminate' | 'failed';
+        };
+    };
+    expires: number;
+};
+export type SignInAction = 'takeover' | 'notNow' | 'cancel' | 'done' | 'reopen' | 'retry';
+export type SignInWordKey = 'signin.waiting' | 'signin.private' | 'signin.checking' | 'signin.parked' | 'signin.verified' | 'signin.noVerifier' | 'signin.stillSignedOut' | 'signin.expired' | 'signin.cancelled' | 'signin.runReplaced' | 'signin.superseded' | 'signin.originMismatch' | 'signin.browserGone' | 'signin.resumeFailed' | 'signin.resumeUnknown' | 'signin.insecureRemote';
+export type SignInVars = {
+    site: string;
+    name: string;
+    origin: string;
+};
+export type SignInSheet = {
+    id: string;
+    gen: number;
+    /** `signin.title` with `site`. */
+    site: string;
+    /** The address the person is signing in on, shown in full; it states the address bar, never that a site is safe. */
+    origin: string;
+    secure: boolean;
+    /** First time on this site: `signin.confirmSite`, and the person types or picks the site before taking over. */
+    confirmSite: boolean;
+    /** The helper's own words, to show only as a quote (`signin.agentNote`), never as a title or button. */
+    note?: string;
+    hints: string[];
+    /** The one sentence under the title. */
+    line: {
+        key: SignInWordKey;
+        vars: SignInVars;
+    };
+    /** Buttons, in order. Empty while someone else signs in or the check runs. */
+    actions: SignInAction[];
+    /** The chip in the chat: `entered` ("Sign-in details entered"), `verified` ("Signed in to {site}"). */
+    chip?: 'entered' | 'verified';
+    /** Still waiting on the person: every outcome but a verified sign-in the helper went on from. */
+    needsYou: boolean;
+};
+/**
+ * What to draw for one request. `holder` is whether this device holds the takeover lease; `name` is the helper's
+ * name for the sentences.
+ */
+export declare function signInSheetView(r: SignInRequest, { name, holder }: {
+    name: string;
+    holder?: boolean;
+}): SignInSheet;
+/** A frame of the kit's event stream; only `byokit.browser` sign-in pings matter here. */
+export type BrowserFrame = {
+    event: string;
+    payload?: unknown;
+};
+/** What `signInsStore` needs from a device client: the kit's device client fits once its browser ops land (O22). */
+export type SignInsSource = {
+    signIns(): Promise<SignInRequest[]>;
+    events(): AsyncIterable<BrowserFrame>;
+};
+/**
+ * The member's sign-in requests, live: listed once the event stream is open (so no ping falls between the two), and
+ * listed again on every sign-in ping, which carries no origin or URL. Opened again after the link comes back.
+ */
+export declare function signInsStore(source: SignInsSource, { retryMs }?: Pick<FollowOptions, 'retryMs'>): Store<SignInRequest[]>;
+/** One live view's state as the kit reports it (`LiveViewState`), as far as drawing it needs. */
+export type LiveState = {
+    phase: 'connecting' | 'live' | 'reconnecting' | 'private' | 'ended' | 'failed';
+    mode: 'observe' | 'control';
+    origin?: string;
+    offOrigin?: boolean;
+};
+export type LivePanel = {
+    /** Draw frames; otherwise keep the last one dimmed under `line`, or a blank panel. */
+    showFrames: boolean;
+    /** Input goes to the page only while this is true: in control, live, and not paused on an unexpected address. */
+    input: boolean;
+    /** `confirmOrigin` button: the page moved to `origin`, which the person hasn't confirmed for this sign-in. */
+    confirmOrigin?: string;
+    line?: {
+        key: 'live.reconnecting' | 'signin.private' | 'signin.offOrigin';
+    };
+};
+/** What to draw for one live view. Watching never asks the helper anything. */
+export declare function livePanelView(s: LiveState): LivePanel;

package/dist/browser.js

@@ -0,0 +1,97 @@
+// The browser sign-in sheet and live view as a person sees them: which sentence to show, which buttons to offer, and
+// the chip under the chat. Framework-free; typed structurally against `@byokit/openclaw`'s `NeedSignIn` and
+// `LiveViewState` (spec 5.17), so nothing here imports a kit. Sentences are the kit's word keys plus their values,
+// for the kit's own `words` to say. Nothing here ever holds what the person types.
+import { retrying, store } from "./follow.js";
+const settledLine = (s) => {
+    switch (s.state) {
+        case 'verified':
+            return s.resume?.state === 'failed' ? 'signin.resumeFailed'
+                : s.resume?.state === 'indeterminate' ? 'signin.resumeUnknown' : 'signin.verified';
+        case 'entered-unverified': return s.reason === 'still-signed-out' ? 'signin.stillSignedOut' : 'signin.noVerifier';
+        case 'cancelled':
+            return s.reason === 'run-replaced' ? 'signin.runReplaced' : s.reason === 'superseded' ? 'signin.superseded' : 'signin.cancelled';
+        case 'expired': return 'signin.expired';
+        case 'failed': return s.reason === 'origin-mismatch' ? 'signin.originMismatch' : 'signin.browserGone';
+    }
+};
+/**
+ * What to draw for one request. `holder` is whether this device holds the takeover lease; `name` is the helper's
+ * name for the sentences.
+ */
+export function signInSheetView(r, { name, holder = false }) {
+    const vars = { site: r.site, name, origin: r.origin };
+    const can = (k) => r.choices.some((c) => c.kind === k);
+    const base = {
+        id: r.id, gen: r.gen, site: r.site, origin: r.origin, secure: r.secure, hints: r.hints,
+        confirmSite: r.firstTime && r.state === 'waiting', ...(r.agentNote ? { note: r.agentNote } : {}),
+    };
+    const line = (key) => ({ key, vars });
+    switch (r.state) {
+        case 'waiting': {
+            const actions = [];
+            if (can('takeover'))
+                actions.push('takeover');
+            if (can('not-now'))
+                actions.push('notNow');
+            return { ...base, line: line(r.secure ? 'signin.waiting' : 'signin.insecureRemote'), actions, needsYou: true };
+        }
+        case 'held':
+            return holder
+                ? { ...base, line: line('signin.waiting'), actions: ['done', 'notNow', 'cancel'], needsYou: true }
+                : { ...base, line: line('signin.private'), actions: [], needsYou: true };
+        case 'checking': return { ...base, line: line('signin.checking'), actions: [], chip: 'entered', needsYou: true };
+        case 'parked': return { ...base, line: line('signin.parked'), actions: ['reopen'], needsYou: true };
+        case 'settled': {
+            const s = r.settled ?? { state: 'failed' };
+            const key = settledLine(s);
+            const verified = s.state === 'verified';
+            const chip = verified ? 'verified' : s.state === 'entered-unverified' ? 'entered' : undefined;
+            return {
+                ...base, line: line(key), actions: verified ? [] : ['retry'], ...(chip ? { chip } : {}),
+                needsYou: key !== 'signin.verified',
+            };
+        }
+    }
+}
+const ping = (f) => f.event === 'byokit.browser' && f.payload?.kind === 'signin';
+/**
+ * The member's sign-in requests, live: listed once the event stream is open (so no ping falls between the two), and
+ * listed again on every sign-in ping, which carries no origin or URL. Opened again after the link comes back.
+ */
+export function signInsStore(source, { retryMs = 2000 } = {}) {
+    return store([], (set) => retrying(async (live) => {
+        const it = source.events()[Symbol.asyncIterator]();
+        live.hold(it);
+        try {
+            const first = it.next();
+            first.catch(() => { });
+            set(await source.signIns());
+            if (live.stopped())
+                return;
+            live.ok();
+            for (let r = await first; !r.done && !live.stopped(); r = await it.next()) {
+                if (ping(r.value))
+                    set(await source.signIns());
+            }
+        }
+        finally {
+            void it.return?.();
+        }
+    }, retryMs));
+}
+/** What to draw for one live view. Watching never asks the helper anything. */
+export function livePanelView(s) {
+    switch (s.phase) {
+        case 'live':
+            if (s.mode === 'control' && s.offOrigin) {
+                return { showFrames: true, input: false, line: { key: 'signin.offOrigin' }, ...(s.origin ? { confirmOrigin: s.origin } : {}) };
+            }
+            return { showFrames: true, input: s.mode === 'control' };
+        case 'connecting':
+        case 'reconnecting': return { showFrames: false, input: false, line: { key: 'live.reconnecting' } };
+        case 'private': return { showFrames: false, input: false, line: { key: 'signin.private' } };
+        case 'ended':
+        case 'failed': return { showFrames: false, input: false };
+    }
+}