ngx-json-render 0.9.2 → 0.9.5

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

@@ -0,0 +1,223 @@
+import { Spec } from '@json-render/core';
+import * as _angular_core from '@angular/core';
+import { Signal, Type } from '@angular/core';
+import { SpecValidationMode, RenderLimits, SpecCatalog, SpecCheckIssue } from 'ngx-json-render';
+
+/**
+ * The `activityType` a json-render spec travels under.
+ *
+ * An agent sends the spec as an AG-UI activity: `ACTIVITY_SNAPSHOT` carries a
+ * whole spec in `content`, and `ACTIVITY_DELTA` carries RFC 6902 patches
+ * against it in `patch` — the same patches a json-render JSONL stream is made
+ * of. CopilotKit carries A2UI the same way, under `"a2ui-surface"`.
+ *
+ * The name says both the format and what `content` holds — a `Spec`, the
+ * object upstream calls a spec in its AI SDK part type `data-spec` — so a
+ * renderer for another framework can match it without reading these docs.
+ */
+declare const JSON_RENDER_ACTIVITY_TYPE = "json-render-spec";
+/**
+ * The part of an AG-UI event this entry point reads.
+ *
+ * Structural on purpose: `@ag-ui/core`'s `EventType` is a string enum, so its
+ * events fit a `string` here, and nothing below needs the package at runtime
+ * or pins its version.
+ */
+interface AgUiEvent {
+    readonly type: string;
+}
+/** The part of an AG-UI message this entry point reads. */
+interface AgUiMessage {
+    readonly id: string;
+    readonly role: string;
+}
+/** One spec an agent is building, keyed by its activity message. */
+interface AgUiSurface {
+    /** The activity's `messageId`; one run can build several surfaces. */
+    readonly messageId: string;
+    readonly spec: Spec;
+}
+/**
+ * Whether activity content has the shape of a spec. Only the shape: what the
+ * elements say is the renderer's and the finished-spec check's business.
+ */
+declare function isJsonRenderSpec(content: unknown): content is Spec;
+/**
+ * The surfaces an AG-UI message list holds, in message order.
+ *
+ * Used for `MESSAGES_SNAPSHOT` and to pick up the history an agent already
+ * has when a hook attaches to it.
+ */
+declare function surfacesFromMessages(messages: readonly AgUiMessage[], activityType?: string): readonly AgUiSurface[];
+/**
+ * Fold one AG-UI event into the surfaces built so far.
+ *
+ * Returns the same array when the event does not concern json-render, so a
+ * signal holding the result only notifies on a real change. A delta applies
+ * through the same immutable patch engine as a JSONL stream: elements it does
+ * not touch keep their identity, and the renderer skips them.
+ *
+ * Two leniencies, both in the direction of rendering what arrived:
+ * - a delta for a surface no snapshot has opened starts from an empty spec,
+ *   so an agent can stream patches the way a JSONL endpoint does;
+ * - a malformed patch op is dropped rather than failing the surface.
+ */
+declare function applyAgUiEvent(surfaces: readonly AgUiSurface[], event: AgUiEvent, activityType?: string): readonly AgUiSurface[];
+
+/**
+ * The callbacks of an AG-UI subscriber this entry point uses — a subset of
+ * `@ag-ui/client`'s `AgentSubscriber`.
+ */
+interface AgUiSubscriber {
+    onRunInitialized?(): void;
+    onEvent?(params: {
+        event: AgUiEvent;
+    }): void;
+    onRunErrorEvent?(params: {
+        event: {
+            message: string;
+        };
+    }): void;
+    onRunFailed?(params: {
+        error: Error;
+    }): void;
+    onRunFinalized?(): void;
+}
+/**
+ * What {@link injectAgentUI} needs of an agent. Any `@ag-ui/client` agent —
+ * `HttpAgent`, a subclass of `AbstractAgent`, the agent CopilotKit hands out —
+ * already has this shape.
+ */
+interface AgUiAgent {
+    readonly messages?: readonly AgUiMessage[];
+    subscribe(subscriber: AgUiSubscriber): {
+        unsubscribe(): void;
+    };
+}
+/** Options for {@link injectAgentUI}. */
+interface AgentUIOptions {
+    /** The agent whose runs build the UI. The app runs it; the hook listens. */
+    agent: AgUiAgent;
+    /** Defaults to {@link JSON_RENDER_ACTIVITY_TYPE}. */
+    activityType?: string;
+    /**
+     * Called once per surface a run touched, after the finished-spec check.
+     * Skipped for a run that failed, and for a surface the check rejected.
+     */
+    onComplete?: (spec: Spec, messageId: string) => void;
+    /** Called when a run fails or a finished surface fails the check. */
+    onError?: (error: Error) => void;
+    /** As for `injectUIStream`: checked once per surface, when the run ends. */
+    validate?: SpecValidationMode;
+    /** As for `injectUIStream`; enforced whatever `validate` is. */
+    renderLimits?: RenderLimits | null;
+    /** As for `injectUIStream`: lets `validate` check types and props. */
+    catalog?: SpecCatalog | null;
+}
+/** Return type of {@link injectAgentUI}. */
+interface AgentUIReturn {
+    /** Every json-render surface the agent has built, in order of appearance. */
+    readonly surfaces: Signal<readonly AgUiSurface[]>;
+    /** The most recently opened surface's spec — the one most apps render. */
+    readonly spec: Signal<Spec | null>;
+    /** Whether a run of the agent is in progress. */
+    readonly isStreaming: Signal<boolean>;
+    /** The last run's error, if any. */
+    readonly error: Signal<Error | null>;
+    /** What the check found in the surfaces the last run finished. */
+    readonly issues: Signal<readonly SpecCheckIssue[]>;
+}
+/**
+ * Render what an AG-UI agent streams. Subscribes to the agent, folds every
+ * json-render activity it emits into signals, and checks each surface when
+ * the run ends — the same contract as `injectUIStream`, with the agent in
+ * place of the endpoint.
+ *
+ * The app keeps running the agent itself (`agent.runAgent()`, CopilotKit, a
+ * reconnect); the hook only listens, so it sees every run, whoever starts it.
+ * It starts from whatever surfaces are already in the agent's messages and
+ * unsubscribes on destroy.
+ *
+ * @example
+ * ```ts
+ * export class AgentPage {
+ *   readonly agent = new HttpAgent({ url: '/api/agent' });
+ *   readonly ui = injectAgentUI({ agent: this.agent, catalog });
+ *   ask(text: string) {
+ *     this.agent.addMessage({ id: crypto.randomUUID(), role: 'user', content: text });
+ *     this.agent.runAgent();
+ *   }
+ * }
+ * // template:
+ * // <json-render [spec]="ui.spec()" [registry]="registry" [loading]="ui.isStreaming()" />
+ * ```
+ */
+declare function injectAgentUI(options: AgentUIOptions): AgentUIReturn;
+
+/**
+ * Renders one json-render activity message. It takes the inputs every AG-UI
+ * activity renderer is given — CopilotKit Angular's `ActivityRenderer`
+ * contract — and draws `content` with `<json-render>`, which takes its
+ * registry, catalog and handlers from the nearest `provideJsonRender`.
+ *
+ * Register it with {@link jsonRenderActivityRenderer} rather than by hand.
+ */
+declare class JsonRenderActivity {
+    readonly activityType: _angular_core.InputSignal<string>;
+    readonly content: _angular_core.InputSignal<unknown>;
+    /** The AG-UI activity message; unused, accepted for the contract. */
+    readonly message: _angular_core.InputSignal<unknown>;
+    /** The agent that produced it; unused, accepted for the contract. */
+    readonly agent: _angular_core.InputSignal<unknown>;
+    protected readonly spec: _angular_core.Signal<Spec | null>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<JsonRenderActivity, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<JsonRenderActivity, "json-render-activity", never, { "activityType": { "alias": "activityType"; "required": false; "isSignal": true; }; "content": { "alias": "content"; "required": true; "isSignal": true; }; "message": { "alias": "message"; "required": false; "isSignal": true; }; "agent": { "alias": "agent"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/** Options for {@link jsonRenderActivityRenderer}. */
+interface JsonRenderActivityRendererOptions {
+    /** Defaults to {@link JSON_RENDER_ACTIVITY_TYPE}. */
+    activityType?: string;
+    /** Limit the renderer to one agent's activities. */
+    agentId?: string;
+    /** A component of your own in place of {@link JsonRenderActivity}. */
+    component?: Type<unknown>;
+}
+/**
+ * An activity renderer config in the shape CopilotKit Angular's
+ * `renderActivityMessages` takes, matched structurally so this package does
+ * not depend on CopilotKit.
+ */
+interface JsonRenderActivityRendererConfig {
+    activityType: string;
+    agentId?: string;
+    content: {
+        safeParse(content: unknown): {
+            success: true;
+            data: Spec;
+        } | {
+            success: false;
+            error?: unknown;
+        };
+    };
+    component: Type<any>;
+}
+/**
+ * Teach a CopilotKit Angular app to render json-render activities:
+ *
+ * ```ts
+ * providers: [
+ *   provideJsonRender({ registry }),
+ *   provideCopilotKit({
+ *     runtimeUrl: '/api/copilotkit',
+ *     renderActivityMessages: [jsonRenderActivityRenderer()],
+ *   }),
+ * ]
+ * ```
+ *
+ * Content that is not a spec is rejected by the config's schema, so CopilotKit
+ * skips the message with a warning instead of mounting an empty renderer.
+ */
+declare function jsonRenderActivityRenderer(options?: JsonRenderActivityRendererOptions): JsonRenderActivityRendererConfig;
+
+export { JSON_RENDER_ACTIVITY_TYPE, JsonRenderActivity, applyAgUiEvent, injectAgentUI, isJsonRenderSpec, jsonRenderActivityRenderer, surfacesFromMessages };
+export type { AgUiAgent, AgUiEvent, AgUiMessage, AgUiSubscriber, AgUiSurface, AgentUIOptions, AgentUIReturn, JsonRenderActivityRendererConfig, JsonRenderActivityRendererOptions };

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

@@ -0,0 +1,107 @@
+import { Catalog } from '@json-render/core';
+import { McpUiResourceCsp } from '@modelcontextprotocol/ext-apps';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+/** Options for {@link createRenderUiServer}. */
+interface RenderUiServerOptions {
+    /** The components and actions the model may use. */
+    catalog: Catalog;
+    /** The view: one self-contained HTML document that renders the spec. */
+    html: string;
+    /** The server's name, as hosts list it. Default `'ngx-json-render'`. */
+    name?: string;
+    /** The server's version. Default `'0.0.0'`. */
+    version?: string;
+    /** The tool's name; the view resource is `ui://<toolName>/view.html`. Default `'render-ui'`. */
+    toolName?: string;
+    /** The tool's title, as hosts show it. Default `'Render UI'`. */
+    title?: string;
+    /** The tool's description. Default: {@link renderUiDescription} for the catalog. */
+    description?: string;
+    /**
+     * The origins the view may load from (`resourceDomains`) and connect to
+     * (`connectDomains`). Left out, the host's default applies, which the MCP
+     * Apps spec defines as none.
+     */
+    csp?: McpUiResourceCsp;
+    /**
+     * The origin ChatGPT derives the view's sandbox origin from, which its
+     * plugin directory requires, unique per plugin. Set through the OpenAI
+     * alias rather than `_meta.ui.domain`, because that key's format is up to
+     * each host and Claude expects a `{hash}.claudemcpcontent.com` value there.
+     */
+    widgetDomain?: string;
+}
+/**
+ * An MCP server with a `render-ui` tool for `catalog` and its `ui://` view.
+ * Connect it to any transport: `StdioServerTransport` for a local host,
+ * or {@link handleRenderUiRequest} for Streamable HTTP.
+ *
+ * The tool checks a spec against the catalog before it echoes it back. A
+ * rejected spec goes back to the model as an error it can fix.
+ */
+declare function createRenderUiServer(options: RenderUiServerOptions): McpServer;
+/**
+ * Serve one Streamable HTTP request, statelessly: a fresh server and
+ * transport per request, so it runs unchanged on a serverless or edge
+ * function (anything with web `Request` and `Response`). Answers CORS,
+ * because browser-based clients such as MCP Inspector call cross-origin.
+ */
+declare function handleRenderUiRequest(options: RenderUiServerOptions, request: Request): Promise<Response>;
+
+/** Claude cuts a tool description off after roughly this many characters. */
+declare const DESCRIPTION_LIMIT = 2000;
+/** Options for {@link renderUiDescription}. */
+interface RenderUiDescriptionOptions {
+    /** What the tool draws, as the first sentence names it. Default `'UI'`. */
+    ui?: string;
+}
+/**
+ * The `render-ui` tool description for `catalog`: how a spec is put
+ * together, in under {@link DESCRIPTION_LIMIT} characters. The components,
+ * props and actions are left to the input schema. The paragraph on
+ * `sendMessage` is included only when the catalog defines that action, since
+ * the view has to handle it.
+ */
+declare function renderUiDescription(catalog: Catalog, { ui }?: RenderUiDescriptionOptions): string;
+/**
+ * The tool's input schema: a spec whose elements are typed per component.
+ *
+ * `catalog.zodSchema()` types an element's `type` but not its props, and it
+ * has no `state`, `on` or `watch`, so the MCP SDK, which parses tool
+ * arguments with the input schema, stripped those and let any prop through.
+ * Here each component's props are its catalog schema (with dynamic values
+ * allowed and unknown props rejected), and each action's params are checked.
+ */
+declare function specInputSchema(catalog: Catalog): z.ZodObject<{
+    root: z.ZodString;
+    elements: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>, ...z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>[]], "type">>;
+    state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+/**
+ * What `render-ui` returns as `structuredContent`: the spec it was given,
+ * after the input schema filled in missing `children`. Only its outline,
+ * since the input schema already carries the catalog and a second copy would
+ * double what every `tools/list` sends the model. ChatGPT flags a tool
+ * without an output schema ("Output schema recommended").
+ */
+declare const specOutputSchema: z.ZodObject<{
+    root: z.ZodString;
+    elements: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        children: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>>;
+    state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+/**
+ * What the input schema cannot express: a root and children that exist,
+ * repeat with a template child, valid visibility conditions, and `$template`
+ * placeholders that read a repeat item. Returns the problems as text for the
+ * model, or `undefined` when there are none.
+ */
+declare function specProblems(spec: object): string | undefined;
+
+export { DESCRIPTION_LIMIT, createRenderUiServer, handleRenderUiRequest, renderUiDescription, specInputSchema, specOutputSchema, specProblems };
+export type { RenderUiDescriptionOptions, RenderUiServerOptions };