@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.
- package/ACTION_DOCS.md +552 -0
- package/ADAPTER.md +170 -0
- package/DESIGN.md +719 -0
- package/I18N_DOCS.md +224 -0
- package/LAYOUT_DOCS.md +505 -0
- package/LICENSE +202 -0
- package/REACT_DOCS.md +562 -0
- package/README.md +379 -0
- package/SHELL_DOCS.md +615 -0
- package/TERMINAL_DOCS.md +124 -0
- package/dist/adapters/dom/components/index.cjs +473 -0
- package/dist/adapters/dom/components/index.cjs.map +1 -0
- package/dist/adapters/dom/components/index.d.cts +48 -0
- package/dist/adapters/dom/components/index.d.ts +48 -0
- package/dist/adapters/dom/components/index.js +420 -0
- package/dist/adapters/dom/components/index.js.map +1 -0
- package/dist/adapters/dom/index.cjs +171 -0
- package/dist/adapters/dom/index.cjs.map +1 -0
- package/dist/adapters/dom/index.d.cts +29 -0
- package/dist/adapters/dom/index.d.ts +29 -0
- package/dist/adapters/dom/index.js +15 -0
- package/dist/adapters/dom/index.js.map +1 -0
- package/dist/adapters/dom/server.cjs +129 -0
- package/dist/adapters/dom/server.cjs.map +1 -0
- package/dist/adapters/dom/server.d.cts +15 -0
- package/dist/adapters/dom/server.d.ts +15 -0
- package/dist/adapters/dom/server.js +37 -0
- package/dist/adapters/dom/server.js.map +1 -0
- package/dist/adapters/ink/index.d.ts +75 -0
- package/dist/adapters/ink/index.js +472 -0
- package/dist/adapters/ink/index.js.map +1 -0
- package/dist/adapters/react/components/index.cjs +552 -0
- package/dist/adapters/react/components/index.cjs.map +1 -0
- package/dist/adapters/react/components/index.d.cts +30 -0
- package/dist/adapters/react/components/index.d.ts +30 -0
- package/dist/adapters/react/components/index.js +12 -0
- package/dist/adapters/react/components/index.js.map +1 -0
- package/dist/adapters/react/index.cjs +1526 -0
- package/dist/adapters/react/index.cjs.map +1 -0
- package/dist/adapters/react/index.d.cts +149 -0
- package/dist/adapters/react/index.d.ts +149 -0
- package/dist/adapters/react/index.js +12 -0
- package/dist/adapters/react/index.js.map +1 -0
- package/dist/adapters/tty/components/index.cjs +255 -0
- package/dist/adapters/tty/components/index.cjs.map +1 -0
- package/dist/adapters/tty/components/index.d.cts +40 -0
- package/dist/adapters/tty/components/index.d.ts +40 -0
- package/dist/adapters/tty/components/index.js +187 -0
- package/dist/adapters/tty/components/index.js.map +1 -0
- package/dist/adapters/tty/index.cjs +76 -0
- package/dist/adapters/tty/index.cjs.map +1 -0
- package/dist/adapters/tty/index.d.cts +47 -0
- package/dist/adapters/tty/index.d.ts +47 -0
- package/dist/adapters/tty/index.js +76 -0
- package/dist/adapters/tty/index.js.map +1 -0
- package/dist/adapters/vue/components/index.cjs +619 -0
- package/dist/adapters/vue/components/index.cjs.map +1 -0
- package/dist/adapters/vue/components/index.d.cts +224 -0
- package/dist/adapters/vue/components/index.d.ts +224 -0
- package/dist/adapters/vue/components/index.js +12 -0
- package/dist/adapters/vue/components/index.js.map +1 -0
- package/dist/adapters/vue/index.cjs +747 -0
- package/dist/adapters/vue/index.cjs.map +1 -0
- package/dist/adapters/vue/index.d.cts +98 -0
- package/dist/adapters/vue/index.d.ts +98 -0
- package/dist/adapters/vue/index.js +127 -0
- package/dist/adapters/vue/index.js.map +1 -0
- package/dist/agent/index.cjs +178 -0
- package/dist/agent/index.cjs.map +1 -0
- package/dist/agent/index.d.cts +28 -0
- package/dist/agent/index.d.ts +28 -0
- package/dist/agent/index.js +30 -0
- package/dist/agent/index.js.map +1 -0
- package/dist/chunk-2MNLEL45.js +47 -0
- package/dist/chunk-2MNLEL45.js.map +1 -0
- package/dist/chunk-3HGE3VWK.js +753 -0
- package/dist/chunk-3HGE3VWK.js.map +1 -0
- package/dist/chunk-4ZID7UX5.js +549 -0
- package/dist/chunk-4ZID7UX5.js.map +1 -0
- package/dist/chunk-7B3RDENH.js +1982 -0
- package/dist/chunk-7B3RDENH.js.map +1 -0
- package/dist/chunk-7S5BNPUS.js +54 -0
- package/dist/chunk-7S5BNPUS.js.map +1 -0
- package/dist/chunk-7TS3YVQR.js +114 -0
- package/dist/chunk-7TS3YVQR.js.map +1 -0
- package/dist/chunk-EG2RUXJN.js +266 -0
- package/dist/chunk-EG2RUXJN.js.map +1 -0
- package/dist/chunk-GVBBL36G.js +429 -0
- package/dist/chunk-GVBBL36G.js.map +1 -0
- package/dist/chunk-I5D2R5UA.js +753 -0
- package/dist/chunk-I5D2R5UA.js.map +1 -0
- package/dist/chunk-IGLCWXQ3.js +304 -0
- package/dist/chunk-IGLCWXQ3.js.map +1 -0
- package/dist/chunk-JI7ZRESP.js +64 -0
- package/dist/chunk-JI7ZRESP.js.map +1 -0
- package/dist/chunk-L5223LLX.js +31 -0
- package/dist/chunk-L5223LLX.js.map +1 -0
- package/dist/chunk-LA3BSEMX.js +1905 -0
- package/dist/chunk-LA3BSEMX.js.map +1 -0
- package/dist/chunk-OAMC6R6E.js +121 -0
- package/dist/chunk-OAMC6R6E.js.map +1 -0
- package/dist/chunk-OGD5CCMZ.js +62 -0
- package/dist/chunk-OGD5CCMZ.js.map +1 -0
- package/dist/chunk-PF4OJTYU.js +199 -0
- package/dist/chunk-PF4OJTYU.js.map +1 -0
- package/dist/chunk-PZ5AY32C.js +9 -0
- package/dist/chunk-PZ5AY32C.js.map +1 -0
- package/dist/chunk-RBU5PHN4.js +8 -0
- package/dist/chunk-RBU5PHN4.js.map +1 -0
- package/dist/chunk-RQB4PRPV.js +285 -0
- package/dist/chunk-RQB4PRPV.js.map +1 -0
- package/dist/chunk-V32EVEVM.js +464 -0
- package/dist/chunk-V32EVEVM.js.map +1 -0
- package/dist/chunk-ZITHBBF3.js +85 -0
- package/dist/chunk-ZITHBBF3.js.map +1 -0
- package/dist/devtools/index.cjs +1088 -0
- package/dist/devtools/index.cjs.map +1 -0
- package/dist/devtools/index.d.cts +33 -0
- package/dist/devtools/index.d.ts +33 -0
- package/dist/devtools/index.js +399 -0
- package/dist/devtools/index.js.map +1 -0
- package/dist/effects-CndX9K7D.d.cts +123 -0
- package/dist/effects-CndX9K7D.d.ts +123 -0
- package/dist/endpoints-CD-6Jl-H.d.ts +36 -0
- package/dist/endpoints-Dem-EdRx.d.cts +36 -0
- package/dist/i18n/index.cjs +299 -0
- package/dist/i18n/index.cjs.map +1 -0
- package/dist/i18n/index.d.cts +28 -0
- package/dist/i18n/index.d.ts +28 -0
- package/dist/i18n/index.js +180 -0
- package/dist/i18n/index.js.map +1 -0
- package/dist/index-CNfzSBe2.d.ts +93 -0
- package/dist/index-caZoXSwr.d.cts +93 -0
- package/dist/index.cjs +3723 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +144 -0
- package/dist/index.d.ts +144 -0
- package/dist/index.js +15 -0
- package/dist/index.js.map +1 -0
- package/dist/migrations/index.cjs +635 -0
- package/dist/migrations/index.cjs.map +1 -0
- package/dist/migrations/index.d.cts +97 -0
- package/dist/migrations/index.d.ts +97 -0
- package/dist/migrations/index.js +50 -0
- package/dist/migrations/index.js.map +1 -0
- package/dist/palette-CP0wd3bE.d.ts +15 -0
- package/dist/palette-lm0bU9i5.d.cts +15 -0
- package/dist/primitive-props-BH_EJWIe.d.cts +100 -0
- package/dist/primitive-props-BH_EJWIe.d.ts +100 -0
- package/dist/primitive-props-CGoJvmcH.d.cts +100 -0
- package/dist/primitive-props-CGoJvmcH.d.ts +100 -0
- package/dist/reflect/index.cjs +998 -0
- package/dist/reflect/index.cjs.map +1 -0
- package/dist/reflect/index.d.cts +125 -0
- package/dist/reflect/index.d.ts +125 -0
- package/dist/reflect/index.js +13 -0
- package/dist/reflect/index.js.map +1 -0
- package/dist/schemas-DPdeFlCT.d.cts +38 -0
- package/dist/schemas-DPdeFlCT.d.ts +38 -0
- package/dist/schemas-pMyyuXV7.d.cts +47 -0
- package/dist/schemas-pMyyuXV7.d.ts +47 -0
- package/dist/types-Boh9ckdG.d.ts +194 -0
- package/dist/types-Brc7v_pS.d.ts +198 -0
- package/dist/types-ByNSwtUV.d.cts +20 -0
- package/dist/types-DdltMfw7.d.ts +20 -0
- package/dist/types-De0KpxfI.d.cts +198 -0
- package/dist/types-DhHL0twe.d.ts +20 -0
- package/dist/types-Dv6JLmgo.d.cts +194 -0
- package/dist/types-Q80YtOQt.d.cts +20 -0
- 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
|
+
|