ngx-json-render 0.1.1 → 0.1.3

package/README.md

@@ -1,10 +1,16 @@
 # ngx-json-render
 
+[![npm](https://img.shields.io/npm/v/ngx-json-render)](https://www.npmjs.com/package/ngx-json-render) [![CI](https://github.com/shteynu/ngx-json-render/actions/workflows/ci.yml/badge.svg)](https://github.com/shteynu/ngx-json-render/actions/workflows/ci.yml) [![license](https://img.shields.io/npm/l/ngx-json-render)](https://github.com/shteynu/ngx-json-render/blob/main/LICENSE)
+
 Angular renderer for [json-render](https://github.com/vercel-labs/json-render) — give an LLM a catalog of your components, stream back a JSON spec, and render it as real Angular components. No `innerHTML`, no `eval`, no framework lock-in on the wire format.
 
 Built on `@json-render/core` (the same spec format, expressions, state store, actions, and streaming compiler used by the React, Vue, Solid, and Svelte renderers) and idiomatic modern Angular: standalone components, signals, zoneless-friendly, `OnPush` everywhere.
 
-**[Live demo](https://shteynu.github.io/ngx-json-render/)** — interactive spec (bindings, repeat, confirm, watch) and a replayable SpecStream showing progressive rendering ([source](https://github.com/shteynu/ngx-json-render/tree/main/projects/demo)).
+This is an Angular **adapter over the official core**, not a second implementation of it — `@json-render/core` is a peer dependency, and the spec your model emits is the same one the React, Vue, Solid and Svelte renderers consume. A catalog and a spec written here move to another framework unchanged.
+
+**[Live demo](https://shteynu.github.io/ngx-json-render/)** — interactive spec (bindings, repeat, confirm, watch) and a replayable SpecStream showing progressive rendering ([source](https://github.com/shteynu/ngx-json-render/tree/main/projects/demo)) — or [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/shteynu/ngx-json-render)
+
+![A SpecStream of RFC 6902 patches rendering progressively into an Angular dashboard](https://raw.githubusercontent.com/shteynu/ngx-json-render/main/docs/streaming.gif)
 
 ## Install
 
@@ -12,7 +18,7 @@ Built on `@json-render/core` (the same spec format, expressions, state store, ac
 npm install ngx-json-render @json-render/core zod
 ```
 
-Requires Angular ≥ 21.
+Requires Angular ≥ 20.
 
 ## Quick start
 
@@ -138,9 +144,40 @@ export class GeneratePage {
 }
 ```
 
+### The server side
+
+`injectUIStream` POSTs `{ prompt, context, currentSpec }` to your endpoint and expects the response body to be SpecStream JSONL — one RFC 6902 patch per line. Any server that can stream text works; with the [AI SDK](https://ai-sdk.dev) it's a few lines — `catalog.prompt()` teaches the model your component vocabulary and the patch protocol:
+
+```ts
+// server.ts — Express shown; any Node server works the same way
+import express from 'express';
+import { streamText } from 'ai';
+import { anthropic } from '@ai-sdk/anthropic';
+import { catalog } from './catalog';
+
+const app = express();
+app.use(express.json());
+
+app.post('/api/generate', async (req, res) => {
+  const { prompt } = req.body; // injectUIStream sends { prompt, context, currentSpec }
+
+  const result = streamText({
+    model: anthropic('claude-sonnet-5'),
+    system: catalog.prompt(),
+    prompt,
+  });
+
+  res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+  for await (const chunk of result.textStream) res.write(chunk);
+  res.end();
+});
+```
+
+The patches apply to the `spec` signal as each line arrives, so the UI assembles on screen while the model is still generating — exactly what the [demo's Streaming tab](https://shteynu.github.io/ngx-json-render/) replays. Prefer structured output? `catalog.jsonSchema()` exports a JSON Schema for `streamObject`/tool calls, and `catalog.validate(spec)` checks a finished spec against the catalog.
+
 Also available:
 
-- `injectChatUI({ api })` — chat + GenUI: assistant messages carrying both prose and specs (` ```spec ` fenced JSONL).
+- `injectChatUI({ api })` — chat + GenUI: the endpoint takes `{ messages }` and streams prose mixed with ` ```spec ` fenced JSONL; each assistant message carries `text` and/or a `spec`.
 - `applyPatch(spec, patch)` — immutably apply one RFC 6902 patch to a spec.
 - `buildSpecFromParts` / `getTextFromParts` / `jsonRenderMessage` — derive specs from AI SDK `message.parts`.
 - `catalog.prompt()` / `buildUserPrompt` (from `@json-render/core`) — generate the system/user prompts for your catalog.
@@ -184,6 +221,54 @@ Share one store across renderers (or drive it from your own state management) by
 
 If a catalog component renders `<input [value]="ctx.props().value">`, remember that one-way bindings do not re-assert the DOM when the bound value returns to its previously applied value while the user typed in between (e.g. `pushState` + `clearStatePath`). Sync imperatively instead — see `InputComponent` in the demo app for the pattern.
 
+## Security
+
+Specs are attacker-shaped input: whatever produced one — a model, a prompt, a
+user's text inside that prompt — is not something you control. The renderer is
+built so that a hostile spec cannot execute code, but it can still act within
+the authority you hand it. What follows is what the renderer guarantees and
+what stays your responsibility.
+
+**A spec cannot execute code.** There is no `eval`, no `Function` constructor,
+and no `innerHTML`/`bypassSecurityTrust` anywhere in this package or in
+`@json-render/core`. Expressions (`$state`, `$item`, `$index`, `$bindState`)
+are interpreted against the state model, not evaluated as JavaScript, and all
+text reaches the DOM through Angular interpolation. Script injection through a
+spec is not a thing you have to defend against.
+
+**A spec can only name actions you registered.** Built-ins (`setState`,
+`pushState`, `removeState`, `push`, `pop`, `validateForm`) are handled inside
+the renderer; every other action name is looked up in the `handlers` you pass.
+An unrecognised name logs a warning and does nothing.
+
+The exception is `onAction`, which is a deliberate catch-all: when you pass it,
+**every** action name in the spec reaches it, including ones you never put in
+your catalog. If you use it, switch on the names you expect and ignore the
+rest.
+
+**A spec chooses its own state paths.** `setState`, `pushState`, `removeState`
+and `onSuccess.set` all take a `statePath` straight from the spec, so a
+generated UI can write anywhere in the state model it is rendered against —
+and `push`/`pop` write `/currentScreen` and `/navStack`. In controlled mode
+this is *your* store. Give the renderer a store scoped to the generated view
+rather than the one holding session, entitlement or billing state.
+
+**A spec chooses the navigation target.** `onSuccess: { navigate }` passes its
+string to the `navigate` callback you provide, verbatim. Treat it as untrusted:
+match it against known routes, and never hand it to `window.location` or
+`router.navigateByUrl` unchecked.
+
+**A spec sizes its own render tree.** `repeat` iterates a state array the spec
+may itself have supplied, so specs are a denial-of-service surface against the
+browser tab. Cap spec size and array lengths at the boundary where you accept
+one.
+
+**`confirm` is a UX affordance, not a security control.** It routes an action
+through the confirmation dialog before the handler runs, but it is set on the
+action binding *inside the spec* (`on.press.confirm`) — so the same party that
+chose the action also chose whether to ask. Real authorization belongs in the
+handler, on the server.
+
 ## API surface
 
 Components: `JsonRenderer` (`<json-render>`), `JrChildren`, `JrConfirmDialog`, `JrElement`, `JrRepeatScope`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Angular renderer for json-render — stream AI-generated JSON specs into real Angular components with signals.",
   "keywords": [
     "angular",
@@ -22,11 +22,12 @@
     "url": "https://github.com/shteynu/ngx-json-render/issues"
   },
   "peerDependencies": {
-    "@angular/common": ">=21.0.0",
-    "@angular/core": ">=21.0.0"
+    "@angular/common": ">=20.0.0",
+    "@angular/core": ">=20.0.0",
+    "@json-render/core": "^0.20.0",
+    "zod": "^4.0.0"
   },
   "dependencies": {
-    "@json-render/core": "^0.20.0",
     "tslib": "^2.3.0"
   },
   "sideEffects": false,