@byokit/ui 0.0.0-stage → 0.6.0

package/dist/steps.d.ts

@@ -0,0 +1,25 @@
+export type StepState = 'todo' | 'checking' | 'ok' | 'failed';
+/** One step as its caller reports it: `label` names the check ("Agent runner"), `detail` says how it stands
+ *  ("ready", "not installed on this computer"), and `fix` is the one next action when it fails. Ids are the
+ *  caller's own; nothing here knows any app's steps. */
+export type StepInput = {
+    id: string;
+    state: StepState;
+    label: string;
+    detail?: string;
+    fix?: string;
+};
+/** One row to draw: `words` is the plain sentence, `fix` the next action ("" until the step fails). */
+export type StepRow = {
+    id: string;
+    state: StepState;
+    words: string;
+    fix: string;
+};
+/** Turn the caller's steps into the rows to draw, in order. A failed step without its own `fix` says "Try again." */
+export declare function stepsView(steps: StepInput[]): StepRow[];
+/** The same rows as text lines for a terminal: `✓` done, `…` checking, `○` waiting, `✗` failed with its fix.
+ *  A phone draws the rows itself; this keeps the terminal showing the same words. */
+export declare function stepsText(rows: StepRow[], opts?: {
+    title?: string;
+}): string;

package/dist/steps.js

@@ -0,0 +1,16 @@
+/** Turn the caller's steps into the rows to draw, in order. A failed step without its own `fix` says "Try again." */
+export function stepsView(steps) {
+    return steps.map((s) => ({
+        id: s.id,
+        state: s.state,
+        words: s.detail ? `${s.label}: ${s.detail}` : s.label,
+        fix: s.state === 'failed' ? (s.fix || 'Try again.') : '',
+    }));
+}
+const mark = { ok: '✓', checking: '…', todo: '○', failed: '✗' };
+/** The same rows as text lines for a terminal: `✓` done, `…` checking, `○` waiting, `✗` failed with its fix.
+ *  A phone draws the rows itself; this keeps the terminal showing the same words. */
+export function stepsText(rows, opts) {
+    const lines = rows.map((r) => `  ${mark[r.state]} ${r.words}${r.state === 'failed' && r.fix ? ` ${r.fix}` : ''}`);
+    return opts?.title ? `${opts.title}\n${lines.join('\n')}` : lines.join('\n');
+}

package/dist/useConnect.d.ts

@@ -0,0 +1,18 @@
+import { type ConnectAction, type ConnectRoute, type ConnectStep, type ConnectWords, type UseConnectSignIn } from './connect.ts';
+export type UseConnect = UseConnectSignIn & {
+    routes: readonly ConnectRoute[];
+    words?: ConnectWords;
+};
+export declare function useConnect({ routes, words, ...o }: UseConnect): {
+    step: ConnectStep;
+    act: (a: ConnectAction) => void;
+    pick: (key: string) => void;
+    back: () => void;
+    /** Pass to `useSignIn` in a sheet keyed by `chosen.row.key`; undefined unless a ready sign-in row is chosen. */
+    signIn: import("./useSignIn.ts").UseSignIn | undefined;
+    groups: import("./connect.ts").ConnectGroup[];
+    chosen?: {
+        row: import("./connect.ts").ConnectRow;
+        key?: ReturnType<typeof import("./key.ts").keyView>;
+    };
+};

package/dist/useConnect.js

@@ -0,0 +1,17 @@
+// The connect view as a React hook: holds the step, recomputes the view from the routes the app passes, and hands
+// the chosen sign-in row's options to `useSignIn`. Keys never enter it: the app sends the input to its kit and
+// reports only the result.
+import { useState } from 'react';
+import { connectStep, connectView, signInFor } from "./connect.js";
+export function useConnect({ routes, words, ...o }) {
+    const [step, setStep] = useState({ at: 'list' });
+    const view = connectView(routes, step, words);
+    const act = (a) => setStep((s) => connectStep(s, a));
+    return {
+        ...view, step, act,
+        pick: (key) => act({ type: 'pick', key }),
+        back: () => act({ type: 'back' }),
+        /** Pass to `useSignIn` in a sheet keyed by `chosen.row.key`; undefined unless a ready sign-in row is chosen. */
+        signIn: signInFor(view, o),
+    };
+}

