@alexkroman1/aai-ui 0.17.0 → 0.18.0

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

@@ -4,7 +4,8 @@
  * `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`.
+ * `<WorkflowFields>` renders a form from — is `use-workflows.ts`. What it hands
+ * back is `WorkflowSubmission` (`workflow-submission.ts`).
  *
  * ## `useWorkflowSubmit` — a form's two halves in one hook
  *
@@ -31,168 +32,11 @@
  * `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.
- *
- * @sealed
- * @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.
- *
- * @sealed
- */
-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;
-};
+import type { AnyWorkflowDef, UploadParallelOption, WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
+import type { WorkflowApi } from "./workflow-client.ts";
+import type { SubmitInputOf, WorkflowAppLike, WorkflowDefOf, WorkflowNameOf } from "./workflow-def-types.ts";
+import type { WorkflowSubmission } from "./workflow-submission.ts";
+export type { UploadStatus, WorkflowSubmission } from "./workflow-submission.ts";
 /**
  * Options for {@link useWorkflowSubmit}.
  *
@@ -208,13 +52,22 @@ export type UseWorkflowSubmitOptions = {
      * 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.
+     * `{ storage: "local" }` — `useRunKey({ storage: "local" })`'s key, minted
+     * here — 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. What was chosen is reported back as
+     * `WorkflowSubmission.scope`.
+     *
+     * **An empty or whitespace key THROWS** at the hook (and the route answers
+     * 400): `""` is not "no key" but one key shared by every visitor whose key
+     * computed to it — `user?.id ?? ""` before login. Pass `undefined` until the
+     * key is known.
      */
-    key?: string;
+    key?: string | {
+        readonly storage?: "session" | "local" | undefined;
+    };
     /**
      * On mount, adopt the newest run this `key` already has.
      *
@@ -270,15 +123,35 @@ export type UseWorkflowSubmitOptions = {
  *   Passing an output type where a def belongs is now a compile error rather
  *   than a silent loss of typing, which is the point.
  *
+ *   **Or the AGENT.** `useWorkflowSubmit<typeof agentDef>("digest")` reads the
+ *   def off the agent's own `workflows` map, and the NAME is then a literal the
+ *   compiler checks — a typo is an error naming the keys the agent declares,
+ *   where the def form accepts any string and 404s. See `WorkflowNameOf`; an
+ *   app with several workflows names the one it means as a second type
+ *   argument.
+ *
  * @example
- * ```tsx no-check
+ * ```tsx
+ * // file: agent.ts
+ * import { agent, workflow } from "@alexkroman1/aai";
+ * import { z } from "zod";
+ *
+ * export const digest = workflow({
+ *   input: z.object({ url: z.string() }),
+ *   output: z.object({ title: z.string() }),
+ *   run: async ({ url }) => ({ title: url }),
+ * });
+ *
+ * export default agent({ name: "Digest", workflows: { digest } });
+ *
+ * // file: client.tsx
  * 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");
+ *   const { submitForm, run, pending, error } = useWorkflowSubmit<typeof digest>("digest");
  *   return (
- *     <Form onSubmit={(values) => submit(values)} error={error}>
+ *     <Form onSubmit={(values) => submitForm(values)} error={error}>
  *       <TextField name="url" label="Link" type="url" required />
  *       <SubmitButton pending={pending}>Digest</SubmitButton>
  *       {run?.status === "completed" && <p>{run.output.title}</p>}
@@ -287,6 +160,35 @@ export type UseWorkflowSubmitOptions = {
  * }
  * ```
  *
