@alexkroman1/aai-ui 5.13.2 → 6.1.0

package/README.md

@@ -37,7 +37,8 @@ function OrderSidebar() {
   );
 }
 
-client({ sidebar: <OrderSidebar /> });
+// `sidebar` takes the COMPONENT, not an element — the shell renders it.
+client({ sidebar: OrderSidebar });
 ```
 
 ## Hooks

package/dist/_repeat-until.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A bounded read, re-armed from the SETTLED read — the loop both workflow
+ * watchers are built out of.
+ *
+ * `pollUntilTerminal` (`use-workflow-run.ts`) and `readProgressUntilComplete`
+ * (`use-workflow-progress.ts`) each open a request, decide from its answer
+ * whether to come back, and stop when told to. What they had in common was not
+ * the decision — one reads a snapshot, the other drains an SSE body — but the
+ * scaffold around it, and that scaffold is where the two rules live:
+ *
+ * - **Re-armed from the settled read, never on an interval.** A slow response
+ *   would otherwise stack overlapping requests on an agent that is already
+ *   struggling, and on the platform every one of them BROKERS.
+ * - **Cancellation is a signal, not a flag.** The teardown has to reach the
+ *   in-flight request too — an abandoned progress read otherwise keeps pulling
+ *   chunks out of a run for a page that has navigated away — so `step` is
+ *   handed the signal rather than being trusted to check a boolean.
+ */
+/**
+ * Call `step` until it reports it is finished, or until the returned stop
+ * function is called.
+ *
+ * `step` resolves `true` when there is nothing left to come back for. It is
+ * responsible for its own failures: a rejection would leave the loop stopped
+ * with nobody told, so each caller decides whether its failure is terminal or
+ * just another reason to try again.
+ *
+ * @internal
+ */
+export declare function repeatUntil(intervalMs: number, step: (signal: AbortSignal) => Promise<boolean>): () => void;

package/dist/_sse.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The server-sent-event parser both workflow streams read through.
+ *
+ * Split out when the second stream arrived: `workflow-events.ts` watches a run's
+ * STATE and `use-workflow-progress.ts` reads what the run WROTE, and they parse
+ * the identical wire format. A second copy of a stream parser is the kind of
+ * duplication that goes wrong quietly — the two would drift on exactly the edges
+ * documented below, and the symptom is a page that silently stops updating.
+ *
+ * @internal
+ */
+/** One parsed SSE frame. Comment frames (heartbeats) are skipped, not yielded. */
+export type SseFrame = {
+    event: string;
+    data: unknown;
+};
+/**
+ * Parse an SSE byte stream into frames, with `eventsource-parser`.
+ *
+ * The parser is `aai-studio-client`'s already (`src/api-events.ts`), and it is
+ * catalogued — plus a transitive dependency of `@ai-sdk/provider-utils`, so it
+ * is in this package's tree either way. Adopting it retired a hand-rolled line
+ * splitter justified on the subset in use being "small and fixed" — true of our
+ * own server, and not of what sits between it and the page:
+ *
+ * - It split on `"\n\n"` only. The spec permits `\n`, `\r\n` and `\r`, and a
+ *   CRLF stream is `\r\n\r\n` — no two adjacent `\n`, so **not one frame ever
+ *   parsed** and `pump` fell through to `"fallback"` on the clean end. Silently
+ *   dropping to the poll is the exact cost the run-watch stream exists to avoid,
+ *   and an intermediary re-terminating lines is not our choice to make.
+ * - `line.startsWith("event: ")` required the space the spec makes optional.
+ * - It kept only the LAST `data:` line rather than joining a multi-line one.
+ *
+ * Those three are what `workflow-events.test.ts` pins, and they are the three
+ * that DISCRIMINATE — checked by running the specs against the old parser.
+ * Comment frames and a leading BOM were already fine and are not credited here:
+ * a heartbeat has no `event:` line, so the old parser dropped it anyway, and
+ * `TextDecoder` strips the BOM before either parser sees a byte.
+ *
+ * Three properties of the parser this leans on. `feed` invokes `onEvent`
+ * SYNCHRONOUSLY for every complete event in the chunk, so a batch is collected
+ * per read and yielded in arrival order — the generator shape, and therefore
+ * every caller, is unchanged. An event with no `data:` line at all is not
+ * dispatched (also per spec); every frame these routes emit carries one, since
+ * `workflow-api-events.ts` and `workflow-api-stream.ts` write `event:` and
+ * `data:` together. And a chunk ending in a lone `\r` holds that byte back,
+ * because it may yet turn out to be the first half of a `\r\n` — so a CR-ONLY
+ * stream chunked per frame dispatches one frame behind, and its last frame not
+ * at all (it would need `reset({ consume: true })`, which would also consume a
+ * genuinely truncated frame as if it were whole). Nothing emits CR-only endings,
+ * and the outcome if anything did is the safe one for both readers: a stream
+ * that ends with no final frame is read as a dropped connection, which the run
+ * watch answers by falling back to the poll and the progress reader by
+ * re-opening.
+ */
+export declare function sseFrames(body: ReadableStream<Uint8Array>, signal: AbortSignal): AsyncGenerator<SseFrame>;

package/dist/_workflow-api-ref.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The client preamble every workflow hook needs, once.
+ *
+ * Five hooks (`useWorkflowRun`, `useWorkflowProgress`, `useWorkflowRuns`,
+ * `useWorkflows`, `useWorkflowSubmit`) opened with the same two refs and the
+ * same two paragraphs explaining them, and both halves are load-bearing rather
+ * than stylistic — which is exactly why they should not be re-derived per hook:
+ *
+ * - **The caller's client lives in a REF, never in an effect's dependency
+ *   array.** The natural call site is
+ *   `useWorkflowRun(id, { api: createWorkflowApi() })`, which passes a NEW
+ *   object every render; as a dependency that tears the effect down and
+ *   restarts it on each one, and because a restart clears state and re-renders,
+ *   it schedules the next. The result is an unbounded request loop against the
+ *   agent — on the platform, against the BROKER — with `error` wiped before
+ *   anything can read it, presenting as "the page polls forever" rather than as
+ *   a mistake at the call site.
+ * - **The no-client default is built lazily and ONCE.** As a render-time
+ *   default (`api ?? createWorkflowApi()`) it is a fresh object per render,
+ *   which is the same hazard one layer down; built inside an effect it is a
+ *   fresh object per watch.
+ *
+ * The returned getter is stable for the life of the component and reads the ref
+ * on every call, so a caller that SWAPS clients mid-watch — a token arriving
+ * after login — is picked up by the next request without the watch restarting.
+ */
+import { type WorkflowApi } from "./workflow-client.ts";
+/**
+ * Resolve the client a workflow hook should use, now.
+ *
+ * @param api - The caller's client, or undefined for one aimed at the page's
+ *   own agent.
+ * @returns A stable getter. Call it per request, never once per watch.
+ *
+ * @internal
+ */
+export declare function useWorkflowApiRef(api: WorkflowApi | undefined): () => WorkflowApi;

package/dist/audio.js

@@ -50,14 +50,14 @@ function createCaptureNode(ctx, onChunk, onSilent) {
 			node.port.postMessage({ event: "start" });
 		},
 		stop() {
-			return new Promise((resolve) => {
-				const cap = setTimeout(resolve, CAPTURE_STOP_ACK_TIMEOUT_MS);
-				onStopped = () => {
-					clearTimeout(cap);
-					resolve();
-				};
-				node.port.postMessage({ event: "stop" });
-			});
+			const { promise, resolve } = Promise.withResolvers();
+			const cap = setTimeout(resolve, CAPTURE_STOP_ACK_TIMEOUT_MS);
+			onStopped = () => {
+				clearTimeout(cap);
+				resolve();
+			};
+			node.port.postMessage({ event: "stop" });
+			return promise;
 		}
 	};
 }
@@ -185,24 +185,24 @@ async function createVoiceIO(opts) {
 				pendingStopTurn = null;
 				return Promise.resolve();
 			}
-			return new Promise((resolve) => {
-				onPlaybackStop?.();
-				const settle = () => {
-					clearInterval(poll);
-					clearTimeout(cap);
-					if (onPlaybackStop === settle) {
-						onPlaybackStop = null;
-						pendingStopTurn = null;
-					}
-					resolve();
-				};
-				const poll = setInterval(() => {
-					if (ctx.state !== "running") settle();
-				}, PLAYBACK_DONE_POLL_MS);
-				const cap = setTimeout(settle, PLAYBACK_DONE_MAX_WAIT_MS);
-				onPlaybackStop = settle;
-				pendingStopTurn = turn;
-			});
+			const { promise, resolve } = Promise.withResolvers();
+			onPlaybackStop?.();
+			const settle = () => {
+				clearInterval(poll);
+				clearTimeout(cap);
+				if (onPlaybackStop === settle) {
+					onPlaybackStop = null;
+					pendingStopTurn = null;
+				}
+				resolve();
+			};
+			const poll = setInterval(() => {
+				if (ctx.state !== "running") settle();
+			}, PLAYBACK_DONE_POLL_MS);
+			const cap = setTimeout(settle, PLAYBACK_DONE_MAX_WAIT_MS);
+			onPlaybackStop = settle;
+			pendingStopTurn = turn;
+			return promise;
 		},
 		flush() {
 			if (!playNode) return;

package/dist/{chat-view-DadZOvJO.js → chat-view-CK61bWWx.js}

@@ -1,9 +1,9 @@
+import { t as MessageList } from "./message-list-BwA3rdPi.js";
 import { useSessionSelector, useTheme } from "./context.js";
 import { n as THINKING_COLOR, r as inkTint, t as ERROR_COLOR } from "./_colors-CcAi2FOU.js";
-import { t as AaiLogo } from "./aai-logo-B8lDmsut.js";
+import { t as AaiLogo } from "./aai-logo-9xRBGVFl.js";
 import { t as Eyebrow } from "./eyebrow-C6ZFuiz6.js";
-import { t as Controls } from "./controls-DzQEKq9c.js";
-import { t as MessageList } from "./message-list-YdLocGoT.js";
+import { t as Controls } from "./controls-Cy_YVfsa.js";
 import clsx from "clsx";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region components/console-shell.tsx
@@ -67,6 +67,7 @@ function ConsoleShell({ icon, title, state, pulsing, error, children, footer, cl
 				})]
 			}),
 			error && /* @__PURE__ */ jsx("div", {
+				role: "alert",
 				className: "px-3.5 py-2.5 rounded-aai border text-[13px] leading-[130%] shrink-0",
 				style: {
 					borderColor: "rgba(179,38,30,0.35)",

package/dist/components/_form-values.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reading a `<form>`'s named controls into a plain object.
+ *
+ * Split from `form.tsx` because it is the half with no JSX in it and the half
+ * that carries the rules: what a control CONTRIBUTES is the contract — the
+ * object goes straight into a workflow's input, where a zod schema is waiting —
+ * and each branch below is a decision about that rather than about rendering.
+ *
+ * See `form.tsx`'s module doc for why the values come off the DOM at all.
+ */
+import type { FormValues } from "./form-types.ts";
+/**
+ * Read one `<form>`'s named controls into a plain object.
+ *
+ * Exported for tests and for a caller doing its own submit handling.
+ *
+ * @internal
+ */
+export declare function collectValues(form: HTMLFormElement): Promise<FormValues>;

package/dist/components/auto-scroll.d.ts

@@ -0,0 +1,63 @@
+import type { CSSProperties, ReactNode } from "react";
+/**
+ * A scroll container that stays pinned to the bottom as its content grows,
+ * releases when the reader scrolls up, and re-engages once they return to the
+ * bottom.
+ *
+ * For clients that render their own chat chrome instead of using
+ * {@link MessageList} — a terminal, a dispatch board, a themed transcript.
+ * `MessageList` already behaves this way; this is the same mechanism with no
+ * opinion about what goes inside it.
+ *
+ * @remarks
+ * The pattern this replaces is a `useEffect` that calls
+ * `ref.current?.scrollIntoView()` on every message change. That version has
+ * three faults, and they compound: it fights the reader, since scrolling up to
+ * re-read is undone by the next transcript delta; it misses growth that is not
+ * a new message, because a streamed reply, an expanding tool block or a
+ * markdown reflow changes height without changing the dependency array; and it
+ * needs a synthetic dependency (`messages.length + transcript.length`) to fire
+ * at all, which is where the dead `if (version < 0) return;` line comes from.
+ * A `ResizeObserver` on the content — what this uses — has none of those.
+ *
+ * @example
+ * ```tsx
+ * import { AutoScroll, useSession } from "@alexkroman1/aai-ui";
+ *
+ * function Transcript() {
+ *   const session = useSession();
+ *   return (
+ *     <AutoScroll className="flex-1 min-h-0" contentClassName="flex flex-col gap-2 p-4">
+ *       {session.messages.map((m) => (
+ *         <div key={m.id}>{m.content}</div>
+ *       ))}
+ *     </AutoScroll>
+ *   );
+ * }
+ * ```
+ *
+ * @param children - The scrollable content.
+ * @param className - Classes for the outer container. It must be given a
+ *   bounded height (`flex-1 min-h-0`, `h-full`, a fixed height) — an unbounded
+ *   one grows with its content and never scrolls, so nothing pins.
+ * @param contentClassName - Classes for the inner content element, where
+ *   padding and the children's own layout belong.
+ * @param scrollClassName - Classes for the scrolling element itself. Defaults
+ *   to hiding the scrollbar; pass `"overflow-y-auto"` to show a native one.
+ * @param style - Inline styles for the outer container.
+ * @param initial - Scroll behavior on mount. Defaults to `"instant"` (start at
+ *   the latest content without animating a scroll the reader did not ask for).
+ * @param resize - Scroll behavior when pinned content grows. Defaults to
+ *   `"smooth"`.
+ *
+ * @public
+ */
+export declare function AutoScroll({ children, className, contentClassName, scrollClassName, style, initial, resize, }: {
+    children: ReactNode;
+    className?: string | undefined;
+    contentClassName?: string | undefined;
+    scrollClassName?: string | undefined;
+    style?: CSSProperties | undefined;
+    initial?: "instant" | "smooth" | undefined;
+    resize?: "instant" | "smooth" | undefined;
+}): ReactNode;

package/dist/components/chat-view.js

@@ -1,3 +1,3 @@
 import "../context.js";
-import { t as ChatView } from "../chat-view-DadZOvJO.js";
+import { t as ChatView } from "../chat-view-CK61bWWx.js";
 export { ChatView };

package/dist/components/controls.js

@@ -1,3 +1,3 @@
 import "../context.js";
-import { t as Controls } from "../controls-DzQEKq9c.js";
+import { t as Controls } from "../controls-Cy_YVfsa.js";
 export { Controls };

package/dist/components/form-types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * What a form's controls CONTRIBUTE — the three types both halves of the form
+ * code share.
+ *
+ * Their own module because `form.tsx` (the components) and `_form-values.ts`
+ * (the DOM read) both need them, and a type living in one of those would make
+ * the pair import each other.
+ */
+/**
+ * One submitted form, as a plain object keyed by field name.
+ *
+ * `unknown` values rather than `string`: see the module doc — a number field
+ * yields a number and a file field yields a {@link FileValue}.
+ *
+ * @public
+ */
+export type FormValues = Record<string, unknown>;
+/**
+ * What a {@link FileField} contributes to {@link FormValues}.
+ *
+ * @public
+ */
+export type FileValue = {
+    name: string;
+    /** Size in bytes. */
+    size: number;
+    /** MIME type the browser reported, or `""` when it could not tell. */
+    type: string;
+    /** Last modified, as epoch ms. */
+    lastModified: number;
+    /**
+     * The file's contents, present only when the field asked for them — see
+     * {@link FileField}'s `read` prop. A `data:` URL for `"dataUrl"`, decoded text
+     * for `"text"`.
+     */
+    content?: string;
+};
+/**
+ * How much of a chosen file a {@link FileField} reads.
+ *
+ * `"upload"` is the odd one and the one a workflow input wants: the field
+ * contributes the `File` ITSELF rather than a description of it, and
+ * `useWorkflowSubmit` then stores it through `POST /workflows/uploads` and puts
+ * the id in the run input. Bytes cannot travel in a run input — see
+ * {@link FileField} — so this is how a form takes a file at all.
+ *
+ * @public
+ */
+export type FileRead = "none" | "text" | "dataUrl" | "upload";
+/**
+ * The props every field in `form.tsx` shares.
+ *
+ * Public because it is part of each field's own signature — a type reachable
+ * from a documented one has to be reachable from the entry point too, which the
+ * docs build enforces.
+ *
+ * @public
+ */
+export type FieldShell = {
+    /** Key this field contributes to {@link FormValues}. */
+    name: string;
+    /** Visible label. Omitted leaves the control unlabelled — pass `aria-label` instead. */
+    label?: string | undefined;
+    /** One line of guidance under the control. */
+    hint?: string | undefined;
+    className?: string | undefined;
+};

package/dist/components/form.d.ts

@@ -0,0 +1,138 @@
+import type { FormHTMLAttributes, InputHTMLAttributes, ReactNode, SelectHTMLAttributes, TextareaHTMLAttributes } from "react";
+import { type ButtonSize } from "./button.tsx";
+import type { FieldShell, FileRead, FormValues } from "./form-types.ts";
+export type { FieldShell, FileRead, FileValue, FormValues } from "./form-types.ts";
+/** Props of {@link Form}. */
+export type FormProps = {
+    /**
+     * Called with the collected values. May be async — the form stays disabled
+     * for the duration, so a double-click cannot submit twice.
+     */
+    onSubmit: (values: FormValues) => void | Promise<void>;
+    /**
+     * A failure to show above the fields. The caller owns it, because the
+     * interesting failures are the server's (`useWorkflowSubmit`'s `error`) and
+     * this component never sees them.
+     */
+    error?: string | undefined;
+    children?: ReactNode;
+    className?: string | undefined;
+} & Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "className">;
+/**
+ * A form that hands its values to `onSubmit` as one object.
+ *
+ * Native validation still applies — a `required` field blocks the submit and the
+ * browser says so, which is better than anything this could render.
+ *
+ * @example
+ * ```tsx
+ * import { Form, SubmitButton, TextField } from "@alexkroman1/aai-ui";
+ *
+ * function NameForm() {
+ *   return (
+ *     <Form onSubmit={(values) => console.log(values.topic)}>
+ *       <TextField name="topic" label="Topic" required />
+ *       <SubmitButton>Start</SubmitButton>
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function Form({ onSubmit, error, children, className, ...rest }: FormProps): import("react").JSX.Element;
+/**
+ * Label + control + hint, in the layout every field here uses.
+ *
+ * Exported so a caller's own control gets the same shell rather than an
+ * approximation of it.
+ *
+ * @public
+ */
+export declare function Field({ label, hint, htmlFor, className, children, }: {
+    label?: string | undefined;
+    hint?: string | undefined;
+    /** Id of the control this labels. */
+    htmlFor?: string | undefined;
+    className?: string | undefined;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A single-line text input.
+ *
+ * @public
+ */
+export declare function TextField({ name, label, hint, className, ...rest }: FieldShell & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className">): import("react").JSX.Element;
+/**
+ * A number input. Contributes a NUMBER to {@link FormValues}, or nothing when
+ * left empty.
+ *
+ * @public
+ */
+export declare function NumberField({ name, label, hint, className, ...rest }: FieldShell & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className" | "type">): import("react").JSX.Element;
+/**
+ * A multi-line text input.
+ *
+ * @public
+ */
+export declare function TextAreaField({ name, label, hint, className, rows, ...rest }: FieldShell & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "name" | "className">): import("react").JSX.Element;
+/**
+ * A dropdown. Pass `options`, or `children` for full control over the
+ * `<option>` elements.
+ *
+ * @public
+ */
+export declare function SelectField({ name, label, hint, className, options, children, ...rest }: FieldShell & {
+    options?: readonly (string | {
+        value: string;
+        label: string;
+    })[];
+} & Omit<SelectHTMLAttributes<HTMLSelectElement>, "name" | "className">): import("react").JSX.Element;
+/**
+ * A checkbox. Contributes a BOOLEAN to {@link FormValues}.
+ *
+ * @public
+ */
+export declare function CheckboxField({ name, label, hint, className, ...rest }: FieldShell & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className" | "type">): import("react").JSX.Element;
+/**
+ * A file picker. Contributes a {@link FileValue} (or an array, with `multiple`)
+ * to {@link FormValues} — or nothing when no file was chosen.
+ *
+ * **`upload` is what a workflow input wants.** A run's input is serialized into
+ * the run record and replayed from it on every resume, so a file's BYTES cannot
+ * travel in it. With `upload` the field contributes the `File` itself,
+ * `useWorkflowSubmit` stores it through `POST /workflows/uploads` before
+ * starting the run, and the input carries the upload id — which a step reads
+ * windows of with `readUpload`. Declaring the property in the workflow's
+ * `uploads` list makes `<WorkflowFields>` render exactly this, so a declared
+ * form needs no file markup at all.
+ *
+ * **Without it the field describes the file and does not read it.** `read`
+ * exists for the cases where the bytes really are small and really are the
+ * input — a CSV of ids, a config — and the size is the author's to check.
+ *
+ * @public
+ */
+export declare function FileField({ name, label, hint, className, read, upload, ...rest }: FieldShell & {
+    read?: FileRead;
+    /** Shorthand for `read="upload"` — see above. */
+    upload?: boolean;
+} & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className" | "type">): import("react").JSX.Element;
+/**
+ * The form's submit button, disabled and relabelled while a submit is in
+ * flight.
+ *
+ * @public
+ */
+export declare function SubmitButton({ children, pending, pendingLabel, size, className, }: {
+    children?: ReactNode;
+    /**
+     * Whether the WORK this form started is still going. Separate from the
+     * submit itself, which {@link Form} disables on its own: a workflow run
+     * outlives its `POST`, and the button should stay busy until the run is done.
+     */
+    pending?: boolean;
+    pendingLabel?: string;
+    size?: ButtonSize | undefined;
+    className?: string | undefined;
+}): import("react").JSX.Element;

package/dist/components/message-list.js

@@ -1,3 +1,3 @@
+import { t as MessageList } from "../message-list-BwA3rdPi.js";
 import "../context.js";
-import { t as MessageList } from "../message-list-YdLocGoT.js";
 export { MessageList };

package/dist/components/start-screen.js

@@ -1,7 +1,7 @@
 import { useSessionCore, useSessionSelector, useTheme } from "../context.js";
 import { r as inkTint } from "../_colors-CcAi2FOU.js";
 import { Button } from "./button.js";
-import { t as AaiLogo } from "../aai-logo-B8lDmsut.js";
+import { t as AaiLogo } from "../aai-logo-9xRBGVFl.js";
 import { t as Eyebrow } from "../eyebrow-C6ZFuiz6.js";
 import clsx from "clsx";
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/components/tool-call-block.js

@@ -1,3 +1,3 @@
 import "../context.js";
-import { t as ToolCallBlock } from "../tool-call-block-CAscLGFy.js";
+import { t as ToolCallBlock } from "../tool-call-block-CrLN7xlI.js";
 export { ToolCallBlock };

package/dist/components/workflow-fields.d.ts

@@ -0,0 +1,57 @@
+/** @jsxImportSource react */
+/**
+ * A form built from a workflow's declared input schema.
+ *
+ * `GET workflows` reports each workflow's `inputSchema` as JSON Schema — the
+ * zod schema an author wrote in `agent.ts`, converted at listing time precisely
+ * so a browser can read it. This is what reads it: one `<WorkflowFields>` and a
+ * workflow's form matches its schema by construction, so adding a field to the
+ * schema adds it to the page and nothing can drift.
+ *
+ * ## It covers SCALARS, and says so rather than guessing
+ *
+ * A string, number, integer, boolean or enum has one obvious control each. A
+ * nested object or an array does not — every choice (a JSON textarea, a repeater,
+ * a comma-separated string) is a guess about what the author meant, and a guess
+ * that produces a value the schema then rejects is worse than no field at all.
+ * So those are SKIPPED, and the fields for them are written by hand: every field
+ * in this package is a plain named control, so a hand-written one composes with
+ * a generated one inside the same {@link Form}.
+ */
+import type { WorkflowSummary } from "@alexkroman1/aai";
+/**
+ * Render one field per scalar property of a workflow's input schema.
+ *
+ * Pass the workflow's NAME and the schema is fetched here; pass a
+ * {@link WorkflowSummary} you already hold and nothing is fetched. The name form
+ * is the one a page usually wants — it is the same string the submit hook takes,
+ * and the alternative is three lines (`useWorkflows()`, a `.find()` by name, and
+ * folding that lookup's error into the form's) whose only product is this
+ * component's argument.
+ *
+ * Renders nothing when the workflow declared no schema — a workflow with no
+ * declared input takes anything, and a form for "anything" is not a form — and
+ * nothing while a named lookup is still in flight, so the hand-written fields
+ * beside it are not reordered when the schema lands.
+ *
+ * @example
+ * ```tsx
+ * import { Form, SubmitButton, WorkflowFields, useWorkflowSubmit }
+ *   from "@alexkroman1/aai-ui";
+ *
+ * function StartRun() {
+ *   const { submit, pending, error } = useWorkflowSubmit("transcribe");
+ *   return (
+ *     <Form onSubmit={(values) => submit(values)} error={error}>
+ *       <WorkflowFields workflow="transcribe" />
+ *       <SubmitButton pending={pending}>Transcribe</SubmitButton>
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function WorkflowFields({ workflow }: {
+    workflow?: WorkflowSummary | string | undefined;
+}): import("react").JSX.Element | null;

package/dist/components/workflow-progress.d.ts

@@ -0,0 +1,55 @@
+import type { ReactNode } from "react";
+import type { WorkflowApi } from "../workflow-client.ts";
+/**
+ * What a run has said so far, rendered.
+ *
+ * The complement of a status line, and the reason both exist: a run is
+ * `running` for its whole life, so a one-round job and a ten-round one look
+ * identical while they happen. These lines come from the run itself (`report()`
+ * in a `"use step"` body), which is the only channel a workflow has before it
+ * produces an output.
+ *
+ * Three rules are baked in, and they are why this is a component rather than
+ * three lines each page writes for itself — the two templates that had written
+ * it had written all three, comments included:
+ *
+ * - **It renders nothing until there is something to render.** `supported` is
+ *   what keeps this from being an empty box forever on an agent deployed before
+ *   progress streams existed: "wrote nothing yet" and "serves no stream" are
+ *   indistinguishable from the chunk list alone.
+ * - **The lines are TEXT, not elements.** They are append-only and two rounds
+ *   legitimately produce identical text, so there is no stable per-line key to
+ *   give React. Joining sidesteps the question instead of suppressing the lint
+ *   rule that asks it.
+ * - **They REPLAY.** Chunks are retained with the run, so a reload mid-run —
+ *   or opening a finished run tomorrow — shows how it got there rather than an
+ *   empty box. That is `useWorkflowProgress`'s doing; this is what makes it
+ *   visible.
+ *
+ * @example
+ * ```tsx
+ * import { WorkflowProgress } from "@alexkroman1/aai-ui";
+ *
+ * function RunPanel({ runId }: { runId: string }) {
+ *   return <WorkflowProgress runId={runId} />;
+ * }
+ * ```
+ *
+ * @param runId - The run to read. `undefined` renders nothing, so a page may
+ *   pass its state straight through before a run exists.
+ * @param api - The workflow API client, when the page holds its own. Defaults
+ *   to the one `page()` installs.
+ * @param className - Replaces the default classes rather than extending them,
+ *   so a custom chrome is not fighting a default it did not ask for.
+ * @param placeholder - Rendered instead of nothing while the run has said
+ *   nothing yet — for a page that would otherwise reflow when the first line
+ *   lands.
+ *
+ * @public
+ */
+export declare function WorkflowProgress({ runId, api, className, placeholder, }: {
+    runId?: string | undefined;
+    api?: WorkflowApi | undefined;
+    className?: string | undefined;
+    placeholder?: ReactNode | undefined;
+}): ReactNode;