@niscorp/nova 0.1.1 → 0.1.3

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.
Files changed (67) hide show
  1. package/ACTION_DOCS.md +121 -30
  2. package/ADAPTER.md +167 -12
  3. package/CHANGELOG.md +18 -0
  4. package/DESIGN.md +45 -22
  5. package/I18N_DOCS.md +4 -4
  6. package/LAYOUT_DOCS.md +55 -14
  7. package/REACT_DOCS.md +52 -16
  8. package/README.md +55 -20
  9. package/SHELL_DOCS.md +136 -16
  10. package/TERMINAL_DOCS.md +13 -7
  11. package/dist/adapters/dom/components/index.d.cts +2 -2
  12. package/dist/adapters/dom/components/index.d.ts +2 -2
  13. package/dist/adapters/dom/index.cjs +351 -53
  14. package/dist/adapters/dom/index.cjs.map +1 -1
  15. package/dist/adapters/dom/index.d.cts +4 -2
  16. package/dist/adapters/dom/index.d.ts +4 -2
  17. package/dist/adapters/dom/index.js +2 -2
  18. package/dist/adapters/dom/server.cjs +356 -55
  19. package/dist/adapters/dom/server.cjs.map +1 -1
  20. package/dist/adapters/dom/server.d.cts +2 -2
  21. package/dist/adapters/dom/server.d.ts +2 -2
  22. package/dist/adapters/dom/server.js +7 -4
  23. package/dist/adapters/dom/server.js.map +1 -1
  24. package/dist/adapters/react/components/index.d.cts +2 -2
  25. package/dist/adapters/react/components/index.d.ts +2 -2
  26. package/dist/adapters/react/index.d.cts +4 -4
  27. package/dist/adapters/react/index.d.ts +4 -4
  28. package/dist/adapters/tty/components/index.d.cts +2 -2
  29. package/dist/adapters/tty/components/index.d.ts +2 -2
  30. package/dist/adapters/tty/index.d.cts +2 -2
  31. package/dist/adapters/tty/index.d.ts +2 -2
  32. package/dist/adapters/vue/components/index.d.cts +5 -5
  33. package/dist/adapters/vue/components/index.d.ts +5 -5
  34. package/dist/adapters/vue/index.d.cts +4 -4
  35. package/dist/adapters/vue/index.d.ts +4 -4
  36. package/dist/adapters/vue/index.js +1 -1
  37. package/dist/agent/index.d.cts +2 -2
  38. package/dist/agent/index.d.ts +2 -2
  39. package/dist/{chunk-7B3RDENH.js → chunk-6N4WRC5V.js} +9 -4
  40. package/dist/chunk-6N4WRC5V.js.map +1 -0
  41. package/dist/chunk-FQAJ24KA.js +408 -0
  42. package/dist/chunk-FQAJ24KA.js.map +1 -0
  43. package/dist/devtools/index.d.cts +2 -2
  44. package/dist/devtools/index.d.ts +2 -2
  45. package/dist/i18n/index.d.cts +2 -2
  46. package/dist/i18n/index.d.ts +2 -2
  47. package/dist/index.cjs +8 -2
  48. package/dist/index.cjs.map +1 -1
  49. package/dist/index.d.cts +5 -5
  50. package/dist/index.d.ts +5 -5
  51. package/dist/index.js +2 -2
  52. package/dist/{palette-CP0wd3bE.d.ts → palette-Mx7XHYC6.d.ts} +1 -1
  53. package/dist/{palette-lm0bU9i5.d.cts → palette-wbJB_svk.d.cts} +1 -1
  54. package/dist/reflect/index.d.cts +2 -2
  55. package/dist/reflect/index.d.ts +2 -2
  56. package/dist/{types-DdltMfw7.d.ts → types-B-rjaUX0.d.ts} +1 -1
  57. package/dist/{types-Boh9ckdG.d.ts → types-BB9RXel5.d.ts} +1 -1
  58. package/dist/{types-De0KpxfI.d.cts → types-BLVRduoz.d.cts} +11 -1
  59. package/dist/{types-DhHL0twe.d.ts → types-B_nOtkyt.d.ts} +1 -1
  60. package/dist/{types-Brc7v_pS.d.ts → types-DE77Jl2W.d.ts} +11 -1
  61. package/dist/{types-Dv6JLmgo.d.cts → types-PDXOkvtK.d.cts} +1 -1
  62. package/dist/{types-Q80YtOQt.d.cts → types-mRKXqZPX.d.cts} +1 -1
  63. package/dist/{types-ByNSwtUV.d.cts → types-uk19d6KC.d.cts} +1 -1
  64. package/package.json +7 -7
  65. package/dist/chunk-7B3RDENH.js.map +0 -1
  66. package/dist/chunk-OAMC6R6E.js +0 -121
  67. package/dist/chunk-OAMC6R6E.js.map +0 -1
package/DESIGN.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Declarative, framework-agnostic UI runtime. JSON layouts, action lifecycles,
4
4
  shell orchestration. The core is pure TypeScript with zero framework
5
- dependencies. Framework adapters (React, plain DOM) consume the
5
+ dependencies. Adapters (React, Vue, plain DOM, TTY, Ink) consume the
6
6
  `RenderNode[]` output.
7
7
 
8
8
  This document describes the package as it actually exists today. Anything
