@niscorp/nova 0.3.0 → 0.4.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 (226) hide show
  1. package/ACTION_DOCS.md +3 -1
  2. package/ADAPTER.md +19 -1
  3. package/CHANGELOG.md +33 -0
  4. package/DESIGN.md +9 -6
  5. package/I18N_DOCS.md +18 -3
  6. package/REACT_DOCS.md +4 -2
  7. package/README.md +94 -4
  8. package/SHELL_DOCS.md +24 -17
  9. package/TERMINAL_DOCS.md +24 -5
  10. package/dist/adapters/dom/components/index.cjs +2 -4
  11. package/dist/adapters/dom/components/index.cjs.map +1 -1
  12. package/dist/adapters/dom/components/index.d.cts +4 -4
  13. package/dist/adapters/dom/components/index.d.ts +4 -4
  14. package/dist/adapters/dom/components/index.js +1 -3
  15. package/dist/adapters/dom/components/index.js.map +1 -1
  16. package/dist/adapters/dom/index.cjs +14 -14
  17. package/dist/adapters/dom/index.d.cts +4 -4
  18. package/dist/adapters/dom/index.d.ts +4 -4
  19. package/dist/adapters/dom/index.js +12 -12
  20. package/dist/adapters/dom/server.cjs +13 -13
  21. package/dist/adapters/dom/server.cjs.map +1 -1
  22. package/dist/adapters/dom/server.d.cts +4 -4
  23. package/dist/adapters/dom/server.d.ts +4 -4
  24. package/dist/adapters/dom/server.js +12 -12
  25. package/dist/adapters/dom/server.js.map +1 -1
  26. package/dist/adapters/ink/index.js +0 -2
  27. package/dist/adapters/ink/index.js.map +1 -1
  28. package/dist/adapters/react/components/index.cjs +32 -32
  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 +13 -13
  32. package/dist/adapters/react/index.cjs +35 -35
  33. package/dist/adapters/react/index.d.cts +6 -6
  34. package/dist/adapters/react/index.d.ts +6 -6
  35. package/dist/adapters/react/index.js +13 -13
  36. package/dist/adapters/tty/components/index.cjs +2 -4
  37. package/dist/adapters/tty/components/index.cjs.map +1 -1
  38. package/dist/adapters/tty/components/index.d.cts +4 -4
  39. package/dist/adapters/tty/components/index.d.ts +4 -4
  40. package/dist/adapters/tty/components/index.js +1 -3
  41. package/dist/adapters/tty/components/index.js.map +1 -1
  42. package/dist/adapters/tty/index.cjs +12 -12
  43. package/dist/adapters/tty/index.cjs.map +1 -1
  44. package/dist/adapters/tty/index.d.cts +4 -4
  45. package/dist/adapters/tty/index.d.ts +4 -4
  46. package/dist/adapters/tty/index.js +10 -10
  47. package/dist/adapters/tty/index.js.map +1 -1
  48. package/dist/adapters/vue/components/index.cjs +32 -32
  49. package/dist/adapters/vue/components/index.d.cts +12 -12
  50. package/dist/adapters/vue/components/index.d.ts +12 -12
  51. package/dist/adapters/vue/components/index.js +13 -13
  52. package/dist/adapters/vue/index.cjs +41 -41
  53. package/dist/adapters/vue/index.cjs.map +1 -1
  54. package/dist/adapters/vue/index.d.cts +6 -6
  55. package/dist/adapters/vue/index.d.ts +6 -6
  56. package/dist/adapters/vue/index.js +14 -14
  57. package/dist/adapters/vue/index.js.map +1 -1
  58. package/dist/agent/index.cjs +6 -6
  59. package/dist/agent/index.cjs.map +1 -1
  60. package/dist/agent/index.d.cts +2 -2
  61. package/dist/agent/index.d.ts +2 -2
  62. package/dist/agent/index.js +3 -3
  63. package/dist/agent/index.js.map +1 -1
  64. package/dist/{chunk-QLFHYHJ2.js → chunk-2HWYS6OJ.js} +6 -6
  65. package/dist/chunk-2HWYS6OJ.js.map +1 -0
  66. package/dist/{chunk-7MATRNZZ.js → chunk-2SEZAI3I.js} +6 -6
  67. package/dist/chunk-2SEZAI3I.js.map +1 -0
  68. package/dist/{chunk-OE527MXF.cjs → chunk-3XFQI5P2.cjs} +2 -2
  69. package/dist/chunk-3XFQI5P2.cjs.map +1 -0
  70. package/dist/{chunk-P5SJ3QXJ.js → chunk-3YS2FBF5.js} +54 -68
  71. package/dist/chunk-3YS2FBF5.js.map +1 -0
  72. package/dist/{chunk-XQTI4Q4I.js → chunk-A4GK3PLP.js} +4 -4
  73. package/dist/chunk-A4GK3PLP.js.map +1 -0
  74. package/dist/{chunk-PMKWYOOX.cjs → chunk-BXUEWV7V.cjs} +2 -2
  75. package/dist/chunk-BXUEWV7V.cjs.map +1 -0
  76. package/dist/{chunk-RFBIGRCI.js → chunk-C63CBYD5.js} +3 -3
  77. package/dist/chunk-C63CBYD5.js.map +1 -0
  78. package/dist/{chunk-FSUMCJAR.cjs → chunk-CQZH3L3W.cjs} +39 -39
  79. package/dist/chunk-CQZH3L3W.cjs.map +1 -0
  80. package/dist/{chunk-RB4OMSPA.js → chunk-D42FJUQA.js} +7 -7
  81. package/dist/chunk-D42FJUQA.js.map +1 -0
  82. package/dist/{chunk-UGG7MCX4.cjs → chunk-DC5HONDE.cjs} +2 -2
  83. package/dist/chunk-DC5HONDE.cjs.map +1 -0
  84. package/dist/{chunk-HYFNOF7Y.cjs → chunk-EZ3AJRQ7.cjs} +8 -8
  85. package/dist/chunk-EZ3AJRQ7.cjs.map +1 -0
  86. package/dist/{chunk-ZYTWQZZC.cjs → chunk-FG6IKUHA.cjs} +26 -26
  87. package/dist/chunk-FG6IKUHA.cjs.map +1 -0
  88. package/dist/{chunk-DIFE573X.js → chunk-G4OQ4PEO.js} +6 -6
  89. package/dist/chunk-G4OQ4PEO.js.map +1 -0
  90. package/dist/{chunk-RBU5PHN4.js → chunk-GQVJ5UAS.js} +2 -2
  91. package/dist/chunk-GQVJ5UAS.js.map +1 -0
  92. package/dist/{chunk-KW34ZKF5.cjs → chunk-ITGR7P2B.cjs} +2 -2
  93. package/dist/chunk-ITGR7P2B.cjs.map +1 -0
  94. package/dist/{chunk-JI7ZRESP.js → chunk-JKULAG53.js} +2 -2
  95. package/dist/chunk-JKULAG53.js.map +1 -0
  96. package/dist/{chunk-PBPUSZIQ.cjs → chunk-K54CT3QN.cjs} +50 -69
  97. package/dist/chunk-K54CT3QN.cjs.map +1 -0
  98. package/dist/{chunk-7TS3YVQR.js → chunk-M2ZZUSH3.js} +6 -7
  99. package/dist/chunk-M2ZZUSH3.js.map +1 -0
  100. package/dist/{chunk-GV7UC3SS.cjs → chunk-MEZCO7ND.cjs} +2 -2
  101. package/dist/chunk-MEZCO7ND.cjs.map +1 -0
  102. package/dist/{chunk-D4PUWBN6.cjs → chunk-NBXZ3RAC.cjs} +2 -2
  103. package/dist/chunk-NBXZ3RAC.cjs.map +1 -0
  104. package/dist/{chunk-EG45GQOE.js → chunk-O2N4BVLL.js} +5 -5
  105. package/dist/chunk-O2N4BVLL.js.map +1 -0
  106. package/dist/{chunk-L5223LLX.js → chunk-OBFFZ23H.js} +2 -2
  107. package/dist/chunk-OBFFZ23H.js.map +1 -0
  108. package/dist/{chunk-WGZZKCJQ.cjs → chunk-QHX3VA55.cjs} +7 -7
  109. package/dist/chunk-QHX3VA55.cjs.map +1 -0
  110. package/dist/{chunk-PNQY6OFB.cjs → chunk-QTJ4ZQRM.cjs} +20 -20
  111. package/dist/chunk-QTJ4ZQRM.cjs.map +1 -0
  112. package/dist/{chunk-KOYRJXTI.cjs → chunk-RVU6YEHO.cjs} +10 -11
  113. package/dist/chunk-RVU6YEHO.cjs.map +1 -0
  114. package/dist/{chunk-V4BPFFFV.js → chunk-SCXYAXMO.js} +3 -3
  115. package/dist/chunk-SCXYAXMO.js.map +1 -0
  116. package/dist/{chunk-2MNLEL45.js → chunk-SVWDKXSH.js} +2 -2
  117. package/dist/chunk-SVWDKXSH.js.map +1 -0
  118. package/dist/{chunk-X5JTZ5LW.js → chunk-UXFQZX6O.js} +3 -3
  119. package/dist/chunk-UXFQZX6O.js.map +1 -0
  120. package/dist/{chunk-Z7CS43ZT.cjs → chunk-WQJZMXS5.cjs} +28 -28
  121. package/dist/chunk-WQJZMXS5.cjs.map +1 -0
  122. package/dist/{chunk-ECFWPZGL.cjs → chunk-X77B4ZKQ.cjs} +129 -143
  123. package/dist/chunk-X77B4ZKQ.cjs.map +1 -0
  124. package/dist/{chunk-AGEAMUQR.cjs → chunk-XHDQIQAG.cjs} +13 -13
  125. package/dist/chunk-XHDQIQAG.cjs.map +1 -0
  126. package/dist/{chunk-OE4E6IBD.js → chunk-Y3UKAJJX.js} +2 -2
  127. package/dist/chunk-Y3UKAJJX.js.map +1 -0
  128. package/dist/{chunk-XUSKGJRI.js → chunk-YV2G37TJ.js} +8 -27
  129. package/dist/chunk-YV2G37TJ.js.map +1 -0
  130. package/dist/{chunk-5YQIAS4V.cjs → chunk-ZR54IVVS.cjs} +20 -20
  131. package/dist/chunk-ZR54IVVS.cjs.map +1 -0
  132. package/dist/{chunk-M3UFIUXK.cjs → chunk-ZVQKCDUG.cjs} +7 -7
  133. package/dist/chunk-ZVQKCDUG.cjs.map +1 -0
  134. package/dist/{chunk-OGD5CCMZ.js → chunk-ZZRQAH5Z.js} +2 -2
  135. package/dist/chunk-ZZRQAH5Z.js.map +1 -0
  136. package/dist/devtools/index.cjs +12 -42
  137. package/dist/devtools/index.cjs.map +1 -1
  138. package/dist/devtools/index.d.cts +4 -4
  139. package/dist/devtools/index.d.ts +4 -4
  140. package/dist/devtools/index.js +9 -39
  141. package/dist/devtools/index.js.map +1 -1
  142. package/dist/document/index.cjs +16 -16
  143. package/dist/document/index.d.cts +6 -6
  144. package/dist/document/index.d.ts +6 -6
  145. package/dist/document/index.js +3 -3
  146. package/dist/{effects-CndX9K7D.d.cts → effects-DkBBrxVj.d.cts} +0 -2
  147. package/dist/{effects-CndX9K7D.d.ts → effects-DkBBrxVj.d.ts} +0 -2
  148. package/dist/{endpoints-CD-6Jl-H.d.ts → endpoints-DD6VsLv9.d.ts} +1 -1
  149. package/dist/{endpoints-Dem-EdRx.d.cts → endpoints-fqx9Vmf6.d.cts} +1 -1
  150. package/dist/examples/index.cjs +4 -4
  151. package/dist/examples/index.cjs.map +1 -1
  152. package/dist/examples/index.d.cts +4 -4
  153. package/dist/examples/index.d.ts +4 -4
  154. package/dist/examples/index.js +3 -3
  155. package/dist/examples/index.js.map +1 -1
  156. package/dist/{head-DRpbbj-l.d.ts → head-BvqHLqlL.d.ts} +2 -2
  157. package/dist/{head-CAzfTnpV.d.cts → head-CB1fcRjc.d.cts} +2 -2
  158. package/dist/i18n/index.cjs +13 -13
  159. package/dist/i18n/index.d.cts +4 -6
  160. package/dist/i18n/index.d.ts +4 -6
  161. package/dist/i18n/index.js +3 -3
  162. package/dist/{index-CNfzSBe2.d.ts → index-BjQX8XZl.d.ts} +1 -1
  163. package/dist/{index-caZoXSwr.d.cts → index-BoPH5aSd.d.cts} +1 -1
  164. package/dist/index.cjs +91 -91
  165. package/dist/index.d.cts +11 -11
  166. package/dist/index.d.ts +11 -11
  167. package/dist/index.js +11 -11
  168. package/dist/migrations/index.cjs +8 -9
  169. package/dist/migrations/index.cjs.map +1 -1
  170. package/dist/migrations/index.d.cts +1 -1
  171. package/dist/migrations/index.d.ts +1 -1
  172. package/dist/migrations/index.js +5 -6
  173. package/dist/migrations/index.js.map +1 -1
  174. package/dist/{palette-CIpPH90W.d.ts → palette-BZujb2rm.d.ts} +1 -1
  175. package/dist/{palette-CvwZZCkx.d.cts → palette-CCxWSi3C.d.cts} +1 -1
  176. package/dist/reflect/index.cjs +27 -27
  177. package/dist/reflect/index.d.cts +5 -5
  178. package/dist/reflect/index.d.ts +5 -5
  179. package/dist/reflect/index.js +9 -9
  180. package/dist/{types-qkzTfSye.d.cts → types-BTha1ZLR.d.cts} +4 -5
  181. package/dist/{types-D23TRvqe.d.ts → types-BxpSKUxn.d.ts} +4 -5
  182. package/dist/{types-qnKMx0_V.d.ts → types-CJC8mnzl.d.ts} +0 -1
  183. package/dist/{types-j290XhCn.d.cts → types-CR56luN7.d.cts} +0 -1
  184. package/dist/{types-DsWNYc7R.d.cts → types-D0x56Ya-.d.cts} +1 -1
  185. package/dist/{types-C9734_lJ.d.cts → types-DzB3TAQj.d.cts} +1 -1
  186. package/dist/{types-BWc-olbY.d.ts → types-LXw2RJfH.d.ts} +1 -1
  187. package/dist/{types-BSKx5MXW.d.ts → types-pbBIUNxw.d.ts} +1 -1
  188. package/package.json +7 -7
  189. package/dist/chunk-2MNLEL45.js.map +0 -1
  190. package/dist/chunk-5YQIAS4V.cjs.map +0 -1
  191. package/dist/chunk-7MATRNZZ.js.map +0 -1
  192. package/dist/chunk-7TS3YVQR.js.map +0 -1
  193. package/dist/chunk-AGEAMUQR.cjs.map +0 -1
  194. package/dist/chunk-D4PUWBN6.cjs.map +0 -1
  195. package/dist/chunk-DIFE573X.js.map +0 -1
  196. package/dist/chunk-ECFWPZGL.cjs.map +0 -1
  197. package/dist/chunk-EG45GQOE.js.map +0 -1
  198. package/dist/chunk-FSUMCJAR.cjs.map +0 -1
  199. package/dist/chunk-GV7UC3SS.cjs.map +0 -1
  200. package/dist/chunk-HYFNOF7Y.cjs.map +0 -1
  201. package/dist/chunk-JI7ZRESP.js.map +0 -1
  202. package/dist/chunk-KOYRJXTI.cjs.map +0 -1
  203. package/dist/chunk-KW34ZKF5.cjs.map +0 -1
  204. package/dist/chunk-L5223LLX.js.map +0 -1
  205. package/dist/chunk-M3UFIUXK.cjs.map +0 -1
  206. package/dist/chunk-OE4E6IBD.js.map +0 -1
  207. package/dist/chunk-OE527MXF.cjs.map +0 -1
  208. package/dist/chunk-OGD5CCMZ.js.map +0 -1
  209. package/dist/chunk-P5SJ3QXJ.js.map +0 -1
  210. package/dist/chunk-PBPUSZIQ.cjs.map +0 -1
  211. package/dist/chunk-PMKWYOOX.cjs.map +0 -1
  212. package/dist/chunk-PNQY6OFB.cjs.map +0 -1
  213. package/dist/chunk-QLFHYHJ2.js.map +0 -1
  214. package/dist/chunk-RB4OMSPA.js.map +0 -1
  215. package/dist/chunk-RBU5PHN4.js.map +0 -1
  216. package/dist/chunk-RFBIGRCI.js.map +0 -1
  217. package/dist/chunk-UGG7MCX4.cjs.map +0 -1
  218. package/dist/chunk-V4BPFFFV.js.map +0 -1
  219. package/dist/chunk-WGZZKCJQ.cjs.map +0 -1
  220. package/dist/chunk-X5JTZ5LW.js.map +0 -1
  221. package/dist/chunk-XQTI4Q4I.js.map +0 -1
  222. package/dist/chunk-XUSKGJRI.js.map +0 -1
  223. package/dist/chunk-Z7CS43ZT.cjs.map +0 -1
  224. package/dist/chunk-ZYTWQZZC.cjs.map +0 -1
  225. package/dist/{primitive-props-CGoJvmcH.d.cts → primitive-props-Cl5jiC8g.d.cts} +5 -5
  226. package/dist/{primitive-props-CGoJvmcH.d.ts → primitive-props-Cl5jiC8g.d.ts} +5 -5
