@alexkroman1/aai-ui 0.12.2 → 0.13.0

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

@@ -0,0 +1,138 @@
+/**
+ * `useTapToTalk` — one tap goes live, the next hangs up: the TOGGLE counterpart
+ * of `usePushToTalk`, for an agent with automatic turn detection (the default).
+ * It is how a smart speaker's button works, and a page that is the speaker's
+ * twin wants the same thing.
+ *
+ * Tapping is the easy half. What each hand-written copy had to work out:
+ *
+ * - **Hanging up is `disconnect()`, never `end()`**, so the next tap RESUMES
+ *   the session — the agent still knows what was said a minute ago.
+ * - **The mic is muted unless live.** A typed turn opens the session too, and
+ *   must not open the microphone with it; the mute is set before the connect,
+ *   so the call opens already in the right state.
+ * - **A typed turn while idle opens the session and waits for it**
+ *   (`session.sendText(text, { connect: true })`) instead of being dropped.
+ * - **A call that is not live hangs itself up** after `idleHangupMs` of quiet
+ *   (the device's follow-up window) or `thinkingHangupMs` of thinking — every
+ *   session activity restarts the clock, and a speaking agent is never cut
+ *   off. A LIVE call ends only when the caller taps.
+ * - **A connection that never comes is a failure**, after `connectTimeoutMs`.
+ * - **The session going down on its own** (an error, the server closing it)
+ *   leaves live mode — otherwise the next tap would read as "hang up".
+ * - The talk key's auto-repeat is not a tap, it is ignored in a text field, and
+ *   the button's own Space activation is suppressed so it does not count twice.
+ *
+ * The decisions are a statechart (`_tap-to-talk-state.ts`); this hook feeds it
+ * the session and runs its effects.
+ *
+ * @module
+ */
+/**
+ * Options for {@link useTapToTalk}.
+ *
+ * @public
+ */
+export type UseTapToTalkOptions = {
+    /**
+     * The keyboard key that taps, as a `KeyboardEvent.code` — `"Space"` by
+     * default. `false` turns the page-wide key off; the button itself still
+     * answers a click, Space and Enter.
+     */
+    key?: string | false | undefined;
+    /**
+     * Hang up a call that is NOT live after this long with nothing happening —
+     * the device's follow-up window. Default 3000 ms.
+     */
+    idleHangupMs?: number | undefined;
+    /**
+     * Hang up a call that is not live when the agent has been thinking this
+     * long. Default 60,000 ms — long enough for a slow tool.
+     */
+    thinkingHangupMs?: number | undefined;
+    /** Give up on a connection attempt after this long, and report `failed`. Default 8000 ms. */
+    connectTimeoutMs?: number | undefined;
+};
+/**
+ * What {@link useTapToTalk} returns.
+ *
+ * @public
+ */
+export type UseTapToTalkResult = {
+    /**
+     * The call: `"idle"` (not meant to be running), `"connecting"`, or
+     * `"active"` — up, whatever the agent is doing.
+     */
+    phase: "idle" | "connecting" | "active";
+    /** Whether the caller is live — mic open, in a realtime conversation. The button is ON. */
+    live: boolean;
+    /**
+     * Whether the last attempt failed: the connection timed out or the session
+     * reported an error. Cleared by the next tap or typed turn.
+     */
+    failed: boolean;
+    /** Tap: go live (connecting first if idle), or hang up if live. */
+    toggle: () => void;
+    /**
+     * A typed turn. Sent at once while the call is up; while idle it opens the
+     * session WITHOUT the mic and is sent once connected. Blank text is ignored.
+     */
+    send: (text: string) => void;
+    /** Hang up now — resumably (`disconnect()`), live or not. */
+    hangUp: () => void;
+    /**
+     * Spread onto a `<button>`: the click, the keyboard guard against a double
+     * tap, and `aria-pressed`. Style it however you like.
+     */
+    buttonProps: {
+        onClick: () => void;
+        onKeyDown: (event: {
+            code: string;
+            preventDefault(): void;
+        }) => void;
+        onKeyUp: (event: {
+            code: string;
+            preventDefault(): void;
+        }) => void;
+        "aria-pressed": boolean;
+    };
+};
+/**
+ * Tap to go live, tap to hang up, over the session — see this module's doc
+ * for what it handles beyond the tap.
+ *
+ * Must be used inside the provider `mountClient()` installs. Call it ONCE per
+ * page: it owns the session's mute and hang-up clock.
+ *
+ * @example A talk button and a composer
+ * ```tsx
+ * import { useTapToTalk } from "@alexkroman1/aai-ui";
+ *
+ * function Speaker() {
+ *   const { live, phase, send, buttonProps } = useTapToTalk();
+ *   return (
+ *     <>
+ *       <button type="button" {...buttonProps}>
+ *         {phase === "connecting" ? "Connecting…" : live ? "Tap to hang up" : "Tap to talk"}
+ *       </button>
+ *       <form
+ *         onSubmit={(e) => {
+ *           e.preventDefault();
+ *           const input = e.currentTarget.elements.namedItem("say") as HTMLInputElement;
+ *           send(input.value);
+ *           input.value = "";
+ *         }}
+ *       >
+ *         <input name="say" placeholder="…or type" />
+ *       </form>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @param options - The talk key and the three clocks; see {@link UseTapToTalkOptions}.
+ * @returns The phase, the live flag and the controls; see {@link UseTapToTalkResult}.
+ *
+ * @public
+ */
+export declare function useTapToTalk(options?: UseTapToTalkOptions): UseTapToTalkResult;

