@flikk/ui 1.0.0-beta.31 → 1.0.0-beta.32

package/dist/components/generative/GenerativeView.js

@@ -6,7 +6,63 @@ import { defaultRegistry, CardShell } from './registry.js';
 import { applyResolvers } from './resolvers.js';
 import { SKELETON_NODE } from './streaming.js';
 import { bindActionProps } from './actions.js';
+import { getFieldBinding } from './fieldBinding.js';
+import { useFormScope } from './formScope.js';
 
+/**
+ * Which props each curated field component actually DECLARES, and may
+ * therefore be handed. NOT every FIELD_BINDINGS entry supports all three —
+ * hand-verified against each component's OWN Props interface, not a sibling's
+ * (mirrors the same "don't infer from the name" caution as `fieldBinding.ts`'s
+ * own table):
+ *   - Select/Combobox/Switch/Slider/TimePicker/InputTag accept `state` (for
+ *     border styling) but declare NO `errorMessage` prop at all.
+ *   - Checkbox accepts `state` but NOT `errorMessage` — `errorMessage` exists
+ *     only on the separate `CheckboxGroupProps` (`Checkbox.Group`), not on
+ *     `CheckboxProps` (what's actually registered/rendered here). Checkbox.tsx
+ *     destructures known props and spreads the rest onto the native `<input>`
+ *     (Checkbox.tsx:35,115), so this one is a real, reproducible DOM leak if
+ *     gotten wrong, not a hypothetical — verified by reverting this row and
+ *     confirming GenerativeView.test.tsx's Checkbox pinning test fails.
+ *   - Rating has none of the three: it's a Core rating widget, not a
+ *     FORMS_STANDARDS component.
+ * Forwarding a prop a component doesn't declare reaches the DOM as an
+ * unrecognized attribute (most of these spread unknown rest props onto
+ * their root element) and React logs it — see GenerativeView.test.tsx's
+ * "does not forward errorMessage/state to a control that doesn't declare
+ * them" tests (Switch and Checkbox each get their own).
+ *
+ * 🔴 `required` is on this table for FORWARDING ONLY. It is separately an
+ * ENGINE-SEMANTIC prop: `node.props.required` is read below to register the
+ * field's required-ness with the FormScope, which is what blocks submit —
+ * that happens for all 13 regardless of this table, and is why all 13 must
+ * declare `required` in the generated schema (see `REQUIRED_PROP` in
+ * packages/mcp/scripts/generativeManifest.ts). The four that decline it here
+ * (InputOTP/InputCounter/InputTag/Rating) extend
+ * `HTMLAttributes<HTMLDivElement>` and declare no `required` of their own, so
+ * forwarding would paint an invalid `required` attribute onto a `<div>` and
+ * buy nothing. Their required-ness is still enforced, and surfaced to the
+ * user by `FormShell`'s error summary rather than a per-field indicator.
+ * 🔴 The forwarding strip below is UNCONDITIONAL — it runs for every node,
+ * not only ones with a `name`/binding. A `required` prop with no `name` at
+ * all never registers with the scope, but it still rides along in `hydrated`
+ * and would otherwise reach a component's root element untouched.
+ */
+const FIELD_PROP_SUPPORT = {
+    Input: { state: true, errorMessage: true, required: true },
+    Textarea: { state: true, errorMessage: true, required: true },
+    Select: { state: true, errorMessage: false, required: true },
+    Combobox: { state: true, errorMessage: false, required: true },
+    Checkbox: { state: true, errorMessage: false, required: true },
+    Switch: { state: true, errorMessage: false, required: true },
+    Slider: { state: true, errorMessage: false, required: true },
+    InputOTP: { state: true, errorMessage: true, required: false },
+    TimePicker: { state: true, errorMessage: false, required: true },
+    InputDate: { state: true, errorMessage: true, required: true },
+    InputCounter: { state: true, errorMessage: true, required: false },
+    InputTag: { state: true, errorMessage: false, required: false },
+    Rating: { state: false, errorMessage: false, required: false },
+};
 const placeholderStyle = "rounded-lg border border-dashed border-[var(--color-border-secondary)] " +
     "bg-[var(--color-surface-sunken)] p-3 text-xs text-[var(--color-text-muted)]";
 /** The model asked for a component we didn't register — render, don't throw. */
