ngx-json-render 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Angular renderer for json-render — stream AI-generated JSON specs into real Angular components with signals.",
   "keywords": [
     "angular",

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

@@ -1,7 +1,7 @@
 import { Spec, StateStore, ActionHandler, ComputedFunction, ValidationFunction, DirectiveDefinition } from '@json-render/core';
-import { Type, Provider } from '@angular/core';
+import { Provider, Type } from '@angular/core';
 import { ComponentFixture } from '@angular/core/testing';
-import { ComponentRegistry, StateModel, RegistryEntry, JsonRenderer, JsonRenderStateService, JsonRenderValidationService, StateChange } from 'ngx-json-render';
+import { RenderContext, 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,
@@ -85,6 +85,111 @@ declare function usageLine(usage: {
     totalTokens?: number;
 }): string;
 
+/** The DOM half of a harness. */
+interface DomQueries {
+    /** 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>;
+}
+
+/** One `setBound` call that reached a bound prop, in order. */
+interface BoundWrite {
+    prop: string;
+    value: unknown;
+}
+/** Options for {@link renderComponent}. Everything is optional. */
+interface RenderComponentOptions<P extends object> {
+    /** The resolved props the component sees. Defaults to `{}`. */
+    props?: P;
+    /**
+     * Which props are two-way bound, as `prop → state path` — what
+     * `$bindState` / `$bindItem` would have resolved to. A `setBound` on a prop
+     * listed here is recorded and written back into `props`; on any other prop
+     * it is a no-op, exactly as under the renderer.
+     */
+    bindings?: Record<string, string>;
+    /**
+     * The events the spec would bind in `on`. Only affects what `ctx.on(event)`
+     * reports as `bound` — `emitted` records every event regardless.
+     */
+    on?: readonly string[];
+    /** The loading flag the component sees. */
+    loading?: boolean;
+    /** The spec key, for components that `injectElementKey()`. */
+    key?: string;
+    /** The element's catalog type name. */
+    type?: string;
+    /** Extra TestBed providers for anything else the component injects. */
+    providers?: Provider[];
+}
+/**
+ * A catalog component mounted on its own, and what it said to the renderer
+ * it thinks it is inside.
+ */
+interface ComponentHarness<T, P extends object> extends DomQueries {
+    /** The fixture of the host the component is mounted in. */
+    readonly fixture: ComponentFixture<unknown>;
+    /** The host element, the root of the rendered DOM. */
+    readonly element: HTMLElement;
+    /** The component instance. */
+    readonly component: T;
+    /** The render context the component injected. */
+    readonly context: RenderContext<P>;
+    /** Every event the component emitted, bound or not, in order. */
+    readonly emitted: readonly string[];
+    /** Every `setBound` that reached a bound prop, in order. */
+    readonly writes: readonly BoundWrite[];
+    /** The props as the component currently sees them. */
+    props(): P;
+    /** Replace the props and settle. */
+    setProps(props: P): Promise<void>;
+    /** Merge into the props and settle. */
+    patchProps(patch: Partial<P>): Promise<void>;
+    /** Flip the loading flag and settle. */
+    setLoading(loading: boolean): Promise<void>;
+    /** Let effects, promises and change detection finish. */
+    settle(): Promise<void>;
+    /** Destroy the fixture. Rarely needed — TestBed resets between tests. */
+    destroy(): void;
+}
+/**
+ * Mount a catalog component with no renderer and no spec: hand it props, and
+ * read back the events it emitted and the values it wrote to bound props.
+ *
+ * This is the test of a component as a presentational one — what it draws
+ * for these props, and what it says when used. What the spec then does with
+ * that is the renderer's business, and `renderSpec` is where to test it.
+ *
+ * `props` is not inferred from the first value, so a later `patchProps` can
+ * set a prop the first render left out. Pass `P` to have the props typed.
+ *
+ * A component that renders `<jr-children>`, registers field validation or
+ * dispatches actions directly needs the renderer's services and fails with a
+ * message pointing at `renderSpec`.
+ *
+ * @example
+ * ```ts
+ * const button = await renderComponent(MyButton, { props: { label: 'Save' } });
+ *
+ * expect(button.text('button')).toBe('Save');
+ * await button.click('button');
+ * expect(button.emitted).toEqual(['press']);
+ *
+ * await button.patchProps({ disabled: true });
+ * expect(button.find<HTMLButtonElement>('button').disabled).toBe(true);
+ * ```
+ */
+declare function renderComponent<T, P extends object = Record<string, unknown>>(component: Type<T>, options?: RenderComponentOptions<NoInfer<P>>): Promise<ComponentHarness<T, P>>;
+
 /** One action the spec asked for, in the order it was dispatched. */
 interface DispatchedAction {
     name: string;
@@ -123,7 +228,7 @@ interface RenderSpecOptions {
  * `fixture` and `element` are there for everything this does not cover — the
  * harness is a shortcut, not a wall.
  */
-interface SpecHarness {
+interface SpecHarness extends DomQueries {
     /** The fixture of the host that owns the `<json-render>`. */
     readonly fixture: ComponentFixture<unknown>;
     /** The host element, the root of the rendered DOM. */
@@ -150,18 +255,6 @@ interface SpecHarness {
     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;
 }
@@ -193,5 +286,5 @@ interface SpecHarness {
  */
 declare function renderSpec(spec: Spec | null, options: RenderSpecOptions): Promise<SpecHarness>;
 
-export { recordedTransport, renderSpec, specStream, usageLine };
-export type { DispatchedAction, RecordedFailure, RecordedTransportOptions, Recording, Recordings, RenderSpecOptions, SpecHarness };
+export { recordedTransport, renderComponent, renderSpec, specStream, usageLine };
+export type { BoundWrite, ComponentHarness, DispatchedAction, RecordedFailure, RecordedTransportOptions, Recording, Recordings, RenderComponentOptions, RenderSpecOptions, SpecHarness };

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

@@ -1,5 +1,5 @@
 import * as _json_render_core 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';
+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';
@@ -69,6 +69,93 @@ 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.
  *
@@ -77,8 +164,24 @@ declare function injectAction(binding: ActionBinding): {
  * - `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 {
     /**
@@ -86,23 +189,41 @@ interface SpecCheck {
      * untouched when validation is off.
      */
     readonly spec: Spec | null;
-    /** Structural issues left after the fixes. */
-    readonly issues: readonly SpecIssue[];
+    /** 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` asks for.
+ * 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 checkSpec(spec: Spec | null, mode: SpecValidationMode): SpecCheck;
+declare function formatSpecCheckIssues(issues: readonly SpecCheckIssue[]): string;
 
 /**
  * State setter function for updating application state.
@@ -341,6 +462,27 @@ declare class JsonRenderer {
      * 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.
@@ -390,7 +532,7 @@ declare class JsonRenderer {
      */
     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; }; "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>;
+    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>;
 }
 
 /**
@@ -424,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;
@@ -445,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>;
@@ -458,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();
@@ -473,6 +643,12 @@ declare class JrElement {
      */
     private fireEvent;
     private emitEvent;
+    /**
+     * Run an `on` or `watch` binding's actions in order. Params are resolved
+     * per action, just before it runs, so a `$state` read in a later action of
+     * the chain sees what an earlier one wrote.
+     */
+    private dispatch;
     private eventHandle;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<JrElement, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<JrElement, "jr-element", never, { "elementKey": { "alias": "elementKey"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
@@ -646,6 +822,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`. */
@@ -901,6 +1082,18 @@ interface UIStreamOptions {
      * 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`.
      *
@@ -928,10 +1121,12 @@ interface UIStreamReturn {
     /** 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.
+     * 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 SpecIssue[]>;
+    readonly issues: Signal<readonly SpecCheckIssue[]>;
     /** Send a prompt to generate UI */
     send: (prompt: string, options?: UIStreamSendOptions) => Promise<void>;
     /**
@@ -998,6 +1193,18 @@ interface ChatUIOptions {
      * 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}.
@@ -1010,10 +1217,12 @@ interface ChatUIReturn {
     /** 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.
+     * 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 SpecIssue[]>;
+    readonly issues: Signal<readonly SpecCheckIssue[]>;
     /** Send a user message */
     send: (text: string) => Promise<void>;
     /**
@@ -1110,5 +1319,5 @@ type AngularSpec<TCatalog> = typeof schema extends {
  */
 declare function injectDevtoolsActive(): Signal<boolean>;
 
-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 };
+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 };