package/ACTION_DOCS.md CHANGED
@@ -451,7 +451,7 @@ In **strict mode** (set `strict: true` on the shell), a failure inside a lifecyc
451
451
 
452
452
  ## Fragments
453
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`.
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. Hand fragments over in `ShellConfig.fragments`, or add one while the shell runs with `shell.registerAction`, which takes an action or a fragment; `shell.removeAction` takes either out. A fragment and an action do not share an id.
455
455
 
456
456
  ```ts
457
457
  import type { ActionFragment } from '@niscorp/nova';
@@ -567,6 +567,8 @@ Action definitions are validated against `ActionDefinitionSchema` when you pass
567
567
 
568
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.
569
569
 
570
+ A catalog entry's `input` is the target action's `input` schema: seeded keys are checked against its `properties`, and an entry without `properties` passes any key. A step that opens the definition's own id needs no catalog entry.
571
+
570
572
  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.
571
573
 
572
574
  ---
package/ADAPTER.md CHANGED
@@ -114,7 +114,8 @@ and `ACTION_SLOT_NAME` — the shell's default layouts reference them:
114
114
  - **ActionSlot** (`{ instanceId }`): renders that instance's tree; nothing
115
115
  when `instanceId` is missing. Wrap the dispatch handed to the instance's
116
116
  subtree with core's `scopeDispatch(dispatch, instanceId)` so its UI events
