@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/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.
|