@niscorp/nova 0.1.1 → 0.1.3

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 (67) hide show
  1. package/ACTION_DOCS.md +121 -30
  2. package/ADAPTER.md +167 -12
  3. package/CHANGELOG.md +18 -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 +55 -20
  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 +2 -2
  25. package/dist/adapters/react/components/index.d.ts +2 -2
  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 +5 -5
  33. package/dist/adapters/vue/components/index.d.ts +5 -5
  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 -7
  65. package/dist/chunk-7B3RDENH.js.map +0 -1
  66. package/dist/chunk-OAMC6R6E.js +0 -121
  67. package/dist/chunk-OAMC6R6E.js.map +0 -1
package/ACTION_DOCS.md CHANGED
@@ -91,6 +91,9 @@ triggers: [
91
91
  // Two-way model binding update
92
92
  { event: 'ui:model', ref: 'name-input', do: [...] },
93
93
 
94
+ // A key press, filtered by key (and optionally ref)
95
+ { event: 'ui:key', key: 'Enter', ref: 'search', do: [...] },
96
+
94
97
  // Cross-action message bus subscription
95
98
  { message: 'cart-updated', do: [...] },
96
99
  ],
@@ -98,16 +101,21 @@ triggers: [
98
101
 
99
102
  ### Trigger fields
100
103
 
101
- - **`event`** *(optional)* — UI event type. Common values: `ui:click`, `ui:input`, `ui:submit`, `ui:focus`, `ui:blur`, `ui:model`. Custom event names work too.
104
+ - **`event`** *(optional)* — UI event type. The built-in events are `ui:click`, `ui:submit`, `ui:input`, `ui:focus`, `ui:blur`, `ui:model`, `ui:key`, `ui:drop`. Custom event names work too.
102
105
  - **`message`** *(optional)* — message bus channel name. Listens via the shell's shared message bus, so this trigger fires from emits in any other action on any other canvas.
103
106
  - **`ref`** *(optional)* — filter UI events by component ref. If unset, the trigger fires on every event of that type. Has no effect on message triggers.
107
+ - **`key`** *(optional)* — filter `ui:key` events by the key pressed, e.g. `"ArrowDown"`. Has no effect on message triggers.
104
108
  - **`do`** *(required)* — ordered array of steps to run.
105
109
 
106
- A trigger MUST have either `event` or `message`. Setting both is an error.
110
+ A trigger MUST have `event` or `message` — the schema rejects one with neither. If both are set the trigger listens for the event and the `message` is ignored.
111
+
112
+ Steps can read the thing that fired them as **`@event`**: `@event.payload` is a UI event's payload (the typed text of a `ui:model`, a clicked row's key), or the `payload` of the `emit` that reached a message trigger.
107
113
 
108
114
  ### When triggers fire
109
115
 
110
- Triggers attach when the action mounts and detach when it unmounts. While the action is **suspended** (another action is pushed on top), triggers stay attached but do **not** fire — a suspended action reacts to nothing until it resumes, and the runtime's abort signal prevents in-flight async work from completing. On resume the `mount` hook re-runs (see [Lifecycle hooks](#lifecycle-hooks)), so the action refreshes its own data instead of reacting while backgrounded.
116
+ Triggers attach when the action mounts and detach when it unmounts. A UI event dispatched from inside an instance's rendered layout carries that instance's id as its `origin` and reaches that instance's triggers only; an event with no `origin` (a programmatic `shell.dispatch`) reaches every instance listening. While the action is **suspended** (another action is pushed on top of it on a `stack` canvas), triggers stay attached but do **not** fire — a suspended action reacts to nothing until it resumes. Suspension does not cancel async work already in flight; only unmounting aborts it. On resume the `mount` hook re-runs (see [Lifecycle hooks](#lifecycle-hooks)), so the action refreshes its own data instead of reacting while backgrounded.
117
+
118
+ A chain of triggers is bounded: each `emit` reaching a message trigger, each `reload`, and each navigation that mounts an action is one hop, and a chain more than 64 hops deep (or 1024 hops in total from the gesture that started it) stops and reports a `NovaError` with code `RUNAWAY_CHAIN` to `onError`.
111
119
 
112
120
  A `ui:model` trigger observes the value the event wrote: the runtime applies a `ui:model` to its own model bindings **before** it dispatches the event to triggers, so a trigger's steps read the just-typed value, not the one the field held before the keystroke.
113
121
 
@@ -164,7 +172,7 @@ Add or subtract from a number.
164
172
  { decrement: 'count', by: 2 } // -2
165
173
  ```
166
174
 
167
- If the field isn't a number, it's treated as 0.
175
+ If the field isn't a number, it's treated as 0. `by` is a literal number — the schema rejects a template string here.
168
176
 
169
177
  ### `push` / `pop`
170
178
 
@@ -175,6 +183,8 @@ Append to or remove from the end of an array. **Note:** `push` / `pop` here are
175
183
  { pop: 'items' }
176
184
  ```
177
185
 
186
+ `push` onto a path that doesn't exist yet creates the array. `pop` on something that isn't an array is a no-op.
187
+
178
188
  ### `removeAt`
179
189
 
180
190
  Remove an element at a specific index.
@@ -199,29 +209,29 @@ Reorder an array element from one index to another.
199
209
 
200
210
  ### `clear`
