@alexkroman1/aai-ui 0.12.2 → 0.13.0

package/dist/use-push-to-talk.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `usePushToTalk` — a hold-to-speak button, for an agent that declares
+ * `turnTaking: { detection: "manual" }`.
+ *
+ * The three session edges underneath (`session.userTurn`'s `start`, `commit`
+ * and `clear`) are one line each; what a button needs on top of them is
+ * where hand-written versions go wrong, and every one of the four is a turn
+ * that is left OPEN — the microphone live and nothing ever answered:
+ *
+ * - **The pointer leaves.** A `mouseup` outside the button never reaches it.
+ *   The handlers here capture the pointer on the way down, so the release
+ *   arrives wherever it happens; an `onPointerCancel` (a scroll gesture, a
+ *   system dialog) DISCARDS the turn rather than answering half a sentence.
+ * - **The key repeats.** Holding a key fires `keydown` over and over, and each
+ *   one would re-open the turn. Only the first counts.
+ * - **The window loses focus mid-hold.** The `keyup` goes to another window
+ *   and is never delivered, so the turn is committed on `blur` — what the
+ *   caller would have done had the release been seen.
+ * - **The component unmounts mid-hold.** The turn is discarded on the way out.
+ *
+ * And one that is a nuisance rather than a stuck turn: the hold key is ignored
+ * while focus is in a text field, where Space is a character.
+ */
+/** Options for {@link usePushToTalk}. */
+export type UsePushToTalkOptions = {
+    /**
+     * The keyboard key that holds the turn open, as a `KeyboardEvent.code` —
+     * `"Space"` by default, so the whole page is a walkie-talkie. `false` turns
+     * the global key off; the button itself still answers Space and Enter while
+     * it has focus.
+     */
+    holdKey?: string | false;
+};
+/**
+ * What {@link usePushToTalk} returns.
+ *
+ * @public
+ */
+export type UsePushToTalkResult = {
+    /** Whether a turn is being held open right now — the button is DOWN. */
+    talking: boolean;
+    /**
+     * Whether pressing would do anything: the call is live. False before Start
+     * and while paused, which is when a button should render disabled.
+     */
+    ready: boolean;
+    /** Open a turn. Interrupts the agent if it is speaking. Ignored while held. */
+    press: () => void;
+    /** Close the turn and have the agent answer it. Ignored unless held. */
+    release: () => void;
+    /** Close the turn and discard it — nothing is answered. Ignored unless held. */
+    cancel: () => void;
+    /**
+     * Spread onto a `<button>`: pointer capture, the keyboard pair, and
+     * `aria-pressed`. The handlers are the whole contract — style it however you
+     * like.
+     */
+    buttonProps: {
+        onPointerDown: (event: {
+            currentTarget: Element;
+            pointerId: number;
+        }) => void;
+        onPointerUp: () => void;
+        onPointerCancel: () => void;
+        onKeyDown: (event: {
+            key: string;
+            repeat: boolean;
+            preventDefault(): void;
+        }) => void;
+        onKeyUp: (event: {
+            key: string;
+            preventDefault(): void;
+        }) => void;
+        onContextMenu: (event: {
+            preventDefault(): void;
+        }) => void;
+        disabled: boolean;
+        "aria-pressed": boolean;
+    };
+};
+/**
+ * Hold-to-speak over the session's push-to-talk methods, with the four ways a
+ * turn gets stuck open handled — see this module's doc.
+ *
+ * Must be used inside the provider `mountClient()` installs, against an agent
+ * declaring `turnTaking: { detection: "manual" }`; any other agent ignores the commands and
+ * its server says so once.
+ *
+ * @example A hold-to-talk button
+ * ```tsx
+ * import { usePushToTalk } from "@alexkroman1/aai-ui";
+ *
+ * function TalkButton() {
+ *   const { talking, buttonProps } = usePushToTalk();
+ *   return (
+ *     <button type="button" {...buttonProps}>
+ *       {talking ? "Listening… release to send" : "Hold to talk (or hold Space)"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function usePushToTalk(options?: UsePushToTalkOptions): UsePushToTalkResult;

package/dist/use-route-mutation.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `useRouteMutation` — WRITE to one of the agent's own `/api` routes from a
+ * component: the writing half of `useRoute`, over `routeFetch`.
+ *
+ * Every save, delete and connect button on a device-twin page wrote the same
+ * nine lines: set a busy flag, call the route, clear the error on success or
+ * set it from the thrown message on failure, clear the flag, and re-read the
+ * list the write changed. This is those lines once, plus the three things the
+ * copies got wrong:
+ *
+ * - **A write settling after unmount sets no state and calls nothing** — the
+ *   page navigated away, and its `reload` would read into a dead component.
+ * - **An OLDER write settling after a newer one does not overwrite its
+ *   outcome** — each write is numbered, and the error shown is that of the
+ *   highest-numbered write to have settled (`useRoute`'s stale-read rule, for
+ *   writes, which cannot be dropped the way a read can).
+ * - **`busy` names WHICH write is in flight**, not just that one is — a row of
+ *   buttons disables the one that was pressed, where a boolean greyed them all.
+ *
+ * `run` never rejects: a failure is `error` (the route's own `{ error }`
+ * sentence when it answered one) and `run` resolves `undefined`.
+ *
+ * @module
+ */
+import { type RouteMethod } from "./route-fetch.ts";
+/**
+ * Options for {@link useRouteMutation}.
+ *
+ * @public
+ */
+export type UseRouteMutationOptions = {
+    /**
+     * The `?client=` to send. Default: the session's client
+     * (`session.identity.clientId()`, read per write) inside `mountClient()`,
+     * none on a page with no session.
+     */
+    client?: string | undefined;
+    /**
+     * Called after every write settles, success or failure — a `useRoute`'s
+     * `reload`, so the list shows what the write did. Not called after unmount.
+     * Read at settle time, so an inline arrow is fine.
+     */
+    onSettled?: (() => void) | undefined;
+};
+/**
+ * Options for one {@link UseRouteMutationResult.run} call.
+ *
+ * @public
+ */
+export type RouteMutationRunOptions = {
+    /**
+     * What {@link UseRouteMutationResult.busy} names while this write is in
+     * flight — the field being saved, the row being deleted. Default:
+     * `"<METHOD> <path>"`.
+     */
+    key?: string | undefined;
+};
+/**
+ * What {@link useRouteMutation} returns.
+ *
+ * @public
+ */
+export type UseRouteMutationResult = {
+    /**
+     * Send one write: `routeFetch(method, path, body, { client })`. Resolves the
+     * route's answer, or `undefined` when it failed (the reason is in `error`) —
+     * never rejects.
+     */
+    run: <T = unknown>(method: RouteMethod, path: string, body?: unknown, options?: RouteMutationRunOptions) => Promise<T | undefined>;
+    /**
+     * The key of the newest write still in flight (see
+     * {@link RouteMutationRunOptions.key}), or `undefined` when none is —
+     * `busy === "email"` for one field, `busy !== undefined` for any.
+     */
+    busy: string | undefined;
+    /** Why the newest settled write failed — the route's `{ error }` when it said — or `undefined`. */
+    error: string | undefined;
+    /** Forget `error` — when the reader dismissed it, or edited the field again. */
+    clearError: () => void;
+};
+/**
+ * Write to the agent's own routes, with a busy key, the last error and a
+ * re-read after — see this module's doc.
+ *
+ * @example A profile field that saves, then re-reads
+ * ```tsx
+ * import { useRoute, useRouteMutation } from "@alexkroman1/aai-ui";
+ *
+ * function Name() {
+ *   const { data, reload } = useRoute<{ name: string }>("/profile");
+ *   const { run, busy, error } = useRouteMutation({ onSettled: reload });
+ *   return (
+ *     <form
+ *       onSubmit={(e) => {
+ *         e.preventDefault();
+ *         const name = new FormData(e.currentTarget).get("name");
+ *         void run("PUT", "/profile", { name }, { key: "name" });
+ *       }}
+ *     >
+ *       <input name="name" defaultValue={data?.name} disabled={busy === "name"} />
+ *       {error && <p role="alert">{error}</p>}
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @param options - `client` and `onSettled`; see {@link UseRouteMutationOptions}.
+ * @returns `run`, the busy key, the last error and `clearError`; see
+ *   {@link UseRouteMutationResult}.
+ *
+ * @public
+ */
+export declare function useRouteMutation(options?: UseRouteMutationOptions): UseRouteMutationResult;