package/dist/useKits.d.ts

@@ -0,0 +1,62 @@
+import { type Approval, type ApprovalsSource, type FollowOptions } from './approvals.ts';
+import { type HerdrSource } from './herdr.ts';
+import { type RunSource, type RunWordsOptions } from './run.ts';
+/** One run at a time: `send(message)` streams the reply in; `words` says how a failed run ended. */
+export declare function useRun(source: RunSource, o: RunWordsOptions): {
+    send: (message: string, o?: {
+        sessionKey?: string;
+    }) => void;
+    stop: () => void;
+    phase: import("./run.ts").RunPhase;
+    text: string;
+    tools: {
+        name: string;
+        done: boolean;
+    }[];
+    tool: string | undefined;
+    words: string;
+};
+/** The approvals waiting for a yes, live; `decide` answers one (it leaves the list when the computer says so). */
+export declare function useApprovals(source: ApprovalsSource & {
+    decide(id: string, d: {
+        allow: boolean;
+        reason?: string;
+        answer?: unknown;
+    }): Promise<void>;
+}, o?: FollowOptions): {
+    approvals: Approval[];
+    decide: (id: string, d: {
+        allow: boolean;
+        reason?: string;
+        answer?: unknown;
+    }) => Promise<void>;
+};
+/** Herdr's agents grouped by where they run, live; `agent(paneId)` finds one. `ready` once the computer has said. */
+export declare function useHerdrTree(source: HerdrSource): {
+    ready: boolean;
+    tree: import("./herdr.ts").HerdrTree | null;
+    groups: {
+        workspaceId: string;
+        tabId: string;
+        project: string;
+        where: string;
+        agents: import("./herdr.ts").AgentRow[];
+    }[];
+    agent: (paneId: string) => import("./herdr.ts").AgentRow | undefined;
+};
+/** The agents waiting for an answer, live; `answer` sends keys to one, with the revision it was asked at. */
+export declare function useBlocked(source: HerdrSource & {
+    answer(paneId: string, keys: string[], revision: number): Promise<void>;
+}): {
+    blocked: {
+        name: string;
+        paneId: string;
+        workspaceId: string;
+        tabId: string;
+        kind?: string;
+        revision: number;
+        prompt: string;
+        since: number;
+    }[];
+    answer: (paneId: string, keys: string[], revision: number) => Promise<void>;
+};

package/dist/useKits.js

@@ -0,0 +1,30 @@
+// The runtime kits' view state as React hooks (React and React Native alike). Each hook reads one of the
+// framework-free stores from `@byokit/ui/kits`; pass the same device client each render (e.g. from useMemo),
+// since a new one starts following afresh.
+import { useEffect, useMemo, useSyncExternalStore } from 'react';
+import { approvalsStore } from "./approvals.js";
+import { agentIn, blockedView, herdrStore, herdrTreeView } from "./herdr.js";
+import { runStore, runView } from "./run.js";
+const useStore = (s) => useSyncExternalStore(s.subscribe, s.get, s.get);
+/** One run at a time: `send(message)` streams the reply in; `words` says how a failed run ended. */
+export function useRun(source, o) {
+    const run = useMemo(() => runStore(source), [source]);
+    useEffect(() => run.stop, [run]); // leaving the screen stops listening
+    const state = useStore(run);
+    return { ...runView(state, o), send: run.send, stop: run.stop };
+}
+/** The approvals waiting for a yes, live; `decide` answers one (it leaves the list when the computer says so). */
+export function useApprovals(source, o) {
+    const approvals = useStore(useMemo(() => approvalsStore(source, o), [source]));
+    return { approvals, decide: (id, d) => source.decide(id, d) };
+}
+/** Herdr's agents grouped by where they run, live; `agent(paneId)` finds one. `ready` once the computer has said. */
+export function useHerdrTree(source) {
+    const { tree } = useStore(herdrStore(source));
+    return { ready: tree !== null, tree, groups: useMemo(() => herdrTreeView(tree), [tree]), agent: (paneId) => agentIn(tree, paneId) };
+}
+/** The agents waiting for an answer, live; `answer` sends keys to one, with the revision it was asked at. */
+export function useBlocked(source) {
+    const state = useStore(herdrStore(source));
+    return { blocked: useMemo(() => blockedView(state), [state]), answer: (paneId, keys, revision) => source.answer(paneId, keys, revision) };
+}

