ngx-json-render 0.2.1 → 0.4.0

package/types/ngx-json-render.d.ts

@@ -1,10 +1,11 @@
 import * as _json_render_core from '@json-render/core';
-import { ResolvedAction, ActionHandler, ActionBinding, Catalog, InferCatalogActions, InferActionParams, StateModel, InferCatalogComponents, UIElement, Spec, StateStore, ValidationFunction, ComputedFunction, DirectiveDefinition, ActionConfirm, DirectiveRegistry, ValidationResult, ValidationConfig, JsonPatch, FlatElement } from '@json-render/core';
-export { ActionBinding, ActionHandler, JsonPatch, Spec, StateModel, StateStore, UIElement, VisibilityCondition, createStateStore, nestedToFlat } from '@json-render/core';
+import { ResolvedAction, ActionHandler, ActionBinding, SpecIssue, Spec, Catalog, InferCatalogActions, InferActionParams, StateModel, InferCatalogComponents, UIElement, StateStore, ValidationFunction, ComputedFunction, DirectiveDefinition, ActionConfirm, DirectiveRegistry, ValidationResult, ValidationConfig, JsonPatch, FlatElement } from '@json-render/core';
+export { ActionBinding, ActionHandler, JsonPatch, Spec, SpecIssue, StateModel, StateStore, UIElement, VisibilityCondition, autoFixSpec, createStateStore, formatSpecIssues, nestedToFlat, validateSpec } from '@json-render/core';
 import * as zod from 'zod';
 import * as zod_v4_core from 'zod/v4/core';
 import * as _angular_core from '@angular/core';
 import { Signal, Type, InjectionToken } from '@angular/core';
