@voltro/client 0.54.0 → 0.56.0

package/dist/index.d.ts

@@ -16,6 +16,7 @@ import { RpcGroup } from '@effect/rpc';
 import { Schema } from 'effect';
 import { Stream } from 'effect';
 import { SubscriptionEvent } from '@voltro/protocol';
+import { TargetRelations } from '@voltro/protocol';
 import { UIEvent as UIEvent_2 } from 'react';
 import { WorkflowDomainEventRow } from '@voltro/protocol';
 import { WorkflowEventDeliveryRow } from '@voltro/protocol';
@@ -315,6 +316,12 @@ export declare interface AutoApplyTarget {
      *  nested-array item when `path` is set. Typed to the item, not the output.
      *  2nd arg is the optimistic id (insert) or the current item (update). */
     readonly shapeItem?: ((input: Record<string, unknown>, currentOrOptimisticId: unknown) => Record<string, unknown>) | undefined;
+    /** Declared many-to-many relations (`{ inputField: { junction, anchorColumn,
+     *  targetColumn } }`). Drives JUNCTION auto-optimistic: entries sourced on the
+     *  junction table get their link rows for this anchor reconciled against
+     *  `input[inputField]` immediately, instead of waiting for the server delta
+     *  while every scalar field of the same form has already flipped. */
+    readonly relations?: TargetRelations | undefined;
 }
 
 /**
@@ -822,6 +829,9 @@ export declare const deriveEntityAdmins: (manifest: CapabilityManifest) => Reado
  *  outside a browser. Primary subtag only (`de-AT` → `de`). */
 export declare const documentLocale: () => string;
 
+/** The empty value — what an unfilled rich-text field holds. */
+export declare const emptyRichTextDocument: RichTextDocument;
+
 export declare const enqueueEntry: (queue: Outbox, id: string, tag: string, input: unknown) => Outbox;
 
 /**
@@ -1101,6 +1111,28 @@ export declare interface FormBinding<Input, Output> {
     readonly focusFirstInvalid: () => void;
 }
 
+/**
+ * Make one binding reachable to every field component below, so
+ * {@link useFormField} can find it WITHOUT the binding being threaded through
+ * each one as a prop.
+ *
+ * That thread is what stops an incremental migration. A deployment moving a
+ * hundred-plus forms keeps its own field context and swaps engines per form
+ * with a single prop; `useFormField(form, path)` would have forced the binding
+ * down to every one of their ~30 field components at once, so they adopted the
+ * binding and declined the narrow subscription — the exact optimisation they
+ * had the most forms to gain from.
+ *
+ *     <FormBindingProvider binding={form}>{children}</FormBindingProvider>
+ *     // deeper: const f = useFormField('address.city')
+ *
+ * `<AutoForm>` mounts one for you.
+ */
+export declare const FormBindingProvider: (props: {
+    readonly binding: FormBinding<never, never> | FormBinding<Record<string, unknown>, unknown>;
+    readonly children?: ReactNode;
+}) => ReactElement;
+
 /**
  * Convert posted form entries into the input object the mutation's schema
  * decodes — the shape `validateFields` (and the RPC payload) expects.
@@ -1251,15 +1283,40 @@ export declare interface FrameworkRuntimes {
     readonly get: (name: string) => ApiHandle;
     /** Enumerate the names of currently-installed apis (for debug). */
     readonly names: ReadonlyArray<string>;