+ * @example Named through the agent, so the name is checked
+ * ```tsx
+ * // file: agent.ts
+ * import { agent, workflow } from "@alexkroman1/aai";
+ * import { z } from "zod";
+ *
+ * export const digest = workflow({
+ *   input: z.object({ url: z.string() }),
+ *   output: z.object({ title: z.string() }),
+ *   run: async ({ url }) => ({ title: url }),
+ * });
+ *
+ * export default agent({ name: "Digest", workflows: { digest } });
+ *
+ * // file: client.tsx
+ * import { useWorkflowSubmit } from "@alexkroman1/aai-ui";
+ * import type agentDef from "./agent.ts";
+ *
+ * export function DigestForm() {
+ *   const { submit } = useWorkflowSubmit<typeof agentDef>("digest"); // "digset" would not compile
+ *   return (
+ *     <button type="button" onClick={() => submit({ url: "https://example.com/a" })}>
+ *       Digest
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
  * @public
  */
+export declare function useWorkflowSubmit<App extends WorkflowAppLike = never, Name extends WorkflowNameOf<App> = WorkflowNameOf<App>>(workflow: Name, options?: UseWorkflowSubmitOptions): WorkflowSubmission<WorkflowOutputOf<WorkflowDefOf<App, Name>>, SubmitInputOf<WorkflowDefOf<App, Name>>>;
 export declare function useWorkflowSubmit<D extends AnyWorkflowDef>(workflow: string, options?: UseWorkflowSubmitOptions): WorkflowSubmission<WorkflowOutputOf<D>, SubmitInputOf<D>>;

package/dist/{use-workflow-run-DdhWmbx-.js → use-workflow-run-BTEemod0.js}

@@ -1,4 +1,4 @@
-import { n as pageBaseUrl } from "./_utils-Mi-SCFA1.js";
+import { n as pageBaseUrl } from "./_utils-BlZBJPdj.js";
 import { errorMessage } from "@alexkroman1/aai";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { omitUndefined } from "@alexkroman1/aai/utils";
@@ -694,4 +694,4 @@ function useWorkflowRun(runId, options = {}) {
 	};
 }
 //#endregion
-export { useWorkflowProgress as a, isTerminal$1 as c, DEFAULT_PROGRESS_POLL_MS as i, MAX_MISSING_READS as n, useWorkflowApiRef as o, useWorkflowRun as r, createWorkflowApi as s, DEFAULT_WORKFLOW_POLL_MS as t };
+export { useWorkflowProgress as a, createWorkflowApi as c, DEFAULT_PROGRESS_POLL_MS as i, isTerminal$1 as l, MAX_MISSING_READS as n, repeatUntil as o, useWorkflowRun as r, useWorkflowApiRef as s, DEFAULT_WORKFLOW_POLL_MS as t };

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

@@ -20,7 +20,9 @@
  * a page calls when its own run settles, which is exactly when the list is
  * stale.
  */
+import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
+import type { WorkflowAppLike, WorkflowDefOf, WorkflowNameOf, WorkflowsOf } from "./workflow-def-types.ts";
 /**
  * Options for {@link useWorkflowRuns}.
  *
@@ -62,7 +64,10 @@ export type UseWorkflowRunsResult<R = unknown> = {
  * Read a workflow's recent runs.
  *
  * @typeParam R - The workflow's output type, so a completed run's `output` is
- *   typed rather than `unknown`. Derive it with `WorkflowOutputOf`.
+ *   typed rather than `unknown`. Derive it with `WorkflowOutputOf` — or name
+ *   the AGENT instead, `useWorkflowRuns<typeof agentDef>("transcribe")`, and
+ *   both the name and the output come off its `workflows` map (see
+ *   `WorkflowNameOf`).
  *
  * @example
  * ```tsx