package/dist/useSignIn.d.ts

@@ -0,0 +1,32 @@
+import { type AccountView, type Phase } from './phase.ts';
+export type UseSignIn = {
+    /** This account, fresh from the back end. A rejection counts as the home computer being out of reach unless `offline` says otherwise. */
+    read: () => Promise<AccountView | null>;
+    /** Begin the sign-in on the back end. Absent when something else starts it (a CLI in a Herdr tab): the sheet
+     *  then only watches, and nothing begins as it opens. */
+    start?: (body?: {
+        via?: 'code';
+        fresh?: boolean;
+    }) => Promise<unknown>;
+    cancel: () => Promise<unknown>;
+    offline?: (e: unknown) => boolean;
+    ms?: number;
+    /** Draw one phase regardless (design review, screenshots): nothing starts and nothing polls. */
+    pinned?: Phase | null;
+};
+export declare function useSignIn({ read, start, cancel, offline: isOffline, ms, pinned }: UseSignIn): {
+    phase: Phase;
+    account: AccountView | null;
+    code: string | undefined;
+    url: string | undefined;
+    /** Start again: `{ via: 'code' }` for "Having trouble?", `{ fresh: true }` to pick the account again. */
+    start: (body?: {
+        via?: "code";
+        fresh?: boolean;
+    }) => void;
+    cancel: () => void;
+    /** "Keep this one": a work plan the person chose to use anyway. */
+    keepWork: () => void;
+    /** Closing the sheet mid-way cancels the sign-in too. */
+    close: () => void;
+};

package/dist/useSignIn.js

@@ -0,0 +1,38 @@
+// "Sign in with …" as a headless React hook: starts the sign-in as the sheet opens, polls the app's back end, and
+// reports the phase to draw. The app keeps its own look (and its own tab for the provider's page); this is the
+// behaviour every sign-in sheet shares.
+import { useEffect, useState } from 'react';
+import { phaseOf } from "./phase.js";
+export function useSignIn({ read, start, cancel, offline: isOffline = () => true, ms = 1500, pinned }) {
+    const [value, setValue] = useState(null);
+    const [offline, setOffline] = useState(false);
+    const [cancelled, setCancelled] = useState(false);
+    const [keepWork, setKeepWork] = useState(false);
+    useEffect(() => {
+        if (pinned)
+            return;
+        let alive = true;
+        const pull = () => read().then((v) => { if (alive) {
+            setValue(v);
+            setOffline(false);
+        } }, (e) => alive && isOffline(e) && setOffline(true));
+        pull();
+        const t = setInterval(pull, ms);
+        return () => { alive = false; clearInterval(t); };
+    }, [ms, pinned]);
+    const begin = (body = {}) => { setCancelled(false); start?.(body).catch(() => { }); };
+    useEffect(() => { if (!pinned && start)
+        begin(); }, []);
+    const phase = pinned ?? phaseOf(value, { offline, cancelled, keepWork });
+    return {
+        phase, account: value, code: value?.signIn?.code, url: value?.signIn?.url,
+        /** Start again: `{ via: 'code' }` for "Having trouble?", `{ fresh: true }` to pick the account again. */
+        start: begin,
+        cancel: () => { setCancelled(true); cancel().catch(() => { }); },
+        /** "Keep this one": a work plan the person chose to use anyway. */
+        keepWork: () => setKeepWork(true),
+        /** Closing the sheet mid-way cancels the sign-in too. */
+        close: () => { if (phase === 'waiting' || phase === 'opening' || phase === 'code')
+            cancel().catch(() => { }); },
+    };
+}

