@niscorp/nova 0.1.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 (170) hide show
  1. package/ACTION_DOCS.md +552 -0
  2. package/ADAPTER.md +170 -0
  3. package/DESIGN.md +719 -0
  4. package/I18N_DOCS.md +224 -0
  5. package/LAYOUT_DOCS.md +505 -0
  6. package/LICENSE +202 -0
  7. package/REACT_DOCS.md +562 -0
  8. package/README.md +379 -0
  9. package/SHELL_DOCS.md +615 -0
  10. package/TERMINAL_DOCS.md +124 -0
  11. package/dist/adapters/dom/components/index.cjs +473 -0
  12. package/dist/adapters/dom/components/index.cjs.map +1 -0
  13. package/dist/adapters/dom/components/index.d.cts +48 -0
  14. package/dist/adapters/dom/components/index.d.ts +48 -0
  15. package/dist/adapters/dom/components/index.js +420 -0
  16. package/dist/adapters/dom/components/index.js.map +1 -0
  17. package/dist/adapters/dom/index.cjs +171 -0
  18. package/dist/adapters/dom/index.cjs.map +1 -0
  19. package/dist/adapters/dom/index.d.cts +29 -0
  20. package/dist/adapters/dom/index.d.ts +29 -0
  21. package/dist/adapters/dom/index.js +15 -0
  22. package/dist/adapters/dom/index.js.map +1 -0
  23. package/dist/adapters/dom/server.cjs +129 -0
  24. package/dist/adapters/dom/server.cjs.map +1 -0
  25. package/dist/adapters/dom/server.d.cts +15 -0
  26. package/dist/adapters/dom/server.d.ts +15 -0
  27. package/dist/adapters/dom/server.js +37 -0
  28. package/dist/adapters/dom/server.js.map +1 -0
  29. package/dist/adapters/ink/index.d.ts +75 -0
  30. package/dist/adapters/ink/index.js +472 -0
  31. package/dist/adapters/ink/index.js.map +1 -0
  32. package/dist/adapters/react/components/index.cjs +552 -0
  33. package/dist/adapters/react/components/index.cjs.map +1 -0
  34. package/dist/adapters/react/components/index.d.cts +30 -0
  35. package/dist/adapters/react/components/index.d.ts +30 -0
  36. package/dist/adapters/react/components/index.js +12 -0
  37. package/dist/adapters/react/components/index.js.map +1 -0
  38. package/dist/adapters/react/index.cjs +1526 -0
  39. package/dist/adapters/react/index.cjs.map +1 -0
  40. package/dist/adapters/react/index.d.cts +149 -0
  41. package/dist/adapters/react/index.d.ts +149 -0
  42. package/dist/adapters/react/index.js +12 -0
  43. package/dist/adapters/react/index.js.map +1 -0
  44. package/dist/adapters/tty/components/index.cjs +255 -0
  45. package/dist/adapters/tty/components/index.cjs.map +1 -0
  46. package/dist/adapters/tty/components/index.d.cts +40 -0
  47. package/dist/adapters/tty/components/index.d.ts +40 -0
  48. package/dist/adapters/tty/components/index.js +187 -0
  49. package/dist/adapters/tty/components/index.js.map +1 -0
  50. package/dist/adapters/tty/index.cjs +76 -0
  51. package/dist/adapters/tty/index.cjs.map +1 -0
  52. package/dist/adapters/tty/index.d.cts +47 -0
  53. package/dist/adapters/tty/index.d.ts +47 -0
  54. package/dist/adapters/tty/index.js +76 -0
  55. package/dist/adapters/tty/index.js.map +1 -0
  56. package/dist/adapters/vue/components/index.cjs +619 -0
  57. package/dist/adapters/vue/components/index.cjs.map +1 -0
  58. package/dist/adapters/vue/components/index.d.cts +224 -0
  59. package/dist/adapters/vue/components/index.d.ts +224 -0
  60. package/dist/adapters/vue/components/index.js +12 -0
  61. package/dist/adapters/vue/components/index.js.map +1 -0
  62. package/dist/adapters/vue/index.cjs +747 -0
  63. package/dist/adapters/vue/index.cjs.map +1 -0
  64. package/dist/adapters/vue/index.d.cts +98 -0
  65. package/dist/adapters/vue/index.d.ts +98 -0
  66. package/dist/adapters/vue/index.js +127 -0
  67. package/dist/adapters/vue/index.js.map +1 -0
  68. package/dist/agent/index.cjs +178 -0
  69. package/dist/agent/index.cjs.map +1 -0
  70. package/dist/agent/index.d.cts +28 -0
  71. package/dist/agent/index.d.ts +28 -0
  72. package/dist/agent/index.js +30 -0
  73. package/dist/agent/index.js.map +1 -0
  74. package/dist/chunk-2MNLEL45.js +47 -0
  75. package/dist/chunk-2MNLEL45.js.map +1 -0
  76. package/dist/chunk-3HGE3VWK.js +753 -0
  77. package/dist/chunk-3HGE3VWK.js.map +1 -0
  78. package/dist/chunk-4ZID7UX5.js +549 -0
  79. package/dist/chunk-4ZID7UX5.js.map +1 -0
  80. package/dist/chunk-7B3RDENH.js +1982 -0
  81. package/dist/chunk-7B3RDENH.js.map +1 -0
  82. package/dist/chunk-7S5BNPUS.js +54 -0
  83. package/dist/chunk-7S5BNPUS.js.map +1 -0
  84. package/dist/chunk-7TS3YVQR.js +114 -0
  85. package/dist/chunk-7TS3YVQR.js.map +1 -0
  86. package/dist/chunk-EG2RUXJN.js +266 -0
  87. package/dist/chunk-EG2RUXJN.js.map +1 -0
  88. package/dist/chunk-GVBBL36G.js +429 -0
  89. package/dist/chunk-GVBBL36G.js.map +1 -0
  90. package/dist/chunk-I5D2R5UA.js +753 -0
  91. package/dist/chunk-I5D2R5UA.js.map +1 -0
  92. package/dist/chunk-IGLCWXQ3.js +304 -0
  93. package/dist/chunk-IGLCWXQ3.js.map +1 -0
  94. package/dist/chunk-JI7ZRESP.js +64 -0
  95. package/dist/chunk-JI7ZRESP.js.map +1 -0
  96. package/dist/chunk-L5223LLX.js +31 -0
  97. package/dist/chunk-L5223LLX.js.map +1 -0
  98. package/dist/chunk-LA3BSEMX.js +1905 -0
  99. package/dist/chunk-LA3BSEMX.js.map +1 -0
  100. package/dist/chunk-OAMC6R6E.js +121 -0
  101. package/dist/chunk-OAMC6R6E.js.map +1 -0
  102. package/dist/chunk-OGD5CCMZ.js +62 -0
  103. package/dist/chunk-OGD5CCMZ.js.map +1 -0
  104. package/dist/chunk-PF4OJTYU.js +199 -0
  105. package/dist/chunk-PF4OJTYU.js.map +1 -0
  106. package/dist/chunk-PZ5AY32C.js +9 -0
  107. package/dist/chunk-PZ5AY32C.js.map +1 -0
  108. package/dist/chunk-RBU5PHN4.js +8 -0
  109. package/dist/chunk-RBU5PHN4.js.map +1 -0
  110. package/dist/chunk-RQB4PRPV.js +285 -0
  111. package/dist/chunk-RQB4PRPV.js.map +1 -0
  112. package/dist/chunk-V32EVEVM.js +464 -0
  113. package/dist/chunk-V32EVEVM.js.map +1 -0
  114. package/dist/chunk-ZITHBBF3.js +85 -0
  115. package/dist/chunk-ZITHBBF3.js.map +1 -0
  116. package/dist/devtools/index.cjs +1088 -0
  117. package/dist/devtools/index.cjs.map +1 -0
  118. package/dist/devtools/index.d.cts +33 -0
  119. package/dist/devtools/index.d.ts +33 -0
  120. package/dist/devtools/index.js +399 -0
  121. package/dist/devtools/index.js.map +1 -0
  122. package/dist/effects-CndX9K7D.d.cts +123 -0
  123. package/dist/effects-CndX9K7D.d.ts +123 -0
  124. package/dist/endpoints-CD-6Jl-H.d.ts +36 -0
  125. package/dist/endpoints-Dem-EdRx.d.cts +36 -0
  126. package/dist/i18n/index.cjs +299 -0
  127. package/dist/i18n/index.cjs.map +1 -0
  128. package/dist/i18n/index.d.cts +28 -0
  129. package/dist/i18n/index.d.ts +28 -0
  130. package/dist/i18n/index.js +180 -0
  131. package/dist/i18n/index.js.map +1 -0
  132. package/dist/index-CNfzSBe2.d.ts +93 -0
  133. package/dist/index-caZoXSwr.d.cts +93 -0
  134. package/dist/index.cjs +3723 -0
  135. package/dist/index.cjs.map +1 -0
  136. package/dist/index.d.cts +144 -0
  137. package/dist/index.d.ts +144 -0
  138. package/dist/index.js +15 -0
  139. package/dist/index.js.map +1 -0
  140. package/dist/migrations/index.cjs +635 -0
  141. package/dist/migrations/index.cjs.map +1 -0
  142. package/dist/migrations/index.d.cts +97 -0
  143. package/dist/migrations/index.d.ts +97 -0
  144. package/dist/migrations/index.js +50 -0
  145. package/dist/migrations/index.js.map +1 -0
  146. package/dist/palette-CP0wd3bE.d.ts +15 -0
  147. package/dist/palette-lm0bU9i5.d.cts +15 -0
  148. package/dist/primitive-props-BH_EJWIe.d.cts +100 -0
  149. package/dist/primitive-props-BH_EJWIe.d.ts +100 -0
  150. package/dist/primitive-props-CGoJvmcH.d.cts +100 -0
  151. package/dist/primitive-props-CGoJvmcH.d.ts +100 -0
  152. package/dist/reflect/index.cjs +998 -0
  153. package/dist/reflect/index.cjs.map +1 -0
  154. package/dist/reflect/index.d.cts +125 -0
  155. package/dist/reflect/index.d.ts +125 -0
  156. package/dist/reflect/index.js +13 -0
  157. package/dist/reflect/index.js.map +1 -0
  158. package/dist/schemas-DPdeFlCT.d.cts +38 -0
  159. package/dist/schemas-DPdeFlCT.d.ts +38 -0
  160. package/dist/schemas-pMyyuXV7.d.cts +47 -0
  161. package/dist/schemas-pMyyuXV7.d.ts +47 -0
  162. package/dist/types-Boh9ckdG.d.ts +194 -0
  163. package/dist/types-Brc7v_pS.d.ts +198 -0
  164. package/dist/types-ByNSwtUV.d.cts +20 -0
  165. package/dist/types-DdltMfw7.d.ts +20 -0
  166. package/dist/types-De0KpxfI.d.cts +198 -0
  167. package/dist/types-DhHL0twe.d.ts +20 -0
  168. package/dist/types-Dv6JLmgo.d.cts +194 -0
  169. package/dist/types-Q80YtOQt.d.cts +20 -0
  170. package/package.json +237 -0
