@niscorp/nova 0.5.2 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (180) hide show
  1. package/ACTION_DOCS.md +17 -10
  2. package/ADAPTER.md +22 -2
  3. package/CHANGELOG.md +116 -0
  4. package/DESIGN.md +36 -17
  5. package/I18N_DOCS.md +8 -3
  6. package/LAYOUT_DOCS.md +16 -4
  7. package/REACT_DOCS.md +3 -3
  8. package/README.md +22 -7
  9. package/SHELL_DOCS.md +10 -6
  10. package/dist/adapters/dom/components/index.cjs +46 -63
  11. package/dist/adapters/dom/components/index.cjs.map +1 -1
  12. package/dist/adapters/dom/components/index.d.cts +2 -2
  13. package/dist/adapters/dom/components/index.d.ts +2 -2
  14. package/dist/adapters/dom/components/index.js +11 -28
  15. package/dist/adapters/dom/components/index.js.map +1 -1
  16. package/dist/adapters/dom/index.cjs +10 -9
  17. package/dist/adapters/dom/index.d.cts +2 -2
  18. package/dist/adapters/dom/index.d.ts +2 -2
  19. package/dist/adapters/dom/index.js +8 -7
  20. package/dist/adapters/dom/server.cjs +9 -8
  21. package/dist/adapters/dom/server.cjs.map +1 -1
  22. package/dist/adapters/dom/server.d.cts +2 -2
  23. package/dist/adapters/dom/server.d.ts +2 -2
  24. package/dist/adapters/dom/server.js +8 -7
  25. package/dist/adapters/dom/server.js.map +1 -1
  26. package/dist/adapters/ink/index.js +49 -6
  27. package/dist/adapters/ink/index.js.map +1 -1
  28. package/dist/adapters/react/components/index.cjs +28 -27
  29. package/dist/adapters/react/components/index.d.cts +4 -4
  30. package/dist/adapters/react/components/index.d.ts +4 -4
  31. package/dist/adapters/react/components/index.js +9 -8
  32. package/dist/adapters/react/index.cjs +31 -30
  33. package/dist/adapters/react/index.d.cts +4 -4
  34. package/dist/adapters/react/index.d.ts +4 -4
  35. package/dist/adapters/react/index.js +9 -8
  36. package/dist/adapters/tty/components/index.cjs +35 -40
  37. package/dist/adapters/tty/components/index.cjs.map +1 -1
  38. package/dist/adapters/tty/components/index.d.cts +3 -2
  39. package/dist/adapters/tty/components/index.d.ts +3 -2
  40. package/dist/adapters/tty/components/index.js +6 -22
  41. package/dist/adapters/tty/components/index.js.map +1 -1
  42. package/dist/adapters/tty/index.cjs +11 -10
  43. package/dist/adapters/tty/index.cjs.map +1 -1
  44. package/dist/adapters/tty/index.d.cts +2 -2
  45. package/dist/adapters/tty/index.d.ts +2 -2
  46. package/dist/adapters/tty/index.js +9 -8
  47. package/dist/adapters/tty/index.js.map +1 -1
  48. package/dist/adapters/vue/components/index.cjs +28 -27
  49. package/dist/adapters/vue/components/index.d.cts +15 -12
  50. package/dist/adapters/vue/components/index.d.ts +15 -12
  51. package/dist/adapters/vue/components/index.js +9 -8
  52. package/dist/adapters/vue/index.cjs +37 -36
  53. package/dist/adapters/vue/index.cjs.map +1 -1
  54. package/dist/adapters/vue/index.d.cts +4 -4
  55. package/dist/adapters/vue/index.d.ts +4 -4
  56. package/dist/adapters/vue/index.js +10 -9
  57. package/dist/adapters/vue/index.js.map +1 -1
  58. package/dist/agent/index.d.cts +2 -2
  59. package/dist/agent/index.d.ts +2 -2
  60. package/dist/{chunk-57PZEPIK.js → chunk-2USXK2G4.js} +30 -9
  61. package/dist/chunk-2USXK2G4.js.map +1 -0
  62. package/dist/{chunk-RVU6YEHO.cjs → chunk-3TBQ2KGZ.cjs} +12 -12
  63. package/dist/chunk-3TBQ2KGZ.cjs.map +1 -0
  64. package/dist/{chunk-ZR54IVVS.cjs → chunk-67LZ6PTU.cjs} +21 -21
  65. package/dist/chunk-67LZ6PTU.cjs.map +1 -0
  66. package/dist/{chunk-QTJ4ZQRM.cjs → chunk-7BRC4PL4.cjs} +4 -3
  67. package/dist/chunk-7BRC4PL4.cjs.map +1 -0
  68. package/dist/{chunk-M2ZZUSH3.js → chunk-AXRTJAXB.js} +8 -8
  69. package/dist/chunk-AXRTJAXB.js.map +1 -0
  70. package/dist/chunk-BA77UJOE.cjs +21 -0
  71. package/dist/chunk-BA77UJOE.cjs.map +1 -0
  72. package/dist/{chunk-OY7SCFTJ.js → chunk-BRJ333QF.js} +138 -70
  73. package/dist/chunk-BRJ333QF.js.map +1 -0
  74. package/dist/{chunk-5T26T2EJ.cjs → chunk-F2DZ4JMO.cjs} +34 -14
  75. package/dist/chunk-F2DZ4JMO.cjs.map +1 -0
  76. package/dist/{chunk-A4GK3PLP.js → chunk-F2OEWTK6.js} +5 -5
  77. package/dist/chunk-F2OEWTK6.js.map +1 -0
  78. package/dist/chunk-GAWBA53C.js +20 -0
  79. package/dist/chunk-GAWBA53C.js.map +1 -0
  80. package/dist/{chunk-UIWTFU3M.cjs → chunk-J4HGCXLB.cjs} +49 -28
  81. package/dist/chunk-J4HGCXLB.cjs.map +1 -0
  82. package/dist/chunk-JAVBIVKK.js +27 -0
  83. package/dist/chunk-JAVBIVKK.js.map +1 -0
  84. package/dist/{chunk-VDB7VHFS.cjs → chunk-L63PCZNQ.cjs} +75 -60
  85. package/dist/chunk-L63PCZNQ.cjs.map +1 -0
  86. package/dist/{chunk-ITSVPZS5.cjs → chunk-LFKF2PMZ.cjs} +53 -29
  87. package/dist/chunk-LFKF2PMZ.cjs.map +1 -0
  88. package/dist/chunk-LMCCIFCH.js +15 -0
  89. package/dist/chunk-LMCCIFCH.js.map +1 -0
  90. package/dist/{chunk-E2PXYR3H.js → chunk-OT5M3N76.js} +43 -28
  91. package/dist/chunk-OT5M3N76.js.map +1 -0
  92. package/dist/{chunk-OWA5Z3WT.cjs → chunk-OWUKAB6M.cjs} +212 -144
  93. package/dist/chunk-OWUKAB6M.cjs.map +1 -0
  94. package/dist/{chunk-BML7HQPE.cjs → chunk-P6J3V26J.cjs} +7 -7
  95. package/dist/{chunk-BML7HQPE.cjs.map → chunk-P6J3V26J.cjs.map} +1 -1
  96. package/dist/{chunk-C63CBYD5.js → chunk-QERVED37.js} +4 -3
  97. package/dist/chunk-QERVED37.js.map +1 -0
  98. package/dist/{chunk-3XZODV7S.cjs → chunk-SB3MKJH2.cjs} +10 -7
  99. package/dist/chunk-SB3MKJH2.cjs.map +1 -0
  100. package/dist/{chunk-T33VE5XQ.js → chunk-SVL6SPO6.js} +28 -8
  101. package/dist/chunk-SVL6SPO6.js.map +1 -0
  102. package/dist/chunk-SYKWLQJZ.cjs +22 -0
  103. package/dist/chunk-SYKWLQJZ.cjs.map +1 -0
  104. package/dist/{chunk-G4OQ4PEO.js → chunk-WDTSKRH5.js} +19 -10
  105. package/dist/chunk-WDTSKRH5.js.map +1 -0
  106. package/dist/{chunk-CQZH3L3W.cjs → chunk-XBTAEOKJ.cjs} +51 -40
  107. package/dist/chunk-XBTAEOKJ.cjs.map +1 -0
  108. package/dist/{chunk-LAVCNLL3.js → chunk-Y4EE5XF3.js} +33 -9
  109. package/dist/chunk-Y4EE5XF3.js.map +1 -0
  110. package/dist/chunk-Y6DTXVKS.cjs +32 -0
  111. package/dist/chunk-Y6DTXVKS.cjs.map +1 -0
  112. package/dist/{chunk-GY3KNTNK.js → chunk-Y6UT7WA3.js} +3 -3
  113. package/dist/{chunk-GY3KNTNK.js.map → chunk-Y6UT7WA3.js.map} +1 -1
  114. package/dist/{chunk-6VHOMWNF.js → chunk-YMXFBHWZ.js} +8 -5
  115. package/dist/chunk-YMXFBHWZ.js.map +1 -0
  116. package/dist/devtools/index.cjs +8 -8
  117. package/dist/devtools/index.d.cts +2 -2
  118. package/dist/devtools/index.d.ts +2 -2
  119. package/dist/devtools/index.js +5 -5
  120. package/dist/document/index.cjs +4 -3
  121. package/dist/document/index.d.cts +4 -4
  122. package/dist/document/index.d.ts +4 -4
  123. package/dist/document/index.js +2 -1
  124. package/dist/examples/index.cjs +4 -4
  125. package/dist/examples/index.d.cts +2 -2
  126. package/dist/examples/index.d.ts +2 -2
  127. package/dist/examples/index.js +3 -3
  128. package/dist/{head-zznJvVEE.d.cts → head-HDTpptl2.d.cts} +2 -2
  129. package/dist/{head-CVjtToF8.d.ts → head-R4Jx_OVM.d.ts} +2 -2
  130. package/dist/i18n/index.cjs +13 -13
  131. package/dist/i18n/index.d.cts +2 -2
  132. package/dist/i18n/index.d.ts +2 -2
  133. package/dist/i18n/index.js +3 -3
  134. package/dist/index.cjs +69 -69
  135. package/dist/index.d.cts +6 -6
  136. package/dist/index.d.ts +6 -6
  137. package/dist/index.js +6 -6
  138. package/dist/migrations/index.cjs +4 -4
  139. package/dist/migrations/index.js +2 -2
  140. package/dist/{palette-CCxWSi3C.d.cts → palette-BTn4IRXK.d.cts} +1 -1
  141. package/dist/{palette-BZujb2rm.d.ts → palette-BmDclrlr.d.ts} +1 -1
  142. package/dist/{primitive-props-Cl5jiC8g.d.ts → primitive-props-BI8aHvma.d.cts} +1 -0
  143. package/dist/{primitive-props-Cl5jiC8g.d.cts → primitive-props-BI8aHvma.d.ts} +1 -0
  144. package/dist/reflect/index.cjs +23 -23
  145. package/dist/reflect/index.d.cts +2 -2
  146. package/dist/reflect/index.d.ts +2 -2
  147. package/dist/reflect/index.js +5 -5
  148. package/dist/{types-CJC8mnzl.d.ts → types-B5-GtEik.d.ts} +2 -0
  149. package/dist/{types-DOm2MKDk.d.ts → types-BEbjstbo.d.ts} +2 -1
  150. package/dist/{types-DzB3TAQj.d.cts → types-BLESXdu0.d.cts} +1 -1
  151. package/dist/{types-CWOom_fv.d.cts → types-C8OoE1EM.d.cts} +2 -1
  152. package/dist/{types-pbBIUNxw.d.ts → types-CbKiEDDH.d.ts} +1 -1
  153. package/dist/{types-D0x56Ya-.d.cts → types-CmIg-D2q.d.cts} +1 -1
  154. package/dist/{types-LXw2RJfH.d.ts → types-Lld1eifz.d.ts} +1 -1
  155. package/dist/{types-CR56luN7.d.cts → types-Wze4IlEM.d.cts} +2 -0
  156. package/package.json +7 -7
  157. package/dist/chunk-3XZODV7S.cjs.map +0 -1
  158. package/dist/chunk-57PZEPIK.js.map +0 -1
  159. package/dist/chunk-5T26T2EJ.cjs.map +0 -1
  160. package/dist/chunk-6VHOMWNF.js.map +0 -1
  161. package/dist/chunk-A4GK3PLP.js.map +0 -1
  162. package/dist/chunk-C63CBYD5.js.map +0 -1
  163. package/dist/chunk-CQZH3L3W.cjs.map +0 -1
  164. package/dist/chunk-E2PXYR3H.js.map +0 -1
  165. package/dist/chunk-G4OQ4PEO.js.map +0 -1
  166. package/dist/chunk-GQVJ5UAS.js +0 -8
  167. package/dist/chunk-GQVJ5UAS.js.map +0 -1
  168. package/dist/chunk-ITGR7P2B.cjs +0 -12
  169. package/dist/chunk-ITGR7P2B.cjs.map +0 -1
  170. package/dist/chunk-ITSVPZS5.cjs.map +0 -1
  171. package/dist/chunk-LAVCNLL3.js.map +0 -1
  172. package/dist/chunk-M2ZZUSH3.js.map +0 -1
  173. package/dist/chunk-OWA5Z3WT.cjs.map +0 -1
  174. package/dist/chunk-OY7SCFTJ.js.map +0 -1
  175. package/dist/chunk-QTJ4ZQRM.cjs.map +0 -1
  176. package/dist/chunk-RVU6YEHO.cjs.map +0 -1
  177. package/dist/chunk-T33VE5XQ.js.map +0 -1
  178. package/dist/chunk-UIWTFU3M.cjs.map +0 -1
  179. package/dist/chunk-VDB7VHFS.cjs.map +0 -1
  180. package/dist/chunk-ZR54IVVS.cjs.map +0 -1