201
211
 
202
- Empty an array or object, or set a primitive to its zero value.
212
+ Empty an array or object. On anything else (a primitive, a missing path) the key is removed.
203
213
 
204
214
  ```ts
205
215
  { clear: 'items' } // → []
206
216
  { clear: 'user' } // → {}
207
- { clear: 'count' } // → 0
217
+ { clear: 'count' } // → key removed
208
218
  ```
209
219
 
210
220
  ### `reset`
211
221
 
212
- Reset the entire data store to the action's `data` defaults.
222
+ Reset one data path. `reset` takes a path string — `{ reset: true }` does not parse.
213
223
 
214
224
  ```ts
215
- { reset: true }
225
+ { reset: 'draft' }
216
226
  ```
217
227
 
218
- Use this in a "Cancel" or "Start over" handler.
228
+ Restores the path's initial value: the `data` defaults merged with the input the instance was opened with, as they stood at spawn. A path that had no initial value is set to `undefined`.
219
229
 
220
230
  ---
221
231
 
222
232
  ## Effects
223
233
 
224
- Effects can be async and may reach outside the action's data store. There are ten: `call`, `emit`, `reload`, and the navigation effects `push`, `pop`, `replace`, `popTo`, `resetTo`, `removeInstance`, `removeSelf`.
234
+ Effects can be async and may reach outside the action's data store. There are eleven: `call`, `emit`, `reload`, and the navigation effects `push`, `pop`, `replace`, `popTo`, `resetTo`, `removeInstance`, `removeSelf`, `reconcile`.
225
235
 
226
236
  ### `call`
227
237
 
@@ -232,7 +242,6 @@ Invoke a named endpoint. Optional `onSuccess` and `onError` step branches run af
232
242
  call: 'fetchUser',
233
243
  onSuccess: [
234
244
  { set: 'loading', value: false },
235
- { set: 'user', from: 'fetchUserResponse' },
236
245
  ],
237
246
  onError: [
238
247
  { set: 'loading', value: false },
@@ -241,9 +250,11 @@ Invoke a named endpoint. Optional `onSuccess` and `onError` step branches run af
241
250
  }
242
251
  ```
243
252
 
253
+ The response is written to the endpoint's `target` before `onSuccess` runs; there is no implicit per-call response slot. If a newer call to the same endpoint has already landed, an older response arriving late does not overwrite `target` (its `onSuccess` still runs).
254
+
244
255
  The `onError` branch has access to a special **`@error`** scope inside templates: `{{@error.message}}`, `{{@error.status}}`, `{{@error.data}}`. Use it to surface error messages in the UI.
245
256
 
246
- If the endpoint name doesn't exist in the action's `endpoints`, the call fails with a synthetic error and `onError` fires.
257
+ If the endpoint name doesn't exist in the action's `endpoints` (or a function endpoint names an unregistered function), the call fails with a synthetic error and `onError` fires. Inside a lifecycle hook, a failed call with no `onError` raises a `LifecycleError`.
247
258
 
248
259
  ### `emit`
249
260
 
@@ -254,7 +265,7 @@ Publish a message on the shell's shared message bus. Other actions (on any canva
254
265
  { emit: { channel: 'user-saved', payload: { id: '{{$.user.id}}' } } }
255
266
  ```
256
267
 
257
- The `payload` is resolved against the current data — templates and bindings work.
268
+ The `channel` and `payload` are resolved against the current data (and `@event` / `@error`) — templates and bindings work. A listener reads the payload as `@event.payload`. The message is published after the current turn settles, not inside it, so an `emit` followed by a `pop` reaches the action the pop reveals.
258
269
 
259
270
  ### `push`, `pop`, `replace`
260
271
 
@@ -276,7 +287,7 @@ The `pop` effect uses `pop: true` (a literal boolean) to distinguish it from the
276
287
 
277
288
  `push`, `replace`, and `resetTo` accept an optional `with: [...]` — ids of `ActionFragment`s composed into the action before it is instantiated. Each fragment wraps the action (the action's layout fills the fragment's `{ slot: 'body' }`) and contributes its triggers/data; the action wins on conflict.
278
289
 
279
- `input` values resolve against the current data plus the firing event, so a trigger can pass dynamic data to the action it opens — e.g. `input: { record: '@event.payload' }` or `input: { id: '@event.payload.todo_id' }`.
290
+ `input` values resolve against the current data plus the firing event, so a trigger can pass dynamic data to the action it opens — e.g. `input: { record: '@event.payload' }` or `input: { id: '@event.payload.todo_id' }`. `action` resolves the same way (`action: '{{@event.payload}}'` opens the action a binding names); a literal id passes through unchanged.
280
291
 
281
292
  ### `popTo`, `resetTo`
282
293
 
@@ -292,6 +303,34 @@ Stack-navigation effects.
292
303
 
