@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/README.md ADDED
@@ -0,0 +1,379 @@
1
+ # @niscorp/nova
2
+
3
+ Declarative, framework-agnostic UI runtime for actions composed from JSON
4
+ layouts and effects.
5
+
6
+ **Status:** `0.x.x` — pre-1.0, breaking changes expected.
7
+
8
+ ## One tree, five renderers
9
+
10
+ Nova core renders layouts to plain `RenderNode[]` — no framework, no DOM,
11
+ no terminal. What consumes that tree is an adapter, and five ship here:
12
+
13
+ | adapter | surface | interaction |
14
+ | ---------------- | ------------------------- | ---------------------------------------------------------- |
15
+ | `adapters/react` | browser, your styled kit | pointer + keyboard |
16
+ | `adapters/vue` | browser, your styled kit | pointer + keyboard |
17
+ | `adapters/dom` | browser, zero framework | pointer + keyboard |
18
+ | `adapters/tty` | any terminal, line REPL | every interactive carries a `[n]` marker — type the number |
19
+ | `adapters/ink` | any terminal, full-screen | the same `[n]` markers, plus focus and live typing |
20
+
21
+ Same trees down, same `ui:click` / `ui:model` / `ui:key` events up — an app
22
+ renders in all five without changing a line, and a served host (see
23
+ `@niscorp/moss`) cannot tell them apart. The TTY numbering is computed once
24
+ and shared: `[7]` is the same interactive in the REPL and the TUI.
25
+
26
+ An adapter is a walker plus a component kit of ~15 domain-blind primitives.
27
+ [ADAPTER.md](ADAPTER.md) is the whole contract; the terminal adapters' APIs
28
+ are in [TERMINAL_DOCS.md](TERMINAL_DOCS.md); a Svelte or react-native
29
+ adapter is a sibling folder, built the way the Vue one is.
30
+
31
+ Components are decoupled from the shell — they receive only the layout's
32
+ `props` plus `children` / `novaModel`, and emit events via context hooks.
33
+ The React adapter additionally ships `<NovaRenderProvider>`,
34
+ `<NovaShellProvider>`, `<RenderTree>`, and the shell hooks; see
35
+ `REACT_DOCS.md`.
36
+
37
+ An optional `slotWrapper` prop wraps every action instance's content at
38
+ its mount/unmount seam — one pluggable point for animation, auth / feature
39
+ gates, logging, or error boundaries, with nova owning none of that logic.
40
+ See `REACT_DOCS.md`.
41
+
42
+ ---
43
+
44
+ ## What it is
45
+
46
+ Nova is a runtime for **actions**: stateful units of work backed by data,
47
+ endpoints, triggers, lifecycle hooks, and a JSON layout. A `Shell` hosts
48
+ a stack of action instances per **canvas** (a logical surface — a screen,
49
+ a panel, a modal stack), drives their lifecycle, and routes events and
50
+ messages between them.
51
+
52
+ The core is pure TypeScript with **zero framework dependencies**. The
53
+ renderer produces a `RenderNode[]` tree — a plain JSON-shaped structure
54
+ that any framework adapter (React, Vue, headless test harness) can turn
55
+ into real elements. Layout, action, and shell logic are all testable
56
+ without ever importing a UI framework.
57
+
58
+ What makes it different from "just another UI library":
59
+
60
+ - **Declarative.** Layouts and actions are JSON. The runtime walks them.
61
+ - **Headless core.** No framework lock-in. Adapters are thin.
62
+ - **Two-way binding** built into the layout DSL via `model: "$.path"`.
63
+ - **Strict / lax modes** that decide whether errors throw or are
64
+ surfaced via `onError`.
65
+
66
+ ## What it isn't
67
+
68
+ Explicitly out of scope right now:
69
+
70
+ - **No LLM features.** No prompt scaffolding, no plan generation.
71
+ - **No JSON Schema generation / catalog.** Use `z.toJSONSchema()` on
72
+ the exported Zod schemas if you need JSON Schema externally.
73
+ - **No mandatory components.** The component registry is empty by
74
+ default; opt-in reference kits ship at the adapter subpaths
75
+ (`/adapters/react/components`, `/adapters/vue/components`,
76
+ `/adapters/dom/components`, `/adapters/tty/components`, `/adapters/ink`).
77
+ - **No page around the screen.** Nova draws a shell to markup where there is
78
+ no browser (the React hooks, Vue's server renderer, the DOM adapter's
79
+ `renderToString`) and picks that markup up in the page — but the document,
80
+ the paths and the checks a build makes are a host's (`@niscorp/cli`'s `nisc
81
+ export`, or moss for a served shell). See the React compatibility section
82
+ below.
83
+ - **No wire protocol.** Definitions are in-process objects, not a
84
+ serialization format. The wire lives in moss; nova ships the render
85
+ surface a remote terminal targets (`RenderApi`, flattened trees that
86
+ keep `ActionSlot` identity).
87
+
88
+ ---
89
+
90
+ ## Quick example
91
+
92
+ ```ts
93
+ import {
94
+ createShell,
95
+ createComponentRegistry,
96
+ createLayoutStore,
97
+ type ActionDefinition,
98
+ } from '@niscorp/nova';
99
+
100
+ const counter: ActionDefinition = {
101
+ id: 'counter',
102
+ data: { count: 0 },
103
+ triggers: [
104
+ {
105
+ event: 'ui:click',
106
+ ref: 'inc',
107
+ do: [{ increment: 'count' }],
108
+ },
109
+ ],
110
+ layout: {
111
+ component: 'Box',
112
+ children: [
113
+ { component: 'Text', props: { value: '{{$.count}}' } },
114
+ { component: 'Button', ref: 'inc', props: { label: '+1' } },
115
+ ],
116
+ },
117
+ };
118
+
119
+ const shell = createShell({
120
+ canvases: [{ id: 'main' }],
121
+ registry: createComponentRegistry(),
122
+ layoutStore: createLayoutStore(),
123
+ actions: { counter },
124
+ });
125
+
126
+ const id = shell.push('main', 'counter');
127
+ const runtime = shell.getRuntime(id);
128
+ console.log(runtime?.render());
129
+ // → RenderNode[] tree describing the Box / Text / Button
130
+ ```
131
+
132
+ There is no React in that example. A framework adapter would consume
133
+ the same `RenderNode[]` and produce real elements.
134
+
135
+ ---
136
+
137
+ ## The three subsystems
138
+
139
+ ### Layout
140
+
141
+ A JSON tree of components, conditionals, loops, refs, and primitives.
142
+ `renderLayout(node, data)` walks the tree, resolves bindings, and emits
143
+ `RenderNode[]`. Bindings come in two forms:
144
+
145
+ - `"$.user.name"` — bare path, returns the raw value.
146
+ - `"Hello {{$.user.name}}"` — interpolated string.
147
+
148
+ Conditionals at the value level use `{ $if, $then, $else }`. Layout
149
+ nodes also have first-class `if` / `for` / `ref` shapes. See
150
+ `LayoutNodeSchema`.
151
+
152
+ ### Action
153
+
154
+ A stateful unit. An `ActionDefinition` carries:
155
+
156
+ - `data` — the initial state record.
157
+ - `input` — optional JSON Schema of the `data` keys an opener may seed
158
+ when loading the action (its openable-input contract; descriptive,
159
+ not enforced by the runtime).
160
+ - `endpoints` — named HTTP or local-function call configurations, with
161
+ optional `request`/`response` transform configs run by the injected
162
+ evaluator.
163
+ - `triggers` — `(event | message) + ref → do: Step[]` bindings.
164
+ - `lifecycle` — `mount`, `unmount`, `suspend`, `resume` hooks, each a
165
+ `Step[]`.
166
+ - `layout` — the layout to render.
167
+
168
+ A `Step` is either a **mutation** (one of `set`, `toggle`, `increment`,
169
+ `decrement`, `push`, `pop`, `removeAt`, `move`, `clear`, `reset`) or an
170
+ **effect** (`call`, `emit`, navigation `push`/`pop`/`replace`/`popTo`/`resetTo`/
171
+ `removeInstance`/`removeSelf`/`reconcile`, `reload`).
172
+ Mutations are op-per-file under `action/mutations/ops/`.
173
+
174
+ Every navigation step moves ONE action. `reconcile` is the one that moves as
175
+ many as data says: it makes a canvas hold exactly the actions a list in the
176
+ action's data names — missing ones pushed, unlisted ones removed, the rest kept
177
+ mounted (`shell/reconcile.ts`, as a step). A row naming an action the shell
178
+ does not have is skipped, as an ungranted `initial` candidate is.
179
+
180
+ ```ts
181
+ { reconcile: { canvas: 'tools', to: '$.tools', action: 'tool_id', own: 'canvas' } }
182
+ ```
183
+
184
+ `action` names the row field holding the action id; `input` (optional) the field
185
+ holding its input. `own: 'pushed'` (default) removes only what this action placed
186
+ there — stamped with its definition id — while `'canvas'` treats the whole canvas
187
+ as the action's. Added at grammar `nisc.nova` 1: a reader at 0 refuses an action
188
+ that uses it (`TOO_NEW`).
189
+
190
+ The runtime is a closure factory (`createActionRuntime`) — no classes.
191
+ It owns a reactive data store, an `AbortController`, the trigger
192
+ handles, and the model-binding listeners.
193
+
194
+ An `ActionFragment` is a reusable partial action (every field optional, a
195
+ `kind: 'fragment'` marker) — layout chrome plus wired triggers/data. It is
196
+ composed into a concrete action at the call site via a push/replace
197
+ `with: ['id']`: the fragment wraps the action, dropping the action's layout
198
+ into its `{ slot: 'body' }`; the action wins on conflict. Pure data, so it
199
+ ships in a DB row and can be referenced rather than inlined.
200
+
201
+ ### Shell
202
+
203
+ The orchestrator. `createShell(config)` validates every action
204
+ definition at construction (boundary Zod validation) and returns a
205
+ `Shell` with `push`, `pop`, `popTo`, `replace`, `clear`,
206
+ `registerAction`, `registerFragment`, `addCanvas`, `removeCanvas`,
207
+ `setCanvasLayout`, `setLayout`, `getCanvasState`, `getRuntime`,
208
+ `getState`, `getShellRenderTree`, `getCanvasRenderTree`,
209
+ `flattenRenderTree`, `dispatch`, `publish`, `onStateChange`,
210
+ `onDataChange`, `dispose`. Canvases are `CanvasConfig`s (`{ id,
211
+ actionLayout?, initial? }`) — a canvas can pre-seed its stack and
212
+ declare how its instances are arranged. The shell maintains a stack per
213
+ canvas, drives lifecycle hooks via the runtime, composes any `with`
214
+ fragments into the action at push/replace time, and routes navigation
215
+ effects emitted from action steps back into shell calls.
216
+
217
+ ---
218
+
219
+ ## Authoring
220
+
221
+ The Zod schemas are the source of truth and are validated at every
222
+ boundary. They are exported from the package root:
223
+
224
+ - `LayoutNodeSchema`, `ComponentNodeSchema`, `ConditionalNodeSchema`,
225
+ `LoopNodeSchema`, `LayoutRefNodeSchema`, `SlotNodeSchema`
226
+ - `ActionDefinitionSchema`, `ActionFragmentSchema`, `MutationSchema`,
227
+ `StepSchema`, `EffectSchema`, `TriggerConfigSchema`,
228
+ `EndpointConfigSchema`, `LifecycleConfigSchema`
229
+
230
+ Boundary throws use `DefinitionValidationError` with a structured
231
+ `failures` array.
232
+
233
+ ---
234
+
235
+ ## Errors and strict mode
236
+
237
+ `ShellConfig` accepts `strict?: boolean` and `onError?: (err) => void`.
238
+
239
+ - **Lax mode (default).** Lifecycle failures route through `onError`.
240
+ Renderer subtree failures become `RenderErrorNode`s and siblings
241
+ continue.
242
+ - **Strict mode.** Lifecycle failures rethrow as `LifecycleError`. Shell
243
+ methods stay synchronous, so the error is stored in a one-slot
244
+ buffer and surfaces at the **next** public shell call (`push`,
245
+ `pop`, `replace`, `clear`, `getCanvasState`). Renderer failures
246
+ throw out of `render()`.
247
+
248
+ The error hierarchy lives in `shared/errors.ts`:
249
+
250
+ ```
251
+ NovaError
252
+ ├── RenderError
253
+ ├── ComponentNotFoundError
254
+ ├── LayoutRefNotFoundError
255
+ ├── DefinitionValidationError
256
+ ├── UnknownActionError
257
+ ├── ShellDisposedError
258
+ └── LifecycleError
259
+ ```
260
+
261
+ All carry a stable `code` (`ErrorCodes.*`), an optional `context`, and
262
+ a JS-native `cause`.
263
+
264
+ ---
265
+
266
+ ## Two-way binding
267
+
268
+ A layout component can declare `model: "$.user.name"`. The renderer
269
+ emits `model: { ref, path: 'user.name' }` on the corresponding
270
+ `RenderComponentNode`. The action runtime auto-installs a `ui:model`
271
+ event listener for that `ref`. The framework adapter is responsible
272
+ for emitting `ui:model` events on the event bus when its inputs
273
+ change; the runtime responds by applying a `set` mutation to the
274
+ configured path.
275
+
276
+ `model` paths inside loops are resolved to **absolute** paths
277
+ (`items.0.value`) by the renderer using its scope-path tracker, so
278
+ loop items round-trip correctly.
279
+
280
+ ---
281
+
282
+ ## Async safety
283
+
284
+ Every `StepContext` carries an `AbortSignal` from a runtime-owned
285
+ `AbortController`. `callEndpoint` forwards the signal to `fetch`. On
286
+ `unmount`, the controller is aborted, so in-flight calls bail out
287
+ without leaks. Unmount hooks themselves run on a fresh signal so they
288
+ can perform their own final async work (e.g. telemetry flush).
289
+
290
+ ---
291
+
292
+ ## React compatibility
293
+
294
+ - **React 18+ required.** The adapter uses `useSyncExternalStore`.
295
+ - **Concurrent rendering:** fully supported. `useSyncExternalStore` is
296
+ tearing-safe by design — the snapshot getters in `useRenderTree` and
297
+ `useCanvas` return referentially-stable values when the underlying data
298
+ or canvas hasn't changed, which the reference-stability tests verify.
299
+ - **StrictMode:** supported. Snapshot caches correctly handle effect
300
+ double-invocation; nothing tears and no "snapshot returned different
301
+ values" warning appears.
302
+ - **Suspense:** not used as a loading model. Loading state is explicit
303
+ data on the action (e.g. `{loading: true}` as a regular field), so the
304
+ layout renderer reacts to it through data bindings. Consumers can still
305
+ wrap nova components in `<Suspense>` but it never activates — nova
306
+ hooks never throw promises. This is intentional: actions model their
307
+ async state as data so layouts can bind to it directly, rather than
308
+ unwinding the tree for Suspense to catch.
309
+ - **SSR:** supported both ways a screen can be held. A shell that lives with
310
+ its adapter — `<NovaShell>` and the shell-backed hooks — draws under
311
+ `renderToString` (each hook's server snapshot is the shell's own value) and
312
+ is adopted by `hydrateRoot` over a second boot of the same shell: await
313
+ `shellSettled(shell)` before either, so both draw the whole first screen. A
314
+ served screen — `NovaRenderProvider` + `RenderTree` over a `RenderApi` —
315
+ renders with no store at all; that is how moss draws a page server-side and
316
+ how its React target adopts it. `shellView(shell)` reads a local shell as
317
+ that same `RenderApi`, which is how the DOM adapter draws one
318
+ (`mountShell`, and `renderToString` from `/adapters/dom/server`).
319
+ - **React Server Components:** not tested. The hooks are client-only.
320
+
321
+ ---
322
+
323
+ ## Reflection and devtools
324
+
325
+ - **`@niscorp/nova/reflect`** — read-only introspection over definitions
326
+ and live shells; pure and framework-free. `walkNodes` / `componentsOf` /
327
+ `refsOf` / `loopVarsOf` (layout walks), `snapshotShell` /
328
+ `describeInstance` (running state), `actionGraph` (emit/message wiring),
329
+ `classifyAudit` / `auditCatalog` (closure-audit triage), `livenessOf` (what
330
+ an action can still do once drawn: gestures, the channels it waits on, every
331
+ endpoint and whether it is called on open or later).
332
+ - **`@niscorp/nova/devtools`** — a shell inspector built as pure nova:
333
+ `devtoolsActions` (`devtools.dock`, `devtools.inspect` — plain
334
+ ActionDefinitions over generic primitives), `DEVTOOLS_CANVAS`, and
335
+ `createDevtoolsFunctions` serving the `devtools.*` fns (the endpoint
336
+ timeline is a ring buffer fed by `shell.onEndpoint`). An app opts in by
337
+ granting `devtools.*` to a dev role, adding the canvas plus a frame
338
+ slot, and spreading the fns into its `functions(session)`.
339
+
340
+ ---
341
+
342
+ ## The grammar and its versions
343
+
344
+ nova's documents — actions, fragments, layouts — are a grammar with a version,
345
+ published at **`@niscorp/nova/migrations`** for [strata](../strata/README.md):
346
+
347
+ - **`NOVA_SEQUENCE`** — the grammar sequence `nisc.nova`: its kinds
348
+ (`nisc.nova/action`, `/fragment`, `/layout`), where documents nest inside
349
+ them (a layout's `children`, `children[]`, `then`, `else`, `do`; an action's
350
+ `layout` and its endpoints' `request`/`response`, which are Prism configs),
351
+ and its migrations. Stored and submitted documents carry the stamp they were
352
+ written at and are upgraded where they are read (moss does this for
353
+ integration actions).
354
+ - **`NOVA_SCHEMAS`** — the Zod schema behind each kind, snapshotted by the
355
+ repo's grammar gate (`pnpm check:grammars`).
356
+
357
+ **Changing a schema here is a migration** (AGENTS.md rule 18): an empty marker
358
+ appended to `NOVA_SEQUENCE` for an addition, document steps — a Prism config
359
+ over one node — for anything else. The gate refuses the change until it has
360
+ one, and checks every captured lab-app document still upgrades and parses.
361
+
362
+ ---
363
+
364
+ ## Building / dev
365
+
366
+ ```bash
367
+ pnpm build # tsup ESM + CJS + DTS
368
+ pnpm test # vitest run
369
+ pnpm typecheck # tsc --noEmit
370
+ ```
371
+
372
+ The `tsconfig.json` carries an `ignoreDeprecations` workaround for
373
+ `tsup`'s DTS bundler injecting `baseUrl`. This is intentional and
374
+ expected.
375
+
376
+ ---
377
+
378
+ ## Future work
379
+