package/dist/use-route.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `useRoute` — read one of the agent's own `/api` routes into a component, and
+ * again on demand or on a poll. The reading half of `routeFetch`.
+ *
+ * What a hand-written `useEffect` + `fetch` got wrong here: a slow earlier read
+ * overwriting a newer one (each read carries an epoch, and a stale one is
+ * dropped — `useWorkflowRuns`' rule), a read landing after unmount, and a
+ * failure rendered as an empty answer. `data` is KEPT through a failed re-read,
+ * so a poll that hiccups does not blank the panel; `error` says it is stale.
+ *
+ * @module
+ */
+/**
+ * Options for {@link useRoute}.
+ *
+ * @public
+ */
+export type UseRouteOptions = {
+    /** Read again every this many ms, while mounted. Default: never. */
+    pollMs?: number | undefined;
+    /**
+     * The `?client=` to send. Default: the session's client
+     * (`session.identity.clientId()`, read per request) inside `mountClient()`,
+     * none on a page with no session.
+     */
+    client?: string | undefined;
+};
+/**
+ * What {@link useRoute} returns.
+ *
+ * @public
+ */
+export type UseRouteResult<T> = {
+    /** The last answer, kept through a failed re-read. `undefined` until the first. */
+    data: T | undefined;
+    /** Why the LAST read failed — the route's `{ error }` when it said — or `undefined`. */
+    error: string | undefined;
+    /** Whether a read is in flight. */
+    loading: boolean;
+    /** Read again now — after a write, say. */
+    reload: () => void;
+};
+/**
+ * `GET` one of the agent's own routes, on mount, on `reload()` and every
+ * `pollMs` — see this module's doc.
+ *
+ * @example A list that re-reads after each delete
+ * ```tsx
+ * import { routeFetch, useClientId, useRoute } from "@alexkroman1/aai-ui";
+ *
+ * type Memory = { id: string; text: string };
+ *
+ * function Memories() {
+ *   const client = useClientId();
+ *   const { data, error, reload } = useRoute<{ memories: Memory[] }>("/memories");
+ *   if (error) return <p role="alert">{error}</p>;
+ *   return (
+ *     <ul>
+ *       {data?.memories.map((m) => (
+ *         <li key={m.id}>
+ *           {m.text}
+ *           <button
+ *             type="button"
+ *             onClick={() => void routeFetch("DELETE", `/memories/${m.id}`, undefined, { client }).then(reload)}
+ *           >
+ *             Forget
+ *           </button>
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @typeParam T - The shape the route answers. Not checked.
+ * @param path - The route's path as declared, without `/api`. `null` reads nothing.
+ * @param options - `pollMs` and `client`; see {@link UseRouteOptions}.
+ * @returns The answer, the last error, and `reload`; see {@link UseRouteResult}.
+ *
+ * @public
+ */
+export declare function useRoute<T = unknown>(path: string | null, options?: UseRouteOptions): UseRouteResult<T>;

package/dist/use-run-key.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The handle a page keeps on the runs it started, across a reload.
+ *
+ * `useWorkflowSubmit` is what makes a run survivable — the run id is that
+ * hook's own state, so a refresh loses it while the run carries on — and the
+ * `key` is what it looks the run up BY, because it is a lookup CAPABILITY:
+ * there is no per-user filtering behind `find`, so the key IS the scoping
+ * mechanism. Choosing one is easy to get wrong in three separate ways, and six
+ * shipped templates had each written the same twenty lines to get it right.
+ * This is those lines.
+ *
+ * **`useWorkflowSubmit` now mints one for itself** ({@link useDefaultRunKey}),
+ * so a page resumes its own run across a reload with nothing written at the
+ * call site — six of six page templates passed `useRunKey()` and
+ * `recover: true`, which is a default in the wrong place. The hook stays
+ * PUBLIC for the page that wants to choose: an app with accounts passes the
+ * ACCOUNT's own id instead, and a run then follows the person to a new device,
+ * which is a promise only a login can keep; a page whose run outlives the tab
+ * passes `useRunKey({ storage: "local" })`.
+ *
+ * ## Three properties, and the rejected alternatives are why each one matters
+ *
+ * - **Opaque** — `crypto.randomUUID()`, never derived from what was submitted.
+ *   A key derived from the input collides the moment two people submit the same
+ *   thing, and they then recover each other's runs; it also carries what they
+ *   typed into a lookup token the platform deliberately stopped logging.
+ * - **Short.** A `randomUUID` is 36 characters, well inside the 256 that
+ *   `POST /workflows/runs` allows a key.
+ * - **Minted once per load and written back for the next one**, which is the
+ *   whole mechanism: the load that presses the button records the key with the
+ *   run, and the load after it finds the run by producing the same key.
+ *
+ * Storage rather than the page's own URL, for all of them. A `?key=` parameter
+ * survives more (a new tab, a bookmark, a shared link) and that is the problem:
+ * a URL is pasted into chats, copied into referrers and kept in history, and
+ * what a leaked one buys is somebody else's work — reading it, and `cancel()` on
+ * it. An app with accounts should pass the ACCOUNT's own id here instead, and
+ * then a run follows the person to a new device, which is a promise only a login
+ * can keep.
+ *
+ * ## The storage is the caller's decision, and it is not a detail
+ *
+ * `"session"` (the default) dies with the tab, which covers exactly the
+ * interruption most pages have — a reload, a same-tab navigation, a crashed tab
+ * — and is the same lifetime as this package's other two stores, the session
+ * resume id (`session/resume-store.ts`) and the upload recall
+ * (`upload/recall.ts`), so both halves of a reload make the same promise.
+ *
+ * `"local"` is for a run that outlives all of that BY DESIGN — one that sleeps
+ * between digests and may live a month, where closing the browser on Tuesday and
+ * coming back on Friday to press Stop is the ordinary case rather than an edge
+ * one, and a tab-scoped key would answer that with an empty form beside a run
+ * still posting somewhere. It is as far as a key can go without a login, and no
+ * further. `podcast-digest-workflow` is that template, and the reason this hook is still
+ * called by name anywhere; the other five take the tab-scoped default the
+ * submit hook mints for them.
+ *
+ * ## Anything ELSE a page stores back must be VALIDATED on read
+ *
+ * This key needs no validation, and it is worth saying why, because it is the
+ * exception: any string is a legal key, so a value from storage can only fail to
+ * match a run. A page that remembers something more — which MODE submitted, say
+ * — is remembering a value it will turn into a name, and storage hands back a
+ * string some earlier version of that page wrote: a renamed mode, a hand-edited
+ * value, a slot another app on the origin happens to share. Unchecked, that
+ * starts a run called `undefined` and answers a 400 nobody typed. Check it
+ * against the page's own list on the way out (`recalledMode` in
+ * `transcription-workflow/recover.ts` is the worked example) — the recall is the
+ * page's, the validation is not optional.
+ *
+ * ## The slot is keyed by the page's own URL
+ *
+ * Every deployed agent is served from one origin at `/:slug/`, so a fixed name
+ * would have two agents scaffolded from the same template recover each other's
+ * runs. The key is the page's own directory — resolved through `"./"`, which
+ * drops the query and the hash, since a reload carrying `?foo` or `#bar` has to
+ * find the same key. Same call `session/resume-store.ts` makes, for the same
+ * reason.
+ *
+ * One key per PAGE is right even for a page driving several workflows: `find` is
+ * scoped by workflow as well as by key, so three hooks sharing one key recover
+ * three separate runs. `transcription-workflow` is that page.
+ *
+ * Every access is guarded. Storage THROWS outright in some contexts (Safari
+ * private mode, an iframe blocked by policy) and is ABSENT in others (any
+ * server-side render), and a page that cannot remember its key must degrade to
+ * the behaviour it would have had anyway — one run per load — rather than
+ * failing to render.
+ */
+/**
+ * The key `useWorkflowSubmit` uses when the page named none.
+ *
+ * Two things it does that a plain `useRunKey()` at the call site cannot, and
+ * both are about a page that DID name one:
+ *
+ * - **It mints nothing when the caller has a key.** Minting writes to storage,
+ *   so an unconditional `useRunKey()` inside the hook would leave a slot behind
+ *   on every page that passes an account id and never reads it back.
+ * - **It stays reactive to the caller's key.** A key that arrives late — an
+ *   account id resolved after a login — must reach the lookup, which re-asks on
+ *   a changed key by design; freezing it into `useState` would pin the page to
+ *   whatever it held on its first render.
+ *
+ * The minted half is still frozen for the component's life, which is what
+ * `useRunKey` freezes it for: a fresh key per render would record every run
+ * under a name the next load cannot produce.
+ *
+ * @param explicit - The caller's own key, or undefined for a page with none.
+ * @returns The key to record runs under and look them up by.
+ *
+ * @internal
+ */
+export declare function useDefaultRunKey(explicit: string | undefined): string;
+/**
+ * A lookup key for `useWorkflowSubmit({ key })`, stable across reloads.
+ *
+ * @param options - See the module doc for the whole argument. The storage kind
+ *   is read once, when the key is minted: a value that changed afterwards would
+ *   be asking to move a key that has already been recorded with a run.
+ * @returns The key to record runs under and to look them up by — the same one
+ *   for the life of the component, and for the next load in the same tab (or the
+ *   same browser, under `"local"`).
+ */
+export declare function useRunKey(options?: {
+    /**
+     * Which store keeps the key between loads.
+     *
+     * `"session"` (the default) dies with the tab; `"local"` survives the
+     * browser closing, which is what a run that sleeps for days needs. See "The
+     * storage is the caller's decision".
+     */
+    storage?: "session" | "local";
+}): string;

