ngx-json-render 0.7.7 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.7.7",
+  "version": "0.8.0",
   "description": "Angular renderer for json-render — stream AI-generated JSON specs into real Angular components with signals.",
   "keywords": [
     "angular",
@@ -25,7 +25,17 @@
     "@angular/common": ">=19.0.0",
     "@angular/core": ">=19.0.0",
     "@json-render/core": ">=0.20.0 <0.22.0",
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "@modelcontextprotocol/ext-apps": "^1.7.5",
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/ext-apps": {
+      "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
   },
   "dependencies": {
     "tslib": "^2.3.0"
@@ -45,6 +55,14 @@
       "types": "./types/ngx-json-render.d.ts",
       "default": "./fesm2022/ngx-json-render.mjs"
     },
+    "./mcp": {
+      "types": "./types/ngx-json-render-mcp.d.ts",
+      "default": "./fesm2022/ngx-json-render-mcp.mjs"
+    },
+    "./schema": {
+      "types": "./types/ngx-json-render-schema.d.ts",
+      "default": "./fesm2022/ngx-json-render-schema.mjs"
+    },
     "./testing": {
       "types": "./types/ngx-json-render-testing.d.ts",
       "default": "./fesm2022/ngx-json-render-testing.mjs"

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

@@ -0,0 +1,93 @@
+import { Signal } from '@angular/core';
+import { Spec } from '@json-render/core';
+import { App } from '@modelcontextprotocol/ext-apps';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+
+/** Options for {@link injectJsonRenderApp}. */
+interface JsonRenderAppOptions {
+    /** App name sent to the host during initialization. Defaults to `"json-render"`. */
+    name?: string;
+    /** App version sent to the host. Defaults to `"1.0.0"`. */
+    version?: string;
+    /**
+     * Render the spec while the model is still writing the tool call, from the
+     * host's `toolinputpartial` notifications. The host "heals" the truncated
+     * JSON, so each partial spec is valid but may end in a half-written
+     * element; the renderer skips children that do not exist yet. Defaults to
+     * `true`. `useJsonRenderApp` in `@json-render/mcp/app` has no equivalent —
+     * it waits for the tool result.
+     */
+    streamPartialInput?: boolean;
+    /**
+     * Transport to the host. Omit it inside a real MCP Apps iframe: `App`
+     * then talks to `window.parent` over `postMessage`. Tests pass one end of
+     * an in-memory pair here and an `AppBridge` on the other.
+     */
+    transport?: Transport;
+    /**
+     * Report the page's size to the host as it changes, so the iframe grows
+     * with the rendered UI. Defaults to `true`; needs `ResizeObserver`.
+     */
+    autoResize?: boolean;
+}
+/**
+ * What {@link injectJsonRenderApp} returns — the fields of
+ * `UseJsonRenderAppReturn` from `@json-render/mcp/app`, as signals.
+ */
+interface JsonRenderApp {
+    /** The current spec; `null` until the first tool input or result. */
+    readonly spec: Signal<Spec | null>;
+    /** Whether the app is still connecting to the host. */
+    readonly connecting: Signal<boolean>;
+    /** Whether the app is connected to the host. */
+    readonly connected: Signal<boolean>;
+    /** Connection error, if any. */
+    readonly error: Signal<Error | null>;
+    /** Whether the spec is still arriving: pass it to `<json-render [loading]>`. */
+    readonly loading: Signal<boolean>;
+    /** The underlying MCP Apps `App`. */
+    readonly app: App;
+    /**
+     * Call a tool on the MCP server and replace the spec with its result —
+     * for refresh and drill-down interactions.
+     */
+    callServerTool(name: string, args?: Record<string, unknown>): Promise<void>;
+    /**
+     * Post a user message to the host's chat, so the model answers what the
+     * user did in the view. `data`, if given, follows the text as a JSON block.
+     * Rejects when the host does not accept messages from views or turns this
+     * one down, so an action's `onError` runs.
+     */
+    sendMessage(text: string, data?: Record<string, unknown>): Promise<void>;
+}
+/** The text of a {@link JsonRenderApp.sendMessage} message. */
+declare function messageText(text: string, data?: Record<string, unknown>): string;
+interface ToolResultLike {
+    content?: {
+        type: string;
+        text?: string;
+    }[];
+}
+/**
+ * Read a spec out of a tool result. Same rule as `@json-render/mcp/app`: the
+ * first text block, parsed as JSON, either a bare spec or `{ spec }`.
+ */
+declare function parseSpecFromToolResult(result: ToolResultLike): Spec | null;
+/**
+ * Connect an Angular app running inside an MCP Apps iframe to its host and
+ * keep the json-render spec the model sent in a signal. The Angular
+ * counterpart of `useJsonRenderApp` from `@json-render/mcp/app`; the server
+ * side is `createMcpApp` from `@json-render/mcp`, unchanged.
+ *
+ * Call it in an injection context. The connection closes when the injector
+ * that created it is destroyed.
+ *
+ * ```ts
+ * readonly mcp = injectJsonRenderApp();
+ * // <json-render [spec]="mcp.spec()" [loading]="mcp.loading()" [registry]="registry" />
+ * ```
+ */
+declare function injectJsonRenderApp(options?: JsonRenderAppOptions): JsonRenderApp;
+
+export { injectJsonRenderApp, messageText, parseSpecFromToolResult };
+export type { JsonRenderApp, JsonRenderAppOptions };

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

@@ -0,0 +1,74 @@
+import * as _json_render_core from '@json-render/core';
+
+/**
+ * The schema for ngx-json-render.
+ *
+ * Defines:
+ * - Spec: A flat tree of elements with keys, types, props, and children references
+ * - Catalog: Components with props schemas, and optional actions
+ *
+ * This is the same spec grammar the other json-render renderers use, so
+ * catalogs and specs are portable across frameworks.
+ */
+declare const schema: _json_render_core.Schema<{
+    spec: _json_render_core.SchemaType<"object", {
+        /** Root element key */
+        root: _json_render_core.SchemaType<"string", unknown>;
+        /** Flat map of elements by key */
+        elements: _json_render_core.SchemaType<"record", _json_render_core.SchemaType<"object", {
+            /** Component type from catalog */
+            type: _json_render_core.SchemaType<"ref", string>;
+            /** Component props */
+            props: _json_render_core.SchemaType<"propsOf", string>;
+            /** Child element keys (flat reference) */
+            children: _json_render_core.SchemaType<"array", _json_render_core.SchemaType<"string", unknown>>;
+            /** Visibility condition */
+            visible: {
+                optional: true;
+                kind: "any";
+                inner?: unknown;
+            };
+            /** Repeat children from a state array */
+            repeat: {
+                optional: true;
+                kind: "any";
+                inner?: unknown;
+            };
+        }>>;
+    }>;
+    catalog: _json_render_core.SchemaType<"object", {
+        /** Component definitions */
+        components: _json_render_core.SchemaType<"map", {
+            /** Zod schema for component props */
+            props: _json_render_core.SchemaType<"zod", unknown>;
+            /** Slots for this component. Use ['default'] for children, or named slots like ['header', 'footer'] */
+            slots: _json_render_core.SchemaType<"array", _json_render_core.SchemaType<"string", unknown>>;
+            /** Description for AI generation hints */
+            description: _json_render_core.SchemaType<"string", unknown>;
+            /** Example prop values used in prompt examples (auto-generated from Zod schema if omitted) */
+            example: _json_render_core.SchemaType<"any", unknown>;
+        }>;
+        /** Action definitions (optional) */
+        actions: _json_render_core.SchemaType<"map", {
+            /** Zod schema for action params */
+            params: _json_render_core.SchemaType<"zod", unknown>;
+            /** Description for AI generation hints */
+            description: _json_render_core.SchemaType<"string", unknown>;
+        }>;
+    }>;
+}>;
+/**
+ * Type for the Angular schema
+ */
+type AngularSchema = typeof schema;
+/**
+ * Infer the spec type from a catalog
+ */
+type AngularSpec<TCatalog> = typeof schema extends {
+    createCatalog: (catalog: TCatalog) => {
+        _specType: infer S;
+    };
+} ? S : never;
+
+export { schema };
+export type { AngularSchema, AngularSpec };

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

@@ -4,6 +4,7 @@ export { ActionBinding, ActionHandler, InferActionParams, InferCatalogComponents
 import * as _angular_core from '@angular/core';
 import { Signal, Type, Injector, InjectionToken } from '@angular/core';
 import * as ngx_json_render from 'ngx-json-render';
+export { AngularSchema, AngularSpec, schema } from 'ngx-json-render/schema';
 
 interface PendingConfirmation {
     action: ResolvedAction;
@@ -628,7 +629,16 @@ declare class JrElement {
     private readonly repeatScope;
     private readonly parentPath;
     private readonly devtoolsActive;
-    /** The raw (unresolved) element from the spec. */
+    /**
+     * The raw (unresolved) element from the spec.
+     *
+     * Compared by content, not identity. A streamed patch shares every element
+     * it did not touch, and the identity check settles those at once; but a
+     * spec can also arrive as all-new objects — a whole-spec part, a host that
+     * fetches it again, `buildSpecFromParts` replaying a message — and then an
+     * element whose content is unchanged would resolve, and every container
+     * with a fresh `children` array re-render, for nothing.
+     */
     readonly rawElement: Signal<UIElement<string, Record<string, unknown>> | undefined>;
     /**
      * The state paths this element's expressions can read, or null when the
@@ -662,21 +672,30 @@ declare class JrElement {
     private readonly resolutionCtx;
     protected readonly visible: Signal<boolean>;
     /**
-     * The element with all prop expressions resolved.
+     * How many state writes have touched a path this element is two-way bound
+     * to. See {@link resolution} for why those writes count on their own.
+     */
+    private readonly boundWrites;
+    /**
+     * The element with all prop expressions resolved, and the bound writes it
+     * was resolved after.
      *
-     * Resolving builds a new props object on every state write, whatever the
-     * write touched. Handing that on as a change would re-run every catalog
-     * template in the tree for one keystroke, so a result that holds the same
-     * values as the last one counts as unchanged and keeps the old object.
+     * Resolving builds a new props object every time, so a result that holds
+     * the same values as the last one counts as unchanged and keeps the old
+     * object; otherwise one keystroke would re-run every catalog template that
+     * happened to resolve.
      *
-     * Two-way bound elements are the exception, and keep treating every
-     * resolution as a change. Their component writes the user's input into the
-     * DOM before it reaches state, so the DOM can differ from a prop whose
-     * value never did: typing and a `clearStatePath` in the same turn take
-     * the prop from '' through 'milk' back to '' with nobody reading 'milk'.
-     * The README tells catalog authors to sync such inputs with an effect on
-     * props, and that effect only gets to put the DOM right if it runs.
+     * A write to a path the element is bound to always counts, though. Its
+     * component writes the user's input into the DOM before it reaches state,
+     * so the DOM can differ from a prop whose value never did: typing and a
+     * `clearStatePath` in the same turn take the prop from '' through 'milk'
+     * back to '' with nobody reading 'milk'. The README tells catalog authors
+     * to sync such inputs with an effect on props, and that effect only gets to
+     * put the DOM right if it runs. Writes anywhere else compare by value, like
+     * any element's.
      */
+    private readonly resolution;
+    /** The element with all prop expressions resolved. */
     readonly resolvedElement: Signal<UIElement<string, Record<string, unknown>> | undefined>;
     /** Two-way binding paths ($bindState / $bindItem) by prop name. */
     readonly bindings: Signal<Record<string, string> | undefined>;
@@ -1327,81 +1346,11 @@ interface ChatUIReturn {
  */
 declare function injectChatUI(options: ChatUIOptions): ChatUIReturn;
 
-/**
- * The schema for ngx-json-render.
- *
- * Defines:
- * - Spec: A flat tree of elements with keys, types, props, and children references
- * - Catalog: Components with props schemas, and optional actions
- *
- * This is the same spec grammar the other json-render renderers use, so
- * catalogs and specs are portable across frameworks.
- */
-declare const schema: _json_render_core.Schema<{
-    spec: _json_render_core.SchemaType<"object", {
-        /** Root element key */
-        root: _json_render_core.SchemaType<"string", unknown>;
-        /** Flat map of elements by key */
-        elements: _json_render_core.SchemaType<"record", _json_render_core.SchemaType<"object", {
-            /** Component type from catalog */
-            type: _json_render_core.SchemaType<"ref", string>;
-            /** Component props */
-            props: _json_render_core.SchemaType<"propsOf", string>;
-            /** Child element keys (flat reference) */
-            children: _json_render_core.SchemaType<"array", _json_render_core.SchemaType<"string", unknown>>;
-            /** Visibility condition */
-            visible: {
-                optional: true;
-                kind: "any";
-                inner?: unknown;
-            };
-            /** Repeat children from a state array */
-            repeat: {
-                optional: true;
-                kind: "any";
-                inner?: unknown;
-            };
-        }>>;
-    }>;
-    catalog: _json_render_core.SchemaType<"object", {
-        /** Component definitions */
-        components: _json_render_core.SchemaType<"map", {
-            /** Zod schema for component props */
-            props: _json_render_core.SchemaType<"zod", unknown>;
-            /** Slots for this component. Use ['default'] for children, or named slots like ['header', 'footer'] */
-            slots: _json_render_core.SchemaType<"array", _json_render_core.SchemaType<"string", unknown>>;
-            /** Description for AI generation hints */
-            description: _json_render_core.SchemaType<"string", unknown>;
-            /** Example prop values used in prompt examples (auto-generated from Zod schema if omitted) */
-            example: _json_render_core.SchemaType<"any", unknown>;
-        }>;
-        /** Action definitions (optional) */
-        actions: _json_render_core.SchemaType<"map", {
-            /** Zod schema for action params */
-            params: _json_render_core.SchemaType<"zod", unknown>;
-            /** Description for AI generation hints */
-            description: _json_render_core.SchemaType<"string", unknown>;
-        }>;
-    }>;
-}>;
-/**
- * Type for the Angular schema
- */
-type AngularSchema = typeof schema;
-/**
- * Infer the spec type from a catalog
- */
-type AngularSpec<TCatalog> = typeof schema extends {
-    createCatalog: (catalog: TCatalog) => {
-        _specType: infer S;
-    };
-} ? S : never;
-
 /**
  * Reactive mirror of the json-render devtools-active flag. When active, the
  * renderer wraps each element with a `data-jr-key` attribute for the picker.
  */
 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, 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 };
+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 };
+export type { ActionFn, Actions, 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 };