117
- reach its own triggers only. Do not reimplement the stamping rule.
117
+ reach its own triggers only. An event that already carries an `origin`
118
+ passes through unchanged. Do not reimplement the stamping rule.
118
119
 
119
120
  `flattenRenderTree` resolves `CanvasSlot` markers away, but the `ActionSlot`
120
121
  marker *survives* flattening: it arrives as a component node with
@@ -139,6 +140,17 @@ Checkbox, Textarea, and Table, with Select and Switch as aliases of Input and
139
140
  Checkbox; the TTY and Ink kits ship the DOM kit's names plus Badge (each a
140
141
  `defaultRegistry()`).
141
142
 
143
+ `Table`, in the three kits that ship it, reads `columns` (`[{ label, cell:
144
+ { key } }]`, `key` a dotted path into a row) and `rows`. With `rowRef` set, a
145
+ press on a row dispatches `ui:click` on that ref with the row's `clickKey`
146
+ value as payload; `clickKey` defaults to `rowKey`, and `rowKey` to `id`.
147
+
148
+ `createDomView`, `mountShell` and `renderToString` take a `fallback` component
149
+ in their options for a name the registry does not hold; without one, such a
150
+ name draws a `COMPONENT_NOT_FOUND` marker. The DOM kit exports one
151
+ (`fallback`): a `div` holding the node's children, or with no children its
152
+ `label` or `title` prop and a `count`.
153
+
142
154
  ### 5. SlotWrapper persistence
143
155
 
