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