@tai42/studio-sdk 30.0.1 → 31.0.0

package/src/schema-form/default-value.ts

@@ -12,8 +12,9 @@
  *    opted into.
  *
  * `skeletonValueForSchema` is the sibling entry for programmatic reseeds (a
- * union variant switch): same walk, but required scalars mint their type's
- * empty value so the committed seed validates against its own schema.
+ * union variant switch): same walk, but every required field with a known empty
+ * value is minted, so the committed seed has no missing required field. A minted
+ * empty value may still fail its own value check (see the sibling's docstring).
  */
 import { classifySchema } from './classify';
 import type { FieldModel } from './field-model';
@@ -37,22 +38,56 @@ function explicitDefault(
  * whole-tool-schema call).
  */
 export function defaultValueForSchema(schema: JsonSchema, root: JsonSchema = schema): unknown {
-  return seedValue(schema, root, false);
+  return finiteSeed(seedValue(schema, root, false, new Set()));
 }
 
 /**
  * A SELF-CONSISTENT skeleton for a schema — the seed a variant switch (or any
  * other programmatic reseed) commits as the field's new value. Where
  * {@link defaultValueForSchema} deliberately leaves a required scalar absent so
- * a fresh form flags it, a committed skeleton must validate against its own
- * schema, so here EVERY required field with a known empty value is minted:
- * required strings seed `''`, numbers `0`, booleans `false` — consistently with
- * the `[]` / `{}` / nested-object seeds the default path already mints. Kinds
- * with no empty value to name (enum, union, free-form JSON) stay absent either
- * way: inventing a choice would be a lie the user never made.
+ * a fresh form flags it, a committed skeleton carries no missing required field,
+ * so here EVERY required field with a known empty value is minted: required
+ * strings seed `''`, numbers `0`, booleans `false`, a templated text an empty
+ * inline source `{ content: '' }` — consistently with the `[]` / `{}` /
+ * nested-object seeds the default path already mints. A minted empty value is
+ * not promised to pass its own value check: an empty templated text fails it
+ * ("needs inline content or a stored template"), as does `''` under a
+ * `minLength` or a `pattern`, and validation reports that error like any
+ * other. Kinds with no empty value to name (enum,
+ * union, free-form JSON) stay absent either way: inventing a choice would be a
+ * lie the user never made.
  */
 export function skeletonValueForSchema(schema: JsonSchema, root: JsonSchema = schema): unknown {
-  return seedValue(schema, root, true);
+  return finiteSeed(seedValue(schema, root, true, new Set()));
+}
+
+/**
+ * The walk's answer when an object's required structure leads back into an object
+ * shape it is already inside with no `null` accepted anywhere on the way: that
+ * nesting never ends, so the object has no finite value.
+ */
+const NO_FINITE_VALUE: unique symbol = Symbol('no finite value');
+
+/**
+ * Thrown by {@link defaultValueForSchema} and {@link skeletonValueForSchema} when the
+ * schema admits no finite value: a chain of required properties refers back to its
+ * own definition with no `null` accepted on the way. A caller that seeds on a user
+ * action catches exactly this type to show the failure on its field; any other error
+ * is not a seeding outcome and propagates.
+ */
+export class NoFiniteValueError extends Error {
+  constructor() {
+    super(
+      'SchemaForm: the schema admits no finite value: its required properties refer back to their own definition with no null accepted on the way',
+    );
+    this.name = 'NoFiniteValueError';
+  }
+}
+
+/** The entry points' result: the seeded value, or {@link NoFiniteValueError} when none is finite. */
+function finiteSeed(seed: unknown): unknown {
+  if (seed === NO_FINITE_VALUE) throw new NoFiniteValueError();
+  return seed;
 }
 
 /**
@@ -60,16 +95,44 @@ export function skeletonValueForSchema(schema: JsonSchema, root: JsonSchema = sc
  * carries an explicit default. A required property recurses; an optional one is
  * materialized only when it declares a `default`, so its own required children
  * never raise errors on a field the user did not opt into.
+ *
+ * `expanding` holds the object shapes being seeded on the way down. Reaching one of
+ * them again (a self-referencing definition) answers {@link NO_FINITE_VALUE}, and
+ * so does an object with any required property that answers it. A `nullable` object
+ * turns that answer into `null`, the value that ends the nesting there. So the
+ * answer climbs to the nearest nullable object above the point where the cycle
+ * closes, and reaches the entry point only when no object on the way accepts
+ * `null`: then no finite value exists.
  */
 function seedObject(
+  model: ModelOf<'object'>,
+  nullable: boolean,
+  root: JsonSchema,
+  mintScalars: boolean,
+  expanding: ReadonlySet<object>,
+): unknown {
+  const seeded = seedProperties(model, root, mintScalars, expanding);
+  return seeded === NO_FINITE_VALUE && nullable ? null : seeded;
+}
+
+/**
+ * An object's own seed (see {@link seedObject}): its properties' seeds, or
+ * {@link NO_FINITE_VALUE} when its shape is already being seeded above or a required
+ * property has no finite value.
+ */
+function seedProperties(
   model: ModelOf<'object'>,
   root: JsonSchema,
   mintScalars: boolean,
-): Record<string, unknown> {
+  expanding: ReadonlySet<object>,
+): unknown {
+  if (expanding.has(model.shape)) return NO_FINITE_VALUE;
+  const inside = new Set(expanding).add(model.shape);
   const entries: [string, unknown][] = [];
   for (const [name, propSchema] of model.properties) {
     if (model.required.has(name)) {
-      const seeded = seedValue(propSchema, root, mintScalars);
+      const seeded = seedValue(propSchema, root, mintScalars, inside);
+      if (seeded === NO_FINITE_VALUE) return NO_FINITE_VALUE;
       if (seeded !== undefined) entries.push([name, seeded]);
       continue;
     }
@@ -101,9 +164,16 @@ function seedScalar(kind: 'string' | 'number' | 'boolean', mintScalars: boolean)
 /**
  * The shared seeding walk. `mintScalars` distinguishes the two entry points
  * above: `false` leaves value-less required scalars absent; `true` mints their
- * type's empty value.
+ * type's empty value. `expanding` holds the object shapes being seeded on the way
+ * down; a nullable object whose own seed has no finite value seeds `null` (see
+ * {@link seedObject}).
  */
-function seedValue(schema: JsonSchema, root: JsonSchema, mintScalars: boolean): unknown {
+function seedValue(
+  schema: JsonSchema,
+  root: JsonSchema,
+  mintScalars: boolean,
+  expanding: ReadonlySet<object>,
+): unknown {
   const classified = classifySchema(schema, root);
   const explicit = explicitDefault(schema, classified.schema);
   if (explicit.present) return explicit.value;
@@ -113,7 +183,7 @@ function seedValue(schema: JsonSchema, root: JsonSchema, mintScalars: boolean):
     case 'const':
       return model.value;
     case 'object':
-      return seedObject(model, root, mintScalars);
+      return seedObject(model, classified.nullable, root, mintScalars, expanding);
     case 'array':
     case 'multiselect':
       return [];
@@ -123,6 +193,10 @@ function seedValue(schema: JsonSchema, root: JsonSchema, mintScalars: boolean):
     case 'number':
     case 'boolean':
       return seedScalar(model.kind, mintScalars);
+    case 'templated-text':
+      // Inline is the templated text's own starting mode, so its empty value is an
+      // empty inline source; the default path leaves it absent like a scalar.
+      return mintScalars ? { content: '' } : undefined;
     case 'enum':
     case 'union':
     case 'json':

package/src/schema-form/expression-field.tsx

@@ -0,0 +1,162 @@
+/**
+ * The injected expression door as a schema-form field: an `x-tai42-expression`
+ * annotation mapped onto the door's input-shape descriptor, and the door mounted
+ * inside a Suspense boundary that paints a resting shell while a lazily-injected
+ * door resolves. A jq-annotated string draws it as the whole field; a jq-annotated
+ * templated-text field draws it as its inline editor.
+ *
+ * NO JQ EDGE: the door arrives from the host (see `ExpressionFieldContext`);
+ * this module names no jq type.
+ */
+import type { ReactNode } from 'react';
+import { Suspense, useMemo } from 'react';
+
+import { Field } from '../components/field';
+import { Textarea } from '../components/inputs';
+import type { ExpressionFieldComponent, ExpressionInputShape } from './context';
+import type { ExpressionAnnotation } from './field-model';
+
+/**
+ * An expression-annotated field, rendered through the injected door: a
+ * multiline resting control with the door's own visual-editor button. The door
+ * brings its own label/description/error chrome (a11y-linked slots), so it is NOT
+ * wrapped in the form's `Field` component — the annotation's descriptor fields map
+ * onto the input-shape descriptor, and the form's per-field error feeds `error`.
+ *
+ * The door is rendered as an ELEMENT, never called as a function, so its hooks and
+ * state (editor open, worker handle) belong to it and survive re-renders of this
+ * field.
+ *
+ * It mounts inside a `Suspense` boundary because a host is free to inject a `lazy`
+ * door to keep the jq subgraph in a split chunk of ITS OWN bundle. The fallback
+ * paints the resting shell — label/description/error chrome around the current
+ * value in a read-only multiline control — so the field holds its layout and keeps
+ * the value visible while that chunk resolves, and the swap does not flash. A door
+ * injected eagerly never suspends and renders straight through.
+ *
+ * The form passes only the props the field owns; a jq door's `serverValidate`,
+ * `onEditorOpenChange`, and `compact` stay unwired, because no author-time
+ * validation endpoint applies to a schema-declared field, the hosts that render
+ * `SchemaForm` register no global shortcuts to mute, and every sibling field shows
+ * a visible label (the compact variant is for dense host rows).
+ */
+export function ExpressionField({
+  component: Door,
+  heading,
+  description,
+  error,
+  expression,
+  argName,
+  value,
+  onChange,
+}: {
+  component: ExpressionFieldComponent;
+  heading: string;
+  description: string | undefined;
+  error: string | undefined;
+  expression: ExpressionAnnotation;
+  argName: string;
+  value: string;
+  onChange: (value: string) => void;
+}): ReactNode {
+  // Memoised: the descriptor's identity feeds the door's own memoisation, so a
+  // fresh object each keystroke would defeat it.
+  const shape = useMemo(() => expressionShape(expression, argName), [expression, argName]);
+  return (
+    <Suspense
+      fallback={
+        <ExpressionFieldSkeleton
+          heading={heading}
+          description={description}
+          error={error}
+          value={value}
+        />
+      }
+    >
+      <Door
+        label={heading}
+        description={description}
+        error={error}
+        shape={shape}
+        multiline
+        value={value}
+        onChange={onChange}
+      />
+    </Suspense>
+  );
+}
+
+/**
+ * The resting shell shown while a lazily-injected door resolves. It mirrors the
+ * live door's footprint — the same label/description/error chrome wrapping a
+ * multiline control seeded with the current value — but the control is
+ * non-interactive (read-only, `aria-busy`) because there is nothing to edit yet. Matching the
+ * footprint is what keeps the Suspense swap from shifting layout or flashing.
+ */
+function ExpressionFieldSkeleton({
+  heading,
+  description,
+  error,
+  value,
+}: {
+  heading: string;
+  description: string | undefined;
+  error: string | undefined;
+  value: string;
+}): ReactNode {
+  return (
+    <Field label={heading} description={description} error={error}>
+      <Textarea value={value} readOnly aria-busy="true" />
+    </Field>
+  );
+}
+
+/**
+ * Map a classified expression annotation onto the door's input-shape descriptor.
+ * A bare annotation (`language` only) maps to NO descriptor — an undeclared shape
+ * is the honest rendering when the server said nothing about `.`. When any
+ * descriptor field is present, the required descriptor members the annotation
+ * omits fall back to neutral values rather than invented copy.
+ */
+function expressionShape(
+  expression: ExpressionAnnotation,
+  argName: string,
+): ExpressionInputShape | undefined {
+  const declared =
+    [
+      expression.label,
+      expression.blurb,
+      expression.keys,
+      expression.variables,
+      expression.returns,
+      expression.caveats,
+    ].some((field) => field !== undefined) || expression.hasSample;
+  if (!declared) return undefined;
+  return {
+    // Opaque, host-namespaced, stable per field (memoisation/telemetry only).
+    id: argName === '' ? 'tai42.schema-form' : `tai42.schema-form.${argName}`,
+    label: expression.label ?? 'input',
+    blurb: expression.blurb ?? '',
+    keys: expression.keys ?? [],
+    returns: expression.returns ?? '',
+    ...(expression.caveats === undefined ? {} : { caveats: expression.caveats }),
+    ...(expression.hasSample ? { sample: expression.sample } : {}),
+    ...(expression.variables === undefined
+      ? {}
+      : { variables: expression.variables.map(expressionVariable) }),
+  };
+}
+
+/** Map one classified annotation variable onto the door's variable descriptor. */
+function expressionVariable(
+  variable: NonNullable<ExpressionAnnotation['variables']>[number],
+): NonNullable<ExpressionInputShape['variables']>[number] {
+  return {
+    name: variable.name,
+    blurb: variable.blurb,
+    // The annotation glosses no sub-keys of a variable's value, so the door gets
+    // the variable's shape as untyped (empty keys).
+    keys: [],
+    ...(variable.hasSample ? { sample: variable.sample } : {}),
+  };
+}

package/src/schema-form/field-model.ts

@@ -70,10 +70,11 @@ export interface ExpressionAnnotationVariable {
 }
 
 /**
- * The `x-tai42-expression` annotation on a string schema: the server declares
- * that the field's value is authored in a pipeline expression language (only jq
- * today) and optionally describes what `.` is for that expression. The renderer
- * uses it to open the visual-editor door instead of a plain text box. The shape
+ * The `x-tai42-expression` annotation on a string or templated-text property: the
+ * server declares that the field's value is authored in a pipeline expression
+ * language (only jq today) and optionally describes what `.` is for that expression.
+ * The renderer uses it to open the visual-editor door instead of a plain text box
+ * (on a templated-text field, as its inline editor). The shape
  * mirrors jq-studio's input-shape descriptor WITHOUT importing it — classification
  * stays a pure schema concern; the renderer maps this onto a jq field declaration.
  */
@@ -165,6 +166,13 @@ export type FieldModel =
       readonly kind: 'object';
       readonly properties: readonly (readonly [string, JsonSchema])[];
       readonly required: ReadonlySet<string>;
+      /**
+       * The schema's own `properties` map, by identity. Every classification of one
+       * definition — through a `$ref`, a null-union or single-`allOf` wrapper, or an
+       * annotated property site — carries this same map, so a walker recognises a
+       * definition nested inside itself (a self-referencing schema) by it.
+       */
+      readonly shape: Readonly<Record<string, JsonSchema>>;
     }
   | {
       // A string-keyed map typed by `additionalProperties` (no fixed
@@ -174,10 +182,25 @@ export type FieldModel =
       readonly kind: 'record';
       readonly values: JsonSchema;
     }
+  | {
+      // A property typed as the platform's templated text (its schema carries
+      // `x-tai42-templated-text`): inline `content` or a stored template `id`, plus
+      // the render `kwargs`. The value is that object, authored as one field.
+      readonly kind: 'templated-text';
+      /** Present when the property's `x-tai42-expression` annotation declares its
+       *  inline content an expression: the inline editor is the expression door. */
+      readonly expression: ExpressionAnnotation | undefined;
+    }
   | {
       readonly kind: 'union';
       readonly variants: readonly UnionVariant[];
       readonly discriminator: string | undefined;
+      /**
+       * The schema's own `anyOf`/`oneOf` member list, by identity: every
+       * classification of one union carries this same list, so a field can tell
+       * whether it still draws the union it drew before.
+       */
+      readonly members: readonly JsonSchema[];
     }
   | {
       // A shape with no structured editor to build — a property-less object, a

package/src/schema-form/field-node.tsx

@@ -4,14 +4,16 @@
  * inline; every other kind delegates to a dedicated field component). Object,
  * array, and union renderers recurse back through here for their children.
  */
-import { memo, type ReactNode } from 'react';
+import { memo, type ReactNode, useContext } from 'react';
 
 import { Checkbox } from '../components/checkbox';
 import { Field } from '../components/field';
 import { NumberInput, TextInput } from '../components/inputs';
-import { ownValue } from '../guards';
+import { isRecord, ownValue } from '../guards';
 import { ArrayField } from './array-field';
 import { classifySchema } from './classify';
+import { CollapsedObjectField } from './collapsed-object-field';
+import { ExpandedShapesContext } from './context';
 import { EnumField } from './enum-field';
 import { FieldGroup } from './field-group';
 import type { FieldModel } from './field-model';
@@ -21,6 +23,7 @@ import { ObjectFields } from './object-fields';
 import { RecordField } from './record-field';
 import { scalarLabel } from './resolve';
 import { StringField } from './string-field';
+import { TemplatedField } from './templated-field';
 import type { FieldWords, JsonSchema, SchemaFormErrors } from './types';
 import { UnionField } from './union-field';
 
@@ -67,12 +70,15 @@ function labelText(explicit: string | undefined, label: string | undefined): str
  */
 function FieldNodeImpl(props: FieldNodeProps): ReactNode {
   const { root, value, onChange, path, required, idPrefix, errors } = props;
+  const expanded = useContext(ExpandedShapesContext);
   const classified = classifySchema(props.schema, root);
   const base = labelText(classified.title, props.label);
   const heading = props.markRequired === true && required ? `${base} *` : base;
   const { model, description } = classified;
   return renderField({
     model,
+    definition: classified.schema,
+    expanded,
     nullable: classified.nullable,
     heading,
     description,
@@ -93,6 +99,10 @@ function FieldNodeImpl(props: FieldNodeProps): ReactNode {
 /** The props the per-kind renderer needs, computed once by {@link FieldNodeImpl}. */
 interface RenderFieldArgs {
   readonly model: FieldModel;
+  /** The ref-resolved schema the model was classified from. */
+  readonly definition: JsonSchema;
+  /** The object shapes the fields above this one are drawing. */
+  readonly expanded: ReadonlySet<object>;
   readonly nullable: boolean;
   readonly heading: string;
   readonly description: string | undefined;
@@ -187,6 +197,19 @@ function renderField(args: RenderFieldArgs): ReactNode {
           onChange={onChange}
         />
       );
+    case 'templated-text':
+      return (
+        <TemplatedField
+          heading={heading}
+          description={description}
+          error={error}
+          expression={model.expression}
+          argName={path}
+          required={required}
+          value={value}
+          onChange={onChange}
+        />
+      );
     case 'multiselect':
       return (
         <MultiSelectField
@@ -228,10 +251,26 @@ function renderCompositeField(
         />
       );
     case 'object':
+      // A definition nested inside itself draws its fields only for a level the
+      // value holds; an absent level is one Add button, so the nesting stops at the data.
+      if (args.expanded.has(model.shape) && !isRecord(value)) {
+        return (
+          <CollapsedObjectField
+            heading={heading}
+            description={description}
+            error={error}
+            definition={args.definition}
+            shape={model.shape}
+            root={root}
+            onChange={onChange}
+          />
+        );
+      }
       return (
         <FieldGroup heading={heading} description={description} error={error} atRoot={path === ''}>
           <ObjectFields
             properties={model.properties}
+            shape={model.shape}
             requiredKeys={model.required}
             root={root}
             value={value}

package/src/schema-form/index.ts

@@ -35,12 +35,13 @@ export type {
   ExpressionFieldProps,
   ExpressionInputKey,
   ExpressionInputShape,
+  UseTemplatedTextCatalog,
 } from './context';
 export { RecordEntryRendererContext } from './context';
-export { ExpressionFieldContext } from './context';
+export { ExpressionFieldContext, TemplatedTextCatalogContext } from './context';
 export type { DateRangePair } from './date-range-field';
 export { dateRangePairs, fieldDrawingOrder } from './date-range-field';
-export { defaultValueForSchema } from './default-value';
+export { defaultValueForSchema, NoFiniteValueError } from './default-value';
 export { resolveRef } from './resolve';
 export type { CompletionProvider, SchemaFormProps } from './SchemaForm';
 export { SchemaForm } from './SchemaForm';

package/src/schema-form/object-fields.tsx

@@ -1,12 +1,14 @@
 /**
  * Renders the property fields of an object schema, one {@link FieldNode} per
- * property. Each child's edits are folded back into an immutable copy of the
+ * property, and records the object's `shape` as expanded for every field below it
+ * (see {@link ExpandedShapesContext}). Each child's edits are folded back into an immutable copy of the
  * object value; an optional `skip` omits a property (used for a union's
  * discriminator tag, which the variant picker owns).
  */
-import type { ReactNode } from 'react';
+import { type ReactNode, useContext, useMemo } from 'react';
 
 import { ownValue } from '../guards';
+import { ExpandedShapesContext } from './context';
 import { DateRangeField, dateRangePairs, fieldDrawingOrder } from './date-range-field';
 import { FieldNode } from './field-node';
 import { useKeyedCallbacks } from './keyed-callbacks';
@@ -19,6 +21,7 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 
 export function ObjectFields({
   properties,
+  shape,
   requiredKeys,
   root,
   value,
@@ -31,6 +34,8 @@ export function ObjectFields({
   fieldWording,
 }: {
   properties: readonly (readonly [string, JsonSchema])[];
+  /** The object model's `shape`, recorded as expanded for the fields below. */
+  shape: object;
   requiredKeys: ReadonlySet<string>;
   root: JsonSchema;
   value: unknown;
@@ -50,6 +55,8 @@ export function ObjectFields({
   fieldWording?: Readonly<Record<string, FieldWords>>;
 }): ReactNode {
   const obj = isPlainObject(value) ? value : {};
+  const above = useContext(ExpandedShapesContext);
+  const expanded = useMemo(() => new Set(above).add(shape), [above, shape]);
   const changeFor = useKeyedCallbacks<string, unknown>(
     (name, next) => {
       onChange(setKey(obj, name, next));
@@ -96,7 +103,7 @@ export function ObjectFields({
   const timeOf = (name: string | undefined, propSchema: JsonSchema | undefined): ReactNode =>
     name === undefined || propSchema === undefined ? null : fieldOf(name, propSchema);
   return (
-    <>
+    <ExpandedShapesContext.Provider value={expanded}>
       {drawn.map((name) => {
         const propSchema = schemaByName.get(name);
         if (propSchema === undefined) return null;
@@ -127,7 +134,7 @@ export function ObjectFields({
         }
         return fieldOf(name, propSchema);
       })}
-    </>
+    </ExpandedShapesContext.Provider>
   );
 }
 

package/src/schema-form/record-field.tsx

@@ -23,6 +23,7 @@ import { defaultValueForSchema } from './default-value';
 import { FieldGroup } from './field-group';
 import { FieldNode } from './field-node';
 import { useKeyedCallbacks } from './keyed-callbacks';
+import { useSeedingAction } from './seeding-action';
 import type { JsonSchema, SchemaFormErrors } from './types';
 
 interface Row {
@@ -126,8 +127,10 @@ export function RecordField({
     setValue,
     rows.map((row) => row.id),
   );
+  const add = useSeedingAction(values);
   const addRow = (): void => {
-    commit([...rows, { id: nextId.current++, key: '', value: newEntryValue(values, root) }]);
+    const entry = add.seed(() => newEntryValue(values, root));
+    if (entry.ok) commit([...rows, { id: nextId.current++, key: '', value: entry.value }]);
   };
   const removeRow = (id: number): void => {
     commit(rows.filter((row) => row.id !== id));
@@ -137,7 +140,12 @@ export function RecordField({
   const summary = keyFaultSummary(blankRowIds.size, duplicateRowIds.size);
 
   return (
-    <FieldGroup heading={heading} description={description} error={error} atRoot={false}>
+    <FieldGroup
+      heading={heading}
+      description={description}
+      error={add.failure ?? error}
+      atRoot={false}
+    >
       {rows.length === 0 ? <span className="tai-field-hint">No entries</span> : null}
       {summary !== undefined ? (
         <span role="alert" className="tai-field-error">

package/src/schema-form/seeding-action.ts

@@ -0,0 +1,44 @@
+/**
+ * The state behind a control that seeds a fresh value on a user action: a list's
+ * "Add item", a map's "Add entry", a nested level's "Add", and the union variant
+ * picker's switch. Seeding throws {@link NoFiniteValueError} when the schema admits no
+ * finite value, and a throw inside an event handler never reaches an error boundary,
+ * so that failure is logged and kept as the field's error message. Only the seed runs
+ * inside the catch, and only that error type is caught: the caller commits the value
+ * (its `onChange`) outside it, so every other error propagates as thrown.
+ *
+ * A failure belongs to the `subject` it was raised for (the schema identity the
+ * caller seeds from): when the same field later draws a different subject, the
+ * failure is no longer reported. The next successful seed clears it.
+ */
+import { useState } from 'react';
+
+import { NoFiniteValueError } from './default-value';
+
+/** A seed attempt's outcome: the seeded value, or a failure now shown on the field. */
+export type SeedOutcome = { readonly ok: true; readonly value: unknown } | { readonly ok: false };
+
+export interface SeedingAction {
+  /** The failure message for the current subject, or `undefined` when there is none. */
+  readonly failure: string | undefined;
+  /** Run `make`, the seeding step; a {@link NoFiniteValueError} becomes the failure. */
+  readonly seed: (make: () => unknown) => SeedOutcome;
+}
+
+export function useSeedingAction(subject: object): SeedingAction {
+  const [failed, setFailed] = useState<{ subject: object; message: string } | undefined>(undefined);
+  const seed = (make: () => unknown): SeedOutcome => {
+    let value: unknown;
+    try {
+      value = make();
+    } catch (error) {
+      if (!(error instanceof NoFiniteValueError)) throw error;
+      console.error('SchemaForm: seeding a new value failed', error);
+      setFailed({ subject, message: error.message });
+      return { ok: false };
+    }
+    setFailed(undefined);
+    return { ok: true, value };
+  };
+  return { failure: failed?.subject === subject ? failed.message : undefined, seed };
+}