@niscorp/nova 0.1.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.
Files changed (170) hide show
  1. package/ACTION_DOCS.md +552 -0
  2. package/ADAPTER.md +170 -0
  3. package/DESIGN.md +719 -0
  4. package/I18N_DOCS.md +224 -0
  5. package/LAYOUT_DOCS.md +505 -0
  6. package/LICENSE +202 -0
  7. package/REACT_DOCS.md +562 -0
  8. package/README.md +379 -0
  9. package/SHELL_DOCS.md +615 -0
  10. package/TERMINAL_DOCS.md +124 -0
  11. package/dist/adapters/dom/components/index.cjs +473 -0
  12. package/dist/adapters/dom/components/index.cjs.map +1 -0
  13. package/dist/adapters/dom/components/index.d.cts +48 -0
  14. package/dist/adapters/dom/components/index.d.ts +48 -0
  15. package/dist/adapters/dom/components/index.js +420 -0
  16. package/dist/adapters/dom/components/index.js.map +1 -0
  17. package/dist/adapters/dom/index.cjs +171 -0
  18. package/dist/adapters/dom/index.cjs.map +1 -0
  19. package/dist/adapters/dom/index.d.cts +29 -0
  20. package/dist/adapters/dom/index.d.ts +29 -0
  21. package/dist/adapters/dom/index.js +15 -0
  22. package/dist/adapters/dom/index.js.map +1 -0
  23. package/dist/adapters/dom/server.cjs +129 -0
  24. package/dist/adapters/dom/server.cjs.map +1 -0
  25. package/dist/adapters/dom/server.d.cts +15 -0
  26. package/dist/adapters/dom/server.d.ts +15 -0
  27. package/dist/adapters/dom/server.js +37 -0
  28. package/dist/adapters/dom/server.js.map +1 -0
  29. package/dist/adapters/ink/index.d.ts +75 -0
  30. package/dist/adapters/ink/index.js +472 -0
  31. package/dist/adapters/ink/index.js.map +1 -0
  32. package/dist/adapters/react/components/index.cjs +552 -0
  33. package/dist/adapters/react/components/index.cjs.map +1 -0
  34. package/dist/adapters/react/components/index.d.cts +30 -0
  35. package/dist/adapters/react/components/index.d.ts +30 -0
  36. package/dist/adapters/react/components/index.js +12 -0
  37. package/dist/adapters/react/components/index.js.map +1 -0
  38. package/dist/adapters/react/index.cjs +1526 -0
  39. package/dist/adapters/react/index.cjs.map +1 -0
  40. package/dist/adapters/react/index.d.cts +149 -0
  41. package/dist/adapters/react/index.d.ts +149 -0
  42. package/dist/adapters/react/index.js +12 -0
  43. package/dist/adapters/react/index.js.map +1 -0
  44. package/dist/adapters/tty/components/index.cjs +255 -0
  45. package/dist/adapters/tty/components/index.cjs.map +1 -0
  46. package/dist/adapters/tty/components/index.d.cts +40 -0
  47. package/dist/adapters/tty/components/index.d.ts +40 -0
  48. package/dist/adapters/tty/components/index.js +187 -0
  49. package/dist/adapters/tty/components/index.js.map +1 -0
  50. package/dist/adapters/tty/index.cjs +76 -0
  51. package/dist/adapters/tty/index.cjs.map +1 -0
  52. package/dist/adapters/tty/index.d.cts +47 -0
  53. package/dist/adapters/tty/index.d.ts +47 -0
  54. package/dist/adapters/tty/index.js +76 -0
  55. package/dist/adapters/tty/index.js.map +1 -0
  56. package/dist/adapters/vue/components/index.cjs +619 -0
  57. package/dist/adapters/vue/components/index.cjs.map +1 -0
  58. package/dist/adapters/vue/components/index.d.cts +224 -0
  59. package/dist/adapters/vue/components/index.d.ts +224 -0
  60. package/dist/adapters/vue/components/index.js +12 -0
  61. package/dist/adapters/vue/components/index.js.map +1 -0
  62. package/dist/adapters/vue/index.cjs +747 -0
  63. package/dist/adapters/vue/index.cjs.map +1 -0
  64. package/dist/adapters/vue/index.d.cts +98 -0
  65. package/dist/adapters/vue/index.d.ts +98 -0
  66. package/dist/adapters/vue/index.js +127 -0
  67. package/dist/adapters/vue/index.js.map +1 -0
  68. package/dist/agent/index.cjs +178 -0
  69. package/dist/agent/index.cjs.map +1 -0
  70. package/dist/agent/index.d.cts +28 -0
  71. package/dist/agent/index.d.ts +28 -0
  72. package/dist/agent/index.js +30 -0
  73. package/dist/agent/index.js.map +1 -0
  74. package/dist/chunk-2MNLEL45.js +47 -0
  75. package/dist/chunk-2MNLEL45.js.map +1 -0
  76. package/dist/chunk-3HGE3VWK.js +753 -0
  77. package/dist/chunk-3HGE3VWK.js.map +1 -0
  78. package/dist/chunk-4ZID7UX5.js +549 -0
  79. package/dist/chunk-4ZID7UX5.js.map +1 -0
  80. package/dist/chunk-7B3RDENH.js +1982 -0
  81. package/dist/chunk-7B3RDENH.js.map +1 -0
  82. package/dist/chunk-7S5BNPUS.js +54 -0
  83. package/dist/chunk-7S5BNPUS.js.map +1 -0
  84. package/dist/chunk-7TS3YVQR.js +114 -0
  85. package/dist/chunk-7TS3YVQR.js.map +1 -0
  86. package/dist/chunk-EG2RUXJN.js +266 -0
  87. package/dist/chunk-EG2RUXJN.js.map +1 -0
  88. package/dist/chunk-GVBBL36G.js +429 -0
  89. package/dist/chunk-GVBBL36G.js.map +1 -0
  90. package/dist/chunk-I5D2R5UA.js +753 -0
  91. package/dist/chunk-I5D2R5UA.js.map +1 -0
  92. package/dist/chunk-IGLCWXQ3.js +304 -0
  93. package/dist/chunk-IGLCWXQ3.js.map +1 -0
  94. package/dist/chunk-JI7ZRESP.js +64 -0
  95. package/dist/chunk-JI7ZRESP.js.map +1 -0
  96. package/dist/chunk-L5223LLX.js +31 -0
  97. package/dist/chunk-L5223LLX.js.map +1 -0
  98. package/dist/chunk-LA3BSEMX.js +1905 -0
  99. package/dist/chunk-LA3BSEMX.js.map +1 -0
  100. package/dist/chunk-OAMC6R6E.js +121 -0
  101. package/dist/chunk-OAMC6R6E.js.map +1 -0
  102. package/dist/chunk-OGD5CCMZ.js +62 -0
  103. package/dist/chunk-OGD5CCMZ.js.map +1 -0
  104. package/dist/chunk-PF4OJTYU.js +199 -0
  105. package/dist/chunk-PF4OJTYU.js.map +1 -0
  106. package/dist/chunk-PZ5AY32C.js +9 -0
  107. package/dist/chunk-PZ5AY32C.js.map +1 -0
  108. package/dist/chunk-RBU5PHN4.js +8 -0
  109. package/dist/chunk-RBU5PHN4.js.map +1 -0
  110. package/dist/chunk-RQB4PRPV.js +285 -0
  111. package/dist/chunk-RQB4PRPV.js.map +1 -0
  112. package/dist/chunk-V32EVEVM.js +464 -0
  113. package/dist/chunk-V32EVEVM.js.map +1 -0
  114. package/dist/chunk-ZITHBBF3.js +85 -0
  115. package/dist/chunk-ZITHBBF3.js.map +1 -0
  116. package/dist/devtools/index.cjs +1088 -0
  117. package/dist/devtools/index.cjs.map +1 -0
  118. package/dist/devtools/index.d.cts +33 -0
  119. package/dist/devtools/index.d.ts +33 -0
  120. package/dist/devtools/index.js +399 -0
  121. package/dist/devtools/index.js.map +1 -0
  122. package/dist/effects-CndX9K7D.d.cts +123 -0
  123. package/dist/effects-CndX9K7D.d.ts +123 -0
  124. package/dist/endpoints-CD-6Jl-H.d.ts +36 -0
  125. package/dist/endpoints-Dem-EdRx.d.cts +36 -0
  126. package/dist/i18n/index.cjs +299 -0
  127. package/dist/i18n/index.cjs.map +1 -0
  128. package/dist/i18n/index.d.cts +28 -0
  129. package/dist/i18n/index.d.ts +28 -0
  130. package/dist/i18n/index.js +180 -0
  131. package/dist/i18n/index.js.map +1 -0
  132. package/dist/index-CNfzSBe2.d.ts +93 -0
  133. package/dist/index-caZoXSwr.d.cts +93 -0
  134. package/dist/index.cjs +3723 -0
  135. package/dist/index.cjs.map +1 -0
  136. package/dist/index.d.cts +144 -0
  137. package/dist/index.d.ts +144 -0
  138. package/dist/index.js +15 -0
  139. package/dist/index.js.map +1 -0
  140. package/dist/migrations/index.cjs +635 -0
  141. package/dist/migrations/index.cjs.map +1 -0
  142. package/dist/migrations/index.d.cts +97 -0
  143. package/dist/migrations/index.d.ts +97 -0
  144. package/dist/migrations/index.js +50 -0
  145. package/dist/migrations/index.js.map +1 -0
  146. package/dist/palette-CP0wd3bE.d.ts +15 -0
  147. package/dist/palette-lm0bU9i5.d.cts +15 -0
  148. package/dist/primitive-props-BH_EJWIe.d.cts +100 -0
  149. package/dist/primitive-props-BH_EJWIe.d.ts +100 -0
  150. package/dist/primitive-props-CGoJvmcH.d.cts +100 -0
  151. package/dist/primitive-props-CGoJvmcH.d.ts +100 -0
  152. package/dist/reflect/index.cjs +998 -0
  153. package/dist/reflect/index.cjs.map +1 -0
  154. package/dist/reflect/index.d.cts +125 -0
  155. package/dist/reflect/index.d.ts +125 -0
  156. package/dist/reflect/index.js +13 -0
  157. package/dist/reflect/index.js.map +1 -0
  158. package/dist/schemas-DPdeFlCT.d.cts +38 -0
  159. package/dist/schemas-DPdeFlCT.d.ts +38 -0
  160. package/dist/schemas-pMyyuXV7.d.cts +47 -0
  161. package/dist/schemas-pMyyuXV7.d.ts +47 -0
  162. package/dist/types-Boh9ckdG.d.ts +194 -0
  163. package/dist/types-Brc7v_pS.d.ts +198 -0
  164. package/dist/types-ByNSwtUV.d.cts +20 -0
  165. package/dist/types-DdltMfw7.d.ts +20 -0
  166. package/dist/types-De0KpxfI.d.cts +198 -0
  167. package/dist/types-DhHL0twe.d.ts +20 -0
  168. package/dist/types-Dv6JLmgo.d.cts +194 -0
  169. package/dist/types-Q80YtOQt.d.cts +20 -0
  170. package/package.json +237 -0
