@verajs/renderer 0.2.2 → 0.3.1

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 (90) hide show
  1. package/README.md +757 -225
  2. package/dist/development/vera-renderer-elements.d.ts +39 -0
  3. package/dist/development/vera-renderer-elements.d.ts.map +1 -0
  4. package/dist/development/vera-renderer-elements.js +193 -0
  5. package/dist/development/vera-renderer-elements.js.map +1 -0
  6. package/dist/development/vera-renderer-hydrate-slots.d.ts +94 -0
  7. package/dist/development/vera-renderer-hydrate-slots.d.ts.map +1 -0
  8. package/dist/development/vera-renderer-hydrate-slots.js +325 -0
  9. package/dist/development/vera-renderer-hydrate-slots.js.map +1 -0
  10. package/dist/development/vera-renderer-hydration.d.ts +332 -0
  11. package/dist/development/vera-renderer-hydration.d.ts.map +1 -0
  12. package/dist/development/vera-renderer-hydration.js +902 -0
  13. package/dist/development/vera-renderer-hydration.js.map +1 -0
  14. package/dist/development/vera-renderer-keyed.d.ts +25 -8
  15. package/dist/development/vera-renderer-keyed.d.ts.map +1 -1
  16. package/dist/development/vera-renderer-keyed.js +843 -268
  17. package/dist/development/vera-renderer-keyed.js.map +1 -1
  18. package/dist/development/vera-renderer-multi-window.d.ts +5 -0
  19. package/dist/development/vera-renderer-multi-window.d.ts.map +1 -0
  20. package/dist/development/vera-renderer-multi-window.js +40 -0
  21. package/dist/development/vera-renderer-multi-window.js.map +1 -0
  22. package/dist/development/vera-renderer-namespaces.d.ts +64 -0
  23. package/dist/development/vera-renderer-namespaces.d.ts.map +1 -0
  24. package/dist/development/vera-renderer-namespaces.js +94 -0
  25. package/dist/development/vera-renderer-namespaces.js.map +1 -0
  26. package/dist/development/vera-renderer-native-elements.d.ts +13 -0
  27. package/dist/development/vera-renderer-native-elements.d.ts.map +1 -0
  28. package/dist/development/vera-renderer-native-elements.js +231 -0
  29. package/dist/development/vera-renderer-native-elements.js.map +1 -0
  30. package/dist/development/vera-renderer-portal.d.ts +29 -0
  31. package/dist/development/vera-renderer-portal.d.ts.map +1 -0
  32. package/dist/development/vera-renderer-portal.js +167 -0
  33. package/dist/development/vera-renderer-portal.js.map +1 -0
  34. package/dist/development/vera-renderer-profiler.d.ts +48 -96
  35. package/dist/development/vera-renderer-profiler.d.ts.map +1 -1
  36. package/dist/development/vera-renderer-profiler.js +2632 -2142
  37. package/dist/development/vera-renderer-profiler.js.map +1 -1
  38. package/dist/development/vera-renderer-slots.d.ts +88 -92
  39. package/dist/development/vera-renderer-slots.d.ts.map +1 -1
  40. package/dist/development/vera-renderer-slots.js +1834 -1237
  41. package/dist/development/vera-renderer-slots.js.map +1 -1
  42. package/dist/development/vera-renderer-spread.d.ts +7 -41
  43. package/dist/development/vera-renderer-spread.d.ts.map +1 -1
  44. package/dist/development/vera-renderer-spread.js +539 -477
  45. package/dist/development/vera-renderer-spread.js.map +1 -1
  46. package/dist/development/vera-renderer-tag.d.ts +12 -3
  47. package/dist/development/vera-renderer-tag.d.ts.map +1 -1
  48. package/dist/development/vera-renderer-tag.js +671 -513
  49. package/dist/development/vera-renderer-tag.js.map +1 -1
  50. package/dist/development/vera-renderer-until.d.ts +24 -0
  51. package/dist/development/vera-renderer-until.d.ts.map +1 -0
  52. package/dist/development/vera-renderer-until.js +83 -0
  53. package/dist/development/vera-renderer-until.js.map +1 -0
  54. package/dist/development/vera-renderer.d.ts +48 -96
  55. package/dist/development/vera-renderer.d.ts.map +1 -1
  56. package/dist/development/vera-renderer.js +2607 -2104
  57. package/dist/development/vera-renderer.js.map +1 -1
  58. package/dist/vera-renderer-elements.min.js +2 -0
  59. package/dist/vera-renderer-elements.min.js.map +1 -0
  60. package/dist/vera-renderer-hydrate-slots.min.js +2 -0
  61. package/dist/vera-renderer-hydrate-slots.min.js.map +1 -0
  62. package/dist/vera-renderer-hydration.min.js +3 -0
  63. package/dist/vera-renderer-hydration.min.js.map +1 -0
  64. package/dist/vera-renderer-keyed.min.js +1 -1
  65. package/dist/vera-renderer-keyed.min.js.map +1 -1
  66. package/dist/vera-renderer-multi-window.min.js +2 -0
  67. package/dist/vera-renderer-multi-window.min.js.map +1 -0
  68. package/dist/vera-renderer-namespaces.min.js +2 -0
  69. package/dist/vera-renderer-namespaces.min.js.map +1 -0
  70. package/dist/vera-renderer-native-elements.min.js +2 -0
  71. package/dist/vera-renderer-native-elements.min.js.map +1 -0
  72. package/dist/vera-renderer-portal.min.js +2 -0
  73. package/dist/vera-renderer-portal.min.js.map +1 -0
  74. package/dist/vera-renderer-slots.min.js +1 -1
  75. package/dist/vera-renderer-slots.min.js.map +1 -1
  76. package/dist/vera-renderer-spread.min.js +1 -1
  77. package/dist/vera-renderer-spread.min.js.map +1 -1
  78. package/dist/vera-renderer-tag.min.js +1 -1
  79. package/dist/vera-renderer-tag.min.js.map +1 -1
  80. package/dist/vera-renderer-until.min.js +2 -0
  81. package/dist/vera-renderer-until.min.js.map +1 -0
  82. package/dist/vera-renderer.min.js +1 -1
  83. package/dist/vera-renderer.min.js.map +1 -1
  84. package/package.json +52 -9
  85. package/dist/development/vera-renderer-hydrate.d.ts +0 -147
  86. package/dist/development/vera-renderer-hydrate.d.ts.map +0 -1
  87. package/dist/development/vera-renderer-hydrate.js +0 -3136
  88. package/dist/development/vera-renderer-hydrate.js.map +0 -1
  89. package/dist/vera-renderer-hydrate.min.js +0 -2
  90. package/dist/vera-renderer-hydrate.min.js.map +0 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @verajs/renderer
2
2
 
3
- The DOM renderer for VeraJS — <!--size:renderer.gzip-->4.58 KB<!--/size:renderer.gzip--> gzipped,
3
+ The DOM renderer for VeraJS — <!--size:renderer.gzip-->6.26 KB<!--/size:renderer.gzip--> gzipped,
4
4
  no dependencies, no build step required.
5
5
 
6
6
  Tagged templates parse once and clone; every render after the first walks only the value slots, so
@@ -18,7 +18,7 @@ there is no second call to make.
18
18
 
19
19
  <!-- recipe -->
20
20
  ```js
21
- import { init, createStore, render, wire, html } from '@verajs/core';
21
+ import { init, createStore, wire, html } from '@verajs/core';
22
22
  import { renderer } from '@verajs/renderer';
23
23
 
24
24
  wire([renderer]);
@@ -27,9 +27,10 @@ customElements.define(
27
27
  'click-counter',
28
28
  class extends HTMLElement {
29
29
  connectedCallback() {
30
- init(this, { mode: 'open' });
31
- const state = createStore({ count: 0 });
32
- render(() => html`<button @click=${() => state.count++}>Clicked ${state.count} times</button>`);
30
+ init({ host: this, shadow: 'open' }, () => {
31
+ const state = createStore({ count: 0 });
32
+ return () => html`<button @click=${() => state.count++}>Clicked ${state.count} times</button>`;
33
+ });
33
34
  }
34
35
  }
35
36
  );
@@ -37,13 +38,21 @@ customElements.define(
37
38
  document.body.append(document.createElement('click-counter'));
38
39
  ```
39
40
 
40
- Without it, core has no renderer at all: `render()` warns once in development and puts
41
+ Without it, core has no renderer at all: a component warns once (in every build) and puts
41
42
  nothing on the page. `@event`, `.prop` and `?bool` bindings are the first things to go missing.
42
43
 
44
+ **One renderer serves one core.** A renderer connects to the core whose `wire` it was last handed. On
45
+ a CDN page with two apps that load DIFFERENT copies of core (two versions) but the SAME renderer
46
+ URL, the second app's `wire([renderer])` takes the renderer over, and the first app's renders lose
47
+ their tracking. The renderer says so when it happens — `[vera] renderer-two-cores` (the code's entry
48
+ at `verajs.dev/e/renderer-two-cores` explains it). Give each app its own renderer URL beside its own core,
49
+ or share one core between them. (Under a bundler, or two apps on the same core URL, there is one
50
+ core and nothing to do.)
51
+
43
52
  ### `renderInto(result, container)`
44
53
 
45
54
  The same write, called directly — no reactivity, no lifecycle, no custom element. `wire([renderer])`
46
- registers exactly this function, so a component's `render()` ends up here; calling it yourself is how
55
+ registers exactly this function, so every component's render ends up here; calling it yourself is how
47
56
  you draw into a plain node, which is the incremental-adoption path and the way to test a template
48
57
  without spinning up an element.
49
58
 
@@ -54,14 +63,28 @@ import { html } from '@verajs/core';
54
63
  renderInto(html`<p>${count}</p>`, document.querySelector('#app'));
55
64
  ```
56
65
 
57
- It **owns its own range and nothing else**: the first call anchors a root part at a marker it
58
- appends, later calls with the same container reuse that part and walk only the value slots, and
59
- whatever was already in the container stays. It is not reactive — call it again to update, or use a
60
- component and let a store do it.
61
-
62
- It was named `render` until 0.2.0, which collided with core's `render` — a different function, with
63
- a different arity, that declares a *reactive* template and commits a component's setup. Both are
64
- public and both are documented, so a reader who knew one misread the other.
66
+ It **owns its own range and nothing else**: the first call anchors a root part between two markers
67
+ it appends, later calls with the same container reuse that part and walk only the value slots, and
68
+ content before and after that range stays — whatever was already in the container, and whatever other
69
+ code (a script, a browser extension) appends to it later, survives every re-render, a template swap
70
+ included. It is not reactive — call it again to update, or use a component and let a store do it.
71
+
72
+ **A component's shadow root is different: by default its template owns it** (`foreignNodes: 'drop'`). Foreign nodes
73
+ — nodes placed in a component's root by anything other than its own template — are left alone by an ordinary
74
+ re-render, and cleared with everything else when the template changes (a different template, text, a list, nothing);
75
+ development says so the first time. The root then needs no marker comments, which makes every shadow component
76
+ cheaper to create. A component that must keep what something else puts in its root says
77
+ `init({ host: this, shadow: 'open', foreignNodes: 'preserve' }, setup)`; `wire([renderer({ foreignNodes: 'preserve' })])`
78
+ makes that every component's default. Either way it covers component roots only: a container handed to `renderInto`
79
+ (`document.body`, `#app`) always keeps foreign nodes, as above. A shadow root that already holds something at its first
80
+ render (a server's declarative root, styles' `<style>` fallback) keeps its markers too. Light-DOM component roots are
81
+ not affected yet. One corner: a `hold()` at an owned root parks the root's whole content with the branch it parks, so
82
+ a foreign node there goes away with that branch and comes back with it rather than being dropped — as with a plain
83
+ element whose whole content is one binding.
84
+
85
+ It was named `render` until 0.2.0, which collided with core's `render` of the time — a different function, with
86
+ a different arity, that declared a *reactive* template and committed a component's setup (a setup now returns its
87
+ render instead). Both were public and both were documented, so a reader who knew one misread the other.
65
88
 
66
89
  ## Bindings
67
90
 
@@ -74,12 +97,23 @@ public and both are documented, so a reader who knew one misread the other.
74
97
  | `<p ?hidden=${value}>` | boolean attribute, present when truthy |
75
98
  | `<input !checked=${value}>` | property written from the **live DOM** rather than from what the binding last wrote — see below |
