@alexkroman1/aai-ui 0.17.0 → 0.18.1

package/README.md

@@ -28,21 +28,20 @@ still React, still the same theme tokens.
 
 ### Agent `agent.ts`
 
-The session's state lives in a slot, and `syncState` is what the browser sees —
-pushed after every tool call, so the client never rebuilds it from events:
+The session's state lives in a slot, and a slot declared `sync: true` is what
+the browser sees — pushed after every tool call, so the client never rebuilds it
+from events:
 
 ```ts
 import { agent, sessionSlot } from "@alexkroman1/aai";
 
 const desk = sessionSlot("desk", () => ({ symbols: [] as string[] }), {
   view: (state) => ({ symbols: state.symbols }),
+  sync: true,
 });
 
-export default agent({
-  name: "Market Desk",
-  systemPrompt: "You look up quotes and keep the caller's watchlist.",
-  syncState: desk.projected,
-});
+// The `sync: true` slot is collected; the prompt is the system-prompt.md beside this file.
+export default agent({ name: "Market Desk" });
 ```
 
 ### Tool `tools/get_quote.ts`

package/dist/_submission-timing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The press-to-settle stopwatch both submit hooks report as
+ * `WorkflowSubmission.timing`: the mark `submit()` was called at, and the mark
+ * the submission settled at, read off the one flag that spans both waits.
+ *
+ * It is the half of `transcription-workflow`'s `useTotalLatency` that is a
+ * fact about the SUBMISSION rather than about the page: that template kept
+ * `startedAt`/`frozenMs` in its own state, armed by its own submit handler
+ * and cleared by its own Clear button — shadow state for two instants only
+ * the hook can place exactly. The rendering half (the interval that re-draws
+ * a running clock, the "before the run / inside it" split) stays on the page,
+ * because it is the page that decides how to print a duration.
+ *
+ * Two details it would be easy to get wrong, both kept from the template:
+ *
+ * - **The settle is measured in the effect that sees `pending` fall**, so the
+ *   mark is the moment the run settled rather than whenever the page next
+ *   drew. And only after `pending` has been seen TRUE since the press — a
+ *   press that lands one render before the submission reports itself in
+ *   flight would otherwise freeze the clock at zero.
+ * - **`performance.now()`, not `Date.now()`.** Monotonic; see
+ *   `WorkflowSubmissionTiming`.
+ */
+import type { WorkflowSubmissionTiming } from "./workflow-submission.ts";
+/** What the stopwatch hands a submit hook. */
+export type SubmissionTiming = {
+    /** The marks, for `WorkflowSubmission.timing`. A new object only when a mark changes. */
+    timing: WorkflowSubmissionTiming;
+    /** Call from `submit()`: sets `submittedAt`, clears `settledAt`. */
+    markSubmitted: () => void;
+    /** Call from `reset()`: drops both marks. */
+    clear: () => void;
+};
+/**
+ * The stopwatch over `pending` — see the module doc.
+ *
+ * @param pending - The submission's own `pending`: true from the press until
+ *   the run settles, which is the whole of what the clock covers.
+ */
+export declare function useSubmissionTiming(pending: boolean): SubmissionTiming;