+import * as ngx_json_render from 'ngx-json-render';
 
 interface PendingConfirmation {
     action: ResolvedAction;
@@ -12,13 +13,15 @@ interface PendingConfirmation {
     resolve: () => void;
     reject: () => void;
 }
+/** True for the rejection produced by cancelling a confirmation dialog. */
+declare function isActionCancelled(error: unknown): boolean;
 /**
  * Action dispatcher of a `<json-render>` subtree.
  *
  * Executes {@link ActionBinding}s: built-in actions (`setState`, `pushState`,
- * `removeState`, `push`, `pop`, `validateForm`) are handled internally;
- * everything else is routed to the host-provided `handlers` (or the
- * `onAction` catch-all), honoring `confirm`, `onSuccess`, and `onError`.
+ * `removeState`, `push`, `pop`, `validateForm`, `submitForm`) are handled
+ * internally; everything else is routed to the host-provided `handlers` (or
+ * the `onAction` catch-all), honoring `confirm`, `onSuccess`, and `onError`.
  */
 declare class JsonRenderActionsService {
     private readonly root;
@@ -41,6 +44,15 @@ declare class JsonRenderActionsService {
     confirm(): void;
     /** Cancel the pending confirmation dialog. */
     cancel(): void;
+    /**
+     * Validate every registered field and write `{ valid, errors }` to the
+     * action's `statePath` (default `/formValidation`). Returns null when there
+     * is no validation service to ask.
+     *
+     * Shared by `validateForm` and `submitForm`: the two must report the same
+     * thing about the same form, and one implementation is how that stays true.
+     */
+    private checkForm;
     private lookupHandler;
     private runHandler;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<JsonRenderActionsService, never>;
@@ -57,6 +69,162 @@ declare function injectAction(binding: ActionBinding): {
     isLoading: Signal<boolean>;
 };
 
+/**
+ * Caps on what a spec is allowed to cost the browser.
+ *
+ * A spec is attacker-shaped input: whatever produced one chose its own size,
+ * its own nesting and — through `repeat` — its own array lengths. These are
+ * the three of those the renderer can enforce for you.
+ *
+ * Every field is opt-in and unset means unlimited. There are no defaults
+ * because no single number is right for every catalog, and a default would
+ * change what an existing app renders the moment it upgraded.
+ *
+ * Limits are enforced whenever they are set, whatever `validate` is: a number
+ * the app chose is a control, not advice. What "enforced" means differs by
+ * limit, because the limits differ in kind — see each field.
+ *
+ * @example
+ * ```html
+ * <json-render
+ *   [spec]="spec()"
+ *   [registry]="registry"
+ *   [renderLimits]="{ maxElements: 500, maxDepth: 16, maxRepeatItems: 200 }"
+ * />
+ * ```
+ */
+interface RenderLimits {
+    /**
+     * Most elements a spec may contain. A spec over the cap does not render at
+     * all: element count is a property of the whole spec, and there is no
+     * meaningful "first 500 elements" of a graph.
+     */
+    readonly maxElements?: number;
+    /**
+     * Deepest the render tree may nest, counting the root as 1. An element
+     * below the cap does not render, and neither does anything under it; what
+     * fits still renders. Reported as an error, so `validate="strict"` refuses
+     * the spec outright rather than truncating it.
+     *
+     * A capped element does not act either — its `watch` stays unwired, so it
+     * cannot dispatch actions from behind the cap.
+     */
+    readonly maxDepth?: number;
+    /**
+     * Most items one `repeat` may expand. The surplus items do not render.
+     *
+     * Enforced at render time only: `repeat` iterates a live state array, so no
+     * amount of inspecting the spec can predict how long it will be. Nested
+     * repeats multiply, so this is a per-repeat cap, not a total.
+     */
+    readonly maxRepeatItems?: number;
+}
+/**
+ * Issue codes this package reports, widening core's set with the ones only a
+ * renderer can find.
+ *
+ * - `cycle` — an element renders itself against the same data, which cannot
+ *   terminate. A tree that recurses into its items is not this.
+ * - `too_deep` / `too_many_elements` — a {@link RenderLimits} cap was passed.
+ * - `unknown_component` — a `type` the catalog does not define.
+ * - `invalid_props` — the catalog's own schema rejected part of the spec.
+ */
+type SpecCheckIssueCode = SpecIssue['code'] | 'cycle' | 'too_deep' | 'too_many_elements' | 'unknown_component' | 'invalid_props';
+/**
+ * A problem found in a spec. Core's {@link SpecIssue} widened with the codes
+ * above, so a {@link SpecIssue} is always one of these.
+ */
+interface SpecCheckIssue {
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly elementKey?: string;
+    readonly code: SpecCheckIssueCode;
+}
+/**
+ * The part of a json-render `Catalog` the check needs.
+ *
+ * Structural on purpose: a real catalog satisfies it, and the renderer stays
+ * free of any dependency on the schema library behind `validate`.
+ */
+interface SpecCatalog {
+    /** Component type names the catalog defines. */
+    readonly componentNames: readonly string[];
+    /** Check a spec against the catalog's own schema. */
+    validate(spec: unknown): {
+        readonly success: boolean;
+        readonly error?: unknown;
+    };
+}
+
+/**
+ * How much a spec has to be trusted.
+ *
+ * - `off` — render whatever arrives. The default, and what every version
+ *   before this one did.
+ * - `warn` — check the spec, apply the lossless fixes, report what is left,
+ *   render it anyway.
+ * - `strict` — the same check, but an error means the spec does not render.
+ *
+ * This governs *reporting* and strict refusal. {@link RenderLimits} are a
+ * separate axis: a limit the app set is enforced in every mode, including
+ * `off`.
+ */
+type SpecValidationMode = 'off' | 'warn' | 'strict';
+/** Everything {@link checkSpec} needs beyond the spec and the mode. */
+interface SpecCheckOptions {
+    /** Caps on the spec's size, enforced whatever the mode. */
+    readonly limits?: RenderLimits | null;
+    /**
+     * The catalog the spec was generated for. Given one, the check also reports
+     * component types the catalog does not define and props its own schema
+     * rejects — the half of "is this spec renderable" that structure alone
+     * cannot answer.
+     */
+    readonly catalog?: SpecCatalog | null;
+}
+/** What {@link checkSpec} found, and the spec that should render. */
+interface SpecCheck {
+    /**
+     * The spec to render: the input with lossless fixes applied, or the input
+     * untouched when validation is off.
+     */
+    readonly spec: Spec | null;
+    /** Structural, limit and catalog issues left after the fixes. */
+    readonly issues: readonly SpecCheckIssue[];
+    /** Descriptions of the fixes that were applied. */
+    readonly fixes: readonly string[];
+    /** Whether an issue of `error` severity survived. */
+    readonly hasErrors: boolean;
+    /**
+     * Whether the spec is refused outright, in every mode, for breaching an
+     * enforced limit. Distinct from {@link hasErrors}, which only stops a spec
+     * under `strict`.
+     */
+    readonly blocked: boolean;
+}
+/**
+ * Check a spec the way `validate` and `renderLimits` ask for.
+ *
+ * Only lossless fixes are applied — `visible`, `on` and `repeat` that a model
+ * put inside `props`, which the renderer would otherwise ignore, moved back
+ * where they belong. The lossy ones prune content, and core's own guidance is
+ * to re-prompt rather than accept that; a renderer that silently deleted
+ * elements would be the worse failure.
+ *
+ * Note what is *not* here: cycles are broken as the tree renders, whatever
+ * this returns, because a spec that never stops rendering is a crash rather
+ * than an opinion about quality. This reports them so an app can see them.
+ */
+declare function checkSpec(spec: Spec | null, mode: SpecValidationMode, options?: SpecCheckOptions): SpecCheck;
+/**
+ * Render issues as one indented block, errors and warnings alike.
+ *
+ * Core's `formatSpecIssues` drops warnings and only accepts core's own issue
+ * codes, so it cannot describe what this package reports. Use this instead
+ * when showing `issues()` to a developer.
+ */
+declare function formatSpecCheckIssues(issues: readonly SpecCheckIssue[]): string;
+
 /**
  * State setter function for updating application state.
  * Matches the `SetState` contract of the other json-render renderers
@@ -281,6 +449,40 @@ declare class JsonRenderer {
     readonly loading: _angular_core.InputSignal<boolean>;
     /** Fallback component for unknown types. */
     readonly fallback: _angular_core.InputSignal<RegistryEntry | Type<unknown> | null>;
+    /**
+     * Whether to check the spec's structure before rendering it, and what to do
+     * about what turns up. Off by default.
+     *
+     * `'warn'` reports the issues and renders anyway; `'strict'` renders nothing
+     * when the spec has errors. Both first apply the lossless fixes — `visible`,
+     * `on` and `repeat` misplaced inside `props` are moved back to the element,
+     * where they take effect instead of being ignored.
+     *
+     * The check is skipped while `loading` is true: a spec that is still
+     * arriving is expected to reference children that have not streamed in yet.
+     */
+    readonly validate: _angular_core.InputSignal<SpecValidationMode>;
+    /**
+     * Caps on what the spec may cost the browser: `maxElements`, `maxDepth` and
+     * `maxRepeatItems`. Unset by default, and each field is independently
+     * optional.
+     *
+     * Unlike `validate`, these are enforced in every mode — a number the app
+     * chose is a control, not a report. A spec over `maxElements` renders
+     * nothing; `maxDepth` and `maxRepeatItems` truncate where they are hit.
+     * They apply while `loading` too: a partial spec is a subset of the
+     * finished one, so a cap can only ever fire early, never falsely.
+     */
+    readonly renderLimits: _angular_core.InputSignal<RenderLimits | null>;
+    /**
+     * The catalog the spec was generated for. Given one, `validate` also checks
+     * what structure alone cannot: that every `type` is a component the catalog
+     * defines, and that the props match its schema.
+     *
+     * Only read when `validate` is on, and — like the rest of the check —
+     * skipped while `loading`.
+     */
+    readonly catalog: _angular_core.InputSignal<SpecCatalog | null>;
     /**
      * Initial state model (uncontrolled mode). Defaults to `spec.state`.
      * Ignored when `store` is provided.
@@ -306,11 +508,31 @@ declare class JsonRenderer {
     readonly stateStore: JsonRenderStateService;
     /** The action dispatcher of this renderer. */
     protected readonly actions: JsonRenderActionsService;
+    /**
+     * The spec as checked, and what the check found. While `loading`, the mode
+     * is forced off: the spec is still arriving, and the missing children it
+     * refers to are the normal state of a stream, not a defect.
+     */
+    private readonly checked;
     constructor();
     protected readonly rootKey: _angular_core.Signal<string | null>;
     protected readonly pendingConfirm: _angular_core.Signal<_json_render_core.ActionConfirm | null>;
+    /**
+     * The app's own dialog, if it provided one. Read once: which component
+     * answers a confirmation is an application decision, not something that
+     * changes between two confirmations.
+     */
+    protected readonly customDialog: Type<unknown> | null;
+    private readonly injector;
+    /**
+     * A replacement dialog takes no inputs and emits no outputs — it injects
+     * everything it needs, the way catalog components do. That keeps the seam
+     * one token wide instead of a component contract the renderer would have to
+     * bind to.
+     */
+    protected readonly confirmInjector: _angular_core.Signal<_angular_core.DestroyableInjector | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<JsonRenderer, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<JsonRenderer, "json-render", never, { "spec": { "alias": "spec"; "required": true; "isSignal": true; }; "registry": { "alias": "registry"; "required": true; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "fallback": { "alias": "fallback"; "required": false; "isSignal": true; }; "state": { "alias": "state"; "required": false; "isSignal": true; }; "store": { "alias": "store"; "required": false; "isSignal": true; }; "handlers": { "alias": "handlers"; "required": false; "isSignal": true; }; "onAction": { "alias": "onAction"; "required": false; "isSignal": true; }; "navigate": { "alias": "navigate"; "required": false; "isSignal": true; }; "validationFunctions": { "alias": "validationFunctions"; "required": false; "isSignal": true; }; "functions": { "alias": "functions"; "required": false; "isSignal": true; }; "directives": { "alias": "directives"; "required": false; "isSignal": true; }; }, { "stateChange": "stateChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<JsonRenderer, "json-render", never, { "spec": { "alias": "spec"; "required": true; "isSignal": true; }; "registry": { "alias": "registry"; "required": true; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "fallback": { "alias": "fallback"; "required": false; "isSignal": true; }; "validate": { "alias": "validate"; "required": false; "isSignal": true; }; "renderLimits": { "alias": "renderLimits"; "required": false; "isSignal": true; }; "catalog": { "alias": "catalog"; "required": false; "isSignal": true; }; "state": { "alias": "state"; "required": false; "isSignal": true; }; "store": { "alias": "store"; "required": false; "isSignal": true; }; "handlers": { "alias": "handlers"; "required": false; "isSignal": true; }; "onAction": { "alias": "onAction"; "required": false; "isSignal": true; }; "navigate": { "alias": "navigate"; "required": false; "isSignal": true; }; "validationFunctions": { "alias": "validationFunctions"; "required": false; "isSignal": true; }; "functions": { "alias": "functions"; "required": false; "isSignal": true; }; "directives": { "alias": "directives"; "required": false; "isSignal": true; }; }, { "stateChange": "stateChange"; }, never, never, true, never>;
 }
 
 /**
@@ -344,6 +566,16 @@ declare class JrChildren {
         key?: string;
     } | undefined>;
     private readonly repeatBasePath;
+    /** Every item the repeat's state array holds, before any cap. */
+    private readonly allRepeatItems;
+    /**
+     * The items this repeat actually renders.
+     *
+     * `repeat` iterates a state array the spec may itself have supplied, which
+     * is the one place a spec sizes the render tree out of data rather than out
+     * of its own structure — so the cap has to be applied here, as it expands,
+     * rather than anywhere a spec can be inspected up front.
+     */
     protected readonly repeatItems: _angular_core.Signal<unknown[]>;
     constructor();
     protected itemPath(index: number): string;
@@ -365,6 +597,7 @@ declare class JrElement {
     private readonly state;
     private readonly actions;
     private readonly repeatScope;
+    private readonly parentPath;
     private readonly devtoolsActive;
     /** The raw (unresolved) element from the spec. */
     readonly rawElement: Signal<UIElement<string, Record<string, unknown>> | undefined>;
@@ -378,6 +611,23 @@ declare class JrElement {
     private readonly entry;
     protected readonly component: Signal<_angular_core.Type<unknown> | null>;
     protected readonly devtoolsKey: Signal<string | null>;
+    /**
+     * Where this element sits in the tree. Passed down to everything it renders
+     * below itself, which is what lets each element see its own ancestry
+     * without the renderer holding a registry of who is drawing what.
+     */
+    private readonly path;
+    /**
+     * Why this element is not drawn, or null when it is.
+     *
+     * The cycle half is unconditional — not something `validate` turns on. An
+     * element that renders itself without reading any deeper renders forever,
+     * and a spec that never stops rendering takes the tab with it; refusing to
+     * draw the repetition is the only outcome that leaves anything on screen.
+     * It costs one walk up a chain of parents, bounded by `maxDepth` where one
+     * is set and by the spec's own nesting where it is not.
+     */
+    protected readonly refusal: Signal<"cycle" | "depth" | null>;
     private readonly renderCtx;
     protected readonly outletInjector: _angular_core.DestroyableInjector;
     constructor();
@@ -416,21 +666,103 @@ declare class JrRepeatScope implements RepeatScope {
  * Default confirmation dialog shown for action bindings with a `confirm`
  * field. Rendered automatically by `<json-render>`; can also be used
  * standalone with a custom action flow.
+ *
+ * It is a real dialog: `role="dialog"` with `aria-modal`, labelled by its own
+ * title and described by its message, focus moved in on open and returned to
+ * wherever it came from on close, Tab kept inside it and Escape cancelling.
+ * A generated UI can ask for confirmation of something destructive, so a
+ * keyboard or screen-reader user has to be able to answer it.
+ *
+ * Colours come from CSS custom properties with light and dark defaults, so an
+ * app can theme it — `--jr-confirm-surface`, `--jr-confirm-ink`,
+ * `--jr-confirm-muted`, `--jr-confirm-border`, `--jr-confirm-scrim`,
+ * `--jr-confirm-accent`, `--jr-confirm-danger`, `--jr-confirm-on-accent`,
+ * `--jr-confirm-radius` — and replace it outright through
+ * {@link JR_CONFIRM_DIALOG} when that is not enough.
  */
 declare class JrConfirmDialog {
     readonly config: _angular_core.InputSignal<ActionConfirm>;
     readonly confirmed: _angular_core.OutputEmitterRef<void>;
     readonly cancelled: _angular_core.OutputEmitterRef<void>;
+    protected readonly labels: ngx_json_render.ConfirmLabels;
+    private readonly id;
+    protected readonly titleId: string;
+    protected readonly messageId: string;
+    private readonly cancelButton;
+    private readonly confirmButton;
     protected readonly isDanger: _angular_core.Signal<boolean>;
+    constructor();
+    /**
+     * Keep Tab inside the dialog. With exactly two buttons the whole trap is
+     * wrapping the ends; a modal that lets focus wander behind it is a modal
+     * only for people using a mouse.
+     */
+    protected onKeydown(event: KeyboardEvent): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<JrConfirmDialog, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<JrConfirmDialog, "jr-confirm-dialog", never, { "config": { "alias": "config"; "required": true; "isSignal": true; }; }, { "confirmed": "confirmed"; "cancelled": "cancelled"; }, never, never, true, never>;
 }
 
+/** The two words the confirmation dialog says on its own. */
+interface ConfirmLabels {
+    confirm: string;
+    cancel: string;
+}
+/**
+ * Labels for the default confirmation dialog's buttons, when the spec does not
+ * supply `confirmLabel` / `cancelLabel` of its own.
+ *
+ * They are the only strings this package puts on screen, and they were English
+ * with no way to change them. Override once, in an app's providers:
+ *
+ * ```ts
+ * { provide: JR_CONFIRM_LABELS, useValue: { confirm: 'Подтвердить', cancel: 'Отмена' } }
+ * ```
+ */
+declare const JR_CONFIRM_LABELS: InjectionToken<ConfirmLabels>;
+/**
+ * Everything a replacement confirmation dialog is given: the config the spec
+ * asked for, and the two ways to answer it. Inject it with
+ * {@link injectConfirmContext}.
+ */
+interface ConfirmContext {
+    /** Title, message, labels and variant, straight from the action binding. */
+    readonly config: ActionConfirm;
+    /** Let the action proceed. */
+    readonly confirm: () => void;
+    /** Dismiss it — a normal answer, not a failure. */
+    readonly cancel: () => void;
+}
+/** The confirmation a replacement dialog component is rendered for. */
+declare const CONFIRM_CONTEXT: InjectionToken<ConfirmContext>;
+/**
+ * The component `<json-render>` should render for a `confirm` on an action.
+ * Unset means the packaged {@link JrConfirmDialog}.
+ *
+ * The component is rendered with a {@link CONFIRM_CONTEXT} in its injector, so
+ * it takes no inputs and emits no outputs:
+ *
+ * ```ts
+ * @Component({ template: `<my-modal (ok)="ctx.confirm()" (dismiss)="ctx.cancel()">…` })
+ * export class AppConfirm {
+ *   readonly ctx = injectConfirmContext();
+ * }
+ * // providers: [{ provide: JR_CONFIRM_DIALOG, useValue: AppConfirm }]
+ * ```
+ */
+declare const JR_CONFIRM_DIALOG: InjectionToken<Type<unknown>>;
+/** Inject the confirmation a replacement dialog component is rendering for. */
+declare function injectConfirmContext(): ConfirmContext;
+
 /**
  * The render context of the element currently being rendered.
  * Provided by the renderer for every catalog component instance.
  */
 declare const RENDER_CONTEXT: InjectionToken<RenderContext<Record<string, unknown>>>;
+/**
+ * The spec key of the element currently being rendered. Provided alongside
+ * {@link RENDER_CONTEXT} for every catalog component instance.
+ */
+declare const ELEMENT_KEY: InjectionToken<Signal<string>>;
 /**
  * The current repeat scope. Present only for elements rendered inside a
  * `repeat` block.
@@ -451,6 +783,21 @@ declare const REPEAT_SCOPE: InjectionToken<RepeatScope>;
  * ```
  */
 declare function injectRenderContext<P = Record<string, unknown>>(): RenderContext<P>;
+/**
+ * Inject the spec key of the element this component renders.
+ *
+ * Catalog components that collect their children — a tab group discovering
+ * its tabs, for instance — need it to order registrations by the spec's
+ * `children` array rather than by the order the children happened to
+ * announce themselves in.
+ *
+ * @example
+ * ```ts
+ * const key = injectElementKey();
+ * const index = computed(() => parent.element().children?.indexOf(key()) ?? -1);
+ * ```
+ */
+declare function injectElementKey(): Signal<string>;
 /**
  * Inject the current repeat scope, or `null` when the component is not
  * rendered inside a `repeat` block.
@@ -469,6 +816,11 @@ declare class JsonRenderRootContext {
     registry: Signal<ComponentRegistry | undefined>;
     loading: Signal<boolean>;
     fallback: Signal<Type<unknown> | RegistryEntry | null | undefined>;
+    /**
+     * Caps on what the spec may cost the browser. Read as the tree renders, so
+     * they apply whatever `validate` is set to.
+     */
+    limits: Signal<RenderLimits | null | undefined>;
     /** External store (controlled mode). */
     store: Signal<StateStore | null | undefined>;
     /** Initial state (uncontrolled mode); falls back to `spec.state`. */
@@ -496,17 +848,36 @@ interface FieldValidationState {
  * Form validation state of a `<json-render>` subtree. Fields register their
  * {@link ValidationConfig}; the built-in `validateForm` action validates all
  * registered fields and writes the result to state.
+ *
+ * Registrations are owner-scoped: a path stays registered while at least one
+ * owner holds it, and its config and state are dropped when the last one
+ * releases. A spec that swaps screens or hides fields therefore stops
+ * validating what is no longer on screen.
  */
 declare class JsonRenderValidationService {
     private readonly root;
     private readonly state;
     private readonly _fieldStates;
     private readonly _fieldConfigs;
+    /** Live owners per path — the reference count behind a registration. */
+    private readonly fieldOwners;
     /** Validation state per registered field path. */
     readonly fieldStates: Signal<Record<string, FieldValidationState>>;
     get customFunctions(): Record<string, ValidationFunction>;
-    /** Register (or update) a field's validation config. */
-    registerField(path: string, config: ValidationConfig): void;
+    /**
+     * Register (or update) a field's validation config.
+     *
+     * @param owner Identity holding the registration — pass the same value to
+     * {@link unregisterField} to release it. Field components pass themselves,
+     * so two components bound to one path each hold their own claim.
+     */
+    registerField(path: string, config: ValidationConfig, owner?: object): void;
+    /**
+     * Release one owner's registration of a field. The config and validation
+     * state survive while another owner still holds the path; once the last
+     * one lets go, `validateAll` stops seeing the field.
+     */
+    unregisterField(path: string, owner?: object): void;
     /** Validate a single field and record the result. */
     validate(path: string, config: ValidationConfig): ValidationResult;
     /** Mark a field as touched. */
@@ -523,6 +894,10 @@ declare function injectValidation(): JsonRenderValidationService;
 /**
  * Field-level validation helper for catalog input components: registers the
  * config and exposes the field's validation state as signals.
+ *
+ * The registration follows the component: it moves when the bound path
+ * changes and is released when the component is destroyed, so a field that
+ * has left the screen no longer takes part in `validateForm`.
  */
 declare function injectFieldValidation(path: string | (() => string), config?: ValidationConfig | (() => ValidationConfig | undefined)): {
     state: Signal<FieldValidationState>;
@@ -625,6 +1000,13 @@ interface DataPart {
     type: string;
     text?: string;
     data?: unknown;
+    /**
+     * The SDK's reconciliation key. A part written with one is *replaced* by the
+     * next part carrying the same id, rather than followed by it — so a spec
+     * streamed as patches must be written without an id, and only a whole-spec
+     * part (`flat` / `nested`), which is a snapshot of itself, can share one.
+     */
+    id?: string;
 }
 /**
  * Build a `Spec` by replaying all spec data parts from a message's
@@ -683,6 +1065,29 @@ interface UIStreamOptions {
     onComplete?: (spec: Spec) => void;
     /** Callback on error */
     onError?: (error: Error) => void;
+    /**
+     * Whether to check the finished spec's structure, and what a problem means.
+     * Off by default.
+     *
+     * The check runs once, when the generation completes — a spec mid-stream is
+     * supposed to be incomplete. Both modes apply the lossless fixes and publish
+     * the fixed spec; `'warn'` reports what is left, while `'strict'` fails the
+     * generation instead of calling `onComplete`, so an app that persists the
+     * spec there does not persist a broken one.
+     */
+    validate?: SpecValidationMode;
+    /**
+     * Caps on what the finished spec may cost the browser. Enforced whatever
+     * `validate` is: a spec over `maxElements` fails the generation rather than
+     * reaching `onComplete`.
+     */
+    renderLimits?: RenderLimits | null;
+    /**
+     * The catalog the spec was generated for. Given one, `validate` also checks
+     * every element `type` against the catalog and the props against its
+     * schema — the half a structural check cannot see.
+     */
+    catalog?: SpecCatalog | null;
     /**
      * Transport, defaulting to the global `fetch`.
      *
@@ -709,6 +1114,13 @@ interface UIStreamReturn {
     readonly usage: Signal<TokenUsage | null>;
     /** Raw JSONL lines received from the stream (JSON patch lines) */
     readonly rawLines: Signal<string[]>;
+    /**
+     * What the check found in the finished spec — structure, catalog and
+     * limits alike. Empty until a generation completes; empty while `validate`
+     * is off unless a `renderLimits` cap was passed, since those are enforced
+     * in every mode.
+     */
+    readonly issues: Signal<readonly SpecCheckIssue[]>;
     /** Send a prompt to generate UI */
     send: (prompt: string, options?: UIStreamSendOptions) => Promise<void>;
     /**
@@ -769,6 +1181,24 @@ interface ChatUIOptions {
      * `Response` whose `body` streams the reply.
      */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Whether to check the spec a reply built, and what a problem means. Off by
+     * default; same contract as `UIStreamOptions.validate`, applied once per
+     * reply that produced a spec.
+     */
+    validate?: SpecValidationMode;
+    /**
+     * Caps on what the finished spec may cost the browser. Enforced whatever
+     * `validate` is: a spec over `maxElements` fails the generation rather than
+     * reaching `onComplete`.
+     */
+    renderLimits?: RenderLimits | null;
+    /**
+     * The catalog the spec was generated for. Given one, `validate` also checks
+     * every element `type` against the catalog and the props against its
+     * schema — the half a structural check cannot see.
+     */
+    catalog?: SpecCatalog | null;
 }
 /**
  * Return type for {@link injectChatUI}.
@@ -780,6 +1210,13 @@ interface ChatUIReturn {
     readonly isStreaming: Signal<boolean>;
     /** Error from the last request, if any */
     readonly error: Signal<Error | null>;
+    /**
+     * What the check found in the last completed reply's spec — structure,
+     * catalog and limits alike. Empty until a reply completes; empty while
+     * `validate` is off unless a `renderLimits` cap was passed, since those are
+     * enforced in every mode.
+     */
+    readonly issues: Signal<readonly SpecCheckIssue[]>;
     /** Send a user message */
     send: (text: string) => Promise<void>;
     /**
@@ -876,5 +1313,5 @@ type AngularSpec<TCatalog> = typeof schema extends {
  */
 declare function injectDevtoolsActive(): Signal<boolean>;
 
-export { JrChildren, JrConfirmDialog, JrElement, JrRepeatScope, JsonRenderActionsService, JsonRenderRootContext, JsonRenderStateService, JsonRenderValidationService, JsonRenderer, RENDER_CONTEXT, REPEAT_SCOPE, applyPatch, buildSpecFromParts, createStoreSetState, defineRegistry, flatToTree, getTextFromParts, injectAction, injectActions, injectBoundProp, injectChatUI, injectDevtoolsActive, injectFieldValidation, injectRenderContext, injectRepeatScope, injectStateBinding, injectStateStore, injectStateValue, injectUIStream, injectValidation, jsonRenderMessage, schema };
-export type { ActionFn, Actions, AngularSchema, AngularSpec, CatalogHasActions, ChatMessage, ChatUIOptions, ChatUIReturn, ComponentRegistry, Components, DataPart, DefineRegistryResult, EventHandle, FieldValidationState, PendingConfirmation, RegistryEntry, RenderContext, RepeatScope, SetState, StateChange, TokenUsage, UIStreamOptions, UIStreamReturn, UIStreamSendOptions };
+export { CONFIRM_CONTEXT, ELEMENT_KEY, JR_CONFIRM_DIALOG, JR_CONFIRM_LABELS, JrChildren, JrConfirmDialog, JrElement, JrRepeatScope, JsonRenderActionsService, JsonRenderRootContext, JsonRenderStateService, JsonRenderValidationService, JsonRenderer, RENDER_CONTEXT, REPEAT_SCOPE, applyPatch, buildSpecFromParts, checkSpec, createStoreSetState, defineRegistry, flatToTree, formatSpecCheckIssues, getTextFromParts, injectAction, injectActions, injectBoundProp, injectChatUI, injectConfirmContext, injectDevtoolsActive, injectElementKey, injectFieldValidation, injectRenderContext, injectRepeatScope, injectStateBinding, injectStateStore, injectStateValue, injectUIStream, injectValidation, isActionCancelled, jsonRenderMessage, schema };
+export type { ActionFn, Actions, AngularSchema, AngularSpec, CatalogHasActions, ChatMessage, ChatUIOptions, ChatUIReturn, ComponentRegistry, Components, ConfirmContext, ConfirmLabels, DataPart, DefineRegistryResult, EventHandle, FieldValidationState, PendingConfirmation, RegistryEntry, RenderContext, RenderLimits, RepeatScope, SetState, SpecCatalog, SpecCheck, SpecCheckIssue, SpecCheckIssueCode, SpecCheckOptions, SpecValidationMode, StateChange, TokenUsage, UIStreamOptions, UIStreamReturn, UIStreamSendOptions };