+    /**
+     * "Something in this tree needs `apiName`."
+     *
+     * Under `web.api.connect: 'lazy'` the provider does not open a socket until
+     * this is called, so a page that reads no data never opens one. Under the
+     * default `'eager'` it is a no-op — every api connects at mount, as before.
+     *
+     * It exists because the alternative was worse in a specific, measured way:
+     * `interactive: 'full'` is the DEFAULT render mode, and the client opened a
+     * WebSocket on every such page whether or not it subscribed. A pre-rendered
+     * documentation page with no data at all opened one (measured in a real
+     * browser: 0 sockets on `interactive: 'none'` / `'islands'`, one on `'full'`).
+     * And an open socket keeps a dormancy-managed instance awake — `isIdleNow`
+     * returns false while `connectedClients() > 0` — so one browser tab on a
+     * pricing page prevented scale-to-zero indefinitely.
+     *
+     * Optional so a foreign host embedding `FrameworkRuntimesContext` by hand
+     * keeps working; absent means "already connected", which is the safe reading.
+     */
+    readonly demand?: (apiName: string) => void;
 }
 
 export declare const FrameworkRuntimesContext: Context<FrameworkRuntimes | null>;
 
-export declare const FrameworkRuntimesProvider: ({ apis, children, }: FrameworkRuntimesProviderProps) => ReactNode;
+export declare const FrameworkRuntimesProvider: ({ apis, children, demand, }: FrameworkRuntimesProviderProps) => ReactNode;
 
 export declare interface FrameworkRuntimesProviderProps {
     readonly apis: ReadonlyMap<string, ApiHandle>;
     readonly children: ReactNode;
+    /** Passed straight through to the context so `useFrameworkApi` can say that
+     *  something in the tree needs an api. The web boot supplies it under
+     *  `web.api.connect: 'lazy'`; a foreign host may omit it, which reads as
+     *  "already connected". */
+    readonly demand?: (apiName: string) => void;
 }
 
 /** Browser-safe unique idempotency key: prefer `crypto.randomUUID`, fall back to
@@ -1301,6 +1358,20 @@ export declare const getMutations: () => ReadonlyArray<MutationEvent>;
  */
 export declare const globalContext: <T>(key: string, initial: T) => Context<T>;
 
+/** True when `value` is structurally a rich-text document (a cheap render-side
+ *  guard; the decode remains the boundary). */
+export declare const isRichTextDocument: (value: unknown) => value is RichTextDocument;
+
+/**
+ * Is this `href` safe to put in a document?
+ *
+ * ALLOWLIST, never a denylist — a denylist is a list of the bypasses somebody
+ * already thought of. Accepted: absolute `http(s)`, `mailto:`, a same-document
+ * fragment, and a root-relative path. Everything else, `javascript:` and
+ * `data:` included, is refused.
+ */
+export declare const isSafeHref: (href: string) => boolean;
+
 /** Is this the framework's `Unauthenticated`? Matched on `_tag`, the wire
  *  contract, rather than on an instance — the error crosses a package boundary
  *  and may be re-created by the decoder. */