package/dist/_submission.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Everything a submit hook is, bar its BODY.
+ *
+ * `useWorkflowSubmit` (`use-workflow-form.ts`) and `useWorkflowStream`
+ * (`use-workflow-stream.ts`) differ in one thing — when the run is created
+ * relative to the bytes — and that one thing is the submission body each hands
+ * to the form's statechart. Everything after the body was written out twice,
+ * identically: the watch over the run id (`useWorkflowRun`), the two controls
+ * bound to it (`_run-controls.ts`), `pending` as "the machine is busy or the
+ * watch is still polling", the press-to-settle stopwatch
+ * (`_submission-timing.ts`), a `reset` that clears both, and the fourteen-field
+ * `WorkflowSubmission` assembled from all of it. Two copies of a return object
+ * that have to agree field for field are two copies that can stop agreeing —
+ * the stream hook's type is an ALIAS of the form hook's for the same reason —
+ * so the tail is one function, and each hook keeps only what makes it itself.
+ */
+import type { RecoverRunOptions } from "./_recover-run.ts";
+import type { SubmissionWork } from "./_workflow-form-state.ts";
+import type { UploadGate } from "./upload/index.ts";
+import type { WorkflowApi } from "./workflow-client.ts";
+import type { WorkflowSubmission, WorkflowSubmissionScope } from "./workflow-submission.ts";
+/**
+ * What one `submit(input)` does, from the hook that owns it: the gate the
+ * bytes pause through, and the work that runs as THE submission (see
+ * `SubmissionActions.submit`). Called per press with the client read at that
+ * moment, after the stopwatch has marked it.
+ *
+ * It is a `useCallback` dependency of `submit`, so a hook hands over a stable
+ * one — rebuilt only when what it closes over changes — or `submit`, and with
+ * it the `onSubmit` a page gives `<Form>`, is rebuilt every render.
+ */
+export type BeginSubmission = (input: unknown, client: WorkflowApi) => {
+    gate: UploadGate;
+    work: SubmissionWork;
+};
+/** What {@link useSubmission} needs from the hook. */
+export type SubmissionOptions = {
+    /** The stable getter from `useWorkflowApiRef` — the hook's, since the convention keys on the hook file. */
+    getClient: () => WorkflowApi;
+    /** The caller's client, for the watch; `undefined` is the page's own agent. */
+    api: WorkflowApi | undefined;
+    /** How often the fallback poll re-reads a live run; `undefined` is the default. */
+    intervalMs: number | undefined;
+    /** The mount-time lookup, or nothing for a hook that refuses it (`useWorkflowStream`). */
+    recover?: RecoverRunOptions;
+    /** Who finds the run again — reported back as `WorkflowSubmission.scope`. */
+    scope: WorkflowSubmissionScope;
+    /** The hook's own half — see {@link BeginSubmission}. */
+    begin: BeginSubmission;
+};
+/**
+ * The shared tail of a submit hook: the statechart, the watch, the controls,
+ * the stopwatch, and the `WorkflowSubmission` built from them. See the module
+ * doc.
+ */
+export declare function useSubmission(options: SubmissionOptions): WorkflowSubmission<unknown, never>;

package/dist/_theme.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One `ClientTheme` — either form — to the five resolved tokens.
+ *
+ * Its own module rather than a branch in `context.ts` (which is at the cap)
+ * because the derivation is a decision worth a test of its own: the dark
+ * neutrals are chosen to keep the components' derived tints (`_colors.ts`'s
+ * `inkTint`, which walks from `text` toward the ground) above WCAG AA on a
+ * dark surface, exactly as the light defaults do on a light one.
+ */
+import type { ClientTheme, ResolvedClientTheme } from "./types.ts";
+export declare const DEFAULT_THEME: ResolvedClientTheme;
+/**
+ * Every token filled in: the preset's neutrals under its accent, or the given
+ * tokens over the defaults. `undefined` is the default theme itself. A token
+ * given as `""` is ignored with a warning ({@link withoutBlankTokens}).
+ */
+export declare function resolveClientTheme(theme: ClientTheme | undefined): ResolvedClientTheme;

package/dist/_theme.test-d.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The two forms of `ClientTheme` are EXCLUSIVE at the type level.
+ *
+ * A mixed `{ primary, mode: "dark", bg }` used to compile: an object literal is
+ * checked against the union as a whole, so a key from either member passed
+ * excess-property checking, and at runtime `isPreset` won and `bg` was dropped
+ * without a word. The `?: undefined` guards on each member are what make the
+ * mixed literal a compile error, and this file is what keeps them there.
+ *
+ * Probed with a conditional rather than a suppression directive: an assignability
+ * question answered as `true`/`false` names the shape that moved, where a
+ * suppressed error passes on ANY error.
+ */
+export {};

package/dist/{_utils-Mi-SCFA1.js → _utils-BlZBJPdj.js}