package/ACTION_DOCS.md CHANGED
@@ -194,7 +194,9 @@ Remove an element at a specific index.
194
194
  { removeAt: 'items', index: 2 } // remove third
195
195
  ```
196
196
 
197
- The index can also be a template string (e.g. `"{{@event.payload}}"`) resolved before applying.
197
+ The index can also be a template string (e.g. `"{{@event.payload}}"`) resolved before applying. One that does not resolve to a whole number (a missing path, a fraction, a word) leaves the array as it is, and the steps after it run.
198
+
199
+ A negative index counts from the end, as in JavaScript's `splice`: `-1` removes the last element, and an index further back than the first element removes the first. An index computed as `-1` for "not found" therefore removes the last element: check the index before the step runs. An `index` template that resolves to a negative number is reported to `onError` (a `NovaError` with code `MUTATION_ERROR` naming the template) and then applied; a literal negative `index` is not reported. An index past the end removes nothing.
198
200
 
199
201
  ### `move`
200
202
 
@@ -205,7 +207,7 @@ Reorder an array element from one index to another.
205
207
  { move: 'items', from: '{{@event.payload}}', to: 0 }
206
208
  ```
207
209
 
208
- `from` / `to` accept a number or a template string resolved before applying. An out-of-range `from` is a no-op; `to` is clamped into range.
210
+ `from` / `to` accept a number or a template string resolved before applying. An out-of-range `from` is a no-op; `to` is clamped into range. A template that does not resolve to a whole number leaves the array as it is.
209
211
 