144
156
  If the adapter supports an app-supplied slot wrapper (animation, gating,
@@ -239,6 +251,12 @@ was replaced because its own props changed, or the view was destroyed
239
251
  (`renderToString` destroys the view it drew with, so nothing is left running
240
252
  where only markup was wanted). An element that stays is not told anything.
241
253
 
254
+ **`dispatch(event)` is for a component with presses of its own** — a table's
255
+ rows, a panel's close button. The event goes to the canvas the component sits
256
+ in, as the instance it sits in; in the frame, outside any `CanvasSlot`, it goes
257
+ nowhere. A node's own `ref` and `model` need none of it: the adapter wires
258
+ those on the element the component returns.
259
+
242
260
  **Children are patched in place only under an element that holds exactly them.**
243
261
  The adapter looks at what the component returned:
244
262
 
package/CHANGELOG.md CHANGED
@@ -1,5 +1,38 @@
1
1
  # @niscorp/nova
2
2
 
3
+ ## 0.4.0
4
+
5
+ ### Minor Changes
6
+
7
+ - c7c4f9b: A nova shell keeps actions and fragments in one registry. **Breaking.**
8
+
9
+ BREAKING — approved by moccadroid, 2026-10-13: `shell.registerFragment` is gone, and an action and a fragment no longer share an id.
10
+ - **`shell.registerAction(definition)` takes an action or a fragment**, told apart by the fragment's `kind: 'fragment'`, and **`shell.removeAction(id)` takes either out**. There was no call to take a fragment out. Taken out, a fragment is unknown to a later `with: [...]`; an instance that was opened with it keeps the definition it was composed into, and `back` skips a position that was opened with it, as it skips one it cannot put back.
11
+ - **A fragment handed to `createShell` is validated**, as an action is: one that does not parse throws `DefinitionValidationError` at construction. Only `registerFragment` validated one before.
12
+ - **An id names an action or a fragment, never both.** `createShell` and `registerAction` throw `DefinitionValidationError` for an id that is already the other kind's.
13
+ - Opening a fragment by itself still throws `UnknownActionError`, and a `with: [...]` that names an action still throws `UnknownFragmentError`. `ShellConfig` keeps `actions` and `fragments`.
14
+ - **Moss:** a fragment that is no longer answered for a principal is taken out of their open shell, as an action is. A boot, and a set of actions handed over, refuse an action under the id of a fragment a shell ships. On a session's own shell, `registerAction` (refused there as before) is the one call that would take a fragment.
15
+
16
+ **What to change:** `shell.registerFragment(fragment)` becomes `shell.registerAction(fragment)`. Give an action and a fragment that share an id two ids.
17
+
18
+ ## 0.3.1
19
+
20
+ ### Patch Changes
21
+
22
+ - d6b2c4a: The docs state seventy-three facts about the API that were written only in source comments.
23
+
24
+ README: what each reflect export returns (`walkNodes`, `snapshotShell`, `describeInstance`, `describeShell`, `actionGraph`, `auditCatalog`, `livenessOf`, `chainCycles`, the `*Keys` helpers), the devtools functions and how an app opens the inspector, `paletteFromRegistry`'s options and `paletteEntryOf`, what `collectInteractive` returns, an example's `replies`, `fetches`, `presses` and `expected`, what `headOf` returns, and `placeHead`'s `{ site, path }`. ACTION_DOCS.md: a catalog entry's `input`. ADAPTER.md, REACT_DOCS.md and TERMINAL_DOCS.md: what the kits' `Table` and `fallback` read, what a component's `dispatch` is for, what a Vue component and slot wrapper receive, a TTY interactive's `label` and `register`, how the terminal kits lay out and focus. I18N_DOCS.md: what counts as a binding and as a phrase, `fillPhrase` on a plain value, the form of `where`, and the order of a harvest. SHELL_DOCS.md: a layout given as a store id, what `back` passes over, `removeAction`, a reconcile entry's `with` and the call's `notes`, an unstamped `api.dispatch`, and what `canvasTree` counts as nothing.
25
+
26
+ Two statements are corrected. SHELL_DOCS.md said an `initial` seed equals a `shell.push` made after `createShell` returns; a seed is pushed with `history: false`, so `back` does not undo it. TERMINAL_DOCS.md said a model-bound field's marker resolves by `occurrence`; the Ink kit passes `occurrence` for a `Table` row only, and an `Input` or `Checkbox` resolves by its ref.
27
+
28
+ No behaviour changed.
29
+
30
+ **What to change:** nothing.
31
+
32
+ - 037d26c: Inside the action runtime, the map from a `ui:model` node's ref to the state path it writes is named `modelPaths`; it was `modelListeners` and holds no listener. `teardownModelListeners`, which only cleared that map, is gone and its two callers clear the map. No behaviour changed.
33
+
34
+ **What to change:** nothing.
35
+
3
36
  ## 0.3.0
4
37
 
5
38
  ### Minor Changes
package/DESIGN.md CHANGED
@@ -382,9 +382,8 @@ removeInstance(canvasId, instanceId): void
382
382
  replace(canvasId, actionId, input?, fragments?): string
383
383
  clear(canvasId): void
384
384
  back(): boolean
385
- registerAction(definition): void
386
- removeAction(actionId): void
387
- registerFragment(fragment): void
385
+ registerAction(definition): void // an action or a fragment
386
+ removeAction(id): void // an action or a fragment
388
387
  addCanvas(config): void
389
388
  removeCanvas(canvasId): void
390
389
  setCanvasLayout(layout): void
@@ -451,9 +450,13 @@ fire-and-forget failures via a synchronous API without making
451
450
 
452
451
  An `ActionFragment` is a reusable **partial action** — every
453
452
  `ActionDefinition` field optional, plus a `kind: 'fragment'` discriminator.
454
- It is **abstract**: it lives in a separate registry (`ShellConfig.fragments`
455
- / `registerFragment`), can never be `push`ed as an action (its id isn't in
456
- `actions`, so that throws `UnknownActionError`), and only exists once merged.
453
+ It is **abstract**: it can never be `push`ed as an action (that throws
454
+ `UnknownActionError`), and only exists once merged. A shell keeps actions and
455
+ fragments in one registry, by id, and tells them apart by `kind`: both are
456
+ added with `registerAction` and taken out with `removeAction`, and an id names
457
+ one or the other, never both (`DefinitionValidationError`). An app writes its
458
+ fragments down in `ShellConfig.fragments`, beside `actions`; they are
459
+ validated at construction as actions are.
457
460
  Because it is pure data it ships in a DB row and an agent can author it; a
458
461
  reference (`with: ['modal']`) collapses an arbitrary amount of chrome to a
459
462
  single token in the model's context.
package/I18N_DOCS.md CHANGED
@@ -116,6 +116,14 @@ 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 `{{`.
122
+
123
+ A phrase (`isPhrase`) is a non-blank string that is not a binding and holds at
124
+ least one letter. Only a phrase is harvested, looked up in the book or reported
125
+ as a miss: `12`, `100%` and `—` never are.
126
+
119
127
  ## Counted phrases
120
128
 
121
129
  A dictionary can hold "Standing". It can never hold "12 of 20" — two numbers
@@ -139,7 +147,9 @@ source language, not switching i18n off — a shell is language-bearing from the
139
147
  moment it is given a book or a key set.
140
148
 
141
149
  For a pattern held as data rather than shown — a check reading engine output, a
142
- fixture, an exporter — use `fillPhrase(value)` from `@niscorp/nova/i18n`.
150
+ fixture, an exporter — use `fillPhrase(value)` from `@niscorp/nova/i18n`. A value
151
+ that is not a `{ phrase, slots }` pattern comes back unchanged, so it can be
152
+ called on a column of mixed values.
143
153
 
144
154
  ## What this cannot do
145
155
 
@@ -201,16 +211,21 @@ At runtime, `onPhraseMiss(phrase, where)` reports every lookup that failed. A
201
211
  miss renders as the **source language** — never an empty box, never a raw key —
202
212
  which is the only sane failure and also the one that hides, so wire the report.
203
213
 
214
+ `where` is the path of component names from the layout's root, then the prop:
215
+ `/Stack/Button.label`, `/Stack/Table.columns[0].label`, or `/Stack/Text#text`
216
+ for a text child. The hook is called inside the render, once for each failed
217
+ lookup and again on every later render, so a slow handler slows every render.
218
+
204
219
  ## API
205
220
 
206
221
  From `@niscorp/nova/i18n`:
207
222
 
208
223
  | Export | Purpose |
209
224
  |---|---|
210
- | `harvestLayout` / `harvestDefinition` / `harvestDefinitions` | Enumerate the phrases an artifact can show |
225
+ | `harvestLayout` / `harvestDefinition` / `harvestDefinitions` | Enumerate the phrases an artifact can show. The list is sorted by phrase; each phrase's `where` holds its author sites, sorted, each once |
211
226
  | `missingFrom(harvested, book)` | What a language is still missing |
212
227
  | `fillPhrase(value)` | Close a counted phrase held as data, outside a render |
213
- | `translateRenderTree(tree, { phrases, keys?, onMiss? })` | For a tree you did **not** render — a replayed frame, a fixture. An empty book returns the same tree, patterns unfilled |
228
+ | `translateRenderTree(tree, { phrases, keys?, onMiss? })` | For a tree you did **not** render — a replayed frame, a fixture. An empty book returns the same tree, patterns unfilled. `onMiss(phrase, where)` is called for each lookup the book has no entry for |
214
229
  | `DEFAULT_PHRASE_KEYS` | The default prose prop set |
215
230
  | `isBinding` / `isPhrase` / `matcherFor` | The primitives the rules are built from |
216
231
  | `Phrasebook` / `PhraseKeys` / `PhraseKeyMatcher` / `TranslateOptions` / `HarvestedPhrase` | Types |
package/REACT_DOCS.md CHANGED
@@ -139,7 +139,7 @@ Three components that hide the registry/provider/render-tree wiring. Each is als
139
139
  <Nova.Canvas id="main" /> // one canvas, inside a shell provider
140
140
  ```
141
141
 
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.
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
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
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.
145
145
 
@@ -427,7 +427,7 @@ The same seam, used as a gate: the wrapper decides whether to render the content
427
427
 
428
428
  ### `useSlotWrapper()`
429
429
 
430
- Reads the active `slotWrapper` from render context (or `undefined`). You rarely call it directly — `ActionSlot` does — but it's there if you build your own slot rendering.
430
+ Reads the active `slotWrapper` from render context (or `undefined`). You rarely call it directly — `ActionSlot` does — but it's there if you build your own slot rendering. Outside a provider it returns `undefined`; it does not throw.
431
431
 
432
432
  Both examples above ship as runnable demos in the showroom under **Slot wrappers**.
433
433
 
@@ -591,6 +591,8 @@ type NovaComponentProps = {
591
591
 
592
592
  - The shell-backed composables return a `Readonly<Ref<…>>` and take a ref or getter for their id (`useCanvas(() => props.id)`).
593
593
  - The render context travels by provide/inject (`NovaRenderKey`, `NovaShellKey`); children reach a component as its default slot.
594
+ - A component receives the node's props, `novaRef` and `novaModel` as Vue props, so one that declares `props` lists each it reads (the kit's `Button` lists `novaRef`); a functional component that declares none receives them all.
595
+ - A slot wrapper is a Vue component: `canvasId`, `instanceId` and `action` arrive as props, the content as its default slot.
594
596
  - There is no `Nova` namespace and no `NovaLayout`; `NovaRenderProvider` takes `fallback` but not `textWrapper` / `errorMarker`.
595
597
  - `NovaErrorBoundary`'s `onError` receives Vue's info string.
596
598
  - The kit is `registerNovaVueComponents(registry)` from `@niscorp/nova/adapters/vue/components`: the same nine names over the same props schemas.
package/README.md CHANGED
@@ -242,7 +242,7 @@ ships in a DB row and can be referenced rather than inlined.
242
242
  The orchestrator. `createShell(config)` validates every action
243
243
  definition at construction (boundary Zod validation) and returns a
244
244
  `Shell` with `push`, `pop`, `popTo`, `removeInstance`, `replace`, `clear`,
245
- `back`, `originOf`, `registerAction`, `removeAction`, `registerFragment`,
245
+ `back`, `originOf`, `registerAction`, `removeAction`,
246
246
  `addCanvas`, `removeCanvas`, `setCanvasLayout`, `setLayout`, `setPhrases`,
247
247
  `getPhrases`, `getCanvasState`, `getRuntime`, `getState`,
248
248
  `getShellRenderTree`, `getCanvasRenderTree`, `flattenRenderTree`,
@@ -282,7 +282,10 @@ head or for what it holds, no registry has to have the names, and a component
282
282
  is never handed a head as a child. It rides in the render tree, so it reaches
283
283
  every place a screen does — a shell in the page, a snapshot a server drew, the
284
284
  trees on a wire — and `headOf(api)` reads it off any of them:
285
- `{ elements, actions, refused }`.
285
+ `{ elements, actions, refused }`. Each of `elements` is
286
+ `{ tag, attributes, text? }`, where `text` is a title's words or a script's
287
+ data as JSON. `actions` lists the ids of the actions that said any of them; it
288
+ is empty when only the shell's own layouts did.
286
289
 
287
290
  A screen can hold more than one head: the shell's chrome says what holds on
288
291
  every screen, an action says its own, a dialog opens over a page. They are
@@ -302,7 +305,12 @@ anything, or in the kit component that needs them.
302
305
  `@niscorp/nova/document` is the surface that has a `<head>`. `placeHead`
303
306
  writes the elements into an HTML document being drawn to a string (what
304
307
  `@niscorp/cli` and moss's `renderDocument` call): an element takes the place
305
- of the tag that said the same thing, and anything else is added. In the page,
308
+ of the tag that said the same thing, and anything else is added. Its third
309
+ argument is `{ site, path }`: given both, with `site` an origin
310
+ (`https://example.com`), it also writes that path's canonical `<link>` and
311
+ `og:url`, built from `site` and `path` without its query or fragment, as the
312
+ document's own tags, so a screen that says either takes its place. Given only
313
+ one of the two it writes neither. In the page,
306
314
  the DOM, React and Vue adapters keep `document.head` on the screen
307
315
  (`createHeadKeeper`): its elements go in, the document's own tags give way to
308
316
  them and come back when the screen stops saying them. To offer the names to a
@@ -429,6 +437,56 @@ can perform their own final async work (e.g. telemetry flush).
429
437
  `classifyAudit` / `auditCatalog` (closure-audit triage), `livenessOf` (what
430
438
  an action can still do once drawn: gestures, the channels it waits on, every
431
439
  endpoint and whether it is called on open or later).
440
+ - `walkNodes(value, visit)` calls `visit` on every plain object in a tree,
441
+ an object before the ones inside it. `refsOf` returns only the refs inside
442
+ a component's props (a Table's `rowRef`, a cell's `ref`), not a node's own
443
+ `ref`.
444
+ - `snapshotShell(shell, exclude?)` returns `{ canvases, layouts,
445
+ components }`: every canvas with its instances, top of the stack first,
446
+ the ids in the layout store, and every component name in the registry.
447
+ `exclude` lists canvas ids to leave out.
448
+ - `describeInstance(shell, instanceId)` returns one live instance's
449
+ definition wiring, its current data and its classified audit, or
450
+ `undefined` when no instance with that id is mounted.
451
+ - `describeShell(shell, options?)` returns the shell as text: a line per
452
+ canvas with its stack, bottom to top and the last marked `*`, then a line
453
+ per instance with its data as JSON. `only` names the canvases to write
454
+ (all of them without it). `mark(instanceId)` returns a note written beside
455
+ that instance. An array longer than `collapseOver` (5 by default; `0`
456
+ collapses nothing) is cut to its first `head` items (3 by default) and a
457
+ count of the rest. `clean(data)` maps each instance's data before it is
458
+ written.
459
+ - `actionGraph(definitions)` returns `{ nodes, dangling }`: `dangling` lists
460
+ the `push` / `replace` / `resetTo` targets that no definition in the set
461
+ has; a target written as a `{{…}}` template is left out.
462
+ - `auditCatalog(definitions)` audits each definition against a catalog and
463
+ a channel list built from the whole set, so the wiring between actions is
464
+ checked. It returns a row `{ id, address, issues }` for each definition
465
+ that has findings: every issue is classified by `classifyAudit` as
466
+ `address` or `info`, the `address` ones first, and the rows are ordered by
467
+ how many `address` findings they hold, most first.
468
+ - `livenessOf(definition)`: `gestures` is true when the action has an
469
+ `event` trigger or a component with a `model`. An HTTP endpoint also
470
+ carries its `url` and `request` as authored (a template stays a template).
471
+ When the layout is a store id it is not read: `opaqueLayout` is true, and
472
+ `gestures: false` then does not mean nothing can be pressed.
473
+ - `chainCycles(definitions)` returns the loops in the set's trigger chains,
474
+ one `{ steps, path }` per group of chains that lead back into each other.
475
+ A chain starts at a `message:` trigger or a `mount` hook and runs on
476
+ through `emit`, `reload`, `push`, `replace` and `resetTo` steps; only
477
+ literal channels and the ids of actions in the set are followed. A step is
478
+ `{ from, to, action, via }`: `from` and `to` are `channel:<name>` or
479
+ `mount:<action id>`, `action` is the definition whose trigger or `mount`
480
+ hook holds the step, and `via` is the step's kind. `path` is the loop on
481
+ one line: `x —emit (loop)→ x`.
482
+ - `gesturedKeys`, `declaredKeys`, `loadedKeys` and `lifecycleKeys` return a
483
+ definition's top-level data keys by who writes them: the mutation steps of
484
+ its `ui:` triggers, the keys its `input` declares, every endpoint's
485
+ `target` and `errorTarget`, and the mutation steps of its lifecycle hooks.
486
+ `mountInputKeys` returns the declared input keys that the `request` of an
487
+ endpoint called from `mount` reads: writing one into a live instance
488
+ leaves the previous record's data on screen, so a caller that re-aims the
489
+ instance re-mounts it.
432
490
  - **`@niscorp/nova/devtools`** — a shell inspector built as pure nova:
433
491
  `devtoolsActions` (`devtools.dock`, `devtools.inspect` — plain
434
492
  ActionDefinitions over generic primitives), `DEVTOOLS_CANVAS`, and
@@ -436,6 +494,19 @@ can perform their own final async work (e.g. telemetry flush).
436
494
  timeline is a ring buffer fed by `shell.onEndpoint`). An app opts in by