76
99
  | `<button @click=${fn}>` | event listener. An object with a `handleEvent` method works too — `addEventListener` takes both |
77
- | `<button onClick=${fn}>` | the same thing, React-style. Strictly `on` + a capital — a template-written `onclick` stays a plain attribute (yours, greppable); **spread refuses it** (see the spread section's security note) |
100
+ | `<button onClick=${fn}>` | the same thing, React-style. Strictly `on` + a capital. A STATIC `onclick="…"` stays a plain attribute (yours, greppable); a BOUND `onclick=${…}` runs its value as code, so it is **refused** — in templates, in spread and on the server alike |
78
101
  | `<input ${fn}>` | element ref: a function is called with the element |
79
- | `<input ${obj}>` | element ref: an object gets the element assigned to `.value`, so core's `ref()` works here |
102
+ | `<input ${obj}>` | element ref: an object gets the element assigned to `.value`, so core's `signal()` works here |
80
103
  | `<input ${spread(props)}>` | names resolved at runtime — see [`/spread`](#verajsrendererspread) |
81
104
 
82
- A ref runs once per **distinct value**, not once per render.
105
+ A ref runs once per **distinct value**, not once per render — and **after its render pass**, once the
106
+ pass's DOM exists: the element is inserted, a custom element is upgraded, and it belongs to its own
107
+ document, so a ref can measure it, focus it, or read its window. Within a pass, refs run in commit order
108
+ — document pre-order, so an element's ref runs before the refs inside it and before its next sibling's —
109
+ after the pass's `<select>` values are set; a
110
+ ref replaced or removed before its turn is handed nothing. A ref runs **untracked**: what it reads never
111
+ subscribes the component that rendered it — a ref captures an element, it is not a dependency.
112
+
113
+ **Replacing a ref tells the old one first.** Changing `${a}` to `${b}` calls `a(null)` at once and hands `b`
114
+ the element after the pass; changing it to `${null}` calls `a(null)`. A `{ value }` ref is emptied the same way.
115
+ A value that applies itself (`_$apply$`, such as a spread) is never written to — it owns its own lifecycle,
116
+ so a position switching from a spread to a ref leaves the spread's keys as they were.
83
117
 
84
118
  **A ref is released when its subtree is rendered away, and not when its component is removed from
85
119
  the document.** Toggling `${show ? html`<i ${box}>` : 'gone'}` sets `box.value` back to `null` (and
@@ -98,6 +132,13 @@ object with no `handleEvent` — is inert, and **development names it at the bin
98
132
  only ever called when a user clicks, so left unchecked the mistake surfaces at a point where nothing
99
133
  on the stack says where the value came from.
100
134
 
135
+ **A handler never subscribes the hook that happens to be running.** An effect that fires an event
136
+ synchronously — `button.click()`, `input.focus()`, `dispatchEvent` — runs the handler inside itself, and
137
+ the handler's reads used to subscribe that effect: a handler doing `state.count++` re-ran the effect on
138
+ every later click. Every listener Vera binds — `@event`, spread's `@event` key, `data-vd-on-*` — runs
139
+ untracked. A listener you add yourself with `addEventListener` is outside Vera: fired synchronously from
140
+ inside a hook it still tracks, so read through `untrack()` there.
141
+
101
142
  ### `!name` — a live property
102
143
 
103
144
  Every other binding skips a write when the value matches what it last wrote. That is what keeps a
@@ -114,15 +155,27 @@ first binding still says `true`, still matches what it committed, and never writ
114
155
  and the page diverge and no amount of re-rendering reconciles them. A `<select>`'s options are the
115
156
  same shape.
116
157
 
158
+ A `<select>`'s selection is controlled however it is spelled — `.value`, `!value` or `.selectedIndex`, written
159
+ in the template or as a `spread()` key. Every binding on a select is committed when the render pass ends, so
160
+ its options exist whether they are static, a list, a nested template or a keyed list; the selection is re-asserted
161
+ on every render (its options can move under an unchanged value) and written only when the select holds a different
162
+ one (the write resets every option, so skipping it is what keeps a table with a select per row fast). On a
163
+ `<select multiple>`, `value` and `selectedIndex` each control ONE selection and a selection the user adds is kept;
164
+ bind `?selected=${…}` on each `<option>` to control every one. Development says so.
165
+
117
166
  It is deliberately narrow, and it is a **property** binding only:
118
167
 
119
168
  - **Not for text inputs.** Bind those with `.value` and let a person's typing stand. `!value` exists
120
169
  and is authoritative, which is precisely why it is not the default.
121
170
  - **Not offered for attributes or booleans.** Nothing changes those behind the renderer's back, so
122
171
  there is nothing to re-read.
123
- - **It yields during hydration.** A click that happened before the bundle landed had no handler to
124
- report it, so adoption records the value without writing; live semantics resume on the first
125
- state-driven render.
172
+ - **On a component it is delivered**, exactly as `.name` is: compared against the component's current
173
+ value on every render and, on a difference, handed to it — a running component re-renders. An equal
174
+ value costs one read and renders nothing.
175
+ - **It yields during hydration — for a control's user state.** A click that happened before the bundle
176
+ landed had no handler to report it, so adoption records `value`, `checked`, `selected` and `open`
177
+ without writing; live semantics resume on the first state-driven render. Any other `!name` is
178
+ written on adoption (`!indeterminate`, which no markup can carry), and on a component delivered.
126
179
 
127
180
  `spread({ '!checked': … })` means the same thing, and `@verajs/ssr` serializes it exactly as
128
181
  `.checked` — a server has nothing to re-read.
@@ -149,6 +202,12 @@ What a child position does with each kind of value. These match lit-html exactly
149
202
  Strings render as **text**, always. There is no path by which an interpolated value becomes markup
150
203
  — see [Trusted HTML](#trusted-html-and-why-there-is-no-unsafehtml).
151
204
 
205
+ **An element whose whole content is one `${…}` belongs to that value.** `<ul>${rows}</ul>` renders its rows
206
+ straight into the `<ul>` with no marker nodes at all, so nodes added to that `<ul>` by other code are removed when
207
+ the value changes. Anywhere else a position is bracketed by two empty comments, and what sits outside them is
208
+ left alone. A custom element is never owned this way — a light-DOM component renders into its own children, so a
209
+ `${…}` inside `<my-panel>` keeps its markers and the two coexist.
210
+
152
211
  ### A boolean child renders the word, and JSX is the exception
153
212
 
154
213
  `${items.length > 0 && html\`…\`}` is the ordinary conditional idiom, and when the test fails the
@@ -165,6 +224,46 @@ React's rule and where React expectations live. That is the **one** value semant
165
224
  a hand-written template differ, and this warning is what meets JSX-shaped code pasted into a
166
225
  template. `0` still renders in both, exactly as in React: the rule is about booleans, not falsiness.
167
226
 
227
+ ### A template committed into the wrong namespace is named
228
+
229
+ An `<svg>` draws SVG content and its three HTML integration points — `<foreignObject>`, `<desc>`
230
+ and `<title>` — and nothing else. A template written `` html`…` ``
231
+ and handed across a function boundary into one is still HTML — `<path>` parsed as HTML is an
232
+ `HTMLUnknownElement` with the right tag name and no geometry, so a whole set of icons can vanish
233
+ with nothing to search for:
234
+
235
+ ```js
236
+ const Frame = (children) => html`<svg viewBox="0 0 24 24">${children}</svg>`;
237
+ Frame(html`<path d="M0 0h24" />`); // silent: nothing draws
238
+ Frame(svg`<path d="M0 0h24" />`); // the fix — the tag is chosen where the template is WRITTEN
239
+ ```
240
+
241
+ The tag is right where it was written and the call site cannot know the destination — lit-html
242
+ behaves the same way. **Wire `@verajs/renderer/namespaces`** and the renderer corrects it: an
243
+ `` html`…` `` template is then parsed in the namespace of the position it lands in, so the first line
244
+ above draws too (see [below](#verajsrenderernamespaces--a-template-parsed-where-it-lands)).
245
+ Without it, **development names it**, once per host namespace, host name, content namespace and tag. HTML content gets both remedies: `` svg`…` `` when the element was
246
+ meant to be SVG, and an HTML island (`<foreignObject>` in SVG, `<mtext>` in MathML) when it is
247
+ genuinely HTML. Tagging a custom element `` svg`…` `` would silence the message and leave the
248
+ element permanently un-upgraded, since custom-element upgrade is spec-gated on the HTML namespace.
249
+
250
+ The rule is a namespace MISMATCH, so MathML committed into an `<svg>` and SVG committed into a
251
+ `<math>` are named by it too — with their own advice, since the template's tag is already right
252
+ there and only the destination is wrong. It is silent where the content is correct: inside
253
+ `<foreignObject>`, `<desc>` and `<title>`, inside MathML's token elements, inside
254
+ `<annotation-xml>` carrying an HTML `encoding` — or `image/svg+xml`, MathML's own registered
255
+ spelling for an SVG annotation — as an ATTRIBUTE, the only form the parser reads (an `.encoding`
256
+ property is named), for an `<svg>` in any `<annotation-xml>`, where the parser itself puts one, and
257
+ for `<style>`/`<script>`, which never draw — an HTML `<style>` inside an `<svg>` applies its rules
258
+ perfectly well.
259
+
260
+ **In JSX this cannot happen** unless it is switched off: `@verajs/jsx` wires
261
+ `@verajs/renderer/namespaces` from every file it compiles (not with `inject: false` or
262
+ `namespaces: false`, which leave it to you), so `<Frame><path /></Frame>` works. The message is what meets a hand-written template when
263
+ the module is not wired, or a template built before it was — the message names that too.
264
+
265
+ The whole check folds away in production — no code and no strings.
266
+
168
267
  A DOM node renders as itself, which is how a template holds something another library owns:
169
268
 
170
269
  ```js
@@ -184,9 +283,11 @@ renderInto(html`<ul>${rows.map((row) => keyed(row.id, html`<li>${row.label}</li>
184
283
  ```
185
284
 
186
285
  `keyed(key, result)` tags a result with its identity, so a reorder **moves** the existing elements
187
- instead of rebuilding them — focus, scroll position, form state and running animations all survive.
286
+ instead of rebuilding them — form state, scroll position and running animations survive. Focus does
287
+ not survive a MOVE: the platform blurs any node that is re-inserted, framework or not (pinned in the
288
+ browser suite), so only the elements that actually moved lose it.
188
289
  It is its own entry because most apps never reorder a list, and the algorithm that makes reordering
189
- cheap is <!--size:keyed.gzip-->923 B<!--/size:keyed.gzip--> gzipped they would otherwise carry. Importing `keyed` is the whole installation:
290
+ cheap is <!--size:keyed.gzip-->2.69 KB<!--/size:keyed.gzip--> gzipped they would otherwise carry. Importing `keyed` is the whole installation:
190
291
  nothing registers, and there is no `wire()` call — the marker stamps each result with the strategy
191
292
  that understands it, so a list always names its own reconciler and two strategies cannot disagree
192
293
  about one. Lit splits `repeat` out for the same reason; the difference is that this one arrives on
@@ -199,10 +300,29 @@ than at install. Both ship from this package and bump together, so a single vers
199
300
  the trap is pinning one and floating the other. `@verajs/renderer/spread` carries the same rule for
200
301
  the same reason.
201
302
 
202
- **It is additive, not a substitute.** Unlike `/hydrate` and `/profiler`, this entry imports nothing
303
+ **It is additive, not a substitute.** Unlike `/profiler`, this entry imports nothing
203
304
  at all — it reaches whatever renderer is present through a handful of mangling-exempt members — so
204
305
  it is safe alongside any of them, `/hydrate` included.
205
306
 
307
+ <!-- D28, 2026-11-12: the full-renderer requirement below lives HERE while lists is unreleased; llms.txt documents no
308
+ automatic lists yet, and its lists section must carry the same sentence when lists is released. -->
309
+ **Experimental: automatic `.map`, `lists` and `createSelector`.** With `lists` wired —
310
+ `wire([renderer, lists])` — a plain `state.rows.map((row) => html`…`)` over a store array inside a render is a keyed
311
+ list whose rows track themselves: a field write re-renders that one row, and pushes, removals and swaps touch only what
312
+ moved. Rows are keyed by an item's own `id`, else by the item itself. `lists` needs the FULL renderer: wired beside a
313
+ bare `{ on: 'render', fn: renderInto }` its rows cannot commit themselves, so every row's change re-renders the parent,
314
+ and development says so once (`lists-no-renderer`). `createSelector(() => state.selected)` returns
315
+ `isSelected(key)`, which re-renders only the old and the new key's rows on a change. Without `lists` wired, development says so once
316
+ (`lists-unwired`) when such a `.map` returns unkeyed templates, since rows are then matched by position (rows from
317
+ `keyed()`, or JSX's `key={id}`, are matched by key and say nothing); to match by position on purpose, map a plain copy,
318
+ `[...state.rows].map(…)`. The copy still TRACKS — spreading reads every index, so the render
319
+ re-runs on any item change — it opts out of keying, not of reactivity. **Hydrated, an automatic list adopts the server's rows**
320
+ (their nodes, and a component row's element) instead of rebuilding them; a component row is handed its `.item` AFTER it
321
+ upgrades — its first render may see `undefined`, so read it as `this.item?.label`. Not released; the design is still
322
+ being measured. **A hidden list is released when the render that hid it returns**: a component's render, or a row's
323
+ own render for a list nested in a row. A `.map` inside your own render-priority hook (`effect(fn, { priority: 50 })`) is a list too,
324
+ but one it hides is released only when that hook is torn down.
325
+
206
326
  **A list is keyed because `keyed()` marked it, not because its results have a `key` property.**
207
327
  Setting `.key` by hand no longer makes a list keyed — the marker is what carries the algorithm, so
208
328
  it is what the renderer looks for, on the client and when adopting server markup alike.
@@ -213,6 +333,9 @@ unkeyed item in a keyed list has no identity to match on.
213
333
  An unkeyed list is not wrong — it updates each position in place, which is exactly right for a list
214
334
  whose order never changes.
215
335
 
336
+ One position can switch between a keyed and an unkeyed list, in either direction, and render
337
+ correctly — the items are the same kind of thing, and an unkeyed one simply has no key to match on.
338
+
216
339
  ## Preserving DOM — `hold()`
217
340
 
218
341
  ```js
@@ -231,7 +354,9 @@ parked, `0` on return, and `0` even for a node moved directly between two attach
231
354
  applier does with the nodes can hold it, and lit's `cache()` cannot either. If a scroll position
232
355
  matters, read it before the toggle and restore it after.
233
356
 
234
- Anything that is not a template passes straight through — there is nothing to park for a string, a list, `null` or `false` — so `hold(editing && editor())` is safe to write.
357
+ Anything that is not a template passes straight through — there is nothing to park for a string, a list, `null` or `false` — so `hold(editing && editor())` is safe to write, and the editor is rebuilt when it returns: parking happens only when another held template takes its place.
358
+
359
+ **A parked template's refs keep their element** — parking is not destruction, and the element comes back. They are released when the section itself goes away, along with everything it parked; clearing the section (`null`) keeps what it parked.
235
360
 
236
361
  It only re-adopts a template it has seen at **that same call site** — two `hold()` calls in
237
362
  different templates are two different templates, and neither adopts the other's DOM. The other
@@ -277,22 +402,306 @@ committed in place against templates that replaced a different template.
277
402
  | Import | What it adds | Ships in production |
278
403
  | --- | --- | --- |
279
404
  | `@verajs/renderer` | the renderer | yes |
280
- | `@verajs/renderer/hydrate` | a superset whose first render adopts server-rendered DOM | yes |
405
+ | `@verajs/renderer/hydration` | `hydration` (wire it beside the renderer) — the first render adopts server-rendered DOM | yes |
406
+ | `@verajs/renderer/hydrate-slots` | `hydrateSlots` (wire it) — reads the server's light-slot format, for an app that hydrates light slots | yes |
281
407
  | `@verajs/renderer/keyed` | `keyed(key, result)` — keyed list reconciliation | yes |
282
408
  | `@verajs/renderer/spread` | `spread(props)` — binding names resolved at runtime | yes |
283
409
  | `@verajs/renderer/tag` | `` tag`h1` `` — an element whose tag name is decided at runtime | yes |
284
410
  | `@verajs/renderer/slots` | `slots` (wire it) + `slotted(host, name?)` — light-DOM `<slot>` distribution | yes |
411
+ | `@verajs/renderer/namespaces` | `namespaces` (wire it) — an `html` template parsed in the namespace of where it lands | yes |
412
+ | `@verajs/renderer/elements` | `elements` (wire it) — behavior attached to claimed elements in templates, mounted and unmounted with their instances | yes |
413
+ | `@verajs/renderer/portal` | `portal(target, template)` — a component draws into ANOTHER element (a modal on `document.body`), in a range of its own | yes |
414
+ | `@verajs/renderer/until` | `until(promise, fallback)` — a promise at a child position: the fallback, then its value | yes |
415
+ | `@verajs/renderer/native-elements` | `nativeElements` (wire it) — `init` on a built-in element (a `div`, a `section`…) with a custom element's lifecycle | yes |
416
+ | `@verajs/renderer/multi-window` | `multiWindow` (wire it) — components left in a pop-out or an iframe are released when that window closes | yes |
285
417
  | `@verajs/renderer/profiler` | a superset that measures template churn | no — development only |
286
418
 
287
- `/hydrate` and `/profiler` each re-export the whole public API, so they are drop-in replacements for
288
- the base import. **Never mix two of them in one app** — that loads two renderers with two template
289
- caches.
419
+ `/profiler` re-exports the whole public API, so it is a drop-in replacement for the base import. **Never mix it
420
+ with `@verajs/renderer` in one app** — that loads two renderers with two template caches, and profiling while
421
+ rendering through the other observes an instance nothing renders into (measured: renders reported zero frames while
422
+ the page updated correctly). `formatReport` says so when it observed nothing, because a zero report is otherwise
423
+ indistinguishable from an app with nothing to optimize. **A hydrating app profiles like any other:** wire
424
+ `hydration` beside the profiler's renderer — `wire([renderer, hydration])` with `renderer` from
425
+ `@verajs/renderer/profiler` — and its adoption is profiled too.
426
+
427
+ ## `@verajs/renderer/elements` — behavior on elements in templates
428
+
429
+ Attach behavior to elements *in templates* — "every `[autofocus]`", "every `<slot>`", "every
430
+ `<dialog open>`" — without a directive system and without touching the elements' markup. A
431
+ **claimant** is an ordinary insert on `'element'`: it is asked about each element of a template once,
432
+ when the template is first used, and answers with a shared behavior object or `undefined`. Every
433
+ instance of that template then runs the behavior's `mount` once its render has finished, and
434
+ `unmount` at teardown with whatever `mount` returned.
435
+
436
+ The example is a real gap. Measured on Chromium, Firefox and WebKit, the first `autofocus` element
437
+ rendered after page load takes focus and **every later one is ignored** — so the second form an app
438
+ shows, an edit dialog or a step two, never gets the focus its markup asks for. Five lines fix it:
439
+
440
+ <!-- recipe -->
441
+ ```js
442
+ import { wire, html } from '@verajs/core';
443
+ import { renderer, renderInto } from '@verajs/renderer';
444
+ import { elements } from '@verajs/renderer/elements';
445
+
446
+ /** One shared object for every claimed element of every instance. */
447
+ const autofocus = { mount: (element) => element.focus() };
448
+
449
+ wire([
450
+ renderer,
451
+ elements,
452
+ { on: 'element', fn: (el) => (el.hasAttribute('autofocus') ? autofocus : undefined), priority: 50 },
453
+ ]);
454
+
455
+ const step = (n) => html`<form><label>Step ${n} <input autofocus name=${'step' + n}></label></form>`;
456
+ const [first, second] = [document.createElement('div'), document.createElement('div')];
457
+ document.body.append(first, second);
458
+ renderInto(step(1), first);
459
+ document.activeElement.blur();
460
+ renderInto(step(2), second); // a second form, later: focused, where the platform alone would not
461
+ if (document.activeElement.name !== 'step2') throw new Error('the second form did not take focus');
462
+ ```
463
+
464
+ What a claimant can rely on:
465
+
466
+ - **It is asked about the TEMPLATE's element, once.** The element is inert: its tag and its
467
+ **static** attributes are real, bindings are not applied yet — `autofocus=${x}` cannot be claimed on
468
+ `x`. Claim the attribute's presence and decide in `mount`. SVG and MathML elements are asked too.
469
+ - **`create(element, adopted)` runs as each instance is created** — before its first update writes
470
+ anything, and before the instance is connected anywhere — so the element holds exactly the static
471
+ children the template wrote, each binding position still the empty text it parsed as. It is the one
472
+ moment those can be told apart; `@verajs/renderer/slots` records a host's static children there.
473
+ Nothing is kept from it, and it is optional.
474
+ - **`mount(element, { root, adopted })` runs once the render that created the instance has
475
+ finished** — in the same end-of-render pass as refs, in document order, so a claim that MOVES an
476
+ element does so after refs above it saw it in place (measure in `mount`, not in a ref) — so the whole tree is in place and connected if its container is — a nested instance is
477
+ inserted only when its outer one is, which is why it does not run straight after the instance's own
478
+ update. `root` is the render's container. An instance discarded before its render ends never mounts.
479
+ - **`unmount(kept, element)` runs once, at teardown** — a template swapped out, a keyed row dropped, a
480
+ list shrunk, a container cleared — and only when `mount` returned something. **`hold()` is not
481
+ teardown**: a parked instance keeps its mount and is not mounted again when it returns.
482
+ - **Several claimants may claim one element**; each gets its own `create`/`mount`/`unmount`, in wire order.
483
+ - **No updates.** A behavior that must react to values is a binding or an applier (`_$apply$`), not a
484
+ claim — which is what keeps claims off the hot path.
485
+ - **A throwing `create`, `mount` or `unmount` is reported, never raised** — the rule a `&ref` follows:
486
+ to the app's `'error'` chain with the component, else as uncaught (`reportError`), and the render,
487
+ the other claims and the teardown carry on. Every throw is reported. A claim whose `create` threw is
488
+ dropped for that instance — it never mounts or unmounts — and its element stays as the template
489
+ built it.
490
+ - **Wire it before anything renders**, like `slots`: a template asks its claimants when it is first
491
+ used, and a claimant wired later never hears about templates already built — development says so
492
+ at `wire`, for this module and every other that decides per template (`namespaces`, `slots`). An app that wires no
493
+ claimant pays nothing; one that does pays one walk per new template, and one short walk per
494
+ instance of a template something claimed.
495
+
496
+ ## `@verajs/renderer/until` — a promise in a template
497
+
498
+ ```js
499
+ import { until } from '@verajs/renderer/until';
500
+
501
+ define('x-user', () => {
502
+ const user = fetchUser(); // made ONCE, in the setup
503
+ return () => html`<p>${until(user, html`<em>loading…</em>`)}</p>`;
504
+ });
505
+ ```
506
+
507
+ It shows the fallback, then what the promise resolves to.
508
+
509
+ - **The same promise again** (any re-render) keeps what is shown: no flash, no second subscription. Make the promise in
510
+ the setup, as above; one written inline in the template is a new promise, a new request, every render.
511
+ - **A new promise** shows the fallback again, and the old one's late answer is dropped, so a slow first request never
512
+ overwrites a newer one.
513
+ - **Removed before it settles,** the answer is dropped.
514
+ - **Not a promise:** shown at once.
515
+ - **A rejection** keeps the fallback, and the browser reports it, as any unhandled rejection: in the console with its
516
+ stack, and as an `unhandledrejection` event, which error monitoring hears. To SHOW an error, pass the caught promise —
517
+ a caught promise resolves to whatever the handler returns:
518
+
519
+ ```js
520
+ html`<p>${until(user.catch(() => html`<b>couldn't load</b>`), html`<em>loading…</em>`)}</p>`
521
+ ```
522
+
523
+ That also keeps the browser from reporting an error you handled. For a refreshing state too, use `resource()` from
524
+ `@verajs/store/resource`, which carries `loading`, `value` and `error`.
525
+ - **On a server** it renders the fallback and waits for nothing, and a rejection there is consumed: the server never shows
526
+ the result, and an unhandled rejection would end a Node process. Hydration draws the fallback again and the value
527
+ replaces it.
528
+
529
+ `until` is built on the `_$child$` protocol below; core and the renderer carry nothing for it.
530
+
531
+ ## `@verajs/renderer/multi-window` — components in the windows your page opens
532
+
533
+ A component moved into another window's document — a pop-out (`window.open`) or an iframe — is kept by core, state and
534
+ all, and comes back the same way. When that window CLOSES with components still inside, nothing tells them: they stay
535
+ subscribed to this window's stores, alive and running, for the life of the page. Wire `multiWindow` and they are
536
+ released then:
537
+
538
+ ```js
539
+ import { wire } from '@verajs/core';
540
+ import { renderer } from '@verajs/renderer';
541
+ import { multiWindow } from '@verajs/renderer/multi-window';
542
+
543
+ wire([renderer, multiWindow]);
544
+
545
+ const popup = window.open('', 'panel');
546
+ popup.document.body.append(panel); // pop out: kept
547
+ popup.addEventListener('pagehide', () => document.body.append(panel)); // optional: bring it home as it closes
548
+ ```
549
+
550
+ - **What is released:** every component of this core still in the closed window's document, shadow roots included —
551
+ one moved there, one built there while it was out, one appended there directly. Each runs its cleanups once, and no
552
+ write wakes it again.
553
+ - **When:** at that window's final `pagehide`, on this window's NEXT task, so your own `pagehide` handler runs first; a
554
+ panel it moves home is no longer in the closed document and survives.
555
+ - **Not released:** a back/forward-cached hide (`persisted`), which can come back.
556
+ - **Cost:** nothing on any normal path (core hears a move into another document on its cold cross-window path only), and
557
+ nothing at all for an app that does not wire it. It imports nothing.
558
+
559
+ In the platform's words: a `window.open` window is an *auxiliary browsing context*, an iframe's a *child navigable*,
560
+ moving a node into another document is *adoption* (core's `'adopted'` insert point), and a closing window's document is
561
+ *unloaded*.
562
+
563
+ ## `@verajs/renderer/native-elements` — `init` on a built-in element
564
+
565
+ A custom element tells core when it leaves the page and when it comes back — its `connectedCallback` and
566
+ `disconnectedCallback` — so a component that calls `init(this)` there is torn down when it is removed, set up again when
567
+ it returns, and kept when it is merely moved. A built-in element (a `div`, a `section`) given to `init` tells nobody: by
568
+ itself it is drawn and stays reactive, but it is never released when removed. Wire `nativeElements` and it gets exactly
569
+ the custom element's lifecycle. (Not to be confused with `@verajs/renderer/elements`, above, which attaches behavior to
570
+ elements *inside* templates.)
571
+
572
+ <!-- recipe -->
573
+ ```js
574
+ import { wire, init, html, createStore } from '@verajs/core';
575
+ import { renderer } from '@verajs/renderer';
576
+ import { nativeElements } from '@verajs/renderer/native-elements';
577
+
578
+ wire([renderer, nativeElements]);
579
+
580
+ const state = createStore({ count: 0 });
581
+ const panel = document.createElement('section');
582
+ document.body.append(panel);
583
+ init(panel, () => () => html`<button @click=${() => state.count++}>${state.count}</button>`);
584
+
585
+ panel.remove(); // torn down: its effects' cleanups run, it leaves every store
586
+ document.body.append(panel); // set up again, fresh — as a custom element re-added
587
+ ```
588
+
589
+ - **Removed:** torn down, exactly as a custom element's removal (cleanups run, nothing it read keeps it alive).
590
+ - **Re-attached:** set up again — its setup runs again, so what the setup created starts fresh.
591
+ - **Moved** in one operation (`append`/`insertBefore` of a connected element), or **into another window's document** (a
592
+ popped-out panel): kept, with its state.
593
+ - **Given `init` before it is on the page:** its setup waits for its first connect, as a custom element's does — a host
594
+ built off the page and never attached is never set up and holds nothing.
595
+
596
+ **For a few hosts, not for volume:** a built-in host carries a little more than a custom element (its closed root and two
597
+ small nodes), so it costs a little more to create and to collect. Use it for the handful of roots, islands and panels
598
+ an app has; anything created in volume — rows, items, repeated widgets — belongs in a custom element.
599
+
600
+ **How it hears:** each host gets a CLOSED shadow root holding a default `<slot>` (its light content renders exactly as
601
+ before) and a tiny custom element whose own callbacks fire when its host is attached, moved or removed — the same in
602
+ Chromium, Firefox and WebKit. The root is closed, so `host.shadowRoot` stays `null` and selectors see the host's children
603
+ as before.
604
+
605
+ **Not supported** (said by name in development; the element still renders, and is never released when removed):
606
+
607
+ - elements that cannot hold a shadow root — `ul`, `li`, `table`, `button` and the rest; supported are `div`, `section`,
608
+ `article`, `aside`, `header`, `footer`, `main`, `nav`, `p`, `span`, `blockquote`, `h1`–`h6` and `body`;
609
+ - an element that already has a shadow root — including one `init` attached from a `shadow` option, or from the app's
610
+ `renderer({ shadow })` default (an app with a shadow default has no supported built-in hosts);
611
+ - the host's own later `attachShadow()` (or declarative shadow DOM) — it now has one; development says why.
612
+
613
+ One thing changes for a supported host: a DIRECT child carrying a `slot` attribute (`<span slot="title">`) renders
614
+ nowhere, since the host's root has only a default `<slot>` (the same in every engine; a deeper descendant with one is
615
+ unaffected) — development says so, naming the host. Document CSS is otherwise unaffected — child and structural selectors, `:empty`, `:has()`, inheritance
616
+ and layout match a host without it.
290
617
 
291
- **Which means an app can have one of them, not both — so a hydrating app cannot be profiled.** They
292
- each bundle their own renderer with its own instrumentation hook, so profiling while rendering
293
- through `/hydrate` observes an instance nothing renders into: measured, three renders reported zero
294
- frames while the page updated correctly. `formatReport` says so when it observed nothing, because a
295
- zero report is otherwise indistinguishable from an app with nothing to optimise.
618
+ Also: a built-in element built in a document with no window (`document.implementation.createHTMLDocument`, a
619
+ `DOMParser` result) is not set up; and a component left inside a window when that window closes (an iframe removed, a
620
+ pop-out closed, with the component still in it) is the app's to remove.
621
+
622
+ ## `@verajs/renderer/portal` — drawing into another element
623
+
624
+ A component's own render goes into its own root. To draw somewhere ELSE — a modal or a toast on `document.body`, a
625
+ tooltip in an overlay layer — call `portal(target, template)` in its setup:
626
+
627
+ <!-- recipe -->
628
+ ```js
629
+ import { wire, define, html, createStore } from '@verajs/core';
630
+ import { renderer } from '@verajs/renderer';
631
+ import { portal } from '@verajs/renderer/portal';
632
+
633
+ wire([renderer]);
634
+
635
+ const state = createStore({ open: true, title: 'Saved' });
636
+ define('x-toast', () => {
637
+ portal(document.body, () => (state.open ? html`<div role="status">${state.title}</div>` : ''));
638
+ return () => html`<button @click=${() => (state.open = !state.open)}>toggle</button>`;
639
+ });
640
+
641
+ const toast = document.createElement('x-toast');
642
+ document.body.append(toast); // the button in the component, the status line at the end of <body>
643
+ toast.remove(); // the status line goes with it
644
+ ```
645
+
646
+ - **A range of its own.** It appends two comment markers to `target` and draws between them, so any number of portals
647
+ share one target and none touches what was there before it.
648
+ - **The render's slot.** It is drawn when the component's render is (a keyed `.map` keeps its rows with their items, and
649
+ layout effects see it drawn), it updates from what it reads like any render, and what a draw made and no longer
650
+ reaches — a hidden automatic list, a computed — is released as a render's is.
651
+ - **Owned by the component.** Removing the component takes its content and its markers out of `target`; a component
652
+ that `persist`s takes them out while it is away and draws them again when it is back — appended at the END of
653
+ `target` again, so its order among the target's other children (two open modals) can change. Moving the component into
654
+ another window's document (a pop-out) leaves the portal where it is — `target` is where it was asked to draw — and it
655
+ stays live.
656
+ - **Light DOM.** It draws into `target` itself, never into a shadow root: into a shadow host, the content is the host's
657
+ light content, placed by its `<slot>`. Styles are therefore `target`'s, not the component's — a shadow component's
658
+ `static styles` do not reach a portal's content (style it in the document, or with its own `<style>`). Events bubble
659
+ from the content up through `target`'s ancestors, not through the component.
660
+ - **The client only.** On a server a portal registers nothing: the server renders the component's own template, and
661
+ hydration adopts that and then draws the portal once.
662
+ - **Call it in a setup.** It belongs to the component being set up; after an `await` in an async setup none is, and it
663
+ throws, as `effect` does (`no-owner`).
664
+
665
+ It keeps `@verajs/core` external in every build (its draw is one of core's effects; inlined, it would be a second core),
666
+ so a CDN page's import map names `@verajs/core` beside it — as it already does for `@verajs/store`.
667
+
668
+ ## `@verajs/renderer/namespaces` — a template parsed where it lands
669
+
670
+ A template's namespace is normally fixed by its tag: `` html`…` `` is HTML wherever it goes, which is
671
+ why a shape handed into an `<svg>` needs `` svg`…` ``. Wire this module and the renderer instead
672
+ parses an `html` template **in the namespace of the position it is committed into** — the way the
673
+ browser's own parser treats markup written inside an `<svg>`:
674
+
675
+ <!-- recipe -->
676
+ ```js
677
+ import { html, wire } from '@verajs/core';
678
+ import { renderer, renderInto } from '@verajs/renderer';
679
+ import { namespaces } from '@verajs/renderer/namespaces';
680
+
681
+ wire([renderer, namespaces]);
682
+
683
+ const Frame = (children) => html`<svg viewBox="0 0 24 24">${children}</svg>`;
684
+ const host = document.createElement('div');
685
+ renderInto(Frame([html`<title>Close</title>`, html`<path d="M0 0h24"></path>`]), host);
686
+
687
+ if (host.querySelector('path').namespaceURI !== 'http://www.w3.org/2000/svg') throw new Error('not SVG');
688
+ if (host.querySelector('title').namespaceURI !== 'http://www.w3.org/2000/svg') throw new Error('not SVG');
689
+ ```
690
+
691
+ The answer comes from the parser, not from a list: SVG's camelCase names keep their case,
692
+ `<foreignObject>`, `<desc>` and `<title>` hold HTML again, MathML's token elements likewise, and the
693
+ same strings committed into a `<div>` stay HTML. Under a MathML parent the parser's answer depends on
694
+ the child as well — `<svg>` inside `<annotation-xml>`, `<mglyph>` inside `<mi>` — so there it is asked
695
+ with the template's own first tag.
696
+
697
+ - **`@verajs/jsx` wires it for you**, from every file it compiles — JSX cannot write `` svg`…` ``.
698
+ - **Wire it before anything renders.** It applies to a template when the template is first built, so
699
+ one built earlier keeps the namespace it was built in; development names that case.
700
+ - **`svg`/`mathml` tags still work** and still decide their own namespace — wiring this changes only
701
+ `html` templates.
702
+ - **What it costs**: its own bundle, only when wired. The renderer's update path is untouched; a
703
+ template is resolved once per instance it creates, measured at parity with explicit tags on
704
+ Chromium, Firefox and WebKit.
296
705
 
297
706
  ## `@verajs/renderer/slots` — light-DOM slots
298
707
 
@@ -318,7 +727,7 @@ Given this markup:
318
727
 
319
728
  <!-- recipe -->
320
729
  ```js
321
- import { init, render, wire, html } from '@verajs/core';
730
+ import { init, wire, html } from '@verajs/core';
322
731
  import { renderer } from '@verajs/renderer';
323
732
  import { slots, slotted } from '@verajs/renderer/slots';
324
733
 
@@ -328,13 +737,10 @@ customElements.define(
328
737
  'my-card',
329
738
  class extends HTMLElement {
330
739
  connectedCallback() {
331
- init(this); // LIGHT DOM — no shadow options
332
- render(
333
- () => html`<article>
740
+ init(this, () => () => html`<article>
334
741
  <header><slot name="header" @slotchange=${(e) => this.onHeader(e.target)}>Untitled</slot></header>
335
742
  <main><slot>Nothing here yet.</slot></main>
336
- </article>`
337
- );
743
+ </article>`); // LIGHT DOM — no shadow option
338
744
  }
339
745
  /** Written exactly as it would be against a shadow root, and it runs in both. */
340
746
  onHeader(slot) {
@@ -363,9 +769,38 @@ console.log(slotted(card, 'header').length); // 1
363
769
  > DIFFERENT renderer — lit-html — where there is no seam to find.) The assignment follows
364
770
  the platform's own rules — elements to the slot their `slot` attribute names, text to the default
365
771
  slot, fallback shown only while a slot is unassigned and restored when it empties, direct children
366
- only. Live: appending, removing, or re-slotting children redistributes automatically, with one documented
367
- divergence — see **Late children** below. Re-renders leave slotted nodes in place, identity intact, so focus and input values
368
- survive; SSR emits already-distributed markup and hydration adopts it.
772
+ only. **Every node goes to the slot its own `slot` names** — including the nodes a binding in the
773
+ page's template writes, so ``${items.map((i) => html`<li slot=${i.where}>…</li>`)}`` distributes
774
+ exactly as the same markup written out by hand, and keeps doing so as the list changes. Live:
775
+ appending, removing, or re-slotting children redistributes automatically. Re-renders leave slotted
776
+ nodes in place, identity intact, so focus and input values survive.
777
+
778
+ **Server-rendered and hydrated.** `@verajs/ssr` emits already-distributed markup — each filled slot's
779
+ content between two comments, exactly as this module leaves it on the client — and states the light
780
+ tree on each host. A hydrating page adopts it in place, nested components included, with one more
781
+ module wired, which only an app that hydrates light slots loads:
782
+
783
+ ```js
784
+ import { hydrateSlots } from '@verajs/renderer/hydrate-slots';
785
+ wire([renderer, hydration, slots, hydrateSlots]);
786
+ ```
787
+
788
+ Without it, a server-rendered host with light content is left exactly as served — never cleared — and the console
789
+ names what to wire (`hydration-slots`); a host the server stated empty (`1:`) hydrates without it.
790
+ **Wire `slots` on the server too:** a server without it writes no light-tree statement, so every
791
+ component it rendered is taken for client-made and renders fresh on the client — its server markup kept, hidden, as
792
+ unassigned light content — and no warning is possible, because the client cannot tell the two apart. **Serve the server's HTML unmodified, comments included:** a
793
+ minifier that strips comments removes the slots' markers, and the host renders fresh, as React, Lit
794
+ and Solid treat a missing marker. The light-tree statement carries a format number, so render and
795
+ hydrate with matching releases of `@verajs/ssr` and `@verajs/renderer`: a page in another format
796
+ renders fresh, its content kept, and the warning says so. A component host carrying no statement was
797
+ made on the client, and gets a client first render rather than an adoption.
798
+
799
+ **Measured, including where it still differs.** `tests/browser/slots-conformance.test.js` runs whole
800
+ component lifecycles through a real shadow root and through this module on Chromium, Firefox and
801
+ WebKit, comparing the composed tree and element identity after every step, and every scenario
802
+ matches — slot forwarding (a `<slot>` placed inside another light component shows what the outer slot
803
+ shows) and `hold()` inside content one template places into another component included.
369
804
 
370
805
  **A `<slot>` inside another slot's fallback works**, and takes over at the moment that fallback
371
806
  becomes visible — the same thing the platform does, verified by layout on three engines. Slots are
@@ -389,18 +824,17 @@ it work would mean writing framework attributes into the user's own markup.
389
824
 
390
825
  **A node added AFTER the first render joins its slot with full native semantics** — bare text and
391
826
  attribute-less elements included, in document order, exactly as a shadow root would assign them.
392
- The renderer stamps everything it emits at a light host's top level with a hidden, non-enumerable
393
- property, so an unstamped node there is knowably the user's; `slot=""`/`slot="name"` still route,
394
- they are simply no longer required.
395
-
396
- This used to be the feature's one documented divergence, and the rule existed because a light
397
- host's children after the first render are also the component's own rendered output, with nothing
398
- in the DOM to tell them apart. Ownership is written down now rather than inferred from position,
399
- so the ambiguity — and the rule — are gone. Two things remain worth knowing: whitespace appended
400
- to a light host suppresses the default fallback, which is parity (a shadow root does the same), and
401
- re-slotting a node (`slot="a"` → `"b"`) rejoins in light-tree order rather than arrival order.
402
- Every position you can reach orders exactly as the platform does — what light has fewer of is
403
- positions you can name, since a distributed child is no longer a direct child of the host.
827
+ A light host's own render occupies one range of its children, bracketed by the renderer's own
828
+ comments, so a node added outside that range is knowably the user's: added before it, it joins
829
+ ahead of everything the host was given; after it, behind. `slot=""`/`slot="name"` still route, they
830
+ are simply not required. Inside a slot, use `before()`/`after()` on what is already there (see
831
+ below) and the new node joins at that place in light order.
832
+
833
+ Two things are worth knowing: whitespace appended to a light host suppresses the default fallback,
834
+ which is parity (a shadow root does the same), and re-slotting a node (`slot="a"` → `"b"`) rejoins
835
+ in light-tree order rather than arrival order. Every position you can reach orders exactly as the
836
+ platform does — what light has fewer of is positions you can name, since a distributed child is no
837
+ longer a direct child of the host.
404
838
 
405
839
  **Cloning a RENDERED light component does not work, and cannot.** `cloneNode(true)` copies a
406
840
  light host's children — which after a render are the component's own output with the user's slotted
@@ -409,26 +843,46 @@ rendered tree ends up nested inside its own default slot. A shadow component clo
409
843
  opposite reason: `cloneNode` does not copy a shadow root, so the clone re-renders and its light
410
844
  children are still just its light children.
411
845
 
412
- Nothing can detect this — the ambiguity is the same one behind the late-children rule above, and
413
- the original user content was consumed at the first render, so there is nothing to recover. **To
414
- duplicate a component, clone the SOURCE markup and let the copy render itself**, rather than cloning
415
- a live instance. This matters most to anything that duplicates components as an operation: an editor
846
+ Nothing can detect this — after a render the user's content and the component's output are the
847
+ same kind of node in the same tree, and the original user content was consumed at the first render,
848
+ so there is nothing to recover. **To duplicate a component, clone the SOURCE markup and let the copy
849
+ render itself**, rather than cloning a live instance. This matters most to anything that duplicates components as an operation: an editor
416
850
  canvas, a repeater, a drag-to-copy.
417
851
 
418
852
  **`slotted(host, name?)`** is the component-internal accessor — what the user assigned to a slot,
419
853
  answered identically in shadow mode (native assignment) and light mode (the capture map). Omit
420
854
  `name` for the default slot. Component authors reach for this; app users do not.
421
855
 
856
+ **When the assignment is current.** Whatever a template does is distributed by the end of that render — an outer
857
+ template changing a component's children included — so code measuring slotted content right after a render (a layout
858
+ effect, `getBoundingClientRect`) sees the new assignment. A light host changed directly by your code
859
+ (`host.append(node)`, `node.slot = 'x'`) is redistributed by the next microtask, or at once when its slotted content is
860
+ read through the slots API (`slotted()`, `slot.assignedNodes()`).
861
+
862
+ ### Where the `<slot>` element is
863
+
864
+ **A slot with content steps out of the page, and its content stands in its place. A slot with
865
+ nothing assigned stays in the page, showing its fallback.** So the rendered tree reads the way the
866
+ composed tree of a shadow root reads: where a slot has content, that content is a child of the
867
+ slot's parent; where it has none, the fallback is the `<slot>` element's own children, and the
868
+ HTML standard's UA stylesheet gives every `<slot>` `display: contents`, so the element itself adds no
869
+ box. The switch happens each time a slot gains its first node or loses its last one.
870
+
871
+ Two things follow. `querySelector('slot')` finds exactly the slots currently showing their
872
+ fallback, and none that have content — so reach a slot through `&ref` or `event.target`, never by
873
+ selector. And a structural selector written against your template (`:first-child`, `> h2`) sees the
874
+ slotted content where a filled slot stood, which is where a reader sees it.
875
+
422
876
  ### The `<slot>` element is still the component's handle on the slot
423
877
 
424
878
  A slot is not only a position, and a component that keeps up with what it was given binds to the
425
879
  element itself. All of that means here what it means in a shadow root:
426
880
 
427
881
  ```js
428
- render(() => html`<header>
882
+ return () => html`<header>
429
883
  <slot name=${section} &ref=${(el) => (this.slot = el)}
430
884
  @slotchange=${(e) => wire(e.target.assignedElements())}>Nothing yet</slot>
431
- </header>`);
885
+ </header>`;
432
886
  ```
433
887
 
434
888
  - **`@slotchange`** fires on first assignment and on every change after it — and only then, so a
@@ -436,15 +890,38 @@ render(() => html`<header>
436
890
  `assignedNodes()` are asserted against real shadow DOM, which is the oracle for this. It fires
437
891
  for a slot whose rendering is currently displaced too (assignment is independent of rendering),
438
892
  exactly as native does for a slot that is not on screen.
439
- - **`node.assignedSlot` answers `null` — ask the slot, not the node.** The reverse lookup is a
440
- platform accessor tied to real shadow assignment, and overriding it on YOUR nodes is an intrusion
441
- this module refuses. The forward reads carry the same fact: `slot.assignedNodes().includes(node)`
442
- through a `&ref`, or `slotted(host, name)` from outside.
443
- - **Bind `slotchange` directly — it does not bubble to the host.** In a shadow root one listener on
444
- the root hears every slot by bubbling; here the slot handles are deliberately out of the document,
445
- so there is no tree for the event to climb and `host.addEventListener('slotchange', …)` hears
446
- silence. Use `@slotchange` on each slot, which also hands you the right `event.target`. (The same
447
- boundary as `querySelector('slot')`: fewer places to listen, not fewer events.)
893
+ - **`node.assignedSlot` answers light slots too.** The platform's getter knows only shadow roots, so slots replaces it
894
+ once per window, at that window's first light host. It answers for the nodes slots placed, from what distribution
895
+ already records (nothing is written per node), and defers to the getter it replaced for every other node, so
896
+ shadow-DOM nodes, other copies of Vera, and other code that patched it answer as before. One case stays native: a node
897
+ created in another window (an iframe's parent) and placed into a light host here reads `null` unless its own window
898
+ also has a light host. The forward reads carry the same fact: `slot.assignedNodes()` through a `&ref`, or
899
+ `slotted(host, name)` from outside.
900
+ - **Only a component that needs slotting pays for it.** One with no light content and no `<slot>` gets no observer and
901
+ no hidden element; a component is observed from its first `<slot>`. So a child appended by hand to a component that
902
+ has neither shows until a slot renders — native hides it. `observeSlots: 'eager'` observes a component
903
+ from its first render instead — `init({ host: this, observeSlots: 'eager' }, setup)` — as a shadow root follows
904
+ every host; `wire([renderer, slots({ observeSlots: 'eager' })])` makes that every light component's default (its own
905
+ `observeSlots` wins), at an observer per component. The default, `'lazy'` (paired as HTML's `loading` pairs them),
906
+ starts at the first `<slot>` or light child and is fully correct for everything a template renders. A value it does
907
+ not have reads as `'lazy'` — the built-in default, even where the app's is `'eager'`, as `foreignNodes` does — and
908
+ development says so.
909
+ - **A component you remove by hand and put back follows the hand-edit rule.** What its outer template then writes into
910
+ it is distributed by the component's own observer, a microtask later, not by the end of that template's render; the
911
+ slots API reads it at once (it flushes), and a direct DOM read in the same task can still see the old content.
912
+ - **A `<slot>` removed by hand unassigns its content, as in a shadow root.** Its content shows in the next slot of that
913
+ name, or nowhere: through the slot's own `remove()` / `replaceWith()`, or by removing its parent or an ancestor (a
914
+ microtask later, the hand-edit rule). One spelling cannot work: a slot WITH content has stepped out of the page (its
915
+ region stands in its place), so `slot.parentNode` is `null` and `parentNode.removeChild(slot)` has nothing to call.
916
+ - **Insert `<slot>`s through the template, or observe the component eagerly.** On a component observed lazily (the
917
+ default), a `<slot>` inserted by hand is not one the template rendered, so it stays empty, where a shadow root uses it
918
+ at once. With `observeSlots: 'eager'` it is claimed like the template's own. Rendering the slot conditionally
919
+ (`${open ? html`<slot></slot>` : null}`) works in every mode.
920
+ - **Bind `slotchange` directly — do not count on it reaching the host.** In a shadow root one listener
921
+ on the root hears every slot by bubbling. Here a slot with content is out of the document, so the
922
+ event fired as it fills has no tree to climb, while the one fired as it empties — the slot is back
923
+ in the page by then — does climb: a host-level listener hears some changes and not others. Use
924
+ `@slotchange` on each slot, which hears all of them and hands you the right `event.target`.
448
925
  - **`assignedNodes(options)` / `assignedElements(options)`** answer from the live assignment,
449
926
  through `event.target` or a `&ref`. With nothing assigned, `{ flatten: true }` gives the fallback
450
927
  actually on screen — slottables only, so a comment you wrote into fallback content is not in it,
@@ -456,139 +933,88 @@ render(() => html`<header>
456
933
  root the same line works, because there nothing moves. `before()`/`after()` route through the
457
934
  node's own current parent, so they are correct in both modes, and the content lands in the order
458
935
  you asked for. This is the sharpest difference between the two modes and the easiest to hit.
459
- - **A displaced node is *disconnected* here; native slotting never disconnects it.** Shadow
460
- distribution is virtual — a slottable no slot names stays in the light tree, connected, merely
461
- unrendered. Light slots park it physically, so a custom element inside displaced content runs its
462
- `disconnectedCallback` (and a Vera component's effect cleanups) on the way out, and
463
- `connectedCallback` again when its slot returns — with its element identity, stores and typed-in
464
- state intact, and reactivity re-established by the re-init. Component authors already handle this
465
- pair for any `appendChild` move; the difference is only *when* it happens: a component that
466
- pauses a video on disconnect pauses while displaced here and keeps playing in a shadow root.
467
- The slot element is deliberately not in your DOM (see below), so it is unreachable by selector and
468
- reports `isConnected === false`. It is a live API object, not a position in the tree.
936
+ - **A slotted component is MOVED into its slot, and a Vera component is not torn down by it.** Each
937
+ slotted node goes from where it is to where it is shown in ONE DOM operation, which core treats as a
938
+ move: a component that called `init()` keeps its effects, state and setup through it — nothing runs
939
+ twice, as nothing runs twice under native slotting, where nothing moves at all. A custom element
940
+ that is not a Vera component gets the platform's callbacks for a move: `disconnectedCallback` and
941
+ then `connectedCallback`.
942
+ - **A node no slot takes stays connected, and is not rendered — as under native slots.** A light
943
+ host has no second tree to hide it in, so it waits in a hidden container the host is given for
944
+ the purpose, `<ins hidden data-vm-unassigned>`, its FIRST child: a component in it keeps running (its
945
+ effects stay live), it is still in the host's tree for `querySelector`, as a native unassigned
946
+ light child is, and when a
947
+ slot for it appears it moves there in one operation and is kept. The container is there only
948
+ while it holds something, so a host whose content is all assigned has no extra child. When it is
949
+ there, it is a child of your host like any other: `host.children`, `:scope > *`, `:first-child`,
950
+ `:nth-child()` and `:empty` see it — write `:scope > :not([data-vm-unassigned])` where that matters.
951
+ It stays hidden whatever a stylesheet says (an inline `display: none !important` beside `hidden`).
952
+ It is a standard element, so it is valid HTML around any content, and `:defined`: a lazy loader
953
+ or a "wait until every element is defined" check never waits on it.
469
954
  - **`name` can be a binding.** `<slot name=${section}>` routes by the name it actually has, and
470
955
  re-routes if it changes between renders.
471
956
 
472
- ### Keeping the `<slot>` in the tree — a strategy you can own
473
-
474
- Every boundary above has one cause: the shipped strategy removes the `<slot>` element so your
475
- markup stays exactly what you wrote. The seam it registers through is public, single-registrant,
476
- and takes whole strategies — so if you would rather have the *shadow tree's own structure* (the
477
- slot element present, selectable, `:first-child`-countable, made layout-invisible by the same
478
- `display: contents` the UA stylesheet gives real slots), you can wire a strategy that keeps it.
479
- This one is complete enough to run — and it runs, in CI, as written:
480
-
481
- <!-- recipe -->
482
- ```js
483
- import { init, render, wire, html } from '@verajs/core';
484
- import { renderer } from '@verajs/renderer';
485
-
486
- /** Distribution that KEEPS the <slot>: content moves INSIDE it, fallback shows when it is empty. */
487
- const slotsInTree = {
488
- name: 'my-app/slots-in-tree',
489
- on: 'slot',
490
- priority: 50,
491
- fn(slot, root, name) {
492
- if (root.nodeType !== 1) return null; // a shadow root keeps native slotting
493
- const host = root;
494
- const fallback = [...slot.childNodes];
495
- const isMine = (n) =>
496
- n.nodeType === 1 ? (n.getAttribute('slot') ?? '') === name
497
- : name === '' && n.nodeType === 3 && n.data.trim() !== '';
498
- let shown = -1;
499
- const fill = () => {
500
- for (const n of [...host.childNodes]) if (isMine(n)) slot.append(n);
501
- const assigned = [...slot.childNodes].filter((n) => !fallback.includes(n));
502
- for (const n of fallback) (assigned.length ? n.remove() : slot.append(n));
503
- observer.takeRecords(); // our own moves are not the user's
504
- if (assigned.length !== shown) {
505
- shown = assigned.length;
506
- slot.dispatchEvent(new Event('slotchange', { bubbles: true })); // real ancestors — it CLIMBS
507
- }
508
- };
509
- const observer = new MutationObserver(fill);
510
- fill();
511
- observer.observe(host, { childList: true, subtree: true });
512
- return { _$park$: () => { observer.disconnect(); for (const n of [...slot.childNodes]) if (!fallback.includes(n)) host.append(n); } };
513
- },
514
- };
515
-
516
- wire([renderer, slotsInTree]);
517
- document.head.insertAdjacentHTML('beforeend', '<style>slot{display:contents}</style>');
518
-
519
- customElements.define('tree-card', class extends HTMLElement {
520
- connectedCallback() {
521
- init(this);
522
- render(() => html`<article><slot name="header">Untitled</slot></article>`);
523
- }
524
- });
525
-
526
- const card = document.createElement('tree-card');
527
- card.innerHTML = '<h2 slot="header">Hello</h2>';
528
- document.body.append(card);
529
- await new Promise((resolve) => requestAnimationFrame(resolve));
530
-
531
- /** Every documented boundary of the shipped strategy, working: */
532
- let heard = 0;
533
- card.addEventListener('slotchange', () => heard++); // a HOST-level listener — bubbling exists here
534
- if (!card.querySelector('slot')) throw new Error('querySelector finds the slot');
535
- if (card.querySelector('h2').parentElement.localName !== 'slot') throw new Error('reverse lookup');
536
- card.querySelector('h2').remove();
537
- await new Promise((resolve) => setTimeout(resolve, 0));
538
- if (card.querySelector('article').textContent !== 'Untitled') throw new Error('fallback returns');
539
- if (heard !== 1) throw new Error('slotchange bubbled to the host');
540
- ```
541
-
542
- The trade is the one the platform itself makes: this is the shadow tree's structure, so the
543
- `<slot>` now appears in your host's serialized markup (as it appears in a `shadowRoot`'s), your
544
- component CSS can select it — and structural selectors written against the template see it as the
545
- child it is, because selectors follow the tree, not layout. Wire it *instead of* `slots` — the
546
- seam is single-registrant, and wiring both says so in development, by name.
547
-
548
- What this recipe deliberately does not do is the audited module's territory: light-tree ordering
549
- under re-slots and prepends, duplicate-name handover, nested slots in fallbacks, dynamic
550
- `name=${…}`, SSR and hydration. It is a starting point you own, not a drop-in peer — the measured
551
- design for a full sibling lives with the maintainers.
552
-
553
- **The one thing a light-DOM slot cannot carry is presentation** — `class`, `style`, `id` and other
554
- plain attributes. A light host has no second tree, so the slot element is not rendered and there is
555
- nothing for them to apply to, while in a shadow root they do apply. Put them on a real element
556
- around the slot. Development builds say so, naming the attribute, rather than leaving it to be
557
- found.
957
+ **A `<slot>` carries presentation only while it shows its fallback** — `class`, `style`, `id` and
958
+ other plain attributes. Once it has content it steps out of the page and its attributes go with it,
959
+ while in a shadow root they keep applying. Put them on a real element around the slot. Development
960
+ builds say so, naming the attribute, rather than leaving it to be found.
558
961
 
559
962
  Additive like `keyed`/`spread`: it imports no renderer and reaches the one present through the wired
560
963
  seam, so it is safe beside any renderer entry on a CDN page. The entry is
561
- **<!--size:slots.gzip-->3.35 KB<!--/size:slots.gzip-->** gzipped and only apps importing it pay;
562
- `@verajs/renderer` itself carries just the seam that records where a template's slots are. It is
563
- also Node-safe — it imports nothing and touches no global document — so a universal app can wire it
564
- on both sides.
964
+ **<!--size:slots.gzip-->6.22 KB<!--/size:slots.gzip-->** gzipped and only apps importing it pay;
965
+ `@verajs/renderer` itself carries only generic hooks it plugs into. It is also Node-safe to import —
966
+ it imports nothing and touches no DOM until something renders — so a universal app can wire it on
967
+ both sides.
565
968
 
566
- ## `@verajs/renderer/hydrate`
969
+ ## `@verajs/renderer/hydration`
567
970
 
568
971
  <!-- recipe -->
569
972
  ```js
570
- import { renderer } from '@verajs/renderer/hydrate'; // instead of '@verajs/renderer'
571
- ```
973
+ import { wire } from '@verajs/core';
974
+ import { renderer } from '@verajs/renderer';
975
+ import { hydration } from '@verajs/renderer/hydration';
572
976
 
573
- Same name, same `wire([renderer])`, different entry — this one's `renderer` binds the adopting
574
- render below, so swapping the import (or the importmap target) really is the only change.
977
+ wire([renderer, hydration]);
978
+ ```
575
979
 
576
- The first render into a container that already has children **adopts** them as server output of the
577
- same template: node identity is preserved, listeners attach, and updates mutate the adopted nodes.
578
- Hydration here is **markerless** — server HTML carries no framework comments, and the client repairs
579
- its own anchors into the adopted DOM.
980
+ One more module wired beside the renderer — nothing else changes. The first render into a container that already has
981
+ children **adopts** them as server output of the same template: node identity is preserved, listeners attach, and
982
+ updates mutate the adopted nodes. Hydration here is **markerless** — server HTML carries no framework comments (light
983
+ slots aside: each filled slot's content sits between two, see [`/slots`](#verajsrendererslots--light-dom-slots)), and
984
+ the client repairs its own anchors into the adopted DOM.
985
+
986
+ **Server-rendered HTML must be hydrated.** A client that does not wire `hydration` renders beside the server's markup
987
+ — two copies, the server's dead — because a first render appends, and markup without a marker cannot be recognized.
988
+ The one case that can be: with slots wired, the server states every component host it renders, so on a client
989
+ without `hydration` a host stated empty (no light content) is cleared and rendered once, and a host holding the page's
990
+ light content stands exactly as served with a coded error (`hydration-unwired`; development names what to wire); development warns
991
+ once per page. A host that arrives with no children at all is simply rendered fresh, whatever its statement says, since
992
+ there is nothing to duplicate or lose. Its `data-vm-light` attribute is then left in place. That is harmless: only a
993
+ host's first render ever reads it, and a server re-states it on every render, so a copy of the live page (an editor's
994
+ save, a devtools copy of `outerHTML`) carrying it is no different from served markup.
580
995
 
581
996
  Any disagreement with the server markup clears the container (keeping `<style data-vm-sheet="styles">` tags)
582
997
  and renders fresh, so correctness never depends on the server output being right. A DOM node at a
583
998
  child position is the one thing the server cannot have rendered; it is inserted without giving up
584
999
  adoption of everything around it.
585
1000
 
586
- **A fallback warns in development, naming the first place the two renders disagreed** — *"expected
587
- `<p>` and found `<div>`"*, *"`<ul>` contains `<li>`, which the template does not describe"*. The page
1001
+ **A fallback warns in every build, naming the first place the two renders disagreed** — development
1002
+ spells it out, *"expected `<p>` and found `<div>`"*, *"`<ul>` contains `<li>`, which the template does
1003
+ not describe"*; production prints the kind and the node it found. It is said once per kind of
1004
+ disagreement per hydration pass, so a list whose every row disagrees the same way is one line. The page
588
1005
  is correct either way, which is the point of the fallback and also why it needs saying: that
589
1006
  container's markup was just thrown away, and with nothing observable to notice, the only symptom is
590
- a first paint that is slower than the one you paid a server render for. An attribute that disagrees
591
- is simply re-set during adoption and is not a fallback at all.
1007
+ a first paint that is slower than the one you paid a server render for. An attribute is **read** during
1008
+ adoption and written only if it disagrees — a right one costs no write, a wrong one is repaired — and
1009
+ neither is a fallback.
1010
+
1011
+ **Form state stands.** A form control's `.value`, `.checked` and `.selected`, a `!name` on a built-in
1012
+ element and a `<select>`'s selection are recorded, not written, so whatever the user typed before the
1013
+ script arrived is kept (a `!name` then compares on the next render and takes over, as it always does).
1014
+ **Whoever writes an element's content owns its verification.** A custom element's children are its own
1015
+ render: when the template writes nothing inside the tag, adoption leaves them to the component (what the
1016
+ template does write inside it is compared as usual). And an element whose whole content is one `${…}`
1017
+ adopts as that value's range, with no marker put in.
592
1018
 
593
1019
  **A fallback costs one container, not the page.** Adoption is decided per container, so components
594
1020
  hydrating into their own roots are independent: one that disagrees rebuilds and warns, and every
@@ -601,23 +1027,22 @@ required in the server markup, and one in the server markup that your template d
601
1027
  a disagreement. A comment renders nothing, so neither direction changes what a reader sees; matching
602
1028
  on them would only cost every commented template its adoption.
603
1029
 
604
- On a CDN page, point the import map's `@verajs/renderer` at `vera-renderer-hydrate.min.js` and
605
- nothing else changes. Apps that never hydrate download none of this.
1030
+ On a CDN page, load `vera-renderer-hydration.min.js` beside `vera-renderer.min.js`, from the same version, and wire both. Apps that never
1031
+ hydrate download none of this.
606
1032
 
607
1033
  ### Importing this in Node
608
1034
 
609
1035
  **`@verajs/renderer` needs a DOM to be imported at all**, not merely to render. It captures
610
- `document` at module scope and builds two shared `TreeWalker`s there, which is what saves an
611
- allocation per instance — so `import '@verajs/renderer'` on a server throws
1036
+ `document` at module scope (and creates its scratch fragment there) — so `import '@verajs/renderer'` on a server throws
612
1037
  `ReferenceError: document is not defined` before any of your code runs. The same is true of
613
- `/hydrate` and `/profiler`, and of `@verajs/jsx/standalone`, which contains a renderer.
1038
+ `/profiler`, and of `@verajs/jsx/standalone`, which contains a renderer.
614
1039
 
615
1040
  This is worth stating because [`@verajs/router`](../router#node-and-ssr) documents the opposite
616
1041
  about itself, and the asymmetry is easy to read the wrong way. The rest of the family is Node-safe:
617
1042
  `@verajs/core`, `@verajs/inserts`, `@verajs/store` and `/collections`, `@verajs/router`,
618
1043
  `@verajs/styles`, `@verajs/autoloader`, `@verajs/jsx` (the transform), `@verajs/ssr` — **and
619
- `@verajs/renderer/keyed`, `/spread` and `/tag`**, which hold no DOM of their own even though their
620
- parent entry does.
1044
+ `@verajs/renderer/keyed`, `/spread`, `/tag`, `/hydration` and `/hydrate-slots`**, which hold no DOM of their own even
1045
+ though their parent entry does.
621
1046
 
622
1047
  In a universal app, hand the renderer in rather than importing it in shared code — which is what
623
1048
  `examples/kitchen-sink/wiring.js` does, taking it as a parameter so the server can pass `null`.
@@ -629,7 +1054,7 @@ Spread a props object onto an element, with names resolved at runtime.
629
1054
 
630
1055
  <!-- recipe -->
631
1056
  ```js
632
- import { init, createStore, render, wire, html } from '@verajs/core';
1057
+ import { init, createStore, wire, html } from '@verajs/core';
633
1058
  import { renderer } from '@verajs/renderer';
634
1059
  import { spread } from '@verajs/renderer/spread';
635
1060
 
@@ -639,16 +1064,17 @@ customElements.define(
639
1064
  'x-field',
640
1065
  class extends HTMLElement {
641
1066
  connectedCallback() {
642
- init(this, { mode: 'open' });
643
- const state = createStore({ disabled: false });
644
- const props = {
645
- id: 'email', // attribute
646
- placeholder: 'you@example.com', // "
647
- '.value': '', // property
648
- '?disabled': state.disabled, // boolean attribute
649
- onInput: (e) => console.log(e.target.value), // event — @input works too
650
- };
651
- render(() => html`<input ${spread(props)} />`);
1067
+ init({ host: this, shadow: 'open' }, () => {
1068
+ const state = createStore({ disabled: false });
1069
+ const props = {
1070
+ id: 'email', // attribute
1071
+ placeholder: 'you@example.com', // "
1072
+ '.value': '', // property
1073
+ '?disabled': state.disabled, // boolean attribute
1074
+ onInput: (e) => console.log(e.target.value), // event — @input works too
1075
+ };
1076
+ return () => html`<input ${spread(props)} />`;
1077
+ });
652
1078
  }
653
1079
  }
654
1080
  );
@@ -689,7 +1115,7 @@ html`<calendar-day ${props({ date, events })}></calendar-day>`
689
1115
  <calendar-day date={date} events={events} /> // JSX only: bare props ARE props on a component tag
690
1116
  ```
691
1117
 
692
- One function, both surfaces — JSX compiles `{...x}` to `spread(x)`, and `spread()` recognises an
1118
+ One function, both surfaces — JSX compiles `{...x}` to `spread(x)`, and `spread()` recognizes an
693
1119
  already-branded result, so the two spellings are literally the same call. In JSX the bag is
694
1120
  optional altogether: on a dash-named tag a bare prop compiles to the `.name` binding directly
695
1121
  (`@verajs/jsx`'s README has the two attribute carve-outs), so `props()` is the template's
@@ -715,7 +1141,7 @@ Three rules, each earned:
715
1141
 
716
1142
  Nothing to declare on the other side — no `static properties`, no props argument. A component that
717
1143
  calls `init()` finds every bound property on `this`, **reactively**: reading `this.date` in a
718
- render tracks it, the parent's next commit re-renders, and a store or `ref()` passed through stays
1144
+ render tracks it, the parent's next commit re-renders, and a store or `signal()` passed through stays
719
1145
  live because it arrives by identity. The full reception contract — including what happens when the
720
1146
  component's module loads *after* the parent rendered — is documented with `init()` in
721
1147
  `@verajs/core`'s README; this package's half is the delivery:
@@ -770,12 +1196,11 @@ written `@event` bindings behave too.
770
1196
 
771
1197
  ### What it costs, and why it is a separate entry
772
1198
 
773
- `@verajs/renderer` grows **5 B** gzipped for the protocol this uses, whether or not you import it —
774
- measured 2026-08-27 by deleting the `_$apply$` branch and rebuilding, as a **difference** rather than
775
- a pair of totals — the totals move with every change to this package and the difference does not,
776
- which is the mistake this line already made once. `llms.txt` and this file disagreed about the figure
777
- for a while, at 16 B and 8 B respectively, and both were wrong. Nothing regenerates it, so it is
778
- dated; re-measure the same way if it matters.
1199
+ `@verajs/renderer` grows **25 B** gzipped for the protocol this uses, whether or not you import it —
1200
+ measured 2026-09-28 by deleting the `_$apply$` branch and its teardown guard (a released ref must not
1201
+ write `.value = null` onto an object that applies itself) and rebuilding, as a **difference** rather
1202
+ than a pair of totals — the totals move with every change to this package and the difference does not.
1203
+ Nothing regenerates it, so it is dated; re-measure the same way if it matters.
779
1204
  The entry itself is **<!--size:spread.gzip-->1.60 KB<!--/size:spread.gzip-->** gzipped, and only apps
780
1205
  that import it pay for that.
781
1206
 
@@ -788,7 +1213,7 @@ small and fast, and it is why neither this renderer nor lit-html has spread buil
788
1213
 
789
1214
  The renderer itself holds only a protocol: a value at element position carrying `_$apply$` applies
790
1215
  itself. Everything else lives in this entry, which imports nothing — not even from the renderer — so
791
- it loads alongside any renderer that honours the protocol, including your own.
1216
+ it loads alongside any renderer that honors the protocol, including your own.
792
1217
 
793
1218
  ## `@verajs/renderer/profiler`
794
1219
 
@@ -848,17 +1273,111 @@ renderInto(html`<div .innerHTML=${trustedMarkup}></div>`, host);
848
1273
 
849
1274
  Greppable, obviously yours, reviewable as the security decision it is. Sanitize first
850
1275
  (`DOMPurify.sanitize`) unless the markup is genuinely your own, and put it on an element whose
851
- children nothing else binds — the renderer owns the content of elements it renders into.
1276
+ children nothing else binds — the renderer owns the content of elements it renders into. `@verajs/ssr`
1277
+ serializes it into the served page and hydration adopts it, behaving as the assignment does: a `<script>` in it
1278
+ never runs and a `<template shadowrootmode>` never attaches, on either side.
1279
+
1280
+ **Only a tagged template is a template.** A value renders as markup only when its strings came from a tagged
1281
+ template literal — an array owning `raw`, which nothing from `JSON.parse` can be. Data shaped like a template (an
1282
+ API field an attacker turned into `{"strings": [...]}`, a real template sent through JSON, or a hand-built
1283
+ `html([markup])`) renders as the text any object does, `[object Object]`, here and in `@verajs/ssr` alike — and here,
1284
+ in development, with a warning each time a new one arrives. Never a throw: the value is attacker-controlled, and a throw would hand over the subtree. The
1285
+ check runs where a template is first built, so a cached template pays nothing. (An ordinary object interpolated
1286
+ as a child renders as `String(object)`, as before; one that cannot convert — a parsed `"toString"` key — throws,
1287
+ as it does in React. Render a field, not a raw API object.)
1288
+
1289
+ **Development tells you; production pays nothing.** Misuse the renderer can see in a template's own source, or in an
1290
+ obviously wrong call, is caught in development: a template that cannot work as written throws there (a name
1291
+ expression, below; a value in TAG position, `<${x}>`, which needs a tag value from `@verajs/renderer/tag`;
1292
+ `renderInto` without a container; `keyed` without a template; a template ending inside a tag; a binding beside or
1293
+ inside an element in an SVG/MathML `<title>` or `<style>`, which this renderer reads as text), and a mistake that still renders
1294
+ but not as meant is a `[vera]` warning (a self-closed `<div />`, a boolean child, a value that cannot
1295
+ listen, `@clik`, a binding on an element the parser drops, content in the wrong namespace, a repeated key) — said
1296
+ once where the mistake is in the template's source, and each time it happens where it is in a value (a boolean
1297
+ child, a value that cannot listen, a repeated key). None of
1298
+ it exists in the production build — those bundles are byte-for-byte what they would be without it.
1299
+
1300
+ **An attribute name cannot be an expression.** `<p data-${key}="1">` (or `<b ${name}="x">`, or
1301
+ `<p ${key}-x>`) throws in development when the template is first used — `@verajs/ssr` refuses it in every
1302
+ build — because the parser reads a name before any value exists. (Production pays nothing for the check:
1303
+ a template is fixed source, so its first development render finds it.) A name known only at runtime is a spread —
1304
+ `${spread({ [`data-${key}`]: '1' })}` — which refuses what a runtime name must not become (an inline handler,
1305
+ `srcdoc`, a `javascript:` URL); in development the error shows that rewrite for your template.
1306
+
1307
+ **Security: a bound URL cannot be a `javascript:` URL, and a bound `srcdoc` is refused.** A value
1308
+ bound where a browser *navigates* — `href`, `src`, `action`, `formaction`, `xlink:href` or `data`,
1309
+ as the attribute or as its property — is refused when it parses as a `javascript:` URL, and the
1310
+ attribute is removed. The same holds for an SVG animation's `to`, `from`, `by` and `values` (every item
1311
+ of a `values` list), on any element and whatever `attributeName` says: `<animate>`/`<set>` write their
1312
+ value onto the attribute they animate, `href` included, and Chromium, Firefox and WebKit all run a
1313
+ `javascript:` URL set on a link that way when it is clicked. It is read the way the URL Standard reads
1314
+ a scheme, so `" jAvA\tscript:"` is caught as surely as `javascript:`, and it is judged on the whole JOINED value, so `href="java${x}"` is
1315
+ caught too; the statics you write are yours and are never refused on their own. A value that is not a
1316
+ string is converted ONCE and the string checked is the string written, so an object whose `toString`
1317
+ changes its answer cannot pass as one URL and land as another. A custom element's property of the same
1318
+ name (`<my-chart .data=${rows}>`) is its own business: an object arrives untouched, and only a string is
1319
+ checked. A bound `srcdoc`
1320
+ *attribute* is refused outright, because it renders its value as an HTML document —
1321
+ `.srcdoc=${trusted}` is the deliberate spelling, exactly as `.innerHTML` is. There is no opt-out for
1322
+ URLs. `@verajs/ssr` applies the same rule, so a server never serves a link the client refuses.
1323
+ Development builds name each refusal.
1324
+
1325
+ **Security: a value enters a `<script>` only as a JSON data block.** A value in a script's text is code: on a page
1326
+ `@verajs/ssr` rendered, the browser runs it, and a value holding `<!--<script>` would make the rest of the page script
1327
+ text. So a script hole is accepted only when the script is a JSON data block — its `type`, as written in the template,
1328
+ ends in `json` (`application/json`, `application/ld+json`), with no character reference — for handing state to the
1329
+ client or for JSON-LD:
1330
+
1331
+ ```js
1332
+ html`<script type="application/ld+json">${JSON.stringify(schema)}</script>`;
1333
+ ```
1334
+
1335
+ Any other script hole is refused, in every build: by `@verajs/ssr` (`ssr-script-hole`) and by this renderer
1336
+ (`script-hole`). A template's HTML `<script>` never runs on the live page, but a page saved from the DOM and served again
1337
+ runs it, and an SVG `<script>` from a template runs in Chromium and WebKit — so an SVG script hole is refused even with
1338
+ a JSON type. The start tag judged is the one that opened the script, never one found in the script's own text.
1339
+
1340
+ **A `<style>`'s or a data block's text stays text after the page is saved and parsed again.** A browser serializes such
1341
+ an element's text exactly as it is, so a value written into it as it stands would become markup once the page is saved
1342
+ from the DOM (`outerHTML`, an editor's publish) and served again. So the renderer and `@verajs/ssr` write the same
1343
+ bytes: the element's statics and values composed together (a closer can form across a hole), a data block's every `<`
1344
+ as `\u003c`, which JSON reads back unchanged, and a style's every `</style` as `<\/style`, the same CSS. Hydration
1345
+ adopts a served text equal to that, and rewrites one that differs.
1346
+
1347
+ **A value in a text-only element is text, the same on every tier and the server** — a `<style>`, a JSON block, an HTML
1348
+ `<title>` or `<textarea>`: nothing for `null`/`undefined`, a list its items' text (nested lists flattened), anything
1349
+ else `String(value)`. A **template** in a `<style>` or a JSON block is **refused** (`template-in-text`; the server's
1350
+ `ssr-template-in-text`) — its markup is not text, so `<style>${rules.map(…)}</style>` joins the rules. In an HTML
1351
+ `<title>` or `<textarea>` the renderer places a template, as it always has, and development warns that it is never
1352
+ shown there (`template-in-text`); **the server refuses it** (`ssr-template-in-text`). That is a recorded difference: such
1353
+ a template is a mistake either way, and the server cannot write elements a browser would keep there (it reads that
1354
+ content back as text). An SVG `<title>` is markup (an integration point), so a template there renders, as the server
1355
+ renders it.
1356
+
1357
+ **A value inside an element whose content is never shown is text that can never become markup** — an `<iframe>`, a
1358
+ `<noscript>`, and the obsolete `<xmp>`, `<noembed>`, `<noframes>` and `<plaintext>`. The renderer writes each value
1359
+ there fully encoded (every ASCII character but a letter, digit or `_` as a character reference), so a page saved from
1360
+ the DOM and parsed again, with scripting on or off, holds no value that ends the element or adds an attribute; an
1361
+ analytics pixel's URL in a `<noscript><img src=${…}>` reads back intact. A template there is refused
1362
+ (`template-in-text`). The server writes these values escaped as text, so its bytes differ from the client's, and
1363
+ hydration rewrites that text rather than adopting it. `@verajs/lite` and `@verajs/static` refuse a value there.
1364
+
1365
+
1366
+ **`.textContent` into a `<style>` or `<script>` is the platform's, not a template hole.** A browser serializes such an
1367
+ element's text exactly as it is, so a user value written there with `.textContent=${value}` (or any DOM write) becomes
1368
+ markup the moment the page is saved through `innerHTML`/`outerHTML` and parsed again. Escape `</` in such a value
1369
+ yourself, or put it in a template hole, which does.
852
1370
 
853
1371
  **Security: spread refuses the injection sinks.** The `.innerHTML` posture above rests on the
854
1372
  template spelling being greppable, obviously yours, and reviewable — three properties a spread key
855
1373
  does not have, because spread names arrive at runtime inside a props object that is often built
856
1374
  from data. So `spread()` refuses `.innerHTML`/`!outerHTML` property keys, the `srcdoc` attribute,
857
- and any inline-handler attribute name (`onclick` and friends, any casing — `on` + Capital with a
858
- function remains the documented event spelling and still works), on the client AND in the SSR
859
- serializer alike. Development builds name each refused key and the sanctioned template spelling.
1375
+ any inline-handler attribute name (`onclick` and friends, any casing — `on` + Capital with a
1376
+ function remains the documented event spelling and still works), and — as a template binding is —
1377
+ a `javascript:` URL on a key a browser navigates (`href`, `.href` and the rest), on the client AND
1378
+ in the SSR serializer alike. A key's verdict is decided once, when it first appears, not per render. Development builds name each refused key and the sanctioned template spelling.
860
1379
  If you genuinely need one of these dynamically, write the binding in the template where a reviewer
861
- can see it.
1380
+ can see it — for `srcdoc`, the property: `.srcdoc=${trusted}`.
862
1381
 
863
1382
  ## `@verajs/renderer/tag`
864
1383
 
@@ -902,7 +1421,7 @@ component: `@verajs/jsx` consumes it into `keyed(…)` for both spellings, and a
902
1421
  `H({ key })` drops it and says so in development, because a key marks a template for reconciliation
903
1422
  and this call *returns* one rather than being one.
904
1423
 
905
- **`dangerouslySetInnerHTML` is the one React name a tag cannot honour, and that is a security
1424
+ **`dangerouslySetInnerHTML` is the one React name a tag cannot honor, and that is a security
906
1425
  property rather than a gap.** A tag reaches its element through `/spread`, whose names are only
907
1426
  known at runtime — which is exactly what makes that sink unreviewable — so `/spread` refuses
908
1427
  `.innerHTML` outright. Write the element directly, with the value sanitized first:
@@ -928,7 +1447,7 @@ life of three defects.
928
1447
  writing tests for it.
929
1448
  - HTML only. There is no `svg`/`mathml` equivalent yet.
930
1449
 
931
- <!--size:tag.gzip-->2.20 KB<!--/size:tag.gzip--> gzipped, which includes `/spread` — the factory
1450
+ <!--size:tag.gzip-->2.36 KB<!--/size:tag.gzip--> gzipped, which includes `/spread` — the factory
932
1451
  needs it to apply props whose names it cannot know. Additive, like `/spread` and unlike the other
933
1452
  entries: it inlines no renderer internals, so it is safe alongside any of them.
934
1453
 
@@ -950,18 +1469,29 @@ BOOLEAN_ATTRIBUTES.has('disabled'); // true — the names the tag entry toggles
950
1469
 
951
1470
  The renderer holds no directive system. It holds a **protocol**, at the two positions worth
952
1471
  extending, and everything built on it is an ordinary package the renderer knows nothing about —
953
- `@verajs/renderer/spread` is the proof, at 5 B of protocol in this bundle and its own weight only
1472
+ `@verajs/renderer/spread` is the proof, at 25 B of protocol in this bundle and its own weight only
954
1473
  for apps that import it.
955
1474
 
956
1475
  | position | brand | called as |
957
1476
  | --- | --- | --- |
958
- | element — `<div ${value}>` | `_$apply$` | `value._$apply$(element, part)` |
959
- | child — `<div>${value}</div>` | `_$child$` | `value._$child$(part, previous)` |
1477
+ | element — `<div ${value}>` | `_$apply$` | `value._$apply$(element, part, untracked, adopting)` |
1478
+ | child — `<div>${value}</div>` | `_$child$` | `value._$child$(part, previous, adopting)` |
1479
+
1480
+ `adopting` is `true` exactly once, while `hydration` adopts server markup: leave form state
1481
+ alone, and adopt what the server rendered at the position or replace it — an applier that ignores the flag
1482
+ renders, which replaces. (`untracked` is how an applier runs someone else's code without subscribing the
1483
+ render — see core's `untrack`.)
960
1484
 
961
1485
  A child-position value carrying `_$child$` applies itself. It is handed the part and whatever it
962
1486
  returned last time **at that part**, and calls `part._$commit$(value)` to render content. That is
963
1487
  the whole surface: `until()` is nine lines against it.
964
1488
 
1489
+ Both kinds apply **mid-commit** — `_$apply$` has to, because properties must reach an element before it
1490
+ is inserted and upgraded. So an element an applier receives may not be in its document yet: a template
1491
+ with no custom element is cloned from the browser's inert template document and inserted after its
1492
+ values commit. Read the realm lazily (`element.ownerDocument.defaultView` when it is needed, not at apply
1493
+ time), or use a ref, which runs once the element is in place.
1494
+
965
1495
  ```js
966
1496
  /** Hoisted — the applier's identity is its own continuity key. */
967
1497
  function applyUntil(part, previous) {
@@ -980,7 +1510,7 @@ renderInto(html`<p>${until(fetchUser(), html`<em>loading…</em>`)}</p>`, host);
980
1510
  Three rules, each of which is a real trap:
981
1511
 
982
1512
  - **Hoist the applier.** Written as an object-literal method it is a new function per call, so the
983
- part can never recognise it and `previous` is always `undefined`. Its identity is what keeps two
1513
+ part can never recognize it and `previous` is always `undefined`. Its identity is what keeps two
984
1514
  appliers at one part from reading each other's state.
985
1515
  - **Continuity lives in the return value**, not in an applier instance. That is what makes this a
986
1516
  protocol rather than a framework — no base class, no `directive()` factory, no lifecycle.
@@ -1026,9 +1556,11 @@ The check costs the hot path nothing: it sits after the template branch, and a t
1026
1556
  common object at a child position — returns before ever reading it, so only arrays, nodes and
1027
1557
  appliers pay a property read. Measured with no runtime difference distinguishable from noise.
1028
1558
 
1029
- The whole protocol is **116 B gzipped** — the check, the two fields holding an applier's state and
1030
- whose it is, the save/restore in `_$commit$` that stops an applier's own rendering from destroying
1031
- its continuity, and the `_$detach$` call. It was 94 B before teardown existed.
1559
+ The whole protocol is **134 B gzipped** (measured 2026-09-28 by deleting it and rebuilding) — the
1560
+ check, the two fields holding an applier's state and whose it is, the save/restore in `_$commit$` that
1561
+ stops an applier's own rendering from destroying its continuity, running a commit that arrives after
1562
+ the render returned as a render of the container that attached it (so it builds in that container's document and
1563
+ its refs run once it is done), and the `_$detach$` call.
1032
1564
 
1033
1565
  ## Animating things in and out
1034
1566
 
@@ -1081,7 +1613,7 @@ Directives other renderers ship, and what replaces them here.
1081
1613
  | --- | --- |
1082
1614
  | `repeat()` | `keyed()` |
1083
1615
  | `cache()` | `hold()` |
1084
- | `ref()` | an element-position expression, `<input ${myRef}>` |
1616
+ | `signal()` | an element-position expression, `<input ${myRef}>` |
1085
1617
  | `ifDefined()` | built in — `null`/`undefined` remove an attribute |
1086
1618
  | `classMap()` / `styleMap()` | build the string: `class="base ${extra}"` |
1087
1619
  | `guard()` | reactivity already skips unchanged work |