ngx-json-render 0.7.8 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.7.8",
+  "version": "0.8.1",
   "description": "Angular renderer for json-render — stream AI-generated JSON specs into real Angular components with signals.",
   "keywords": [
     "angular",
@@ -25,7 +25,21 @@
     "@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",
+    "@json-render/devtools": ">=0.20.0 <0.22.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/ext-apps": {
+      "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "@json-render/devtools": {
+      "optional": true
+    }
   },
   "dependencies": {
     "tslib": "^2.3.0"
@@ -45,6 +59,18 @@
       "types": "./types/ngx-json-render.d.ts",
       "default": "./fesm2022/ngx-json-render.mjs"
     },
+    "./devtools": {
+      "types": "./types/ngx-json-render-devtools.d.ts",
+      "default": "./fesm2022/ngx-json-render-devtools.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/schematics/ng-add/index.cjs

@@ -32,7 +32,7 @@ function ngAdd() {
             'ngx-json-render is ready. Next: describe your components in a catalog,',
             `register them, and render a spec with <json-render> — see ${README}`,
             'No components of your own yet? `ng add ngx-json-render-material` adds',
-            '28 ready-made Angular Material ones.',
+            '29 ready-made Angular Material ones.',
         ].join('\n'));
         return (0, schematics_1.chain)(rules);
     };

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

@@ -0,0 +1,67 @@
+import * as _json_render_core from '@json-render/core';
+import { Spec, Catalog } from '@json-render/core';
+import * as _angular_core from '@angular/core';
+import { PanelPosition, DevtoolsEvent } from '@json-render/devtools';
+export { DevtoolsEvent, PanelPosition } from '@json-render/devtools';
+import { JsonRenderer, ChatUIReturn } from 'ngx-json-render';
+
+/**
+ * A floating json-render devtools panel for an Angular app — the counterpart
+ * of `<JsonRenderDevtools />` in `@json-render/devtools-react`, `-vue`,
+ * `-svelte` and `-solid`, with the same tabs (Spec, State, Actions, Stream,
+ * Catalog) and the same element picker.
+ *
+ * Angular has no provider above `<json-render>` to read the renderer from, so
+ * the renderer is passed in by template reference. Streams need no wiring:
+ * every `injectUIStream` and `injectChatUI` generation in the app reaches the
+ * Stream tab.
+ *
+ * Renders nothing outside dev mode, and loads the panel itself
+ * (`@json-render/devtools`) with a dynamic `import()`, so a production build
+ * never fetches it.
+ *
+ * @example
+ * ```html
+ * <json-render #renderer [spec]="ui.spec()" [registry]="registry" />
+ * <json-render-devtools [renderer]="renderer" [catalog]="catalog" />
+ * ```
+ */
+declare class JsonRenderDevtools {
+    /** The renderer to inspect: its spec, state store and catalog. */
+    readonly renderer: _angular_core.InputSignal<JsonRenderer | null>;
+    /** Spec to show instead of the renderer's. */
+    readonly spec: _angular_core.InputSignal<Spec | null | undefined>;
+    /** Catalog for the Catalog tab, if the renderer was not given one. */
+    readonly catalog: _angular_core.InputSignal<Catalog<_json_render_core.SchemaDefinition<_json_render_core.SchemaType<string, unknown>, _json_render_core.SchemaType<string, unknown>>, unknown> | null | undefined>;
+    /**
+     * A chat from `injectChatUI`: every assistant reply with a spec becomes a
+     * generation in the Spec tab's switcher.
+     */
+    readonly chat: _angular_core.InputSignal<ChatUIReturn | null>;
+    readonly initialOpen: _angular_core.InputSignal<boolean>;
+    readonly position: _angular_core.InputSignal<PanelPosition>;
+    /** Toggle shortcut; `false` disables it. */
+    readonly hotkey: _angular_core.InputSignal<string | false>;
+    /** Events kept in the ring buffer. Read once, at creation. */
+    readonly bufferSize: _angular_core.InputSignal<number>;
+    /** Pad the page while the panel is open instead of overlaying it. */
+    readonly reserveSpace: _angular_core.InputSignal<boolean>;
+    /** Let the viewer flip the panel between bottom and right dock. */
+    readonly allowDockToggle: _angular_core.InputSignal<boolean>;
+    /** Every event the panel records, for an app's own logging. */
+    readonly event: _angular_core.OutputEmitterRef<DevtoolsEvent>;
+    private readonly destroyRef;
+    private events;
+    private panel;
+    private destroyed;
+    constructor();
+    private currentSpec;
+    private currentCatalog;
+    private generations;
+    private stateStore;
+    private mount;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<JsonRenderDevtools, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<JsonRenderDevtools, "json-render-devtools", never, { "renderer": { "alias": "renderer"; "required": false; "isSignal": true; }; "spec": { "alias": "spec"; "required": false; "isSignal": true; }; "catalog": { "alias": "catalog"; "required": false; "isSignal": true; }; "chat": { "alias": "chat"; "required": false; "isSignal": true; }; "initialOpen": { "alias": "initialOpen"; "required": false; "isSignal": true; }; "position": { "alias": "position"; "required": false; "isSignal": true; }; "hotkey": { "alias": "hotkey"; "required": false; "isSignal": true; }; "bufferSize": { "alias": "bufferSize"; "required": false; "isSignal": true; }; "reserveSpace": { "alias": "reserveSpace"; "required": false; "isSignal": true; }; "allowDockToggle": { "alias": "allowDockToggle"; "required": false; "isSignal": true; }; }, { "event": "event"; }, never, never, true, never>;
+}
+
+export { JsonRenderDevtools };

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;
@@ -1089,6 +1090,36 @@ declare function createStoreSetState(store: Pick<StateStore, 'getSnapshot' | 'up
  */
 declare function applyPatch(spec: Spec, patch: JsonPatch): Spec;
 
+/** Token usage as the AI SDK reports it in its usage line. */
+interface StreamObserverUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * Hooks into every `injectUIStream` and `injectChatUI` generation in the app,
+ * the counterpart of `registerActionObserver` in `@json-render/core`. This is
+ * what `ngx-json-render/devtools` fills its Stream tab from, so it is private
+ * API: the `ɵ` prefix says it may change in any release.
+ */
+interface StreamObserver {
+    /** A generation started. */
+    onStart?(): void;
+    /** A patch was applied to the spec, in arrival order. */
+    onPatch?(patch: JsonPatch): void;
+    /** A line of prose arrived (`injectChatUI` only). */
+    onText?(text: string): void;
+    /** The usage line arrived (`injectUIStream` only). */
+    onUsage?(usage: StreamObserverUsage): void;
+    /** The generation ended; `ok` is false on an error, true on a stop. */
+    onEnd?(ok: boolean): void;
+}
+/**
+ * Register an observer for every stream in the app. Returns the function that
+ * removes it. Private API for `ngx-json-render/devtools`.
+ */
+declare function ɵregisterStreamObserver(observer: StreamObserver): () => void;
+
 /**
  * Convert a flat element list to a Spec.
  * Input elements use key/parentKey to establish identity and relationships.
@@ -1345,81 +1376,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, ɵregisterStreamObserver };
+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, StreamObserver, StreamObserverUsage, TokenUsage, UIStreamOptions, UIStreamReturn, UIStreamSendOptions };