437
495
  granting `devtools.*` to a dev role, adding the canvas plus a frame
438
496
  slot, and spreading the fns into its `functions(session)`.
497
+ - `createDevtoolsFunctions({ shell, definitions })`: `definitions` is the
498
+ app's catalog (a record or an array) and is what the audit tab checks;
499
+ without it the audit is empty.
500
+ - The `devtools.setEnabled` fn mounts and unmounts the dock: it reads the
501
+ calling action's `devtools` data key, pushes `devtools.dock` onto the
502
+ `devtools` canvas when that is `true`, and clears the canvas otherwise.
503
+ `devtools.enabled` answers whether the dock is mounted.
504
+ - While the dock is mounted, a `ui:click` with ref `inspect` and an instance
505
+ id as its payload, dispatched on the devtools canvas, pushes
506
+ `devtools.inspect` for that instance. An app's own control (a chip in a
507
+ `slotWrapper`) opens the inspector that way.
508
+ - A timeline row's `action` is the calling instance's definition id, read
509
+ when the call is recorded, so it is there after the instance unmounts.
439
510
 
440
511
  ---
441
512
 
@@ -448,6 +519,21 @@ can perform their own final async work (e.g. telemetry flush).
448
519
  `meta`), and `collectInteractive` (a layout's refs, models and bound data
449
520
  keys, derived by walking the tree). Needs the optional peer
