@soba-so/react 0.0.16 → 0.0.18

package/dist/useCompute.d.ts

@@ -0,0 +1,91 @@
+import type { Machine, Runtime } from "./types.js";
+/**
+ * WHAT THIS PERSON HAS CONNECTED, IN WORDS — the headless half of
+ * `<ComputeStatus />` and `<ConnectCompute />`.
+ *
+ * `useSoba().compute` is already the raw list, and it is not enough to draw
+ * from. Every surface that tried re-derived the same five judgements, and the
+ * two below are ones this repo has got wrong in production:
+ *
+ * **"Nothing connected yet" is a claim about somebody's ACCOUNT**, and it is
+ * only true once the account has been read. While the first poll is in flight,
+ * or after it has failed, the honest answer is that we do not know — and saying
+ * the empty thing instead tells a person with a paired laptop that it has
+ * vanished, during an outage they cannot see and did not cause. `view` is that
+ * decision, made once. Two of our own components drew this list and only one of
+ * them knew the rule.
+ *
+ * **Machines in hand beat both flags.** The provider polls, so `loading` and
+ * `error` come back around; a poll that fails on its fourth round must not
+ * blank a list somebody is already reading.
+ *
+ * The rest is naming: a hostname is not what anybody calls the laptop on their
+ * desk, `darwin · arm64` is what a kernel calls itself, and a runtime's
+ * `authenticated` is tri-state all the way to the screen — "could not tell" is
+ * not "signed out", and rendering it as one tells somebody their working setup
+ * is broken.
+ */
+export interface ComputeRuntime {
+    runtime: Runtime;
+    /** "Claude Code". */
+    name: string;
+    /** Signed in, signed out, or we could not tell — with the tone to draw it
+     *  in. Never collapse `unknown` into `warn`. */
+    auth: {
+        tone: "ok" | "warn" | "unknown";
+        text: string;
+    };
+    /** It arrived on a machine that was already paired, so it waits to be let in
+     *  and serves nothing until somebody says so. */
+    quarantined: boolean;
+}
+export interface ComputeMachine {
+    machine: Machine;
+    /** What to call it: the name they gave it, else a tidied hostname. */
+    name: string;
+    /** One word plus a tone, for a dot. Agrees with the panel's own badge. */
+    state: {
+        tone: "ok" | "busy" | "off";
+        word: string;
+    };
+    /** The sentence version — "serving 2 of 4" — for where there is room. */
+    status: {
+        tone: "ok" | "busy" | "off";
+        text: string;
+    };
+    /** "MacBook · Apple silicon", or null when the worker reported nothing. */
+    hardware: string | null;
+    /** "3 days ago", or null while it is here. */
+    lastSeen: string | null;
+    /** The agents a person may send runs to: let in, and never the shell. */
+    runtimes: ComputeRuntime[];
+    /** Which agent this app's next run on it goes to, and whose decision that
+     *  was — the app's, the person's, or the machine's own first-found default. */
+    runsOn: {
+        by: "app" | "you" | "default";
+        name: string | null;
+    };
+}
+export interface ComputeView {
+    /**
+     * WHAT TO DRAW, decided once instead of by each surface. `empty` is a claim
+     * about the account and is only reached once one has actually been read.
+     */
+    view: "loading" | "error" | "empty" | "machines";
+    /** Every machine, named and worded, best-present first. */
+    machines: ComputeMachine[];
+    /** The one the panel is about: serving beats awake beats asleep, and within a
+     *  state the one heard from most recently. Null with nothing connected. */
+    primary: ComputeMachine | null;
+    /** Something paired. It may still be asleep — see `online`. */
+    connected: boolean;
+    /** Something of theirs could serve a run right now. */
+    online: boolean;
+    /** Paired and not reachable: the state an app goes silent in unless it says
+     *  something. `<ConnectNudge />`'s `stalled` reason is this one. */
+    stalled: ComputeMachine | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+export declare function useCompute(): ComputeView;

package/dist/useConnectButton.d.ts

@@ -0,0 +1,75 @@
+import type { Machine } from "./types.js";
+import { type ComputeMachine } from "./useCompute.js";
+/**
+ * WHAT THE CONTROL SAYS AND WHAT PRESSING IT DOES — the headless half of
+ * `<ConnectButton />`.
+ *
+ * Almost every app that drew its own version of this button got the same thing
+ * wrong, and it is not a styling question: **a button that still asks after
+ * they have connected is the screen telling them it did not work.** So the
+ * label is a function of what is attached, and so is what the press means —
+ * before anything is paired it opens the flow, and afterwards the honest
+ * reading of a press is "show me what I have".
+ *
+ * The word and its tone come from the same function the panel's own badge uses,
+ * so a dot an app draws here and the badge inside the sheet it opens cannot end
+ * up disagreeing about a laptop.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT CARRY is the popover: the panel that hangs
+ * off our pill is a component, not a decision, and an app building its own
+ * control has its own idea of where that goes. `connect.open()` raises the
+ * flow — the part that genuinely needs the screen — and `<ConnectCompute />`
+ * or `useCompute()` draws the machines wherever the app wants them.
+ */
+export interface ConnectButtonView {
+    /** "Connected", "Serving", "Asleep" — or "Connect compute" with nothing
+     *  paired. The whole label, ready to print. */
+    label: string;
+    /**
+     * The accessible name, which is not the label: on a narrow bar a host hides
+     * the words and leaves a mark and a dot, and a control whose only accessible
+     * name was those words then has none.
+     */
+    ariaLabel: string;
+    /** Something is paired. The label is about a machine when this is true. */
+    connected: boolean;
+    /** The machine the label is about, named and worded. Null until one is. */
+    machine: ComputeMachine | null;
+    /** One word plus a tone, for a dot beside the label. */
+    state: {
+        tone: "ok" | "busy" | "off";
+        word: string;
+    };
+    /** Raise the connect flow — the modal the provider mounts. */
+    open: () => void;
+    /** Whether `open()` does anything: false under `<SobaProvider modal={false}>`
+     *  with no modal placed, which is the honest state for a control with nothing
+     *  to control. */
+    canOpen: boolean;
+    /** The first read of the account is still in flight, so `connected` is not
+     *  yet an answer. */
+    loading: boolean;
+}
+export declare function useConnectButton(): ConnectButtonView;
+/**
+ * WHAT THE CONTROL SAYS ABOUT ONE MACHINE — the rule itself, with no hooks in
+ * it, because `<ConnectButton />` cannot read it off this hook.
+ *
+ * While its panel is open the pill's state is THIS APP'S RUNS rather than the
+ * machine's own counters: the run list is read every three seconds and is
+ * exactly this app's, where `state` and `active` arrive by heartbeat and count
+ * every app on that laptop. So the component substitutes its own machine list
+ * for those few seconds, and a hook reading the provider cannot.
+ *
+ * Both call this, so the words and the dot are one decision with two readers
+ * rather than two compositions that happen to agree today.
+ */
+export declare function connectSays(machine: Machine | null): {
+    label: string;
+    ariaLabel: string;
+    connected: boolean;
+    state: {
+        tone: "ok" | "busy" | "off";
+        word: string;
+    };
+};

package/dist/useConnectNudge.d.ts

@@ -0,0 +1,204 @@
+import type { Launch, Plan } from "./types.js";
+/**
+ * THE NUDGE'S DECISION, WITHOUT THE CARD.
+ *
+ * `<ConnectNudge />` is one rendering of this and renders nothing else, so a
+ * line an app writes from these values and the card we draw cannot disagree
+ * about whether there is anything worth saying.
+ *
+ * The hard part of this component was never the markup. It is knowing WHEN to
+ * speak: a nudge that shows up when it cannot help is an advertisement, and the
+ * four states below are four different reasons, three of which withdraw by
+ * themselves and one of which needs a way out. An app that wanted its own
+ * wording had to re-derive all of that from `plan` and `compute`, and the parts
+ * that are easy to get wrong — a credit is not an allowance, a paired machine
+ * is not a reachable one, `ask_to_connect` is the app's own switch — are
+ * exactly the parts nothing would have told it about.
+ */
+export type NudgeReason = 
+/** Nothing can run until something is attached. A prerequisite, not an offer. */
+"needed"
+/** The allowance is nearly gone and connecting would lift it. */
+ | "running"
+/** It runs either way, and the plan would rather it ran on theirs. */
+ | "preferred"
+/** A machine they already have has stopped answering. Not an offer at all. */
+ | "stalled";
+export interface NudgeStep {
+    lead: string;
+    detail: string;
+    /** The lead is a control that raises the connect flow, not a heading. */
+    opens?: boolean;
+    linksLead?: string;
+    links: {
+        label: string;
+        href: string;
+    }[];
+}
+/**
+ * The machine that went quiet, and what can be done about it from here.
+ * Non-null on `stalled` and null on every other reason.
+ */
+export interface NudgeStalled {
+    /** What to call it, or null when the list did not say. */
+    machine: string | null;
+    /** The plan can only reach compute this person owns, so there is no
+     *  elsewhere for a run to go while this one is quiet. */
+    ownCompute: boolean;
+    /** Bring the Soba app forward, which wakes a machine that was only asleep. */
+    wake: () => void;
+    /** What that attempt looked like, or null before one. See `useOpenSobaConnect`. */
+    launch: Launch | null;
+    /** The one line worth showing about the attempt, or null. */
+    note: string | null;
+    /**
+     * OPENED, AND STILL NOT BACK after twenty seconds.
+     *
+     * Waking cannot bring back a machine whose pairing with this app is gone: the
+     * app opens, says "Ready", and the machine this card names never reports in.
+     * While this is false the card's own offer is to wake it; once it is true the
+     * honest offer is to connect something again.
+     */
+    stuck: boolean;
+    /** Pair another machine, for when waking this one is not going to work. */
+    connectAnother: () => void;
+}
+export interface NudgeView {
+    /** The one claim worth making, or null for silence — which is most of the
+     *  time, and is the whole point of the component. */
+    reason: NudgeReason | null;
+    /** `reason !== null`. The name a host actually wants at the call site. */
+    visible: boolean;
+    title: string | null;
+    detail: string | null;
+    /**
+     * The allowance behind a `running` claim, null on every other reason.
+     * Not drawn by our own card any more — the title already says the number —
+     * but it is still what decides whether this person is stuck or merely warned.
+     */
+    meter: {
+        left: number;
+        of: number;
+    } | null;
+    /** True on `preferred` alone: the other three withdraw by themselves when the
+     *  fact behind them changes, and that one is true for as long as it works. */
+    dismissible: boolean;
+    /** Already waved off. `visible` is false when it is. */
+    dismissed: boolean;
+    dismiss: () => void;
+    /** Raise the connect flow. */
+    open: () => void;
+    /**
+     * Whether somebody is STOPPED rather than warned, which is what sizes the
+     * card: at the wall the steps are the way out, and above it they are clutter
+     * over a composer somebody can still use.
+     */
+    atTheWall: boolean;
+    /** Download, connect, allow — the three steps, for a host drawing its own. */
+    steps: NudgeStep[];
+    stalled: NudgeStalled | null;
+    /** The plan or the machines have not been read yet. Silent until they are. */
+    loading: boolean;
+}
+export interface UseConnectNudgeOptions {
+    /**
+     * How little has to be left before the `running` claim speaks. A fraction of
+     * the allowance rather than a count, so it means the same on a plan of 20 and
+     * a plan of 2,000.
+     */
+    at?: number;
+    /**
+     * WHAT THE LAST RUN CAME BACK WITH, and passing it at all changes which of
+     * the two integrations this is.
+     *
+     * Anything your catch block caught. Read through `sobaErrorCode`, so an
+     * unrelated failure is silence here and still renders however your app
+     * renders errors.
+     */
+    error?: unknown;
+    /** Both halves at once. Defaults to true exactly when `error` is not given —
+     *  see the note on `errorGiven`. */
+    predict?: boolean;
+    /**
+     * WHETHER AN `error` KEY WAS PRESENT AT ALL, which a hook cannot see for
+     * itself and a component can.
+     *
+     * `useState<unknown>(null)` is how every app holds its last failure, so a
+     * slot holding nothing has to mean "nothing has failed yet" and not "no
+     * argument was given". `<ConnectNudge />` answers this with `"error" in
+     * props`; a hook is passed one object and cannot tell an absent key from an
+     * explicit `undefined`, so a caller that holds a failure slot says so here.
+     * Leaving it out and passing `error` reads as the attempted integration,
+     * which is what passing an error means.
+     */
+    errorGiven?: boolean;
+    /**
+     * THE CEILING THE RUN WAS SENT UNDER, when your app narrows `route.allow`
+     * per run rather than leaving the question to the plan.
+     *
+     * An explicit `null` is no ceiling; `undefined` falls back to the plan rather
+     * than claiming anything. It narrows what this SAYS, never what a run may do.
+     */
+    allow?: string[] | null;
+}
+/**
+ * THE WHOLE DECISION, AS A PURE FUNCTION over facts an app already holds.
+ *
+ * Exported for the reason `useRunLimit` exports `foreseen`: this is the part
+ * worth testing and the part worth reading, and neither should need React to
+ * run. The hook below is the wiring — context, the dismissal in storage, and
+ * the twenty seconds after which waking a machine has visibly not worked.
+ */
+export interface NudgeSaid {
+    reason: NudgeReason;
+    title: string;
+    detail: string;
+    meter: {
+        left: number;
+        of: number;
+    } | null;
+    dismissible: boolean;
+    atTheWall: boolean;
+    /** On `stalled`: the plan can only reach compute this person owns, so there
+     *  is no elsewhere for a run to go while this machine is quiet. */
+    ownCompute: boolean;
+}
+export interface NudgeInput {
+    /** The plan they are on. Null while it loads, or when they are on none —
+     *  either way there is nothing to claim. */
+    plan: Plan | null;
+    /** The allowance arithmetic, as `useSoba().plan` already derives it. */
+    allowance: {
+        remaining: number | null;
+        included: number | null;
+    };
+    /** Something paired. It may still be asleep. */
+    connected: boolean;
+    /** Something of theirs could serve a run right now. */
+    online: boolean;
+    /** The machine that has gone quiet, named. Null unless one has. */
+    quiet: string | null;
+    error?: unknown;
+    /** Whether to speak about what is already in the way, or only about a run
+     *  that has actually been refused. */
+    predict: boolean;
+    /** The ceiling the run was sent under. `undefined` falls back to the plan. */
+    allow?: string[] | null;
+    /** How little has to be left before the `running` claim speaks. */
+    at: number;
+    /** The dismissible claim has already been waved off. */
+    waved: boolean;
+}
+export declare function nudgeSays(input: NudgeInput): NudgeSaid | null;
+export declare function useConnectNudge(options?: UseConnectNudgeOptions): NudgeView;
+/**
+ * A step that names a screen somebody does not have, or one they cannot reach
+ * from here, is an instruction to go and find something — which is where people
+ * stop. So the builds are links, the second step opens the flow it describes,
+ * and the third answers the question it raises.
+ *
+ * If the flow changes this list is wrong and nothing will fail to tell us — the
+ * one real cost of naming screens, and worth paying, because a list that could
+ * not be wrong was not saying anything.
+ */
+export declare function stepsFor(app: string | undefined, origin: string): NudgeStep[];

package/dist/useModel.d.ts

@@ -0,0 +1,93 @@
+import type { ModelGroup, ModelOption } from "./types.js";
+export interface UseModelOptions {
+    /**
+     * CONTROLLED. Pass both, or neither — a `value` without an `onChange` is a
+     * picker that cannot be changed, which is a label.
+     *
+     * Passing them turns off the remembered pick entirely: the app owns the
+     * value, and two places writing one preference is how it ends up disagreeing
+     * with itself across two tabs.
+     */
+    value?: string;
+    onChange?: (id: string) => void;
+    /** What a first-time visitor gets. `auto` unless you have a reason. */
+    defaultValue?: string;
+    /**
+     * Remember the pick in this browser, per app and per person. Left on: the
+     * person chose a model for themselves rather than for a page, and a reload
+     * putting them back on Automatic is the app forgetting what they said.
+     * Ignored under `value`.
+     */
+    remember?: boolean;
+    /**
+     * WHO THEY ARE, when the app knows, so two people sharing a browser do not
+     * share a pick. Many apps resolve the person server-side from a cookie and
+     * never tell the browser — that is the better design, and then the pick is
+     * scoped to the app alone. It is folded before it is stored, never sent
+     * anywhere, and the worst case on a shared machine is that a stranger learns
+     * somebody here prefers Haiku.
+     */
+    user?: string;
+}
+export interface ModelView {
+    /** Every model this person could be answered by, Automatic first. */
+    options: ModelOption[];
+    /** The same list, ready for a menu: Automatic and the sizes, then one group
+     *  per agent. */
+    groups: ModelGroup[];
+    /** The one in force. Never null — Automatic when nothing is picked, and when
+     *  what was picked is not here. */
+    selected: ModelOption;
+    select: (id: string) => void;
+    /**
+     * SPREAD THIS INTO THE RUN, and spread it rather than reading `model` off it.
+     *
+     * It is `{ model }` for Automatic and a size, and `{ model, runtime }` for a
+     * named model — because the broker applies the person's preferred agent only
+     * to a run whose model is blank or a size, so a name sent without its agent
+     * is handed to whatever agent the broker finds first. An app that forwards
+     * only `model` works until somebody with two agents picks a model from the
+     * second one.
+     */
+    run: {
+        model: string;
+        runtime?: string;
+    };
+    /**
+     * WHAT THEY PICKED THAT IS NOT CURRENTLY ON OFFER — the laptop with Opus on
+     * it is shut, or they are on a phone.
+     *
+     * The pick is kept, not cleared: `selected` falls back to Automatic so the
+     * run still goes, and this comes back the moment the machine does. Say
+     * something with it if the surface has room; ignoring it is also correct,
+     * because the run will work either way.
+     */
+    unavailable: string | null;
+    /** More than Automatic to choose between. False with nothing connected,
+     *  which is when `<ModelPicker />` draws nothing. */
+    pickable: boolean;
+    /** The first machines poll is still in flight. The list is Automatic only
+     *  until it lands, so a picker drawn on this is a picker that pops in. */
+    loading: boolean;
+}
+/**
+ * WHICH MODEL ANSWERS, AS A HOOK — because the moment of choosing lands in the
+ * middle of somebody else's composer.
+ *
+ * `<ModelPicker />` is one rendering of exactly this, so a control built from
+ * these values and the one we draw cannot disagree about what is on offer.
+ *
+ * NOTHING HERE FETCHES. The options are derived from the machines the provider
+ * is already polling, so three pickers on a page is still one request — and the
+ * list changes on its own when somebody connects a second agent, with no event
+ * for an app to subscribe to.
+ *
+ * WHY THE LIST IS NOT A CONSTANT, which is the thing worth understanding before
+ * using this: the models on offer are read off the computer the person
+ * connected. Claude Code advertises haiku/sonnet/opus/fable because those are
+ * the words its CLI accepts; a local endpoint advertises what has been pulled;
+ * Codex advertises nothing and gets Automatic alone. An app cannot know any of
+ * that at build time, which is why a model picker on this product is derived
+ * rather than configured.
+ */
+export declare function useModel(options?: UseModelOptions): ModelView;

package/dist/useOpenSobaConnect.d.ts

@@ -1,4 +1,4 @@
-import { type Launch } from "@soba-so/connect-ui";
+import type { Launch } from "./types.js";
 /**
  * THE PRESS THAT PUTS SOBA CONNECT IN FRONT OF SOMEBODY, and the one honest
  * thing a page can say about it afterwards.

package/dist/watch.d.ts

@@ -0,0 +1,48 @@
+import type { AgentEvent } from "./types.js";
+/**
+ * READ A RUN STRAIGHT FROM SOBA, in the browser.
+ *
+ * Your server starts the run (`soba.runs.start`) and hands the page the run's
+ * `stream`: a URL and a token good for that one run. The page reads the run
+ * here instead of through your server, so your server answers in milliseconds
+ * rather than holding a function open for the whole run, and is never cut off
+ * by its host's time limit.
+ *
+ *   for await (const event of watchRun(stream)) { … }
+ *
+ * Read-only: the token cannot start, steer or cancel anything, and tool calls
+ * arrive as their names only (your server answers them). If the connection
+ * drops before the run ends — a deploy on Soba's side, a network blip — it
+ * reconnects and reads on from the last frame it saw.
+ *
+ * With `local`, a page on the computer running the run reads it from that
+ * computer instead (the Soba app's local server on 127.0.0.1), live for as long
+ * as the run goes and without passing through Soba at all. The browser asks
+ * the person once whether this site may talk to apps on their device; if they
+ * say no, or the page is on another computer, it reads through Soba as above.
+ *
+ *   watchRun(stream, { local: { session: useSoba().session } })
+ */
+export interface RunStream {
+    url: string;
+    token: string;
+}
+export interface WatchOptions {
+    /** Read on from after this frame, e.g. one you kept from an earlier visit. */
+    after?: number;
+    signal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+    /** Reconnects in a row without a frame before giving up. */
+    maxRetries?: number;
+    /**
+     * Try the person's own machine first: their Soba session, which the machine
+     * checks with Soba before showing anything. Ignored with `after`, whose
+     * numbers are Soba's.
+     */
+    local?: {
+        session: string | null;
+        port?: number;
+        timeoutMs?: number;
+    };
+}
+export declare function watchRun(stream: RunStream, options?: WatchOptions): AsyncGenerator<AgentEvent>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soba-so/react",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Connect the AI your users already pay for, from your own React app.",
   "license": "UNLICENSED",
   "homepage": "https://soba.so/docs/components",
@@ -19,13 +19,18 @@
     "!dist/**/*.map",
     "README.md"
   ],
+  "scripts": {
+    "build": "node ../../scripts/build-react.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepublishOnly": "node ../../scripts/build-react.mjs"
+  },
   "peerDependencies": {
     "react": ">=18"
   },
   "devDependencies": {
+    "@soba-so/connect-ui": "workspace:*",
     "@types/react": "^19.0.0",
-    "typescript": "^7.0.2",
-    "@soba-so/connect-ui": "0.1.0"
+    "typescript": "^7.0.2"
   },
   "engines": {
     "node": ">=22"
@@ -39,9 +44,5 @@
   ],
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "node ../../scripts/build-react.mjs",
-    "typecheck": "tsc -p tsconfig.json"
   }
-}
+}