@@ -43,23 +99,56 @@ class NodeBoundary extends React__default.Component {
         return this.props.children;
     }
 }
-function NodeRenderer({ node, registry, inShell, dispatch, }) {
-    var _a, _b, _c;
+function NodeRenderer({ node, registry, inShell, dispatch, path, values, defaultValues, onFormValuesChange, }) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    const scope = useFormScope();
+    const fieldName = typeof ((_a = node.props) === null || _a === void 0 ? void 0 : _a.name) === "string" ? node.props.name : undefined;
+    const binding = fieldName ? getFieldBinding(node.component) : undefined;
+    const specSeed = binding
+        ? ((_c = (_b = node.props) === null || _b === void 0 ? void 0 : _b[binding.valueProp]) !== null && _c !== void 0 ? _c : (binding.defaultValueProp
+            ? (_d = node.props) === null || _d === void 0 ? void 0 : _d[binding.defaultValueProp]
+            : undefined))
+        : undefined;
+    // Registration is an effect, not a render side effect: a field that
+    // disappears when the model re-emits a different spec must stop
+    // contributing its stale value to the next submit. The seed (spec value,
+    // or the binding's "empty") is handed to the scope rather than committed
+    // here via `setValue` — `formScope`'s `register` commits it internally
+    // without notifying `onValuesChange`, since mounting a field isn't a
+    // user-driven change (see formScope.tsx).
+    const required = ((_e = node.props) === null || _e === void 0 ? void 0 : _e.required) === true;
+    // The field's own label, handed to the scope purely so `FormShell`'s error
+    // summary can name a blocked field the way the user sees it rather than by
+    // its submission key ("Email address", not "email_address").
+    const fieldLabel = typeof ((_f = node.props) === null || _f === void 0 ? void 0 : _f.label) === "string" ? node.props.label : undefined;
+    React__default.useEffect(() => {
+        if (!scope || !fieldName || !binding)
+            return;
+        scope.register(fieldName, { required, binding, label: fieldLabel, seed: specSeed !== null && specSeed !== void 0 ? specSeed : binding.empty });
+        return () => scope.unregister(fieldName);
+        // `specSeed` is intentionally omitted from the deps: it's read straight
+        // from `node.props` for this same field/binding pair, so it's already
+        // implied by `fieldName`/`binding` being unchanged — and `register`
+        // itself only ever applies a seed once (it no-ops once the scope holds
+        // a value for the name), so re-deriving it on an unrelated re-render
+        // would be a no-op anyway.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [scope, fieldName, binding, required, fieldLabel]);
     if (node.component === SKELETON_NODE)
         return jsx(SkeletonPlaceholder, { props: node.props });
     const entry = registry.components[node.component];
     if (!entry)
         return jsx(UnknownNode, { name: node.component });
-    const hydrated = applyResolvers(((_a = node.props) !== null && _a !== void 0 ? _a : {}), registry.resolvers, { icons: registry.icons, node });
+    const hydrated = applyResolvers(((_g = node.props) !== null && _g !== void 0 ? _g : {}), registry.resolvers, { icons: registry.icons, node });
     const isContainer = entry.kind === "container";
-    if (process.env.NODE_ENV !== "production" && !isContainer && ((_b = node.children) === null || _b === void 0 ? void 0 : _b.length)) {
+    if (process.env.NODE_ENV !== "production" && !isContainer && ((_h = node.children) === null || _h === void 0 ? void 0 : _h.length)) {
         console.warn(`[GenerativeView]: "${node.component}" is not a container — its children are ignored`);
     }
     const childInShell = entry.providesShell ? true : inShell;
-    const children = isContainer && ((_c = node.children) === null || _c === void 0 ? void 0 : _c.length)
+    const children = isContainer && ((_j = node.children) === null || _j === void 0 ? void 0 : _j.length)
         ? node.children.map((child, index) => {
-            var _a;
-            return (jsx(NodeBoundary, { name: child.component, children: jsx(NodeRenderer, { node: child, registry: registry, inShell: childInShell, dispatch: dispatch }) }, (_a = child.id) !== null && _a !== void 0 ? _a : index));
+            var _a, _b;
+            return (jsx(NodeBoundary, { name: child.component, children: jsx(NodeRenderer, { node: child, registry: registry, inShell: childInShell, dispatch: dispatch, path: `${path}.${(_a = child.id) !== null && _a !== void 0 ? _a : index}`, values: values, defaultValues: defaultValues, onFormValuesChange: onFormValuesChange }) }, (_b = child.id) !== null && _b !== void 0 ? _b : index));
         })
         : undefined;
     // Shell-wrapped leaves: title/subtitle belong to the shell, not the component.
@@ -78,6 +167,89 @@ function NodeRenderer({ node, registry, inShell, dispatch, }) {
         componentProps = bound.props;
         unboundClick = bound.unboundClick;
     }
+    // `required` is forwarded ONLY to a component whose FIELD_PROP_SUPPORT
+    // entry declares it — those need it for their own native `required`
+    // attribute and their FormLabel asterisk/"(required)" indicator (WCAG
+    // 3.3.2 — a required field must be identifiable before submit, not just
+    // after a rejected one). `FormShell` renders `<form noValidate>`, so the
+    // native attribute never interferes with `scope.submit()`'s own required
+    // check. This strip is UNCONDITIONAL — it must run whether or not this
+    // node has a `name`/`binding` at all: a node can carry `required` with no
+    // `name` (the field never registers, but `required` still rode along in
+    // `hydrated`) or a `name` for a component with no binding, and either way
+    // the component's own root element (e.g. Rating's `<div role="slider">`)
+    // must never receive an attribute it doesn't declare. Enforcement is
+    // unaffected either way: `node.props.required` was already read above and
+    // registered with the scope regardless of whether it survives forwarding.
+    if (!((_k = FIELD_PROP_SUPPORT[node.component]) === null || _k === void 0 ? void 0 : _k.required))
+        delete componentProps.required;
+    if (scope && fieldName && binding) {
+        const held = scope.getValue(fieldName);
+        const value = held !== undefined ? held : specSeed;
+        const existingChange = componentProps[binding.changeProp];
+        const support = FIELD_PROP_SUPPORT[node.component];
+        const next = { ...componentProps };
+        delete next.name; // consumed for registration; never forwarded
+        if (binding.defaultValueProp)
+            delete next[binding.defaultValueProp];
+        next[binding.valueProp] = value !== null && value !== void 0 ? value : binding.empty;
+        next[binding.changeProp] = (...args) => {
+            scope.setValue(fieldName, args[0]);
+            existingChange === null || existingChange === void 0 ? void 0 : existingChange(...args);
+        };
+        if (scope.errors[fieldName]) {
+            if (support === null || support === void 0 ? void 0 : support.state)
+                next.state = "invalid";
+            if (support === null || support === void 0 ? void 0 : support.errorMessage)
+                next.errorMessage = (_l = next.errorMessage) !== null && _l !== void 0 ? _l : scope.errors[fieldName];
+        }
+        componentProps = next;
+    }
+    else if (fieldName && binding) {
+        // A named FIELD-BINDING component outside a Form still renders; `name`
+        // is simply inert there. Strip it so it never reaches the DOM. A
+        // component with NO binding (e.g. `Avatar.name`, a person's display
+        // name) never entered this branch's condition for the wrong reason —
+        // `binding` here confirms it actually IS a field component, so its
+        // `name` prop is left alone and forwarded untouched.
+        const { name: _unused, ...rest } = componentProps;
+        componentProps = rest;
+    }
+    // Design spec §3.5: a `Button` inside a Form that declares no `actions` of
+    // its own IS that form's submit button. Core `Button` renders `type="button"`
+    // ahead of its rest-prop spread (Button.tsx:170), so injecting `type` here
+    // overrides it — and `FormShell`'s
+    // `button[type="submit"]:not([data-generative-auto-submit])` probe then finds
+    // it and suppresses the auto-rendered one, leaving exactly one button.
+    // `type` is deliberately NOT in the generative schema: the rule is the
+    // engine's to apply, not a knob the model can set (or forget to set).
+    // A Button WITH actions keeps its own click behaviour and never submits.
+    const declaresOwnActions = !!node.actions && Object.keys(node.actions).length > 0;
+    if (node.component === "Button" && scope && !declaresOwnActions) {
+        componentProps = { ...componentProps, type: "submit" };
+    }
+    if (entry.isForm) {
+        const formId = (_m = node.id) !== null && _m !== void 0 ? _m : `form-${path}`;
+        componentProps = {
+            ...componentProps,
+            formId,
+            // `Object.hasOwn`, not `values?.[formId]`: `formId` comes from the spec's
+            // own `node.id`. `validate()` now rejects unsafe ids (see validate.ts),
+            // but `GenerativeView` also accepts RAW specs, where a plain-object bag
+            // would resolve `id: "toString"` to an inherited function instead of
+            // `undefined` — and hand `FormShell` a function as its `values` prop.
+            values: values && Object.hasOwn(values, formId) ? values[formId] : undefined,
+            defaultValues: defaultValues && Object.hasOwn(defaultValues, formId) ? defaultValues[formId] : undefined,
+            onValuesChange: (formValues) => onFormValuesChange === null || onFormValuesChange === void 0 ? void 0 : onFormValuesChange(formId, formValues),
+            onSubmit: (formValues) => {
+                var _a;
+                const descriptor = (_a = node.actions) === null || _a === void 0 ? void 0 : _a.submit;
+                if (!descriptor || !dispatch)
+                    return;
+                dispatch(descriptor, { component: "Form", nodeId: node.id, values: formValues });
+            },
+        };
+    }
     const Component = entry.component;
     let inner;
     if (entry.render)
@@ -106,12 +278,32 @@ function NodeRenderer({ node, registry, inShell, dispatch, }) {
  * Render a serializable UINode spec with the given registry.
  * Render-only in P1 — streaming (P3) and action dispatch (P4) layer on top.
  */
-function GenerativeView({ spec, registry = defaultRegistry, onAction, className, }) {
+function GenerativeView({ spec, registry = defaultRegistry, onAction, className, values, defaultValues, onValuesChange, }) {
     const nodes = Array.isArray(spec) ? spec : [spec];
+    const isControlled = values !== undefined;
+    // `onValuesChange` is documented to fire with the COMPLETE next values bag,
+    // across every form in the spec. Controlled mode gets that for free: the
+    // consumer's `values` is the live bag, so merging onto it is correct.
+    // Uncontrolled mode does not — `defaultValues` is a static seed that never
+    // reflects what the user has since typed, so merging each form's callback
+    // onto it erased every OTHER form's live state (type in form A, then form B,
+    // and A's value vanished from the payload). This ref carries the last bag we
+    // emitted so the merge base stays current between forms.
+    const lastEmittedRef = React__default.useRef(defaultValues !== null && defaultValues !== void 0 ? defaultValues : {});
+    const handleFormValuesChange = React__default.useCallback((formId, formValues) => {
+        const base = isControlled ? (values !== null && values !== void 0 ? values : {}) : lastEmittedRef.current;
+        // A computed key in an object literal is a data-property definition, not
+        // an assignment, so a hostile `formId` cannot reach a prototype setter
+        // here even on a raw (unvalidated) spec.
+        const next = { ...base, [formId]: formValues };
+        if (!isControlled)
+            lastEmittedRef.current = next;
+        onValuesChange === null || onValuesChange === void 0 ? void 0 : onValuesChange(next);
+    }, [isControlled, values, onValuesChange]);
     return (jsx("div", { className: className, children: nodes.map((node, index) => {
-            var _a;
-            return (jsx(NodeBoundary, { name: node.component, children: jsx(NodeRenderer, { node: node, registry: registry, inShell: false, dispatch: onAction }) }, (_a = node.id) !== null && _a !== void 0 ? _a : index));
+            var _a, _b;
+            return (jsx(NodeBoundary, { name: node.component, children: jsx(NodeRenderer, { node: node, registry: registry, inShell: false, dispatch: onAction, path: `${(_a = node.id) !== null && _a !== void 0 ? _a : index}`, values: values, defaultValues: defaultValues, onFormValuesChange: handleFormValuesChange }) }, (_b = node.id) !== null && _b !== void 0 ? _b : index));
         }) }));
 }
 
-export { GenerativeView };
+export { FIELD_PROP_SUPPORT, GenerativeView };

package/dist/components/generative/actions.d.ts

@@ -7,6 +7,11 @@ export interface ActionContext {
     nodeId?: string;
     /** Serializable callback payload (e.g. the clicked Table row). Never a DOM event. */
     data?: JSONValue;
+    /**
+     * Present only on a Form's submit action: every registered field value,
+     * collected in one bag. Built with a null prototype.
+     */
+    values?: Record<string, JSONValue>;
 }
 /** Consumer handler: first arg is the EXACT descriptor from the spec. */
 export type ActionHandler = (action: ActionDescriptor, context: ActionContext) => void;

package/dist/components/generative/ai-sdk/index.d.ts

@@ -0,0 +1 @@
+export { useGenerativeChat, type UseGenerativeChatOptions, type UseGenerativeChatReturn, } from "./useGenerativeChat";

package/dist/components/generative/ai-sdk/index.js

@@ -0,0 +1 @@
+export { useGenerativeChat } from './useGenerativeChat.js';

package/dist/components/generative/ai-sdk/useGenerativeChat.d.ts

@@ -0,0 +1,52 @@
+import { useChat } from "@ai-sdk/react";
+import { ActionContext } from "../actions";
+import { ActionDescriptor, UISpec } from "../types";
+export interface UseGenerativeChatOptions {
+    /** Chat endpoint. Passed straight to the AI SDK's transport. @default "/api/chat" */
+    api?: string;
+    /** Tool name the model calls to render UI. @default GENERATIVE_TOOL.name */
+    toolName?: string;
+}
+export interface UseGenerativeChatReturn {
+    /** The validated spec from the most recent render tool call. Empty array while nothing has streamed in yet. */
+    spec: UISpec;
+    /** Route this into <GenerativeView onAction={…} /> to close the loop. */
+    onAction: (action: ActionDescriptor, ctx: ActionContext) => void;
+    /**
+     * True while the render tool's arguments are still arriving — either the
+     * matched tool-call part's own `state` is `"input-streaming"`, or the chat
+     * as a whole is still streaming (`chat.status === "streaming"`, e.g. the
+     * tool call hasn't started yet but a response is in flight). False at rest
+     * (no messages, nothing in flight) and once the matched part has settled.
+     *
+     * NOT derived from `useGenerativeStream`'s own `complete` flag — see the
+     * note on `useGenerativeChat` below for why that signal is unusable here.
+     */
+    streaming: boolean;
+    messages: ReturnType<typeof useChat>["messages"];
+    sendMessage: ReturnType<typeof useChat>["sendMessage"];
+    status: ReturnType<typeof useChat>["status"];
+}
+/**
+ * Wires the AI SDK's chat loop to the generative engine: feeds the render
+ * tool's arguments through `useGenerativeStream`, validates the result, and
+ * routes user interactions back to the model as a tool result.
+ *
+ * 🔴 Skeleton placeholders do NOT apply on this path. `useGenerativeStream` /
+ * `parseStreamingSpec` detect "still arriving" content by finding an unclosed
+ * bracket in raw, truncated JSON text — that's how `GenerativeView` gets to
+ * render `__skeleton__` placeholders mid-stream. But `@ai-sdk/react` never
+ * exposes that raw text: a streaming tool-call part's `input` is already a
+ * parsed `DeepPartial` snapshot, and `JSON.stringify`-ing it (the only way to
+ * satisfy `useGenerativeStream`'s string contract) always yields syntactically
+ * COMPLETE JSON, at every step. So `pending` is always `0` here, and content
+ * pops in whole as fields complete rather than reserving skeleton space for
+ * fields that haven't started. This is a real, accepted trade-off of the
+ * installed SDK's surface — not a bug — which is also why `streaming` below
+ * is derived from the tool-call part's own `state` / `chat.status`, and NOT
+ * from `useGenerativeStream`'s `complete` flag (which is always `true` here
+ * for the same reason `pending` is always `0`).
+ *
+ * Requires the optional peers `ai` and `@ai-sdk/react`.
+ */
+export declare function useGenerativeChat({ api, toolName, }?: UseGenerativeChatOptions): UseGenerativeChatReturn;

package/dist/components/generative/ai-sdk/useGenerativeChat.js

@@ -0,0 +1,73 @@
+"use client";
+import React__default from 'react';
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+import { GENERATIVE_TOOL } from '../tools.js';
+import { toToolResult } from '../toToolResult.js';
+import { useGenerativeStream } from '../useGenerativeStream.js';
+import { validate } from '../validate.js';
+
+/**
+ * Wires the AI SDK's chat loop to the generative engine: feeds the render
+ * tool's arguments through `useGenerativeStream`, validates the result, and
+ * routes user interactions back to the model as a tool result.
+ *
+ * 🔴 Skeleton placeholders do NOT apply on this path. `useGenerativeStream` /
+ * `parseStreamingSpec` detect "still arriving" content by finding an unclosed
+ * bracket in raw, truncated JSON text — that's how `GenerativeView` gets to
+ * render `__skeleton__` placeholders mid-stream. But `@ai-sdk/react` never
+ * exposes that raw text: a streaming tool-call part's `input` is already a
+ * parsed `DeepPartial` snapshot, and `JSON.stringify`-ing it (the only way to
+ * satisfy `useGenerativeStream`'s string contract) always yields syntactically
+ * COMPLETE JSON, at every step. So `pending` is always `0` here, and content
+ * pops in whole as fields complete rather than reserving skeleton space for
+ * fields that haven't started. This is a real, accepted trade-off of the
+ * installed SDK's surface — not a bug — which is also why `streaming` below
+ * is derived from the tool-call part's own `state` / `chat.status`, and NOT
+ * from `useGenerativeStream`'s `complete` flag (which is always `true` here
+ * for the same reason `pending` is always `0`).
+ *
+ * Requires the optional peers `ai` and `@ai-sdk/react`.
+ */
+function useGenerativeChat({ api = "/api/chat", toolName = GENERATIVE_TOOL.name, } = {}) {
+    const transport = React__default.useMemo(() => new DefaultChatTransport({ api }), [api]);
+    const chat = useChat({ transport });
+    // Most recent render tool call across the transcript, streaming or settled.
+    const match = React__default.useMemo(() => {
+        var _a, _b;
+        const staticType = `tool-${toolName}`;
+        for (let i = chat.messages.length - 1; i >= 0; i--) {
+            const parts = (_a = chat.messages[i].parts) !== null && _a !== void 0 ? _a : [];
+            for (let j = parts.length - 1; j >= 0; j--) {
+                const part = parts[j];
+                const isMatch = part.type === staticType || (part.type === "dynamic-tool" && part.toolName === toolName);
+                if (isMatch) {
+                    return {
+                        text: typeof part.input === "string" ? part.input : JSON.stringify((_b = part.input) !== null && _b !== void 0 ? _b : {}),
+                        isStreaming: part.state === "input-streaming",
+                    };
+                }
+            }
+        }
+        return { text: "", isStreaming: false };
+    }, [chat.messages, toolName]);
+    const stream = useGenerativeStream({ text: match.text });
+    const spec = React__default.useMemo(() => {
+        if (!stream.spec)
+            return [];
+        return validate(stream.spec).spec;
+    }, [stream.spec]);
+    const onAction = React__default.useCallback((action, ctx) => {
+        chat.sendMessage({ text: JSON.stringify(toToolResult(action, ctx)) });
+    }, [chat.sendMessage]);
+    return {
+        spec,
+        onAction,
+        streaming: match.isStreaming || chat.status === "streaming",
+        messages: chat.messages,
+        sendMessage: chat.sendMessage,
+        status: chat.status,
+    };
+}
+
+export { useGenerativeChat };

package/dist/components/generative/ai-sdk/useGenerativeChat.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/generative/fieldBinding.d.ts

@@ -0,0 +1,31 @@
+import { JSONValue } from "./types";
+/**
+ * How one curated control exposes its value to the form scope.
+ *
+ * Hand-verified against each component's `.types.ts` — these contracts are NOT
+ * uniform and must never be inferred from the component name:
+ *   - `Checkbox.value` / `Switch.value` are the HTML *value attribute*
+ *     (Checkbox.types.ts:23 declares it REQUIRED); the state is `checked`.
+ *   - `Input`/`Textarea` fire `onValueChange`; everything else fires `onChange`.
+ *   - `Input`/`Textarea` inherit `value`/`defaultValue` from the native
+ *     HTML attribute interfaces rather than declaring them.
+ */
+export interface FieldBinding {
+    /** Prop carrying the field's current value in controlled use. */
+    valueProp: string;
+    /** Prop carrying the seed value in uncontrolled use, when the control has one. */
+    defaultValueProp?: string;
+    /** Callback prop fired on change. Its first argument is the new value. */
+    changeProp: string;
+    /** The value this control considers "blank" for the `required` check. */
+    empty: JSONValue;
+}
+export declare const FIELD_BINDINGS: Record<string, FieldBinding>;
+/**
+ * Look up a binding. Uses `Object.hasOwn` so inherited Object.prototype members
+ * ("constructor", "toString") resolve to undefined rather than a function —
+ * the same guard `validate.ts`'s `safeLookup` applies.
+ */
+export declare function getFieldBinding(component: string): FieldBinding | undefined;
+/** Is this value "blank" for the purposes of a `required` check? */
+export declare function isEmptyValue(binding: FieldBinding, value: JSONValue | undefined): boolean;

package/dist/components/generative/fieldBinding.js

@@ -0,0 +1,33 @@
+const FIELD_BINDINGS = {
+    Input: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onValueChange", empty: "" },
+    Textarea: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onValueChange", empty: "" },
+    Select: { valueProp: "value", changeProp: "onChange", empty: "" },
+    Combobox: { valueProp: "value", changeProp: "onChange", empty: "" },
+    Checkbox: { valueProp: "checked", defaultValueProp: "defaultChecked", changeProp: "onChange", empty: false },
+    Switch: { valueProp: "checked", defaultValueProp: "defaultChecked", changeProp: "onChange", empty: false },
+    Slider: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onChange", empty: null },
+    InputOTP: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onChange", empty: "" },
+    TimePicker: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onChange", empty: "" },
+    InputDate: { valueProp: "value", changeProp: "onChange", empty: "" },
+    InputCounter: { valueProp: "value", changeProp: "onChange", empty: null },
+    InputTag: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onChange", empty: [] },
+    Rating: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onChange", empty: 0 },
+};
+/**
+ * Look up a binding. Uses `Object.hasOwn` so inherited Object.prototype members
+ * ("constructor", "toString") resolve to undefined rather than a function —
+ * the same guard `validate.ts`'s `safeLookup` applies.
+ */
+function getFieldBinding(component) {
+    return Object.hasOwn(FIELD_BINDINGS, component) ? FIELD_BINDINGS[component] : undefined;
+}
+/** Is this value "blank" for the purposes of a `required` check? */
+function isEmptyValue(binding, value) {
+    if (value === undefined || value === null)
+        return true;
+    if (Array.isArray(binding.empty))
+        return Array.isArray(value) && value.length === 0;
+    return value === binding.empty;
+}
+
+export { FIELD_BINDINGS, getFieldBinding, isEmptyValue };

package/dist/components/generative/fieldBinding.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/generative/formScope.d.ts

@@ -0,0 +1,71 @@
+import React from "react";
+import { FieldBinding } from "./fieldBinding";
+import { JSONValue } from "./types";
+/** One form's field values, keyed by field name. */
+export type FormValues = Record<string, JSONValue>;
+/** Every form in a spec, keyed by form id. */
+export type GenerativeValues = Record<string, FormValues>;
+export declare const REQUIRED_MESSAGE = "This field is required.";
+interface FieldRegistration {
+    required?: boolean;
+    binding: FieldBinding;
+    /**
+     * The field's visible label, if it has one. Used only by `FormShell`'s error
+     * summary, so a blocked field is named the way the user sees it rather than
+     * by its submission key.
+     */
+    label?: string;
+    /**
+     * The field's initial value (spec seed or the binding's "empty"), committed
+     * to the scope on registration if nothing is held for this name yet. Kept
+     * separate from `setValue` so mounting a field doesn't fire `onValuesChange`
+     * before any user interaction — seeding is not a user-driven change.
+     */
+    seed?: JSONValue;
+}
+export interface FormScopeValue {
+    formId: string;
+    getValue(name: string): JSONValue | undefined;
+    setValue(name: string, value: JSONValue): void;
+    /**
+     * The registered label for a field, if any. Read at render time by the
+     * error summary; safe because the scope's identity changes whenever
+     * `errors` does, so the summary always re-reads after a blocked submit.
+     */
+    getLabel(name: string): string | undefined;
+    register(name: string, opts: FieldRegistration): void;
+    /** Drop a field that has unmounted, so its stale value never submits. */
+    unregister(name: string): void;
+    errors: Record<string, string>;
+    submit(): void;
+}
+export declare const FormScopeContext: React.Context<FormScopeValue | undefined>;
+/** Nearest enclosing form scope, or undefined outside a Form. */
+export declare function useFormScope(): FormScopeValue | undefined;
+export interface UseFormScopeStateOptions {
+    formId: string;
+    /** Controlled values for THIS form. Presence switches to controlled mode. */
+    values?: FormValues;
+    /** Uncontrolled seed for THIS form. */
+    defaultValues?: FormValues;
+    onValuesChange?: (values: FormValues) => void;
+    onSubmit: (values: FormValues) => void;
+    /**
+     * Called with EVERY invalid field name, in registration order, when submit
+     * is blocked. Deliberately the whole list rather than just the first: the
+     * per-field invalid treatment reaches only some controls (six of the
+     * thirteen render no focusable primary element at all — per-field focus
+     * isn't viable without a core-component change, a deferred follow-up, see
+     * FormShell.tsx — and Switch/Rating render no error text at all), so
+     * `FormShell` needs the full set to build the form-level error summary
+     * that covers all of them.
+     */
+    onInvalid?: (invalidNames: string[]) => void;
+}
+/**
+ * The form state machine. Controlled when `values` is passed; otherwise it owns
+ * state seeded from `defaultValues`. Mode is derived per render and never
+ * stored (CLAUDE.md §9).
+ */
+export declare function useFormScopeState({ formId, values, defaultValues, onValuesChange, onSubmit, onInvalid, }: UseFormScopeStateOptions): FormScopeValue;
+export {};