450
521
  `@niscorp/cortex`.
522
+ - `paletteFromRegistry(registry, { include, omitProps })`: `include` limits
523
+ the palette to the named components (every registered one without it);
524
+ `omitProps` removes the named props from every component's schema, so the
525
+ agent cannot set them.
526
+ - `paletteEntryOf(name, meta, omitProps?)`, exported from the package root,
527
+ is the entry `paletteFromRegistry` builds for one component: `{ name,
528
+ description, propsSchema? }`, with `propsSchema` the component's props
529
+ schema as draft-07 JSON Schema, left out when the component has none.
530
+ - `collectInteractive(layout)` returns `{ refs, models, boundKeys,
531
+ suspectBindings, componentCount }`. A ref's `via` is `'ref'` for a node's
532
+ own `ref`, or the prop name (`rowRef`) for a ref held in a `*Ref` prop. A
533
+ model's `path` is the binding as written (`'$.search'`).
534
+ `suspectBindings` lists each `$name.` whose `name` is not a loop variable
535
+ of an enclosing `for`/`as`; `auditAction` reports each one as a malformed
536
+ binding.
451
537
  - **`@niscorp/nova/i18n`** — nova is language-blind: a host hands the shell a
452
538
  phrasebook (`phrases` on `ShellConfig`, `shell.setPhrases` at runtime) and
453
539
  nova swaps prose at render. The subpath holds the pieces around that:
@@ -492,7 +578,11 @@ const counter = NOVA_EXAMPLES.find((example) => example.id === 'counter');
492
578
  // counter.expected: { data: { count: 1 }, says: ['Count: 1', 'One more', 'One fewer'] }
493
579
  ```
494
580
 
495
- An example is one action alone on a canvas (`action`) or a small shell (`shell`: canvases, actions, and how the canvases are arranged). Beside either stand what it needs from its host: `fragments`, stored `layouts`, a phrase book (`phrases`, `phraseKeys`), and what its endpoints are answered (`replies` for `fn:`, `fetches` for a URL). Every id an example brings begins with the example's own, so a host can hold all of them in one shell.
581
+ An example is one action alone on a canvas (`action`) or a small shell (`shell`: canvases, actions, and how the canvases are arranged). Beside either stand what it needs from its host: `fragments`, stored `layouts`, a phrase book (`phrases`, `phraseKeys`), and what its endpoints are answered (`replies` for `fn:`, `fetches` for a URL). Every id an example brings begins with the example's own, so a host can hold all of them in one shell. `replies` is keyed by the function's name and holds what each returns; `fetches` is keyed by method and address (`'GET /examples/<id>/…'`) and holds the `status` and `body` each is answered with.
582
+
583
+ `presses` are what is done to it, in order. A press is `{ ref, type?, payload?, canvas? }`: a `ui:click` on the component with that `ref`, or with `type: 'ui:model'` the `payload` typed into it. In a shell example `canvas` names the canvas and the press goes to the action on top of it; without `canvas` it goes to the first canvas. A press of `{ phrases }` is the host changing the language: it hands the shell that book, or with `null` takes the book away.
584
+
585
+ `expected` is what must come out once the presses are done. `says` is every text the screen holds, in reading order, with what stands in a prop at a prose key (a placeholder, a label). `data` is what the one action holds (an `action` example). `stacks` is the action ids on each canvas, bottom to top (a `shell` example). `asked` is what was sent to each URL the example called: `method`, `url`, and `headers` and `body` where there were any.
496
586
 
497
587
  The examples name only the plain components every kit has (`Stack`, `Text`, `Button`, `Input`) and nova's two slots, with no prop about looks. One that says `stage: false` (the ones on i18n) cannot simply be mounted beside a host's own screens, and is shown as what it comes to. The package's tests run each one, so what they say is what this version does.
498
588
 
package/SHELL_DOCS.md CHANGED
@@ -46,7 +46,8 @@ type ShellConfig = {
46
46
 
47
47
  // Layout of the shell itself
48
48
  canvasLayout?: LayoutNode | string; // how the shell arranges its canvases; when omitted,
49
- // canvases render in a single flex row in declaration order
49
+ // canvases render in a single flex row in declaration order.
50
+ // A string is the id of a layout in the layout store
50
51
 
51
52
  // Registry / layouts (both built fresh when omitted)
52
53
  registry?: ComponentRegistry; // shared component registry for all actions
@@ -99,13 +100,15 @@ type CanvasConfig = {
99
100
  // that loops `$.instances`
100
101
  actionLayout?: LayoutNode | string; // how this canvas arranges its instances; when omitted,
101
102
  // only the top-of-stack (card-deck) action renders.
102
- // Scope available to resolvables: { instances, active, count }
103
+ // Scope available to resolvables: { instances, active, count }.
104
+ // A string is the id of a layout in the layout store
103
105
  initial?: CanvasInitialSeed | CanvasInitialSeed[]; // pre-populate the stack on shell creation;
104
106
  // a list is pushed left to right
105
107
  };
106
108
 
107
- // A seed is an action id, or an object with input and fragment composition —
108
- // equivalent to calling shell.push(canvasId, ...) after createShell returns.
109
+ // A seed is an action id, or an object with input and fragment composition.
110
+ // It is pushed as shell.push(canvasId, ..., { history: false }) pushes it:
111
+ // `back` does not undo it.
109
112
  type CanvasInitialSeed = string | { action: string; input?: Record<string, unknown>; with?: string[] };
110
113
  ```