package/dist/use-session-controls.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `useSessionControls` — the two flags and four methods a control row is made
+ * of, and nothing else.
+ *
+ * Every custom chrome's control row opened with the same three lines:
+ * `useSessionActions()` for the methods, then two one-field
+ * `useSessionSelector` calls for `started` and `running`. That is the right
+ * shape — the whole-snapshot `useSession()` it replaced re-rendered four
+ * buttons at STT-partial rate to read two booleans that flip once a call — and
+ * it is also three lines every row writes identically, which is what a hook is
+ * for. `<SessionControls>` is built on it; a chrome whose buttons are too
+ * unusual for even that component's render slot takes the hook alone.
+ */
+/**
+ * What {@link useSessionControls} returns.
+ *
+ * @public
+ */
+export type UseSessionControlsResult = {
+    /** Whether a call has been started and not yet ended — the Start/End hinge. */
+    started: boolean;
+    /** Whether the started call is live rather than paused — the Pause/Resume hinge. */
+    running: boolean;
+    /** Dial. What the button before `started` presses. */
+    start: () => void;
+    /** Pause a running call, or resume a paused one. */
+    toggle: () => void;
+    /**
+     * Hang up AND dial again — a brand-new session with fresh session-scoped
+     * state, a fresh greeting, and the chrome kept on the call. `end()` then
+     * `start()`, never `reset()`: `reset()` clears the conversation and reconnects
+     * carrying the same session id, so every `sessionSlot` on the agent survives
+     * and the next tool call repopulates the board, cart or game that was just
+     * abandoned. Three chromes each found this and wrote the pair by hand.
+     */
+    restart: () => void;
+    /**
+     * Hang up. Flips `started` back, so a chrome returns to its Start button and
+     * the next `start()` is a new session. `reset()` would keep the call live.
+     */
+    end: () => void;
+};
+/**
+ * The state and the actions a Start / Pause–Resume / New conversation / End row
+ * renders from, on two one-field subscriptions.
+ *
+ * Must be used inside the provider `mountClient()` installs.
+ *
+ * @example A footer that renders its own buttons
+ * ```tsx
+ * import { useSessionControls } from "@alexkroman1/aai-ui";
+ *
+ * function Footer() {
+ *   const { started, running, start, toggle, end } = useSessionControls();
+ *   if (!started) return <button type="button" onClick={start}>Begin</button>;
+ *   return (
+ *     <>
+ *       <button type="button" onClick={toggle}>{running ? "Hold" : "Resume"}</button>
+ *       <button type="button" onClick={end}>Hang up</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @returns See {@link UseSessionControlsResult}.
+ *
+ * @public
+ */
+export declare function useSessionControls(): UseSessionControlsResult;