package/dist/use-user-transcript-uyHhzy4d.js

@@ -0,0 +1,73 @@
+import { useSessionSelector } from "./context.js";
+import { useMemo } from "react";
+//#region src/use-user-transcript.ts
+/**
+* `useUserTranscript` — what the caller is saying RIGHT NOW, read correctly.
+*
+* `SessionSnapshot.userTranscript` is `string | null`, and the two falsy values
+* mean different things:
+*
+* - `null` — nobody is speaking. There is no partial turn.
+* - `""` — speech HAS been detected and no words have come back yet. A live
+*   session sits here for a few hundred milliseconds at the start of every turn.
+*
+* Read as one falsy check, those collapse and the indicator never appears at the
+* start of a turn — which is the moment it is for. So every custom chrome writes
+* `transcript !== null && (transcript === "" ? "…" : transcript)`, three
+* templates did exactly that, and each one re-derived a protocol distinction
+* from the type rather than from anything that told them.
+*
+* This is the same distinction as two named booleans, so a component can say
+* what it means: render on `speaking`, show `text`, and use the SDK's own
+* placeholder when there is nothing to show yet.
+*/
+/**
+* Placeholder for "listening, no words yet" — the `""` case above.
+*
+* A one-character ellipsis rather than three dots, because it is read by a
+* screen reader as an ellipsis and it does not reflow the row when the first
+* real word replaces it.
+*
+* On `@alexkroman1/aai-ui/internal`, not the root: no public signature names
+* it, and a `client.tsx` rendering its own transcript row compares against the
+* character. `UseUserTranscriptResult.text` therefore spells the value out
+* rather than linking here.
+*
+* @internal
+*/
+const TRANSCRIBING_PLACEHOLDER = "…";
+/**
+* Subscribe to the caller's in-progress turn.
+*
+* Narrowly subscribed — a component using this re-renders at STT-partial rate,
+* which is exactly what it is for and exactly what a whole-page `useSession()`
+* should not do.
+*
+* @example
+* ```tsx
+* import { useUserTranscript } from "@alexkroman1/aai-ui";
+*
+* function LiveTranscript() {
+*   const { speaking, text } = useUserTranscript();
+*   if (!speaking) return null;
+*   return <div className="italic opacity-60">{text}</div>;
+* }
+* ```
+*
+* @public
+*/
+function useUserTranscript() {
+	const partial = useSessionSelector((snapshot) => snapshot.userTranscript);
+	return useMemo(() => ({
+		speaking: partial !== null,
+		text: displayText(partial),
+		partial
+	}), [partial]);
+}
+/** The three cases, spelled out: silent, detected-but-wordless, and words. */
+function displayText(partial) {
+	if (partial === null) return "";
+	return partial === "" ? "…" : partial;
+}
+//#endregion
+export { useUserTranscript as n, TRANSCRIBING_PLACEHOLDER as t };