111
114
 
@@ -135,7 +138,7 @@ These are **shared** across every action in the shell. All actions read componen
135
138
 
136
139
  ### `fragments`
137
140
 
138
- Reusable partial actions (`ActionFragment`s), keyed by id, referenceable from a push/replace effect's `with: [...]`. More can be added at runtime via `shell.registerFragment`.
141
+ Reusable partial actions (`ActionFragment`s), keyed by id, referenceable from a push/replace effect's `with: [...]`. Each is validated at construction, as an action is. The shell keeps them in the registry its actions are in, so an id that is also an action's is refused (`DefinitionValidationError`). More are added while the shell runs with `shell.registerAction`, and one is taken out with `shell.removeAction`.
139
142
 
140
143
  ### `fetch`, `transform`, and `functions`
141
144
 
@@ -194,9 +197,8 @@ type Shell = {
194
197
  back: () => boolean; // undo the last navigation, anywhere on the shell
195
198
 
196
199
  // Runtime registration
197
- registerAction: (definition: ActionDefinition) => void;
198
- removeAction: (actionId: string) => void; // revocation: unmounts live instances
199
- registerFragment: (fragment: ActionFragment) => void;
200
+ registerAction: (definition: ActionDefinition | ActionFragment) => void;
201
+ removeAction: (actionId: string) => void; // an action: unmounts live instances. A fragment: what was opened with it keeps what it was composed into
200
202
 
201
203
  // Canvas set / layout mutation
202
204
  addCanvas: (config: CanvasConfig) => void;
@@ -316,7 +318,9 @@ shell.back();
316
318
  The shell keeps a **navigation journal**: before every `push`, `replace`,
317
319
  `clear` and `resetTo` — and every `reconcile` that moved something — it writes
318
320
  down the canvas that is about to change. One entry is one position somebody can
319
- be returned to; `back` restores the newest.
321
+ be returned to; `back` restores the newest. An entry whose position is already on
322
+ screen is passed over, so one call can spend several entries and `true` means the
323
+ screen moved.
320
324
 
321
325
  - **Global and ordered.** One journal across every canvas, each entry naming the
322
326
  one canvas it describes — so back walks a person's own moves in the order they
@@ -333,7 +337,8 @@ be returned to; `back` restores the newest.
333
337
  false }`) are never recorded, so `back` cannot empty the screen somebody landed
334
338
  on. A revoked action takes its entries with it: `removeAction` purges anything
335
339
  that would hand it back, and `removeCanvas` drops what can no longer be
336
- restored.
340
+ restored. A position that was opened with a fragment taken out since cannot
341
+ be put back as it was: `back` skips it and goes to the one before.
337
342
  - **Depth.** `ShellConfig.historyDepth` (default 50) bounds the journal;
338
343
  `historyDepth: 0` switches it off and makes `back` a no-op.
339
344
 
@@ -346,15 +351,16 @@ protocol-level: see its `back` client message.
346
351
  The shell starts from `createShell`'s `actions` / `fragments` / `canvases` / `canvasLayout` and can change all four live:
347
352
 
348
353
  ```ts
349
- shell.registerAction(definition); // add (or replace) an action definition
350
- shell.removeAction(actionId); // revocation: unmounts live instances, drops the definition
351
- shell.registerFragment(fragment); // add a fragment for `with: [...]`
354
+ shell.registerAction(definition); // add (or replace) an action definition, or a fragment for `with: [...]`
355
+ shell.removeAction(actionId); // an action: unmounts live instances, drops the definition. A fragment: drops it; a later `with` naming it throws
352
356
  shell.addCanvas({ id: 'aside', initial: 'inspector' }); // appends + seeds; no-op if the id exists
353
357
  shell.removeCanvas('aside'); // unmounts its instances, then drops it
354
358
  shell.setCanvasLayout(layout); // swap how the shell arranges its canvases
355
359
  shell.setLayout('region-a', layout); // swap what a LayoutRef placeholder resolves to
356
360
  ```
357
361
 
362
+ `removeAction` with an id the shell does not have is a no-op. Where it unmounts the top of a canvas, the instance beneath resumes; fragments and the instances of other actions are untouched.
363
+
358
364
  `setLayout` is the hot-swap hook for dynamic region layouts: a canvasLayout embeds `{ ref: id }` placeholders, and this replaces what one resolves to — the frame/chrome stays intact.
359
365
 
360
366
  ### Language
@@ -382,7 +388,7 @@ const { changed, notes } = reconcileCanvas(
382
388
  );
383
389
  ```
384
390
 
385
- `origin` (required) is stamped on everything the call pushes. `own: 'pushed'` (default) moves only instances carrying that origin; `own: 'canvas'` moves everything on the canvas. One instance per action id. An optional `definitionOf(actionId)` enables the re-aim rule: when a live instance's input changed and that input carries a key the action declares in its `input` and its mount-time load reads through an endpoint `request`, the instance is re-opened instead of written into.
391
+ `origin` (required) is stamped on everything the call pushes. `own: 'pushed'` (default) moves only instances carrying that origin; `own: 'canvas'` moves everything on the canvas. One instance per action id. An optional `definitionOf(actionId)` enables the re-aim rule: when a live instance's input changed and that input carries a key the action declares in its `input` and its mount-time load reads through an endpoint `request`, the instance is re-opened instead of written into. A desired entry's `with` names the fragments the action is composed with when the call pushes it, as `push` takes them. `notes` lists what the call did, in order (`placed notes`, `closed timer`, `set minutes on timer`), for a log or a trace.
386
392
 
387
393
  ### Render-tree access
388
394
 
@@ -548,7 +554,9 @@ api.dispatch('main', { type: 'ui:click', ref: 'save' });
548
554
  const done = await shellIdle(shell, { waitMs: 5000 }); // true: what the press set going has finished