@@ -39,10 +39,10 @@ action, and shell never import from each other transitively except via
39
39
  `@layout` / `@action` / `@shell` aliases at well-defined seams (the shell
40
40
  wires everything together at construction time).
41
41
 
42
- Around the core sit four subpath areas:
42
+ Around the core sit six subpath areas:
43
43
 
44
- - **`adapters/`** — framework bindings (`react/`, `dom/`), each with its own
45
- export subpath. Adapters import only the core public surface; core never
44
+ - **`adapters/`** — framework bindings (`react/`, `vue/`, `dom/`, `tty/`,
45
+ `ink/`), each with its own export subpath. Adapters import only the core public surface; core never
46
46
  imports an adapter. See [ADAPTER.md](ADAPTER.md).
47
47
  - **`reflect/`** — read-only introspection (`@niscorp/nova/reflect`): layout
48
48
  walks, shell snapshots, the action graph, audit classification, and what an
@@ -52,6 +52,11 @@ Around the core sit four subpath areas:
52
52
  plain ActionDefinitions plus fns over `reflect/`.
53
53
  - **`agent/`** — cortex agents owned by nova (`@niscorp/nova/agent`);
54
54
  importing the subpath is what pulls in the optional cortex peer.
55
+ - **`i18n/`** — the language surface (`@niscorp/nova/i18n`): the phrase-key
56
+ vocabulary, the harvest, `translateRenderTree`, `fillPhrase`. The swap itself
57
+ runs in the renderer. See [I18N_DOCS.md](I18N_DOCS.md).
58
+ - **`migrations/`** — nova's grammar as a strata sequence
59
+ (`@niscorp/nova/migrations`: `NOVA_SEQUENCE`, `NOVA_SCHEMAS`).
55
60
 
56
61
  ---
57
62
 
@@ -73,7 +78,9 @@ NovaError (base; carries code + context + cause)
73
78
  ├── UnknownActionError (shell.push of unregistered id)
74
79
  ├── UnknownFragmentError (push `with` names an unregistered fragment)
75
80
  ├── ShellDisposedError (post-dispose call)
76
- └── LifecycleError (hook failure; carries hook + cause)
81
+ ├── UnknownFunctionError (`fn` endpoint names an unregistered function)
82
+ ├── LifecycleError (hook failure; carries hook + cause)
83
+ └── MutationError (a mutation op that cannot apply)
77
84
  ```
78
85
 
79
86
  Subclasses are added only when there is a real throw site. No dead exports.
@@ -153,6 +160,8 @@ Zod schemas for the layout DSL:
153
160
  - `ConditionalNodeSchema` — `{ if, then, else? }`.
154
161
  - `LoopNodeSchema` — `{ for, as, key?, do }`.
155
162
  - `LayoutRefNodeSchema` — `{ ref }`. Resolves against the layout store.
163
+ - `SlotNodeSchema` — `{ slot }`. Filled at compose time (see "ActionFragment
164
+ composition").
156
165
  - `LayoutNodeSchema` — discriminated union of all of the above plus arrays.
157
166
 
158
167
  ### Renderer (`layout/renderer.ts`)
@@ -161,10 +170,10 @@ Walks a `LayoutNode` and emits a `RenderNode[]` tree:
161
170
 
162
171
  ```
163
172
  RenderComponentNode { type: 'component'; name; props; children;
164
- ref?; model?: { ref, path } }
173
+ ref?; key?; model?: { ref, path } }
165
174
  RenderTextNode { type: 'text'; value }
166
175
  RenderFragmentNode { type: 'fragment'; children }