package/dist/use-user-transcript.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `useUserTranscript` — what the caller is saying RIGHT NOW, read correctly.
+ *
+ * `SessionSnapshot.userTranscript` is `string | null`, and the two falsy values
+ * mean different things:
+ *
+ * - `null` — nobody is speaking. There is no partial turn.
+ * - `""` — speech HAS been detected and no words have come back yet. A live
+ *   session sits here for a few hundred milliseconds at the start of every turn.
+ *
+ * Read as one falsy check, those collapse and the indicator never appears at the
+ * start of a turn — which is the moment it is for. So every custom chrome writes
+ * `transcript !== null && (transcript === "" ? "…" : transcript)`, three
+ * templates did exactly that, and each one re-derived a protocol distinction
+ * from the type rather than from anything that told them.
+ *
+ * This is the same distinction as two named booleans, so a component can say
+ * what it means: render on `speaking`, show `text`, and use the SDK's own
+ * placeholder when there is nothing to show yet.
+ */
+/**
+ * Placeholder for "listening, no words yet" — the `""` case above.
+ *
+ * A one-character ellipsis rather than three dots, because it is read by a
+ * screen reader as an ellipsis and it does not reflow the row when the first
+ * real word replaces it.
+ *
+ * On `@alexkroman1/aai-ui/internal`, not the root: no public signature names
+ * it, and a `client.tsx` rendering its own transcript row compares against the
+ * character. `UseUserTranscriptResult.text` therefore spells the value out
+ * rather than linking here.
+ *
+ * @internal
+ */
+export declare const TRANSCRIBING_PLACEHOLDER = "\u2026";
+/** What {@link useUserTranscript} returns. */
+export interface UseUserTranscriptResult {
+    /**
+     * True while the caller holds the turn — from speech detection to the final
+     * transcript. This is the flag a live-transcript row renders on.
+     */
+    speaking: boolean;
+    /**
+     * The words so far, or a one-character ellipsis (`…`) while there are none.
+     * Empty string when nobody is speaking.
+     */
+    text: string;
+    /**
+     * The raw partial: the words so far, `""` while there are none, and `null`
+     * when nobody is speaking. For a chrome that wants to render its own
+     * placeholder (or none).
+     */
+    partial: string | null;
+}
+/**
+ * Subscribe to the caller's in-progress turn.
+ *
+ * Narrowly subscribed — a component using this re-renders at STT-partial rate,
+ * which is exactly what it is for and exactly what a whole-page `useSession()`
+ * should not do.
+ *
+ * @example
+ * ```tsx
+ * import { useUserTranscript } from "@alexkroman1/aai-ui";
+ *
+ * function LiveTranscript() {
+ *   const { speaking, text } = useUserTranscript();
+ *   if (!speaking) return null;
+ *   return <div className="italic opacity-60">{text}</div>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useUserTranscript(): UseUserTranscriptResult;

package/dist/use-workflow-form.d.ts

@@ -0,0 +1,285 @@
+/**
+ * The hook a FORM needs, as against the one a status view does.
+ *
+ * `useWorkflowRun` (`workflow-client.ts`) watches a run you already have.
+ * This is what comes before it: `useWorkflowSubmit` starts a run and hands the
+ * id straight to `useWorkflowRun`. Its sibling `useWorkflows` — the listing
+ * `<WorkflowFields>` renders a form from — is `use-workflows.ts`.
+ *
+ * ## `useWorkflowSubmit` — a form's two halves in one hook
+ *
+ * A page that submits a workflow always needs the same four pieces of state:
+ * the run id, whether a submit is in flight, whether the RUN is still going, and
+ * whichever of the two failed. `link-digest-workflow` writes them out by hand, which is
+ * the right shape for a template teaching the primitives and the wrong shape to
+ * write a third time — and it is easy to get subtly wrong: dropping the previous
+ * run id before the new `POST` returns is what stops a finished result sitting
+ * under a form that is already submitting again.
+ *
+ * So this is `api.start` plus {@link useWorkflowRun}, with the state between
+ * them. It adds no transport of its own and holds no run state of its own; the
+ * watching (stream first, poll as its fallback, terminal stops) is entirely
+ * `useWorkflowRun`'s, and `run` here IS its run.
+ *
+ * ## Why it starts ASYNCHRONOUSLY even though a synchronous call exists
+ *
+ * `api.startAndWait` would collapse this to one request, and it is the wrong
+ * default for a page: it holds a socket open for up to a minute, answers nothing
+ * until it settles, and a page has `useWorkflowRun` — which survives a reload,
+ * shows progress, and costs one stream. The synchronous call is for callers with
+ * nowhere to put a watch (a script, a cron, a form POST from a server). Pass
+ * `wait` here when the page really does want one request, and the run is
+ * followed from the same id either way.
+ */
+import type { AnyWorkflowDef, UploadParallelOption, UploadProgress, WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
+import type { FormValues } from "./components/form-types.ts";
+import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
+import type { SubmitInputOf } from "./workflow-def-types.ts";
+/**
+ * What {@link WorkflowSubmission.upload} reports while the bytes are going.
+ *
+ * The SDK's per-request {@link UploadProgress} plus WHICH file it describes,
+ * because a form is allowed more than one and a bar over "the upload" would
+ * restart at zero partway through with nothing to say why.
+ *
+ * @public
+ */
+export type UploadStatus = UploadProgress & {
+    /** The file being sent, by the name the picker gave it. */
+    name: string;
+    /** Which file of the submission this is, counting from 1. */
+    index: number;
+    /** How many files this submission sends in total. */
+    count: number;
+    /**
+     * Whether the person has parked this upload.
+     *
+     * A paused upload is not a stopped one: the windows already stored stay stored,
+     * `loaded` holds where it got to, and resuming sends what is missing rather than
+     * the file. So a bar rendering this reads "Paused at 62%", never "62% and
+     * frozen" — which is what a page could otherwise only guess from a number that
+     * stopped moving, the same ambiguity `complete` exists to remove on the run side.
+     */
+    paused: boolean;
+};
+/**
+ * What {@link useWorkflowSubmit} returns.
+ *
+ * @see {@link WorkflowStreamSubmission} — an ALIAS of this type, returned by
+ * `useWorkflowStream`, which is a drop-in sibling. Exactly two fields MEAN
+ * something different there, and both differences follow from WHEN the run is
+ * created: there, `submit()` resolves when the UPLOAD finishes rather than when
+ * the run is accepted, and `run` is non-`undefined` from before the bytes are
+ * in, so a page can render `<WorkflowProgress>` beside the upload bar instead
+ * of after it. Here the run does not exist until the last byte lands.
+ */
+export type WorkflowSubmission<R = unknown, I = unknown> = {
+    /**
+     * Start a run with this input. Resolves once the run EXISTS — progress
+     * arrives through `run` — so a `<Form>`'s handler can await it to know the
+     * submission was accepted.
+     */
+    submit: (input: I) => Promise<void>;
+    /**
+     * Start a run from a `<Form>`'s values, which are UNVALIDATED.
+     *
+     * The same function as {@link WorkflowSubmission.submit}, with the type the
+     * form path can honestly offer. `FormValues` is `Record<string, unknown>`
+     * scraped off the DOM at submit time — a `<TextField name="limit">`
+     * contributes a string whatever the schema says — so the shape is not known
+     * here and the SERVER is what checks it against the workflow's schema.
+     *
+     * Two doors rather than one loose one: `submit` takes the workflow's own
+     * input type, so a hand-built object is checked at compile time and
+     * `submit({ ur1: 42 })` is an error; widening it to accept `FormValues` would
+     * have made every object satisfy it and given the typing back. Reaching for
+     * this one is the author saying "these came from a form", which is a fact
+     * about the values and not a cast.
+     */
+    submitForm: (values: FormValues) => Promise<void>;
+    /** Clear the run and any error, putting the form back to its initial state. */
+    reset: () => void;
+    /**
+     * End the current run's `sleep()` early — "file it now" — resolving how many
+     * pending sleeps were interrupted.
+     *
+     * Bound to the run this submission is following, which is the point: it is
+     * the only reason a page holding one of these hooks needed an `api` of its
+     * own. `0` is an answer rather than a failure (the run had already moved past
+     * its wait, or there is no run yet), so nothing here has to be guarded.
+     */
+    wake: () => Promise<number>;
+    /**
+     * Stop the current run, resolving whether this call is what ended it.
+     *
+     * `false` for a run that had already finished, and for no run at all — the
+     * SDK's contract, because two tabs pressing Stop is ordinary. Distinct from
+     * `reset()`, which puts the FORM back and leaves the run running.
+     */
+    cancel: () => Promise<boolean>;
+    /** The run, once started, followed to completion. */
+    run: WorkflowRun<R> | undefined;
+    /**
+     * True from `submit()` on this mount until `reset()` — did THIS page start
+     * the run it is showing?
+     *
+     * A page needs it to say the right sentence and cannot derive it: a run
+     * ADOPTED by the mount-time lookup after a reload looks exactly like one this
+     * page started. Six templates kept a `useState(false)` next to this hook, set
+     * it in their `onSubmit` and mirrored it in their `onClear` — shadow state
+     * for a fact only this hook can know, since it is the thing that decides
+     * between `submit()` and the recovery lookup. One of the six grew a fourth
+     * branch and had to move the whole note into its own module with its own
+     * spec, which is what a seam missing one layer down looks like.
+     *
+     * The RAW fact rather than a derived "recovered", deliberately: with `run`
+     * these are three states, not two, and the third is the one a page most needs
+     * to explain. `startedHere` is "you pressed the button"; `!startedHere &&
+     * !run` is the mount-time lookup still going; `!startedHere && run` is a run
+     * this browser started earlier, now in front of somebody who did not press
+     * anything. A boolean meaning only the last of those cannot express the
+     * middle one.
+     *
+     * @example
+     * ```ts
+     * declare const submission: import("@alexkroman1/aai-ui").WorkflowSubmission;
+     * const note = submission.startedHere
+     *   ? "You can close this tab or reload it — this page will find the run again."
+     *   : submission.run === undefined
+     *     ? "Looking for a run this tab started earlier…"
+     *     : "Still working on the run this tab started earlier. Reloading is safe.";
+     * ```
+     */
+    startedHere: boolean;
+    /**
+     * True from `submit()` until the run reaches a terminal status.
+     *
+     * The WORK, not the request: a run outlives its `POST`, and a submit button
+     * that re-enabled on the response would invite a second submission of work
+     * already in flight.
+     */
+    pending: boolean;
+    /**
+     * How far the submission's files have got, while any are still going.
+     *
+     * Undefined before the first byte and again from the moment the last one
+     * lands, so a page can render `{upload && <UploadProgressBar upload={upload} />}`
+     * and the bar exists exactly for as long as there is an upload to describe. A
+     * form with no files never sets it at all.
+     *
+     * The wait it covers is the one `run` cannot: a run does not EXIST until its
+     * input is stored, so `pending` is true and there is nothing to poll — which
+     * for a 200 MB recording is minutes of a page that looks stuck.
+     */
+    upload: UploadStatus | undefined;
+    /**
+     * Park the upload where it is, stopping the bytes in flight.
+     *
+     * The windows already stored stay stored, so `resumeUpload()` sends what is
+     * missing rather than the file — which is the difference between a pause a
+     * person will actually use on a 200 MB recording and a cancel dressed up as one.
+     *
+     * `submit()`'s promise stays unresolved across a pause, because the submission
+     * genuinely has not finished: the run does not exist until the last byte lands,
+     * so resolving here would tell a `<Form>` the work was accepted when nothing has
+     * been started. A no-op when there is no upload in flight.
+     */
+    pauseUpload: () => void;
+    /** Continue a paused upload, sending only the windows the store does not have. */
+    resumeUpload: () => void;
+    /** The submit's own failure (a rejected input), or the watch's. */
+    error: string | undefined;
+};
+/** Options for {@link useWorkflowSubmit}. */
+export type UseWorkflowSubmitOptions = {
+    /** The client to start runs with. Defaults to one for the page's own agent. */
+    api?: WorkflowApi;
+    /**
+     * Correlation key recorded with the run, for finding it again without the id.
+     *
+     * **Defaulted**, to an opaque per-page key in `sessionStorage` that the next
+     * load produces again — `useRunKey()`'s, minted by the hook. Pass one to
+     * scope runs to something the page knows better: an ACCOUNT's own id, which
+     * is what makes a run follow the person to a new device, or
+     * `useRunKey({ storage: "local" })` for a run that outlives the tab by
+     * design. The key is a lookup CAPABILITY (there is no per-user filtering
+     * behind `find`), it must fit the route's 256-character bound, and anything
+     * derived from a person's own input both collides and carries what they
+     * typed — `use-run-key.ts` argues every alternative.
+     */
+    key?: string;
+    /**
+     * On mount, adopt the newest run this `key` already has.
+     *
+     * **This is what makes a reload survivable, and it is ON.** The run id is
+     * this hook's own state, so a refresh loses it while the run carries on — and
+     * a page that cannot name a run cannot show it, cancel it or wake it. The
+     * hook asks `find(workflow, key)` once as it mounts and follows whatever
+     * comes back, so the answer, the progress and the controls are all there
+     * again.
+     *
+     * It used to be opt-in, on the argument that a `key` alone means only "record
+     * this with the run" — true of `ctx.workflows.start({ key })`, where there is
+     * no page to put a run back on, and not of a form: six of six page templates
+     * passed `useRunKey()` and `recover: true` together, which is a default in
+     * the wrong place. `false` is the opt-out, and what it buys is a form that
+     * always opens empty — no lookup on mount, and a live run reachable only by
+     * an id the page has already lost.
+     */
+    recover?: boolean;
+    /**
+     * Hold the `POST` open until the run settles, up to this many ms — the
+     * synchronous mode. Omitted (the default) returns as soon as the run exists.
+     */
+    wait?: number;
+    /** How often the fallback poll re-reads a live run. */
+    intervalMs?: number;
+    /**
+     * Send each chosen file as concurrent parts instead of in one request.
+     *
+     * **On by default.** `false` opts out, `{ partBytes, concurrency }` tunes it.
+     * This is the wait a form with a recording in it actually spends: the run does
+     * not exist until its input is stored, so until the last byte lands there is no
+     * run to watch and nothing for `<WorkflowProgress>` to say. Splitting the file
+     * across connections is what makes that stretch shorter, and it degrades to the
+     * single request wherever it would not help — a small file, an older agent — so
+     * the default costs nothing where it would not have paid. See
+     * `UploadOptions.parallel`.
+     */
+    parallel?: UploadParallelOption;
+};
+/**
+ * Start a workflow from a form, and follow the run it creates.
+ *
+ * @typeParam D - The workflow DEFINITION, which types both halves of the
+ *   submission: `submit(input)` takes what the workflow's schema parses to, and
+ *   `run.status === "completed"` narrows to a typed `run.output`.
+ *
+ *   It used to be the OUTPUT type alone, and the asymmetry was the bug: a page
+ *   already wrote `WorkflowOutputOf<typeof digest>` to get the output, while
+ *   `submit` took `unknown`, so `submit({ ur1: 42 })` compiled and arrived as a
+ *   400 in the browser. Naming the def instead types the input from the same
+ *   declaration — and `import type` is ERASED, so it costs the bundle nothing.
+ *   Passing an output type where a def belongs is now a compile error rather
+ *   than a silent loss of typing, which is the point.
+ *
+ * @example
+ * ```tsx no-check
+ * import { Form, SubmitButton, TextField, useWorkflowSubmit } from "@alexkroman1/aai-ui";
+ * import type { digest } from "./agent.ts";
+ *
+ * function DigestForm() {
+ *   const { submit, run, pending, error } = useWorkflowSubmit<typeof digest>("digest");
+ *   return (
+ *     <Form onSubmit={(values) => submit(values)} error={error}>
+ *       <TextField name="url" label="Link" type="url" required />
+ *       <SubmitButton pending={pending}>Digest</SubmitButton>
+ *       {run?.status === "completed" && <p>{run.output.title}</p>}
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useWorkflowSubmit<D extends AnyWorkflowDef>(workflow: string, options?: UseWorkflowSubmitOptions): WorkflowSubmission<WorkflowOutputOf<D>, SubmitInputOf<D>>;