ngx-json-render 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Angular renderer for json-render — stream AI-generated JSON specs into real Angular components with signals.",
   "keywords": [
     "angular",
@@ -40,6 +40,10 @@
     ".": {
       "types": "./types/ngx-json-render.d.ts",
       "default": "./fesm2022/ngx-json-render.mjs"
+    },
+    "./testing": {
+      "types": "./types/ngx-json-render-testing.d.ts",
+      "default": "./fesm2022/ngx-json-render-testing.mjs"
     }
   },
   "type": "module"

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

@@ -0,0 +1,197 @@
+import { Spec, StateStore, ActionHandler, ComputedFunction, ValidationFunction, DirectiveDefinition } from '@json-render/core';
+import { Type, Provider } from '@angular/core';
+import { ComponentFixture } from '@angular/core/testing';
+import { ComponentRegistry, StateModel, RegistryEntry, JsonRenderer, JsonRenderStateService, JsonRenderValidationService, StateChange } from 'ngx-json-render';
+
+/**
+ * The lines of one recorded response body, in the order the server sent them,
+ * without their trailing newlines.
+ */
+type Recording = readonly string[];
+/**
+ * What to replay for a request. Either one recording for every request, a
+ * lookup by prompt, or a function for anything more involved.
+ */
+type Recordings = Recording | Readonly<Record<string, Recording>> | ((prompt: string, body: Readonly<Record<string, unknown>>) => Recording | undefined);
+/** An error the recorded server answers with instead of a stream. */
+interface RecordedFailure {
+    /** HTTP status. Defaults to 500. */
+    status?: number;
+    /** The `message` field of the JSON error body. */
+    message?: string;
+}
+/** Options for {@link recordedTransport}. */
+interface RecordedTransportOptions {
+    /**
+     * Milliseconds between lines — the pace a model would emit them at.
+     * Defaults to 0, which still yields to the event loop between lines, so a
+     * test can observe the stream in flight.
+     */
+    delayMs?: number;
+    /**
+     * Answer with an error instead of a stream. A function is called per
+     * request, so a test can turn the failure on and off between sends.
+     */
+    fail?: RecordedFailure | (() => RecordedFailure | null | undefined);
+    /**
+     * Pull the prompt out of the request body. The default reads `prompt`
+     * (what `injectUIStream` sends) and falls back to the last message's
+     * content (what `injectChatUI` sends).
+     */
+    promptOf?: (body: Readonly<Record<string, unknown>>) => string;
+}
+/**
+ * A `fetch` that answers the streaming hooks from a recording instead of a
+ * server.
+ *
+ * Both {@link injectUIStream} and {@link injectChatUI} take any function with
+ * fetch's shape, so a test runs the real client — request body, streamed
+ * lines, usage metadata, abort on supersede — with no server, no API key and
+ * no global patched behind the test's back. Only the transport is recorded.
+ *
+ * @example
+ * ```ts
+ * const ui = injectUIStream({
+ *   api: '/api/generate',
+ *   fetch: recordedTransport(specStream(spec)),
+ * });
+ * ```
+ *
+ * @example Different answers per prompt, at a visible pace:
+ * ```ts
+ * recordedTransport(
+ *   { 'a dashboard': specStream(dashboard), 'a form': specStream(form) },
+ *   { delayMs: 20 },
+ * );
+ * ```
+ */
+declare function recordedTransport(recordings: Recordings, options?: RecordedTransportOptions): typeof globalThis.fetch;
+/**
+ * The JSONL patch lines a model would emit to build `spec`: the root, then
+ * the state, then one line per element in declaration order.
+ *
+ * Recording a stream by hand means writing patches by hand; this writes them
+ * from the spec a test already has, so the test says what it renders rather
+ * than how the wire spells it.
+ */
+declare function specStream(spec: Spec): string[];
+/**
+ * The usage metadata line `injectUIStream` reads into its `usage` signal.
+ * Append it to a recording to exercise that path.
+ */
+declare function usageLine(usage: {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+}): string;
+
+/** One action the spec asked for, in the order it was dispatched. */
+interface DispatchedAction {
+    name: string;
+    params?: Record<string, unknown>;
+}
+/** Options for {@link renderSpec}. Everything but `registry` is optional. */
+interface RenderSpecOptions {
+    /** Catalog type name → Angular component. The one required option. */
+    registry: ComponentRegistry;
+    /** Initial state model. Defaults to the spec's own `state`. */
+    state?: StateModel;
+    /** External store, for controlled mode. */
+    store?: StateStore | null;
+    /** Action handlers by name. Dispatches are recorded either way. */
+    handlers?: Record<string, ActionHandler>;
+    /** Catch-all handler for actions with no dedicated handler. */
+    onAction?: (name: string, params?: Record<string, unknown>) => unknown;
+    /** Navigation function for `onSuccess: { navigate }`. */
+    navigate?: (path: string) => void;
+    /** Fallback component for unknown types. */
+    fallback?: Type<unknown> | RegistryEntry | null;
+    /** Named functions for `$computed` props. */
+    functions?: Record<string, ComputedFunction>;
+    /** Custom validation functions. */
+    validationFunctions?: Record<string, ValidationFunction>;
+    /** Custom directives for `$`-prefixed values. */
+    directives?: DirectiveDefinition[];
+    /** Render as if the spec were still streaming. */
+    loading?: boolean;
+    /** Extra TestBed providers, e.g. a `JR_CONFIRM_DIALOG` replacement. */
+    providers?: Provider[];
+}
+/**
+ * A rendered spec, and the handful of things a test does to one.
+ *
+ * `fixture` and `element` are there for everything this does not cover — the
+ * harness is a shortcut, not a wall.
+ */
+interface SpecHarness {
+    /** The fixture of the host that owns the `<json-render>`. */
+    readonly fixture: ComponentFixture<unknown>;
+    /** The host element, the root of the rendered DOM. */
+    readonly element: HTMLElement;
+    /** The renderer instance. */
+    readonly renderer: JsonRenderer;
+    /** The renderer's state store. */
+    readonly store: JsonRenderStateService;
+    /** The renderer's validation service. */
+    readonly validation: JsonRenderValidationService;
+    /** Every action the spec dispatched, handled or not, in order. */
+    readonly dispatched: readonly DispatchedAction[];
+    /** Every state change the renderer emitted, flattened, in order. */
+    readonly changes: readonly StateChange[];
+    /** Render a different spec (a later streaming frame, say). */
+    setSpec(spec: Spec | null): Promise<void>;
+    /** Flip the loading flag catalog components see. */
+    setLoading(loading: boolean): Promise<void>;
+    /** Let effects, promises and change detection finish. */
+    settle(): Promise<void>;
+    /** Read a state path, e.g. `/form/email`. */
+    read(path: string): unknown;
+    /** Write a state path and settle. */
+    write(path: string, value: unknown): Promise<void>;
+    /** The whole state model. */
+    state(): StateModel;
+    /** Trimmed text of the first match, or of everything when given nothing. */
+    text(selector?: string): string;
+    /** Trimmed text of every match. */
+    texts(selector: string): string[];
+    /** The first match. Throws when there is none. */
+    find<T extends HTMLElement>(selector: string): T;
+    /** Every match, possibly none. */
+    findAll<T extends HTMLElement>(selector: string): T[];
+    /** Click an element (or the first match of a selector) and settle. */
+    click(target: string | Element): Promise<void>;
+    /** Set an input's value, fire `input`, and settle. */
+    fill(target: string | Element, value: string): Promise<void>;
+    /** Destroy the fixture. Rarely needed — TestBed resets between tests. */
+    destroy(): void;
+}
+/**
+ * Render a spec against a registry and hand back the few things a test does
+ * to it.
+ *
+ * Testing a catalog component otherwise means a host component, a TestBed
+ * module, a zoneless provider, two settle passes and a `querySelector` — the
+ * same twenty lines in every project that adopts this package, none of them
+ * about the component under test.
+ *
+ * @example
+ * ```ts
+ * const ui = await renderSpec(
+ *   {
+ *     root: 'save',
+ *     elements: {
+ *       save: { type: 'Button', props: { label: 'Save' }, on: { press: { action: 'save' } } },
+ *     },
+ *   },
+ *   { registry: { Button: MyButton } },
+ * );
+ *
+ * expect(ui.text('button')).toBe('Save');
+ * await ui.click('button');
+ * expect(ui.dispatched).toEqual([{ name: 'save', params: {} }]);
+ * ```
+ */
+declare function renderSpec(spec: Spec | null, options: RenderSpecOptions): Promise<SpecHarness>;
+
+export { recordedTransport, renderSpec, specStream, usageLine };
+export type { DispatchedAction, RecordedFailure, RecordedTransportOptions, Recording, Recordings, RenderSpecOptions, SpecHarness };

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, Spec, SpecIssue, 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,41 @@ declare function injectAction(binding: ActionBinding): {
     isLoading: Signal<boolean>;
 };
 