package/DESIGN.md ADDED
@@ -0,0 +1,719 @@
1
+ # `@niscorp/nova` — Design
2
+
3
+ Declarative, framework-agnostic UI runtime. JSON layouts, action lifecycles,
4
+ shell orchestration. The core is pure TypeScript with zero framework
5
+ dependencies. Framework adapters (React, plain DOM) consume the
6
+ `RenderNode[]` output.
7
+
8
+ This document describes the package as it actually exists today. Anything
9
+ not implemented is called out as **Future work**.
10
+
11
+ ---
12
+
13
+ ## Architecture
14
+
15
+ Four core areas, one package. Each area imports across boundaries via the
16
+ path aliases `@shared`, `@layout`, `@action`, `@shell`. Local imports stay
17
+ relative.
18
+
19
+ ```
20
+ ┌─────────────────────────────────────────────────────────────┐
21
+ │ shell/ Public factory, canvas stacks, navigation, │
22
+ │ lifecycle bookkeeping, telemetry. │
23
+ ├─────────────────────────────────────────────────────────────┤
24
+ │ action/ Definitions (Zod schemas), runtime, mutation │
25
+ │ ops, step executor, triggers, endpoints, │
26
+ │ lifecycle hooks, model bindings. │
27
+ ├─────────────────────────────────────────────────────────────┤
28
+ │ layout/ Layout schemas, renderer, layout store, │
29
+ │ component registry, RenderNode output. │
30
+ ├─────────────────────────────────────────────────────────────┤
31
+ │ shared/ Errors, ids, common utilities, bindings │
32
+ │ (paths, scope chain, unified resolver), │
33
+ │ data store, event bus, message bus. │
34
+ └─────────────────────────────────────────────────────────────┘
35
+ ```
36
+
37
+ The `shared/` module is the only one any other area imports from. Layout,
38
+ action, and shell never import from each other transitively except via
39
+ `@layout` / `@action` / `@shell` aliases at well-defined seams (the shell
40
+ wires everything together at construction time).
41
+
42
+ Around the core sit four subpath areas:
43
+
44
+ - **`adapters/`** — framework bindings (`react/`, `dom/`), each with its own
45
+ export subpath. Adapters import only the core public surface; core never
46
+ imports an adapter. See [ADAPTER.md](ADAPTER.md).
47
+ - **`reflect/`** — read-only introspection (`@niscorp/nova/reflect`): layout
48
+ walks, shell snapshots, the action graph, audit classification, and what an
49
+ action can still do once it has been drawn (`livenessOf`). Imports
50
+ `@action`/`@shell`/`@layout`; pure and framework-free.
51
+ - **`devtools/`** — the shell inspector (`@niscorp/nova/devtools`), built as
52
+ plain ActionDefinitions plus fns over `reflect/`.
53
+ - **`agent/`** — cortex agents owned by nova (`@niscorp/nova/agent`);
54
+ importing the subpath is what pulls in the optional cortex peer.
55
+
56
+ ---
57
+
58
+ ## `shared/`
59
+
60
+ The substrate. Everything else builds on this.
61
+
62
+ ### `shared/errors.ts`
63
+
64
+ Domain error hierarchy. Classes are permitted **only here** because
65
+ identity (`instanceof`) is required for typed catch sites.
66
+
67
+ ```
68
+ NovaError (base; carries code + context + cause)
69
+ ├── RenderError (renderer subtree failure)
70
+ ├── ComponentNotFoundError (registry miss)
71
+ ├── LayoutRefNotFoundError (layout store miss)
72
+ ├── DefinitionValidationError (Zod failure at boundary)
73
+ ├── UnknownActionError (shell.push of unregistered id)
74
+ ├── UnknownFragmentError (push `with` names an unregistered fragment)
75
+ ├── ShellDisposedError (post-dispose call)
76
+ └── LifecycleError (hook failure; carries hook + cause)
77
+ ```
78
+
79
+ Subclasses are added only when there is a real throw site. No dead exports.
80
+
81
+ ### `shared/bindings/`
82
+
83
+ Unified resolver. The core function is
84
+
85
+ ```ts
86
+ resolve(value: unknown, chain: ScopeChain, extras?: ExtraScopes): unknown
87
+ ```
88
+
89
+ It is the **only** binding-resolution entry point. Every binding site —
90
+ component props, conditional `if`, loop `for`, endpoint url/headers, trigger
91
+ emit channel, mutation operands — calls it. (An endpoint's `request`/`response`
92
+ are the exception: they run through the injected `transform` evaluator, not the
93
+ binding resolver — see `endpoints.ts`.)
94
+
95
+ Resolution rules:
96
+
97
+ - **String, sole `{{ expr }}`** → returns the raw resolved value (preserves
98
+ type — number stays number, object stays object).
99
+ - **String, `"text {{expr}} text"`** → string interpolation.
100
+ - **String, bare `"$.path"` or `"$item.field"`** → raw resolved value.
101
+ - **String, anything else** → returned literally.
102
+ - **Object `{ $if, $then, $else }`** → conditional. The only directive form.
103
+ `$else` is optional.
104
+ - **Array** → walked recursively.
105
+ - **Plain object** → walked recursively.
106
+
107
+ The previous `BindingSchema` value-form objects (`{ template: ... }`,
108
+ `{ if, then, else }`) **no longer exist**. The unified resolver replaced
109
+ them.
110
+
111
+ Scope chains are arrays of records, innermost first. `createScopeChain(data)`
112
+ returns `[data]`. Loops push a new scope on the front (`{ [as]: item }`).
113
+ `extras` is a separate flat record for non-scoped names like `@error`.
114
+
115
+ ### `shared/data-store/`
116
+
117
+ A small reactive `Record<string, unknown>` store with `get`, `update`, and
118
+ `subscribe`. Used as the single source of truth per action runtime: the
119
+ runtime writes to it, the layout renderer reads from it via a narrow
120
+ `DataStoreView` (`{ get }`-only) interface.
121
+
122
+ ### `shared/event-bus/`
123
+
124
+ Topic-based pub/sub. Validates events against `NovaEventSchema` before
125
+ dispatch. Used for ambient UI events such as `ui:model`. Handlers receive
126
+ typed `NovaEvent` payloads. Subscriptions return cleanup functions.
127
+
128
+ ### `shared/message-bus/`
129
+
130
+ Channel-based pub/sub, distinct from the event bus. Carries
131
+ `MessageEnvelope` structures with a `channel` and arbitrary `payload`.
132
+ Trigger configs with a `message` field bind to this bus.
133
+
134
+ The two buses are **independent**. The previous `msg:<channel>` prefix
135
+ bridge through the event bus is gone.
136
+
137
+ ### `shared/ids.ts`, `shared/common.ts`
138
+
139
+ `createIdFactory(prefix)` for instance/shell ids; small type guards
140
+ (`isObject`, `isString`, etc.); shared `Unsubscribe` type.
141
+
142
+ ---
143
+
144
+ ## `layout/`
145
+
146
+ ### Schemas (`layout/schemas.ts`)
147
+
148
+ Zod schemas for the layout DSL:
149
+
150
+ - `LayoutPrimitiveSchema` — string, number, boolean, null.
151
+ - `ComponentNodeSchema` — `{ component, props?, children?, ref?, model?,
152
+ events? }`.
153
+ - `ConditionalNodeSchema` — `{ if, then, else? }`.
154
+ - `LoopNodeSchema` — `{ for, as, key?, do }`.
155
+ - `LayoutRefNodeSchema` — `{ ref }`. Resolves against the layout store.
156
+ - `LayoutNodeSchema` — discriminated union of all of the above plus arrays.
157
+
158
+ ### Renderer (`layout/renderer.ts`)
159
+
160
+ Walks a `LayoutNode` and emits a `RenderNode[]` tree:
161
+
162
+ ```
163
+ RenderComponentNode { type: 'component'; name; props; children;
164
+ ref?; model?: { ref, path } }
165
+ RenderTextNode { type: 'text'; value }
166
+ RenderFragmentNode { type: 'fragment'; children }
167
+ RenderErrorNode { type: 'error'; message }
168
+ ```
169
+
170
+ The renderer:
171
+
172
+ 1. Resolves every binding via `@shared/bindings.resolve`.
173
+ 2. Wraps every child render in a try/catch boundary. In **lax mode**,
174
+ subtree failures become `RenderErrorNode`s; siblings continue. In
175
+ **strict mode**, the throw escapes.
176
+ 3. Looks up component metadata in the `ComponentRegistry`. Missing
177
+ components throw `ComponentNotFoundError`.
178
+ 4. Resolves `LayoutRefNode` against the `LayoutStore`. Missing refs throw
179
+ `LayoutRefNotFoundError`.
180
+ 5. Tracks absolute scope paths. When a `model: "$item.field"` appears
181
+ inside a loop, the renderer materializes the absolute path
182
+ (`items.0.field`) on the emitted `RenderComponentNode.model.path`.
183
+ This is what makes two-way binding work for loop items.
184
+
185
+ ### Layout store and registry
186
+
187
+ `LayoutStore.set` validates every layout against `LayoutNodeSchema` and
188
+ throws `DefinitionValidationError` on failure — boundary validation.
189
+
190
+ `ComponentRegistry` is a name → metadata map. Adapters fill it with their
191
+ own component implementations later.
192
+
193
+ ---
194
+
195
+ ## `action/`
196
+
197
+ ### Schemas (`action/schemas/`)
198
+
199
+ Split into focused files:
200
+
201
+ - `effects.ts` — `CallEffect`, `EmitEffect`, navigation effects (`Push`,
202
+ `Pop`, `Replace`).
203
+ - `triggers.ts` — `TriggerConfigSchema { event?, message?, ref?, do }`.
204
+ - `endpoints.ts` — `EndpointConfigSchema`: a function call `{ fn, target?,
205
+ errorTarget? }` **or** an HTTP call `{ method, url, headers?, request?,
206
+ response?, target?, errorTarget? }`. `request` is run by the injected
207
+ `transform` evaluator over the action data to build the body; `response` is
208
+ run over the reply exactly as received (`$` is the reply — object, array, or
209
+ scalar; no wrapping) to produce the value stored at `target`. Both are opaque
210
+ to Nova (the host injects the interpreter, e.g.
211
+ Prism), so Prism stays an optional dependency; declaring either without an
212
+ injected transform errors. The injected transform is endpoint-only — initial
213
+ data is never transformed.
214
+ - `lifecycle.ts` — `LifecycleConfigSchema { mount?, unmount?, suspend?,
215
+ resume? }`. Each is `Step[]`.
216
+ - `index.ts` — `StepSchema = Mutation | Effect`, `ActionDefinitionSchema`,
217
+ exports.
218
+
219
+ ### Mutations (`action/mutations/`)
220
+
221
+ **Op-per-file.** Each operator lives in `action/mutations/ops/{name}.ts`
222
+ and exports a `match` predicate plus an `apply` function. A registry
223
+ (`action/mutations/registry.ts`) dispatches by walking the ops and using
224
+ the first match. Adding a mutation is a new file, not an edit to a
225
+ giant switch.
226
+
227
+ Current ops: `set`, `toggle`, `increment`, `decrement`, `push`, `pop`,
228
+ `removeAt`, `clear`, `reset`.
229
+
230
+ Each op has its own Zod schema. The combined `MutationSchema` is the
231
+ union.
232
+
233
+ ### Runtime (`action/runtime/`)
234
+
235
+ `createActionRuntime(config)` produces an `ActionRuntime`:
236
+
237
+ - **`runtime.ts`** — assembles the data store, abort controller,
238
+ trigger handle, model listeners, status subscribers. Owns the
239
+ lifecycle methods (`mount`, `unmount`, `suspend`, `resume`).
240
+ - **`lifecycle.ts`** — `buildInitialData` merges `definition.data` with
241
+ input (clone only — no transform); `runLifecycleHook`
242
+ invokes the hook's steps with `lifecycleHook` set on the step
243
+ context. In strict mode it rethrows hook failures as `LifecycleError`;
244
+ in lax mode it routes them through `ctx.onError`.
245
+ - **`steps.ts`** — `executeSteps` walks a `Step[]`. Mutations are
246
+ buffered and flushed in batches; effects (`call`, `emit`, navigation)
247
+ flush first, then run. `runCall` invokes endpoints via `callEndpoint`
248
+ and routes success/failure through `onSuccess` / `onError` step
249
+ branches. When a step is running inside a lifecycle hook
250
+ (`ctx.lifecycleHook` set) and an unknown endpoint or unhandled
251
+ endpoint failure occurs, `runCall` throws `LifecycleError` so the
252
+ lifecycle wrapper can route it.
253
+ - **`endpoints.ts`** — pure `callEndpoint(...)` returning a `Result`.
254
+ Honors `AbortSignal` from `ctx.signal`.
255
+ - **`triggers.ts`** — wires trigger configs to the event bus or
256
+ message bus and runs their `do` steps when fired.
257
+ - **`render.ts`** — calls `renderLayoutFromStore` (or inline layout)
258
+ with the action's data, returning `RenderNode[]`.
259
+ - **`model-bindings.ts`** — walks a `RenderNode[]` collecting
260
+ `(ref, path)` pairs from `model` fields.
261
+
262
+ ### Later bodies, and the calls an instance has made
263
+
264
+ A response may change after it resolved. `FetchResponse.onChange` is a
265
+ transport saying so — moss offers it for a reactive vex read. `runCall`
266
+ applies every later body exactly as it applied the first: the endpoint's
267
+ `response` transform, then `target`. Nothing else runs — no `onSuccess`, no
268
+ telemetry, no loading flag — because a later body is data, not a call. A body
269
+ the transform rejects is dropped; the screen keeps its last good value. Nova
270
+ does not know why a body changed, and there is nothing in a definition to
271
+ declare: an endpoint whose transport never offers `onChange` behaves exactly
272
+ as before.
273
+
274
+ The runtime keeps a small ledger per endpoint name (`EndpointCalls`), and it
275
+ does two jobs:
276
+
277
+ - **An older response never writes over a newer one.** Each call takes a
278
+ ticket; a response that lands after a newer call to the same endpoint
279
+ already landed leaves `target` alone. (Before, the slower of two searches
280
+ won — whichever answered last.) Its `onSuccess` still runs; the call
281
+ happened.
282
+ - **One followed answer per endpoint.** A newer call that lands stops
283
+ following the older one — an old search's updates would otherwise keep
284
+ writing over the new one's rows — and unmount (or dispose) stops them all.
285
+
286
+ A bare step context (a test driving `executeSteps` directly) has no ledger:
287
+ every response lands as before and none is followed.
288
+
289
+ ### Two-way binding
290
+
291
+ When the layout author writes `model: "$.user.name"` on a component, the
292
+ renderer emits `model: { ref, path: 'user.name' }` on the
293
+ `RenderComponentNode`. After every render, the runtime reconciles its
294
+ `ui:model` event-bus listeners against the live set of model refs:
295
+
296
+ - New ref → install a listener that, on `ui:model` events for that ref,
297
+ applies a `set` mutation to `path`.
298
+ - Removed ref or changed path → tear down the old listener.
299
+
300
+ The framework adapter is responsible for emitting `ui:model` events on
301
+ the event bus when its inputs change.
302
+
303
+ ### AbortSignal threading
304
+
305
+ Each runtime owns an `AbortController`. Its signal is threaded into every
306
+ `StepContext` and forwarded to `fetch` calls inside `callEndpoint`. On
307
+ `unmount`, the controller is aborted before any unmount hooks run, so
308
+ in-flight endpoint calls bail out. Unmount hooks themselves run on a
309
+ fresh (non-aborted) controller so they can perform their own final
310
+ async work.
311
+
312
+ ### Public vs internal runtime types
313
+
314
+ The shell exposes runtimes via `shell.getRuntime(id)` typed as
315
+ `PublicActionRuntime`:
316
+
317
+ ```
318
+ PublicActionRuntime = {
319
+ readonly instance, definition;
320
+ getData(); render();
321
+ onDataChange(handler); onStatusChange(handler);
322
+ }
323
+ ```
324
+
325
+ The wider internal `ActionRuntime` adds `mount`, `unmount`, `suspend`,
326
+ `resume`, `applyMutations`, `executeSteps`, `updateData`, `dispose`, and
327
+ the underlying `dataStore`. **It is not re-exported from the package
328
+ root.** Tests that exercise internals reach it via
329
+ `@shell/shell-internals.getInternalRuntime`.
330
+
331
+ ---
332
+
333
+ ## `shell/`
334
+
335
+ The user's entry point. Splits responsibilities across small files:
336
+
337
+ - **`shell.ts`** — public `createShell` factory. Composes everything,
338
+ defines the public methods, holds the `pendingStrictError` slot, and
339
+ owns the canvas map.
340
+ - **`runtime-registry.ts`** — instance-id → runtime map with subscribe
341
+ hooks for telemetry.
342
+ - **`telemetry.ts`** — state-change, data-change, and endpoint subscriber
343
+ lists. Endpoint events (`EndpointEvent`: name, `fn`/`http`, ok, status,
344
+ ms, stamped with instance and canvas) are reported by `runCall` at the
345
+ `callEndpoint` seam — the one point every call passes through, so a
346
+ server shell whose actions are all `fn:` is observed exactly like an
347
+ HTTP one. Aborted calls are not reported.
348
+ - **`navigation.ts`** — converts `NavigationEffect` (from inside an
349
+ action's steps) into `push`/`pop`/`replace` calls on the shell.
350
+ - **`lifecycle-ops.ts`** — `unmountInstance`, `suspendTop`, `resumeTop`
351
+ bookkeeping. Idempotent unmount via an internal `Set`.
352
+ - **`canvas.ts`** — pure stack: `pushInstance`, `popInstance`,
353
+ `clearStack`, `peek`. No I/O.
354
+ - **`shell-internals.ts`** — `validateActions` (boundary Zod validation
355
+ on the action map at construction), `snapshotCanvas`,
356
+ `createRuntimeFactory`, and the test escape hatch
357
+ `getInternalRuntime`.
358
+
359
+ ### Public API
360
+
361
+ ```
362
+ createShell(config: ShellConfig): Shell
363
+ ```
364
+
365
+ `Shell` exposes:
366
+
367
+ ```
368
+ push(canvasId, actionId, input?, fragments?): string
369
+ pop(canvasId): void
370
+ popTo(canvasId, instanceId): void
371
+ replace(canvasId, actionId, input?, fragments?): string
372
+ clear(canvasId): void
373
+ registerAction(definition): void
374
+ removeAction(actionId): void
375
+ registerFragment(fragment): void
376
+ addCanvas(config): void
377
+ removeCanvas(canvasId): void
378
+ setCanvasLayout(layout): void
379
+ setLayout(refId, layout): void
380
+ getCanvasState(canvasId): CanvasState
381
+ getRuntime(instanceId): PublicActionRuntime | undefined
382
+ getState(): StateSnapshot
383
+ getShellRenderTree(): RenderNode[]
384
+ getCanvasRenderTree(canvasId): RenderNode[]
385
+ flattenRenderTree(tree): RenderNode[]
386
+ dispatch(event): void
387
+ publish(channel, payload?): void
388
+ onStateChange(handler): Unsubscribe
389
+ onDataChange(handler): Unsubscribe
390
+ onEndpoint(handler): Unsubscribe
391
+ onCanvasChange(canvasId, handler): Unsubscribe
392
+ dispose(): void
393
+ ```
394
+
395
+ `fragments` is a list of `ActionFragment` ids to compose the action with
396
+ before it is instantiated (same as a push/replace effect's `with: [...]`).
397
+ See "ActionFragment composition" below.
398
+
399
+ `push`, `pop`, `replace`, `clear`, `getCanvasState` are **synchronous**
400
+ in both lax and strict mode. The runtime's lifecycle methods are async
401
+ underneath, fired with `.catch(handleLifecycleRejection)`.
402
+
403
+ ### Strict mode and error surfacing
404
+
405
+ `ShellConfig.strict: boolean` and `ShellConfig.onError?: (err) => void`
406
+ are plumbed through `ActionRuntimeConfig` into every `StepContext`.
407
+
408
+ - **Lax mode (default).** Lifecycle hook failures are caught inside
409
+ `runLifecycleHook` and routed through `onError`. Renderer subtree
410
+ failures become `RenderErrorNode`s. The shell never throws from a
411
+ lifecycle hook.
412
+
413
+ - **Strict mode.** `runLifecycleHook` rethrows failures as
414
+ `LifecycleError`. The shell catches the rejection in
415
+ `handleLifecycleRejection` and stores it in a single
416
+ `pendingStrictError` slot. The **next** public shell call
417
+ (`push`/`pop`/`replace`/`clear`/`getCanvasState`) consumes the slot
418
+ and throws the stored error before doing any work. Renderer failures
419
+ in strict mode throw out of `render()`.
420
+
421
+ This is the documented contract: shell method signatures stay
422
+ synchronous; strict-mode lifecycle errors surface deterministically at
423
+ the next operation boundary. It is the only honest way to expose async
424
+ fire-and-forget failures via a synchronous API without making
425
+ `push`/`pop` return promises.
426
+
427
+ ### Definition validation at boundaries
428
+
429
+ - `createShell` validates every entry in `config.actions` via
430
+ `ActionDefinitionSchema.safeParse`, aggregating failures into a
431
+ single `DefinitionValidationError`.
432
+ - `LayoutStore.set` validates every layout the same way.
433
+ - `runtime.executeSteps` validates `Step[]` input via
434
+ `StepSchema.safeParse` before running.
435
+
436
+ ### ActionFragment composition
437
+
438
+ An `ActionFragment` is a reusable **partial action** — every
439
+ `ActionDefinition` field optional, plus a `kind: 'fragment'` discriminator.
440
+ It is **abstract**: it lives in a separate registry (`ShellConfig.fragments`
441
+ / `registerFragment`), can never be `push`ed as an action (its id isn't in
442
+ `actions`, so that throws `UnknownActionError`), and only exists once merged.
443
+ Because it is pure data it ships in a DB row and an agent can author it; a
444
+ reference (`with: ['modal']`) collapses an arbitrary amount of chrome to a
445
+ single token in the model's context.
446
+
447
+ Composition is **call-site**, not on the action — an action never knows where
448
+ it renders, so the modal-ness lives on the push: `{ push: { action:
449
+ 'new-contact', with: ['modal'], canvas: 'modal' } }`. The same `with: [...]` is
450
+ accepted on a `replace` effect and on a canvas `initial` seed (`{ action,
451
+ with }`), and as the `fragments?` arg of `shell.push`/`replace`.
452
+ `composeAction(action, fragments[])` produces the effective `ActionDefinition`
453
+ that spawns:
454
+
455
+ - **layout** — `fillSlots(fragment.layout, { body: action.layout })`: the
456
+ fragment is the outer chrome, the action's own layout is dropped into the
457
+ fragment's `{ slot: 'body' }` node. The fragment wraps; the action is the
458
+ innermost content. Multiple fragments fold in array order (last listed is
459
+ outermost). An unfilled slot renders nothing.
460
+ - **data / endpoints** — shallow-merge, **action wins** on conflict.
461
+ - **triggers** — concat, fragment's first (so a fragment's `close`/`cancel`
462
+ and the action's `confirm` coexist; authors keep refs distinct).
463
+ - **lifecycle** — per-hook concat, fragment steps run before the action's.
464
+ - **id / name / description** — the action's. The result is a full
465
+ `ActionDefinition` with no `kind` — composition, not inheritance.
466
+
467
+ `slot` is a fourth layout placeholder (beside `LayoutRef`): `{ slot: name }`,
468
+ filled only at compose time by `fillSlots`. A slot that survives to the
469
+ renderer was never filled, so the renderer emits nothing for it. This is the
470
+ single seam a fragment uses to wrap an action; named/multiple slots are future
471
+ work (v1 fills one `body` slot with the action's `layout`).
472
+
473
+ ---
474
+
475
+ ## Data flow (push to render)
476
+
477
+ 1. User calls `shell.push('main', 'A', input)`.
478
+ 2. `validateActions` already passed at construction. `getDefinition('A')`
479
+ returns the validated `ActionDefinition`. When the call carries
480
+ `fragments` (or the effect a `with: [...]`), `composeAction` folds the
481
+ named fragments into the definition first (see "ActionFragment
482
+ composition"); the merged result is what spawns.
483
+ 3. `ops.suspendTop(canvas)` runs the previous top's `suspend` hook
484
+ (fire-and-forget; strict mode wires errors back).
485
+ 4. `spawn` calls `buildRuntime` → `createActionRuntime`. The runtime
486
+ builds its data store from `definition.data` merged with `input`,
487
+ creates an `AbortController`, registers triggers.
488
+ 5. `runtime.mount(input)` is fired and not awaited. It runs the
489
+ `mount` lifecycle hook via `runLifecycleHook`, then transitions to
490
+ `active`. Failures route through the strict/lax pipeline.
491
+ 6. The new instance is pushed onto the canvas; `fireState()` notifies
492
+ state subscribers.
493
+ 7. The adapter (when one exists) calls `runtime.render()` which returns
494
+ `RenderNode[]`. The runtime reconciles model bindings against the
495
+ produced tree.
496
+
497
+ ---
498
+
499
+ ## Future work
500
+
501
+ The following are explicitly **not implemented** and have no design
502
+ yet beyond a placeholder:
503
+
504
+ - ~~**React adapter.**~~ **Implemented.** See "React adapter" below.
505
+ - ~~**Headless component primitives.**~~ **Implemented.** Reference kits
506
+ ship at `/adapters/react/components`, `/adapters/vue/components`,
507
+ `/adapters/dom/components`, `/adapters/tty/components`, and `/adapters/ink`.
508
+ - **Wire protocol.** No serialization format for shipping *definitions*
509
+ across processes. Serving rendered trees over a socket is moss's job;
510
+ nova ships the surface it targets (`RenderApi`, ActionSlot-preserving
511
+ `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.
515
+
516
+ ---
517
+
518
+ ## React adapter
519
+
520
+ The React adapter lives under `src/adapters/react/` and ships at the
521
+ `@niscorp/nova/adapters/react` subpath. It is a thin layer over the
522
+ framework-agnostic core — no shell logic lives in React, and React is a
523
+ peer (optional) dependency of the core package.
524
+
525
+ ### Two-provider pattern
526
+
527
+ There are deliberately two providers:
528
+
529
+ - **`<NovaRenderProvider>`** — pairs a component registry with a
530
+ `dispatch` and `publish` function. It does NOT require a shell. This
531
+ is the minimum needed to render a `RenderNode[]` into React. Use it
532
+ for static layouts, snapshot tests, or any scenario where you have
533
+ data but no orchestrator.
534
+ - **`<NovaShellProvider>`** — a thin wrapper around `<NovaRenderProvider>`
535
+ that ALSO exposes a `Shell` via context. Internally it derives
536
+ `dispatch`/`publish` from `shell.dispatch` / `shell.publish` and
537
+ forwards them to the inner render provider. Hooks like `useShellState`,
538
+ `useCanvas`, `useRenderTree`, `useActionData`, `useActionStatus`
539
+ require a `<NovaShellProvider>` ancestor; the bare hooks
540
+ (`useNovaDispatch`, `useNovaPublish`, `useNovaRegistry`) work under
541
+ either.
542
+
543
+ ### The provider does NOT own the shell
544
+
545
+ This is a deliberate contract. `NovaShellProvider` never calls
546
+ `shell.dispose()` on unmount or on shell-prop change — it merely
547
+ re-points its context. Lifecycle ownership stays with the consumer that
548
+ created the shell. This is verified by `test/react/shell-swap.test.tsx`,
549
+ which spies on `shell.dispose` and asserts it is never invoked. Swapping
550
+ the `shell` prop causes hooks to resubscribe to the new shell on the
551
+ next render via the standard `useSyncExternalStore` plumbing.
552
+
553
+ ### Component prop injection is minimal
554
+
555
+ A nova component registered with the React adapter receives:
556
+
557
+ - `children?: ReactNode` — populated when the layout node has children
558
+ - `novaModel?: { ref, path }` — populated when the layout node has a
559
+ `model:` binding (so the component can dispatch `ui:model` events)
560
+ - ...the layout node's `props` spread on top
561
+
562
+ That's it. Components do not receive a `shell`, an `instanceId`, an
563
+ `onChange`, or any other framework-supplied callback. If a component
564
+ needs to emit, it calls `useNovaDispatch()` or `useNovaPublish()`. If a
565
+ component needs to introspect the registry, it calls
566
+ `useNovaRegistry()`. New props on the `NovaComponentProps` bag require
567
+ explicit justification.
568
+
569
+ ### The `slotWrapper` seam
570
+
571
+ Cross-cutting rendering concerns — enter/leave animation, auth / feature
572
+ gates, logging, error boundaries — do not belong in the core. Animation in
573
+ particular is fickle and opinionated (framer-motion vs react-transition-group
574
+ vs plain CSS), so the core owns **none** of it. Instead the React adapter
575
+ exposes a single seam: an optional `slotWrapper` component, threaded through
576
+ `NovaRenderContext` (so it reaches deeply-nested slots) and accepted on
577
+ `<Nova.Shell>` and both providers.
578
+
579
+ Deliberate boundaries:
580
+
581
+ - **Adapter-only, never core.** `slotWrapper` is a React component — it lives
582
+ in `src/adapters/react`, not in `ShellConfig` or any schema. The core stays
583
+ serializable data + a state machine; the Vue adapter exposes its own
584
+ equivalent (a Vue component handed the same identity props). Nothing here touches `LayoutNode`, so a model-authored (or
585
+ DB-stored) layout never carries animation/gate concerns.
586
+ - **One seam: `ActionSlot`.** That is the single place an instance's content
587
+ mounts and unmounts. `CanvasSlot` is a router (it expands to `ActionSlot`s),
588
+ so it is not wrapped — there is exactly one place a wrapper exists, which is
589
+ why the wrapper takes no `kind` discriminator.
590
+ - **Identity, not state.** The wrapper receives `{ canvasId, instanceId,
591
+ action }` (resolved from `shell.getRuntime(instanceId)`), never the live
592
+ data. `canvasId`/`action` are the policy axes (route by region or by
593
+ `action.id`); `instanceId` is the keying axis. Passing live data would turn
594
+ a presence/gate seam into a reactive render path — the wrong tool.
595
+ - **Persistent render, no timing.** When a `slotWrapper` is present,
596
+ `ActionSlot` renders it even with no active instance (`children` becomes
597
+ `null`, identity becomes `undefined`), so a presence-managing wrapper can
598
+ hold and animate the leaving content. The core disposes the instance
599
+ immediately on pop; nova never waits on `animationend` or any completion
600
+ callback — the wrapper (and whatever library it plugs in) owns the exit
601
+ lifecycle entirely.
602
+ - **Passthrough default.** With no `slotWrapper`, `ActionSlot` renders exactly
603
+ as before. Generated layouts that introduce new canvases flow through the
604
+ same single wrapper and hit its default branch — nothing is registered per
605
+ slot.
606
+
607
+ Verified by `test/react/slot-wrapper.test.tsx` (correct identity, passthrough
608
+ default, and that the wrapper still mounts for an empty slot so exits can run).
609
+
610
+ ### Snapshot caching strategy
611
+
612
+ Both `useRenderTree` and `useCanvas` cache their snapshot via `useRef`
613
+ so `useSyncExternalStore`'s `getSnapshot` returns a stable reference
614
+ when nothing has changed. This is mandatory for tearing-safety in
615
+ React 18 concurrent rendering.
616
+
617
+ - **`useRenderTree`** caches by **data identity**. The runtime exposes
618
+ the current data object; if the cached data reference is `===` to the
619
+ current one, the cached `RenderNode[]` is returned unchanged. When
620
+ the runtime mutates data, the new data object replaces the old, the
621
+ cache misses, the layout is re-rendered, and the new `RenderNode[]`
622
+ becomes the cached snapshot. A missing instance returns a singleton
623
+ `EMPTY` constant so re-renders are also stable in that case.
624
+ - **`useCanvas`** caches via a structural comparison helper
625
+ (`sameActive`) over the canvas's stack length, active id, and per-
626
+ frame `(id, status)` tuples. If two consecutive `getCanvasState`
627
+ results compare equal under that helper, the cached value is reused;
628
+ otherwise the new state is captured and the React store is notified.
629
+
630
+ Both contracts are verified by `test/react/snapshot-stability.test.tsx`,
631
+ which asserts referential equality across re-renders without state
632
+ changes and reference inequality after a real data or stack change.
633
+
634
+ ### React 18+ compatibility
635
+
636
+ - Requires React 18 or later (uses `useSyncExternalStore`).
637
+ - Concurrent rendering: tearing-safe by construction.
638
+ - StrictMode: works correctly; snapshot caches survive effect double-
639
+ invocation.
640
+ - Suspense: not used as a loading model. Loading state is explicit data
641
+ on the action. Nova hooks never throw promises.
642
+ - SSR: the shell-backed hooks draw where there is no browser. Each passes its
643
+ own `getSnapshot` as `useSyncExternalStore`'s server snapshot — a shell is
644
+ the same object on a server, at a build, and in the page, so the value it
645
+ holds is the value to draw. That is what lets an app with its OWN shell (no
646
+ server holding one) be drawn ahead of time: its boot runs at build,
647
+ `shellSettled` waits for the first screen to be whole, `renderToString` draws
648
+ it through these hooks, and the page's boot adopts the markup with
649
+ `hydrateRoot`. A SERVED tree needs none of this — it renders through
650
+ `RenderTree` over a `RenderApi`, which touches no store (moss's
651
+ `terminal/react/server`). `shellView(shell)` is the bridge between the two:
652
+ a local shell, read as a `RenderApi`.
653
+ - React Server Components: not tested. Hooks are client-only.
654
+
655
+ ---
656
+
657
+ ## Serving trees: `RenderApi` and flattening
658
+
659
+ A remote renderer (a moss terminal) never holds a shell; it is handed a
660
+ `RenderApi` — `frame()`, `canvasTree(canvasId)`, `dispatch(canvasId, event)`,
661
+ `publish(channel, payload?)`. One shape shared by the DOM adapter, the React
662
+ terminal target, and moss's conductor, aliased rather than redeclared, so a
663
+ renderer written against one host drops onto another. Origin stamping is the
664
+ host's job, not the renderer's.
665
+
666
+ `flattenRenderTree` resolves `CanvasSlot` markers away but keeps the
667
+ `ActionSlot` marker: a component node with
668
+ `props: { instanceId, canvasId, definitionId }`, `key: instanceId`, children
669
+ = the instance's rendered tree. Deliberate: a served tree must still carry
670
+ instance identity, so a remote renderer can key by instance (a swap remounts
671
+ — no stale DOM state crossing instances, enter animations fire) and a
672
+ terminal-side slot wrapper has a seam. Identity only, never the definition —
673
+ wire weight.
674
+
675
+ ## DOM adapter
676
+
677
+ `src/adapters/dom/` (`@niscorp/nova/adapters/dom`) renders a served tree to
678
+ 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
681
+ kit (`/adapters/dom/components`: `defaultRegistry`, `fallback`,
682
+ `DEFAULT_CSS`, `ROOT_CLASS`) is the batteries-included reference set. It
683
+ exists as the proof that a terminal needs no framework — and as the adapter
684
+ sibling that keeps the adapter contract honest.
685
+
686
+ ## Terminal adapters
687
+
688
+ `src/adapters/tty/` renders a served tree to plain text: `createTtyView` is
689
+ a pure `RenderApi` → `{ text, interactives }` — no framework, no I/O, no
690
+ node builtins. The walker applies the event conventions itself (`ref` →
691
+ a numbered `[n]` marker registered as a click, `model` → model/toggle by
692
+ value type), so the interactives table is a complete, ordered action space
693
+ a host maps commands (or an agent's tool calls) onto. `src/adapters/ink/`
694
+ is the full-screen sibling: an Ink component kit riding the REACT walker
695
+ (the walker is renderer-agnostic — zero react-dom), with the same `[n]`
696
+ markers resolved through `CanvasMarkersContext` — the host computes the
697
+ numbering by running the TTY walker over the same trees, so both terminals
698
+ agree on what `[7]` is. Marker identity is the click payload for
699
+ click-kinds (a list's rows share one ref) and sibling order for
700
+ model-kinds. See TERMINAL_DOCS.md.
701
+
702
+ ## Reflect and devtools
703
+
704
+ `reflect/` formalizes the walks moss and app devtools kept re-deriving.
705
+ Everything in nova is closed, validated data — definitions, layouts, the
706
+ live shell — so introspection can be complete, a thing no code-based UI
707
+ framework offers. Structural walkers (`walkNodes`, `componentsOf`, `refsOf`,
708
+ `loopVarsOf`), shell state (`snapshotShell`, `describeInstance`), the action
709
+ adjacency (`actionGraph`), and audit triage (`classifyAudit`,
710
+ `auditCatalog`). Pure, framework-free, read-only.
711
+
712
+ `devtools/` is the consumer proof: the dock and inspector are plain
713
+ ActionDefinitions over generic primitives (Panel, JsonTree), so they render
714
+ in any terminal. `createDevtoolsFunctions` builds the `devtools.*` fns per
715
+ session — a closure over that session's shell, no module globals, so
716
+ introspection is per-session-correct under moss. The endpoint timeline is a
717
+ capped ring buffer fed by `shell.onEndpoint` (notify-then-pull: the fn is
718
+ the pull), and the devtools canvas excludes itself so the inspector never
719
+ observes its own traffic.