package/ACTION_DOCS.md ADDED
@@ -0,0 +1,552 @@
1
+ # Action — Author Guide
2
+
3
+ How to write nova actions. An action is a stateful unit: it owns a data store, runs lifecycle hooks, listens for events and messages, mutates its data, calls endpoints, and produces a layout that reads from its data. The shell drives instances of actions on canvases (see `SHELL_DOCS.md`).
4
+
5
+ This guide is for **authoring** actions. For the architecture see `DESIGN.md`.
6
+
7
+ ---
8
+
9
+ ## A first action
10
+
11
+ ```ts
12
+ import type { ActionDefinition } from '@niscorp/nova';
13
+
14
+ const counter: ActionDefinition = {
15
+ id: 'counter',
16
+ data: { count: 0 },
17
+ layout: {
18
+ component: 'Stack',
19
+ props: { direction: 'column', gap: 16, padding: 24 },
20
+ children: [
21
+ { component: 'Text', props: { size: 'xl', weight: 'bold' }, children: 'Count: {{$.count}}' },
22
+ { component: 'Stack', props: { direction: 'row', gap: 8 }, children: [
23
+ { component: 'Button', ref: 'inc', children: 'Increment' },
24
+ { component: 'Button', ref: 'dec', children: 'Decrement' },
25
+ ]},
26
+ ],
27
+ },
28
+ triggers: [
29
+ { event: 'ui:click', ref: 'inc', do: [{ increment: 'count' }] },
30
+ { event: 'ui:click', ref: 'dec', do: [{ decrement: 'count' }] },
31
+ ],
32
+ };
33
+ ```
34
+
35
+ This is a complete action definition. Pass it to a shell, push it onto a canvas, it runs.
36
+
37
+ ## What's in an `ActionDefinition`
38
+
39
+ ```ts
40
+ {
41
+ id: string; // required — stable identifier
42
+ name?: string; // human label (optional)
43
+ description?: string; // free-form description
44
+ title?: string; // resolvable instance label (e.g. '{{$.record.name}}'),
45
+ // exposed as instance.title for stack-nav chrome
46
+ layout?: LayoutNode | string; // inline layout, or an id in the layout store
47
+ data?: Record<string, unknown>; // initial data merged with input on mount
48
+ input?: Record<string, unknown>; // JSON Schema of the data keys an opener may seed —
49
+ // the openable-input contract (descriptive, not enforced)
50
+ triggers?: TriggerConfig[]; // event/message → step bindings
51
+ endpoints?: Record<string, EndpointConfig>; // named HTTP or local-function calls
52
+ lifecycle?: LifecycleConfig; // mount/unmount/suspend/resume hooks
53
+ }
54
+ ```
55
+
56
+ That's the entire surface. Everything else is composed from these fields.
57
+
58
+ ---
59
+
60
+ ## Data
61
+
62
+ The action's data is a plain object merged from `data` (defaults) + the `input` passed when the action is pushed onto a canvas. It's the **single source of truth** the layout reads from via bindings.
63
+
64
+ ```ts
65
+ data: {
66
+ count: 0,
67
+ user: { name: '', email: '' },
68
+ items: [],
69
+ loading: false,
70
+ }
71
+ ```
72
+
73
+ Bindings in the layout (`{{$.count}}`, `$.user.name`, etc.) resolve against this object. When mutations or `setData` change it, subscribers (the React adapter's `useRenderTree`, the inspector tabs, etc.) re-render automatically.
74
+
75
+ The data is **immutable from the outside** — every mutation produces a new top-level reference. Internally the store does structural sharing so unchanged subtrees keep their identity.
76
+
77
+ ---
78
+
79
+ ## Triggers
80
+
81
+ A trigger binds an event source to an ordered list of steps. When the event fires, the steps execute in sequence.
82
+
83
+ ```ts
84
+ triggers: [
85
+ // UI click on a component with ref="save"
86
+ { event: 'ui:click', ref: 'save', do: [...] },
87
+
88
+ // UI input change on a component with ref="email-field"
89
+ { event: 'ui:input', ref: 'email-field', do: [...] },
90
+
91
+ // Two-way model binding update
92
+ { event: 'ui:model', ref: 'name-input', do: [...] },
93
+
94
+ // Cross-action message bus subscription
95
+ { message: 'cart-updated', do: [...] },
96
+ ],
97
+ ```
98
+
99
+ ### Trigger fields
100
+
101
+ - **`event`** *(optional)* — UI event type. Common values: `ui:click`, `ui:input`, `ui:submit`, `ui:focus`, `ui:blur`, `ui:model`. Custom event names work too.
102
+ - **`message`** *(optional)* — message bus channel name. Listens via the shell's shared message bus, so this trigger fires from emits in any other action on any other canvas.
103
+ - **`ref`** *(optional)* — filter UI events by component ref. If unset, the trigger fires on every event of that type. Has no effect on message triggers.
104
+ - **`do`** *(required)* — ordered array of steps to run.
105
+
106
+ A trigger MUST have either `event` or `message`. Setting both is an error.
107
+
108
+ ### When triggers fire
109
+
110
+ Triggers attach when the action mounts and detach when it unmounts. While the action is **suspended** (another action is pushed on top), triggers stay attached but do **not** fire — a suspended action reacts to nothing until it resumes, and the runtime's abort signal prevents in-flight async work from completing. On resume the `mount` hook re-runs (see [Lifecycle hooks](#lifecycle-hooks)), so the action refreshes its own data instead of reacting while backgrounded.
111
+
112
+ A `ui:model` trigger observes the value the event wrote: the runtime applies a `ui:model` to its own model bindings **before** it dispatches the event to triggers, so a trigger's steps read the just-typed value, not the one the field held before the keystroke.
113
+
114
+ ---
115
+
116
+ ## Steps
117
+
118
+ A step is either a **mutation** (sync, modifies the data store) or an **effect** (may be async, touches the outside world). Steps in a trigger's `do` array execute in order; mutations are applied as a batch when an effect or the end of the list is reached.
119
+
120
+ ```ts
121
+ do: [
122
+ { set: 'loading', value: true }, // mutation
123
+ { call: 'fetchUser', onSuccess: [ // effect — the response lands at the endpoint's `target`
124
+ { set: 'loading', value: false }, // mutation
125
+ ]},
126
+ ],
127
+ ```
128
+
129
+ Mutations and effects share the same `do` slot — they're a discriminated union called `Step`.
130
+
131
+ ---
132
+
133
+ ## Mutations
134
+
135
+ Mutations are pure, sync operations that produce a new data store from the old one. There are 10 mutation kinds: `set`, `toggle`, `increment`, `decrement`, `push`, `pop`, `removeAt`, `move`, `clear`, `reset`.
136
+
137
+ ### `set`
138
+
139
+ Set a path to a literal value or copy from another path.
140
+
141
+ ```ts
142
+ { set: 'count', value: 0 } // literal
143
+ { set: 'user.name', value: 'Ada' } // nested path
144
+ { set: 'previous', from: 'current' } // copy from another path
145
+ ```
146
+
147
+ ### `toggle`
148
+
149
+ Flip a boolean.
150
+
151
+ ```ts
152
+ { toggle: 'isOpen' }
153
+ ```
154
+
155
+ If the field doesn't exist or isn't a boolean, it becomes `true` on first toggle.
156
+
157
+ ### `increment` / `decrement`
158
+
159
+ Add or subtract from a number.
160
+
161
+ ```ts
162
+ { increment: 'count' } // +1
163
+ { increment: 'count', by: 5 } // +5
164
+ { decrement: 'count', by: 2 } // -2
165
+ ```
166
+
167
+ If the field isn't a number, it's treated as 0.
168
+
169
+ ### `push` / `pop`
170
+
171
+ Append to or remove from the end of an array. **Note:** `push` / `pop` here are **mutations** that take a path string. The navigation `push`/`pop` effects (which take an object) live under [Effects](#effects).
172
+
173
+ ```ts
174
+ { push: 'items', value: { name: 'New item' } }
175
+ { pop: 'items' }
176
+ ```
177
+
178
+ ### `removeAt`
179
+
180
+ Remove an element at a specific index.
181
+
182
+ ```ts
183
+ { removeAt: 'items', index: 0 } // remove first
184
+ { removeAt: 'items', index: 2 } // remove third
185
+ ```
186
+
187
+ The index can also be a template string (e.g. `"{{@event.payload}}"`) resolved before applying.
188
+
189
+ ### `move`
190
+
191
+ Reorder an array element from one index to another.
192
+
193
+ ```ts
194
+ { move: 'items', from: 0, to: 2 }
195
+ { move: 'items', from: '{{@event.payload}}', to: 0 }
196
+ ```
197
+
198
+ `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.
199
+
200
+ ### `clear`
201
+
202
+ Empty an array or object, or set a primitive to its zero value.
203
+
204
+ ```ts
205
+ { clear: 'items' } // → []
206
+ { clear: 'user' } // → {}
207
+ { clear: 'count' } // → 0
208
+ ```
209
+
210
+ ### `reset`
211
+
212
+ Reset the entire data store to the action's `data` defaults.
213
+
214
+ ```ts
215
+ { reset: true }
216
+ ```
217
+
218
+ Use this in a "Cancel" or "Start over" handler.
219
+
220
+ ---
221
+
222
+ ## Effects
223
+
224
+ Effects can be async and may reach outside the action's data store. There are ten: `call`, `emit`, `reload`, and the navigation effects `push`, `pop`, `replace`, `popTo`, `resetTo`, `removeInstance`, `removeSelf`.
225
+
226
+ ### `call`
227
+
228
+ Invoke a named endpoint. Optional `onSuccess` and `onError` step branches run after the response.
229
+
230
+ ```ts
231
+ {
232
+ call: 'fetchUser',
233
+ onSuccess: [
234
+ { set: 'loading', value: false },
235
+ { set: 'user', from: 'fetchUserResponse' },
236
+ ],
237
+ onError: [
238
+ { set: 'loading', value: false },
239
+ { set: 'errorMessage', value: '{{@error.message}}' },
240
+ ],
241
+ }
242
+ ```
243
+
244
+ The `onError` branch has access to a special **`@error`** scope inside templates: `{{@error.message}}`, `{{@error.status}}`, `{{@error.data}}`. Use it to surface error messages in the UI.
245
+
246
+ If the endpoint name doesn't exist in the action's `endpoints`, the call fails with a synthetic error and `onError` fires.
247
+
248
+ ### `emit`
249
+
250
+ Publish a message on the shell's shared message bus. Other actions (on any canvas) with a matching `message:` trigger receive it.
251
+
252
+ ```ts
253
+ { emit: { channel: 'cart-updated' } }
254
+ { emit: { channel: 'user-saved', payload: { id: '{{$.user.id}}' } } }
255
+ ```
256
+
257
+ The `payload` is resolved against the current data — templates and bindings work.
258
+
259
+ ### `push`, `pop`, `replace`
260
+
261
+ Navigation effects. They escape from the action via the shell's `onNavigate` callback and become canvas operations.
262
+
263
+ ```ts
264
+ { push: { action: 'edit-user' } } // push onto current canvas
265
+ { push: { action: 'login', canvas: 'modal' } } // push onto a different canvas
266
+ { push: { action: 'edit-user', input: { id: 'u_42' } } } // with initial data
267
+ { push: { action: 'edit-user', with: ['modal-frame'] } } // composed with fragments
268
+
269
+ { pop: true } // pop the current action
270
+
271
+ { replace: { action: 'step2' } } // replace current with another
272
+ { replace: { action: 'article-a', canvas: 'content' } } // on a different canvas
273
+ ```
274
+
275
+ The `pop` effect uses `pop: true` (a literal boolean) to distinguish it from the `pop` mutation (which takes a string path).
276
+
277
+ `push`, `replace`, and `resetTo` accept an optional `with: [...]` — ids of `ActionFragment`s composed into the action before it is instantiated. Each fragment wraps the action (the action's layout fills the fragment's `{ slot: 'body' }`) and contributes its triggers/data; the action wins on conflict.
278
+
279
+ `input` values resolve against the current data plus the firing event, so a trigger can pass dynamic data to the action it opens — e.g. `input: { record: '@event.payload' }` or `input: { id: '@event.payload.todo_id' }`.
280
+
281
+ ### `popTo`, `resetTo`
282
+
283
+ Stack-navigation effects.
284
+
285
+ ```ts
286
+ { popTo: { instance: 'act-3' } } // pop until this instance is on top
287
+ { popTo: { canvas: 'main', instance: 'act-3' } }
288
+
289
+ { resetTo: { action: 'home' } } // clear the canvas, push a new root
290
+ { resetTo: { action: 'home', canvas: 'main', input: {...}, with: [...] } }
291
+ ```
292
+
293
+ `popTo` unmounts everything above the given instance (a no-op if it isn't in the stack) — what a breadcrumb fires. `resetTo` clears the whole stack and pushes one new root — what a screen-level nav fires so drilling into a record doesn't leave a stale stack beneath the new screen.
294
+
295
+ ### `reload`
296
+
297
+ ```ts
298
+ { reload: true } // re-run THIS instance's mount hook
299
+ ```
300
+
301
+ Re-reads the firing instance in place: same instance, same data object, no navigation. It re-runs whatever the action does on `mount`, which is the only definition of "current" the action itself has — a caller never names endpoints.
302
+
303
+ It exists for `mode: 'list'` canvases. A stack canvas suspends what it covers and `resume` already re-runs `mount`, so a revealed action is never stale; a list suspends nothing, so a card mounted once and opened much later would answer with the data it loaded then. `{ reload: true }` is what "opening it" means there. Harmless on an action with no `mount` hook.
304
+
305
+ ---
306
+
307
+ ## Endpoints
308
+
309
+ An endpoint is either a named HTTP call or a named local function call (`EndpointConfigSchema` is the union of the two). Define them once in the action, invoke them via `{call: 'name'}` from any trigger.
310
+
311
+ ```ts
312
+ endpoints: {
313
+ fetchUser: {
314
+ url: '/api/users/{{$.userId}}',
315
+ method: 'GET',
316
+ target: 'user',
317
+ },
318
+ saveUser: {
319
+ url: '/api/users/{{$.user.id}}',
320
+ method: 'POST',
321
+ headers: {
322
+ 'content-type': 'application/json',
323
+ 'authorization': 'Bearer {{$.token}}',
324
+ },
325
+ request: { name: { $ref: '$.user.name' }, email: { $ref: '$.user.email' } },
326
+ target: 'savedUser',
327
+ errorTarget: 'lastError',
328
+ },
329
+ }
330
+ ```
331
+
332
+ ### HTTP endpoint fields
333
+
334
+ - **`url`** *(required)* — template URL. Bindings work.
335
+ - **`method`** *(required)* — `GET` | `POST` | `PUT` | `PATCH` | `DELETE`.
336
+ - **`headers`** *(optional)* — object of header name → value. Values can be templated; names cannot.
337
+ - **`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.
338
+ - **`response`** *(optional)* — a transform config run by the injected evaluator over the reply **exactly as received** (`$` is the reply — object, array, or scalar; no wrapping) to produce the value stored at `target`. Declaring it without an injected transform is a hard error — never the unshaped reply.
339
+ - **`target`** *(optional)* — data path to write the (possibly transformed) response into on success. If unset, the response is discarded.
340
+ - **`errorTarget`** *(optional)* — data path to write the error info into on failure.
341
+
342
+ The evaluator is dependency-injected: `ShellConfig.transform` is a `(config, source) => unknown` function nova never interprets — the host wires in Prism's `evaluate` (or anything else). Initial data is never transformed.
343
+
344
+ ### Function endpoints
345
+
346
+ The other side of the union: a call to a host-registered function instead of a URL.
347
+
348
+ ```ts
349
+ endpoints: {
350
+ exportCsv: { fn: 'exportCsv', target: 'exportResult' },
351
+ }
352
+ ```
353
+
354
+ - **`fn`** *(required)* — key of a function registered in `ShellConfig.functions`. The handler receives `(data, signal)` and its return value is stored at `target`. An unregistered name fails the call.
355
+ - **`target`** / **`errorTarget`** — as above.
356
+
357
+ ### The fetch implementation
358
+
359
+ The runtime needs a fetch implementation injected. The shell takes a `fetch?: FetchFn` config option. Default is the global `fetch` if available; otherwise endpoint calls fail.
360
+
361
+ For tests and the showroom, you inject a mock:
362
+
363
+ ```ts
364
+ const mockFetch: FetchFn = async (url) => ({
365
+ ok: true,
366
+ status: 200,
367
+ json: async () => ({ name: 'Ada Lovelace' }),
368
+ text: async () => '{"name":"Ada Lovelace"}',
369
+ });
370
+
371
+ createShell({ ..., fetch: mockFetch });
372
+ ```
373
+
374
+ ---
375
+
376
+ ## Lifecycle hooks
377
+
378
+ Run steps when the action transitions through its lifecycle states. Four hooks: `mount`, `unmount`, `suspend`, `resume`.
379
+
380
+ ```ts
381
+ lifecycle: {
382
+ mount: [
383
+ { call: 'fetchUser', onSuccess: [{ set: 'loading', value: false }] },
384
+ ],
385
+ unmount: [
386
+ { call: 'savePartialState' },
387
+ ],
388
+ suspend: [
389
+ { set: 'wasSuspended', value: true },
390
+ ],
391
+ resume: [
392
+ { set: 'wasSuspended', value: false },
393
+ ],
394
+ }
395
+ ```
396
+
397
+ ### When each fires
398
+
399
+ - **`mount`** — when the action is pushed onto a canvas (after `data` and `input` are merged, before triggers attach), and **again on every resume**, before the `resume` hook. A suspended action ignores everything while backgrounded, so re-running `mount` is what brings its data current when it is revealed again.
400
+ - **`suspend`** — when another action is pushed on top, this action transitions from `active` → `suspended`. Triggers stay attached but do not fire while suspended.
401
+ - **`resume`** — when the action above is popped, this action transitions from `suspended` → `active`. Runs after the re-run of `mount`.
402
+ - **`unmount`** — once, when the action is popped from the canvas (or the shell is disposed). Triggers detach AFTER the unmount steps run.
403
+
404
+ In **strict mode** (set `strict: true` on the shell), a failure inside a lifecycle hook surfaces on the next shell call as a `LifecycleError`. In **lax mode** (the default), it routes to the shell's `onError` telemetry and the lifecycle continues.
405
+
406
+ ---
407
+
408
+ ## The bindings inside steps
409
+
410
+ Step values can use bindings — same syntax as layout bindings.
411
+
412
+ ```ts
413
+ // Set with a literal
414
+ { set: 'count', value: 0 }
415
+
416
+ // Set from another path (copy)
417
+ { set: 'previous', from: 'current' }
418
+
419
+ // Increment by a value from data
420
+ { increment: 'total', by: '{{$.delta}}' } // Wait — `by` is typed as number; templates here would need
421
+ // the bare `{{ expr }}` form to preserve the number type.
422
+ ```
423
+
424
+ Endpoint URL templates, body templates, header templates all resolve against the current data. The `@error` scope is available inside `onError` chains.
425
+
426
+ ---
427
+
428
+ ## The `@error` scope
429
+
430
+ When an endpoint call fails and the `onError` chain runs, the error is in scope as `@error`. Reference it via templates:
431
+
432
+ ```ts
433
+ onError: [
434
+ { set: 'errorMessage', value: '{{@error.message}}' },
435
+ { set: 'errorStatus', value: '{{@error.status}}' },
436
+ ],
437
+ ```
438
+
439
+ Fields available on `@error`:
440
+ - `message: string`
441
+ - `status: number` (HTTP status, or 0 for network/function errors)
442
+ - `data: unknown` (the response body if any)
443
+ - `aborted?: boolean` (true if the call was aborted by an unmount)
444
+
445
+ ---
446
+
447
+ ## Action runtime methods
448
+
449
+ When you call `shell.getRuntime(instanceId)` you get a `PublicActionRuntime`:
450
+
451
+ ```ts
452
+ type PublicActionRuntime = {
453
+ readonly instance: ActionInstance;
454
+ readonly definition: ActionDefinition;
455
+ getData: () => Record<string, unknown>;
456
+ setData: (next: Record<string, unknown>) => void;
457
+ render: () => RenderNode[];
458
+ onDataChange: (handler: DataChangeHandler) => Unsubscribe;
459
+ onStatusChange: (handler: StatusChangeHandler) => Unsubscribe;
460
+ };
461
+ ```
462
+
463
+ - **`getData`** — synchronous snapshot of the data store.
464
+ - **`setData`** — replace the entire data store with a new object. Use for tooling/debugging (the showroom's editable Data tab uses this). Normal mutations should go through triggers.
465
+ - **`render`** — produce the current `RenderNode[]` tree.
466
+ - **`onDataChange`** — subscribe to data changes. Returns an unsubscribe.
467
+ - **`onStatusChange`** — subscribe to status changes (`active`/`suspended`/`unmounted`). Returns an unsubscribe.
468
+
469
+ You don't construct runtimes directly — the shell does that. You access them via `shell.getRuntime(instanceId)`.
470
+
471
+ ---
472
+
473
+ ## Errors
474
+
475
+ Action-time errors all extend `NovaError`:
476
+
477
+ - **`LifecycleError`** — a step inside a lifecycle hook failed
478
+ - **`UnknownActionError`** — `shell.push(canvas, 'name')` where `'name'` isn't in `actions`
479
+ - **`DefinitionValidationError`** — an action definition fails Zod validation at shell init
480
+
481
+ In strict mode all of these throw. In lax mode they route through the shell's `onError` callback.
482
+
483
+ ---
484
+
485
+ ## Validation
486
+
487
+ Action definitions are validated against `ActionDefinitionSchema` when you pass them to `createShell`. Invalid definitions throw `DefinitionValidationError` with structured failures listing every Zod issue. So you cannot accidentally run an action with a malformed shape.
488
+
489
+ ### `auditAction` — static wiring audit
490
+
491
+ A definition can parse, mount, and render politely while being broken at click time. `auditAction(def, { catalog? })` cross-references the definition against itself: layout bindings ↔ `data` defaults, layout refs ↔ triggers (dead chrome and phantom triggers both), `call` steps ↔ endpoint names, endpoint targets ↔ `data`, mutation paths ↔ `data`, and — when a `catalog` of `{ id, input }` entries is given — push/replace/resetTo targets and their seeded input keys. Returns `{ ok, issues: string[] }` with precise messages.
492
+
493
+ Scope: SELF-CONTAINED definitions with inline layouts (generated actions above all). Hand-authored actions that receive triggers from fragments or bind stored layouts should audit the COMPOSED definition, or skip.
494
+
495
+ ---
496
+
497
+ ## Quick reference
498
+
499
+ ```ts
500
+ type ActionDefinition = {
501
+ id: string;
502
+ name?: string;
503
+ description?: string;
504
+ title?: string; // resolvable instance label for stack-nav chrome
505
+ layout?: LayoutNode | string;
506
+ data?: Record<string, unknown>;
507
+ input?: Record<string, unknown>; // JSON Schema — the openable-input contract
508
+ triggers?: TriggerConfig[];
509
+ endpoints?: Record<string, EndpointConfig>;
510
+ lifecycle?: LifecycleConfig;
511
+ };
512
+
513
+ type TriggerConfig = {
514
+ event?: string; // OR message
515
+ message?: string;
516
+ ref?: string;
517
+ do: Step[];
518
+ };
519
+
520
+ type Step = Mutation | Effect;
521
+
522
+ // Mutations
523
+ { set: string, value: unknown }
524
+ { set: string, from: string }
525
+ { toggle: string }
526
+ { increment: string, by?: number }
527
+ { decrement: string, by?: number }
528
+ { push: string, value: unknown }
529
+ { pop: string }
530
+ { removeAt: string, index: number | string }
531
+ { move: string, from: number | string, to: number | string }
532
+ { clear: string }
533
+ { reset: true }
534
+
535
+ // Effects
536
+ { call: string, onSuccess?: Step[], onError?: Step[] }
537
+ { emit: { channel: string, payload?: unknown } }
538
+ { push: { action: string, canvas?: string, input?: object, with?: string[] } }
539
+ { pop: true }
540
+ { replace: { action: string, canvas?: string, input?: object, with?: string[] } }
541
+ { popTo: { canvas?: string, instance: string } }
542
+ { resetTo: { action: string, canvas?: string, input?: object, with?: string[] } }
543
+ { removeInstance: { canvas?: string, instance: string } }
544
+ { removeSelf: true }
545
+ { reload: true }
546
+
547
+ // Endpoints (EndpointConfig = HTTP | Function)
548
+ { url: string, method: string, headers?: object, request?: unknown, response?: unknown, target?: string, errorTarget?: string }
549
+ { fn: string, target?: string, errorTarget?: string }
550
+ ```
551
+
552
+ For wiring actions onto a canvas via the shell, see `SHELL_DOCS.md`. For the layout language actions render through, see `LAYOUT_DOCS.md`.