@brad-frost-web/eddie-render 0.65.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,127 @@
1
+ # @brad-frost-web/eddie-render
2
+
3
+ > The browser half of Eddie's generative-UI layer: a **surface host** that
4
+ > turns `a2ui-eddie/1.0` messages and SpecStream patches into Eddie DOM, a
5
+ > **validator** that refuses what the catalog does not allow, and a
6
+ > **composer kit** that streams a model's patches through that validator
7
+ > before anything reaches a page. Zero runtime dependencies.
8
+
9
+ ## Why this exists
10
+
11
+ A model asked to write a page writes HTML, and HTML has no rails: the
12
+ realtime-ui pilot's dashboard opened with a hero, invented slot names rendered
13
+ nothing, and the model's own narration ("I don't have enough context…") landed
14
+ in the DOM as prose. Every one of those is a *composition* error that the
15
+ design system already knows how to refuse, if the vocabulary is the catalog
16
+ rather than the alphabet.
17
+
18
+ So the model never writes markup. It emits **patches to a spec** whose nodes
19
+ are the catalog's (`DashboardPage`, `StatCard`, `Text`), a validator checks the
20
+ spec against the catalog's containment, props, slots, and anti-patterns, and
21
+ the host paints Eddie components by node id. What the catalog forbids cannot be
22
+ expressed; what it allows renders as the system intended. The strategy is
23
+ `docs/GENERATIVE-UI-STRATEGY.md`; the wire format is `docs/A2UI-EDDIE.md`.
24
+
25
+ ## Three entry points
26
+
27
+ | Import | Runs in | What it is |
28
+ |---|---|---|
29
+ | `@brad-frost-web/eddie-render` | browser | `createSurfaceHost` plus the spec, patch, and serializer helpers |
30
+ | `@brad-frost-web/eddie-render/validate` | anywhere | `validateSpec`, `toA2uiErrors`, the anti-pattern selector core |
31
+ | `@brad-frost-web/eddie-render/composer` | server | `createComposer`, `buildDigest` — a Messages API client that streams SpecStream lines through the validator |
32
+
33
+ The CDN build `cdn/eddie-render.js` carries the first entry point for
34
+ no-build pages.
35
+
36
+ ## The surface host
37
+
38
+ ```js
39
+ import { createSurfaceHost } from '@brad-frost-web/eddie-render';
40
+
41
+ const host = createSurfaceHost(document.getElementById('surface'), {
42
+ catalog: 'https://ds.bradfrost.com/catalog.json?profile=realtime',
43
+ scripts: false, // the page already loads Eddie
44
+ bind: (path) => clientState[path], // resolves { bind: "client" } data-model values
45
+ });
46
+ await host.ready;
47
+
48
+ // One turn: validate strictly, then commit or refuse.
49
+ const result = host.apply({
50
+ version: 'v1.0',
51
+ createSurface: { surfaceId: 'main', components: [{ id: 'page', component: 'DashboardPage', heading: 'Castle P&L', children: [] }] },
52
+ });
53
+ result.outcome; // 'committed' | 'refused'
54
+
55
+ // A streamed turn: paint provisionally as lines land, decide at the end.
56
+ const turn = host.beginTurn();
57
+ turn.push('{"op":"replace","path":"/elements/page/heading","value":"Castle P&L, YTD"}');
58
+ turn.end();
59
+
60
+ host.addEventListener('action', (e) => console.log(e.detail)); // A2UI action events
61
+ host.addEventListener('refusal', (e) => console.log(e.detail.issues));
62
+ ```
63
+
64
+ What the host guarantees:
65
+
66
+ - **Refusal is an outcome, not an exception.** A turn that fails strict
67
+ validation reverts to the previous spec, keeps the previous DOM, renders the
68
+ reasons in an `ed-alert` in the refusal region, and emits a `refusal` event.
69
+ - **Untouched nodes keep their element** across updates: scroll position,
70
+ open accordions, focus. Reconciliation is keyed by node id and resolved
71
+ props.
72
+ - **A streamed turn paints provisionally** (`data-eddie-provisional` on the
73
+ host element, hidden placeholders for children that have not arrived) and
74
+ produces the same DOM one `createSurface` would.
75
+ - **Composition nodes expand** through the catalog's `eddie_expansion`
76
+ template; primitives render their `eddie_tag` with scalar props as
77
+ attributes, objects as properties, `accessibility` as ARIA, `action` as an
78
+ A2UI action.
79
+ - **v0.8 messages still apply** (`surfaceUpdate`, `beginRendering`, the
80
+ `{ Name: { props } }` component shape), so the hub and Chameleon can migrate
81
+ on their own schedule.
82
+
83
+ ## The validator
84
+
85
+ ```js
86
+ import { validateSpec } from '@brad-frost-web/eddie-render/validate';
87
+
88
+ const { ok, issues, fixed } = validateSpec(spec, catalog, { autoFix: true, streaming: false });
89
+ ```
90
+
91
+ Errors refuse; warnings render. Codes: `MISSING_ROOT`, `UNKNOWN_COMPONENT`,
92
+ `VALIDATION_FAILED` (required / enum / type), `UNKNOWN_PROP` (warning; dropped
93
+ under `autoFix`), `UNKNOWN_SLOT`, `DANGLING_CHILD` (pending while `streaming`),
94
+ `CYCLE`, `UNALLOWED_PARENT`, `UNALLOWED_CHILD`, `ORPHAN` (warning),
95
+ `ANTI_PATTERN` (the graph's `@antipattern` rules evaluated on the expanded
96
+ tree), `A11Y` (heading order, one h1, labelled fields). `toA2uiErrors` maps
97
+ issues to A2UI's `error` message. The same function backs the Brain's
98
+ `eddie_validate_spec` MCP tool, and the Brain imports the selector core from
99
+ here so the two never drift.
100
+
101
+ ## The composer kit
102
+
103
+ ```js
104
+ import { createComposer } from '@brad-frost-web/eddie-render/composer';
105
+
106
+ const composer = createComposer({ catalog, apiKey, model: 'claude-haiku-4-5-20251001' });
107
+ for await (const ev of composer.compose({ spec, transcript })) {
108
+ // ev.type: 'patch' | 'reset' | 'refusal' | 'done'
109
+ }
110
+ ```
111
+
112
+ The digest of the catalog is sent as a cached system block, so an update pays
113
+ for the transcript and the spec, not the vocabulary. Prose is dropped, a
114
+ truncated final line is healed, a batch the validator refuses is re-prompted
115
+ once with the errors, and a turn that still fails leaves the spec untouched and
116
+ reports `mode: 'refused'`. `done` carries the spec, the mode
117
+ (`compose | update | noop | refused`), usage with cache tokens, and the issues.
118
+
119
+ ## Testing
120
+
121
+ ```bash
122
+ npm test # Node: spec, validator, composer; Chromium: the surface host
123
+ ```
124
+
125
+ The validator fixtures are realtime-ui's on-camera failures against the real
126
+ `realtime` catalog, so a catalog change that would let one of them through
127
+ fails here first.