293
304
  `popTo` unmounts everything above the given instance (a no-op if it isn't in the stack) — what a breadcrumb fires. `resetTo` clears the whole stack and pushes one new root — what a screen-level nav fires so drilling into a record doesn't leave a stale stack beneath the new screen.
294
305
 
306
+ ### `removeInstance`, `removeSelf`
307
+
308
+ ```ts
309
+ { removeInstance: { instance: '{{@event.payload}}' } } // remove one instance, anywhere in the stack
310
+ { removeInstance: { canvas: 'tray', instance: 'act-3' } }
311
+ { removeSelf: true } // remove the firing instance
312
+ ```
313
+
314
+ `pop` removes the top; `removeInstance` removes a named instance wherever it sits (a no-op if it isn't on the canvas). `removeSelf` is the same aimed at the firing instance — what a card's close button fires on a `mode: 'list'` canvas, without knowing its own id. `instance` (and `popTo`'s) resolves against data and the firing event.
315
+
316
+ ### `reconcile`
317
+
318
+ ```ts
319
+ { reconcile: { to: '$.tools', action: 'tool_id' } }
320
+ { reconcile: { to: '$.tools', action: 'tool_id', input: 'tool_input', canvas: 'tools', own: 'canvas', with: ['card-frame'] } }
321
+ ```
322
+
323
+ Makes a canvas hold exactly the actions a list in the action's data names: missing ones are pushed, ones no longer listed are removed, ones already there stay mounted. One instance per action id.
324
+
325
+ - **`to`** *(required)* — binding to the list, an array of rows. Anything else is an empty list.
326
+ - **`action`** *(required)* — the row field naming the action id to place. Rows without it are skipped; so is a row naming an action the shell doesn't have.
327
+ - **`input`** *(optional)* — the row field holding that action's input object.
328
+ - **`canvas`** *(optional)* — canvas to reconcile; defaults to the current one.
329
+ - **`own`** *(optional)* — what the step may remove or rewrite: `'pushed'` (default) only what this action placed there, `'canvas'` everything on it.
330
+ - **`with`** *(optional)* — fragment ids to compose each placed action with.
331
+
332
+ When a listed action is already mounted and its row's input changed, the new input is written into the live instance — unless the row's input carries a key (changed or not) that the action declares in its `input` and its `mount` calls read through an endpoint `request`, in which case the instance is re-opened.
333
+
295
334
  ### `reload`
296
335
 
297
336
  ```ts
@@ -338,6 +377,9 @@ endpoints: {
338
377
  - **`response`** *(optional)* — a transform config run by the injected evaluator over the reply **exactly as received** (`$` is the reply — object, array, or scalar; no wrapping) to produce the value stored at `target`. Declaring it without an injected transform is a hard error — never the unshaped reply.
339
378
  - **`target`** *(optional)* — data path to write the (possibly transformed) response into on success. If unset, the response is discarded.
340
379
  - **`errorTarget`** *(optional)* — data path to write the error info into on failure.
380
+ - **`timeoutMs`** *(optional)* — positive integer: how long to wait for the reply, in ms, before the call fails to `onError` (with `@error.timedOut`). Defaults to the shell's `endpointTimeoutMs`, itself 30000 by default. It bounds the first answer only.
381
+
382
+ A successful reply must be JSON: a 2xx whose body does not parse fails to `onError` (`the reply is not JSON`). 204 and 205 succeed with no value.
341
383
 
342
384
  The evaluator is dependency-injected: `ShellConfig.transform` is a `(config, source) => unknown` function nova never interprets — the host wires in Prism's `evaluate` (or anything else). Initial data is never transformed.
343
385
 
@@ -351,12 +393,14 @@ endpoints: {
351
393
  }
352
394
  ```
353
395
 
354
- - **`fn`** *(required)* — key of a function registered in `ShellConfig.functions`. The handler receives `(data, signal)` and its return value is stored at `target`. An unregistered name fails the call.
355
- - **`target`** / **`errorTarget`** — as above.
396
+ - **`fn`** *(required)* — key of a function registered in `ShellConfig.functions`. The handler receives `(data, signal)` and its return value is stored at `target`. An unregistered name fails the call. The name resolves through the action's data, so `fn: '{{$.saveFn}}'` lets one action pick its handler from data.
397
+ - **`target`** / **`errorTarget`** / **`timeoutMs`** — as above.
356
398
 
357
399
  ### The fetch implementation
358
400
 
359
- The runtime needs a fetch implementation injected. The shell takes a `fetch?: FetchFn` config option. Default is the global `fetch` if available; otherwise endpoint calls fail.
401
+ The runtime needs a fetch implementation injected. The shell takes a `fetch?: FetchFn` config option. There is no default — nova does not reach for the global `fetch`; with none injected an HTTP endpoint call fails to `onError` (`No fetch implementation provided to action runtime`).
402
+
403
+ A `FetchResponse` may also carry `onChange(handler)`: a transport that can tell the answer changed later (a reactive read under moss) offers it, and nova applies each later body as it applied the first — `response`, then `target` — with no `onSuccess` and no telemetry, until a newer call to the same endpoint lands or the instance unmounts.
360
404
 
361
405
  For tests and the showroom, you inject a mock:
362
406
 
@@ -396,15 +440,40 @@ lifecycle: {
396
440
 
397
441
  ### When each fires
398
442
 
399
- - **`mount`** — when the action is pushed onto a canvas (after `data` and `input` are merged, before triggers attach), and **again on every resume**, before the `resume` hook. A suspended action ignores everything while backgrounded, so re-running `mount` is what brings its data current when it is revealed again.
400
- - **`suspend`** — when another action is pushed on top, this action transitions from `active` → `suspended`. Triggers stay attached but do not fire while suspended.
443
+ - **`mount`** — when the action is pushed onto a canvas (after `data` and `input` are merged and triggers attach; the instance is `initializing` until the hook completes), and **again on every resume**, before the `resume` hook. A suspended action ignores everything while backgrounded, so re-running `mount` is what brings its data current when it is revealed again. A `{ reload: true }` step re-runs it too.
444
+ - **`suspend`** — when another action is pushed on top on a `stack` canvas, this action transitions from `active` → `suspended`. Triggers stay attached but do not fire while suspended. A `mode: 'list'` canvas suspends nothing.
401
445
  - **`resume`** — when the action above is popped, this action transitions from `suspended` → `active`. Runs after the re-run of `mount`.
402
- - **`unmount`** — once, when the action is popped from the canvas (or the shell is disposed). Triggers detach AFTER the unmount steps run.
446
+ - **`unmount`** — once, when the action is popped from the canvas (or the shell is disposed). In-flight steps are aborted and triggers detach BEFORE the unmount steps run; the unmount steps run on a fresh signal, so they can do their own async work.
403
447
 
404
448
  In **strict mode** (set `strict: true` on the shell), a failure inside a lifecycle hook surfaces on the next shell call as a `LifecycleError`. In **lax mode** (the default), it routes to the shell's `onError` telemetry and the lifecycle continues.
405
449
 
406
450
  ---
407
451
 
452
+ ## Fragments
453
+
454
+ An `ActionFragment` is a reusable partial action — chrome plus wired behavior — merged into a concrete action when it is opened with `with: [...]`. It only exists merged; it cannot be pushed on its own. Register fragments on `ShellConfig.fragments` or with `shell.registerFragment`.
455
+
456
+ ```ts
457
+ import type { ActionFragment } from '@niscorp/nova';
458
+
459
+ const modalFrame: ActionFragment = {
460
+ kind: 'fragment', // required discriminator
461
+ id: 'modal-frame', // required — the id a `with: [...]` names
462
+ layout: {
463
+ component: 'Panel',
464
+ props: { title: 'Confirm', closeRef: 'close' },
465
+ children: { slot: 'body' }, // the composing action's layout lands here
466
+ },
467
+ triggers: [{ event: 'ui:click', ref: 'close', do: [{ pop: true }] }],
468
+ };
469
+ ```
470
+
471
+ Fields: `kind`, `id`, and optional `name`, `description`, `layout`, `data`, `triggers`, `endpoints`, `lifecycle` — the same shapes as on an action. A fragment has no `title` or `input`.
472
+
473
+ On merge (`composeAction(action, fragments)`): each fragment's layout wraps the layout so far, filling its `{ slot: 'body' }` — the last fragment listed is the outermost; a fragment whose `layout` is a store id replaces the layout instead of wrapping it. `data` and `endpoints` merge with the action winning on a clash (`data` is a shallow merge). Triggers concatenate, fragment first. Lifecycle steps concatenate per hook, fragment first. An unknown fragment id throws `UnknownFragmentError`.
474
+
475
+ ---
476
+
408
477
  ## The bindings inside steps
409
478
 
410
479
  Step values can use bindings — same syntax as layout bindings.
@@ -416,12 +485,13 @@ Step values can use bindings — same syntax as layout bindings.
416
485
  // Set from another path (copy)
417
486
  { set: 'previous', from: 'current' }
418
487
 
419
- // Increment by a value from data
420
- { increment: 'total', by: '{{$.delta}}' } // Wait — `by` is typed as number; templates here would need
421
- // the bare `{{ expr }}` form to preserve the number type.
488
+ // Set from the firing event
489
+ { set: 'selectedId', value: '@event.payload.id' }
422
490
  ```
423
491
 
424
- Endpoint URL templates, body templates, header templates all resolve against the current data. The `@error` scope is available inside `onError` chains.
492
+ Inside mutations, only these resolve: the `value` of a `set` or `push`, and a string `index` / `from` / `to` on `removeAt` / `move`. `set … from` takes a plain data path, not a binding. `increment` / `decrement` take a literal `by`.
493
+
494
+ Endpoint URL templates and header value templates resolve against the current data; a request body is built by the `request` transform. The `@error` scope is available inside `onError` chains, and `@event` inside a trigger's steps.
425
495
 
426
496
  ---
427
497
 
@@ -440,7 +510,9 @@ Fields available on `@error`:
440
510
  - `message: string`
441
511
  - `status: number` (HTTP status, or 0 for network/function errors)
442
512
  - `data: unknown` (the response body if any)
443
- - `aborted?: boolean` (true if the call was aborted by an unmount)
513
+ - `timedOut?: boolean` (true if no reply arrived within the endpoint's wait)
514
+
515
+ A call aborted by an unmount is silent: `onError` does not run, `errorTarget` is not written, and nothing is reported to telemetry.
444
516
 
445
517
  ---
446
518
 
@@ -476,9 +548,14 @@ Action-time errors all extend `NovaError`:
476
548
 
477
549
  - **`LifecycleError`** — a step inside a lifecycle hook failed
478
550
  - **`UnknownActionError`** — `shell.push(canvas, 'name')` where `'name'` isn't in `actions`
551
+ - **`UnknownFragmentError`** — a `with: [...]` names a fragment the shell doesn't have
552
+ - **`UnknownFunctionError`** — a `call` to a function endpoint whose `fn` isn't registered, with no `onError` branch, in strict mode
479
553
  - **`DefinitionValidationError`** — an action definition fails Zod validation at shell init
554
+ - **`MutationError`** — in strict mode, `push`, `pop`, `removeAt`, `move` or `clear` aimed at a path that is missing or of the wrong type. It is reported to `onError`, and the batch of mutations it was in is not applied. In lax mode the op is a no-op
555
+
556
+ A runaway trigger chain is reported as a plain `NovaError` with code `RUNAWAY_CHAIN`.
480
557
 
481
- In strict mode all of these throw. In lax mode they route through the shell's `onError` callback.
558
+ `DefinitionValidationError` always throws, from `createShell` / `registerAction`. `UnknownActionError` and `UnknownFragmentError` always throw from a direct `shell.push` / `shell.replace`; raised by a navigation step inside a trigger they route to `onError`. Lifecycle failures route to `onError`, and in strict mode also surface on the next shell call.
482
559
 
483
560
  ---
484
561
 
@@ -488,7 +565,7 @@ Action definitions are validated against `ActionDefinitionSchema` when you pass
488
565
 
489
566
  ### `auditAction` — static wiring audit
490
567
 
491
- A definition can parse, mount, and render politely while being broken at click time. `auditAction(def, { catalog? })` cross-references the definition against itself: layout bindings ↔ `data` defaults, layout refs ↔ triggers (dead chrome and phantom triggers both), `call` steps ↔ endpoint names, endpoint targets ↔ `data`, mutation paths ↔ `data`, and — when a `catalog` of `{ id, input }` entries is given — push/replace/resetTo targets and their seeded input keys. Returns `{ ok, issues: string[] }` with precise messages.
568
+ A definition can parse, mount, and render politely while being broken at click time. `auditAction(def, { catalog? })` cross-references the definition against itself: layout bindings ↔ `data` defaults, layout refs ↔ triggers (dead chrome and phantom triggers both), `call` steps ↔ endpoint names, endpoint targets ↔ `data`, mutation paths ↔ `data`, and — when a `catalog` of `{ id, input }` entries is given — push/replace/resetTo targets and their seeded input keys. When a `channels` list is given, every `message:` listen and every `emit` must name a known channel (or one the definition itself emits / listens on); `collectChannels(def)` returns a definition's `{ emits, listens }` to build that list from. Returns `{ ok, issues: string[] }` with precise messages.
492
569
 
493
570
  Scope: SELF-CONTAINED definitions with inline layouts (generated actions above all). Hand-authored actions that receive triggers from fragments or bind stored layouts should audit the COMPOSED definition, or skip.
494
571
 
@@ -514,9 +591,22 @@ type TriggerConfig = {
514
591
  event?: string; // OR message
515
592
  message?: string;
516
593
  ref?: string;
594
+ key?: string; // filters ui:key events
517
595
  do: Step[];
518
596
  };
519
597
 
598
+ type ActionFragment = {
599
+ kind: 'fragment';
600
+ id: string;
601
+ name?: string;
602
+ description?: string;
603
+ layout?: LayoutNode | string; // chrome; { slot: 'body' } takes the action's layout
604
+ data?: Record<string, unknown>;
605
+ triggers?: TriggerConfig[];
606
+ endpoints?: Record<string, EndpointConfig>;
607
+ lifecycle?: LifecycleConfig;
608
+ };
609
+
520
610
  type Step = Mutation | Effect;
521
611
 
522
612
  // Mutations
@@ -530,7 +620,7 @@ type Step = Mutation | Effect;
530
620
  { removeAt: string, index: number | string }
531
621
  { move: string, from: number | string, to: number | string }
532
622
  { clear: string }
533
- { reset: true }
623
+ { reset: string }
534
624
 
535
625
  // Effects
536
626
  { call: string, onSuccess?: Step[], onError?: Step[] }
@@ -542,11 +632,12 @@ type Step = Mutation | Effect;
542
632
  { resetTo: { action: string, canvas?: string, input?: object, with?: string[] } }
543
633
  { removeInstance: { canvas?: string, instance: string } }
544
634
  { removeSelf: true }
635
+ { reconcile: { to: string, action: string, input?: string, canvas?: string, own?: 'pushed' | 'canvas', with?: string[] } }
545
636
  { reload: true }
546
637
 
547
638
  // Endpoints (EndpointConfig = HTTP | Function)
548
- { url: string, method: string, headers?: object, request?: unknown, response?: unknown, target?: string, errorTarget?: string }
549
- { fn: string, target?: string, errorTarget?: string }
639
+ { url: string, method: string, headers?: object, request?: unknown, response?: unknown, target?: string, errorTarget?: string, timeoutMs?: number }
640
+ { fn: string, target?: string, errorTarget?: string, timeoutMs?: number }
550
641
  ```
551
642
 
552
643
  For wiring actions onto a canvas via the shell, see `SHELL_DOCS.md`. For the layout language actions render through, see `LAYOUT_DOCS.md`.
package/ADAPTER.md CHANGED
@@ -15,8 +15,8 @@ line-terminal adapter (`@niscorp/nova/adapters/tty`, `createTtyView` — a
15
15
  pure render to `{ text, interactives }`; the host maps commands onto the
16
16
  numbered interactives), and the full-screen terminal kit
17
17
  (`@niscorp/nova/adapters/ink` — an Ink component vocabulary riding the React
18
- adapter's walker; Tab cycles focus, Enter activates). A Svelte adapter is
19
- a sibling folder, built the same way.
18
+ adapter's walker; Tab cycles focus, Enter activates). A Svelte adapter
19
+ would be a sibling folder, built the same way.
20
20
 
21
21
  A react-shaped host that is not the DOM threads three optional seams through
22
22
  `NovaRenderProvider`: `fallback` (unregistered names render their children
@@ -94,8 +94,9 @@ renderers, the DOM adapter through `renderToString(registry, api, { window })`
94
94
  (`@niscorp/nova/adapters/dom/server` — the host hands in a DOM; nova depends
95
95
  on none). Await `shellSettled(shell)` first: an instance is `initializing`
96
96
  until its mount hook has been awaited, so that is the moment the first screen
97
- is whole. Adapters that adopt in place (React, Vue) hydrate over the markup; one
98
- that rebuilds its root (DOM) replaces it with the same elements in one step.
97
+ is whole. Adapters that adopt in place (React, Vue) hydrate over the markup; the
98
+ DOM adapter's first render replaces it with the same elements in one step, and
99
+ keeps those from then on (see "The DOM adapter keeps what did not change").
99
100
 
100
101
  ### 4. Structural slots and the component vocabulary
101
102
 
@@ -125,9 +126,12 @@ against registry schemas — that checks output against an authoring contract.
125
126
  Ship the primitive vocabulary — Stack, Text, Input, Button, Box at minimum,
126
127
  plus the introspection primitives Panel and JsonTree (nova's devtools compose
127
128
  against them) — with static `meta` (description + props schema) so registries
128
- and agent tooling can introspect them. The DOM kit additionally ships Row,
129
- Grid, Checkbox, Textarea, and Table, with Select and Switch as aliases of
130
- Input and Checkbox.
129
+ and agent tooling can introspect them. The React and Vue kits ship exactly
130
+ that set plus the two slots (`registerNovaReactComponents`,
131
+ `registerNovaVueComponents`). The DOM kit additionally ships Row, Grid,
132
+ Checkbox, Textarea, and Table, with Select and Switch as aliases of Input and
133
+ Checkbox; the TTY and Ink kits ship the DOM kit's names plus Badge (each a
134
+ `defaultRegistry()`).
131
135
 
132
136
  ### 5. SlotWrapper persistence
133
137
 
@@ -148,13 +152,14 @@ or bound inputs drop keystrokes the moment the shell is remote:
148
152
 
149
153
  - **Preserve the in-progress value of a focused input.** While a `model`-bound
150
154
  input is focused, its local editing value is authoritative; an incoming tree
151
- must not overwrite it. Release to the server value on blur. The React `Input`
152
- holds a local `draft` (`null` = not editing, server wins); the DOM adapter
153
- captures the focused element's value + caret and restores them across its full
154
- rebuild (`captureFocus`/`restoreFocus`). Same rule, framework-shaped mechanism.
155
+ must not overwrite it. Release to the server value on blur. The React, Vue
156
+ and Ink `Input`s hold a local `draft` (`null` = not editing, server wins); the DOM adapter
157
+ does not build a field again for a change of its `value` alone while it is
158
+ being typed in, and shows the tree's value again at the first render after it
159
+ is left. Same rule, framework-shaped mechanism.
155
160
  - **Honour the `debounce` prop on a `model`-bound node.** `props.debounce`
156
161
  (milliseconds, default 0) coalesces `ui:model` dispatches; flush any pending
157
- value on blur. Both reference adapters implement it — omitting it silently
162
+ value on blur. The React, Vue, DOM and Ink adapters implement it — omitting it silently
158
163
  makes a served `debounce` a no-op in your terminal, so the same layout behaves
159
164
  differently across renderers.
160
165
 
@@ -168,3 +173,153 @@ input (a `set <n> <text>` command is one atomic, complete value, so there is
168
173
  no in-progress draft for an echo to clobber) and therefore nothing for
169
174
  `debounce` to coalesce. The obligations bind any adapter that *does* hold
170
175
  live input focus — a full-screen TUI included.
176
+
177
+ ## The DOM adapter keeps what did not change
178
+
179
+ React and Vue hand nova's trees to a reconciler. The DOM adapter has none to hand
180
+ them to, so it is one: `createDomView` keeps the tree it last drew beside the DOM
181
+ that tree produced, and a render walks the two together. What is the same as
182
+ last time keeps its element — **the same DOM node, never taken off the page** —
183
+ and only what differs is built.
184
+
185
+ That is the difference between a page that is drawn and a page that is drawn
186
+ *again*. An element that stays keeps everything the tree does not hold: focus,
187
+ scroll position, a text selection, an open `<details>`, a CSS animation in
188
+ flight, a playing `<video>`, a timer or an observer its component started. And
189
+ the cost of a change is the size of the change, not the size of the page: one
190
+ changed string is one text node written.
191
+
192
+ ### What a render does
193
+
194
+ - **The same node keeps its element.** A component whose props, `ref`, `model`
195
+ and children are what they were is not asked for an element again.
196
+ - **A text that changed is written** into the text node already there.
197
+ - **Siblings are matched by `renderNodeKey`**, as obligation 1 says. Two that
198
+ share a key (looped rows that share a `ref` and carry no key) are told apart
199
+ by order. A list that is reordered has its elements moved — as few as will do
200
+ — not built; one that gains or loses an item gains or loses that one element.
201
+ - **A component whose own props, `ref` or `model` changed is asked again.** What
202
+ is below it was reconciled all the same and is handed in, so a descendant
203
+ that did not change is the same node under the new element. It was *moved*,
204
+ though, and a move is not free: the browser restarts a moved element's
205
+ animations and drops its scroll.
206
+ - **A different instance or canvas in the same place is all new.** An
207
+ `ActionSlot` whose `instanceId` changed, or a `CanvasSlot` whose `canvasId`
208
+ did, keeps nothing — with or without a key (obligation 4's "a swap remounts").
209
+ Its listeners dispatch as the old instance; kept, a press would reach an
210
+ instance that is no longer there.
211
+ - **A change in one instance or on one canvas leaves the others alone.** That
212
+ follows from the rest and is the point of it.
213
+ - **The first render replaces whatever the root held**, once: markup drawn ahead
214
+ of time is replaced with the same elements. Somebody already typing in that
215
+ markup keeps their words, their caret and their focus — the adapter finds the
216
+ field's twin by where it sits. Adopting the elements themselves, rather than
217
+ replacing them, is not done.
218
+
219
+ ### What a kit can rely on, and what it owes
220
+
221
+ A `DomComponent` is still a builder: props and already-built children in, one
222
+ element out, no update path. What changed is *when it is called* — only when it
223
+ has to be. It is not called because something else on the page changed, so:
224
+
225
+ **It is a function of its props and its children, and of nothing else.** A
226
+ component that reads the clock or the window while it builds keeps what it read
227
+ until its own props change. Something that has to move on its own — a countdown
228
+ — moves itself (a timer), and stops through `onRemove`.
229
+
230
+ **`onRemove(cleanup)`** is the other end of anything a component starts. The
231
+ cleanup runs once, when the element leaves the page for good: it was removed, it
232
+ was replaced because its own props changed, or the view was destroyed
233
+ (`renderToString` destroys the view it drew with, so nothing is left running
234
+ where only markup was wanted). An element that stays is not told anything.
235
+
236
+ **Children are patched in place only under an element that holds exactly them.**
237
+ The adapter looks at what the component returned:
238
+
239
+ | The component… | When its children change |
240
+ | --- | --- |
241
+ | put them, in order and with nothing else, straight into the element it returned | they are put in, taken out and moved under that element; the component is not asked |
242
+ | did anything else with them — an inner wrapper, a cell around each, a heading of its own before them, read them and placed none | it is asked again whenever it would be handed different children. A change *inside* a child is still patched where it stands |
243
+ | goes from having children to having none, or back | it is asked again, whichever of the above it is — it may draw itself differently when empty |
244
+
245
+ The middle row is not a penalty for being unusual; it is the only safe answer.
246
+ A kit that wraps each child in a cell looks, with a single child, exactly like
247
+ one that wraps them all in one box, and the adapter cannot ask what it would do
248
+ with a second. So: **for a list whose items come and go — a thread, a feed, a
249
+ set of cards — put the children straight into the element that holds them** (and
250
+ that scrolls, if it scrolls). A wrapper inside it means every arrival moves
251
+ every item.
252
+
253
+ **A component that depends on its children says so.** One that holds its
254
+ children *and* marks them, counts them, or treats the first unlike the rest
255
+ looks like one that only holds them — and a child patched in beside the others
256
+ would go unmarked. It calls `dependsOnChildren()` while it builds, and is then
257
+ asked again whenever it would be handed different children. It is handed the
258
+ children that stayed as it left them, so what it does to them it must be able
259
+ to do twice: set a mark *and* clear it, not only set it.
260
+
261
+ **What changes often goes in as children, not as a prop.** A component fed by a
262
+ prop is built again when that prop changes — a new element, without the scroll
263
+ or the animation of the old one. The same text handed in as a child is a text
264
+ node written in place, under an element that stays:
265
+
266
+ ```ts
267
+ { component: 'Code', props: { text: '$.source' } } // a new <pre> on every change
268
+ { component: 'Code', children: '$.source' } // the same <pre>, its text written
269
+ ```
270
+
271
+ This is where the DOM adapter is still a step behind React and Vue, which run
272
+ the component again and keep the element. An `update` path on a component would
273
+ close it; nothing has needed one yet.
274
+
275
+ ### Bound fields and focus
276
+
277
+ - **A field that is being typed in is not replaced for its `value`.** A tree
278
+ that differs from the last only in a bound field's `value` — the echo of what
279
+ was just typed, or a value from elsewhere — leaves the field alone while the
280
+ person is in it: its caret, an IME composition and a pending debounce are the
281
+ element's, and stay with it. Once it is left, the next render shows the tree's
282
+ value again (the kit is asked for the field afresh, because how a value is
283
+ shown is the kit's business). A checkbox or a radio is not "typed in": the
284
+ tree's answer shows at once.
285
+ - **A field that had to be built again while focused** (another of its props
286
+ changed) is given what was being typed, the caret, and focus.
287
+ - **Focus follows the element.** One that stayed has it still. One that was
288
+ moved has it given back; one that was built again has it given to the element
289
+ built in its place — a button as much as a field.
290
+ - **Leaving a field sends what debounce was holding**, as obligation 6 says.
291
+
292
+ ### What it costs
293
+
294
+ Keeping a tree beside the DOM is not free, and the cases where it costs more
295
+ than it saves are the ones in which nothing could be kept. Measured in Chrome
296
+ 154 (2026-10-03) on a list of 2,000 rows, each change drawn and laid out,
297
+ against the adapter that drew everything again:
298
+
299
+ | | drawn again | patched |
300
+ | --- | --- | --- |
301
+ | one row's text changes | 5.0 ms | 0.9 ms |
302
+ | one row is added, or moved | 5.1 ms | 1.4 ms |
303
+ | every row's text changes | 7.2 ms | 4.9 ms |
304
+ | the first draw | 5.6 ms | 6.3 ms |
305
+ | the whole list reversed | 5.1 ms | 5.6 ms |
306
+ | every row's own props change | 5.3 ms | 6.7 ms |
307
+ | every row replaced by a new one | 5.2 ms | 6.8 ms |
308
+
309
+ So: a first draw costs about a tenth more, and a render that replaces
310
+ everything about a third more. Any render that keeps something costs less, and
311
+ the usual one — a little changed on a large page — a small fraction. What the
312
+ view holds does not grow with use: after 24,000 renders that each replaced a
313
+ whole list it held what it held after 3,000.
314
+
315
+ ### How it is held to that
316
+
317
+ `test/adapters/dom-retained.test.ts` asserts identity (`toBe`) and "never taken
318
+ off the page" (a `MutationObserver` over the root — an element removed and put
319
+ straight back is the same node and has still lost its scroll).
320
+ `test/adapters/dom-differential.test.ts` draws long runs of random trees and
321
+ holds the patched page, after every one, to a page drawn from nothing: the same
322
+ markup, the same dispatch from every press, and no write at all when the same
323
+ tree is drawn twice. Its kit has one component for each way of treating
324
+ children named above. A change to the adapter that lets a patched page drift
325
+ from a drawn one fails there, by seed.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,23 @@
1
1
  # @niscorp/nova
2
2
 
3
+ ## 0.1.3
4
+
5
+ ### Patch Changes
6
+
7
+ - 80e1ee8: Documentation: the packages are live, and releases are compatible. `STYLE_GUIDE.md` gains "The packages are live" — a release does not break an app that works on the one before it; what should go is deprecated and stays; a breaking change is a last resort that needs the maintainer's approval before it is written — and `AGENTS.md` points every agent changing nisc itself to it. The status lines that said "pre-1.0, breaking changes expected" (nova), "API is pre-1.0 and moves" (moss) and "everything else may move" (tide) now say the same. moss's deprecated `installedIntegrations` is no longer described as scheduled for removal: it stays on the type. The style guide's Node floor is corrected to 22.12, what every package's `engines` already says. No code changes.
8
+
9
+ ## 0.1.2
10
+
11
+ ### Patch Changes
12
+
13
+ - 633d0d1: The DOM adapter (`@niscorp/nova/adapters/dom`) keeps what did not change. `createDomView` used to empty its root and build the whole screen again on every render; it now keeps the tree it drew beside the DOM that tree produced and patches the page, so an element whose part of the tree is the same as before is the same DOM node, never taken off the page. Focus, scroll, a selection, an open `<details>`, a running animation and a timer a component started are kept, and one changed string costs one text node. A change in one instance or on one canvas leaves the others alone; keyed lists move their elements; a different instance in the same place is still all new. The first render still replaces markup drawn ahead of time, and now gives somebody already typing in it their words, caret and focus back by where the field sits rather than by its `ref`.
14
+
15
+ Fixed with it: typing in the second of two instances that share a `ref` moved focus (and the next keystroke) to the first; a bound field with no `ref` of its own lost focus after one keystroke; a pressed button lost focus to `<body>`; `debounce` did not coalesce across a render, and a pending value was not sent on blur.
16
+
17
+ A DOM kit keeps working unchanged if its components are functions of their props and children. `DomComponentContext` gains two things: `onRemove(cleanup)`, run once when the element leaves the page for good, and `dependsOnChildren()`, for a component that marks or counts the children it holds. What a kit should check is in ADAPTER.md, "The DOM adapter keeps what did not change": a component is no longer called because something else on the page changed, children are patched in place only under an element that holds exactly them, and data that changes often should arrive as children rather than as a prop.
18
+
19
+ - 45d6731: Three fixes. `{ reset: 'path' }` run as a step — in a trigger, an `onSuccess`, a lifecycle hook — now restores the path's initial value; it set the path to `undefined`, because steps never handed the mutation the initial snapshot. The same omission kept strict mode out of steps: on a strict shell a `push`/`pop`/`removeAt`/`move`/`clear` at a missing or wrong-typed path now reports a `MutationError` to `onError` (exported from the package root) instead of doing nothing. `shell.addCanvas({ mode: 'list' })` is a list canvas; `mode` was read only from `createShell`'s `canvases`. And an instance covered while its `mount` hook is still running stays suspended — `mount` set it back to `active` when the hook finished, leaving two active instances on a stack.
20
+
3
21
  ## 0.1.1
4
22
 
5
23
  ### Patch Changes