549
555
  ```
550
556
 
551
- `api.dispatch` stamps an event that names no `origin` with the canvas's active instance; `api.publish(channel, payload?)` is `shell.publish`. `shellSettled` and `shellIdle` also take `stopped?: () => boolean` — once it answers `true` the wait ends with `false`.
557
+ `api.dispatch` stamps an event that names no `origin` with the canvas's active instance; `api.publish(channel, payload?)` is `shell.publish`. On a canvas with nothing mounted there is no instance to stamp it with, and the event reaches every instance listening. `shellSettled` and `shellIdle` also take `stopped?: () => boolean` — once it answers `true` the wait ends with `false`.
558
+
559
+ `api.canvasTree(canvasId)` is `canvasTreeOf(shell, canvasId)`: the canvas's flattened tree, or `[]` when `hasVisibleContent` finds nothing to show in it. Empty text, a `nova:head` node, and a fragment or an `ActionSlot` marker with nothing to show inside count as nothing; any other component counts, also one with no children, and so does an error node.
552
560
 
553
561
  `shellView` is what lets an adapter written against `RenderApi` (the DOM and TTY adapters, a moss terminal) draw a shell that lives beside it. `shellSettled` resolves `true` once no instance is `initializing` — every mount hook, and what it chained to, has been awaited — and `false` if `waitMs` (default 300) runs out first. It is the moment to draw a shell to markup, and the moment for the page's own shell to adopt it.
554
562
 
@@ -662,7 +670,7 @@ The shell can produce these:
662
670
  - **`UnknownActionError`** — `shell.push(canvas, 'foo')` where `'foo'` isn't in `actions`
663
671
  - **`UnknownFragmentError`** — a `fragments` / `with: [...]` id that isn't registered
664
672
  - **`ShellDisposedError`** — `push`, `replace`, and the registration / canvas / layout / phrase setters after `dispose()` (`pop`, `popTo`, `removeInstance`, `clear`, `removeCanvas` and `back` are no-ops instead)
665
- - **`DefinitionValidationError`** — at shell construction, if any action in `actions` fails schema validation; also from `registerAction` / `registerFragment`
673
+ - **`DefinitionValidationError`** — at shell construction, if any action in `actions` or fragment in `fragments` fails schema validation, or an id is in both; also from `registerAction`
666
674
  - **`LifecycleError`** — a lifecycle hook step threw (in strict mode propagates, in lax mode routes via `onError`)
667
675
 
668
676
  Plus all action-level errors (from `ACTION_DOCS.md`) and layout-level errors (from `LAYOUT_DOCS.md`) bubble up through the shell's error pipeline.
@@ -707,7 +715,6 @@ shell.back(); // → boolean
707
715
  // Runtime registration / canvas mutation
708
716
  shell.registerAction(definition);
709
717
  shell.removeAction(actionId);
710
- shell.registerFragment(fragment);
711
718
  shell.addCanvas(config);
712
719
  shell.removeCanvas(canvasId);
713
720
  shell.setCanvasLayout(layout);
package/TERMINAL_DOCS.md CHANGED
@@ -53,6 +53,9 @@ canvases collapse entirely.
53
53
  several live instances that share refs — a tab bar's every button is
54
54
  `open` — so the host stamps this as the event's `origin`, as the DOM
55
55
  adapter does, or the server's card-deck fallback picks one of them.
56
+ - `label` — a name to list it by: the first line a `ref`'d or `model`'d
57
+ node printed, cut at 48 characters (the ref when that line is empty); a
58
+ component that registers its own passes one.
56
59
  - `value` — click/row: the dispatch payload; model/toggle: the current
57
60
  value. `path` — the model path, display only.
58
61
 
@@ -68,6 +71,10 @@ register through `ctx.register`.
68
71
  (ctx: { props; children: TtyBlock[]; register }) => TtyBlock // TtyBlock = { lines: string[] }
69
72
  ```
70
73
 
74
+ `register({ kind, ref, label, value?, path? })` adds an interactive and
75
+ returns its index; the component prints that `[n]` itself, where it wants
76
+ it.
77
+
71
78
  Kit (`/adapters/tty/components`): `defaultRegistry()` with `Box, Row,
72
79
  Stack, Grid, Text, Button, Input, Select, Textarea, Checkbox, Switch,
73
80
  Table, Badge, Panel, JsonTree, ActionSlot` (`Select` is `Input`, `Switch`
@@ -77,6 +84,10 @@ render their children; childless ones surface `label`/`title` + `count`)
77
84
  and the helpers (`stack`, `inline`, `inlineText`, `pad`, `truncate`,
78
85
  `indent`, `str`, `num`, `bool`, `iconGlyph`).
79
86
 
87
+ `Box` and `Stack` stack their children. `Row` and `Grid` call `inline`: the
88
+ children join on one line, two spaces apart, while each is a single line,
89
+ and stack as soon as one is not.
90
+
80
91
  ---
81
92
 
82
93
  ## `@niscorp/nova/adapters/ink`
@@ -96,9 +107,10 @@ An Ink component kit for the React adapter's walker — ESM-only, `ink` and
96
107
  provide `FrameControlsContext` at the root (`setTyping` — a focused
97
108
  input claims typed digits as text, so the host's number handling must
98
109
  stand down). Without providers the kit renders markerless and Tab-only.
99
- - Marker identity: click-kinds resolve by `value` (a list's rows share one
100
- ref and differ by payload), model-kinds by `occurrence` (their value
101
- changes as you type). `markerFocusId(n)` is the ink focus id a marked
110
+ - Marker identity: a pressable passes its `value` (a list's rows share one
111
+ ref and differ by payload), a `Table` row passes its `value` and its
112
+ `occurrence` (its place among the rows), and an `Input` or a `Checkbox`
113
+ passes neither and resolves by its ref alone. `markerFocusId(n)` is the ink focus id a marked
102
114
  component adopts — `useFocusManager().focus(markerFocusId(n))` jumps to
103
115
  it.
104
116
 
@@ -110,6 +122,10 @@ only); a focused Input holds a local draft, honours `debounce`, submits `ui:key
110
122
  Enter`, and forwards ↑/↓ to the server as `ui:key ArrowDown/ArrowUp` (a
111
123
  served palette moves its own highlight). Typed-digit handling is the
112
124
  host's job — the kit only displays markers and adopts their focus ids.
125
+ A `ref` on a container (`Box`, `Stack`, `Row`, `Grid`) makes it one focus
126
+ stop with a marker: Enter on it dispatches `ui:click` with its `value` prop
127
+ as payload. Enter in an Input sends a value `debounce` is still holding
128
+ before the `ui:key`.
113
129
 
114
130
  ### Exports
115
131
 
@@ -117,7 +133,8 @@ host's job — the kit only displays markers and adopts their focus ids.
117
133
  Textarea, Checkbox, Switch, Table, Badge, Panel, JsonTree, ActionSlot`
118
134
  (`Select` and `Textarea` are `Input`, `Switch` is `Checkbox`; the
119
135
  components are also exported by name);
120
- `fallback` (ref'd unknowns are focusable and click on Enter); `TextWrap`,
136
+ `fallback` (ref'd unknowns are focusable and click on Enter; childless
137
+ ones surface `label`/`title` + `count`); `TextWrap`,
121
138
  `ErrorMarker`; `useActionable(novaRef, value)` — the full interactive
122
139
  convention (marker + focus + Enter-click) for an app's own components;
123
140
  `useMarker`, `Mark`, `markerFocusId`, `CanvasMarkersContext`,
@@ -127,4 +144,6 @@ Layout mapping: Grid honours `weights` (flex ratios) and `columns`
127
144
  (wrapping tracks); Row honours `justify`/`align`; containers honour
128
145
  `border` (incl. sided `'r'`/`'l'`/`'t'`/`'b'`), `padding`, `w`/`width`
129
146
  (px→cells at ~8px/cell, percent passthrough), `grow`. What has no
130
- terminal analog (bg, radius, glow) is absent, never faked.
147
+ terminal analog (bg, radius, glow) is absent, never faked. `JsonTree`
148
+ prints the TTY kit's lines, which do not fold: four levels are open, and
149
+ each object or array lists its first 20 entries.
@@ -1,6 +1,6 @@
1
1
  'use strict';
2
2
 
3
- var chunkOE527MXF_cjs = require('../../../chunk-OE527MXF.cjs');
3
+ var chunk3XFQI5P2_cjs = require('../../../chunk-3XFQI5P2.cjs');
4
4
  var chunkQ7SFCCGT_cjs = require('../../../chunk-Q7SFCCGT.cjs');
5
5
 
6
6
  // src/adapters/dom/components/components.ts
@@ -326,7 +326,7 @@ var fallback = ({ props, children }) => {
326
326
 
327
327
  // src/adapters/dom/components/registry.ts
328
328
  var defaultRegistry = () => {
329
- const registry = chunkOE527MXF_cjs.createComponentRegistry();
329
+ const registry = chunk3XFQI5P2_cjs.createComponentRegistry();
330
330
  registry.registerAll({
331
331
  Box,
332
332
  Row,
@@ -340,10 +340,8 @@ var defaultRegistry = () => {
340
340
  Checkbox,
341
341
  Switch: Checkbox,
342
342
  Table,
343
- // introspection primitives (used by nova/devtools; useful anywhere)
344
343
  Panel,
345
344
  JsonTree,
346
- // the per-instance boundary from a flattened shell tree — pass-through
347
345
  ActionSlot
348
346
  });
349
347
  return registry;