+/**
+ * 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.
+ */
+type SpecValidationMode = 'off' | 'warn' | 'strict';
+/** 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 issues left after the fixes. */
+    readonly issues: readonly SpecIssue[];
+    /** Descriptions of the fixes that were applied. */
+    readonly fixes: readonly string[];
+    /** Whether an issue of `error` severity survived. */
+    readonly hasErrors: boolean;
+}
+/**
+ * Check a spec the way `validate` asks 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.
+ */
+declare function checkSpec(spec: Spec | null, mode: SpecValidationMode): SpecCheck;
+
 /**
  * State setter function for updating application state.
  * Matches the `SetState` contract of the other json-render renderers
@@ -281,6 +328,19 @@ 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>;
     /**
      * Initial state model (uncontrolled mode). Defaults to `spec.state`.
      * Ignored when `store` is provided.
@@ -306,11 +366,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; }; "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>;
 }
 
 /**
@@ -416,21 +496,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 +613,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.
@@ -496,17 +673,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 +719,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 +825,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 +890,17 @@ 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;
     /**
      * Transport, defaulting to the global `fetch`.
      *
@@ -709,6 +927,11 @@ interface UIStreamReturn {
     readonly usage: Signal<TokenUsage | null>;
     /** Raw JSONL lines received from the stream (JSON patch lines) */
     readonly rawLines: Signal<string[]>;
+    /**
+     * Structural issues in the finished spec. Empty until a generation
+     * completes, and always empty while `validate` is off.
+     */
+    readonly issues: Signal<readonly SpecIssue[]>;
     /** Send a prompt to generate UI */
     send: (prompt: string, options?: UIStreamSendOptions) => Promise<void>;
     /**
@@ -769,6 +992,12 @@ 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;
 }
 /**
  * Return type for {@link injectChatUI}.
@@ -780,6 +1009,11 @@ interface ChatUIReturn {
     readonly isStreaming: Signal<boolean>;
     /** Error from the last request, if any */
     readonly error: Signal<Error | null>;
+    /**
+     * Structural issues in the spec of the last completed reply. Empty until a
+     * reply completes, and always empty while `validate` is off.
+     */
+    readonly issues: Signal<readonly SpecIssue[]>;
     /** Send a user message */
     send: (text: string) => Promise<void>;
     /**
@@ -876,5 +1110,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, 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, RepeatScope, SetState, SpecCheck, SpecValidationMode, StateChange, TokenUsage, UIStreamOptions, UIStreamReturn, UIStreamSendOptions };