210
212
  ### `clear`
211
213
 
@@ -250,7 +252,7 @@ Invoke a named endpoint. Optional `onSuccess` and `onError` step branches run af
250
252
  }
251
253
  ```
252
254
 
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).
255
+ 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), and an older failure arriving late does not overwrite `errorTarget` (its `onError` steps still run). A failure that comes back while a newer call is still on its way is written, as before.
254
256
 
255
257
  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.
256
258
 
@@ -287,6 +289,8 @@ The `pop` effect uses `pop: true` (a literal boolean) to distinguish it from the
287
289
 
288
290
  `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.
289
291
 
292
+ A `push` (the effect or `shell.push`) to a canvas id the shell was not given creates that canvas. It is not in the shell layout: only a `CanvasSlot` naming it, or `getCanvasRenderTree`, shows it. Declare a canvas with `canvases` or `addCanvas`.
293
+
290
294
  `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.
291
295
 
292
296
  ### `popTo`, `resetTo`
@@ -361,7 +365,6 @@ endpoints: {
361
365
  method: 'POST',
362
366
  headers: {
363
367
  'content-type': 'application/json',
364
- 'authorization': 'Bearer {{$.token}}',
365
368
  },
366
369
  request: { name: { $ref: '$.user.name' }, email: { $ref: '$.user.email' } },
367
370
  target: 'savedUser',
@@ -375,7 +378,7 @@ endpoints: {
375
378
  - **`url`** *(required)* — template URL. Bindings work.
376
379
  - **`method`** *(required)* — `GET` | `POST` | `PUT` | `PATCH` | `DELETE`.
377
380
  - **`headers`** *(optional)* — object of header name → value. Values can be templated; names cannot.
378
- - **`request`** *(optional)* — a transform config run by the **injected evaluator** (see below) over the action data to build the request body. Static parts are literal; dynamic parts use the evaluator's ops. A string result is sent as-is; anything else is JSON-stringified. Declaring `request` without an injected transform is a hard error — never a silent empty body.
381
+ - **`request`** *(optional)* — a transform config run by the **injected evaluator** (see below) over the action data to build the request body. Static parts are literal; dynamic parts use the evaluator's ops. A string result is sent as-is; anything else is JSON-stringified. Declaring `request` without an injected transform is a hard error — never a silent empty body. Not on a `GET`: fetch sends no body with a GET, so every call of it fails; the shell reports such an endpoint to `onError` as a `DefinitionValidationError` when `createShell` or `registerAction` loads the definition, and loads it as given.
379
382
  - **`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.
380
383
  - **`target`** *(optional)* — data path to write the (possibly transformed) response into on success. If unset, the response is discarded.
381
384
  - **`errorTarget`** *(optional)* — data path to write the error info into on failure.