package/dist/use-session-id.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `useSessionId()` and `useClientId()` — the two ids a page keys things by, as
+ * React state.
+ *
+ * Both read `session.identity` through the session's own subscription, so they
+ * are current without any wiring. The alternative every app wrote was an
+ * external store fed by `mountClient({ onSessionId })` — which is set up
+ * OUTSIDE the component tree, fires only on a `config` frame (so it never says
+ * "no session" after `end()`), and has to be threaded to wherever the id is
+ * read. The session already knows both ids; these hooks just ask it.
+ *
+ * `useSyncExternalStore` over the snapshot subscription rather than a store of
+ * their own: each returns a string (or `undefined`), which compares by value,
+ * so a component re-renders only when ITS id changes, not on every frame the
+ * session notifies for. The dialer notifies when the confirmed session id
+ * changes even if no snapshot field moved with it.
+ *
+ * @module
+ */
+/**
+ * The server's id for the current session: `undefined` before the session's
+ * first `config` frame and after `end()`; a resume or a new session updates it
+ * from its own `config` frame. Key a page's history by it.
+ *
+ * Treat it as sensitive — whoever holds it can resume the session and read its
+ * history (`VoiceSessionOptions.onSessionId` explains why).
+ *
+ * @example
+ * ```tsx
+ * import { useSessionId } from "@alexkroman1/aai-ui";
+ *
+ * function SessionTag() {
+ *   const id = useSessionId();
+ *   return <small>{id ?? "no session yet"}</small>;
+ * }
+ * ```
+ *
+ * @returns The current session id, or `undefined`.
+ *
+ * @public
+ */
+export declare function useSessionId(): string | undefined;
+/**
+ * The client id this session sends as `?client=` — the id a tool reads with
+ * `sessionClientId(ctx)` and the inbox socket is held under. With
+ * `mountClient({ client: "auto" })` it is this browser's `browserClientId()`;
+ * `undefined` when the session sends none.
+ *
+ * A `client` GETTER is read when the session notifies (each snapshot change),
+ * so a page that changes what its getter answers sees the new id on the next
+ * render the session causes.
+ *
+ * @returns The client id, or `undefined`.
+ *
+ * @public
+ */
+export declare function useClientId(): string | undefined;