@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/ADAPTER.md ADDED
@@ -0,0 +1,170 @@
1
+ # Nova adapter contract
2
+
3
+ Nova's core is framework-free. It renders layout trees into `RenderNode[]`
4
+ and owns all state, events, and subscriptions. An adapter binds that to a UI
5
+ framework. Adapters live under `src/adapters/`, one folder per framework with
6
+ its own export subpath. Five reference implementations ship: the React
7
+ adapter (`@niscorp/nova/adapters/react`), the Vue adapter
8
+ (`@niscorp/nova/adapters/vue` — Vue 3 render functions in plain TS, no SFC
9
+ compiler; provide/inject for the render context, composables bridging the
10
+ shell subscriptions into shallowRefs, children handed to a component as its
11
+ default slot, the same primitive kit at `/adapters/vue/components` over the
12
+ SAME props schemas as React's), the plain-DOM adapter
13
+ (`@niscorp/nova/adapters/dom`, `createDomView` — no framework at all), the
14
+ line-terminal adapter (`@niscorp/nova/adapters/tty`, `createTtyView` — a
15
+ pure render to `{ text, interactives }`; the host maps commands onto the
16
+ numbered interactives), and the full-screen terminal kit
17
+ (`@niscorp/nova/adapters/ink` — an Ink component vocabulary riding the React
18
+ adapter's walker; Tab cycles focus, Enter activates). A Svelte adapter is
19
+ a sibling folder, built the same way.
20
+
21
+ A react-shaped host that is not the DOM threads three optional seams through
22
+ `NovaRenderProvider`: `fallback` (unregistered names render their children
23
+ instead of an error marker), `textWrapper` (ink forbids bare strings outside
24
+ `<Text>`; the DOM renders them raw), and `errorMarker` (the default is a
25
+ `<span>`, which crashes a non-DOM renderer). Browser consumers omit all
26
+ three. A `ref`'d node rendered by a permissive fallback must still be
27
+ actionable — the TTY walker marks refs universally, so a kit-level fallback
28
+ (ink's) carries the focus + click convention itself.
29
+
30
+ An adapter imports only from `@niscorp/nova`'s public surface (plus its own
31
+ framework). Core never imports from an adapter.
32
+
33
+ ## Obligations
34
+
35
+ An adapter must provide six things.
36
+
37
+ ### 1. A RenderNode walker
38
+
39
+ Map `RenderNode[]` to framework elements:
40
+
41
+ - `text` → a text node.
42
+ - `fragment` → its children, keyless grouping.
43
+ - `error` → a visible marker carrying `code` and `message` (the React
44
+ adapter renders a `<span data-nova-error>`; match that convention).
45
+ - `component` → look the name up in the registry; unknown names render an
46
+ error marker with code `COMPONENT_NOT_FOUND`, never throw.
47
+
48
+ Inject framework props from the node using the core constants:
49
+ `node.model` → `NOVA_MODEL_PROP` (`{ ref, path }`), `node.ref` →
50
+ `NOVA_REF_PROP` (string). Spread `node.props` on top.
51
+
52
+ List identity comes from core's `renderNodeKey(node, index)`. Do not invent
53
+ key rules.
54
+
55
+ ### 2. Dependency injection for registry, dispatch, publish
56
+
57
+ Rendered components never touch the shell. The adapter provides a component
58
+ registry, a `dispatch(event)` function, and a `publish(channel, payload)`
59
+ function through the framework's DI (React context, Vue provide/inject).
60
+ Without a shell, dispatch and publish are no-ops so static layouts render
61
+ with no event infrastructure.
62
+
63
+ ### 3. Subscription bindings
64
+
65
+ Bridge core subscriptions into the framework's reactivity:
66
+
67
+ - `shell.onStateChange(handler)` — whole-shell snapshots.
68
+ - `shell.onCanvasChange(canvasId, handler)` — one canvas; the shell owns
69
+ the equality check and only fires on meaningful change.
70
+ - `runtime.onDataChange(handler)` / `runtime.onStatusChange(handler)` — one
71
+ action instance (via `shell.getRuntime(instanceId)`).
72
+
73
+ Trees come from `shell.getShellRenderTree()`, `shell.getCanvasRenderTree(id)`,
74
+ and `runtime.render()`. Recompute on the matching subscription, not on a
75
+ timer or a broader signal.
76
+
77
+ A remote renderer (a moss terminal) has no shell to subscribe to; it is
78
+ handed core's `RenderApi` instead — `frame()`, `canvasTree(canvasId)`,
79
+ `dispatch(canvasId, event)`, `publish(channel, payload?)` — and re-renders
80
+ when its host says so. The DOM adapter's `createDomView` consumes exactly
81
+ this shape.
82
+
83
+ A LOCAL shell is read as that same shape by core's `shellView(shell)` —
84
+ `{ api, subscribe }`: the shell's own trees as they stand, its own dispatch
85
+ (an event that names no origin goes to the canvas's active instance), and one
86
+ coalesced call per burst of changes. So an adapter written against `RenderApi`
87
+ draws a shell beside it with no second code path — the DOM adapter's
88
+ `mountShell(root, registry, shell)` is `createDomView` over a `shellView` —
89
+ and an empty canvas is `[]` either way (`canvasTreeOf`).
90
+
91
+ **Drawing to a string.** An adapter that can draw where there is no browser
92
+ lets a shell arrive as markup: React and Vue through their own server
93
+ renderers, the DOM adapter through `renderToString(registry, api, { window })`
94
+ (`@niscorp/nova/adapters/dom/server` — the host hands in a DOM; nova depends
95
+ on none). Await `shellSettled(shell)` first: an instance is `initializing`
96
+ until its mount hook has been awaited, so that is the moment the first screen
97
+ is whole. Adapters that adopt in place (React, Vue) hydrate over the markup; one
98
+ that rebuilds its root (DOM) replaces it with the same elements in one step.
99
+
100
+ ### 4. Structural slots and the component vocabulary
101
+
102
+ Register two structural components under the core names `CANVAS_SLOT_NAME`
103
+ and `ACTION_SLOT_NAME` — the shell's default layouts reference them:
104
+
105
+ - **CanvasSlot** (`{ canvasId }`): renders that canvas's tree; nothing when
106
+ `canvasId` is missing.
107
+ - **ActionSlot** (`{ instanceId }`): renders that instance's tree; nothing
108
+ when `instanceId` is missing. Wrap the dispatch handed to the instance's
109
+ subtree with core's `scopeDispatch(dispatch, instanceId)` so its UI events
110
+ reach its own triggers only. Do not reimplement the stamping rule.
111
+
112
+ `flattenRenderTree` resolves `CanvasSlot` markers away, but the `ActionSlot`
113
+ marker *survives* flattening: it arrives as a component node with
114
+ `props: { instanceId, canvasId, definitionId }`, `key: instanceId`, and the
115
+ instance's rendered tree as children. An adapter rendering flattened (served)
116
+ trees must key by instance so a swap remounts, and may read the identity
117
+ props (a slot wrapper's seam).
118
+
119
+ The registered ActionSlot's `propsSchema` stays the *authoring* contract —
120
+ `instanceId` only. The flatten-stamped identity props are runtime output,
121
+ never authored, so they don't belong in the schema (the layout agent's
122
+ palette reads it as "props you may set"). Do not validate served trees
123
+ against registry schemas — that checks output against an authoring contract.
124
+
125
+ Ship the primitive vocabulary — Stack, Text, Input, Button, Box at minimum,
126
+ plus the introspection primitives Panel and JsonTree (nova's devtools compose
127
+ against them) — with static `meta` (description + props schema) so registries
128
+ and agent tooling can introspect them. The DOM kit additionally ships Row,
129
+ Grid, Checkbox, Textarea, and Table, with Select and Switch as aliases of
130
+ Input and Checkbox.
131
+
132
+ ### 5. SlotWrapper persistence
133
+
134
+ If the adapter supports an app-supplied slot wrapper (animation, gating,
135
+ logging at the ActionSlot seam), the wrapper renders *persistently* — with
136
+ content or with none — so a presence-managing wrapper can animate an
137
+ instance leaving. The adapter hands the wrapper identity only (`canvasId`,
138
+ `instanceId`, the `ActionDefinition`), never live state; identity fields are
139
+ undefined while the slot is empty or exiting. Nova owns no timing.
140
+
141
+ ### 6. Remote round-trip obligations
142
+
143
+ The shell may be authoritative over a socket (moss serves canvas trees down,
144
+ `NovaEvent`s up), so a bound input's echo is *asynchronous* — the tree carrying
145
+ the value you just typed arrives a round trip later. Two behaviours that a local
146
+ shell gets for free (its echo is synchronous) an adapter must implement itself,
147
+ or bound inputs drop keystrokes the moment the shell is remote:
148
+
149
+ - **Preserve the in-progress value of a focused input.** While a `model`-bound
150
+ input is focused, its local editing value is authoritative; an incoming tree
151
+ must not overwrite it. Release to the server value on blur. The React `Input`
152
+ holds a local `draft` (`null` = not editing, server wins); the DOM adapter
153
+ captures the focused element's value + caret and restores them across its full
154
+ rebuild (`captureFocus`/`restoreFocus`). Same rule, framework-shaped mechanism.
155
+ - **Honour the `debounce` prop on a `model`-bound node.** `props.debounce`
156
+ (milliseconds, default 0) coalesces `ui:model` dispatches; flush any pending
157
+ value on blur. Both reference adapters implement it — omitting it silently
158
+ makes a served `debounce` a no-op in your terminal, so the same layout behaves
159
+ differently across renderers.
160
+
161
+ These belong to *every* adapter because they are artifacts of the transport, not
162
+ of taste — unlike styling, hover, or animation, which *should* differ per kit.
163
+ The line is exactly that: an adapter shares nova's treatment of the round trip
164
+ and nothing about how pixels look.
165
+
166
+ A line renderer discharges both trivially: the TTY adapter has no focused
167
+ input (a `set <n> <text>` command is one atomic, complete value, so there is
168
+ no in-progress draft for an echo to clobber) and therefore nothing for
169
+ `debounce` to coalesce. The obligations bind any adapter that *does* hold
170
+ live input focus — a full-screen TUI included.