167
- RenderErrorNode { type: 'error'; message }
176
+ RenderErrorNode { type: 'error'; code; message; nodeRef?; key? }
168
177
  ```
169
178
 
170
179
  The renderer:
@@ -199,7 +208,8 @@ own component implementations later.
199
208
  Split into focused files:
200
209
 
201
210
  - `effects.ts` — `CallEffect`, `EmitEffect`, navigation effects (`Push`,
202
- `Pop`, `Replace`).
211
+ `Pop`, `Replace`, `PopTo`, `ResetTo`, `RemoveInstance`, `RemoveSelf`,
212
+ `Reconcile`, `Reload`), and `StepSchema = Mutation | Effect`.
203
213
  - `triggers.ts` — `TriggerConfigSchema { event?, message?, ref?, do }`.
204
214
  - `endpoints.ts` — `EndpointConfigSchema`: a function call `{ fn, target?,
205
215
  errorTarget? }` **or** an HTTP call `{ method, url, headers?, request?,
@@ -213,8 +223,7 @@ Split into focused files:
213
223
  data is never transformed.
214
224
  - `lifecycle.ts` — `LifecycleConfigSchema { mount?, unmount?, suspend?,
215
225
  resume? }`. Each is `Step[]`.
216
- - `index.ts` — `StepSchema = Mutation | Effect`, `ActionDefinitionSchema`,
217
- exports.
226
+ - `index.ts` — `ActionDefinitionSchema`, `ActionFragmentSchema`, exports.
218
227
 
219
228
  ### Mutations (`action/mutations/`)
220
229
 
@@ -225,7 +234,7 @@ the first match. Adding a mutation is a new file, not an edit to a
225
234
  giant switch.
226
235
 
227
236
  Current ops: `set`, `toggle`, `increment`, `decrement`, `push`, `pop`,
228
- `removeAt`, `clear`, `reset`.
237
+ `removeAt`, `move`, `clear`, `reset`.
229
238
 
230
239
  Each op has its own Zod schema. The combined `MutationSchema` is the
231
240
  union.
@@ -317,7 +326,7 @@ The shell exposes runtimes via `shell.getRuntime(id)` typed as
317
326
  ```
318
327
  PublicActionRuntime = {
319
328
  readonly instance, definition;
320
- getData(); render();
329
+ getData(); setData(next); render();
321
330
  onDataChange(handler); onStatusChange(handler);
322
331
  }
323
332
  ```
@@ -350,7 +359,7 @@ The user's entry point. Splits responsibilities across small files:
350
359
  - **`lifecycle-ops.ts`** — `unmountInstance`, `suspendTop`, `resumeTop`
351
360
  bookkeeping. Idempotent unmount via an internal `Set`.
352
361
  - **`canvas.ts`** — pure stack: `pushInstance`, `popInstance`,
353
- `clearStack`, `peek`. No I/O.
362
+ `replaceTop`, `clearStack`, `peek`. No I/O.
354
363
  - **`shell-internals.ts`** — `validateActions` (boundary Zod validation
355
364
  on the action map at construction), `snapshotCanvas`,
356
365
  `createRuntimeFactory`, and the test escape hatch
@@ -365,17 +374,22 @@ createShell(config: ShellConfig): Shell
365
374
  `Shell` exposes:
366
375
 
367
376
  ```
368
- push(canvasId, actionId, input?, fragments?): string
377
+ push(canvasId, actionId, input?, fragments?, options?): string
378
+ originOf(instanceId): string | undefined
369
379
  pop(canvasId): void
370
380
  popTo(canvasId, instanceId): void
381
+ removeInstance(canvasId, instanceId): void
371
382
  replace(canvasId, actionId, input?, fragments?): string
372
383
  clear(canvasId): void
384
+ back(): boolean
373
385
  registerAction(definition): void
374
386
  removeAction(actionId): void
375
387
  registerFragment(fragment): void
376
388
  addCanvas(config): void
377
389
  removeCanvas(canvasId): void
378
390
  setCanvasLayout(layout): void
391
+ setPhrases(phrases): void
392
+ getPhrases(): Phrasebook | undefined
379
393
  setLayout(refId, layout): void
380
394
  getCanvasState(canvasId): CanvasState
381
395
  getRuntime(instanceId): PublicActionRuntime | undefined
@@ -509,9 +523,13 @@ yet beyond a placeholder:
509
523
  across processes. Serving rendered trees over a socket is moss's job;
510
524
  nova ships the surface it targets (`RenderApi`, ActionSlot-preserving
511
525
  `flattenRenderTree`).
512
- - **Schema versioning.** Breaking changes in 0.x are unversioned.
513
- - **LLM tooling / JSON Schema generation / catalog.** Excluded by
514
- design — nova is a runtime, not a generator.
526
+ - ~~**Schema versioning.**~~ **Implemented.** The action, fragment and
527
+ layout grammars are a strata sequence at `@niscorp/nova/migrations`
528
+ (`NOVA_SEQUENCE`).
529
+ - **LLM tooling / JSON Schema generation / catalog.** Kept out of the core
530
+ — nova is a runtime, not a generator. What ships is the optional
531
+ `@niscorp/nova/agent` subpath (`layoutAgent`, `paletteFromRegistry`,
532
+ `collectInteractive`); catalogs are the host's.
515
533
 
516
534
  ---
517
535
 
@@ -557,6 +575,7 @@ A nova component registered with the React adapter receives:
557
575
  - `children?: ReactNode` — populated when the layout node has children
558
576
  - `novaModel?: { ref, path }` — populated when the layout node has a
559
577
  `model:` binding (so the component can dispatch `ui:model` events)
578
+ - `novaRef?: string` — the layout node's `ref`, when set
560
579
  - ...the layout node's `props` spread on top
561
580
 
562
581
  That's it. Components do not receive a `shell`, an `instanceId`, an
@@ -612,7 +631,7 @@ default, and that the wrapper still mounts for an empty slot so exits can run).
612
631
  Both `useRenderTree` and `useCanvas` cache their snapshot via `useRef`
613
632
  so `useSyncExternalStore`'s `getSnapshot` returns a stable reference
614
633
  when nothing has changed. This is mandatory for tearing-safety in
615
- React 18 concurrent rendering.
634
+ React's concurrent rendering.
616
635
 
617
636
  - **`useRenderTree`** caches by **data identity**. The runtime exposes
618
637
  the current data object; if the cached data reference is `===` to the
@@ -631,9 +650,9 @@ Both contracts are verified by `test/react/snapshot-stability.test.tsx`,
631
650
  which asserts referential equality across re-renders without state
632
651
  changes and reference inequality after a real data or stack change.
633
652
 
634
- ### React 18+ compatibility
653
+ ### React compatibility
635
654
 
636
- - Requires React 18 or later (uses `useSyncExternalStore`).
655
+ - Requires React 19 (the `react` peer is `^19.2.4`; uses `useSyncExternalStore`).
637
656
  - Concurrent rendering: tearing-safe by construction.
638
657
  - StrictMode: works correctly; snapshot caches survive effect double-
639
658
  invocation.
@@ -676,8 +695,12 @@ wire weight.
676
695
 
677
696
  `src/adapters/dom/` (`@niscorp/nova/adapters/dom`) renders a served tree to
678
697
  vanilla DOM against a `RenderApi`: events wired by convention (`ref` →
679
- `ui:click`, `model` → `ui:model`/`ui:key`), `debounce` honoured, focus and
680
- caret captured/restored across full rebuilds (ADAPTER.md §6). Its components
698
+ `ui:click`, `model` → `ui:model`/`ui:key`), `debounce` honoured. It keeps the
699
+ tree it drew beside the DOM that tree produced and patches the page: an
700
+ element whose part of the tree did not change is the same node, never taken
701
+ off the page, so focus, scroll and a running animation are kept, and a field
702
+ being typed in is not replaced (ADAPTER.md, "The DOM adapter keeps what did
703
+ not change"). Its components
681
704
  kit (`/adapters/dom/components`: `defaultRegistry`, `fallback`,
682
705
  `DEFAULT_CSS`, `ROOT_CLASS`) is the batteries-included reference set. It
683
706
  exists as the proof that a terminal needs no framework — and as the adapter
package/I18N_DOCS.md CHANGED
@@ -38,8 +38,8 @@ child into a text node.
38
38
 
39
39
  Every tree in the system comes out of `renderLayout` / `renderLayoutFromStore`,
40
40
  and there are three callers — the action runtime, the shell, and
41
- `<Nova.Layout>`. So an **adapter contains no i18n code at all**. React, dom, tty,
42
- ink and any adapter written later receive words that are already in the reader's
41
+ `<Nova.Layout>`. So an **adapter contains no i18n code at all**. React, vue, dom,
42
+ tty, ink and any adapter written later receive words that are already in the reader's
43
43
  language and never learn that a second one exists.
44
44
 
45
45
  That is deliberate. An adapter renders a `RenderNode`; if i18n changed the
@@ -210,10 +210,10 @@ From `@niscorp/nova/i18n`:
210
210
  | `harvestLayout` / `harvestDefinition` / `harvestDefinitions` | Enumerate the phrases an artifact can show |
211
211
  | `missingFrom(harvested, book)` | What a language is still missing |
212
212
  | `fillPhrase(value)` | Close a counted phrase held as data, outside a render |
213
- | `translateRenderTree(tree, opts)` | For a tree you did **not** render — a replayed frame, a fixture |
213
+ | `translateRenderTree(tree, { phrases, keys?, onMiss? })` | For a tree you did **not** render — a replayed frame, a fixture. An empty book returns the same tree, patterns unfilled |
214
214
  | `DEFAULT_PHRASE_KEYS` | The default prose prop set |
215
215
  | `isBinding` / `isPhrase` / `matcherFor` | The primitives the rules are built from |
216
- | `Phrasebook` / `PhraseKeys` | Types |
216
+ | `Phrasebook` / `PhraseKeys` / `PhraseKeyMatcher` / `TranslateOptions` / `HarvestedPhrase` | Types |
217
217
 
218
218
  Config fields: `phrases`, `phraseKeys`, `onPhraseMiss` on `ShellConfig`,
219
219
  `RenderContext`, `RenderOptions` and `<Nova.Layout>`. Shell methods:
package/LAYOUT_DOCS.md CHANGED
@@ -80,6 +80,9 @@ The most common one. References a component by name; the registry supplies the i
80
80
  - **`children`** *(optional)* — a single `LayoutNode` or an array of them. Components decide how to render their children slot.
81
81
  - **`ref`** *(optional)* — a stable identifier. Used by triggers (`event: 'ui:click', ref: 'header-stack'`) and as the model binding key. If unset, the renderer auto-generates one for model-bound components.
82
82
  - **`model`** *(optional)* — two-way binding path. See [Two-way binding](#two-way-binding).
83
+ - **`events`** *(optional)* — a record of event name → configuration. The schema accepts it; the renderer does not read it and it does not reach the `RenderNode`. Interaction is `ref` + an action trigger.
84
+
85
+ The node is strict: any other key fails `LayoutNodeSchema`.
83
86
 
84
87
  ### Resolved render output
85
88
 
@@ -96,6 +99,8 @@ A component node renders to a `RenderNode` of type `'component'`:
96
99
  }
97
100
  ```
98
101
 
102
+ When `model` is set and the node has no explicit `value` prop, the renderer also adds `props.value` — the model path's current value.
103
+
99
104
  The framework adapter (React) reads this and instantiates the React component with these props.
100
105
 
101
106
  ---
@@ -114,16 +119,16 @@ Render one of two branches based on a condition.
114
119
 
115
120
  ### Fields
116
121
 
117
- - **`if`** *(required)* — a binding evaluated for truthiness. Strings are bindings, primitives are themselves, objects can be `{$if}` directives. Truthiness rules: `null`, `undefined`, `false`, `0`, `''`, `[]`, `{}` are all falsy. Everything else is truthy.
122
+ - **`if`** *(required)* — a binding evaluated for truthiness. Strings are bindings, primitives are themselves, objects can be `{$if}` directives. Truthiness rules: `null`, `undefined`, `false`, `0`, `''`, `[]` are all falsy. Everything else is truthy — including an empty object `{}`.
118
123
  - **`then`** *(required)* — `LayoutNode` rendered when the condition is truthy.
119
- - **`else`** *(optional)* — `LayoutNode` rendered when the condition is falsy. If absent, an empty fragment is rendered.
124
+ - **`else`** *(optional)* — `LayoutNode` rendered when the condition is falsy. If absent, nothing is rendered.
120
125
 
121
126
  ### Conditionals inside other places
122
127
 
123
128
  There are **two kinds of conditional** in nova:
124
129
 
125
130
  1. **Conditional NODE** (this one) — appears in the layout tree as a sibling of components. Swaps whole subtrees.
126
- 2. **`{$if}` directive** — appears inside a value position (e.g. a prop value, a string content). See [Bindings — directives](#directives).
131
+ 2. **`{$if}` directive** — appears inside a value position (e.g. a prop value, a string content). See [Bindings — directives](#3-directives).
127
132
 
128
133
  Use the node form when you're swapping whole UI sections. Use the directive form when you're picking a value for a single field.
129
134
 
@@ -152,12 +157,12 @@ Iterate an array and render the body once per item.
152
157
 
153
158
  - **`for`** *(required)* — a binding that resolves to an array. If it doesn't resolve to an array, the loop renders nothing (graceful empty).
154
159
  - **`as`** *(required)* — the variable name used for the current item inside `do`. References as `$<name>` (no dot).
155
- - **`key`** *(optional)* — a path on each item used for stable React keys when an adapter consumes the output. Currently informational; the React adapter falls back to index-based keys.
160
+ - **`key`** *(optional)* — a path on each item (e.g. `'id'`) used for stable identity. The renderer stamps each item's output with `key`: the value at that path, or the index when `key` is omitted. Adapters key by it, so looped rows can share a `ref` without colliding.
156
161
  - **`do`** *(required)* — the `LayoutNode` rendered once per item, with the loop variable in scope.
157
162
 
158
- ### The `index` variable
163
+ ### The `index` and `items` variables
159
164
 
160
- Inside the loop body, the variable `index` is automatically bound to the current iteration index (0-based). Reference it as `$index`:
165
+ Inside the loop body, the variable `index` is automatically bound to the current iteration index (0-based), and `items` to the array being iterated (`$items`) — so a control inside the loop can address the whole list. Both names are reserved: with an `as` of `'index'` or `'items'` the loop's own value wins and the item is unreachable. Reference the index as `$index`:
161
166
 
162
167
  ```ts
163
168
  {
@@ -305,7 +310,22 @@ Inside a value position (a prop value, a children string, etc.), you can use the
305
310
  }
306
311
  ```
307
312
 
308
- Truthiness rules are the same as conditional nodes.
313
+ Truthiness rules are the same as conditional nodes. Without `$else`, a falsy `$if` resolves to `undefined`.
314
+
315
+ Four more directives resolve in the same positions:
316
+
317
+ ```ts
318
+ { $eq: ['$.status', 'open'] } // → true when both resolved operands are strictly equal
319
+ { $exists: '$.record.id' } // → true when the operand resolves to anything but undefined
320
+ { $at: ['$.results', '$.cursor'] } // → the array element at a (dynamic) index
321
+ { $at: ['$.results', '$.cursor', 'id'] } // → one field of that element
322
+ { $prism: <prism node> } // → the node evaluated by Prism against the innermost scope:
323
+ // the root data, or inside a loop the loop's own scope
324
+ // ({ <as>, index, items } — the root is not reachable there);
325
+ // undefined when it fails to evaluate
326
+ ```
327
+
328
+ They compose: `{ $if: { $eq: ['$.tab', 'all'] }, $then: 'primary', $else: 'ghost' }`.
309
329
 
310
330
  **Why both `if` (node) and `$if` (directive)?** Different layers. The node form swaps whole UI subtrees. The directive form picks a single value. The node form lives in the layout tree; the directive form lives in the value space.
311
331
 
@@ -313,13 +333,13 @@ Truthiness rules are the same as conditional nodes.
313
333
 
314
334
  - Numbers, booleans, nulls — pass through unchanged
315
335
  - Plain strings without `$` or `{{}}` — pass through unchanged
316
- - Objects without `$if` — walked recursively, each value resolved
336
+ - Objects without a directive key (`$if`, `$eq`, `$exists`, `$at`, `$prism`) — walked recursively, each value resolved
317
337
 
318
338
  ---
319
339
 
320
340
  ## Two-way binding
321
341
 
322
- Set `model: '<path>'` on a component to wire it for two-way data binding. The renderer resolves the path against the current scope chain (so loop variables work) and emits a `model: { ref, path }` field on the rendered node. The React adapter installs an event listener that writes back to the data store when the component dispatches a `ui:model` event.
342
+ Set `model: '<path>'` on a component to wire it for two-way data binding. The renderer resolves the path against the current scope chain (so loop variables work) and emits a `model: { ref, path }` field on the rendered node. The action runtime writes the event's `payload` back to that path when the component dispatches a `ui:model` event with that `ref` — before any `ui:model` trigger runs.
323
343
 
324
344
  ```ts
325
345
  {
@@ -355,11 +375,16 @@ Type into the second input → `data.items[1].value` updates → re-render shows
355
375
  {
356
376
  store: LayoutStore, // for resolving LayoutRefs
357
377
  registry: ComponentRegistry, // to validate component names
358
- strict: boolean, // throw on errors vs return error nodes (default false)
359
- onError: (error: NovaError) => void, // telemetry for non-strict errors
378
+ strict?: boolean, // throw on errors vs return error nodes (default false)
379
+ onError?: (error: NovaError) => void, // telemetry for non-strict errors
380
+ phrases?: Phrasebook, // i18n: source phrase → the reader's words (see I18N_DOCS.md)
381
+ phraseKeys?: PhraseKeys, // i18n: which prop keys carry prose
382
+ onPhraseMiss?: (phrase: string, where: string) => void, // i18n: a phrase with no entry in the book
360
383
  }
361
384
  ```
362
385
 
386
+ `render({ layout, data?, store, registry, ... })` is the object-form alias of `renderLayout` — same options, named, with `data` optional.
387
+
363
388
  When `strict: false` (the default), errors during rendering are caught at each subtree boundary, surfaced via `onError`, and replaced with an error `RenderNode`. Sibling subtrees keep rendering. When `strict: true`, errors propagate.
364
389
 
365
390
  ### Errors the renderer can produce
@@ -391,7 +416,9 @@ type RenderNode =
391
416
  | { type: 'error'; code: string; message: string; nodeRef?: string };
392
417
  ```
393
418
 
394
- This is the contract between the renderer and any framework adapter. The React adapter walks this tree and instantiates the registered React components. A future Vue adapter would do the same with Vue components.
419
+ Every variant may also carry `key?: string` — the identity key the renderer stamps on a loop item's output (see [Loop nodes](#loop-nodes)), distinct from `ref`.
420
+
421
+ This is the contract between the renderer and any framework adapter. The React adapter walks this tree and instantiates the registered React components. The Vue, DOM, TTY and Ink adapters (`@niscorp/nova/adapters/*`) do the same on their own surfaces.
395
422
 
396
423
  ---
397
424
 
@@ -420,9 +447,16 @@ registry.registerAll({
420
447
  Input,
421
448
  Button,
422
449
  Box,
450
+ MyButton: { component: myButtonComponent, meta: { description: 'A clickable button.' } },
423
451
  });
452
+
453
+ registry.get('MyButton'); // → { component, meta } | undefined
454
+ registry.has('MyButton'); // → boolean
455
+ registry.list(); // → array of registered names
424
456
  ```
425
457
 
458
+ Meta is `{ description?, propsSchema?, events? }` — `events` maps an event name to `{ description?, payloadType? }`.
459
+
426
460
  ### `registerAll` and static meta
427
461
 
428
462
  If a component carries a static `.meta` property, `registerAll` picks it up automatically. Explicit meta in the call overrides static. See `REACT_DOCS.md` for the React-specific component shape.
@@ -453,8 +487,9 @@ const store = createLayoutStore();
453
487
 
454
488
  store.set('user-card', { component: 'Box', children: [...] });
455
489
  store.get('user-card'); // → the stored layout, or undefined
456
- store.has('user-card'); // → boolean
490
+ store.delete('user-card'); // remove it
457
491
  store.list(); // → array of stored ids
492
+ store.resolveReferences(layout); // → the layout with every { ref } it can resolve inlined
458
493
  ```
459
494
 
460
495
  `set` validates the layout against `LayoutNodeSchema` and throws `DefinitionValidationError` if it doesn't parse. So you can't accidentally store an invalid layout.
@@ -478,7 +513,7 @@ In **strict mode** (`strict: true` on the render context) these throw. In **lax
478
513
 
479
514
  ```ts
480
515
  // Component
481
- { component: string, props?: object, children?: LayoutNode | LayoutNode[], ref?: string, model?: string }
516
+ { component: string, props?: object, children?: LayoutNode | LayoutNode[], ref?: string, model?: string, events?: object }
482
517
 
483
518
  // Conditional (node form)
484
519
  { if: Resolvable, then: LayoutNode, else?: LayoutNode }
@@ -500,6 +535,12 @@ In **strict mode** (`strict: true` on the render context) these throw. In **lax
500
535
 
501
536
  // Conditional (directive form, used in value positions)
502
537
  { $if: Resolvable, $then: any, $else?: any }
538
+
539
+ // Other value directives
540
+ { $eq: [Resolvable, Resolvable] }
541
+ { $exists: Resolvable }
542
+ { $at: [Resolvable, Resolvable, field?] }
543
+ { $prism: PrismNode }
503
544
  ```
504
545
 
505
546
  For actions that drive data into the layout, see `ACTION_DOCS.md`. For wiring layouts into a React app, see `REACT_DOCS.md`.
package/REACT_DOCS.md CHANGED
@@ -10,7 +10,7 @@ This guide is for **using** nova in React. For nova's framework-agnostic core, s
10
10
 
11
11
  ```bash
12
12
  pnpm add @niscorp/nova
13
- # React + react-dom are peer deps; you almost certainly already have them.
13
+ # `react` (^19.2.4) is an optional peer; a browser app brings `react-dom` itself.
14
14
  ```
15
15
 
16
16
  `@niscorp/nova/adapters/react` is the same package, accessed via the subpath export. No separate install.
@@ -96,12 +96,13 @@ Use this when you have a `Shell`. The provider wires the shell's dispatch/publis
96
96
 
97
97
  Props:
98
98
  - **`shell`** — a `Shell` instance
99
- - **`registry`** — the component registry. Same instance you passed to `createShell`.
99
+ - **`registry?`** — the component registry. Defaults to `shell.registry`; pass one only to render the shell against a different component set.
100
+ - **`slotWrapper?`** — see "The `slotWrapper` seam" below.
100
101
  - **`children`** — the React subtree that uses nova hooks.
101
102
 
102
103
  ### `<NovaRenderProvider>` — render-only mode
103
104
 
104
- Use this when you want to render a layout without a shell — for previews, tests, or the showroom. You supply the dispatch and publish functions yourself (or pass no-ops).
105
+ Use this when you want to render a layout without a shell — for previews, tests, or the showroom. You supply the dispatch and publish functions yourself; both default to no-ops.
105
106
 
106
107
  ```tsx
107
108
  <NovaRenderProvider
@@ -115,8 +116,9 @@ Use this when you want to render a layout without a shell — for previews, test
115
116
 
116
117
  Props:
117
118
  - **`registry`** — the component registry
118
- - **`dispatch`** — function to receive events from components
119
- - **`publish`** — function to receive message bus publishes from components
119
+ - **`dispatch?`** — function to receive events from components (default: no-op)
120
+ - **`publish?`** — function to receive message bus publishes from components (default: no-op)
121
+ - **`slotWrapper?`** — see "The `slotWrapper` seam" below.
120
122
  - **`fallback?`** — renderer for unregistered component names; omit for
121
123
  strict `COMPONENT_NOT_FOUND` markers
122
124
  - **`textWrapper?`** / **`errorMarker?`** — host-specific leaf renderers.
@@ -127,6 +129,20 @@ Props:
127
129
 
128
130
  This is what the showroom uses for layout-only stories that don't need a shell.
129
131
 
132
+ ### `<Nova.Layout>` / `<Nova.Shell>` / `<Nova.Canvas>` — mountable surfaces
133
+
134
+ Three components that hide the registry/provider/render-tree wiring. Each is also exported by its flat name (`NovaLayout`, `NovaShell`, `NovaCanvas`).
135
+
136
+ ```tsx
137
+ <Nova.Layout layout={layout} data={data} /> // one layout, no shell
138
+ <Nova.Shell shell={shell} /> // the shell's whole frame
139
+ <Nova.Canvas id="main" /> // one canvas, inside a shell provider
140
+ ```
141
+
142
+ - **`<Nova.Layout>`** — `layout` (a `LayoutNode` or a layout-store id), `data?`, `components?` (registered after the builtins), `registry?` / `store?` (pre-built; with `registry`, `components` and `builtins` are ignored), `builtins?` (default `true`), `strict?`, `onError?`, and the i18n fields `phrases?` / `phraseKeys?` / `onPhraseMiss?` (see `I18N_DOCS.md`). Renders through a `NovaRenderProvider` with no-op dispatch.
143
+ - **`<Nova.Shell>`** — `shell`, `registry?` (default `shell.registry`), `slotWrapper?`, `builtins?` (default `true`: registers the default component set on the registry if `CanvasSlot` is missing). Renders the shell's canvasLayout.
144
+ - **`<Nova.Canvas>`** — `id`, plus optional `shell`, `registry?`, `builtins?`. With `shell` it provides its own `NovaShellProvider`; without, it must sit inside one. Renders that canvas's actionLayout.
145
+
130
146
  ---
131
147
 
132
148
  ## Hooks
@@ -179,7 +195,7 @@ if (status === 'initializing') return <Spinner />;
179
195
 
180
196
  ### `useRenderTree(instanceId)`
181
197
 
182
- Returns the live `RenderNode[]` for an action instance. Re-computes whenever the instance's data changes. **The result is referentially stable** when the data hasn't changed — important for React's `useSyncExternalStore` and for downstream memoization.
198
+ Returns the live `RenderNode[]` for an action instance. Re-computes whenever the instance's data (or the shell's phrasebook) changes. **The result is referentially stable** when neither has changed — important for React's `useSyncExternalStore` and for downstream memoization.
183
199
 
184
200
  ```tsx
185
201
  const tree = useRenderTree(activeId);
@@ -230,13 +246,15 @@ const tree = useRenderTree(activeId);
230
246
  return <RenderTree nodes={tree} />;
231
247
  ```
232
248
 
249
+ An unregistered component name renders the provider's `fallback` when one was given, otherwise an error marker with code `COMPONENT_NOT_FOUND`. `<RenderNodeView node={...} />` is the single-node form `RenderTree` maps over.
250
+
233
251
  That's the entire React-side rendering pipeline. Everything else is the components themselves.
234
252
 
235
253
  ---
236
254
 
237
255
  ## Writing your own component
238
256
 
239
- A component for the React adapter is a React function component typed as `NovaComponent<P>`:
257
+ A component for the React adapter is a React component typed as `NovaComponent<P>`:
240
258
 
241
259
  ```tsx
242
260
  import type { NovaComponent } from '@niscorp/nova/adapters/react';
@@ -430,17 +448,20 @@ For React-level errors (a buggy component throwing during render), use `<NovaErr
430
448
  ```tsx
431
449
  import { NovaErrorBoundary } from '@niscorp/nova/adapters/react';
432
450
 
433
- <NovaErrorBoundary fallback={<div>Something broke.</div>}>
451
+ <NovaErrorBoundary fallback={(error) => <div>Something broke: {error.message}</div>}>
434
452
  <CanvasView canvasId="main" />
435
453
  </NovaErrorBoundary>
436
454
  ```
437
455
 
438
- This is a real React class component (the only class in the package — React 18 still requires class boundaries).
456
+ `fallback` is a function of the caught error; omitted, the boundary renders the error's message in a `<div data-nova-error-boundary role="alert">`. `onError(error, info)` reports the catch.
457
+
458
+ This is a real React class component (the only class in the package outside the error classes in `shared/errors.ts` — React still requires a class for an error boundary).
439
459
 
440
460
  ---
441
461
 
442
- ## React 18+ compatibility
462
+ ## React compatibility
443
463
 
464
+ - **Version** — React 19 (`react` peer `^19.2.4`).
444
465
  - **Strict mode** — fully supported. The hooks use `useSyncExternalStore` and the render-tree hook caches its snapshot via `useRef`, so dev-mode double-mounting doesn't break anything.
445
466
  - **Concurrent rendering** — fully supported. `useSyncExternalStore` is tearing-safe by design.
446
467
  - **Suspense** — not used as a loading model. Loading state is explicit data on the action (`{ loading: true }` as a regular field). A consumer can wrap nova components in `<Suspense>` but it never activates because nova never throws promises during render.
@@ -516,10 +537,14 @@ const SomeReactComponent = () => {
516
537
  ## Quick reference
517
538
 
518
539
  ```tsx
519
- // Providers (all accept an optional slotWrapper)
520
- <NovaShellProvider shell registry slotWrapper?>...</NovaShellProvider>
521
- <NovaRenderProvider registry dispatch publish slotWrapper? fallback? textWrapper? errorMarker?>...</NovaRenderProvider>
522
- <Nova.Shell shell slotWrapper? />
540
+ // Providers
541
+ <NovaShellProvider shell registry? slotWrapper?>...</NovaShellProvider>
542
+ <NovaRenderProvider registry dispatch? publish? slotWrapper? fallback? textWrapper? errorMarker?>...</NovaRenderProvider>
543
+
544
+ // Mountable surfaces
545
+ <Nova.Layout layout data? components? registry? store? builtins? strict? onError? phrases? phraseKeys? onPhraseMiss? />
546
+ <Nova.Shell shell registry? slotWrapper? builtins? />
547
+ <Nova.Canvas id shell? registry? builtins? />
523
548
 
524
549
  // Hooks
525
550
  useShell() // → Shell (throws outside provider)
@@ -537,6 +562,7 @@ useSlotWrapper() // → SlotWrapper | undefined
537
562
 
538
563
  // Render
539
564
  <RenderTree nodes={...} />
565
+ <RenderNodeView node={...} />
540
566
 
541
567
  // Slot wrapper (animation, gates, logging, error boundaries)
542
568
  type SlotWrapper = FC<{
@@ -548,10 +574,10 @@ type SlotWrapper = FC<{
548
574
 
549
575
  // Errors
550
576
  <ErrorMarker code message />
551
- <NovaErrorBoundary fallback>...</NovaErrorBoundary>
577
+ <NovaErrorBoundary fallback? onError?>...</NovaErrorBoundary> // fallback: (error) => ReactNode
552
578
 
553
579
  // Component contract
554
- type NovaComponent<P> = React.FC<NovaComponentProps & P> & { meta?: ComponentMeta };
580
+ type NovaComponent<P> = React.ComponentType<NovaComponentProps & P> & { meta?: ComponentMeta };
555
581
  type NovaComponentProps = {
556
582
  children?: ReactNode;
557
583
  novaRef?: string;
@@ -559,4 +585,14 @@ type NovaComponentProps = {
559
585
  };
560
586
  ```
561
587
 
588
+ ## The Vue adapter
589
+
590
+ `@niscorp/nova/adapters/vue` (peer `vue` ^3.5, optional) is the same surface in Vue 3 render functions — no SFC compiler. The names match this guide: `NovaRenderProvider`, `NovaShellProvider`, `NovaShell`, `NovaCanvas`, `RenderTree`, `RenderNodeView`, `ErrorMarker`, `NovaErrorBoundary`, and every hook above as a composable. The differences:
591
+
592
+ - The shell-backed composables return a `Readonly<Ref<…>>` and take a ref or getter for their id (`useCanvas(() => props.id)`).
593
+ - The render context travels by provide/inject (`NovaRenderKey`, `NovaShellKey`); children reach a component as its default slot.
594
+ - There is no `Nova` namespace and no `NovaLayout`; `NovaRenderProvider` takes `fallback` but not `textWrapper` / `errorMarker`.
595
+ - `NovaErrorBoundary`'s `onError` receives Vue's info string.
596
+ - The kit is `registerNovaVueComponents(registry)` from `@niscorp/nova/adapters/vue/components`: the same nine names over the same props schemas.
597
+
562
598
  For the layout language registered components consume, see `LAYOUT_DOCS.md`. For the action machinery the shell drives, see `ACTION_DOCS.md` and `SHELL_DOCS.md`.