@@ -21,11 +21,10 @@ function pageBaseUrl() {
 /**
 * Set the document title, when there is one to set and a document to set it on.
 *
-* Both mounts do this and neither may clobber a title the page's own HTML
-* declared — `mountClient()`'s custom-component tier because there is no shell header
-* to show the name in, `mountPage()` because there is no shell at all. One copy, for
-* the reason `resolveContainer` and `mountRoot` are shared: the rule is the
-* same, so the two mounts must not be able to disagree about it.
+* `mountPage()` does this for its `name`, and may not clobber a title the
+* page's own HTML declared — there is no shell to show the name in otherwise.
+* `mountClient()` sets none: the agent's name reaches its default shell from
+* the agent's own `client-config`, and a custom component owns the page.
 */
 function setPageTitle(name) {
 	if (name && typeof document !== "undefined") document.title = name;

package/dist/_utils.d.ts

@@ -11,11 +11,10 @@ export declare function pageBaseUrl(): string;
 /**
  * Set the document title, when there is one to set and a document to set it on.
  *
- * Both mounts do this and neither may clobber a title the page's own HTML
- * declared — `mountClient()`'s custom-component tier because there is no shell header
- * to show the name in, `mountPage()` because there is no shell at all. One copy, for
- * the reason `resolveContainer` and `mountRoot` are shared: the rule is the
- * same, so the two mounts must not be able to disagree about it.
+ * `mountPage()` does this for its `name`, and may not clobber a title the
+ * page's own HTML declared — there is no shell to show the name in otherwise.
+ * `mountClient()` sets none: the agent's name reaches its default shell from
+ * the agent's own `client-config`, and a custom component owns the page.
  */
 export declare function setPageTitle(name: string | undefined): void;
 /**

package/dist/agent-state.d.ts

@@ -1,5 +1,6 @@
 /**
- * Reading what the agent projects — `agent({ syncState })` — in the browser.
+ * Reading what the agent projects — the slots declared `sync: true`, collected
+ * into its `syncState` — in the browser.
  *
  * The frame is KEYED by slot name (`{ [slot]: view }`), so every reader here
  * selects ONE slot by the name the agent keyed it under. That is what lets a
@@ -52,9 +53,10 @@ export declare function useAgentState(): AgentStateFrame | null;
  * import { useAgentState } from "@alexkroman1/aai-ui";
  *
  * // In a real project the slot is declared beside the agent and imported here;
- * // the agent declares `syncState: cartSlot.projected`.
+ * // `sync: true` is what puts it in the agent's `syncState`.
  * const cartSlot = sessionSlot("cart", () => ({ items: [] as string[] }), {
  *   view: (cart) => ({ count: cart.items.length }),
+ *   sync: true,
  * });
  *
  * function CartBadge() {

package/dist/append-dictation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `appendDictation(draft, text)` — where dictated words land in a text box
+ * that may already hold some.
+ */
+/**
+ * `draft` with `text` added after it, joined by exactly one space: a draft
+ * ending in whitespace or a newline does not grow a double space, and an empty
+ * or blank draft is replaced rather than given a leading one.
+ *
+ * Never REPLACES what was typed — the words someone said are an addition to
+ * the box, which is what makes speaking into a half-written prompt safe.
+ *
+ * @example
+ * ```ts
+ * import { appendDictation } from "@alexkroman1/aai-ui";
+ *
+ * appendDictation("Build me an agent", "that books tables."); // "Build me an agent that books tables."
+ * appendDictation("", "Hello"); // "Hello"
+ * ```
+ *
+ * @public
+ */
+export declare function appendDictation(draft: string, text: string): string;

package/dist/audio/dictation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The dictation recorder: the microphone captured into one clip, handed back
+ * as a WAV file for a transcription endpoint to read whole.
+ *
+ * A clip, not a stream — the dictation API takes the whole utterance in one
+ * request — so this is the pre-connect capture (`audio/preconnect.ts`) used
+ * for what it already does: buffer the mic at a known rate. Stopping is its
+ * `detach` (the worklet's tail flush lands in the buffer, so the last word is
+ * kept) and then `close`, which turns the browser's recording indicator off.
+ *
+ * @module
+ */
+/** One recording in progress. Every method is safe to call after another. */
+export type DictationRecorder = {
+    /** The rate the clip is recorded at. */
+    readonly sampleRate: number;
+    /**
+     * Stop, release the microphone, and answer the clip as a mono 16-bit WAV.
+     * An empty clip (stopped before the first batch) is a 44-byte header.
+     */
+    stop(): Promise<Uint8Array<ArrayBuffer>>;
+    /** Stop and release the microphone, keeping nothing. Never rejects. */
+    cancel(): Promise<void>;
+};
+/**
+ * Ask for the microphone and start recording.
+ *
+ * Rejects like the session's own capture does — a denied prompt, a rate the
+ * browser refused — with the microphone released.
+ */
+export declare function openDictationRecorder(opts: {
+    sampleRate: number;
+    /** The capture buffer's bound; the caller stops the clip by then. */
+    maxSeconds: number;
+    captureWorkletSrc: string;
+}): Promise<DictationRecorder>;

package/dist/audio/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * The browser audio layer's import surface for the rest of the package: the
- * {@link VoiceIO} a live call plays and captures through, and the pre-connect
- * capture that buffers the mic before the server names its rates.
+ * {@link VoiceIO} a live call plays and captures through, the pre-connect
+ * capture that buffers the mic before the server names its rates, and the
+ * dictation recorder `useDictation` turns into one clip.
  *
  * `capture.ts` (the grant checks and the capture node both halves share) is
  * private to this directory — guard-invariants rule 37 fails an import from
@@ -14,5 +15,6 @@
  *
  * @module
  */
+export { type DictationRecorder, openDictationRecorder } from "./dictation.ts";
 export { openPreConnectCapture, type PreConnectCapture } from "./preconnect.ts";
 export { createVoiceIO, type VoiceIO, type VoiceIOOptions } from "./voice-io.ts";

package/dist/audio/index.js

@@ -1,4 +1,5 @@
 import { CAPTURE_STOP_ACK_TIMEOUT_MS, MIC_BUFFER_SECONDS, PLAYBACK_DONE_MAX_WAIT_MS, PLAYBACK_DONE_POLL_MS, VOICE_CAPTURE_CONSTRAINTS } from "../types.js";
+import { encodeWav } from "@alexkroman1/aai/step";
 //#region src/audio/capture.ts
 /**
 * The capture half's primitives, shared by the audio path (`audio/voice-io.ts`) and
@@ -250,6 +251,48 @@ async function startCapture(ctx, stream, opts) {
 	};
 }
 //#endregion
+//#region src/audio/dictation.ts
+/**
+* The dictation recorder: the microphone captured into one clip, handed back
+* as a WAV file for a transcription endpoint to read whole.
+*
+* A clip, not a stream — the dictation API takes the whole utterance in one
+* request — so this is the pre-connect capture (`audio/preconnect.ts`) used
+* for what it already does: buffer the mic at a known rate. Stopping is its
+* `detach` (the worklet's tail flush lands in the buffer, so the last word is
+* kept) and then `close`, which turns the browser's recording indicator off.
+*
+* @module
+*/
+/**
+* Ask for the microphone and start recording.
+*
+* Rejects like the session's own capture does — a denied prompt, a rate the
+* browser refused — with the microphone released.
+*/
+async function openDictationRecorder(opts) {
+	const capture = await openPreConnectCapture(opts);
+	let done = false;
+	return {
+		sampleRate: capture.sampleRate,
+		async stop() {
+			if (done) return encodeWav([], { sampleRate: capture.sampleRate });
+			done = true;
+			try {
+				const { chunks, sampleRate } = await capture.detach();
+				return encodeWav(chunks.map((c) => new Uint8Array(c)), { sampleRate });
+			} finally {
+				await capture.close();
+			}
+		},
+		async cancel() {
+			if (done) return;
+			done = true;
+			await capture.close().catch(() => {});
+		}
+	};
+}
+//#endregion
 //#region src/audio/voice-io.ts
 /**
 * Create a {@link VoiceIO} instance that captures microphone audio and
@@ -428,4 +471,4 @@ async function createVoiceIO(opts) {
 	return io;
 }
 //#endregion
-export { createVoiceIO, openPreConnectCapture };
+export { createVoiceIO, openDictationRecorder, openPreConnectCapture };

package/dist/{chat-view-W6KcdjJY.js → chat-view-BwKpF0MN.js}

@@ -1,7 +1,7 @@
-import { useSessionError, useSessionStatus, useTheme } from "./context.js";
-import { t as MessageList } from "./message-list-BsaBkBgo.js";
+import { l as useSessionStatus, s as useSessionError, u as useTheme } from "./context-BF0KsI9X.js";
+import { t as MessageList } from "./message-list-BBHLK05X.js";
 import { a as inkTint, r as THINKING_COLOR, t as ERROR_COLOR } from "./_colors-CpZO-88A.js";
-import { t as Eyebrow } from "./eyebrow-UfmSz9yy.js";
+import { t as Eyebrow } from "./eyebrow-Bp4y1rZ9.js";
 import { Controls } from "./components/controls.js";
 import clsx from "clsx";
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -186,6 +186,23 @@ function StateDot({ color, pulseMs, className, title }) {
 		title
 	});
 }
+/** Which coarse group a state belongs to — `error` deliberately none. */
+function groupOf(state) {
+	switch (state) {
+		case "ready":
+		case "listening":
+		case "speaking": return "live";
+		case "thinking": return "busy";
+		case "error": return;
+		default: return "idle";
+	}
+}
+/**
+* The idle dot's ink step: the theme's text at half strength over its ground.
+* Lighter than `INK_FAINT_PCT` (the text steps) on purpose — a dot is a
+* 8px disc, not a word, and at 65% it read as "on" beside a live one.
+*/
+const INK_IDLE_PCT = 50;
 /**
 * The live session state as a coloured dot and a word, on its own narrow
 * subscription.
@@ -204,25 +221,14 @@ function StateDot({ color, pulseMs, className, title }) {
 *
 * Must be rendered inside the providers `mountClient()` installs.
 *
-* @example A dispatch board's readout: its own colours, three of its own words
+* @example A dispatch board's readout: coarse colours, three of its own words
 * ```tsx
-* import type { AgentState } from "@alexkroman1/aai-ui";
 * import { SessionStateDot } from "@alexkroman1/aai-ui";
 *
-* const STATE_COLORS = {
-*   disconnected: "#6b7280",
-*   connecting: "#6b7280",
-*   ready: "#22c55e",
-*   listening: "#22c55e",
-*   thinking: "#eab308",
-*   speaking: "#3b82f6",
-*   error: "#6b7280",
-* } satisfies Record<AgentState, string>;
-*
 * function StatusReadout() {
 *   return (
 *     <SessionStateDot
-*       colors={STATE_COLORS}
+*       colors={{ idle: "#6b7280", live: "#22c55e", busy: "#eab308", speaking: "#3b82f6" }}
 *       labels={{ listening: "LISTENING", thinking: "PROCESSING", speaking: "TRANSMITTING" }}
 *       labelClassName="text-[11px] uppercase"
 *     />
@@ -230,6 +236,9 @@ function StateDot({ color, pulseMs, className, title }) {
 * }
 * ```
 *
+* With no `colors` at all the dot follows the mounted theme — a chrome that
+* sets `mountClient({ theme })` gets a matching dot for free.
+*
 * @param props - See {@link SessionStateDotProps}.
 *
 * @public
@@ -238,7 +247,8 @@ function SessionStateDot({ colors, labels, pulse = true, className, dotClassName
 	const state = useSessionStatus();
 	const theme = useTheme();
 	const pulseMs = pulse ? PULSE_MS[state] ?? null : null;
-	const color = colors?.[state] ?? stateColor(state, theme.primary, inkTint(theme.text, theme.bg, 65));
+	const group = groupOf(state);
+	const color = colors?.[state] ?? (group === void 0 ? void 0 : colors?.[group]) ?? stateColor(state, theme.primary, inkTint(theme.text, theme.bg, INK_IDLE_PCT));
 	return /* @__PURE__ */ jsxs("span", {
 		className: clsx("inline-flex items-center gap-2", className),
 		"data-state": state,

package/dist/{client-config-CzvWmw4X.js → client-config-DcMCWmkO.js}

@@ -1,4 +1,4 @@
-import { n as pageBaseUrl } from "./_utils-Mi-SCFA1.js";
+import { n as pageBaseUrl } from "./_utils-BlZBJPdj.js";
 import { CLIENT_CONFIG_PATH, ClientConfigResponseSchema, SESSION_TICKET_HEADER } from "@alexkroman1/aai/protocol";
 //#region src/client-config.ts
 /**

package/dist/components/button.js

@@ -1,4 +1,4 @@
-import { useTheme } from "../context.js";
+import { u as useTheme } from "../context-BF0KsI9X.js";
 import { a as inkTint, i as focusRingStyle, n as FOCUS_RING, o as primaryTint } from "../_colors-CpZO-88A.js";
 import clsx from "clsx";
 import { jsx } from "react/jsx-runtime";

package/dist/components/chat-view.js

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

package/dist/components/controls.js

@@ -1,6 +1,6 @@
-import { useSessionCore, useSessionSelector } from "../context.js";
+import { c as useSessionSelector, o as useSessionCore } from "../context-BF0KsI9X.js";
 import { Button } from "./button.js";
-import { n as SessionUrlChips } from "../url-chips-oyy_Eiqh.js";
+import { n as SessionUrlChips } from "../url-chips-C_SHU6fq.js";
 import { memo } from "react";
 import clsx from "clsx";
 import { jsx, jsxs } from "react/jsx-runtime";

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

@@ -1,5 +1,5 @@
 import type { InputHTMLAttributes, JSX, ReactNode, SelectHTMLAttributes, TextareaHTMLAttributes } from "react";
-import type { FieldShell, FileReadMode } from "./form-types.ts";
+import type { FieldShell, FileReadMode, FileValueShape, TextSplitMode } from "./form-types.ts";
 /**
  * Label + control + hint, in the layout every field here uses.
  *
@@ -67,11 +67,21 @@ export declare function NumberField(props: FieldShell & Omit<InputHTMLAttributes
  * Accepts every `<textarea>` attribute except `name` and `className`, plus the
  * shared {@link FieldShell} props. `rows` defaults to 4.
  *
- * @param props - {@link FieldShell} props plus `<textarea>` attributes.
+ * **`split="lines"` contributes a `string[]`** — one entry per non-blank line,
+ * trimmed — which is the control for a schema's `z.array(z.string())`: "one
+ * point per line". `document-redline-workflow` reshaped the textarea's string
+ * by hand on submit; the field does it now, so `<WorkflowFields>` can render
+ * it for a `string[]` property and a hand-written one can match. See
+ * {@link TextSplitMode}.
+ *
+ * @param props - {@link FieldShell} props, `split`, and `<textarea>` attributes.
  *
  * @public
  */
-export declare function TextAreaField({ name, label, hint, className, rows, ...rest }: FieldShell & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "name" | "className">): JSX.Element;
+export declare function TextAreaField({ name, label, hint, className, rows, split, ...rest }: FieldShell & {
+    /** How the text is contributed — see above. Default `"none"`, the string. */
+    split?: TextSplitMode | undefined;
+} & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "name" | "className">): JSX.Element;
 /**
  * A dropdown.
  *
@@ -126,17 +136,26 @@ export declare function CheckboxField({ name, label, hint, className, ...rest }:
  * {@link FileReadMode} for the four values; `upload` is shorthand for
  * `read="upload"`.
  *
+ * **`as="namedText"` contributes `{ name, text }`** ({@link NamedTextValue})
+ * instead of the metadata-bearing {@link FileValue}, and implies
+ * `read="text"`: the shape a schema declares for a draft to redline or a
+ * config to apply, and the one `<WorkflowFields>` renders for an object
+ * property of exactly that shape. `document-redline-workflow` reshaped the
+ * `FileValue` by hand on submit; the field does it now.
+ *
  * Otherwise accepts every `<input>` attribute except `name`, `className` and
  * `type`, plus the shared {@link FieldShell} props — so `accept` and
  * `multiple` are passed straight through.
  *
- * @param props - {@link FieldShell} props, `read`/`upload`, and `<input>`
+ * @param props - {@link FieldShell} props, `read`/`upload`/`as`, and `<input>`
  * attributes.
  *
  * @public
  */
-export declare function FileField({ name, label, hint, className, read, upload, ...rest }: FieldShell & {
+export declare function FileField({ name, label, hint, className, read, upload, as, ...rest }: FieldShell & {
     read?: FileReadMode;
     /** Shorthand for `read="upload"` — see above. */
     upload?: boolean;
+    /** The shape of a READ file's value — see above and {@link FileValueShape}. */
+    as?: FileValueShape | undefined;
 } & Omit<InputHTMLAttributes<HTMLInputElement>, "name" | "className" | "type">): JSX.Element;

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

@@ -48,6 +48,21 @@ export type FileValue = {
  * @public
  */
 export declare function isFileValue(value: unknown): value is FileValue;
+/**
+ * What a `<FileField read="text" as="namedText">` contributes: the file's name
+ * and its text, and nothing else — the shape a workflow schema declares as
+ * `z.object({ name: z.string(), text: z.string() })` for a draft, a config, a
+ * CSV of ids that belongs in the run's input rather than in an upload. A
+ * {@link FileValue} carries the browser's metadata too, which a schema then
+ * has to strip or refuse; this is the value a schema can take as it is.
+ *
+ * @sealed
+ * @public
+ */
+export type NamedTextValue = {
+    name: string;
+    text: string;
+};
 /**
  * How much of a chosen file a {@link FileField} reads.
  *
@@ -60,6 +75,23 @@ export declare function isFileValue(value: unknown): value is FileValue;
  * @public
  */
 export type FileReadMode = "none" | "text" | "dataUrl" | "upload";
+/**
+ * The SHAPE a {@link FileField} contributes a read file as. `"file"` (the
+ * default) is a {@link FileValue}; `"namedText"` is a {@link NamedTextValue},
+ * which implies `read="text"`. Only `"namedText"` is a reshape today; the
+ * option exists so a workflow's object property has a declared control.
+ *
+ * @public
+ */
+export type FileValueShape = "file" | "namedText";
+/**
+ * How a {@link TextAreaField} contributes its text. `"none"` (the default) is
+ * the string; `"lines"` is a `string[]` — one entry per non-blank line,
+ * trimmed — the control for a schema's `z.array(z.string())`.
+ *
+ * @public
+ */
+export type TextSplitMode = "none" | "lines";
 /**
  * The props every field in `form.tsx` shares.
  *

package/dist/components/form.d.ts

@@ -2,7 +2,7 @@ import type { ButtonHTMLAttributes, FormHTMLAttributes, JSX, ReactNode } from "r
 import { type ButtonSize, type ButtonVariant } from "./button.tsx";
 import type { FormValues } from "./form-types.ts";
 export { CheckboxField, Field, FileField, NumberField, SelectField, TextAreaField, TextField, } from "./form-fields.tsx";
-export type { FieldShell, FileReadMode, FileValue, FormValues } from "./form-types.ts";
+export type { FieldShell, FileReadMode, FileValue, FileValueShape, FormValues, NamedTextValue, TextSplitMode, } from "./form-types.ts";
 export { isFileValue } from "./form-types.ts";
 /**
  * Props of {@link Form}.

package/dist/components/message-list.js

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