package/dist/words.json

@@ -0,0 +1,48 @@
+{
+    "connect.plans": "Plans",
+    "connect.plans.note": "Uses a plan you already pay for.",
+    "connect.perUse": "Pay per use",
+    "connect.perUse.note": "Charged each time you use it. Used only when you pick it.",
+    "connect.local": "On this computer",
+    "connect.local.note": "Runs on this computer. Used only when you pick it.",
+    "connect.server": "Your own server",
+    "connect.server.note": "A server you run. You say how it is paid for. Used only when you pick it.",
+    "connect.cloud": "Cloud account",
+    "connect.cloud.note": "Charged to your cloud account. Used only when you pick it.",
+    "connect.other": "Other ways to connect",
+    "connect.other.note": "How these are paid for is set by each company. Used only when you pick one.",
+    "connect.services": "Speech, search and media",
+    "connect.services.note": "Services other than chat. Used only when you pick one.",
+    "billing.subscription": "Uses your {name} plan",
+    "billing.api": "Charged per use to your {company} account",
+    "billing.local": "Runs on this computer",
+    "billing.server": "Your own server",
+    "billing.free": "Free tier from {company}",
+    "billing.unknown": "Billing set by {company}",
+    "via.browser": "Sign in on their page",
+    "via.code": "Sign in with a code",
+    "via.paste": "Sign in, then paste the code back",
+    "via.session": "Sign in",
+    "via.setup_token": "Paste a setup code from your plan",
+    "via.cli": "Sign in inside its own app",
+    "via.key": "Paste a key",
+    "via.plan_key": "Paste the key from your plan",
+    "via.cloud": "Use your cloud account",
+    "via.local": "Use a model on this computer",
+    "via.endpoint": "Use your own server's address",
+    "ready.ready": "Ready",
+    "ready.needs_binary": "Install its app on this computer first.",
+    "ready.needs_plugin": "Add its add-on first.",
+    "ready.needs_host": "Needs the app on your computer.",
+    "ready.needs_client": "Not set up for this app yet.",
+    "ready.unsupported_platform": "Not available on this device.",
+    "ready.no_upstream_flow": "This way to sign in is not available yet.",
+    "key.label.plan": "Key from your plan",
+    "key.label.perUse": "Key (charged per use)",
+    "key.label.other": "Key",
+    "key.entry": "Paste your key. It stays on this device.",
+    "key.checking": "Checking your key…",
+    "key.ok": "Your key is ready. It is used only when you choose this option.",
+    "key.invalid": "This key could not be saved. Check it and try again.",
+    "key.notIncluded": "This option is not available here."
+}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@byokit/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.0",
+  "description": "Headless sign-in, pairing and runtime-kit view state for any UI, plus plain-words copy.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umeranjum17/byokit.git",
+    "directory": "packages/ui"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./phase": {
+      "types": "./dist/phase.d.ts",
+      "default": "./dist/phase.js"
+    },
+    "./route": {
+      "types": "./dist/route.d.ts",
+      "default": "./dist/route.js"
+    },
+    "./link": {
+      "types": "./dist/link.d.ts",
+      "default": "./dist/link.js"
+    },
+    "./kits": {
+      "types": "./dist/kits.d.ts",
+      "default": "./dist/kits.js"
+    },
+    "./steps": {
+      "types": "./dist/steps.d.ts",
+      "default": "./dist/steps.js"
+    },
+    "./connect": {
+      "types": "./dist/connect.d.ts",
+      "default": "./dist/connect.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prepack": "tsc -b"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "react": "^19.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "uqr": "0.1.3"
+  }
+}