@niscorp/nova 0.1.0 → 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.
Files changed (75) hide show
  1. package/ACTION_DOCS.md +121 -30
  2. package/ADAPTER.md +167 -12
  3. package/CHANGELOG.md +19 -0
  4. package/DESIGN.md +45 -22
  5. package/I18N_DOCS.md +4 -4
  6. package/LAYOUT_DOCS.md +55 -14
  7. package/REACT_DOCS.md +52 -16
  8. package/README.md +54 -19
  9. package/SHELL_DOCS.md +136 -16
  10. package/TERMINAL_DOCS.md +13 -7
  11. package/dist/adapters/dom/components/index.d.cts +2 -2
  12. package/dist/adapters/dom/components/index.d.ts +2 -2
  13. package/dist/adapters/dom/index.cjs +351 -53
  14. package/dist/adapters/dom/index.cjs.map +1 -1
  15. package/dist/adapters/dom/index.d.cts +4 -2
  16. package/dist/adapters/dom/index.d.ts +4 -2
  17. package/dist/adapters/dom/index.js +2 -2
  18. package/dist/adapters/dom/server.cjs +356 -55
  19. package/dist/adapters/dom/server.cjs.map +1 -1
  20. package/dist/adapters/dom/server.d.cts +2 -2
  21. package/dist/adapters/dom/server.d.ts +2 -2
  22. package/dist/adapters/dom/server.js +7 -4
  23. package/dist/adapters/dom/server.js.map +1 -1
  24. package/dist/adapters/react/components/index.d.cts +4 -4
  25. package/dist/adapters/react/components/index.d.ts +4 -4
  26. package/dist/adapters/react/index.d.cts +4 -4
  27. package/dist/adapters/react/index.d.ts +4 -4
  28. package/dist/adapters/tty/components/index.d.cts +2 -2
  29. package/dist/adapters/tty/components/index.d.ts +2 -2
  30. package/dist/adapters/tty/index.d.cts +2 -2
  31. package/dist/adapters/tty/index.d.ts +2 -2
  32. package/dist/adapters/vue/components/index.d.cts +6 -6
  33. package/dist/adapters/vue/components/index.d.ts +6 -6
  34. package/dist/adapters/vue/index.d.cts +4 -4
  35. package/dist/adapters/vue/index.d.ts +4 -4
  36. package/dist/adapters/vue/index.js +1 -1
  37. package/dist/agent/index.d.cts +2 -2
  38. package/dist/agent/index.d.ts +2 -2
  39. package/dist/{chunk-7B3RDENH.js → chunk-6N4WRC5V.js} +9 -4
  40. package/dist/chunk-6N4WRC5V.js.map +1 -0
  41. package/dist/chunk-FQAJ24KA.js +408 -0
  42. package/dist/chunk-FQAJ24KA.js.map +1 -0
  43. package/dist/devtools/index.d.cts +2 -2
  44. package/dist/devtools/index.d.ts +2 -2
  45. package/dist/i18n/index.d.cts +2 -2
  46. package/dist/i18n/index.d.ts +2 -2
  47. package/dist/index.cjs +8 -2
  48. package/dist/index.cjs.map +1 -1
  49. package/dist/index.d.cts +5 -5
  50. package/dist/index.d.ts +5 -5
  51. package/dist/index.js +2 -2
  52. package/dist/{palette-CP0wd3bE.d.ts → palette-Mx7XHYC6.d.ts} +1 -1
  53. package/dist/{palette-lm0bU9i5.d.cts → palette-wbJB_svk.d.cts} +1 -1
  54. package/dist/reflect/index.d.cts +2 -2
  55. package/dist/reflect/index.d.ts +2 -2
  56. package/dist/{types-DdltMfw7.d.ts → types-B-rjaUX0.d.ts} +1 -1
  57. package/dist/{types-Boh9ckdG.d.ts → types-BB9RXel5.d.ts} +1 -1
  58. package/dist/{types-De0KpxfI.d.cts → types-BLVRduoz.d.cts} +11 -1
  59. package/dist/{types-DhHL0twe.d.ts → types-B_nOtkyt.d.ts} +1 -1
  60. package/dist/{types-Brc7v_pS.d.ts → types-DE77Jl2W.d.ts} +11 -1
  61. package/dist/{types-Dv6JLmgo.d.cts → types-PDXOkvtK.d.cts} +1 -1
  62. package/dist/{types-Q80YtOQt.d.cts → types-mRKXqZPX.d.cts} +1 -1
  63. package/dist/{types-ByNSwtUV.d.cts → types-uk19d6KC.d.cts} +1 -1
  64. package/package.json +7 -10
  65. package/dist/chunk-7B3RDENH.js.map +0 -1
  66. package/dist/chunk-EG2RUXJN.js +0 -266
  67. package/dist/chunk-EG2RUXJN.js.map +0 -1
  68. package/dist/chunk-I5D2R5UA.js +0 -753
  69. package/dist/chunk-I5D2R5UA.js.map +0 -1
  70. package/dist/chunk-LA3BSEMX.js +0 -1905
  71. package/dist/chunk-LA3BSEMX.js.map +0 -1
  72. package/dist/chunk-OAMC6R6E.js +0 -121
  73. package/dist/chunk-OAMC6R6E.js.map +0 -1
  74. package/dist/primitive-props-CGoJvmcH.d.cts +0 -100
  75. package/dist/primitive-props-CGoJvmcH.d.ts +0 -100
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
- `registerAction`, `registerFragment`, `addCanvas`, `removeCanvas`,
207
- `setCanvasLayout`, `setLayout`, `getCanvasState`, `getRuntime`,
208
- `getState`, `getShellRenderTree`, `getCanvasRenderTree`,
209
- `flattenRenderTree`, `dispatch`, `publish`, `onStateChange`,
210
- `onDataChange`, `dispose`. Canvases are `CanvasConfig`s (`{ id,
211
- actionLayout?, initial? }`) — a canvas can pre-seed its stack and
212
- declare how its instances are arranged. The shell maintains a stack per
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
- └── LifecycleError
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 18+ required.** The adapter uses `useSyncExternalStore`.
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` carries an `ignoreDeprecations` workaround for
373
- `tsup`'s DTS bundler injecting `baseUrl`. This is intentional and
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`. Default `fetch` is the global `fetch` if available; there is no default `transform` or `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. Suspends the previous top (its `suspend` lifecycle hook fires). Returns the new instance id.
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`, 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.
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', value: 'Ada' });
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), and the runtime's abort signal prevents in-flight async work from completing during this state.
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. For deterministic tests, inject your own:
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
- - **`ShellDisposedError`** — any operation after `dispose()`
550
- - **`DefinitionValidationError`** — at shell construction, if any action in `actions` fails schema validation
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?); // → instanceId
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`, plus `fallback` (unknown names
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 line helpers (`stack`, `inline`, `pad`, `truncate`, …).
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 (or Space) activates; a
105
- focused Input holds a local draft, honours `debounce`, submits `ui:key
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, drag) is absent, never faked.
130
+ terminal analog (bg, radius, glow) is absent, never faked.
@@ -1,9 +1,9 @@
1
- import { C as ComponentRegistry } from '../../../types-De0KpxfI.cjs';
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-Dv6JLmgo.cjs';
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-Brc7v_pS.js';
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-Boh9ckdG.js';
6
+ import '../../../types-BB9RXel5.js';
7
7
  import '../../../index-CNfzSBe2.js';
8
8
  import '../../../effects-CndX9K7D.js';
9
9