@@ -1586,6 +1657,13 @@ export declare interface OutboxPersistence {
 
 export declare type OutboxStatus = 'pending' | 'sent' | 'failed' | 'conflict';
 
+/**
+ * Parse the widget's markdown-subset SOURCE into a document. Total: every input
+ * yields a valid document, because everything unrecognised is text. Not a
+ * security boundary — see the header; the decode is.
+ */
+export declare const parseRichText: (source: string) => RichTextDocument;
+
 /** Provide the current subject's scopes to `useCan`. Mount it once high in the
  *  tree, fed by your session subscription so it updates on role changes. */
 export declare function PermissionProvider(props: PermissionProviderProps): ReactNode;
@@ -1848,6 +1926,15 @@ export declare interface RecordState<R> {
     readonly error: unknown | undefined;
 }
 
+/**
+ * Make an api's client descriptors visible to a SERVER render.
+ *
+ * Called by the boot paths before rendering a page; harmless in the browser,
+ * where the real handle carries them. Idempotent — descriptors are static per
+ * api, so last write wins.
+ */
+export declare const registerSsrDescriptors: (apiName: string, descriptors: Readonly<Record<string, ClientDescriptor>>) => void;
+
 /**
  * The entries to replay, in FIFO order, UP TO (not including) the first
  * conflict — a conflicted write blocks everything after it (causality). Sent
@@ -1872,6 +1959,9 @@ export declare const _resetFrameworkRuntimesWarning: () => void;
 /** Drop all applied client-side seeds. Tests only. */
 export declare const resetPreloadSeeds: () => void;
 
+/** Test-only: forget every registration. */
+export declare const _resetSsrDescriptors: () => void;
+
 /** Test helper: forget every defined store. NEVER call this in app code. */
 export declare const resetStoreRegistryForTests: () => void;
 
@@ -1939,6 +2029,33 @@ export declare interface ResourceCansResult {
     readonly allowedIds: ReadonlyArray<string>;
 }
 
+/**
+ * Keep only the keys the input schema DECLARES.
+ *
+ * The two submit paths had drifted apart on this, and the server sided with
+ * neither: `formDataToInput` (the no-JS path) documents "unknown keys are
+ * dropped", while the JS path validated with a decode that IGNORES excess
+ * properties and then sent the object UNCHANGED. Since 0.37 the server
+ * refuses an undeclared input field — so a form carrying anything beyond the
+ * mutation's input (a display toggle, a repeat control, a file held before
+ * upload, which is nearly every real form) passed client validation and was
+ * rejected on the wire, with a message pointing at no field. Measured by a
+ * deployment with `renderFormBinding`, our own harness.
+ *
+ * `toInput` is the seam for this and stays the recommended one — but it only
+ * protects a form that HAS one, and the failure mode of not having one was a
+ * green tick followed by a server refusal. Dropping matches the no-JS path,
+ * so the two submits now agree; a genuinely mistyped key still surfaces,
+ * because the field it was meant to be is then missing and fails validation.
+ *
+ * Non-struct schemas (a scalar input) are returned untouched — there is no
+ * declared key set to restrict against.
+ */
+export declare const restrictToSchema: (schema: Schema.Schema.Any, input: unknown) => {
+    readonly input: unknown;
+    readonly dropped: ReadonlyArray<string>;
+};
+
 export declare interface ResumableAgentStreamControls<E> extends ResumableAgentStreamState<E> {
     /** Begin a run. `input` MUST carry the resume key (`streamId`) so reconnects
      *  target the same server-side log; `fromSeq` is injected by the hook. */
@@ -2004,6 +2121,339 @@ export declare type ResumableStreamMethod<E> = (payload: unknown) => Stream.Stre
 
 export declare type ResumableStreamStatus = 'idle' | 'streaming' | 'reconnecting' | 'done' | 'error';
 
+/** Marks a text run may carry. Closed set — a mark is a NAME, never a style
+ *  string or attribute bag, so nothing here can express behaviour. */
+export declare const RICH_TEXT_MARKS: readonly ["bold", "italic", "code", "strike"];
+
+/** Upper bound on the node count of one document. A refusal, not a hang: an
+ *  unbounded tree is a decode bomb on a server thread. */
+export declare const RICH_TEXT_MAX_NODES = 5000;
+
+export declare type RichTextBlock = typeof RichTextBlock_2.Type;
+
+declare const RichTextBlock_2: Schema.Union<[Schema.Struct<{
+    type: Schema.Literal<["paragraph"]>;
+    content: Schema.Array$<Schema.Union<[Schema.Struct<{
+        type: Schema.Literal<["text"]>;
+        text: typeof Schema.String;
+        marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["link"]>;
+        href: Schema.filter<typeof Schema.String>;
+        content: Schema.Array$<Schema.Struct<{
+            type: Schema.Literal<["text"]>;
+            text: typeof Schema.String;
+            marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+        }>>;
+    }>]>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["heading"]>;
+    level: Schema.Literal<[1, 2, 3]>;
+    content: Schema.Array$<Schema.Union<[Schema.Struct<{
+        type: Schema.Literal<["text"]>;
+        text: typeof Schema.String;
+        marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["link"]>;
+        href: Schema.filter<typeof Schema.String>;
+        content: Schema.Array$<Schema.Struct<{
+            type: Schema.Literal<["text"]>;
+            text: typeof Schema.String;
+            marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+        }>>;
+    }>]>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["blockquote"]>;
+    content: Schema.Array$<Schema.Union<[Schema.Struct<{
+        type: Schema.Literal<["text"]>;
+        text: typeof Schema.String;
+        marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["link"]>;
+        href: Schema.filter<typeof Schema.String>;
+        content: Schema.Array$<Schema.Struct<{
+            type: Schema.Literal<["text"]>;
+            text: typeof Schema.String;
+            marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+        }>>;
+    }>]>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["bulletList"]>;
+    content: Schema.Array$<Schema.Struct<{
+        type: Schema.Literal<["listItem"]>;
+        content: Schema.Array$<Schema.Union<[Schema.Struct<{
+            type: Schema.Literal<["text"]>;
+            text: typeof Schema.String;
+            marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+        }>, Schema.Struct<{
+            type: Schema.Literal<["link"]>;
+            href: Schema.filter<typeof Schema.String>;
+            content: Schema.Array$<Schema.Struct<{
+                type: Schema.Literal<["text"]>;
+                text: typeof Schema.String;
+                marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+            }>>;
+        }>]>>;
+    }>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["orderedList"]>;
+    content: Schema.Array$<Schema.Struct<{
+        type: Schema.Literal<["listItem"]>;
+        content: Schema.Array$<Schema.Union<[Schema.Struct<{
+            type: Schema.Literal<["text"]>;
+            text: typeof Schema.String;
+            marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+        }>, Schema.Struct<{
+            type: Schema.Literal<["link"]>;
+            href: Schema.filter<typeof Schema.String>;
+            content: Schema.Array$<Schema.Struct<{
+                type: Schema.Literal<["text"]>;
+                text: typeof Schema.String;
+                marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+            }>>;
+        }>]>>;
+    }>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["codeBlock"]>;
+    text: typeof Schema.String;
+}>]>;
+
+declare type RichTextBlock = typeof RichTextBlock_2.Type;
+
+/**
+ * The rich-text field's value. Use it directly in a mutation input:
+ *
+ *     Schema.Struct({ id: Schema.String, body: RichTextDocument })
+ *
+ * It carries the `rich-text` widget annotation, so `<AutoForm>` renders the
+ * editor with no extra `formField({ widget })` call — and the decode that
+ * validates the mutation input IS the sanitizing boundary (see the header).
+ */
+export declare const RichTextDocument: Schema.refine<{
+    readonly type: "doc";
+    readonly content: readonly ({
+        readonly type: "paragraph";
+        readonly content: readonly ({
+            readonly text: string;
+            readonly type: "text";
+            readonly marks?: readonly ("bold" | "strike" | "code" | "italic")[] | undefined;
+        } | {
+            readonly type: "link";
+            readonly href: string;
+            readonly content: readonly {
+                readonly text: string;
+                readonly type: "text";
+                readonly marks?: readonly ("bold" | "strike" | "code" | "italic")[] | undefined;
+            }[];
+        })[];
+    } | {
+        readonly type: "heading";
+        readonly level: 1 | 2 | 3;
+        readonly content: readonly ({
+            readonly text: string;
+            readonly type: "text";
+            readonly marks?: readonly ("bold" | "strike" | "code" | "italic")[] | undefined;
+        } | {
+            readonly type: "link";
+            readonly href: string;
+            readonly content: readonly {
+                readonly text: string;
+                readonly type: "text";
+                readonly marks?: readonly ("bold" | "strike" | "code" | "italic")[] | undefined;
+            }[];
+        })[];
+    } | {
+        readonly type: "blockquote";
+        readonly content: readonly ({
+            readonly text: string;
+            readonly type: "text";
+            readonly marks?: readonly ("bold" | "strike" | "code" | "italic")[] | undefined;
+        } | {
+            readonly type: "link";
+            readonly href: string;
+            readonly content: readonly {
+                readonly text: string;
+                readonly type: "text";
+                readonly marks?: readonly ("bold" | "strike" | "code" | "italic")[] | undefined;
+            }[];
+        })[];
+    } | {
+        readonly type: "bulletList";
+        readonly content: readonly {
+            readonly type: "listItem";
+            readonly content: readonly ({
+                readonly text: string;
+                readonly type: "text";
+                readonly marks?: readonly ("bold" | "strike" | "code" | "italic")[] | undefined;
+            } | {
+                readonly type: "link";
+                readonly href: string;
+                readonly content: readonly {
+                    readonly text: string;
+                    readonly type: "text";
+                    readonly marks?: readonly ("bold" | "strike" | "code" | "italic")[] | undefined;
+                }[];
+            })[];
+        }[];
+    } | {
+        readonly type: "orderedList";
+        readonly content: readonly {
+            readonly type: "listItem";
+            readonly content: readonly ({
+                readonly text: string;
+                readonly type: "text";
+                readonly marks?: readonly ("bold" | "strike" | "code" | "italic")[] | undefined;
+            } | {
+                readonly type: "link";
+                readonly href: string;
+                readonly content: readonly {
+                    readonly text: string;
+                    readonly type: "text";
+                    readonly marks?: readonly ("bold" | "strike" | "code" | "italic")[] | undefined;
+                }[];
+            })[];
+        }[];
+    } | {
+        readonly text: string;
+        readonly type: "codeBlock";
+    })[];
+}, Schema.Struct<{
+    type: Schema.Literal<["doc"]>;
+    content: Schema.Array$<Schema.Union<[Schema.Struct<{
+        type: Schema.Literal<["paragraph"]>;
+        content: Schema.Array$<Schema.Union<[Schema.Struct<{
+            type: Schema.Literal<["text"]>;
+            text: typeof Schema.String;
+            marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+        }>, Schema.Struct<{
+            type: Schema.Literal<["link"]>;
+            href: Schema.filter<typeof Schema.String>;
+            content: Schema.Array$<Schema.Struct<{
+                type: Schema.Literal<["text"]>;
+                text: typeof Schema.String;
+                marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+            }>>;
+        }>]>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["heading"]>;
+        level: Schema.Literal<[1, 2, 3]>;
+        content: Schema.Array$<Schema.Union<[Schema.Struct<{
+            type: Schema.Literal<["text"]>;
+            text: typeof Schema.String;
+            marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+        }>, Schema.Struct<{
+            type: Schema.Literal<["link"]>;
+            href: Schema.filter<typeof Schema.String>;
+            content: Schema.Array$<Schema.Struct<{
+                type: Schema.Literal<["text"]>;
+                text: typeof Schema.String;
+                marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+            }>>;
+        }>]>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["blockquote"]>;
+        content: Schema.Array$<Schema.Union<[Schema.Struct<{
+            type: Schema.Literal<["text"]>;
+            text: typeof Schema.String;
+            marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+        }>, Schema.Struct<{
+            type: Schema.Literal<["link"]>;
+            href: Schema.filter<typeof Schema.String>;
+            content: Schema.Array$<Schema.Struct<{
+                type: Schema.Literal<["text"]>;
+                text: typeof Schema.String;
+                marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+            }>>;
+        }>]>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["bulletList"]>;
+        content: Schema.Array$<Schema.Struct<{
+            type: Schema.Literal<["listItem"]>;
+            content: Schema.Array$<Schema.Union<[Schema.Struct<{
+                type: Schema.Literal<["text"]>;
+                text: typeof Schema.String;
+                marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+            }>, Schema.Struct<{
+                type: Schema.Literal<["link"]>;
+                href: Schema.filter<typeof Schema.String>;
+                content: Schema.Array$<Schema.Struct<{
+                    type: Schema.Literal<["text"]>;
+                    text: typeof Schema.String;
+                    marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+                }>>;
+            }>]>>;
+        }>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["orderedList"]>;
+        content: Schema.Array$<Schema.Struct<{
+            type: Schema.Literal<["listItem"]>;
+            content: Schema.Array$<Schema.Union<[Schema.Struct<{
+                type: Schema.Literal<["text"]>;
+                text: typeof Schema.String;
+                marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+            }>, Schema.Struct<{
+                type: Schema.Literal<["link"]>;
+                href: Schema.filter<typeof Schema.String>;
+                content: Schema.Array$<Schema.Struct<{
+                    type: Schema.Literal<["text"]>;
+                    text: typeof Schema.String;
+                    marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+                }>>;
+            }>]>>;
+        }>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["codeBlock"]>;
+        text: typeof Schema.String;
+    }>]>>;
+}>>;
+
+export declare type RichTextDocument = typeof RichTextDocument.Type;
+
+export declare type RichTextInline = typeof RichTextInline_2.Type;
+
+declare const RichTextInline_2: Schema.Union<[Schema.Struct<{
+    type: Schema.Literal<["text"]>;
+    text: typeof Schema.String;
+    marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["link"]>;
+    href: Schema.filter<typeof Schema.String>;
+    content: Schema.Array$<Schema.Struct<{
+        type: Schema.Literal<["text"]>;
+        text: typeof Schema.String;
+        marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+    }>>;
+}>]>;
+
+declare type RichTextInline = typeof RichTextInline_2.Type;
+
+export declare type RichTextListItem = typeof RichTextListItem_2.Type;
+
+declare const RichTextListItem_2: Schema.Struct<{
+    type: Schema.Literal<["listItem"]>;
+    content: Schema.Array$<Schema.Union<[Schema.Struct<{
+        type: Schema.Literal<["text"]>;
+        text: typeof Schema.String;
+        marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["link"]>;
+        href: Schema.filter<typeof Schema.String>;
+        content: Schema.Array$<Schema.Struct<{
+            type: Schema.Literal<["text"]>;
+            text: typeof Schema.String;
+            marks: Schema.optional<Schema.Array$<Schema.Literal<["bold", "italic", "code", "strike"]>>>;
+        }>>;
+    }>]>>;
+}>;
+
+declare type RichTextListItem = typeof RichTextListItem_2.Type;
+
+export declare type RichTextMark = (typeof RICH_TEXT_MARKS)[number];
+
+/** The document's text, with no markers — for search indexing, excerpts and
+ *  plain-text notification bodies. */
+export declare const richTextToPlainText: (value: unknown) => string;
+
 /** Pure: map source rows → `{ value, label }` options. Falls back to the value
  *  when the label field is absent. Exported for direct testing + reuse. */
 export declare const rowsToOptions: (rows: ReadonlyArray<Record<string, unknown>>, labelField: string, valueField: string) => ReadonlyArray<FieldOption>;
@@ -2157,6 +2607,10 @@ export declare type SequenceResult<Ctx> = {
     }>;
 };
 
+/** Render a document back to the widget's source form. Accepts anything —
+ *  a field that has never been filled holds `undefined`. */
+export declare const serializeRichText: (value: unknown) => string;
+
 export declare const ServerRequestContext: Context<ServerRequestContextValue | null>;
 
 export declare interface ServerRequestContextValue {
@@ -2255,6 +2709,9 @@ export declare const sourceValues: (sources: Record<string, unknown>) => Readonl
 
 export declare const ssrClientProxy: unknown;
 
+/** Registered SSR descriptors for `apiName`, if any. */
+export declare const ssrDescriptorsFor: (apiName: string) => Readonly<Record<string, ClientDescriptor>> | undefined;
+
 export declare const ssrStubHandle: ApiHandle;
 
 /**
@@ -2828,9 +3285,13 @@ export declare interface SubscriptionMeta {
      *  screen. Those still reach the api's error bus — subscribe with
      *  `useOnRpcError` for connection-level UX.
      *
-     *  A cold-start failure leaves `loading` TRUE (there is still nothing to
-     *  render), so a component that branches on `loading` alone renders a skeleton
-     *  forever. Check `error` to break out of it. */
+     *  A cold-start failure is its own STATE: `loading` is `false`, `failed` is
+     *  `true`, and this field is non-optional there (see
+     *  {@link SubscriptionFailed}). It used to leave `loading` true — this
+     *  comment predicted the consequence, a deployment hit it, and the fix was
+     *  to stop making `loading` mean two things rather than to keep warning
+     *  about it. Branching on `loading` alone no longer renders a skeleton
+     *  forever. */
     readonly error: unknown | undefined;
     /** Number of live optimistic patches currently applied. Useful for
      *  rendering a faint "syncing…" indicator when > 0. */
@@ -3424,6 +3885,9 @@ export declare interface UseEventOptions {
 
 export declare const useFormBinding: <Input extends Record<string, unknown> = Record<string, unknown>, Output = unknown>(apiName: string, mutationTag: string, options: UseFormBindingOptions<Input>) => FormBinding<Input, Output>;
 
+/** The enclosing binding, if a {@link FormBindingProvider} is mounted. */
+export declare const useFormBindingContext: () => FormBinding<Record<string, unknown>, unknown> | undefined;
+
 export declare interface UseFormBindingOptions<Input> {
     /** The mutation's input `Schema`. Optional: when omitted it is resolved from
      *  the mounted client descriptor (`descriptors[tag].input`, the capability
@@ -3478,6 +3942,17 @@ export declare interface UseFormBindingOptions<Input> {
     }) => Promise<unknown>;
     /** Ran after a successful submit with the mutation's output. */
     readonly onSuccess?: (output: unknown) => void;
+    /**
+     * Ran when a submit failed with something NO field can carry — a store
+     * refusal, a constraint violation, a failure raised by a composed
+     * `onSubmit`. The same value lands in `state.submitError`, so a banner
+     * bound to that needs nothing here; this is for a toast or a report sink.
+     *
+     * `submit()` does not reject for these. It resolves `undefined` and the
+     * failure is state, because a form calls `submit()` from a handler that
+     * cannot await it — a rejection there has nowhere to go but the console.
+     */
+    readonly onError?: (error: unknown) => void;
     /**
      * Async field checks `submit` must wait for. Pass each field's
      * `useAsyncValidation` result under its field path:
@@ -3517,7 +3992,9 @@ export declare interface UseFormBindingOptions<Input> {
  *       return <input id={f.a11y.id} value={String(f.value ?? '')} onChange={(e) => f.setValue(e.target.value)} onBlur={f.onBlur} />
  *     }
  */
-export declare const useFormField: (binding: FormBinding<never, never> | FormBinding<Record<string, unknown>, unknown>, path: string) => FormFieldHandle;
+export declare function useFormField(path: string): FormFieldHandle;
+
+export declare function useFormField(binding: FormBinding<never, never> | FormBinding<Record<string, unknown>, unknown>, path: string): FormFieldHandle;
 
 /**
  * The failed-no-JS-POST payload for ONE form, or `undefined`.
@@ -3835,7 +4312,7 @@ export declare const validationStatus: (args: {
 /** The default widget kinds the framework can render from a schema. `'custom'`
  *  means "no default widget" — the field needs a render-prop (a nested object,
  *  an array of objects, or a multi-branch union). Mirrors innovation/01's set. */
-export declare type WidgetKind = 'text' | 'textarea' | 'number' | 'checkbox' | 'switch' | 'select' | 'radio' | 'async-select' | 'multi-select' | 'date' | 'datetime' | 'daterange' | 'file' | 'hidden' | 'array' | 'reference' | 'custom';
+export declare type WidgetKind = 'text' | 'textarea' | 'rich-text' | 'number' | 'checkbox' | 'switch' | 'select' | 'radio' | 'async-select' | 'multi-select' | 'date' | 'datetime' | 'daterange' | 'file' | 'hidden' | 'array' | 'reference' | 'custom';
 
 export declare interface WindowedSubscriptionState<Row> {
     /** The in-window rows (live). */