@niscorp/nova 0.1.1 → 0.1.2
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 +121 -30
- package/ADAPTER.md +167 -12
- package/CHANGELOG.md +12 -0
- package/DESIGN.md +45 -22
- package/I18N_DOCS.md +4 -4
- package/LAYOUT_DOCS.md +55 -14
- package/REACT_DOCS.md +52 -16
- package/README.md +54 -19
- package/SHELL_DOCS.md +136 -16
- package/TERMINAL_DOCS.md +13 -7
- package/dist/adapters/dom/components/index.d.cts +2 -2
- package/dist/adapters/dom/components/index.d.ts +2 -2
- package/dist/adapters/dom/index.cjs +351 -53
- package/dist/adapters/dom/index.cjs.map +1 -1
- package/dist/adapters/dom/index.d.cts +4 -2
- package/dist/adapters/dom/index.d.ts +4 -2
- package/dist/adapters/dom/index.js +2 -2
- package/dist/adapters/dom/server.cjs +356 -55
- package/dist/adapters/dom/server.cjs.map +1 -1
- package/dist/adapters/dom/server.d.cts +2 -2
- package/dist/adapters/dom/server.d.ts +2 -2
- package/dist/adapters/dom/server.js +7 -4
- package/dist/adapters/dom/server.js.map +1 -1
- package/dist/adapters/react/components/index.d.cts +2 -2
- package/dist/adapters/react/components/index.d.ts +2 -2
- package/dist/adapters/react/index.d.cts +4 -4
- package/dist/adapters/react/index.d.ts +4 -4
- package/dist/adapters/tty/components/index.d.cts +2 -2
- package/dist/adapters/tty/components/index.d.ts +2 -2
- package/dist/adapters/tty/index.d.cts +2 -2
- package/dist/adapters/tty/index.d.ts +2 -2
- package/dist/adapters/vue/components/index.d.cts +5 -5
- package/dist/adapters/vue/components/index.d.ts +5 -5
- package/dist/adapters/vue/index.d.cts +4 -4
- package/dist/adapters/vue/index.d.ts +4 -4
- package/dist/adapters/vue/index.js +1 -1
- package/dist/agent/index.d.cts +2 -2
- package/dist/agent/index.d.ts +2 -2
- package/dist/{chunk-7B3RDENH.js → chunk-6N4WRC5V.js} +9 -4
- package/dist/chunk-6N4WRC5V.js.map +1 -0
- package/dist/chunk-FQAJ24KA.js +408 -0
- package/dist/chunk-FQAJ24KA.js.map +1 -0
- package/dist/devtools/index.d.cts +2 -2
- package/dist/devtools/index.d.ts +2 -2
- package/dist/i18n/index.d.cts +2 -2
- package/dist/i18n/index.d.ts +2 -2
- package/dist/index.cjs +8 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +5 -5
- package/dist/index.d.ts +5 -5
- package/dist/index.js +2 -2
- package/dist/{palette-CP0wd3bE.d.ts → palette-Mx7XHYC6.d.ts} +1 -1
- package/dist/{palette-lm0bU9i5.d.cts → palette-wbJB_svk.d.cts} +1 -1
- package/dist/reflect/index.d.cts +2 -2
- package/dist/reflect/index.d.ts +2 -2
- package/dist/{types-DdltMfw7.d.ts → types-B-rjaUX0.d.ts} +1 -1
- package/dist/{types-Boh9ckdG.d.ts → types-BB9RXel5.d.ts} +1 -1
- package/dist/{types-De0KpxfI.d.cts → types-BLVRduoz.d.cts} +11 -1
- package/dist/{types-DhHL0twe.d.ts → types-B_nOtkyt.d.ts} +1 -1
- package/dist/{types-Brc7v_pS.d.ts → types-DE77Jl2W.d.ts} +11 -1
- package/dist/{types-Dv6JLmgo.d.cts → types-PDXOkvtK.d.cts} +1 -1
- package/dist/{types-Q80YtOQt.d.cts → types-mRKXqZPX.d.cts} +1 -1
- package/dist/{types-ByNSwtUV.d.cts → types-uk19d6KC.d.cts} +1 -1
- package/package.json +7 -7
- package/dist/chunk-7B3RDENH.js.map +0 -1
- package/dist/chunk-OAMC6R6E.js +0 -121
- package/dist/chunk-OAMC6R6E.js.map +0 -1
package/README.md
CHANGED
|
@@ -5,6 +5,17 @@ layouts and effects.
|
|
|
5
5
|
|
|
6
6
|
**Status:** `0.x.x` — pre-1.0, breaking changes expected.
|
|
7
7
|
|
|
8
|
+
## Install
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
pnpm add @niscorp/nova @niscorp/prism @niscorp/strata zod
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
`@niscorp/prism`, `@niscorp/strata` and `zod` are required peers. Everything
|
|
15
|
+
else is optional and installed per surface: `react` for `/adapters/react`
|
|
16
|
+
and `/adapters/ink`, `vue` for `/adapters/vue`, `ink` and `ink-text-input` for
|
|
17
|
+
`/adapters/ink`, `@niscorp/cortex` for `/agent`. Node `>=22.12`.
|
|
18
|
+
|
|
8
19
|
## One tree, five renderers
|
|
9
20
|
|
|
10
21
|
Nova core renders layouts to plain `RenderNode[]` — no framework, no DOM,
|
|
@@ -67,7 +78,9 @@ What makes it different from "just another UI library":
|
|
|
67
78
|
|
|
68
79
|
Explicitly out of scope right now:
|
|
69
80
|
|
|
70
|
-
- **No LLM features.** No prompt scaffolding, no plan generation.
|
|
81
|
+
- **No LLM features in the core.** No prompt scaffolding, no plan generation.
|
|
82
|
+
The one agent nova ships — the layout agent — is opt-in at `/agent` (see
|
|
83
|
+
below).
|
|
71
84
|
- **No JSON Schema generation / catalog.** Use `z.toJSONSchema()` on
|
|
72
85
|
the exported Zod schemas if you need JSON Schema externally.
|
|
73
86
|
- **No mandatory components.** The component registry is empty by
|
|
@@ -202,14 +215,16 @@ ships in a DB row and can be referenced rather than inlined.
|
|
|
202
215
|
|
|
203
216
|
The orchestrator. `createShell(config)` validates every action
|
|
204
217
|
definition at construction (boundary Zod validation) and returns a
|
|
205
|
-
`Shell` with `push`, `pop`, `popTo`, `replace`, `clear`,
|
|
206
|
-
`
|
|
207
|
-
`
|
|
208
|
-
`
|
|
209
|
-
`
|
|
210
|
-
`
|
|
211
|
-
|
|
212
|
-
|
|
218
|
+
`Shell` with `push`, `pop`, `popTo`, `removeInstance`, `replace`, `clear`,
|
|
219
|
+
`back`, `originOf`, `registerAction`, `removeAction`, `registerFragment`,
|
|
220
|
+
`addCanvas`, `removeCanvas`, `setCanvasLayout`, `setLayout`, `setPhrases`,
|
|
221
|
+
`getPhrases`, `getCanvasState`, `getRuntime`, `getState`,
|
|
222
|
+
`getShellRenderTree`, `getCanvasRenderTree`, `flattenRenderTree`,
|
|
223
|
+
`dispatch`, `publish`, `onStateChange`, `onDataChange`, `onEndpoint`,
|
|
224
|
+
`onCanvasChange`, `dispose`. Canvases are `CanvasConfig`s (`{ id, mode?,
|
|
225
|
+
actionLayout?, initial? }`) — a canvas can pre-seed its stack, declare how
|
|
226
|
+
its instances are arranged, and hold them as a `stack` (default: the top is
|
|
227
|
+
active, the rest suspended) or a `list` (every instance stays live). The shell maintains a stack per
|
|
213
228
|
canvas, drives lifecycle hooks via the runtime, composes any `with`
|
|
214
229
|
fragments into the action at push/replace time, and routes navigation
|
|
215
230
|
effects emitted from action steps back into shell calls.
|
|
@@ -254,8 +269,11 @@ NovaError
|
|
|
254
269
|
├── LayoutRefNotFoundError
|
|
255
270
|
├── DefinitionValidationError
|
|
256
271
|
├── UnknownActionError
|
|
272
|
+
├── UnknownFragmentError
|
|
273
|
+
├── UnknownFunctionError
|
|
257
274
|
├── ShellDisposedError
|
|
258
|
-
|
|
275
|
+
├── LifecycleError
|
|
276
|
+
└── MutationError
|
|
259
277
|
```
|
|
260
278
|
|
|
261
279
|
All carry a stable `code` (`ErrorCodes.*`), an optional `context`, and
|
|
@@ -291,7 +309,7 @@ can perform their own final async work (e.g. telemetry flush).
|
|
|
291
309
|
|
|
292
310
|
## React compatibility
|
|
293
311
|
|
|
294
|
-
- **React
|
|
312
|
+
- **React 19 required** (peer `react ^19.2.4`). The adapter uses `useSyncExternalStore`.
|
|
295
313
|
- **Concurrent rendering:** fully supported. `useSyncExternalStore` is
|
|
296
314
|
tearing-safe by design — the snapshot getters in `useRenderTree` and
|
|
297
315
|
`useCanvas` return referentially-stable values when the underlying data
|
|
@@ -315,7 +333,10 @@ can perform their own final async work (e.g. telemetry flush).
|
|
|
315
333
|
renders with no store at all; that is how moss draws a page server-side and
|
|
316
334
|
how its React target adopts it. `shellView(shell)` reads a local shell as
|
|
317
335
|
that same `RenderApi`, which is how the DOM adapter draws one
|
|
318
|
-
(`mountShell`, and `renderToString` from `/adapters/dom/server`).
|
|
336
|
+
(`mountShell`, and `renderToString` from `/adapters/dom/server`). The DOM
|
|
337
|
+
adapter replaces drawn markup on its first render and patches from then on:
|
|
338
|
+
what did not change keeps its element (ADAPTER.md, "The DOM adapter keeps
|
|
339
|
+
what did not change" — a DOM kit's contract is there).
|
|
319
340
|
- **React Server Components:** not tested. The hooks are client-only.
|
|
320
341
|
|
|
321
342
|
---
|
|
@@ -339,6 +360,24 @@ can perform their own final async work (e.g. telemetry flush).
|
|
|
339
360
|
|
|
340
361
|
---
|
|
341
362
|
|
|
363
|
+
## Agent and i18n
|
|
364
|
+
|
|
365
|
+
- **`@niscorp/nova/agent`** — the layout-authoring surface: `layoutAgent`
|
|
366
|
+
(a `@niscorp/cortex` agent definition — intent + component palette + data
|
|
367
|
+
example in, a `LayoutNode` out, validated against `LayoutNodeSchema`),
|
|
368
|
+
`paletteFromRegistry` (the palette, read off a component registry's
|
|
369
|
+
`meta`), and `collectInteractive` (a layout's refs, models and bound data
|
|
370
|
+
keys, derived by walking the tree). Needs the optional peer
|
|
371
|
+
`@niscorp/cortex`.
|
|
372
|
+
- **`@niscorp/nova/i18n`** — nova is language-blind: a host hands the shell a
|
|
373
|
+
phrasebook (`phrases` on `ShellConfig`, `shell.setPhrases` at runtime) and
|
|
374
|
+
nova swaps prose at render. The subpath holds the pieces around that:
|
|
375
|
+
`translateRenderTree`, `fillPhrase`, and the harvest (`harvestLayout`,
|
|
376
|
+
`harvestDefinition`, `harvestDefinitions`, `missingFrom`) that lists the
|
|
377
|
+
phrases a dictionary must cover. See [I18N_DOCS.md](I18N_DOCS.md).
|
|
378
|
+
|
|
379
|
+
---
|
|
380
|
+
|
|
342
381
|
## The grammar and its versions
|
|
343
382
|
|
|
344
383
|
nova's documents — actions, fragments, layouts — are a grammar with a version,
|
|
@@ -369,11 +408,7 @@ pnpm test # vitest run
|
|
|
369
408
|
pnpm typecheck # tsc --noEmit
|
|
370
409
|
```
|
|
371
410
|
|
|
372
|
-
The `tsconfig.json
|
|
373
|
-
`tsup`'s DTS bundler
|
|
374
|
-
expected.
|
|
375
|
-
|
|
376
|
-
---
|
|
377
|
-
|
|
378
|
-
## Future work
|
|
411
|
+
The repo's root `tsconfig.json`, which this package's `tsconfig.json`
|
|
412
|
+
extends, carries an `ignoreDeprecations` workaround for `tsup`'s DTS bundler
|
|
413
|
+
injecting `baseUrl`. This is intentional and expected.
|
|
379
414
|
|
package/SHELL_DOCS.md
CHANGED
|
@@ -60,6 +60,14 @@ type ShellConfig = {
|
|
|
60
60
|
fetch?: FetchFn; // fetch implementation for endpoint calls
|
|
61
61
|
transform?: TransformFn; // evaluator for endpoint `request`/`response` configs (Prism etc.)
|
|
62
62
|
functions?: Record<string, FunctionHandler>; // handlers for `{ fn: '<name>' }` endpoints
|
|
63
|
+
endpointTimeoutMs?: number; // how long an endpoint call waits for its reply before it
|
|
64
|
+
// fails to `onError` (default 30000); an endpoint's own
|
|
65
|
+
// `timeoutMs` wins
|
|
66
|
+
|
|
67
|
+
// Language (see I18N_DOCS.md)
|
|
68
|
+
phrases?: Phrasebook; // the book every tree this shell renders is translated through
|
|
69
|
+
phraseKeys?: PhraseKeys; // which prop keys carry prose
|
|
70
|
+
onPhraseMiss?: (phrase: string, where: string) => void; // a phrase with no entry in the book
|
|
63
71
|
|
|
64
72
|
// Telemetry / observability
|
|
65
73
|
telemetry?: ShellTelemetry; // onStateChange, onDataChange, onEndpoint callbacks
|
|
@@ -86,10 +94,14 @@ The canvases the shell hosts. A canvas is a stack of action instances; the topmo
|
|
|
86
94
|
```ts
|
|
87
95
|
type CanvasConfig = {
|
|
88
96
|
id: string; // arbitrary name, by purpose
|
|
97
|
+
mode?: 'stack' | 'list'; // 'stack' (default): only the top is active, the rest suspended.
|
|
98
|
+
// 'list': every instance stays live — author an `actionLayout`
|
|
99
|
+
// that loops `$.instances`
|
|
89
100
|
actionLayout?: LayoutNode | string; // how this canvas arranges its instances; when omitted,
|
|
90
101
|
// only the top-of-stack (card-deck) action renders.
|
|
91
102
|
// Scope available to resolvables: { instances, active, count }
|
|
92
|
-
initial?: CanvasInitialSeed | CanvasInitialSeed[]; // pre-populate the stack on shell creation
|
|
103
|
+
initial?: CanvasInitialSeed | CanvasInitialSeed[]; // pre-populate the stack on shell creation;
|
|
104
|
+
// a list is pushed left to right
|
|
93
105
|
};
|
|
94
106
|
|
|
95
107
|
// A seed is an action id, or an object with input and fragment composition —
|
|
@@ -105,6 +117,12 @@ canvases: [{ id: 'main', initial: 'home' }, { id: 'modal' }] // app + overla
|
|
|
105
117
|
|
|
106
118
|
The shell tracks each canvas independently — pushing on `main` doesn't affect `modal`.
|
|
107
119
|
|
|
120
|
+
On a `mode: 'list'` canvas a push adds an instance without suspending the others, and `removeInstance` / `removeSelf` resume nothing; `pop` and `popTo` behave as on a stack — the instance they expose re-runs its `mount` and `resume` hooks. An instance closes itself with a `{ removeSelf: true }` step and re-reads itself with `{ reload: true }`. `addCanvas` applies `mode` the same way; a canvas removed and re-added under the same id takes the mode it is re-added with.
|
|
121
|
+
|
|
122
|
+
Each entry of the `instances` scope an `actionLayout` sees is the `ActionInstance` (`id`, `definitionId`, `canvasId`, `status`, `data`) plus `title` — the action's `title` resolved against the instance's data, falling back to its `name`, then its id.
|
|
123
|
+
|
|
124
|
+
In nova itself every `initial` seed is pushed, and one naming an unknown action throws `UnknownActionError`. Under moss the same field is read as a candidate list: the first seed the principal is granted is the one that mounts (see moss's docs).
|
|
125
|
+
|
|
108
126
|
### `actions`
|
|
109
127
|
|
|
110
128
|
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.
|
|
@@ -121,7 +139,15 @@ Reusable partial actions (`ActionFragment`s), keyed by id, referenceable from a
|
|
|
121
139
|
|
|
122
140
|
### `fetch`, `transform`, and `functions`
|
|
123
141
|
|
|
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`.
|
|
142
|
+
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`. There is no default for any of the three: nova does not reach for the global `fetch`, and an HTTP endpoint called with none injected fails to `onError`.
|
|
143
|
+
|
|
144
|
+
### `endpointTimeoutMs`
|
|
145
|
+
|
|
146
|
+
How long an endpoint call waits for its reply before it fails to `onError` — default 30000. An endpoint's own `timeoutMs` wins over it. It bounds the first answer only.
|
|
147
|
+
|
|
148
|
+
### `phrases`, `phraseKeys`, `onPhraseMiss`
|
|
149
|
+
|
|
150
|
+
The shell's language: the book every tree it renders is translated through, which prop keys carry prose, and a hook for phrases the book lacks. All absent means no i18n, at no cost. `shell.setPhrases` swaps the book live. See `I18N_DOCS.md`.
|
|
125
151
|
|
|
126
152
|
### `telemetry`
|
|
127
153
|
|
|
@@ -158,9 +184,11 @@ type Shell = {
|
|
|
158
184
|
readonly layoutStore: LayoutStore;
|
|
159
185
|
|
|
160
186
|
// Canvas operations
|
|
161
|
-
push: (canvasId: string, actionId: string, input?: object, fragments?: string[]) => string;
|
|
187
|
+
push: (canvasId: string, actionId: string, input?: object, fragments?: string[], options?: PushOptions) => string;
|
|
188
|
+
originOf: (instanceId: string) => string | undefined; // the `origin` an instance was pushed with
|
|
162
189
|
pop: (canvasId: string) => void;
|
|
163
190
|
popTo: (canvasId: string, instanceId: string) => void;
|
|
191
|
+
removeInstance: (canvasId: string, instanceId: string) => void;
|
|
164
192
|
replace: (canvasId: string, actionId: string, input?: object, fragments?: string[]) => string;
|
|
165
193
|
clear: (canvasId: string) => void;
|
|
166
194
|
back: () => boolean; // undo the last navigation, anywhere on the shell
|
|
@@ -176,6 +204,10 @@ type Shell = {
|
|
|
176
204
|
setCanvasLayout: (layout: LayoutNode | string) => void;
|
|
177
205
|
setLayout: (refId: string, layout: LayoutNode) => void; // hot-swap a LayoutRef target
|
|
178
206
|
|
|
207
|
+
// Language
|
|
208
|
+
setPhrases: (phrases: Phrasebook | undefined) => void;
|
|
209
|
+
getPhrases: () => Phrasebook | undefined;
|
|
210
|
+
|
|
179
211
|
// State queries
|
|
180
212
|
getCanvasState: (canvasId: string) => CanvasState;
|
|
181
213
|
getRuntime: (instanceId: string) => PublicActionRuntime | undefined;
|
|
@@ -203,16 +235,30 @@ type Shell = {
|
|
|
203
235
|
|
|
204
236
|
### Canvas operations
|
|
205
237
|
|
|
206
|
-
#### `push(canvasId, actionId, input?, fragments?)`
|
|
238
|
+
#### `push(canvasId, actionId, input?, fragments?, options?)`
|
|
207
239
|
|
|
208
|
-
Mount a fresh instance of an action on top of a canvas.
|
|
240
|
+
Mount a fresh instance of an action on top of a canvas. On a `stack` canvas it suspends the previous top (its `suspend` lifecycle hook fires). Returns the new instance id.
|
|
209
241
|
|
|
210
242
|
```ts
|
|
211
243
|
const instanceId = shell.push('main', 'editor', { fileId: 'f_42' });
|
|
212
244
|
shell.push('overlay', 'confirm', { id: 'u_42' }, ['modal-frame']); // composed with a fragment
|
|
213
245
|
```
|
|
214
246
|
|
|
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: [...]`.
|
|
247
|
+
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: [...]`. An unknown action id throws `UnknownActionError`; an unknown fragment id throws `UnknownFragmentError`.
|
|
248
|
+
|
|
249
|
+
The optional `options` is a `PushOptions`:
|
|
250
|
+
|
|
251
|
+
```ts
|
|
252
|
+
type PushOptions = {
|
|
253
|
+
origin?: string; // who is placing this — read back with shell.originOf(instanceId)
|
|
254
|
+
history?: boolean; // default true; false keeps the push out of the navigation journal,
|
|
255
|
+
// so `back` cannot undo it
|
|
256
|
+
};
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
#### `originOf(instanceId)`
|
|
260
|
+
|
|
261
|
+
The `origin` an instance was pushed with, or `undefined` — for anything pushed without one, seeded by `initial`, or already unmounted. It is how a caller that places instances (a server-driven layout, an agent) asks whether one is still its own before closing it.
|
|
216
262
|
|
|
217
263
|
#### `pop(canvasId)`
|
|
218
264
|
|
|
@@ -232,6 +278,14 @@ Pop a canvas down to a given instance — everything above it unmounts, in stack
|
|
|
232
278
|
shell.popTo('main', instanceId);
|
|
233
279
|
```
|
|
234
280
|
|
|
281
|
+
#### `removeInstance(canvasId, instanceId)`
|
|
282
|
+
|
|
283
|
+
Remove one instance anywhere in a canvas's stack, not just the top. On a list canvas this is a card closing; on a stack, removing the top resumes the one beneath. A no-op if the instance isn't on the canvas.
|
|
284
|
+
|
|
285
|
+
```ts
|
|
286
|
+
shell.removeInstance('tray', instanceId);
|
|
287
|
+
```
|
|
288
|
+
|
|
235
289
|
#### `replace(canvasId, actionId, input?, fragments?)`
|
|
236
290
|
|
|
237
291
|
Replace the top of a canvas with a new action instance. The replaced action unmounts; the new one mounts. The action below stays unaffected.
|
|
@@ -260,8 +314,9 @@ shell.back();
|
|
|
260
314
|
```
|
|
261
315
|
|
|
262
316
|
The shell keeps a **navigation journal**: before every `push`, `replace`,
|
|
263
|
-
`clear` and `resetTo
|
|
264
|
-
|
|
317
|
+
`clear` and `resetTo` — and every `reconcile` that moved something — it writes
|
|
318
|
+
down the canvas that is about to change. One entry is one position somebody can
|
|
319
|
+
be returned to; `back` restores the newest.
|
|
265
320
|
|
|
266
321
|
- **Global and ordered.** One journal across every canvas, each entry naming the
|
|
267
322
|
one canvas it describes — so back walks a person's own moves in the order they
|
|
@@ -302,6 +357,33 @@ shell.setLayout('region-a', layout); // swap what a LayoutRef placeholder re
|
|
|
302
357
|
|
|
303
358
|
`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
359
|
|
|
360
|
+
### Language
|
|
361
|
+
|
|
362
|
+
```ts
|
|
363
|
+
shell.setPhrases(book); // replace the book; reaches instances already mounted
|
|
364
|
+
shell.setPhrases(undefined); // back to the source language
|
|
365
|
+
shell.getPhrases(); // the book in force, or undefined
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
`setPhrases` fires a state change, so mounted adapters re-render; stacks and instance data are untouched. See `I18N_DOCS.md`.
|
|
369
|
+
|
|
370
|
+
### `reconcileCanvas(shell, canvasId, desired, options)`
|
|
371
|
+
|
|
372
|
+
The declarative verb beside the imperative ones: make a canvas hold exactly a desired list. It is what the `reconcile` step runs (see `ACTION_DOCS.md`), exported for a host that produces a whole desired state itself.
|
|
373
|
+
|
|
374
|
+
```ts
|
|
375
|
+
import { reconcileCanvas } from '@niscorp/nova';
|
|
376
|
+
|
|
377
|
+
const { changed, notes } = reconcileCanvas(
|
|
378
|
+
shell,
|
|
379
|
+
'tools',
|
|
380
|
+
[{ actionId: 'notes' }, { actionId: 'timer', input: { minutes: 5 }, with: ['card-frame'] }],
|
|
381
|
+
{ origin: 'agent', own: 'pushed' },
|
|
382
|
+
);
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
`origin` (required) is stamped on everything the call pushes. `own: 'pushed'` (default) moves only instances carrying that origin; `own: 'canvas'` moves everything on the canvas. One instance per action id. An optional `definitionOf(actionId)` enables the re-aim rule: when a live instance's input changed and that input carries a key the action declares in its `input` and its mount-time load reads through an endpoint `request`, the instance is re-opened instead of written into.
|
|
386
|
+
|
|
305
387
|
### Render-tree access
|
|
306
388
|
|
|
307
389
|
For non-React consumers (evaluators, exporters, tests):
|
|
@@ -366,10 +448,13 @@ Send a UI event into the shell. Triggers with a matching `event:` (and optional
|
|
|
366
448
|
|
|
367
449
|
```ts
|
|
368
450
|
shell.dispatch({ type: 'ui:click', ref: 'save' });
|
|
369
|
-
shell.dispatch({ type: 'ui:input', ref: 'name',
|
|
451
|
+
shell.dispatch({ type: 'ui:input', ref: 'name', payload: 'Ada' });
|
|
370
452
|
shell.dispatch({ type: 'ui:model', ref: 'name', payload: 'Ada' });
|
|
453
|
+
shell.dispatch({ type: 'ui:key', ref: 'search', key: 'Enter' });
|
|
371
454
|
```
|
|
372
455
|
|
|
456
|
+
A `NovaEvent` is `{ type, ref?, payload?, origin? }` — `type` one of `ui:click`, `ui:submit`, `ui:input`, `ui:focus`, `ui:blur`, `ui:model`, `ui:key` (which also carries `key`), `ui:drop`. `origin` is an instance id: an event carrying one reaches that instance's triggers only; one without it reaches every instance listening. Adapters stamp it at the instance boundary.
|
|
457
|
+
|
|
373
458
|
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
459
|
|
|
375
460
|
#### `publish(channel, payload?)`
|
|
@@ -381,7 +466,25 @@ shell.publish('cart-updated', { itemCount: 3 });
|
|
|
381
466
|
shell.publish('user-logged-out');
|
|
382
467
|
```
|
|
383
468
|
|
|
384
|
-
Use it to coordinate between actions that don't otherwise know about each other.
|
|
469
|
+
Use it to coordinate between actions that don't otherwise know about each other. A listening trigger reads the payload as `@event.payload`.
|
|
470
|
+
|
|
471
|
+
#### The `nova:navigated:<canvasId>` channel
|
|
472
|
+
|
|
473
|
+
The shell itself publishes one message per canvas whenever that canvas's **active** instance changes — whatever caused it (a push, `back`, a host's call). Chrome that follows a canvas (a sidebar highlight, a breadcrumb) listens to it instead of to the click that sent somebody there.
|
|
474
|
+
|
|
475
|
+
```ts
|
|
476
|
+
import { navigatedChannel } from '@niscorp/nova';
|
|
477
|
+
|
|
478
|
+
navigatedChannel('main'); // → 'nova:navigated:main'
|
|
479
|
+
// payload: { canvas: 'main', action?: string, instance?: string }
|
|
480
|
+
// `action` / `instance` are absent when the canvas went empty
|
|
481
|
+
|
|
482
|
+
triggers: [
|
|
483
|
+
{ message: 'nova:navigated:main', do: [{ set: 'current', value: '@event.payload.action' }] },
|
|
484
|
+
]
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
Announcements are deferred and coalesced: a burst (a `resetTo` is a clear and a push) says once where the canvas ended.
|
|
385
488
|
|
|
386
489
|
### Telemetry subscriptions
|
|
387
490
|
|
|
@@ -442,6 +545,8 @@ const stop = subscribe(() => redraw()); // once per burst of changes
|
|
|
442
545
|
const whole = await shellSettled(shell, { waitMs: 300 }); // true: nothing is still mounting
|
|
443
546
|
```
|
|
444
547
|
|
|
548
|
+
`api.dispatch` stamps an event that names no `origin` with the canvas's active instance; `api.publish(channel, payload?)` is `shell.publish`. `shellSettled` also takes `stopped?: () => boolean` — once it answers `true` the wait ends with `false`.
|
|
549
|
+
|
|
445
550
|
`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
551
|
|
|
447
552
|
---
|
|
@@ -515,7 +620,7 @@ Each action instance lives in one of four states:
|
|
|
515
620
|
|
|
516
621
|
- **`initializing`** — between `push()` and the moment the mount lifecycle hook completes.
|
|
517
622
|
- **`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)
|
|
623
|
+
- **`suspended`** — another action is on top (on a `stack` canvas; a `list` canvas suspends nothing). Triggers stay attached but do not fire (a suspended action reacts to nothing). Async work already in flight is not cancelled — only unmounting aborts it.
|
|
519
624
|
- **`unmounted`** — terminal. The runtime is disposed; `getRuntime` returns `undefined`.
|
|
520
625
|
|
|
521
626
|
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).
|
|
@@ -524,7 +629,7 @@ Lifecycle hooks fire on each transition: `mount` (init→active), `suspend` (act
|
|
|
524
629
|
|
|
525
630
|
## ID generation
|
|
526
631
|
|
|
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
|
|
632
|
+
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, prefixed `shell-` and `act-`. For deterministic tests, inject your own:
|
|
528
633
|
|
|
529
634
|
```ts
|
|
530
635
|
import { createIdFactory } from '@niscorp/nova';
|
|
@@ -546,8 +651,9 @@ createShell({
|
|
|
546
651
|
The shell can produce these:
|
|
547
652
|
|
|
548
653
|
- **`UnknownActionError`** — `shell.push(canvas, 'foo')` where `'foo'` isn't in `actions`
|
|
549
|
-
- **`
|
|
550
|
-
- **`
|
|
654
|
+
- **`UnknownFragmentError`** — a `fragments` / `with: [...]` id that isn't registered
|
|
655
|
+
- **`ShellDisposedError`** — `push`, `replace`, and the registration / canvas / layout / phrase setters after `dispose()` (`pop`, `popTo`, `removeInstance`, `clear`, `removeCanvas` and `back` are no-ops instead)
|
|
656
|
+
- **`DefinitionValidationError`** — at shell construction, if any action in `actions` fails schema validation; also from `registerAction` / `registerFragment`
|
|
551
657
|
- **`LifecycleError`** — a lifecycle hook step threw (in strict mode propagates, in lax mode routes via `onError`)
|
|
552
658
|
|
|
553
659
|
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.
|
|
@@ -558,7 +664,7 @@ Plus all action-level errors (from `ACTION_DOCS.md`) and layout-level errors (fr
|
|
|
558
664
|
|
|
559
665
|
```ts
|
|
560
666
|
const shell = createShell({
|
|
561
|
-
canvases: CanvasConfig[], // { id, actionLayout?, initial? }
|
|
667
|
+
canvases: CanvasConfig[], // { id, mode?, actionLayout?, initial? }
|
|
562
668
|
actions: Record<string, ActionDefinition>,
|
|
563
669
|
canvasLayout?: LayoutNode | string,
|
|
564
670
|
registry?: ComponentRegistry, // built fresh when omitted
|
|
@@ -568,17 +674,26 @@ const shell = createShell({
|
|
|
568
674
|
fetch?: FetchFn,
|
|
569
675
|
transform?: TransformFn,
|
|
570
676
|
functions?: Record<string, FunctionHandler>,
|
|
677
|
+
endpointTimeoutMs?: number, // default 30000
|
|
678
|
+
phrases?: Phrasebook,
|
|
679
|
+
phraseKeys?: PhraseKeys,
|
|
680
|
+
onPhraseMiss?: (phrase, where) => void,
|
|
571
681
|
telemetry?: { onStateChange?, onDataChange?, onEndpoint? },
|
|
572
682
|
strict?: boolean,
|
|
573
683
|
onError?: (error) => void,
|
|
684
|
+
historyDepth?: number, // default 50; 0 = off
|
|
685
|
+
shellIdFn?, instanceIdFn?, eventBus?, messageBus?,
|
|
574
686
|
});
|
|
575
687
|
|
|
576
688
|
// Canvas ops
|
|
577
|
-
shell.push(canvasId, actionId, input?, fragments?);
|
|
689
|
+
shell.push(canvasId, actionId, input?, fragments?, options?); // → instanceId; options: { origin?, history? }
|
|
690
|
+
shell.originOf(instanceId); // → string | undefined
|
|
578
691
|
shell.pop(canvasId);
|
|
579
692
|
shell.popTo(canvasId, instanceId);
|
|
693
|
+
shell.removeInstance(canvasId, instanceId);
|
|
580
694
|
shell.replace(canvasId, actionId, input?, fragments?); // → instanceId
|
|
581
695
|
shell.clear(canvasId);
|
|
696
|
+
shell.back(); // → boolean
|
|
582
697
|
|
|
583
698
|
// Runtime registration / canvas mutation
|
|
584
699
|
shell.registerAction(definition);
|
|
@@ -589,6 +704,10 @@ shell.removeCanvas(canvasId);
|
|
|
589
704
|
shell.setCanvasLayout(layout);
|
|
590
705
|
shell.setLayout(refId, layout);
|
|
591
706
|
|
|
707
|
+
// Language
|
|
708
|
+
shell.setPhrases(phrases); // undefined → the source language
|
|
709
|
+
shell.getPhrases(); // → Phrasebook | undefined
|
|
710
|
+
|
|
592
711
|
// State
|
|
593
712
|
shell.getCanvasState(canvasId); // → CanvasState
|
|
594
713
|
shell.getRuntime(instanceId); // → PublicActionRuntime | undefined
|
|
@@ -607,6 +726,7 @@ shell.publish(channel, payload?);
|
|
|
607
726
|
shell.onStateChange(handler); // → Unsubscribe
|
|
608
727
|
shell.onDataChange(handler); // → Unsubscribe
|
|
609
728
|
shell.onEndpoint(handler); // → Unsubscribe
|
|
729
|
+
shell.onCanvasChange(canvasId, handler); // → Unsubscribe
|
|
610
730
|
|
|
611
731
|
// Teardown
|
|
612
732
|
shell.dispose();
|
package/TERMINAL_DOCS.md
CHANGED
|
@@ -70,9 +70,12 @@ register through `ctx.register`.
|
|
|
70
70
|
|
|
71
71
|
Kit (`/adapters/tty/components`): `defaultRegistry()` with `Box, Row,
|
|
72
72
|
Stack, Grid, Text, Button, Input, Select, Textarea, Checkbox, Switch,
|
|
73
|
-
Table, Badge, Panel, JsonTree, ActionSlot
|
|
73
|
+
Table, Badge, Panel, JsonTree, ActionSlot` (`Select` is `Input`, `Switch`
|
|
74
|
+
is `Checkbox`; the components are also exported by name), plus `fallback`
|
|
75
|
+
(unknown names
|
|
74
76
|
render their children; childless ones surface `label`/`title` + `count`)
|
|
75
|
-
and the
|
|
77
|
+
and the helpers (`stack`, `inline`, `inlineText`, `pad`, `truncate`,
|
|
78
|
+
`indent`, `str`, `num`, `bool`, `iconGlyph`).
|
|
76
79
|
|
|
77
80
|
---
|
|
78
81
|
|
|
@@ -101,8 +104,9 @@ An Ink component kit for the React adapter's walker — ESM-only, `ink` and
|
|
|
101
104
|
|
|
102
105
|
### Interaction conventions
|
|
103
106
|
|
|
104
|
-
Tab/Shift+Tab cycle ink's focus ring; Enter (
|
|
105
|
-
|
|
107
|
+
Tab/Shift+Tab cycle ink's focus ring; Enter activates (Space too on a
|
|
108
|
+
Checkbox and on a Panel's header buttons; `useActionable` answers Enter
|
|
109
|
+
only); a focused Input holds a local draft, honours `debounce`, submits `ui:key
|
|
106
110
|
Enter`, and forwards ↑/↓ to the server as `ui:key ArrowDown/ArrowUp` (a
|
|
107
111
|
served palette moves its own highlight). Typed-digit handling is the
|
|
108
112
|
host's job — the kit only displays markers and adopts their focus ids.
|
|
@@ -110,15 +114,17 @@ host's job — the kit only displays markers and adopts their focus ids.
|
|
|
110
114
|
### Exports
|
|
111
115
|
|
|
112
116
|
`defaultRegistry()` — `Box, Row, Stack, Grid, Text, Button, Input, Select,
|
|
113
|
-
Textarea, Checkbox, Switch, Table, Badge, Panel, JsonTree, ActionSlot
|
|
117
|
+
Textarea, Checkbox, Switch, Table, Badge, Panel, JsonTree, ActionSlot`
|
|
118
|
+
(`Select` and `Textarea` are `Input`, `Switch` is `Checkbox`; the
|
|
119
|
+
components are also exported by name);
|
|
114
120
|
`fallback` (ref'd unknowns are focusable and click on Enter); `TextWrap`,
|
|
115
121
|
`ErrorMarker`; `useActionable(novaRef, value)` — the full interactive
|
|
116
122
|
convention (marker + focus + Enter-click) for an app's own components;
|
|
117
123
|
`useMarker`, `Mark`, `markerFocusId`, `CanvasMarkersContext`,
|
|
118
|
-
`FrameControlsContext`.
|
|
124
|
+
`FrameControlsContext`; types `MarkerResolve`, `InkFrameControls`.
|
|
119
125
|
|
|
120
126
|
Layout mapping: Grid honours `weights` (flex ratios) and `columns`
|
|
121
127
|
(wrapping tracks); Row honours `justify`/`align`; containers honour
|
|
122
128
|
`border` (incl. sided `'r'`/`'l'`/`'t'`/`'b'`), `padding`, `w`/`width`
|
|
123
129
|
(px→cells at ~8px/cell, percent passthrough), `grow`. What has no
|
|
124
|
-
terminal analog (bg, radius,
|
|
130
|
+
terminal analog (bg, radius, glow) is absent, never faked.
|
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
import { C as ComponentRegistry } from '../../../types-
|
|
1
|
+
import { C as ComponentRegistry } from '../../../types-BLVRduoz.cjs';
|
|
2
2
|
import { DomComponent } from '../index.cjs';
|
|
3
3
|
import 'zod';
|
|
4
4
|
import '../../../schemas-DPdeFlCT.cjs';
|
|
5
5
|
import '../../../schemas-pMyyuXV7.cjs';
|
|
6
|
-
import '../../../types-
|
|
6
|
+
import '../../../types-PDXOkvtK.cjs';
|
|
7
7
|
import '../../../index-caZoXSwr.cjs';
|
|
8
8
|
import '../../../effects-CndX9K7D.cjs';
|
|
9
9
|
|
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
import { C as ComponentRegistry } from '../../../types-
|
|
1
|
+
import { C as ComponentRegistry } from '../../../types-DE77Jl2W.js';
|
|
2
2
|
import { DomComponent } from '../index.js';
|
|
3
3
|
import 'zod';
|
|
4
4
|
import '../../../schemas-DPdeFlCT.js';
|
|
5
5
|
import '../../../schemas-pMyyuXV7.js';
|
|
6
|
-
import '../../../types-
|
|
6
|
+
import '../../../types-BB9RXel5.js';
|
|
7
7
|
import '../../../index-CNfzSBe2.js';
|
|
8
8
|
import '../../../effects-CndX9K7D.js';
|
|
9
9
|
|