@@ -442,8 +445,8 @@ lifecycle: {
442
445
 
443
446
  ### When each fires
444
447
 
445
- - **`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.
446
- - **`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.
448
+ - **`mount`** — when the action is pushed onto a canvas (after `data` and `input` are merged, triggers attach and the instance is on its canvas, so a `push`, `pop` or `removeSelf` step in it acts from this instance; 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.
449
+ - **`suspend`** — when another action is pushed on top on a `stack` canvas, this action transitions from `active` → `suspended` once the hook has run. Triggers stay attached but do not fire while suspended. A `mode: 'list'` canvas suspends nothing. If the action is revealed (or removed) before its `suspend` hook finishes, it stays `active` (or `unmounted`).
447
450
  - **`resume`** — when the action above is popped, this action transitions from `suspended` → `active`. Runs after the re-run of `mount`.
448
451
  - **`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.
449
452
 
@@ -472,7 +475,7 @@ const modalFrame: ActionFragment = {
472
475
 
473
476
  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`.
474
477
 
475
- 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`.
478
+ On merge (`composeAction(action, fragments)`): each fragment's layout wraps the layout so far, filling its `{ slot: 'body' }` with it — the last fragment listed is the outermost, and a layout so far that is a layout id fills the slot with a `{ ref }` to it, so the slot renders the stored layout; a fragment whose `layout` is a layout 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`.
476
479
 
477
480
  ---
478
481
 
@@ -511,7 +514,7 @@ onError: [
511
514
  Fields available on `@error`:
512
515
  - `message: string`
513
516
  - `status: number` (HTTP status, or 0 for network/function errors)
514
- - `data: unknown` (the response body if any)
517
+ - `data: unknown` (the response body if any: parsed JSON, or the text of a body that is not JSON when the response offers `clone()`, as a real `Response` does; without `clone`, or when the host already read the body, a non-JSON body leaves `data` empty)
515
518
  - `timedOut?: boolean` (true if no reply arrived within the endpoint's wait)
516
519
 
517
520
  A call aborted by an unmount is silent: `onError` does not run, `errorTarget` is not written, and nothing is reported to telemetry.
@@ -553,10 +556,14 @@ Action-time errors all extend `NovaError`:
553
556
  - **`UnknownFragmentError`** — a `with: [...]` names a fragment the shell doesn't have
554
557
  - **`UnknownFunctionError`** — a `call` to a function endpoint whose `fn` isn't registered, with no `onError` branch, in strict mode
555
558
  - **`DefinitionValidationError`** — an action definition fails Zod validation at shell init
556
- - **`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
559
+ - **`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, except `clear`, which removes the key (see `clear` above)
557
560
 
558
561
  A runaway trigger chain is reported as a plain `NovaError` with code `RUNAWAY_CHAIN`.
559
562
 
563
+ In strict mode, a `call` outside a lifecycle hook that fails with no `onError` steps and no `errorTarget` to take it, or that names an endpoint the action does not have with no `onError` steps, is reported to `onError` as a plain `NovaError` with code `ENDPOINT_FAILED` (`endpoint 'save' failed: disk full`, `unknown endpoint: svae`). Nothing is thrown. In lax mode such a call stays silent.
564
+
565
+ In strict mode, a subscriber that throws (a runtime's `onDataChange` or `onStatusChange` handler, a shell's state, data or endpoint listener, a handler on a bus the shell created) is reported to `onError` as a plain `NovaError` with code `HANDLER_FAILED` and the thrown message. It is still caught: the other handlers run.
566
+
560
567
  `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.
561
568
 
562
569
  ---
package/ADAPTER.md CHANGED
@@ -110,7 +110,10 @@ Register two structural components under the core names `CANVAS_SLOT_NAME`
110
110
  and `ACTION_SLOT_NAME` — the shell's default layouts reference them:
111
111
 
112
112
  - **CanvasSlot** (`{ canvasId }`): renders that canvas's tree; nothing when
113
- `canvasId` is missing.
113
+ `canvasId` is missing. A `CanvasSlot` inside the canvas it names would draw
114
+ that canvas forever: carry the canvases open on the way down, and draw an
115
+ error node there instead (`RENDER_ERROR: canvas "<id>" is placed inside
116
+ itself`), as nova's adapters do.
114
117
  - **ActionSlot** (`{ instanceId }`): renders that instance's tree; nothing
115
118
  when `instanceId` is missing. Wrap the dispatch handed to the instance's
116
119
  subtree with core's `scopeDispatch(dispatch, instanceId)` so its UI events
@@ -180,6 +183,21 @@ or bound inputs drop keystrokes the moment the shell is remote:
180
183
  value on blur. The React, Vue, DOM and Ink adapters implement it — omitting it silently
181
184
  makes a served `debounce` a no-op in your terminal, so the same layout behaves
182
185
  differently across renderers.
186
+ - **Honour `replaceDraftOnWrite` on a `model`-bound node.** With
187
+ `props.replaceDraftOnWrite === true`, a focused field still ignores a new
188
+ tree value equal to one it dispatched since it was focused (its echo), but
189
+ any other change of the tree value replaces the in-progress value, drops a
190
+ pending debounced dispatch (which would write the old text back), and puts
191
+ the caret at the end. Keep the values the field dispatched; empty the list
192
+ when the field is focused, when a tree value equals the last of them, and
193
+ when a value replaces the draft. Only a change of the tree value counts: a
194
+ write that leaves the stored value as it was reaches no adapter. So without
195
+ `debounce` (each keystroke already stored) a `set` of the model path to
196
+ `""` clears the field, but with `debounce`, while the typing still waits and
197
+ the stored value is still `""`, the same `set` does nothing, and leaving the
198
+ field then dispatches the typing. Without the prop, the first obligation
199
+ stands as written. The React, Vue, DOM and Ink adapters implement it; the
200
+ React, Vue and DOM ones are tested, Ink's is not.
183
201
 
184
202
  These belong to *every* adapter because they are artifacts of the transport, not
185
203
  of taste — unlike styling, hover, or animation, which *should* differ per kit.
@@ -305,7 +323,9 @@ close it; nothing has needed one yet.
305
323
  element's, and stay with it. Once it is left, the next render shows the tree's
306
324
  value again (the kit is asked for the field afresh, because how a value is
307
325
  shown is the kit's business). A checkbox or a radio is not "typed in": the
308
- tree's answer shows at once.
326
+ tree's answer shows at once. A field with `replaceDraftOnWrite` takes a
327
+ value that is not an echo of what it dispatched into the same element while
328
+ it is typed in, with the caret at the end.
309
329
  - **A field that had to be built again while focused** (another of its props
310
330
  changed) is given what was being typed, the caret, and focus.
311
331
  - **Focus follows the element.** One that stayed has it still. One that was
package/CHANGELOG.md CHANGED
@@ -1,5 +1,121 @@
1
1
  # @niscorp/nova
2
2
 
3
+ ## 0.6.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 4b7d4a4: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on text such as `'$CAD only'` rendering empty, on such text not reaching `onPhraseMiss`, or wrote a condition that way: `{ if: '$count > 0', then, else }` (or a `$if: '$count > 0'` directive) with `count: 0` took `else` and now takes `then`, because the string is text, which is truthy.
8
+
9
+ A string that starts with `$` and a name followed by more words (`'$CAD only'`) is text: it renders as written, where it rendered empty, and, being text, is offered to the phrasebook (`onPhraseMiss` hears of it). Every path that resolved still resolves: `'$.x'` forms, `'$'` alone (the innermost scope), `'$USD'` (a path, empty when there is no `USD`), non-ASCII keys (`'$item.größe'`) and a path with trailing space. Only a data key with a space in it, read the `$name` way, is read differently.
10
+
11
+ - bf72478: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on `errorTarget.data` (or `@error.data`) being missing for a failed HTTP reply whose body is plain text. The message is unchanged. `FetchResponse` gains an optional `clone`.
12
+
13
+ A failed HTTP reply whose body is not JSON (`new Response('Service down for maintenance', { status: 503 })`) puts that text in `errorTarget.data` and `@error.data`, where `data` was missing: nova takes a copy of the response with `clone()` before reading it as JSON. A response without `clone` (a test fake), or one whose body the host already read, is read as before.
14
+
15
+ - e1db181: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on a fragment's slot showing the stored-layout id of the action it wraps as text.
16
+
17
+ A fragment around an action whose `layout` is a stored-layout id (`layout: 'invoice-body'`) renders the stored layout in its `{ slot: 'body' }`, where it rendered the id as text: `composeAction` fills the slot with `{ ref: 'invoice-body' }`, which the renderer resolves from the layout store. A fragment whose own layout is an id still replaces the layout composed so far. The fragment `layout` description says so.
18
+
19
+ - 241bd4d: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app builds a component list from the DOM or TTY kit's `registry.list()` and expects it without `CanvasSlot`.
20
+
21
+ The DOM and TTY kits' `defaultRegistry()` register `CanvasSlot`, so either kit works as the shell's registry, as the README shows: the default shell layout draws instead of `COMPONENT_NOT_FOUND: CanvasSlot`. Their walkers still draw a `CanvasSlot` themselves; the entry is there so the renderer accepts the name, as in the React and Vue kits. `registry.list()` of these two kits names one more component.
22
+
23
+ - 9f8e4b5: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on a late failure of an older call overwriting `errorTarget` after a newer call of the same endpoint already came back.
24
+
25
+ A failed call whose newer call of the same endpoint has already come back no longer writes `errorTarget`, the same rule a late success already follows for `target`. Search "a" (slow, fails), then "ab" (fast, succeeds): the rows show "ab" and the error stays empty, where the late failure wrote it. The call's `onError` steps still run. A failure that comes back while the newer call is still on its way is written, as before.
26
+
27
+ - 1b615d6: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a layout inside a loop writes through `model: '$.<as>.…'`, `'$.items'` or `'$.index'` and relied on the write landing on a root key of that name.
28
+
29
+ Inside a loop, a `model` written with `$.` writes where it reads: `model: '$.line.qty'` (with `as: 'line'`) writes the row it shows (`lines.0.qty`), where it wrote a root `line.qty` that no field shows. `model: '$.index'` binds nothing, as `model: '$index'` already did, where it wrote a root `index` while showing the loop index. A nested loop over `$.<as>.…` (`for: '$.g.items'` inside `for: '$.groups', as: 'g'`) binds its models into each group (`groups.1.items.0.v`), where every group bound `g.items.0.v`. What every layout shows is unchanged.
30
+
31
+ - e7edd95: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app reads `model.ref` from the render tree of a model-bound field that has its own `ref` inside a loop, and expects it to equal that `ref`; dispatching `ui:model` with the render tree's `model.ref`, as every kit does, keeps working.
32
+
33
+ A model-bound field with a `ref` inside a loop (`for: '$.lines', as: 'line', do: { component: 'Input', ref: 'qty', model: '$line.qty' }`) writes what is typed into its own row, where every row wrote the last one. Its render node's `model.ref` is `qty@lines.0.qty` (one per row, the same however many rows there are); its `ref` stays `qty`. Triggers on `ref: 'qty'` fire for every row and see `@event.ref` as `qty`, and a `ui:model` an app dispatches with `ref: 'qty'` still writes the last row. The longer name shows wherever a model ref is shown: adapters, devtools, the TTY command list, and the render trees moss sends to terminals.
34
+
35
+ - 0a46ff6: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on a mount hook's navigation acting from the instance below, on `getState`/`getCanvasState` leaving out an instance whose mount hook is running (a data-change listener that looks the instance up now finds it for the input written at mount), or on the first state snapshot after a push leaving it out.
36
+
37
+ A pushed (or replacing) instance is on its canvas, with its birth, origin and key recorded, before its `mount` hook starts. A `push`, `pop` or `removeSelf` step that runs at the start of a mount hook now acts from that instance: `push` lands above it, `removeSelf` and `pop` close it. A mount hook that pushes onto another canvas fires a first state snapshot that already shows the new instance on its own canvas.
38
+
39
+ A `suspend` whose hook finishes after the action was revealed again (a push and a pop before the suspend ended) or removed no longer sets `suspended`: the action on top stays `active` and its triggers fire.
40
+
41
+ - 59f314a: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app computes a negative `removeAt` index on purpose and does not want `onError` called for it; the data changes exactly as before.
42
+
43
+ A `removeAt` step whose `index` is a template that resolves to a negative number (`index: '{{$.found}}'` with `found = -1`, a search's "not found") is reported to `onError` as a `NovaError` with code `MUTATION_ERROR` (`removeAt: index {{$.found}} resolved to -1, …`), in strict and lax mode, and then applied as before: `-1` still removes the last element. A literal negative `index` is a deliberate "from the end" and is not reported.
44
+
45
+ The report never changes what runs: an `onError` that throws for it does not stop the step, the push or the next handler.
46
+
47
+ - 281108e: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app reads `constructor`, `toString`, `__proto__` or another name every object inherits through a binding (`{{$.x.constructor}}`), which now gives `undefined`.
48
+
49
+ One rule for names a record inherits: what it inherits from a prototype of its own counts, what every object inherits from `Object.prototype` does not. A `functions`, `endpoints`, phrasebook or reconcilers object made with `Object.create(base)` or as a class instance resolves the names it inherits, as in the last release. A data path no longer reads `Object.prototype`'s members: `$.x.constructor` is `undefined` where it rendered `function Object() { [native code] }`. A getter on a class the data carries still reads, and an endpoint with `fn: 'toString'` still fails as an unknown function.
50
+
51
+ - 7aef6a7: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app hands `NovaShell` or `NovaCanvas` a registry with no `CanvasSlot` and relied on React's `Text`, `Stack`, `Input`, `Button`, `Box`, `Panel`, `JsonTree` or `ActionSlot` replacing its own.
52
+
53
+ `NovaShell` and `NovaCanvas`, handed a registry with no `CanvasSlot`, add only the default React components the registry does not have, and replace none it has. The Ink kit's registry keeps Ink's `Text` and gets `CanvasSlot`. A registry that has `CanvasSlot` is untouched, as before.
54
+
55
+ - 79cf65c: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on a field with `model: '{{…}}'`, or inside a loop with `for: '{{…}}'`, writing nothing when typed into.
56
+
57
+ A `model` written as a single template (`model: '{{$.q}}'`) binds like the bare path, and a loop whose `for` is a single template (`for: '{{$.lines}}'`) keeps the bindings of the `model`s inside it: such fields write what is typed, and their render nodes carry `model` and `value`, where they bound nothing.
58
+
59
+ - e828562: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app runs its shell with `strict: true` and does not want `onError` called for failed calls nothing takes. Lax shells (the default) are unchanged. The exported `ErrorCode` type gains `'ENDPOINT_FAILED'`.
60
+
61
+ In strict mode, a `call` outside a lifecycle hook that fails with no `onError` steps and no `errorTarget`, or names an endpoint the action does not have with no `onError` steps, is reported to the shell's `onError` as a `NovaError` with the new code `ENDPOINT_FAILED` (`ErrorCodes.endpointFailed`). Nothing is thrown that was not thrown before; an unknown function still raises `UnknownFunctionError` in strict mode, and a lifecycle hook still raises `LifecycleError`.
62
+
63
+ The report never changes what runs: an `onError` that throws for it does not stop the step, the push or the next handler.
64
+
65
+ - 6b01a50: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app runs its shell with `strict: true` and does not want `onError` called for subscribers that throw. Lax shells (the default) and buses an app hands in are unchanged. The exported `ErrorCode` type gains `'HANDLER_FAILED'`.
66
+
67
+ In a strict shell, a subscriber that throws is reported to the shell's `onError` as a `NovaError` with the new code `HANDLER_FAILED` (`ErrorCodes.handlerFailed`) and the thrown message: `onStateChange`, `onDataChange` and `onEndpoint` listeners, handlers on the event and message bus the shell created itself, and each runtime's data and status subscribers. The throw is still caught, and the other handlers and the push or write that fired them go on.
68
+
69
+ The report never changes what runs: an `onError` that throws for it does not stop the step, the push or the next handler.
70
+
71
+ - 6eef458: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app's translations contain `$$`, `$&`, `` $` ``, `$'` or `$1` and relied on them being read as replacement patterns on text with spaces around it.
72
+
73
+ A translation applied to text with spaces around it goes in as written: "Price in dollars " with the translation "Preis in US$$" renders "Preis in US$$ ", where it rendered "Preis in US$ ". The same translation already rendered as written on text without spaces.
74
+
75
+ ### Patch Changes
76
+
77
+ - b233463: `LayoutStore.resolveReferences` on a stored layout that refers to itself returns, leaving the inner `{ ref }` for the renderer, instead of overflowing the stack.
78
+
79
+ A canvas placed inside itself (a `CanvasSlot` naming the canvas it sits in) draws `RENDER_ERROR: canvas "<id>" is placed inside itself` where it comes back, in the TTY, DOM, React and Vue adapters, instead of overflowing the stack or running out of memory.
80
+
81
+ A `GET` endpoint with a `request` body, which fetch refuses on every call, is reported to `onError` as a `DefinitionValidationError` by `createShell` and `registerAction`; the definition still loads as before.
82
+
83
+ A bound `Input` takes `replaceDraftOnWrite: true`: while it is focused, a change of the value at its model path, other than an echo of a value it dispatched since it was focused, replaces what is typed and drops a pending debounced dispatch, in the DOM, React, Vue and Ink adapters (Ink's is not covered by a test). A write that leaves the stored value as it was changes nothing. Without the prop, a focused field keeps what is typed, as before.
84
+
85
+ Docs say what the code does: the event bus does not validate events; in lax mode `clear` on a missing or wrong-typed path removes the key; a negative `removeAt` index counts from the end; a push to an undeclared canvas creates a canvas the shell layout does not show; `removeAction` on a list canvas re-runs the mount and resume hooks of the card left last; inside a loop `$.index`, `$.items` and `$.<as>` read the loop's values, a lone `$` is the innermost scope, and `'$USD'` is a path. The endpoint example no longer sends a bearer token from action data.
86
+
87
+ - e2b9595: A name every object inherits (`toString`, `constructor`, `valueOf`) is no longer found as an action, fragment, endpoint, function, phrase, slot or directive; a removeAt or move index template that is no whole number leaves the array alone and the next steps run; a stored layout that comes back to itself renders a clear `RenderError` instead of overflowing the stack. An actions or fragments map keyed by something other than the id is now reported to `onError` (the shell still loads it), and the README lists what each adapter kit ships.
88
+ - Updated dependencies [48138de]
89
+ - Updated dependencies [da3037e]
90
+ - Updated dependencies [e957628]
91
+ - Updated dependencies [c30562a]
92
+ - Updated dependencies [efd2368]
93
+ - Updated dependencies [ca26810]
94
+ - Updated dependencies [800a541]
95
+ - Updated dependencies [9c5367b]
96
+ - Updated dependencies [322f241]
97
+ - Updated dependencies [a41edf9]
98
+ - Updated dependencies [eb4ffb9]
99
+ - Updated dependencies [ae647e8]
100
+ - Updated dependencies [2effb54]
101
+ - Updated dependencies [bd996ea]
102
+ - Updated dependencies [180787b]
103
+ - Updated dependencies [d53910e]
104
+ - Updated dependencies [276f457]
105
+ - Updated dependencies [413afbd]
106
+ - Updated dependencies [1f6d37d]
107
+ - Updated dependencies [d77baf9]
108
+ - Updated dependencies [3f92c52]
109
+ - Updated dependencies [841c010]
110
+ - Updated dependencies [d93170b]
111
+ - Updated dependencies [61b15e4]
112
+ - Updated dependencies [7e8f6d4]
113
+ - Updated dependencies [5c52ef5]
114
+ - Updated dependencies [66eb934]
115
+ - @niscorp/cortex@0.2.0
116
+ - @niscorp/prism@0.4.0
117
+ - @niscorp/strata@0.2.0
118
+
3
119
  ## 0.5.2
4
120
 
5
121
  ### Patch Changes
package/DESIGN.md CHANGED
@@ -104,16 +104,18 @@ Resolution rules:
104
104
  - **String, sole `{{ expr }}`** → returns the raw resolved value (preserves
105
105
  type — number stays number, object stays object).
106
106
  - **String, `"text {{expr}} text"`** → string interpolation.
107
- - **String, bare `"$.path"` or `"$item.field"`** → raw resolved value.
107
+ - **String, bare `"$.path"` or `"$item.field"`** → raw resolved value. A
108
+ `$` name followed by more words (`"$CAD only"`) is text.
109
+ - **String, bare `@event…` / `@error…`** → raw resolved value, where that scope
110
+ is present (a trigger's steps, an `onError` list).
108
111
  - **String, anything else** → returned literally.
109
- - **Object `{ $if, $then, $else }`** → conditional. The only directive form.
110
- `$else` is optional.
112
+ - **Object with a directive key** → the directive: `{ $if, $then, $else }` is a
113
+ conditional (`$else` optional), `{ $eq: [a, b] }` strict equality,
114
+ `{ $exists: x }` whether `x` resolves to anything but undefined (null
115
+ counts), `{ $at: [array, index, field?] }` an element or one field of it,
116
+ `{ $prism: node }` a Prism node evaluated against the innermost scope.
111
117
  - **Array** → walked recursively.
112
- - **Plain object** → walked recursively.
113
-
114
- The previous `BindingSchema` value-form objects (`{ template: ... }`,
115
- `{ if, then, else }`) **no longer exist**. The unified resolver replaced
116
- them.
118
+ - **Any other object** → walked recursively.
117
119
 
118
120
  Scope chains are arrays of records, innermost first. `createScopeChain(data)`
119
121
  returns `[data]`. Loops push a new scope on the front (`{ [as]: item }`).
@@ -128,8 +130,10 @@ runtime writes to it, the layout renderer reads from it via a narrow
128
130
 
129
131
  ### `shared/event-bus/`
130
132
 
131
- Topic-based pub/sub. Validates events against `NovaEventSchema` before
132
- dispatch. Used for ambient UI events such as `ui:model`. Handlers receive
133
+ Topic-based pub/sub. It does not validate events: a host that takes events
134
+ from outside parses them with `NovaEventSchema` before it emits them (moss
135
+ does, where a terminal's events arrive). Used for ambient UI events such as
136
+ `ui:model`. Handlers receive
133
137
  typed `NovaEvent` payloads. Subscriptions return cleanup functions.
134
138
 
135
139
  ### `shared/message-bus/`
@@ -141,6 +145,14 @@ Trigger configs with a `message` field bind to this bus.
141
145
  The two buses are **independent**. The previous `msg:<channel>` prefix
142
146
  bridge through the event bus is gone.
143
147
 
148
+ A handler that throws never breaks a bus or a store: the event bus, the
149
+ message bus and the data store catch it and go on to the next handler.
150
+ `createEventBus`, `createMessageBus` and `createDataStore` take an optional
151
+ `{ onHandlerError }` that is handed what was caught. A strict shell wires it
152
+ to its `onError` (code `HANDLER_FAILED`) for the buses it creates itself,
153
+ its telemetry, and each runtime's data store and status subscribers; a bus
154
+ the app hands in is left as it is, and a lax shell reports nothing.
155
+
144
156
  ### `shared/ids.ts`, `shared/common.ts`
145
157
 
146
158
  `createIdFactory(prefix)` for instance/shell ids; small type guards
@@ -299,7 +311,10 @@ every response lands as before and none is followed.
299
311
 
300
312
  When the layout author writes `model: "$.user.name"` on a component, the
301
313
  renderer emits `model: { ref, path: 'user.name' }` on the
302
- `RenderComponentNode`. After every render, the runtime reconciles its
314
+ `RenderComponentNode`. A field with a `ref` bound through a loop name
315
+ gets the per-row model ref `<ref>@<path>`; the runtime maps it to its
316
+ row, maps the written `ref` to the last row as before, and hands
317
+ triggers the event with the written `ref`. After every render, the runtime reconciles its
303
318
  `ui:model` event-bus listeners against the live set of model refs:
304
319
 
305
320
  - New ref → install a listener that, on `ui:model` events for that ref,
@@ -472,8 +487,10 @@ that spawns:
472
487
  - **layout** — `fillSlots(fragment.layout, { body: action.layout })`: the
473
488
  fragment is the outer chrome, the action's own layout is dropped into the
474
489
  fragment's `{ slot: 'body' }` node. The fragment wraps; the action is the
475
- innermost content. Multiple fragments fold in array order (last listed is
476
- outermost). An unfilled slot renders nothing.
490
+ innermost content. An action layout that is a layout id goes into the
491
+ slot as `{ ref: id }`, so the renderer draws the stored layout there.
492
+ Multiple fragments fold in array order (last listed is outermost). An
493
+ unfilled slot renders nothing.
477
494
  - **data / endpoints** — shallow-merge, **action wins** on conflict.
478
495
  - **triggers** — concat, fragment's first (so a fragment's `close`/`cancel`
479
496
  and the action's `confirm` coexist; authors keep refs distinct).
@@ -502,12 +519,14 @@ work (v1 fills one `body` slot with the action's `layout`).
502
519
  4. `spawn` calls `buildRuntime` → `createActionRuntime`. The runtime
503
520
  builds its data store from `definition.data` merged with `input`,
504
521
  creates an `AbortController`, registers triggers.
505
- 5. `runtime.mount(input)` is fired and not awaited. It runs the
522
+ 5. `spawn` pushes the new instance onto the canvas and records its
523
+ birth, origin and key, so a mount hook that navigates (`push`,
524
+ `pop`, `removeSelf`) finds its own instance on top.
525
+ 6. `runtime.mount(input)` is fired and not awaited. It runs the
506
526
  `mount` lifecycle hook via `runLifecycleHook`, then transitions to
507
527
  `active`. Failures route through the strict/lax pipeline.
508
- 6. The new instance is pushed onto the canvas; `fireState()` notifies
509
- state subscribers.
510
- 7. The adapter (when one exists) calls `runtime.render()` which returns
528
+ 7. `fireState()` notifies state subscribers.
529
+ 8. The adapter (when one exists) calls `runtime.render()` which returns
511
530
  `RenderNode[]`. The runtime reconciles model bindings against the
512
531
  produced tree.
513
532
 
package/I18N_DOCS.md CHANGED
@@ -116,14 +116,19 @@ string.
116
116
  rule, where a query manufactures a word and a read puts it on screen. There the
117
117
  key is what protects data.
118
118
 
119
- A string is a binding (`isBinding`) when it is `$` alone or starts with `$`
120
- followed by `.`, a letter or `_`, when it starts with `@` followed by a letter or
121
- `_` (an extra scope such as `@event.payload.id`), or when it holds `{{`.
119
+ A string is a binding (`isBinding`) when it is `$` alone, starts with `$.`, or
120
+ is `$` followed by a letter or `_` and no space before its end (so `'$CAD only'`
121
+ is a phrase), when it starts with `@` followed by a letter or `_` (an extra
122
+ scope such as `@event.payload.id`), or when it contains `{{`.
122
123
 
123
124
  A phrase (`isPhrase`) is a non-blank string that is not a binding and holds at
124
125
  least one letter. Only a phrase is harvested, looked up in the book or reported
125
126
  as a miss: `12`, `100%` and `—` never are.
126
127
 
128
+ A phrase with spaces around it (`'Total '`) is looked up as itself first and
129
+ then trimmed; a translation found for the trimmed text goes in between the same
130
+ spaces, as written: `$$`, `$&` or `$1` in a translation render as they are.
131
+
127
132
  ## Counted phrases
128
133
 
129
134
  A dictionary can hold "Standing". It can never hold "12 of 20" — two numbers
package/LAYOUT_DOCS.md CHANGED
@@ -78,7 +78,7 @@ The most common one. References a component by name; the registry supplies the i
78
78
  - **`component`** *(required)* — the registry name. Must match a name passed to `registry.register(name, ...)`.
79
79
  - **`props`** *(optional)* — an object of props. **Every value is a binding** — strings starting with `$` are resolved as paths, strings with `{{...}}` are interpolated, plain values pass through. See [Bindings](#bindings).
80
80
  - **`children`** *(optional)* — a single `LayoutNode` or an array of them. Components decide how to render their children slot.
81
- - **`ref`** *(optional)* — a stable identifier. Used by triggers (`event: 'ui:click', ref: 'header-stack'`) and as the model binding key. If unset, the renderer auto-generates one for model-bound components.
81
+ - **`ref`** *(optional)* — a stable identifier. Used by triggers (`event: 'ui:click', ref: 'header-stack'`) and as the model binding key. If unset, the renderer auto-generates one for model-bound components. Inside a loop, a model-bound field with a `ref` gets the model ref `<ref>@<path>` (`qty@lines.0.qty`), one per row; its `ref` stays as written, and triggers on that ref still fire for every row.
82
82
  - **`model`** *(optional)* — two-way binding path. See [Two-way binding](#two-way-binding).
83
83
  - **`events`** *(optional)* — a record of event name → configuration. The schema accepts it; the renderer does not read it and it does not reach the `RenderNode`. Interaction is `ref` + an action trigger.
84
84
 
@@ -219,6 +219,7 @@ store.set('user-card', {
219
219
 
220
220
  - The referenced layout sees the **current scope** at the call site. Inside a loop, a `LayoutRef` reads from the loop variable just like an inline layout would.
221
221
  - If the ref doesn't resolve, the renderer throws `LayoutRefNotFoundError`. In lax mode it's caught and replaced with an error RenderNode; in strict mode it propagates.
222
+ - A layout may refer to itself further down its data: a `tree` layout that loops over `$node.children` with `{ ref: 'tree' }` inside renders each level with `$node` bound to a child. A ref reached again where every binding reads what it read the last time the ref was entered would render the same thing forever: a layout `x` whose only child is `{ ref: 'x' }`, `x` → `y` → `x`, or `x` looping over `$.items` with `{ ref: 'x' }` inside. The renderer throws a `RenderError` naming the refs, `Layout ref "x" comes back to itself: x → y → x`, handled as any render error.
222
223
 
223
224
  ---
224
225
 
@@ -271,11 +272,16 @@ A string starting with `$.` reads a value from the data object.
271
272
 
272
273
  The raw value is returned with its type preserved — numbers stay numbers, arrays stay arrays.
273
274
 
275
+ A path reads what a value has, or inherits from a prototype of its own (a getter on a class the data carries, `$.person.fullName`), and never what every object inherits: `$.x.constructor`, `$.x.toString` and `$.x.__proto__` are `undefined`.
276
+
274
277
  **Path forms:**
275
- - `$.foo.bar` — start from the data root, walk `foo` then `bar`
278
+ - `$.foo.bar` — start from the data root, walk `foo` then `bar`. Inside a loop, the loop's own names come first: `$.index`, `$.items` and `$.<as>` read the loop's values, not root keys of those names
276
279
  - `$foo` — read variable `foo` from the closest enclosing scope (loop variable, etc.)
277
280
  - `$foo.bar` — read variable `foo`, walk `bar` on it
278
281
  - `$index` — special: the loop iteration index
282
+ - `$` alone — the whole innermost scope: the data root, or inside a loop the loop's own `{ <as>, index, items }`
283
+
284
+ A string that starts with `$` and then a letter or `_`, with no space before its end, is a path, never text: `'$USD'` reads a key `USD` and renders empty when there is none. When more words follow the name, it is text: `'$CAD only'` renders as written (and is offered to the phrasebook like other text). As a condition such text is truthy: `if: '$count > 0'` (or `$if:`) is not a comparison and always takes `then`; compare with `{ $prism: … }`. A label that is only a `$` word comes from data or a binding (`'{{$.label}}'`).
279
285
 
280
286
  ### 2. Template strings
281
287
 
@@ -349,6 +355,8 @@ Set `model: '<path>'` on a component to wire it for two-way data binding. The re
349
355
  }
350
356
  ```
351
357
 
358
+ A `model` (and the `for` of a loop around it) written as one template, `'{{$.draftName}}'`, binds the same as the bare path.
359
+
352
360
  The `Input` component built into `@niscorp/nova/adapters/react/components` already dispatches `ui:model` on change, so this just works. To wire your own component, see `REACT_DOCS.md`.
353
361
 
354
362
  ### Loop case
@@ -365,6 +373,8 @@ The `Input` component built into `@niscorp/nova/adapters/react/components` alrea
365
373
 
366
374
  Type into the second input → `data.items[1].value` updates → re-render shows the new value.
367
375
 
376
+ `model: '$.item.value'` binds the same way: inside a loop, `$.` looks in the loop's own names (`index`, `items` and the `as` name) first, for writing as for reading. `model: '$.index'` and `model: '$index'` bind nothing — the loop index has no place in the data. Any other `$.name` is the data root's.
377
+
368
378
  ---
369
379
 
370
380
  ## Render context
@@ -391,7 +401,7 @@ When `strict: false` (the default), errors during rendering are caught at each s
391
401
 
392
402
  - **`ComponentNotFoundError`** — `node.component` isn't registered.
393
403
  - **`LayoutRefNotFoundError`** — `node.ref` isn't in the layout store.
394
- - **`RenderError`** — anything else thrown during render (binding resolution, etc.).
404
+ - **`RenderError`** — a layout ref that comes back to itself with every binding reading as before, and anything else thrown during render (binding resolution, etc.).
395
405
 
396
406
  All extend `NovaError` (see `DESIGN.md`).
397
407
 
@@ -467,7 +477,7 @@ If a component carries a static `.meta` property, `registerAll` picks it up auto
467
477
 
468
478
  - **`Stack`** — flex container with `direction`, `gap`, `align`, `justify`, `padding`, `wrap`
469
479
  - **`Text`** — typography element with `as`, `size`, `weight`, `color`
470
- - **`Input`** — text input bound via `model`; holds a local draft while focused and honours a `debounce` prop (ms) on `ui:model` dispatches
480
+ - **`Input`** — text input bound via `model`; while focused it shows a local draft of what is typed, and it honours a `debounce` prop (ms) on `ui:model` dispatches; with `replaceDraftOnWrite: true`, a change of the value at its model path while it is focused, other than an echo of what it dispatched, replaces what is typed (a write that leaves the stored value as it was changes nothing: see ADAPTER.md §6)
471
481
  - **`Button`** — clickable button that dispatches `ui:click` with its `ref`
472
482
  - **`Box`** — generic styling container
473
483
  - **`Panel`** — titled container with optional `backRef`/`closeRef` header buttons
@@ -492,6 +502,8 @@ store.list(); // → array of stored ids
492
502
  store.resolveReferences(layout); // → the layout with every { ref } it can resolve inlined
493
503
  ```
494
504
 
505
+ `resolveReferences` expands without data, so a `{ ref }` met again inside its own expansion (a tree whose rows use the same layout) is left as `{ ref }`; the renderer resolves it row by row.
506
+
495
507
  `set` validates the layout against `LayoutNodeSchema` and throws `DefinitionValidationError` if it doesn't parse. So you can't accidentally store an invalid layout.
496
508
 
497
509
  ---
package/REACT_DOCS.md CHANGED
@@ -140,8 +140,8 @@ Three components that hide the registry/provider/render-tree wiring. Each is als
140
140
  ```
141
141
 
142
142
  - **`<Nova.Layout>`** — `layout` (a `LayoutNode` or a layout-store id), `data?`, `components?` (registered after the builtins), `registry?` / `store?` (pre-built; with `registry`, `components` and `builtins` are ignored), `builtins?` (default `true`), `strict?`, `onError?`, and the i18n fields `phrases?` / `phraseKeys?` / `onPhraseMiss?` (see `I18N_DOCS.md`). Renders through a `NovaRenderProvider` with no-op dispatch. A `layout` given as an id is read from `store`, so pass the `store` that holds it; an id it does not hold renders nothing.
143
- - **`<Nova.Shell>`** — `shell`, `registry?` (default `shell.registry`), `slotWrapper?`, `builtins?` (default `true`: registers the default component set on the registry if `CanvasSlot` is missing). Renders the shell's canvasLayout.
144
- - **`<Nova.Canvas>`** — `id`, plus optional `shell`, `registry?`, `builtins?`. With `shell` it provides its own `NovaShellProvider`; without, it must sit inside one. Renders that canvas's actionLayout.
143
+ - **`<Nova.Shell>`** — `shell`, `registry?` (default `shell.registry`), `slotWrapper?`, `builtins?` (default `true`: if `CanvasSlot` is missing, adds the default components the registry does not have, and replaces none it has). Renders the shell's canvasLayout.
144
+ - **`<Nova.Canvas>`** — `id`, plus optional `shell`, `registry?`, `builtins?` (as for `<Nova.Shell>`). With `shell` it provides its own `NovaShellProvider`; without, it must sit inside one. Renders that canvas's actionLayout.
145
145
 
146
146
  ---
147
147
 
@@ -341,7 +341,7 @@ registerNovaReactComponents(registry);
341
341
  // Now Stack, Text, Input, Button, Box, Panel, JsonTree, CanvasSlot, ActionSlot are all registered.
342
342
  ```
343
343
 
344
- `Input` is remote-safe: while focused it holds a local draft the incoming tree never overwrites, and a `debounce` prop (ms) coalesces `ui:model` dispatches, flushing on blur. See ADAPTER.md §6.
344
+ `Input` is remote-safe: while focused it shows a local draft the incoming tree never overwrites, and a `debounce` prop (ms) coalesces `ui:model` dispatches, flushing on blur. With `replaceDraftOnWrite: true`, a change of the value at its model path while it is focused, other than an echo of a value it dispatched, replaces the draft and drops a pending debounced dispatch. A write that leaves the stored value as it was changes nothing, so with `debounce` a `set` to `""` while the typing still waits and the stored value is still `""` does not clear the field. See ADAPTER.md §6.
345
345
 
346
346
  `CanvasSlot` and `ActionSlot` are shell-aware: they pull state from the React shell context and must only be used inside a `<NovaShellProvider>` (they are what shell/canvas layouts use to paint their regions).
347
347
 
package/README.md CHANGED
@@ -29,12 +29,24 @@ no terminal. What consumes that tree is an adapter, and five ship here:
29
29
  | `adapters/tty` | any terminal, line REPL | every interactive carries a `[n]` marker — type the number |
30
30
  | `adapters/ink` | any terminal, full-screen | the same `[n]` markers, plus focus and live typing |
31
31
 
32
- Same trees down, same `ui:click` / `ui:model` / `ui:key` events up — an app
33
- renders in all five without changing a line, and a served host (see
34
- `@niscorp/moss`) cannot tell them apart. The TTY numbering is computed once
35
- and shared: `[7]` is the same interactive in the REPL and the TUI.
36
-
37
- An adapter is a walker plus a component kit of ~15 domain-blind primitives.
32
+ Same trees down, same `ui:click` / `ui:model` / `ui:key` events up — every
33
+ walker takes the same tree, and a served host (see `@niscorp/moss`) cannot
34
+ tell them apart. The TTY numbering is computed once and shared: `[7]` is the
35
+ same interactive in the REPL and the TUI.
36
+
37
+ An adapter is a walker plus a component kit of domain-blind primitives. The
38
+ kits differ in what they ship, so an app renders unchanged in an adapter when
39
+ every component name it uses is in that kit or registered by the app; a name
40
+ the registry lacks draws a `COMPONENT_NOT_FOUND` marker.
41
+
42
+ | kit | components |
43
+ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
44
+ | `adapters/react/components`, `adapters/vue/components` | Stack, Text, Input, Button, Box, Panel, JsonTree, CanvasSlot, ActionSlot (9) |
45
+ | `adapters/dom/components` | Box, Row, Stack, Grid, Text, Button, Input, Textarea, Checkbox, Table, Panel, JsonTree, CanvasSlot, ActionSlot; Select (an Input), Switch (a Checkbox) |
46
+ | `adapters/tty/components` | the DOM kit's names plus Badge |
47
+ | `adapters/ink` | the TTY kit's names but CanvasSlot, with Textarea an Input |
48
+
49
+ The DOM and TTY walkers draw a `CanvasSlot` themselves; their kits register the name so the renderer accepts it, and either kit works as the shell's registry.
38
50
  [ADAPTER.md](ADAPTER.md) is the whole contract; the terminal adapters' APIs
39
51
  are in [TERMINAL_DOCS.md](TERMINAL_DOCS.md); a Svelte or react-native
40
52
  adapter is a sibling folder, built the way the Vue one is.
@@ -387,7 +399,10 @@ configured path.
387
399
 
388
400
  `model` paths inside loops are resolved to **absolute** paths
389
401
  (`items.0.value`) by the renderer using its scope-path tracker, so
390
- loop items round-trip correctly.
402
+ loop items round-trip correctly. A field with its own `ref` inside a
403
+ loop gets a model ref per row, `<ref>@<path>` (`qty@lines.0.qty`), so
404
+ each row writes its own path; its `ref`, and the ref a trigger matches
405
+ and `@event.ref` reads, stay `qty`.
391
406
 
392
407
  ---
393
408