ngx-json-render 0.9.2 → 0.9.4

package/README.md

@@ -109,28 +109,6 @@ export class App {
 vocabulary. Everything below is the other path — your own components, which is
 what the catalog API is for.
 
-## ngx-json-render or Hashbrown?
-
-[Hashbrown](https://hashbrown.dev) is the other generative-UI library for
-Angular. Both let a model compose your components; they differ in what the
-model emits and in how much of the agent around it they provide. Compared
-against `@hashbrownai/angular` 0.6.1, as published on 2026-09-30:
-
-|                      | ngx-json-render                                                                                                                                                          | Hashbrown                                                                                                                                            |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| What the model emits | A json-render spec, streamed as RFC 6902 patches — the format the React, Vue, Svelte and Solid renderers read, so a catalog and a spec move between frameworks unchanged | Hashbrown's own JSON, generated against a schema built from the components you expose; read by Hashbrown's Angular and React clients                 |
-| Server               | Anything that streams text: the [AI SDK](https://ai-sdk.dev) in a few lines, or your own endpoint; `catalog.prompt()` writes the system prompt                           | An [AG-UI](https://docs.ag-ui.com) endpoint, built with Hashbrown's adapters (OpenAI, Anthropic, Google, Azure, Bedrock, Ollama) or your own mapping |
-| Angular              | 20, 21 and 22, each tested in CI                                                                                                                                         | 22 only since 0.6 (0.5 supported 20 and 21)                                                                                                          |
-| Components           | Your own, or 33 ready-made Angular Material ones ([`ngx-json-render-material`](https://www.npmjs.com/package/ngx-json-render-material))                                  | Your own (`exposeComponent`, UI kits)                                                                                                                |
-| Beyond rendering     | Rendering-focused: state and two-way bindings in the spec, actions, visibility, repeat, watch, confirmation dialogs                                                      | An agent toolkit: client-side tools, a QuickJS sandbox for model-written code, shared agent state, interrupts, streaming Markdown                    |
-| License              | Apache-2.0                                                                                                                                                               | MIT                                                                                                                                                  |
-
-Reach for Hashbrown when you want the agent loop — tools, a sandbox, AG-UI —
-from one library and are on Angular 22. Reach for this one when you want an
-open spec format that is not tied to Angular or to one vendor's client, a
-server you already have, Angular 20 or 21, or a UI that renders from a
-ready-made Material catalog before you have written a component.
-
 ## Quick start
 
 **1. Define a catalog** — the vocabulary the model (or your server) is allowed to use:
@@ -472,6 +450,117 @@ this package's, and both silent when you get them wrong:
 writes the chunks a server route would, reads the message a client would —
 and asserts both of these, so this section cannot quietly go stale.
 
+### From an AG-UI agent
+
+[AG-UI](https://docs.ag-ui.com) is the event protocol CopilotKit, LangGraph and
+others speak between an agent and its frontend. A json-render spec travels on
+it as an **activity** with `activityType: "json-render-spec"`
+(`JSON_RENDER_ACTIVITY_TYPE`): `ACTIVITY_SNAPSHOT` carries a whole spec in
+`content`, and `ACTIVITY_DELTA` carries RFC 6902 patches against it in `patch`
+— the same patches a JSONL stream is made of. `ngx-json-render/ag-ui` reads
+that, and needs nothing from `@ag-ui/*` at runtime: it accepts any agent and
+event of the right shape.
+
+With an `@ag-ui/client` agent, `injectAgentUI` gives the signals `injectUIStream`
+gives. The app keeps running the agent; the hook only listens, so it sees every
+run whoever starts it, and checks each spec when the run ends:
+
+```ts
+import { Component } from '@angular/core';
+import { HttpAgent } from '@ag-ui/client';
+import { JsonRenderer } from 'ngx-json-render';
+import { injectAgentUI } from 'ngx-json-render/ag-ui';
+import { catalog } from './catalog';
+
+@Component({
+  imports: [JsonRenderer],
+  template: `
+    <json-render [spec]="ui.spec()" [loading]="ui.isStreaming()" />
+    <button (click)="ask('show me revenue for the quarter')">Ask</button>
+  `,
+})
+export class AgentPage {
+  readonly agent = new HttpAgent({ url: '/api/agent' });
+  readonly ui = injectAgentUI({ agent: this.agent, catalog, validate: 'warn' });
+
+  ask(text: string) {
+    this.agent.addMessage({ id: crypto.randomUUID(), role: 'user', content: text });
+    this.agent.runAgent();
+  }
+}
+```
+
+`ui.surfaces()` lists every spec the agent has built, keyed by the activity's
+`messageId`, for a run that opens more than one; `ui.spec()` is the latest.
+Elements a delta does not touch keep their identity, so the renderer skips
+them. Without the hook, `applyAgUiEvent(surfaces, event)` is the same fold as a
+pure function.
+
+**In a CopilotKit Angular app**, register the ready-made activity renderer.
+It draws the spec with the registry and catalog from `provideJsonRender`:
+
+```ts
+import { provideJsonRender } from 'ngx-json-render';
+import { jsonRenderActivityRenderer } from 'ngx-json-render/ag-ui';
+
+providers: [
+  provideJsonRender({ registry }),
+  provideCopilotKit({
+    runtimeUrl: '/api/copilotkit',
+    renderActivityMessages: [jsonRenderActivityRenderer()],
+  }),
+];
+```
+
+**On the server**, the model's output — prose with ` ```spec ` fenced JSONL,
+as `catalog.prompt({ mode: 'inline' })` asks for — splits into text-message
+events and activity deltas with `createMixedStreamParser` from
+`@json-render/core`, and `EventEncoder` from `@ag-ui/encoder` writes the
+server-sent events:
+
+```ts
+// server.ts — an AG-UI endpoint (Express)
+import { EventType, type BaseEvent, type RunAgentInput } from '@ag-ui/core';
+import { EventEncoder } from '@ag-ui/encoder';
+import { createMixedStreamParser } from '@json-render/core';
+
+app.post('/api/agent', async (req, res) => {
+  const { threadId, runId, messages } = req.body as RunAgentInput;
+  const encoder = new EventEncoder({ accept: req.headers.accept });
+  const send = (event: BaseEvent) => res.write(encoder.encode(event));
+  res.setHeader('Content-Type', encoder.getContentType());
+
+  const textId = crypto.randomUUID();
+  const uiId = crypto.randomUUID();
+  send({ type: EventType.RUN_STARTED, threadId, runId } as BaseEvent);
+  send({ type: EventType.TEXT_MESSAGE_START, messageId: textId, role: 'assistant' } as BaseEvent);
+  send({ type: EventType.ACTIVITY_SNAPSHOT, messageId: uiId, activityType: 'json-render-spec',
+         content: { root: '', elements: {} } } as BaseEvent);
+
+  const parser = createMixedStreamParser({
+    onText: (line) => send({ type: EventType.TEXT_MESSAGE_CONTENT, messageId: textId,
+                             delta: line + '\n' } as BaseEvent),
+    onPatch: (patch) => send({ type: EventType.ACTIVITY_DELTA, messageId: uiId,
+                               activityType: 'json-render-spec', patch: [patch] } as BaseEvent),
+  });
+  const result = streamText({
+    model: anthropic('claude-sonnet-5'),
+    system: catalog.prompt({ mode: 'inline' }),
+    messages: toModelMessages(messages), // AG-UI user/assistant messages → your model's format
+  });
+  for await (const chunk of result.textStream) parser.push(chunk);
+  parser.flush();
+
+  send({ type: EventType.TEXT_MESSAGE_END, messageId: textId } as BaseEvent);
+  send({ type: EventType.RUN_FINISHED, threadId, runId } as BaseEvent);
+  res.end();
+});
+```
+
+`projects/ngx-json-render/ag-ui/src/ag-ui.spec.ts` runs a real `HttpAgent`
+against a replayed server-sent stream, through AG-UI's own decoder and event
+checks, and renders the result.
+
 ### Supplying the transport
 
 By default the request goes through the global `fetch`. Pass your own to add
@@ -1089,6 +1178,8 @@ MCP Apps (`ngx-json-render/mcp`): `injectJsonRenderApp`, `parseSpecFromToolResul
 
 Router (`ngx-json-render/router`): `injectRouterNavigate`, and the type `RouterNavigateOptions`. Needs the optional peer `@angular/router`, which an Angular app on the router already has.
 
+AG-UI (`ngx-json-render/ag-ui`): `injectAgentUI`, `applyAgUiEvent`, `surfacesFromMessages`, `isJsonRenderSpec`, `JsonRenderActivity` (`<json-render-activity>`), `jsonRenderActivityRenderer`, `JSON_RENDER_ACTIVITY_TYPE`, and the types `AgUiAgent`, `AgUiEvent`, `AgUiMessage`, `AgUiSubscriber`, `AgUiSurface`, `AgentUIOptions`, `AgentUIReturn`, `JsonRenderActivityRendererConfig`, `JsonRenderActivityRendererOptions`. No peer: any agent and event of the right shape will do.
+
 Devtools (`ngx-json-render/devtools`): `JsonRenderDevtools` (`<json-render-devtools>`), and the types `DevtoolsEvent`, `PanelPosition`. Needs the optional peer `@json-render/devtools`.
 
 Testing (`ngx-json-render/testing`): `renderSpec`, `renderComponent`, `recordedTransport`, `specStream`, `usageLine`.

package/fesm2022/ngx-json-render-ag-ui.mjs

@@ -0,0 +1,308 @@
+import { applyPatch, checkSpec, formatSpecCheckIssues, JsonRenderer } from 'ngx-json-render';
+import * as i0 from '@angular/core';
+import { signal, inject, DestroyRef, computed, input, Component } from '@angular/core';
+
+/**
+ * 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.
+ */
+const JSON_RENDER_ACTIVITY_TYPE = 'json-render-spec';
+const EMPTY_SPEC = { root: '', elements: {} };
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 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.
+ */
+function isJsonRenderSpec(content) {
+    return (isRecord(content) &&
+        typeof content['root'] === 'string' &&
+        isRecord(content['elements']));
+}
+function isPatch(value) {
+    return (isRecord(value) &&
+        typeof value['op'] === 'string' &&
+        typeof value['path'] === 'string');
+}
+function upsert(surfaces, messageId, spec) {
+    const index = surfaces.findIndex((s) => s.messageId === messageId);
+    if (index === -1)
+        return [...surfaces, { messageId, spec }];
+    const next = [...surfaces];
+    next[index] = { messageId, spec };
+    return next;
+}
+/**
+ * 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.
+ */
+function surfacesFromMessages(messages, activityType = JSON_RENDER_ACTIVITY_TYPE) {
+    const surfaces = [];
+    for (const message of messages) {
+        const m = message;
+        if (m.role === 'activity' &&
+            m['activityType'] === activityType &&
+            isJsonRenderSpec(m['content'])) {
+            surfaces.push({ messageId: m.id, spec: m['content'] });
+        }
+    }
+    return surfaces;
+}
+/**
+ * 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.
+ */
+function applyAgUiEvent(surfaces, event, activityType = JSON_RENDER_ACTIVITY_TYPE) {
+    const e = event;
+    switch (e.type) {
+        case 'ACTIVITY_SNAPSHOT': {
+            const messageId = e['messageId'];
+            if (typeof messageId !== 'string' || e['activityType'] !== activityType) {
+                return surfaces;
+            }
+            const content = e['content'];
+            if (!isJsonRenderSpec(content))
+                return surfaces;
+            // `replace: false` means "only if new": the client already has a
+            // version of this surface it should keep.
+            if (e['replace'] === false &&
+                surfaces.some((s) => s.messageId === messageId)) {
+                return surfaces;
+            }
+            return upsert(surfaces, messageId, content);
+        }
+        case 'ACTIVITY_DELTA': {
+            const messageId = e['messageId'];
+            const patch = e['patch'];
+            if (typeof messageId !== 'string' ||
+                e['activityType'] !== activityType ||
+                !Array.isArray(patch)) {
+                return surfaces;
+            }
+            const current = surfaces.find((s) => s.messageId === messageId)?.spec ?? EMPTY_SPEC;
+            let spec = current;
+            for (const op of patch) {
+                if (isPatch(op))
+                    spec = applyPatch(spec, op);
+            }
+            return spec === current ? surfaces : upsert(surfaces, messageId, spec);
+        }
+        case 'MESSAGES_SNAPSHOT': {
+            const messages = e['messages'];
+            if (!Array.isArray(messages))
+                return surfaces;
+            // AG-UI's rule: a snapshot that carries any activity message carries
+            // all of them, and one that carries none leaves the client's alone.
+            const carriesActivities = messages.some((m) => isRecord(m) && m['role'] === 'activity');
+            if (!carriesActivities)
+                return surfaces;
+            return surfacesFromMessages(messages, activityType);
+        }
+        default:
+            return surfaces;
+    }
+}
+
+/**
+ * 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()" />
+ * ```
+ */
+function injectAgentUI(options) {
+    const activityType = options.activityType ?? JSON_RENDER_ACTIVITY_TYPE;
+    const validate = options.validate ?? 'off';
+    const checkOptions = {
+        limits: options.renderLimits ?? null,
+        catalog: options.catalog ?? null,
+    };
+    const surfaces = signal(surfacesFromMessages(options.agent.messages ?? [], activityType), ...(ngDevMode ? [{ debugName: "surfaces" }] : /* istanbul ignore next */ []));
+    const isStreaming = signal(false, ...(ngDevMode ? [{ debugName: "isStreaming" }] : /* istanbul ignore next */ []));
+    const error = signal(null, ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
+    const issues = signal([], ...(ngDevMode ? [{ debugName: "issues" }] : /* istanbul ignore next */ []));
+    // Per run: which surfaces it changed, and whether it already failed.
+    let touched = new Set();
+    let failed = false;
+    const fail = (err) => {
+        failed = true;
+        error.set(err);
+        options.onError?.(err);
+    };
+    const finish = () => {
+        const found = [];
+        let next = surfaces();
+        for (const messageId of touched) {
+            const surface = next.find((s) => s.messageId === messageId);
+            if (!surface)
+                continue; // a later MESSAGES_SNAPSHOT dropped it
+            const check = checkSpec(surface.spec, validate, checkOptions);
+            found.push(...check.issues);
+            if (check.spec && check.spec !== surface.spec) {
+                const fixed = check.spec;
+                next = next.map((s) => s.messageId === messageId ? { messageId, spec: fixed } : s);
+            }
+            if (check.blocked || (validate === 'strict' && check.hasErrors)) {
+                fail(new Error(`Generated spec failed validation:\n${formatSpecCheckIssues(check.issues)}`));
+                continue;
+            }
+            options.onComplete?.(check.spec ?? surface.spec, messageId);
+        }
+        surfaces.set(next);
+        issues.set(found);
+    };
+    const subscription = options.agent.subscribe({
+        onRunInitialized() {
+            touched = new Set();
+            failed = false;
+            isStreaming.set(true);
+            error.set(null);
+            issues.set([]);
+        },
+        onEvent({ event }) {
+            const before = surfaces();
+            const after = applyAgUiEvent(before, event, activityType);
+            if (after === before)
+                return;
+            for (const surface of after) {
+                if (!before.includes(surface))
+                    touched.add(surface.messageId);
+            }
+            surfaces.set(after);
+        },
+        onRunErrorEvent({ event }) {
+            fail(new Error(event.message));
+        },
+        onRunFailed({ error: err }) {
+            // A RUN_ERROR event already reported this run; the client then fails
+            // the run with the same message.
+            if (!failed)
+                fail(err instanceof Error ? err : new Error(String(err)));
+        },
+        onRunFinalized() {
+            if (!failed)
+                finish();
+            isStreaming.set(false);
+        },
+    });
+    inject(DestroyRef).onDestroy(() => subscription.unsubscribe());
+    const spec = computed(() => surfaces().at(-1)?.spec ?? null, ...(ngDevMode ? [{ debugName: "spec" }] : /* istanbul ignore next */ []));
+    return {
+        surfaces: surfaces.asReadonly(),
+        spec,
+        isStreaming: isStreaming.asReadonly(),
+        error: error.asReadonly(),
+        issues: issues.asReadonly(),
+    };
+}
+
+/**
+ * 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.
+ */
+class JsonRenderActivity {
+    activityType = input(JSON_RENDER_ACTIVITY_TYPE, ...(ngDevMode ? [{ debugName: "activityType" }] : /* istanbul ignore next */ []));
+    content = input.required(...(ngDevMode ? [{ debugName: "content" }] : /* istanbul ignore next */ []));
+    /** The AG-UI activity message; unused, accepted for the contract. */
+    message = input(...(ngDevMode ? [undefined, { debugName: "message" }] : /* istanbul ignore next */ []));
+    /** The agent that produced it; unused, accepted for the contract. */
+    agent = input(...(ngDevMode ? [undefined, { debugName: "agent" }] : /* istanbul ignore next */ []));
+    spec = computed(() => {
+        const content = this.content();
+        return isJsonRenderSpec(content) ? content : null;
+    }, ...(ngDevMode ? [{ debugName: "spec" }] : /* istanbul ignore next */ []));
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.25", ngImport: i0, type: JsonRenderActivity, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "21.2.25", type: JsonRenderActivity, isStandalone: true, selector: "json-render-activity", inputs: { activityType: { classPropertyName: "activityType", publicName: "activityType", isSignal: true, isRequired: false, transformFunction: null }, content: { classPropertyName: "content", publicName: "content", isSignal: true, isRequired: true, transformFunction: null }, message: { classPropertyName: "message", publicName: "message", isSignal: true, isRequired: false, transformFunction: null }, agent: { classPropertyName: "agent", publicName: "agent", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: `<json-render [spec]="spec()" />`, isInline: true, dependencies: [{ kind: "component", type: JsonRenderer, selector: "json-render", inputs: ["spec", "registry", "loading", "fallback", "validate", "renderLimits", "catalog", "state", "store", "handlers", "onAction", "navigate", "validationFunctions", "functions", "directives"], outputs: ["stateChange"] }] });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.25", ngImport: i0, type: JsonRenderActivity, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'json-render-activity',
+                    imports: [JsonRenderer],
+                    template: `<json-render [spec]="spec()" />`,
+                }]
+        }], propDecorators: { activityType: [{ type: i0.Input, args: [{ isSignal: true, alias: "activityType", required: false }] }], content: [{ type: i0.Input, args: [{ isSignal: true, alias: "content", required: true }] }], message: [{ type: i0.Input, args: [{ isSignal: true, alias: "message", required: false }] }], agent: [{ type: i0.Input, args: [{ isSignal: true, alias: "agent", required: false }] }] } });
+/**
+ * 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.
+ */
+function jsonRenderActivityRenderer(options = {}) {
+    return {
+        activityType: options.activityType ?? JSON_RENDER_ACTIVITY_TYPE,
+        ...(options.agentId !== undefined ? { agentId: options.agentId } : {}),
+        content: {
+            safeParse: (content) => isJsonRenderSpec(content)
+                ? { success: true, data: content }
+                : {
+                    success: false,
+                    error: new Error('Activity content is not a json-render spec: expected { root: string, elements: object }.'),
+                },
+        },
+        component: options.component ?? JsonRenderActivity,
+    };
+}
+
+/*
+ * Public API Surface of ngx-json-render/ag-ui
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { JSON_RENDER_ACTIVITY_TYPE, JsonRenderActivity, applyAgUiEvent, injectAgentUI, isJsonRenderSpec, jsonRenderActivityRenderer, surfacesFromMessages };
+//# sourceMappingURL=ngx-json-render-ag-ui.mjs.map

package/fesm2022/ngx-json-render-ag-ui.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ngx-json-render-ag-ui.mjs","sources":["../../../projects/ngx-json-render/ag-ui/src/events.ts","../../../projects/ngx-json-render/ag-ui/src/agent-ui.ts","../../../projects/ngx-json-render/ag-ui/src/json-render-activity.ts","../../../projects/ngx-json-render/ag-ui/src/public-api.ts","../../../projects/ngx-json-render/ag-ui/src/ngx-json-render-ag-ui.ts"],"sourcesContent":["import type { JsonPatch, Spec } from '@json-render/core';\nimport { applyPatch } from 'ngx-json-render';\n\n/**\n * The `activityType` a json-render spec travels under.\n *\n * An agent sends the spec as an AG-UI activity: `ACTIVITY_SNAPSHOT` carries a\n * whole spec in `content`, and `ACTIVITY_DELTA` carries RFC 6902 patches\n * against it in `patch` — the same patches a json-render JSONL stream is made\n * of. CopilotKit carries A2UI the same way, under `\"a2ui-surface\"`.\n *\n * The name says both the format and what `content` holds — a `Spec`, the\n * object upstream calls a spec in its AI SDK part type `data-spec` — so a\n * renderer for another framework can match it without reading these docs.\n */\nexport const JSON_RENDER_ACTIVITY_TYPE = 'json-render-spec';\n\n/**\n * The part of an AG-UI event this entry point reads.\n *\n * Structural on purpose: `@ag-ui/core`'s `EventType` is a string enum, so its\n * events fit a `string` here, and nothing below needs the package at runtime\n * or pins its version.\n */\nexport interface AgUiEvent {\n  readonly type: string;\n}\n\n/** The part of an AG-UI message this entry point reads. */\nexport interface AgUiMessage {\n  readonly id: string;\n  readonly role: string;\n}\n\n/** One spec an agent is building, keyed by its activity message. */\nexport interface AgUiSurface {\n  /** The activity's `messageId`; one run can build several surfaces. */\n  readonly messageId: string;\n  readonly spec: Spec;\n}\n\nconst EMPTY_SPEC: Spec = { root: '', elements: {} };\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/**\n * Whether activity content has the shape of a spec. Only the shape: what the\n * elements say is the renderer's and the finished-spec check's business.\n */\nexport function isJsonRenderSpec(content: unknown): content is Spec {\n  return (\n    isRecord(content) &&\n    typeof content['root'] === 'string' &&\n    isRecord(content['elements'])\n  );\n}\n\nfunction isPatch(value: unknown): value is JsonPatch {\n  return (\n    isRecord(value) &&\n    typeof value['op'] === 'string' &&\n    typeof value['path'] === 'string'\n  );\n}\n\nfunction upsert(\n  surfaces: readonly AgUiSurface[],\n  messageId: string,\n  spec: Spec,\n): readonly AgUiSurface[] {\n  const index = surfaces.findIndex((s) => s.messageId === messageId);\n  if (index === -1) return [...surfaces, { messageId, spec }];\n  const next = [...surfaces];\n  next[index] = { messageId, spec };\n  return next;\n}\n\n/**\n * The surfaces an AG-UI message list holds, in message order.\n *\n * Used for `MESSAGES_SNAPSHOT` and to pick up the history an agent already\n * has when a hook attaches to it.\n */\nexport function surfacesFromMessages(\n  messages: readonly AgUiMessage[],\n  activityType: string = JSON_RENDER_ACTIVITY_TYPE,\n): readonly AgUiSurface[] {\n  const surfaces: AgUiSurface[] = [];\n  for (const message of messages) {\n    const m = message as AgUiMessage & Record<string, unknown>;\n    if (\n      m.role === 'activity' &&\n      m['activityType'] === activityType &&\n      isJsonRenderSpec(m['content'])\n    ) {\n      surfaces.push({ messageId: m.id, spec: m['content'] });\n    }\n  }\n  return surfaces;\n}\n\n/**\n * Fold one AG-UI event into the surfaces built so far.\n *\n * Returns the same array when the event does not concern json-render, so a\n * signal holding the result only notifies on a real change. A delta applies\n * through the same immutable patch engine as a JSONL stream: elements it does\n * not touch keep their identity, and the renderer skips them.\n *\n * Two leniencies, both in the direction of rendering what arrived:\n * - a delta for a surface no snapshot has opened starts from an empty spec,\n *   so an agent can stream patches the way a JSONL endpoint does;\n * - a malformed patch op is dropped rather than failing the surface.\n */\nexport function applyAgUiEvent(\n  surfaces: readonly AgUiSurface[],\n  event: AgUiEvent,\n  activityType: string = JSON_RENDER_ACTIVITY_TYPE,\n): readonly AgUiSurface[] {\n  const e = event as AgUiEvent & Record<string, unknown>;\n  switch (e.type) {\n    case 'ACTIVITY_SNAPSHOT': {\n      const messageId = e['messageId'];\n      if (typeof messageId !== 'string' || e['activityType'] !== activityType) {\n        return surfaces;\n      }\n      const content = e['content'];\n      if (!isJsonRenderSpec(content)) return surfaces;\n      // `replace: false` means \"only if new\": the client already has a\n      // version of this surface it should keep.\n      if (\n        e['replace'] === false &&\n        surfaces.some((s) => s.messageId === messageId)\n      ) {\n        return surfaces;\n      }\n      return upsert(surfaces, messageId, content);\n    }\n    case 'ACTIVITY_DELTA': {\n      const messageId = e['messageId'];\n      const patch = e['patch'];\n      if (\n        typeof messageId !== 'string' ||\n        e['activityType'] !== activityType ||\n        !Array.isArray(patch)\n      ) {\n        return surfaces;\n      }\n      const current =\n        surfaces.find((s) => s.messageId === messageId)?.spec ?? EMPTY_SPEC;\n      let spec = current;\n      for (const op of patch) {\n        if (isPatch(op)) spec = applyPatch(spec, op);\n      }\n      return spec === current ? surfaces : upsert(surfaces, messageId, spec);\n    }\n    case 'MESSAGES_SNAPSHOT': {\n      const messages = e['messages'];\n      if (!Array.isArray(messages)) return surfaces;\n      // AG-UI's rule: a snapshot that carries any activity message carries\n      // all of them, and one that carries none leaves the client's alone.\n      const carriesActivities = messages.some(\n        (m) => isRecord(m) && m['role'] === 'activity',\n      );\n      if (!carriesActivities) return surfaces;\n      return surfacesFromMessages(messages as AgUiMessage[], activityType);\n    }\n    default:\n      return surfaces;\n  }\n}\n","import {\n  DestroyRef,\n  type Signal,\n  computed,\n  inject,\n  signal,\n} from '@angular/core';\nimport type { Spec } from '@json-render/core';\nimport {\n  type RenderLimits,\n  type SpecCatalog,\n  type SpecCheckIssue,\n  type SpecValidationMode,\n  checkSpec,\n  formatSpecCheckIssues,\n} from 'ngx-json-render';\nimport {\n  type AgUiEvent,\n  type AgUiMessage,\n  type AgUiSurface,\n  JSON_RENDER_ACTIVITY_TYPE,\n  applyAgUiEvent,\n  surfacesFromMessages,\n} from './events';\n\n/**\n * The callbacks of an AG-UI subscriber this entry point uses — a subset of\n * `@ag-ui/client`'s `AgentSubscriber`.\n */\nexport interface AgUiSubscriber {\n  onRunInitialized?(): void;\n  onEvent?(params: { event: AgUiEvent }): void;\n  onRunErrorEvent?(params: { event: { message: string } }): void;\n  onRunFailed?(params: { error: Error }): void;\n  onRunFinalized?(): void;\n}\n\n/**\n * What {@link injectAgentUI} needs of an agent. Any `@ag-ui/client` agent —\n * `HttpAgent`, a subclass of `AbstractAgent`, the agent CopilotKit hands out —\n * already has this shape.\n */\nexport interface AgUiAgent {\n  readonly messages?: readonly AgUiMessage[];\n  subscribe(subscriber: AgUiSubscriber): { unsubscribe(): void };\n}\n\n/** Options for {@link injectAgentUI}. */\nexport interface AgentUIOptions {\n  /** The agent whose runs build the UI. The app runs it; the hook listens. */\n  agent: AgUiAgent;\n  /** Defaults to {@link JSON_RENDER_ACTIVITY_TYPE}. */\n  activityType?: string;\n  /**\n   * Called once per surface a run touched, after the finished-spec check.\n   * Skipped for a run that failed, and for a surface the check rejected.\n   */\n  onComplete?: (spec: Spec, messageId: string) => void;\n  /** Called when a run fails or a finished surface fails the check. */\n  onError?: (error: Error) => void;\n  /** As for `injectUIStream`: checked once per surface, when the run ends. */\n  validate?: SpecValidationMode;\n  /** As for `injectUIStream`; enforced whatever `validate` is. */\n  renderLimits?: RenderLimits | null;\n  /** As for `injectUIStream`: lets `validate` check types and props. */\n  catalog?: SpecCatalog | null;\n}\n\n/** Return type of {@link injectAgentUI}. */\nexport interface AgentUIReturn {\n  /** Every json-render surface the agent has built, in order of appearance. */\n  readonly surfaces: Signal<readonly AgUiSurface[]>;\n  /** The most recently opened surface's spec — the one most apps render. */\n  readonly spec: Signal<Spec | null>;\n  /** Whether a run of the agent is in progress. */\n  readonly isStreaming: Signal<boolean>;\n  /** The last run's error, if any. */\n  readonly error: Signal<Error | null>;\n  /** What the check found in the surfaces the last run finished. */\n  readonly issues: Signal<readonly SpecCheckIssue[]>;\n}\n\n/**\n * Render what an AG-UI agent streams. Subscribes to the agent, folds every\n * json-render activity it emits into signals, and checks each surface when\n * the run ends — the same contract as `injectUIStream`, with the agent in\n * place of the endpoint.\n *\n * The app keeps running the agent itself (`agent.runAgent()`, CopilotKit, a\n * reconnect); the hook only listens, so it sees every run, whoever starts it.\n * It starts from whatever surfaces are already in the agent's messages and\n * unsubscribes on destroy.\n *\n * @example\n * ```ts\n * export class AgentPage {\n *   readonly agent = new HttpAgent({ url: '/api/agent' });\n *   readonly ui = injectAgentUI({ agent: this.agent, catalog });\n *   ask(text: string) {\n *     this.agent.addMessage({ id: crypto.randomUUID(), role: 'user', content: text });\n *     this.agent.runAgent();\n *   }\n * }\n * // template:\n * // <json-render [spec]=\"ui.spec()\" [registry]=\"registry\" [loading]=\"ui.isStreaming()\" />\n * ```\n */\nexport function injectAgentUI(options: AgentUIOptions): AgentUIReturn {\n  const activityType = options.activityType ?? JSON_RENDER_ACTIVITY_TYPE;\n  const validate = options.validate ?? 'off';\n  const checkOptions = {\n    limits: options.renderLimits ?? null,\n    catalog: options.catalog ?? null,\n  };\n\n  const surfaces = signal<readonly AgUiSurface[]>(\n    surfacesFromMessages(options.agent.messages ?? [], activityType),\n  );\n  const isStreaming = signal(false);\n  const error = signal<Error | null>(null);\n  const issues = signal<readonly SpecCheckIssue[]>([]);\n\n  // Per run: which surfaces it changed, and whether it already failed.\n  let touched = new Set<string>();\n  let failed = false;\n\n  const fail = (err: Error) => {\n    failed = true;\n    error.set(err);\n    options.onError?.(err);\n  };\n\n  const finish = () => {\n    const found: SpecCheckIssue[] = [];\n    let next = surfaces();\n    for (const messageId of touched) {\n      const surface = next.find((s) => s.messageId === messageId);\n      if (!surface) continue; // a later MESSAGES_SNAPSHOT dropped it\n      const check = checkSpec(surface.spec, validate, checkOptions);\n      found.push(...check.issues);\n      if (check.spec && check.spec !== surface.spec) {\n        const fixed = check.spec;\n        next = next.map((s) =>\n          s.messageId === messageId ? { messageId, spec: fixed } : s,\n        );\n      }\n      if (check.blocked || (validate === 'strict' && check.hasErrors)) {\n        fail(\n          new Error(\n            `Generated spec failed validation:\\n${formatSpecCheckIssues(check.issues)}`,\n          ),\n        );\n        continue;\n      }\n      options.onComplete?.(check.spec ?? surface.spec, messageId);\n    }\n    surfaces.set(next);\n    issues.set(found);\n  };\n\n  const subscription = options.agent.subscribe({\n    onRunInitialized() {\n      touched = new Set();\n      failed = false;\n      isStreaming.set(true);\n      error.set(null);\n      issues.set([]);\n    },\n    onEvent({ event }) {\n      const before = surfaces();\n      const after = applyAgUiEvent(before, event, activityType);\n      if (after === before) return;\n      for (const surface of after) {\n        if (!before.includes(surface)) touched.add(surface.messageId);\n      }\n      surfaces.set(after);\n    },\n    onRunErrorEvent({ event }) {\n      fail(new Error(event.message));\n    },\n    onRunFailed({ error: err }) {\n      // A RUN_ERROR event already reported this run; the client then fails\n      // the run with the same message.\n      if (!failed) fail(err instanceof Error ? err : new Error(String(err)));\n    },\n    onRunFinalized() {\n      if (!failed) finish();\n      isStreaming.set(false);\n    },\n  });\n\n  inject(DestroyRef).onDestroy(() => subscription.unsubscribe());\n\n  const spec = computed(() => surfaces().at(-1)?.spec ?? null);\n\n  return {\n    surfaces: surfaces.asReadonly(),\n    spec,\n    isStreaming: isStreaming.asReadonly(),\n    error: error.asReadonly(),\n    issues: issues.asReadonly(),\n  };\n}\n","import { Component, type Type, computed, input } from '@angular/core';\nimport type { Spec } from '@json-render/core';\nimport { JsonRenderer } from 'ngx-json-render';\nimport { JSON_RENDER_ACTIVITY_TYPE, isJsonRenderSpec } from './events';\n\n/**\n * Renders one json-render activity message. It takes the inputs every AG-UI\n * activity renderer is given — CopilotKit Angular's `ActivityRenderer`\n * contract — and draws `content` with `<json-render>`, which takes its\n * registry, catalog and handlers from the nearest `provideJsonRender`.\n *\n * Register it with {@link jsonRenderActivityRenderer} rather than by hand.\n */\n@Component({\n  selector: 'json-render-activity',\n  imports: [JsonRenderer],\n  template: `<json-render [spec]=\"spec()\" />`,\n})\nexport class JsonRenderActivity {\n  readonly activityType = input<string>(JSON_RENDER_ACTIVITY_TYPE);\n  readonly content = input.required<unknown>();\n  /** The AG-UI activity message; unused, accepted for the contract. */\n  readonly message = input<unknown>();\n  /** The agent that produced it; unused, accepted for the contract. */\n  readonly agent = input<unknown>();\n\n  protected readonly spec = computed<Spec | null>(() => {\n    const content = this.content();\n    return isJsonRenderSpec(content) ? content : null;\n  });\n}\n\n/** Options for {@link jsonRenderActivityRenderer}. */\nexport interface JsonRenderActivityRendererOptions {\n  /** Defaults to {@link JSON_RENDER_ACTIVITY_TYPE}. */\n  activityType?: string;\n  /** Limit the renderer to one agent's activities. */\n  agentId?: string;\n  /** A component of your own in place of {@link JsonRenderActivity}. */\n  component?: Type<unknown>;\n}\n\n/**\n * An activity renderer config in the shape CopilotKit Angular's\n * `renderActivityMessages` takes, matched structurally so this package does\n * not depend on CopilotKit.\n */\nexport interface JsonRenderActivityRendererConfig {\n  activityType: string;\n  agentId?: string;\n  content: {\n    safeParse(\n      content: unknown,\n    ): { success: true; data: Spec } | { success: false; error?: unknown };\n  };\n  component: Type<any>;\n}\n\n/**\n * Teach a CopilotKit Angular app to render json-render activities:\n *\n * ```ts\n * providers: [\n *   provideJsonRender({ registry }),\n *   provideCopilotKit({\n *     runtimeUrl: '/api/copilotkit',\n *     renderActivityMessages: [jsonRenderActivityRenderer()],\n *   }),\n * ]\n * ```\n *\n * Content that is not a spec is rejected by the config's schema, so CopilotKit\n * skips the message with a warning instead of mounting an empty renderer.\n */\nexport function jsonRenderActivityRenderer(\n  options: JsonRenderActivityRendererOptions = {},\n): JsonRenderActivityRendererConfig {\n  return {\n    activityType: options.activityType ?? JSON_RENDER_ACTIVITY_TYPE,\n    ...(options.agentId !== undefined ? { agentId: options.agentId } : {}),\n    content: {\n      safeParse: (content) =>\n        isJsonRenderSpec(content)\n          ? { success: true, data: content }\n          : {\n              success: false,\n              error: new Error(\n                'Activity content is not a json-render spec: expected { root: string, elements: object }.',\n              ),\n            },\n    },\n    component: options.component ?? JsonRenderActivity,\n  };\n}\n","/*\n * Public API Surface of ngx-json-render/ag-ui\n */\n\nexport {\n  JSON_RENDER_ACTIVITY_TYPE,\n  applyAgUiEvent,\n  isJsonRenderSpec,\n  surfacesFromMessages,\n  type AgUiEvent,\n  type AgUiMessage,\n  type AgUiSurface,\n} from './events';\nexport {\n  injectAgentUI,\n  type AgUiAgent,\n  type AgUiSubscriber,\n  type AgentUIOptions,\n  type AgentUIReturn,\n} from './agent-ui';\nexport {\n  JsonRenderActivity,\n  jsonRenderActivityRenderer,\n  type JsonRenderActivityRendererConfig,\n  type JsonRenderActivityRendererOptions,\n} from './json-render-activity';\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Generative UI for Angular: a json-render renderer that streams AI-generated JSON specs into real Angular components with signals.",
   "keywords": [
     "angular",
@@ -65,6 +65,10 @@
       "types": "./types/ngx-json-render.d.ts",
       "default": "./fesm2022/ngx-json-render.mjs"
     },
+    "./ag-ui": {
+      "types": "./types/ngx-json-render-ag-ui.d.ts",
+      "default": "./fesm2022/ngx-json-render-ag-ui.mjs"
+    },
     "./devtools": {
       "types": "./types/ngx-json-render-devtools.d.ts",
       "default": "./fesm2022/ngx-json-render-devtools.mjs"

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 };