@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 +127 -0
- package/cdn/eddie-render.js +947 -0
- package/cdn/eddie-render.js.map +1 -0
- package/dist/composer/index.d.ts +75 -0
- package/dist/composer/index.d.ts.map +1 -0
- package/dist/composer/index.js +292 -0
- package/dist/composer/index.js.map +1 -0
- package/dist/index.d.ts +26 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +26 -0
- package/dist/index.js.map +1 -0
- package/dist/render.d.ts +92 -0
- package/dist/render.d.ts.map +1 -0
- package/dist/render.js +457 -0
- package/dist/render.js.map +1 -0
- package/dist/serialize.d.ts +29 -0
- package/dist/serialize.d.ts.map +1 -0
- package/dist/serialize.js +128 -0
- package/dist/serialize.js.map +1 -0
- package/dist/spec.d.ts +59 -0
- package/dist/spec.d.ts.map +1 -0
- package/dist/spec.js +364 -0
- package/dist/spec.js.map +1 -0
- package/dist/types.d.ts +180 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +15 -0
- package/dist/types.js.map +1 -0
- package/dist/validate/anti-pattern-selector.d.ts +75 -0
- package/dist/validate/anti-pattern-selector.d.ts.map +1 -0
- package/dist/validate/anti-pattern-selector.js +254 -0
- package/dist/validate/anti-pattern-selector.js.map +1 -0
- package/dist/validate/index.d.ts +36 -0
- package/dist/validate/index.d.ts.map +1 -0
- package/dist/validate/index.js +334 -0
- package/dist/validate/index.js.map +1 -0
- package/package.json +50 -0
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.
|