@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/SHELL_DOCS.md ADDED
@@ -0,0 +1,615 @@
1
+ # Shell — Author Guide
2
+
3
+ How to wire nova together. The shell is the top-level orchestrator: it owns canvases, mounts and unmounts action instances, drives navigation, routes events and messages, and exposes the runtime tree to consumers.
4
+
5
+ If layouts are the "what" and actions are the "behavior," the shell is the "where and when." This guide is for **using** the shell. For the architecture see `DESIGN.md`.
6
+
7
+ ---
8
+
9
+ ## A first shell
10
+
11
+ ```ts
12
+ import { createShell, createComponentRegistry, createLayoutStore } from '@niscorp/nova';
13
+ import { registerNovaReactComponents } from '@niscorp/nova/adapters/react/components';
14
+ import { menuAction, settingsAction, profileAction } from './actions';
15
+
16
+ const registry = createComponentRegistry();
17
+ registerNovaReactComponents(registry);
18
+ const layoutStore = createLayoutStore();
19
+
20
+ const shell = createShell({
21
+ canvases: [{ id: 'main' }],
22
+ registry,
23
+ layoutStore,
24
+ actions: {
25
+ menu: menuAction,
26
+ settings: settingsAction,
27
+ profile: profileAction,
28
+ },
29
+ onError: (err) => console.error(err),
30
+ });
31
+
32
+ shell.push('main', 'menu');
33
+ ```
34
+
35
+ `shell.push` mounts an action instance on a canvas. The shell drives the lifecycle from there. To render the result via React, see `REACT_DOCS.md`.
36
+
37
+ ---
38
+
39
+ ## What's in `ShellConfig`
40
+
41
+ ```ts
42
+ type ShellConfig = {
43
+ // Required
44
+ canvases: CanvasConfig[]; // the canvases the shell hosts (see below)
45
+ actions: Record<string, ActionDefinition>; // every action the shell knows about
46
+
47
+ // Layout of the shell itself
48
+ canvasLayout?: LayoutNode | string; // how the shell arranges its canvases; when omitted,
49
+ // canvases render in a single flex row in declaration order
50
+
51
+ // Registry / layouts (both built fresh when omitted)
52
+ registry?: ComponentRegistry; // shared component registry for all actions
53
+ components?: Record<string, RegistrationInput>; // convenience: registerAll'd onto the registry
54
+ layoutStore?: LayoutStore; // shared layout store for all actions
55
+
56
+ // Fragments
57
+ fragments?: Record<string, ActionFragment>; // partial actions composed via a push/replace `with: [...]`
58
+
59
+ // Optional integrations
60
+ fetch?: FetchFn; // fetch implementation for endpoint calls
61
+ transform?: TransformFn; // evaluator for endpoint `request`/`response` configs (Prism etc.)
62
+ functions?: Record<string, FunctionHandler>; // handlers for `{ fn: '<name>' }` endpoints
63
+
64
+ // Telemetry / observability
65
+ telemetry?: ShellTelemetry; // onStateChange, onDataChange, onEndpoint callbacks
66
+ onError?: (error: NovaError) => void; // single error handler for the whole shell
67
+
68
+ // Strictness
69
+ strict?: boolean; // throw vs route through onError (default false)
70
+
71
+ // Navigation history
72
+ historyDepth?: number; // how many navigations `back` can walk (default 50; 0 = off)
73
+
74
+ // Test injection / advanced
75
+ shellIdFn?: IdFactory;
76
+ instanceIdFn?: IdFactory;
77
+ eventBus?: EventBus;
78
+ messageBus?: MessageBus;
79
+ };
80
+ ```
81
+
82
+ ### `canvases`
83
+
84
+ The canvases the shell hosts. A canvas is a stack of action instances; the topmost is the active one. Each entry is a `CanvasConfig`:
85
+
86
+ ```ts
87
+ type CanvasConfig = {
88
+ id: string; // arbitrary name, by purpose
89
+ actionLayout?: LayoutNode | string; // how this canvas arranges its instances; when omitted,
90
+ // only the top-of-stack (card-deck) action renders.
91
+ // Scope available to resolvables: { instances, active, count }
92
+ initial?: CanvasInitialSeed | CanvasInitialSeed[]; // pre-populate the stack on shell creation
93
+ };
94
+
95
+ // A seed is an action id, or an object with input and fragment composition —
96
+ // equivalent to calling shell.push(canvasId, ...) after createShell returns.
97
+ type CanvasInitialSeed = string | { action: string; input?: Record<string, unknown>; with?: string[] };
98
+ ```
99
+
100
+ ```ts
101
+ canvases: [{ id: 'main' }] // single-pane app
102
+ canvases: [{ id: 'nav' }, { id: 'content' }] // sidebar + main pane
103
+ canvases: [{ id: 'main', initial: 'home' }, { id: 'modal' }] // app + overlay, home pre-pushed
104
+ ```
105
+
106
+ The shell tracks each canvas independently — pushing on `main` doesn't affect `modal`.
107
+
108
+ ### `actions`
109
+
110
+ Every action the shell can mount, keyed by id. Actions are validated at shell init via `ActionDefinitionSchema`. Any malformed definition throws `DefinitionValidationError` with a list of Zod issues.
111
+
112
+ Actions can `{push: {action: 'someId'}}` other actions — but only ones that exist in this map. Trying to push an unknown action throws `UnknownActionError`.
113
+
114
+ ### `registry` and `layoutStore`
115
+
116
+ These are **shared** across every action in the shell. All actions read components from the same registry and layout refs from the same store. Both are optional — createShell builds fresh empty ones when omitted, and exposes whichever ended up in use as `shell.registry` / `shell.layoutStore`. A `components` map, if provided, is `registerAll`'d onto the registry either way.
117
+
118
+ ### `fragments`
119
+
120
+ Reusable partial actions (`ActionFragment`s), keyed by id, referenceable from a push/replace effect's `with: [...]`. More can be added at runtime via `shell.registerFragment`.
121
+
122
+ ### `fetch`, `transform`, and `functions`
123
+
124
+ These are dependency injection points. HTTP endpoint calls use `fetch`. Endpoint `request`/`response` configs run through `transform` — an opaque `(config, source) => unknown` evaluator nova never interprets (the host typically wires Prism's `evaluate`); declaring a `request`/`response` without one is a hard error. `{ fn: '<name>' }` endpoints resolve their handler from `functions`. Default `fetch` is the global `fetch` if available; there is no default `transform` or `functions`.
125
+
126
+ ### `telemetry`
127
+
128
+ ```ts
129
+ telemetry: {
130
+ onStateChange: (snapshot) => { /* whole-shell snapshot */ },
131
+ onDataChange: (event) => { /* per-instance data update */ },
132
+ onEndpoint: (event) => { /* per-endpoint-call outcome */ },
133
+ }
134
+ ```
135
+
136
+ The first two fire whenever the shell's state changes. The React adapter uses these via `useSyncExternalStore` to drive re-renders. You can also use them directly to log, persist, or sync state externally.
137
+
138
+ `onEndpoint` fires once per completed endpoint call — `fn:` and HTTP alike — with an `EndpointEvent`: `{ name, kind: 'fn' | 'http', ok, status, ms, instanceId, canvasId }` (`status` is 0 for fn calls; aborted calls are not reported). This is the observability seam devtools' timeline reads.
139
+
140
+ ### `strict`
141
+
142
+ When `true`, errors throw all the way up through the shell's public methods. Lifecycle errors surface on the next shell call (because they're inherently async). Use strict mode in tests and dev. Use lax mode (`false`, the default) in production where you want graceful degradation via `onError`.
143
+
144
+ ### `onError`
145
+
146
+ A single function that receives every `NovaError` produced anywhere in the shell. Use it for logging, telemetry, or showing an error UI. It fires for render errors, endpoint failures, lifecycle failures, navigation failures.
147
+
148
+ ---
149
+
150
+ ## The `Shell` interface
151
+
152
+ `createShell(config)` returns a `Shell`:
153
+
154
+ ```ts
155
+ type Shell = {
156
+ readonly id: string;
157
+ readonly registry: ComponentRegistry; // what the shell was created with (or built)
158
+ readonly layoutStore: LayoutStore;
159
+
160
+ // Canvas operations
161
+ push: (canvasId: string, actionId: string, input?: object, fragments?: string[]) => string;
162
+ pop: (canvasId: string) => void;
163
+ popTo: (canvasId: string, instanceId: string) => void;
164
+ replace: (canvasId: string, actionId: string, input?: object, fragments?: string[]) => string;
165
+ clear: (canvasId: string) => void;
166
+ back: () => boolean; // undo the last navigation, anywhere on the shell
167
+
168
+ // Runtime registration
169
+ registerAction: (definition: ActionDefinition) => void;
170
+ removeAction: (actionId: string) => void; // revocation: unmounts live instances
171
+ registerFragment: (fragment: ActionFragment) => void;
172
+
173
+ // Canvas set / layout mutation
174
+ addCanvas: (config: CanvasConfig) => void;
175
+ removeCanvas: (canvasId: string) => void;
176
+ setCanvasLayout: (layout: LayoutNode | string) => void;
177
+ setLayout: (refId: string, layout: LayoutNode) => void; // hot-swap a LayoutRef target
178
+
179
+ // State queries
180
+ getCanvasState: (canvasId: string) => CanvasState;
181
+ getRuntime: (instanceId: string) => PublicActionRuntime | undefined;
182
+ getState: () => StateSnapshot;
183
+
184
+ // Render-tree access (canvas/shell layouts)
185
+ getShellRenderTree: () => RenderNode[];
186
+ getCanvasRenderTree: (canvasId: string) => RenderNode[];
187
+ flattenRenderTree: (tree: RenderNode[]) => RenderNode[];
188
+
189
+ // Event/message dispatch
190
+ dispatch: (event: NovaEvent) => void;
191
+ publish: (channel: string, payload?: unknown) => void;
192
+
193
+ // Telemetry subscriptions
194
+ onStateChange: (handler) => Unsubscribe;
195
+ onDataChange: (handler) => Unsubscribe;
196
+ onEndpoint: (handler) => Unsubscribe;
197
+ onCanvasChange: (canvasId, handler) => Unsubscribe;
198
+
199
+ // Lifecycle
200
+ dispose: () => void;
201
+ };
202
+ ```
203
+
204
+ ### Canvas operations
205
+
206
+ #### `push(canvasId, actionId, input?, fragments?)`
207
+
208
+ Mount a fresh instance of an action on top of a canvas. Suspends the previous top (its `suspend` lifecycle hook fires). Returns the new instance id.
209
+
210
+ ```ts
211
+ const instanceId = shell.push('main', 'editor', { fileId: 'f_42' });
212
+ shell.push('overlay', 'confirm', { id: 'u_42' }, ['modal-frame']); // composed with a fragment
213
+ ```
214
+
215
+ The optional `input` is merged into the action's `data` before mount. The optional `fragments` names `ActionFragment`s to compose the action with before instantiation — same as a push effect's `with: [...]`.
216
+
217
+ #### `pop(canvasId)`
218
+
219
+ Unmount the top of a canvas. The unmounted action's `unmount` lifecycle hook fires. The new top (if any) resumes — its `mount` hook re-runs to refresh its data, then its `resume` hook fires.
220
+
221
+ ```ts
222
+ shell.pop('main');
223
+ ```
224
+
225
+ If the canvas is empty, this is a no-op.
226
+
227
+ #### `popTo(canvasId, instanceId)`
228
+
229
+ Pop a canvas down to a given instance — everything above it unmounts, in stack order. A no-op if the instance isn't in the stack. This is what stack-nav chrome (a breadcrumb, a tab) uses to jump straight to an ancestor.
230
+
231
+ ```ts
232
+ shell.popTo('main', instanceId);
233
+ ```
234
+
235
+ #### `replace(canvasId, actionId, input?, fragments?)`
236
+
237
+ Replace the top of a canvas with a new action instance. The replaced action unmounts; the new one mounts. The action below stays unaffected.
238
+
239
+ ```ts
240
+ shell.replace('main', 'next-step', { progress: 0.5 });
241
+ ```
242
+
243
+ Useful for wizards where back-navigation isn't wanted.
244
+
245
+ #### `clear(canvasId)`
246
+
247
+ Unmount every action on a canvas. Each unmount runs `unmount` lifecycle hooks in stack order.
248
+
249
+ ```ts
250
+ shell.clear('main');
251
+ ```
252
+
253
+ #### `back()`
254
+
255
+ Undo the shell's last navigation. Returns `false` when there was nothing left to
256
+ undo — the answer a landing screen gives.
257
+
258
+ ```ts
259
+ shell.back();
260
+ ```
261
+
262
+ The shell keeps a **navigation journal**: before every `push`, `replace`,
263
+ `clear` and `resetTo`, it writes down the canvas that is about to change. One
264
+ entry is one position somebody can be returned to; `back` restores the newest.
265
+
266
+ - **Global and ordered.** One journal across every canvas, each entry naming the
267
+ one canvas it describes — so back walks a person's own moves in the order they
268
+ made them, and never reverts a canvas that changed underneath them (a
269
+ delivered notice, an agent's card) while they were somewhere else.
270
+ - **What survives.** An instance the recorded position still names is kept, with
271
+ everything it holds. One that is gone comes back derived from the action and
272
+ input that made it: back re-opens a screen, it does not resurrect the form
273
+ somebody replaced their way out of.
274
+ - **A pop is a back.** `pop`, `popTo` and `removeInstance` spend a journal entry
275
+ instead of adding one — otherwise a person who used the app's own back button
276
+ would have to press the browser's twice.
277
+ - **The floor.** Canvas seeds (`initial`, and any `push` passing `{ history:
278
+ false }`) are never recorded, so `back` cannot empty the screen somebody landed
279
+ on. A revoked action takes its entries with it: `removeAction` purges anything
280
+ that would hand it back, and `removeCanvas` drops what can no longer be
281
+ restored.
282
+ - **Depth.** `ShellConfig.historyDepth` (default 50) bounds the journal;
283
+ `historyDepth: 0` switches it off and makes `back` a no-op.
284
+
285
+ Nothing about the gesture lives here — a browser's back button, a TUI's Escape
286
+ key and an app's own control all arrive as this one call. In moss it is
287
+ protocol-level: see its `back` client message.
288
+
289
+ ### Runtime registration and canvas mutation
290
+
291
+ The shell starts from `createShell`'s `actions` / `fragments` / `canvases` / `canvasLayout` and can change all four live:
292
+
293
+ ```ts
294
+ shell.registerAction(definition); // add (or replace) an action definition
295
+ shell.removeAction(actionId); // revocation: unmounts live instances, drops the definition
296
+ shell.registerFragment(fragment); // add a fragment for `with: [...]`
297
+ shell.addCanvas({ id: 'aside', initial: 'inspector' }); // appends + seeds; no-op if the id exists
298
+ shell.removeCanvas('aside'); // unmounts its instances, then drops it
299
+ shell.setCanvasLayout(layout); // swap how the shell arranges its canvases
300
+ shell.setLayout('region-a', layout); // swap what a LayoutRef placeholder resolves to
301
+ ```
302
+
303
+ `setLayout` is the hot-swap hook for dynamic region layouts: a canvasLayout embeds `{ ref: id }` placeholders, and this replaces what one resolves to — the frame/chrome stays intact.
304
+
305
+ ### Render-tree access
306
+
307
+ For non-React consumers (evaluators, exporters, tests):
308
+
309
+ ```ts
310
+ shell.getShellRenderTree(); // the canvasLayout rendered against { canvases }
311
+ shell.getCanvasRenderTree('main'); // a canvas's actionLayout rendered against { instances, active, count }
312
+ shell.flattenRenderTree(tree); // materialise a tree: CanvasSlot resolves away, ActionSlot survives
313
+ ```
314
+
315
+ `flattenRenderTree` resolves `CanvasSlot` markers into their canvas trees, but the `ActionSlot` marker survives: a component node with `props: { instanceId, canvasId, definitionId }`, `key: instanceId`, and the instance's rendered tree as children. Served (remote) trees keep instance identity this way — a renderer keys by instance so a swap remounts, and a terminal-side slot wrapper has its seam.
316
+
317
+ React consumers render trees through component boundaries instead — see `REACT_DOCS.md`.
318
+
319
+ ### State queries
320
+
321
+ #### `getCanvasState(canvasId)`
322
+
323
+ Returns the current state of one canvas.
324
+
325
+ ```ts
326
+ const state = shell.getCanvasState('main');
327
+ // {
328
+ // id: 'main',
329
+ // stack: [ActionInstance, ActionInstance, ...],
330
+ // active: ActionInstance | undefined,
331
+ // }
332
+ ```
333
+
334
+ The `stack` is in mount order (oldest first). `active` is the topmost (or `undefined` if empty).
335
+
336
+ #### `getState()`
337
+
338
+ Returns a snapshot of every canvas at once.
339
+
340
+ ```ts
341
+ const snapshot = shell.getState();
342
+ // { canvases: { main: CanvasState, modal: CanvasState, ... } }
343
+ ```
344
+
345
+ This is what `useSyncExternalStore` calls under the hood for the React adapter.
346
+
347
+ #### `getRuntime(instanceId)`
348
+
349
+ Returns the runtime for a specific action instance, or `undefined` if it's been unmounted. The returned `PublicActionRuntime` is narrow — it doesn't expose internal lifecycle methods.
350
+
351
+ ```ts
352
+ const runtime = shell.getRuntime('act-7');
353
+ runtime?.getData(); // current data snapshot
354
+ runtime?.render(); // current RenderNode tree
355
+ runtime?.onDataChange(handler);
356
+ runtime?.setData({...}); // tooling escape hatch
357
+ ```
358
+
359
+ See `ACTION_DOCS.md` for the runtime methods.
360
+
361
+ ### Event and message dispatch
362
+
363
+ #### `dispatch(event)`
364
+
365
+ Send a UI event into the shell. Triggers with a matching `event:` (and optional `ref:`) fire.
366
+
367
+ ```ts
368
+ shell.dispatch({ type: 'ui:click', ref: 'save' });
369
+ shell.dispatch({ type: 'ui:input', ref: 'name', value: 'Ada' });
370
+ shell.dispatch({ type: 'ui:model', ref: 'name', payload: 'Ada' });
371
+ ```
372
+
373
+ This is how the React adapter's components push events into the shell when buttons get clicked, inputs change, etc. You normally don't call it directly from app code — components do.
374
+
375
+ #### `publish(channel, payload?)`
376
+
377
+ Send a message on a channel. Triggers with a matching `message:` fire — across all actions on all canvases.
378
+
379
+ ```ts
380
+ shell.publish('cart-updated', { itemCount: 3 });
381
+ shell.publish('user-logged-out');
382
+ ```
383
+
384
+ Use it to coordinate between actions that don't otherwise know about each other.
385
+
386
+ ### Telemetry subscriptions
387
+
388
+ #### `onStateChange(handler)` / `onDataChange(handler)`
389
+
390
+ Imperative subscription form (alongside the declarative `telemetry` config option). Returns an `Unsubscribe`.
391
+
392
+ ```ts
393
+ const off = shell.onDataChange((event) => {
394
+ console.log(`${event.instanceId} data:`, event.data);
395
+ });
396
+ // later:
397
+ off();
398
+ ```
399
+
400
+ The React adapter uses these internally; app code can use them to drive logging, persistence, devtools, etc.
401
+
402
+ #### `onEndpoint(handler)`
403
+
404
+ Fires once per completed endpoint call any action makes — `fn:` and HTTP alike — with `{ name, kind, ok, status, ms, instanceId, canvasId }` (`status` 0 for fn; aborted calls not reported). Returns an `Unsubscribe`. Devtools' endpoint timeline is built on this.
405
+
406
+ #### `onCanvasChange(canvasId, handler)`
407
+
408
+ Subscribes to one canvas. Fires with the new `CanvasState` only when the canvas meaningfully changed — stack length, item ids/statuses, or the active instance. The shell owns this equality check, so subscribers (adapters included) never encode what "changed" means.
409
+
410
+ ```ts
411
+ const off = shell.onCanvasChange('main', (state) => {
412
+ console.log('main active:', state.active?.id);
413
+ });
414
+ ```
415
+
416
+ ### `dispose()`
417
+
418
+ Tear down the entire shell. Unmounts every action on every canvas. Detaches all listeners. After `dispose()`, every shell method becomes a no-op or throws `ShellDisposedError`.
419
+
420
+ ```ts
421
+ useEffect(() => {
422
+ const shell = createShell({ ... });
423
+ return () => shell.dispose();
424
+ }, []);
425
+ ```
426
+
427
+ Always dispose shells you create — they hold references to runtimes which hold references to event listeners.
428
+
429
+ ### `shellView(shell)` and `shellSettled(shell)`
430
+
431
+ Two helpers beside the shell, for anything that draws one.
432
+
433
+ ```ts
434
+ import { shellView, shellSettled } from '@niscorp/nova';
435
+
436
+ const { api, subscribe } = shellView(shell); // the shell, as a RenderApi
437
+ api.frame(); // the shell layout's tree
438
+ api.canvasTree('main'); // one canvas — [] when nothing visible is mounted
439
+ api.dispatch('main', { type: 'ui:click', ref: 'save' }); // to the canvas's active instance
440
+ const stop = subscribe(() => redraw()); // once per burst of changes
441
+
442
+ const whole = await shellSettled(shell, { waitMs: 300 }); // true: nothing is still mounting
443
+ ```
444
+
445
+ `shellView` is what lets an adapter written against `RenderApi` (the DOM and TTY adapters, a moss terminal) draw a shell that lives beside it. `shellSettled` resolves `true` once no instance is `initializing` — every mount hook, and what it chained to, has been awaited — and `false` if `waitMs` (default 300) runs out first. It is the moment to draw a shell to markup, and the moment for the page's own shell to adopt it.
446
+
447
+ ---
448
+
449
+ ## Multi-canvas patterns
450
+
451
+ ### Sidebar + content
452
+
453
+ ```ts
454
+ canvases: [{ id: 'nav', initial: 'navigator' }, { id: 'content', initial: 'welcome' }]
455
+
456
+ // Inside the navigator action:
457
+ triggers: [
458
+ { event: 'ui:click', ref: 'home', do: [{ replace: { action: 'home', canvas: 'content' } }] },
459
+ { event: 'ui:click', ref: 'settings', do: [{ replace: { action: 'settings', canvas: 'content' } }] },
460
+ ],
461
+ ```
462
+
463
+ Clicking nav buttons swaps the content canvas without affecting the nav canvas. Each is its own independent stack.
464
+
465
+ ### Modal overlays
466
+
467
+ ```ts
468
+ canvases: [{ id: 'main', initial: 'home' }, { id: 'modal' }]
469
+
470
+ // From the home action:
471
+ { push: { action: 'confirm-delete', canvas: 'modal' } }
472
+ // Optionally composed with reusable modal chrome:
473
+ { push: { action: 'confirm-delete', canvas: 'modal', with: ['modal-frame'] } }
474
+
475
+ // From inside the confirm-delete action:
476
+ { pop: true } // pops on the action's current canvas, which is 'modal'
477
+ ```
478
+
479
+ The modal canvas is its own stack. The main canvas is unaffected.
480
+
481
+ ### Cross-canvas messaging
482
+
483
+ Actions on different canvases can talk via the message bus:
484
+
485
+ ```ts
486
+ // Producer canvas — emits when something happens
487
+ { emit: { channel: 'item-added' } }
488
+
489
+ // Consumer canvas — has a trigger listening for it
490
+ triggers: [
491
+ { message: 'item-added', do: [{ increment: 'count' }] },
492
+ ]
493
+ ```
494
+
495
+ The shell's message bus is shared across all canvases. Cross-canvas communication is just publish/subscribe.
496
+
497
+ ---
498
+
499
+ ## State machine
500
+
501
+ Each action instance lives in one of four states:
502
+
503
+ ```
504
+ push
505
+ [ initializing ] ────► [ active ]
506
+ │ ▲
507
+ push other │ │ pop other
508
+ ▼ │
509
+ [ suspended ]
510
+ │
511
+ │ pop / clear
512
+ ▼
513
+ [ unmounted ]
514
+ ```
515
+
516
+ - **`initializing`** — between `push()` and the moment the mount lifecycle hook completes.
517
+ - **`active`** — the topmost instance on a canvas. Triggers attached, render reflects current data.
518
+ - **`suspended`** — another action is on top. Triggers stay attached but do not fire (a suspended action reacts to nothing), and the runtime's abort signal prevents in-flight async work from completing during this state.
519
+ - **`unmounted`** — terminal. The runtime is disposed; `getRuntime` returns `undefined`.
520
+
521
+ Lifecycle hooks fire on each transition: `mount` (init→active), `suspend` (active→suspended), `mount` again then `resume` (suspended→active — the re-run of `mount` refreshes the data a backgrounded action ignored), `unmount` (any→unmounted).
522
+
523
+ ---
524
+
525
+ ## ID generation
526
+
527
+ Every shell has a unique id and assigns ids to action instances. By default both use `crypto.randomUUID()` if available, falling back to a Math.random-based scheme. For deterministic tests, inject your own:
528
+
529
+ ```ts
530
+ import { createIdFactory } from '@niscorp/nova';
531
+
532
+ const myInstanceIds = createIdFactory('act');
533
+ // or write a closure-based counter for full determinism
534
+
535
+ createShell({
536
+ ...
537
+ shellIdFn: () => 'test-shell',
538
+ instanceIdFn: myInstanceIds,
539
+ });
540
+ ```
541
+
542
+ ---
543
+
544
+ ## Errors
545
+
546
+ The shell can produce these:
547
+
548
+ - **`UnknownActionError`** — `shell.push(canvas, 'foo')` where `'foo'` isn't in `actions`
549
+ - **`ShellDisposedError`** — any operation after `dispose()`
550
+ - **`DefinitionValidationError`** — at shell construction, if any action in `actions` fails schema validation
551
+ - **`LifecycleError`** — a lifecycle hook step threw (in strict mode propagates, in lax mode routes via `onError`)
552
+
553
+ Plus all action-level errors (from `ACTION_DOCS.md`) and layout-level errors (from `LAYOUT_DOCS.md`) bubble up through the shell's error pipeline.
554
+
555
+ ---
556
+
557
+ ## Quick reference
558
+
559
+ ```ts
560
+ const shell = createShell({
561
+ canvases: CanvasConfig[], // { id, actionLayout?, initial? }
562
+ actions: Record<string, ActionDefinition>,
563
+ canvasLayout?: LayoutNode | string,
564
+ registry?: ComponentRegistry, // built fresh when omitted
565
+ components?: Record<string, RegistrationInput>,
566
+ layoutStore?: LayoutStore, // built fresh when omitted
567
+ fragments?: Record<string, ActionFragment>,
568
+ fetch?: FetchFn,
569
+ transform?: TransformFn,
570
+ functions?: Record<string, FunctionHandler>,
571
+ telemetry?: { onStateChange?, onDataChange?, onEndpoint? },
572
+ strict?: boolean,
573
+ onError?: (error) => void,
574
+ });
575
+
576
+ // Canvas ops
577
+ shell.push(canvasId, actionId, input?, fragments?); // → instanceId
578
+ shell.pop(canvasId);
579
+ shell.popTo(canvasId, instanceId);
580
+ shell.replace(canvasId, actionId, input?, fragments?); // → instanceId
581
+ shell.clear(canvasId);
582
+
583
+ // Runtime registration / canvas mutation
584
+ shell.registerAction(definition);
585
+ shell.removeAction(actionId);
586
+ shell.registerFragment(fragment);
587
+ shell.addCanvas(config);
588
+ shell.removeCanvas(canvasId);
589
+ shell.setCanvasLayout(layout);
590
+ shell.setLayout(refId, layout);
591
+
592
+ // State
593
+ shell.getCanvasState(canvasId); // → CanvasState
594
+ shell.getRuntime(instanceId); // → PublicActionRuntime | undefined
595
+ shell.getState(); // → StateSnapshot
596
+
597
+ // Render trees (non-React consumers)
598
+ shell.getShellRenderTree(); // → RenderNode[]
599
+ shell.getCanvasRenderTree(canvasId); // → RenderNode[]
600
+ shell.flattenRenderTree(tree); // → RenderNode[]
601
+
602
+ // Events / messages
603
+ shell.dispatch({ type, ref?, ... });
604
+ shell.publish(channel, payload?);
605
+
606
+ // Telemetry
607
+ shell.onStateChange(handler); // → Unsubscribe
608
+ shell.onDataChange(handler); // → Unsubscribe
609
+ shell.onEndpoint(handler); // → Unsubscribe
610
+
611
+ // Teardown
612
+ shell.dispose();
613
+ ```
614
+
615
+ For wiring a shell into a React app, see `REACT_DOCS.md`. For authoring the actions a shell hosts, see `ACTION_DOCS.md`.