@@ -76,4 +81,5 @@ export type UseWorkflowRunsResult<R = unknown> = {
  *
  * @public
  */
-export declare function useWorkflowRuns<R = unknown>(workflow: string | undefined, options?: UseWorkflowRunsOptions): UseWorkflowRunsResult<R>;
+export declare function useWorkflowRuns<App extends WorkflowAppLike = never, Name extends WorkflowNameOf<App> = WorkflowNameOf<App>>(workflow: [App] extends [never] ? never : Name | undefined, options?: UseWorkflowRunsOptions): UseWorkflowRunsResult<WorkflowOutputOf<WorkflowDefOf<App, Name>>>;
+export declare function useWorkflowRuns<R = unknown>(workflow: [WorkflowsOf<R>] extends [never] ? string | undefined : never, options?: UseWorkflowRunsOptions): UseWorkflowRunsResult<R>;

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

@@ -77,9 +77,9 @@
  * pause has become an abandonment.
  */
 import type { AnyWorkflowDef, UploadParallelOption, WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
-import type { WorkflowSubmission } from "./use-workflow-form.ts";
 import type { WorkflowApi } from "./workflow-client.ts";
-import type { SubmitInputOf } from "./workflow-def-types.ts";
+import type { SubmitInputOf, WorkflowAppLike, WorkflowDefOf, WorkflowNameOf } from "./workflow-def-types.ts";
+import type { WorkflowSubmission } from "./workflow-submission.ts";
 /**
  * Options for {@link useWorkflowStream}.
  *
@@ -130,13 +130,13 @@ export type UseWorkflowStreamOptions = {
 /**
  * What {@link useWorkflowStream} returns: a {@link WorkflowSubmission}, exactly.
  *
- * The same eight fields `useWorkflowSubmit` returns, of which this hook is a
+ * The same fields `useWorkflowSubmit` returns, of which this hook is a
  * drop-in sibling — same `<Form>`, same `<UploadProgressBar>`, same
- * `<WorkflowProgress>`. An ALIAS rather than a second declaration of the eight:
+ * `<WorkflowProgress>`. An ALIAS rather than a second declaration of them:
  * the two have to agree field for field to be drop-in, and two copies of a type
  * that have to agree are two copies that can stop agreeing.
  *
- * Exactly two of the fields mean something different here, and both differences
+ * Exactly three of the fields mean something different here, and all three
  * follow from WHEN the run is created — it exists before its bytes do:
  *
  * - `submit()` resolves when the UPLOAD finishes, not when the run is accepted;
@@ -146,6 +146,9 @@ export type UseWorkflowStreamOptions = {
  * - `run` is set from the moment the run EXISTS, which here is before the bytes
  *   are in. That is what lets a page render `<WorkflowProgress>` beside the
  *   upload bar rather than after it.
+ * - `scope` is always `"none"`: the run is reading the bytes THIS page sends,
+ *   so a reload does not orphan it, it ENDS it — and `<WorkflowPendingNote>`
+ *   says so instead of promising the run will be found again.
  */
 export type WorkflowStreamSubmission<R = unknown, I = unknown> = WorkflowSubmission<R, I>;
 /**
@@ -173,4 +176,5 @@ export type WorkflowStreamSubmission<R = unknown, I = unknown> = WorkflowSubmiss
  *
  * @public
  */
+export declare function useWorkflowStream<App extends WorkflowAppLike = never, Name extends WorkflowNameOf<App> = WorkflowNameOf<App>>(workflow: Name, options?: UseWorkflowStreamOptions): WorkflowStreamSubmission<WorkflowOutputOf<WorkflowDefOf<App, Name>>, SubmitInputOf<WorkflowDefOf<App, Name>>>;
 export declare function useWorkflowStream<D extends AnyWorkflowDef>(workflow: string, options?: UseWorkflowStreamOptions): WorkflowStreamSubmission<WorkflowOutputOf<D>, SubmitInputOf<D>>;

package/dist/workflow-def-types.d.ts

@@ -1,7 +1,8 @@
 /**
- * The narrowing the workflow hooks apply to a DEF's input type.
+ * The narrowings the workflow hooks apply to a DEF's input type, and the
+ * readings that let a page name a workflow through its AGENT instead.
  *
- * It used to fall back to `unknown` so an un-parameterized
+ * `SubmitInputOf` used to fall back to `unknown` so an un-parameterized
  * `useWorkflowSubmit("digest")` kept compiling. It does not any more — the def
  * is required — because the fallback was the last way to get an untyped
  * `submit` back, and an escape hatch nobody needs is one somebody uses.
@@ -10,6 +11,20 @@
  * spelled a second way and nothing else, so the hooks name `WorkflowOutputOf`
  * directly — the SDK type this package already re-exports, and the one a page
  * reading the rendered signature can click through to.
+ *
+ * ## Naming a workflow through the agent
+ *
+ * A page used to need the def itself in scope — `import type { digest } from
+ * "./agent.ts"` — which works only when `agent.ts` exports it under a name,
+ * and says nothing about the STRING the page then passes: `useWorkflowSubmit<
+ * typeof digest>("digets")` typechecks and 404s. {@link WorkflowNameOf} and
+ * {@link WorkflowDefOf} read both off the agent's own `workflows` map, so a
+ * page writes `import type agentDef from "./agent.ts"` and the name is a
+ * literal the compiler knows; a typo is an error naming the keys the agent has.
+ * The workflows a build DISCOVERS in `workflows/` are not in that map at the
+ * type level — only `agent({ workflows })`'s entries are — so those pages keep
+ * the def form. The four readings are declared by the SDK
+ * (`@alexkroman1/aai/workflow-api`) and re-exported here.
  */
 import type { WorkflowInputOf } from "@alexkroman1/aai/workflow-api";
 /**
@@ -29,3 +44,4 @@ import type { WorkflowInputOf } from "@alexkroman1/aai/workflow-api";
  * @public
  */
 export type SubmitInputOf<D> = [WorkflowInputOf<D>] extends [never] ? undefined : WorkflowInputOf<D>;
+export type { WorkflowAppLike, WorkflowDefOf, WorkflowNameOf, WorkflowsOf, } from "@alexkroman1/aai/workflow-api";

package/dist/workflow-field-kind.d.ts

@@ -38,18 +38,60 @@
  * text field is — the same value over the wire — so it is a hand-written swap
  * rather than a shape the schema can ask for.
  *
+ * Two NON-scalar shapes do have an honest control, and are the two members
+ * past the scalars: `"lines"` is `<TextAreaField split="lines">` for an array
+ * of strings (one per line), and `"namedText"` is `<FileField read="text"
+ * as="namedText">` for an object of exactly `{ name: string, text: string }` —
+ * a draft, a config, read in the browser and journaled with the input. Both
+ * were the hand-written half of `document-redline-workflow`'s mixed form; a
+ * page may also ASK for either by name through `render`.
+ *
  * Open (`| (string & {})`): a control added later is a new value, so read an
  * unknown kind as `"none"`.
  *
  * @public
  */
-export type WorkflowFieldKind = "text" | "number" | "select" | "checkbox" | "file" | "none" | (string & {});
+export type WorkflowFieldKind = "text" | "number" | "select" | "checkbox" | "file" | "lines" | "namedText" | "none" | (string & {});
+/**
+ * The kinds a page may ask `<WorkflowFields render>` for by property name —
+ * the two non-scalar controls, which a schema cannot always say it wants.
+ *
+ * @public
+ */
+export type WorkflowFieldRender = "lines" | "namedText";
+/**
+ * The schema with a NULLABLE union unwrapped: `anyOf: [X, { type: "null" }]`
+ * reads as `X`, the way `type: ["string", "null"]` reads as `"string"`.
+ *
+ * Zod 4 converts `z.enum([…]).nullable()` (and any nullable whose inner schema
+ * carries keywords of its own) to that `anyOf`, where a bare
+ * `z.string().nullable()` becomes the type list — so a required nullable enum
+ * used to reach the type switch with no `type` at all, render NO control, and
+ * leave a required property out of every submission. A union with two or more
+ * non-null members is some other shape and is answered as itself; a schema
+ * that is not an object has no answer.
+ *
+ * Not exported from the package barrel, like {@link schemaTypeOf}.
+ */
+export declare function nonNullSchemaOf(schema: unknown): Record<string, unknown> | undefined;
+/**
+ * The choices a select renders for `schema`, or undefined when it is not a
+ * closed set: a non-empty `enum`, or the `const` of each member of a union of
+ * literals — which is how zod 4 converts `z.union([z.literal("p"),
+ * z.literal("q")])`, where `z.enum` and `z.literal([1, 2])` convert to `enum`.
+ * The values keep their own type (`[1, 2]` stays numeric), so the control can
+ * submit what the schema declared.
+ *
+ * Not exported from the package barrel, like {@link schemaTypeOf}.
+ */
+export declare function schemaChoicesOf(schema: unknown): readonly unknown[] | undefined;
 /**
  * A property's declared type, taking the first non-null member of a union.
  *
  * `["string", "null"]` is how an optional-and-nullable field converts; the
- * control is the one the non-null half wants. Not exported from the package
- * barrel — the published question is the KIND, and this is the one detail
+ * control is the one the non-null half wants. A nullable `anyOf` is read the
+ * same way ({@link nonNullSchemaOf}). Not exported from the package barrel —
+ * the published question is the KIND, and this is the one detail
  * `<WorkflowFields>` needs past it (an integer's `step`).
  */
 export declare function schemaTypeOf(schema: unknown): string | undefined;
@@ -64,10 +106,18 @@ export declare function schemaTypeOf(schema: unknown): string | undefined;
  *    person to type an id no person has. The declaration is the workflow's
  *    (`workflow({ uploads: [...] })`), not the schema's, precisely because a
  *    marker inside the schema would only work for the library that carried it.
- * 2. **Then a non-empty `enum`**, before the type switch: an enum of strings
- *    is a `string` too, and a select is the narrower, better control.
+ * 2. **Then a closed set of choices**, before the type switch: a non-empty
+ *    `enum`, or a union of `const` literals (`schemaChoicesOf`) — an enum
+ *    of strings is a `string` too, and a select is the narrower, better
+ *    control. A nullable union (`anyOf: [X, { type: "null" }]`) is read as `X`
+ *    throughout, as `type: [X, "null"]` already was.
  * 3. **Then the type** — `boolean`, `number`/`integer`, `string`.
- * 4. **Anything else is `"none"`** rather than a guess. See
+ * 4. **Then the two non-scalar shapes with a control** — an array of strings
+ *    is `"lines"`, an object of exactly `{ name: string, text: string }` is
+ *    `"namedText"`. A page may also name either through `render`, which beats
+ *    the schema for that property (it is the author saying what the shape
+ *    means) but never a declared upload.
+ * 5. **Anything else is `"none"`** rather than a guess. See
  *    {@link WorkflowFieldKind}.
  *
  * @example
@@ -90,10 +140,12 @@ export declare function schemaTypeOf(schema: unknown): string | undefined;
  * @param schema - The property's JSON Schema, as `GET workflows` reports it.
  *   Anything that is not an object reads as `"none"`.
  * @param options - `upload` says the property is named in the workflow's own
- *   `uploads` declaration, which is what step 1 above tests.
+ *   `uploads` declaration, which is what step 1 above tests; `render` is the
+ *   page's own choice for the property (`<WorkflowFields render>`).
  *
  * @public
  */
 export declare function fieldKindFor(schema: unknown, options?: {
     upload?: boolean | undefined;
+    render?: WorkflowFieldRender | undefined;
 }): WorkflowFieldKind;