@verajs/renderer 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/README.md +729 -226
  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 +864 -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 +113 -138
  35. package/dist/development/vera-renderer-profiler.d.ts.map +1 -1
  36. package/dist/development/vera-renderer-profiler.js +2428 -2101
  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 +8 -29
  43. package/dist/development/vera-renderer-spread.d.ts.map +1 -1
  44. package/dist/development/vera-renderer-spread.js +542 -461
  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 -494
  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 +77 -96
  55. package/dist/development/vera-renderer.d.ts.map +1 -1
  56. package/dist/development/vera-renderer.js +2401 -2061
  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 -118
  86. package/dist/development/vera-renderer-hydrate.d.ts.map +0 -1
  87. package/dist/development/vera-renderer-hydrate.js +0 -3092
  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
@@ -1,3 +1,341 @@
1
+ /**
2
+ * **Where every diagnostic code is explained.** The URL is permanent: a released bundle is immutable, so every version
3
+ * published points here for ever — the domain cannot lapse and `/e/` cannot be reorganized without breaking links in
4
+ * code nobody can edit; the docs site redirects instead. `scripts/sync-diagnostics.mjs` imports this constant, so the
5
+ * pages and the bundles can never disagree about where they are.
6
+ */
7
+ const DOCS = 'https://verajs.dev/e/';
8
+ /**
9
+ * **One shape for every diagnostic the framework prints** — the short line production keeps, the whole sentence
10
+ * development adds — so a package converting its messages writes a table and a call, never its own format.
11
+ *
12
+ * production `[vera] hydration: element: found <i> — https://verajs.dev/e/hydration-fallback`
13
+ * development `[vera] hydration: element: found <i> — fell back to a client render: … (hydration-fallback)`
14
+ *
15
+ * `subject` is the free information — what the code already has at hand, naming the problem area — the same in both
16
+ * builds. `prose` is development only: the package's table entry (`Prose`), called behind `true ` at the call site so
17
+ * the table goes unreferenced in production and rollup drops it whole. Production prints the code inside the link, so
18
+ * the reader is one click from the explanation, which `scripts/sync-diagnostics.mjs` publishes from the same tables.
19
+ *
20
+ * **Every production message is coded** (Brian, 2026-11-11; this supersedes "convert where smaller", 2026-10-02):
21
+ * consistency over a few bytes, so no package keeps a hand-written production line beside its table.
22
+ */
23
+ /*
24
+ * The parameter names are deliberately unlike anything a caller holds: terser will not inline a function whose
25
+ * parameter shadows a name at the call site (measured 2026-10-02 — directives passes its own `code`, and a parameter
26
+ * called `code` left `((e,t,n)=>`…`)(0,t,n)` in its bundle, +8 B; renamed, the call folds to the bare template).
27
+ */
28
+ /**
29
+ * **A misused API, named by its function** — the thrown-error twin of `diagnostic()`: `untrack: expected a function …
30
+ * (untrack-not-function)`, function-first because a stack already names the source and the sweep reads that shape. The
31
+ * prose comes from a package's table, behind `true `, so a development-only guard costs production nothing.
32
+ */
33
+ const misuse = (forName, withCode, andProse) => true && andProse
34
+ ? `${forName}: ${andProse[0]}${andProse[1] ? ` ${andProse[1]}` : ''} (${withCode})`
35
+ : `${forName}: ${DOCS}${withCode}`;
36
+ const diagnostic = (inArea, bySubject, withCode, andProse) =>
37
+ /** `true ` HERE as well as at the call: production folds this to the one-line form, branch and all. */
38
+ true && andProse
39
+ ? `[vera] ${inArea}: ${bySubject} — ${andProse[0]}${andProse[1] ? ` ${andProse[1]}` : ''} (${withCode})`
40
+ : `[vera] ${inArea}: ${bySubject} — ${DOCS}${withCode}`;
41
+
42
+ /**
43
+ * core's `html`/`svg`/`mathml` and the renderer's `tag` — a tagged template called as a function. The FACT is shared;
44
+ * the EXAMPLE is each emitter's: `html` writes markup, `tag` an element name — so the emitter passes it.
45
+ */
46
+ const tagCalled = (tag, received, example) => [
47
+ `expected a template literal and received ${received}.`,
48
+ `It is a tagged template — write ${tag}\`${example}\`, not ${tag}('${example}').`,
49
+ ];
50
+ /** core's props adoption on an `init()` element, and the renderer's on any other element. */
51
+ const getterOnlyProp = (key) => [
52
+ `received a bound property \`.${key}\` (or \`!${key}\`), but its class declares \`${key}\` as a getter with no setter — the value cannot be delivered and the binding is ignored.`,
53
+ 'Add a setter, or stop binding it.',
54
+ ];
55
+ /** shared-utils' `adoptProperty` (renderer, spread): an element that never drains the record loses it at upgrade. */
56
+ const upgradeClobber = (name) => [
57
+ `the value bound to \`${name}\` was replaced while the element upgraded. A class field is the usual cause: at ES2022 \`${name}?: …\` emits \`${name};\`, which runs during upgrade and overwrites whatever was set beforehand.`,
58
+ `Write it \`declare ${name}?: …\` instead. A component that calls init() adopts bound properties automatically and never sees this; this element did not. Ignore this if the component replaced the value on purpose.`,
59
+ ];
60
+ /** shared-utils' `isSelection` (renderer, spread). */
61
+ const selectMultiple = (name) => [
62
+ `\`${name}\` controls only ONE selection here, and a selection the user adds is kept — it is not controlled.`,
63
+ 'Bind `?selected=${…}` on each <option> to control every selection.',
64
+ ];
65
+ /** shared-utils' `contentClash` (renderer, spread): a content-replacing property beside content of the element's own. */
66
+ const contentClash$1 = (tag, name, alone) => [
67
+ `<${tag}> binds \`.${name}\`, which replaces the element's content, and also has content of its own — markup or a child binding, which the write would strand.`,
68
+ `Bind one or the other: the property alone (\`${alone}\`), or the content alone.`,
69
+ ];
70
+ /** The renderer and spread (two bundles); @verajs/ssr refuses the same URLs silently today. */
71
+ const scriptUrl = (name) => [
72
+ `\`${name}\` was given a javascript: URL — refused, and the attribute removed.`,
73
+ 'A bound URL is data, and data must never become code.',
74
+ ];
75
+ /**
76
+ * The renderer and spread: `kind` is what the value was (dev-values' `attributeValueKind`); `property` is the
77
+ * emitter's own spelling of a property binding — a template's `.name=${value}`, a spread's `'.name': value`.
78
+ */
79
+ const attributeValue = (name, kind, property) => [
80
+ `the attribute \`${name}\` was given ${kind}. An attribute value is a string and nothing else.`,
81
+ `If the element is meant to RECEIVE this value, bind a property instead — \`${property}\` — which is how a custom element takes anything that is not text. If it is meant to be read as text, convert it where you know what it means: \`date.toISOString()\`, \`list.join(' ')\`. A Date in particular serializes with the SERVER's timezone on one side and the browser's on the other, so it will not survive hydration.`,
82
+ ];
83
+ /** The renderer and spread: `type` is the value's `typeof`. */
84
+ const notAListener = (name, type) => [
85
+ `@${name} was given ${type === 'object' ? 'an object with no handleEvent method' : `a ${type}`}, which cannot listen — the event will do nothing.`,
86
+ 'Pass a function, or an object with a handleEvent method. A missing handler is `undefined` or `false`, both of which are fine; this is neither.',
87
+ ];
88
+ /** The renderer and spread (two bundles; @verajs/ssr refuses the same): binding `__proto__`. */
89
+ const protoBinding = (written) => [
90
+ `binds \`${written}\`, which would replace the element's own prototype and destroy it — no property write does this, and no use of it is legitimate.`,
91
+ 'The binding is ignored.',
92
+ ];
93
+ /** The renderer and spread: a bound `srcdoc` ATTRIBUTE. `property` is the emitter's spelling of the property binding. */
94
+ const srcdocAttribute = (property) => [
95
+ 'binds the `srcdoc` attribute, which renders its value as an HTML document — refused.',
96
+ `If the markup is trusted and sanitized, bind the property: \`${property}\`.`,
97
+ ];
98
+ /** The renderer and spread: a bound inline-handler attribute (`onclick`). `event` is the emitter's event spelling(s). */
99
+ const handlerAttribute = (name, event) => [
100
+ `binds the \`${name}\` attribute, which runs its value as code — refused.`,
101
+ `Bind a function as an event instead: ${event}.`,
102
+ ];
103
+ /**
104
+ * The jsx compiler and the renderer's `tag` — children given to a void element. Both refuse; the FATE the refusal
105
+ * prevents is each emitter's: compiled, they would land after the element; through `tag`, vanish.
106
+ */
107
+ const voidChildren = (tag, fate) => [
108
+ `<${tag}> is a void element — it has no end tag and takes no children, so ${fate}; refused.`,
109
+ 'Move the children out, or use an element that takes content.',
110
+ ];
111
+ /** The jsx compiler and the renderer's `tag` — an object `style`. The EXAMPLE is each emitter's spelling. */
112
+ const styleObject = (example) => [
113
+ 'style expects a STRING, not an object.',
114
+ `Build the string: ${example}.`,
115
+ ];
116
+
117
+ /**
118
+ * **Delivering a bound property to a custom element that may not receive it yet** — the one home of the
119
+ * rule `@verajs/renderer` (a `.prop` template binding) and `@verajs/renderer/spread` (a `.prop` bag key)
120
+ * both apply. They ship as separate bundles that cannot import each other, so this package, inlined into
121
+ * each, is where the rule lives once; before, each carried a full copy and a fix had to visit both.
122
+ *
123
+ * Returns where the binding stands after this write:
124
+ * - `0` — still adopting: nothing received the value, so it was recorded in the element-carried
125
+ * `_$props$`, which core's `init()` drains over whatever the class's field initializers wrote at
126
+ * upgrade. Call again on the next write.
127
+ * - `1` — received (a setter anywhere on the chain, an initialized component's `_$adopt$`, or an element
128
+ * that is already upgraded): later writes are plain property writes.
129
+ * - `2` — refused: a getter with no setter, where the plain write would throw. Later writes do nothing.
130
+ *
131
+ * `_$props$` and `_$adopt$` are `$`-named because they cross bundle boundaries (renderer, spread, core)
132
+ * and must survive property mangling.
133
+ *
134
+ * **`_$adopt$` is a BRAND, not just a slot:** present means "core has initialized this component", which is what routes
135
+ * a delivery to the live accessor (`1`) instead of the `_$props$` record. Do not move it to a class's PROTOTYPE
136
+ * (2026-10-10): every instance would carry it BEFORE `init`, and a delivery to an upgraded-but-uninitialized element
137
+ * would be adopted into a store that does not exist yet. It is ONE shared function written onto each element at `init`,
138
+ * called with the element as `this` (`adopt.call(element, …)`) — 2026-10-11: the closure it replaced was free in
139
+ * optimized code (measured) but cost Chrome's interpreted first render one allocation per component.
140
+ */
141
+ /** Development only: getter-only names already reported, per element — a `!name` re-asserts on every render. */
142
+ let refused;
143
+ const adoptProperty = (element, name, value) => {
144
+ /**
145
+ * **`__proto__` is refused HERE, at the receiver** (2026-11-10): `element.__proto__ = v` replaces the element's
146
+ * prototype, and an own `__proto__` key reaches a bag through `JSON.parse`. This is the choke point every delivery
147
+ * passes; the renderer's template binding and spread's bag key refuse it first, with a development warning naming
148
+ * where it was written (their second addresses: renderer.ts `proto-binding`, spread.ts refusal 3).
149
+ */
150
+ if (name === '__proto__')
151
+ return 2;
152
+ const adopt = element._$adopt$;
153
+ /** The walk comes first: what it finds decides whether writing is even legal. */
154
+ for (let carrier = element; carrier !== null; carrier = Object.getPrototypeOf(carrier)) {
155
+ const desc = Object.getOwnPropertyDescriptor(carrier, name);
156
+ if (desc === undefined)
157
+ continue;
158
+ if (desc.set !== undefined) {
159
+ element[name] = value;
160
+ return 1;
161
+ }
162
+ if (desc.get !== undefined) {
163
+ if (adopt !== undefined)
164
+ adopt.call(element, name, value);
165
+ else if (true ) {
166
+ const names = (refused ??= new WeakMap()).get(element) ?? new Set();
167
+ refused.set(element, names);
168
+ if (!names.has(name)) {
169
+ names.add(name);
170
+ console.warn(diagnostic('renderer', `<${element.localName}>`, 'getter-only-prop', true && getterOnlyProp(name)));
171
+ }
172
+ }
173
+ return 2;
174
+ }
175
+ break; // a data property: an own field, or an inherited default — nothing receives it
176
+ }
177
+ element[name] = value;
178
+ if (adopt !== undefined) {
179
+ adopt.call(element, name, value);
180
+ return 1;
181
+ }
182
+ const record = (element._$props$ ??= {});
183
+ const first = true && !Object.hasOwn(record, name);
184
+ record[name] = value;
185
+ /** Upgrade is read off the PROTOTYPE — a bag key named `constructor` can shadow `el.constructor`. The realm is the element's. */
186
+ const view = element.ownerDocument.defaultView;
187
+ const upgraded = view === null || Object.getPrototypeOf(element) !== view.HTMLElement.prototype;
188
+ /** Development only: an element that never drains still loses the value at upgrade — told apart by ownership. */
189
+ if (true && view !== null && !upgraded && first) {
190
+ const tag = element.localName;
191
+ view.customElements.whenDefined(tag).then(() => {
192
+ let owned = false;
193
+ for (let carrier = element; carrier !== null; carrier = Object.getPrototypeOf(carrier)) {
194
+ const desc = Object.getOwnPropertyDescriptor(carrier, name);
195
+ if (desc === undefined)
196
+ continue;
197
+ owned = desc.get !== undefined || desc.set !== undefined;
198
+ break;
199
+ }
200
+ if (!owned && element[name] !== record[name])
201
+ console.warn(diagnostic('renderer', `<${tag}>`, 'upgrade-clobber', true && upgradeClobber(name)));
202
+ });
203
+ }
204
+ return upgraded ? 1 : 0;
205
+ };
206
+
207
+ /**
208
+ * A URL whose scheme a browser reads as `javascript:` — navigating to one runs it, so a BOUND value
209
+ * that parses this way is code arriving as data, never a link.
210
+ *
211
+ * Matched the way the URL Standard's parser reads a scheme, because that is the only reading that
212
+ * matters: leading C0 controls and spaces are stripped, ASCII tab, LF and CR are removed anywhere, and
213
+ * the scheme is case-insensitive. A check that only lowercases is bypassed by `" jAvA\tscript:"`,
214
+ * which every engine navigates to. React's blocking pattern is the same rule.
215
+ *
216
+ * `@verajs/ssr` keeps a twin (it cannot import this package), held to this one by
217
+ * `tests/url-sinks.test.mjs`, so a server never emits a link the client refuses.
218
+ */
219
+
220
+ const SCRIPT_URL = /^[\u0000- ]*j[\t\n\r]*a[\t\n\r]*v[\t\n\r]*a[\t\n\r]*s[\t\n\r]*c[\t\n\r]*r[\t\n\r]*i[\t\n\r]*p[\t\n\r]*t[\t\n\r]*:/i;
221
+ /**
222
+ * **Every bound name whose value is checked for a `javascript:` URL — and how.** One test answers both.
223
+ *
224
+ * Captured, checked from the start: the attributes (and their reflecting properties) whose value a browser
225
+ * NAVIGATES to or loads as a document — links and areas (`href`, SVG's `xlink:href`), forms (`action`,
226
+ * `formaction`), frames (`src`), and `<object data>`. `src` is matched on every element — refusing one on an `<img>`
227
+ * costs nothing, since an image never runs it. Resource-only attributes (`poster`, `srcset`) are fetched, never run,
228
+ * so they are not listed.
229
+ *
230
+ * Not captured, checked ITEM BY ITEM (`SCRIPT_URL_ITEM`): an SVG animation's values — `to`, `from`, `by`, `values`.
231
+ * `<animate attributeName="href" to="javascript:…">` (or `<set>`, or `values`) writes its value onto the link it
232
+ * animates, and clicking the link then RUNS it: measured 2026-09-30 in Chromium, Firefox and WebKit, through `href`
233
+ * and `xlink:href` alike. Refused on EVERY element and whatever `attributeName` says, because `attributeName` can
234
+ * itself be bound or spread, a server spread has no element to ask, and no legitimate value of any attribute by these
235
+ * names starts with `javascript:` (a component's `to`, a router link's, is a URL too). **Only these names are checked
236
+ * item by item**: an unanchored test scans the whole value for `;`, which on a bound `src` holding a data URI costs
237
+ * ~0.45 ms per MB per update in Chromium and Firefox (measured 2026-09-30), where the anchored `SCRIPT_URL` stops at
238
+ * the first character.
239
+ *
240
+ * Case-insensitive, because property spellings (`formAction`) and attribute spellings meet here. `@verajs/ssr` keeps
241
+ * a twin, held to this one by `tests/url-sinks.test.mjs`.
242
+ */
243
+ const URL_SINK = /^(?:(href|src|action|formaction|xlink:href|data)|to|from|by|values)$/i;
244
+ /**
245
+ * `SCRIPT_URL` at the start of the value OR of any `;`-separated item of it — an animation's `values` list
246
+ * (`"#a;javascript:…"`) applies every item in turn. Only for an animation's values (`URL_SINK`'s uncaptured names): a `;` inside an `href` is a path
247
+ * character, and `/p;javascript:x` is a working link, never a script. Written out rather than derived from
248
+ * `SCRIPT_URL`: the repeated text costs less gzipped than the code that would build it.
249
+ */
250
+
251
+ const SCRIPT_URL_ITEM = /(?:^|;)[\u0000- ]*j[\t\n\r]*a[\t\n\r]*v[\t\n\r]*a[\t\n\r]*s[\t\n\r]*c[\t\n\r]*r[\t\n\r]*i[\t\n\r]*p[\t\n\r]*t[\t\n\r]*:/i;
252
+ /**
253
+ * **An inline event-handler attribute** — `on` and a letter, any case (`onclick`, `onLoad`, `onbeforeinput`): its
254
+ * value is run as CODE, so a BOUND one is code arriving as data, refused by the template scanner, `spread` and the
255
+ * server alike (a static `onclick="save()"` is the author's own and untouched). Broad on purpose — it also refuses a
256
+ * bound `once=`/`online=` attribute; the precise rule would need the platform's list of handler names. `@verajs/ssr`
257
+ * keeps a twin, held to this one by `tests/inline-handlers.test.mjs`.
258
+ */
259
+ const INLINE_HANDLER = /^on./i;
260
+ /**
261
+ * **The properties that replace an element's whole content** — a binding to one owns the element's children, so it
262
+ * cannot share the element with content of its own (markup, or a child binding the write would strand: a later commit
263
+ * into it then throws on a missing parent). Development refuses the pair in the template scanner and in `spread` alike.
264
+ */
265
+ const CONTENT_PROPERTY = /^(?:textContent|innerHTML|innerText|outerHTML|outerText)$/;
266
+ /**
267
+ * Whether an element has content of its own that a content-replacing write would strand or lose: a child that is not
268
+ * whitespace-only text (formatting whitespace loses nothing), or — `$content`, set in development by the renderer — a
269
+ * child binding that owns the element whole and leaves no node behind until it commits. The element-specific `.text`
270
+ * setters (`<a>`, `<option>`, `<title>`, `<script>`) are deliberately not in the list: a custom element's own `text`
271
+ * prop is common, and would be refused for nothing.
272
+ */
273
+ const ownsContent = (element) => {
274
+ if (element.$content === true)
275
+ return true;
276
+ for (let node = element.firstChild; node !== null; node = node.nextSibling)
277
+ /**
278
+ * An EMPTY text node is a child binding's anchor, not formatting: formatting whitespace is never empty. And
279
+ * formatting is HTML's whitespace, `[ \t\n\f\r]` — not JS's `trim()`, which would let an `&nbsp;` be overwritten.
280
+ */
281
+ if (node.nodeType !== 3 || node.data === '' || /[^ \t\n\f\r]/.test(node.data))
282
+ return true;
283
+ return false;
284
+ };
285
+ /** `side` is the module the user wired — `renderer` for a template, `spread` for a spread. */
286
+ const contentClash = (side, tag, name) => {
287
+ throw new Error(misuse(side, 'content-clash', true && contentClash$1(tag, name, `<${tag} \${spread({ '.${name}': … })}></${tag}>` )));
288
+ };
289
+
290
+ /** `fn(a, b, c)`, tracked as the caller is — the stand-in for core's `untracked` when no core was wired. */
291
+ const call = (fn, a, b, c) => fn(a, b, c);
292
+ /**
293
+ * **Runs a bound handler, and its callers run it UNTRACKED**: the renderer's template `@event` and spread's event key,
294
+ * each through `untracked(dispatch, holder, event)` (2026-10-09). An effect that fires an event synchronously
295
+ * (`el.click()`, `focus()`, `dispatchEvent`) runs the handler INSIDE itself, and the handler's reads subscribed the
296
+ * effect: a handler doing `state.n++` made the effect re-run on every click, a self-feeding loop held to one round per
297
+ * frame, forever (measured). A handler's reads are event-time decisions, never a hook's inputs. The directives engine's
298
+ * delegated `listen` makes the same choice its own way. A function is called with the element as `this`; an object
299
+ * through its `handleEvent`. One function for both callers (Brian's size-audit ruling, 2026-11-13): it was two
300
+ * identical copies, so a fix had two addresses; each bundle still inlines its own.
301
+ */
302
+ const dispatch = (holder, event) => {
303
+ const handler = holder._handler;
304
+ if (typeof handler === 'function')
305
+ handler.call(holder._element, event);
306
+ else if (typeof handler?.handleEvent === 'function')
307
+ handler.handleEvent(event);
308
+ };
309
+ /**
310
+ * **Whether a property binding is a `<select>`'s SELECTION** — `value` or `selectedIndex` — which the renderer and
311
+ * `spread` both treat as live: re-asserted every render and compared against the live value (as `!value` is), because
312
+ * a select's options can be replaced under an unchanged value, which drops the selection. One rule, asked once per
313
+ * binding by both, so a template and a spread key cannot disagree about it.
314
+ *
315
+ * In development it names the one shape it cannot serve: on a `<select multiple>` both properties read and set a
316
+ * SINGLE selection, so a selection the user adds is kept rather than controlled. Always writing there was measured
317
+ * 2–3% slower on every table with a select per row, to serve an API that does not fit — hence a warning, not a cost.
318
+ */
319
+ const isSelection = (element, name) => {
320
+ if ((name !== 'value' && name !== 'selectedIndex') || element.localName !== 'select')
321
+ return false;
322
+ return true;
323
+ };
324
+ /**
325
+ * Development: the one shape a selection binding cannot serve, named by the module the user wired (`side`). Called only
326
+ * behind `true ` at each call site, so production keeps `isSelection` exactly as small as it was (a `side` argument on
327
+ * it measured +1 B, a default +9 B on vera-renderer.min.js — 2026-10-09).
328
+ */
329
+ const saySelectMultiple = (element, name, side) => {
330
+ if (element.hasAttribute('multiple'))
331
+ console.warn(diagnostic(side, '<select multiple>', 'select-multiple', true && selectMultiple(String(name))));
332
+ };
333
+ /**
334
+ * `target[key]`, as a function — how a component's GETTER is read through `untracked`. Not `Reflect.get`: `untracked`
335
+ * passes three arguments, and `Reflect.get`'s third is the RECEIVER — `undefined` there runs the getter with no `this`.
336
+ */
337
+ const read = (target, key) => target[key];
338
+
1
339
  /**
2
340
  * `true ` only: the one home for *"is this value something an attribute can carry?"*
3
341
  *
@@ -33,7 +371,7 @@ let reported;
33
371
  * Returns the complaint, or `null` when the value is fine. Never throws — the shapes that break a
34
372
  * naive guard are exactly the ones worth reporting, so they reach the `object` arm and are named.
35
373
  */
36
- const attributeValueComplaint = (tag, name, value) => {
374
+ const attributeValueKind = (tag, name, value) => {
37
375
  const type = typeof value;
38
376
  if (type === 'string' || type === 'number' || type === 'boolean' || type === 'bigint')
39
377
  return null;
@@ -55,7 +393,7 @@ const attributeValueComplaint = (tag, name, value) => {
55
393
  * `<my-chart formatter={fn}>` is a coherent intention that this sink simply cannot express. The
56
394
  * message names the binding that can, rather than blaming the author.
57
395
  */
58
- const said = type === 'function'
396
+ const kind = type === 'function'
59
397
  ? `a function, which becomes its own SOURCE TEXT`
60
398
  : type === 'symbol'
61
399
  ? `a symbol, which every DOM conversion refuses`
@@ -64,39 +402,44 @@ const attributeValueComplaint = (tag, name, value) => {
64
402
  : brand(value) === '[object Date]'
65
403
  ? `a Date, whose text carries the TIMEZONE of whichever side rendered it`
66
404
  : `an ${type}, which cannot survive as text`;
67
- /**
68
- * Returned WITHOUT the `[vera]` prefix, which each call site writes as a literal.
69
- * `tests/diagnostics-convention.test.mjs` reads the prefix off the call, so a message handed over
70
- * as a variable is invisible to it — and its answer to that is an allowance list. Taking the
71
- * allowance would have excused these two calls rather than checked them, which is the
72
- * reclassification this audit keeps refusing; the literal at the call site is what every other
73
- * diagnostic in the repo does anyway.
74
- */
75
- return (`renderer: the attribute \`${name}\` on <${tag}> was given ${said}. ` +
76
- `An attribute value is a string and nothing else.\n` +
77
- `If the element is meant to RECEIVE this value, bind a property instead — \`.${name}=\${value}\` ` +
78
- `— which is how a custom element takes anything that is not text. If it is meant to be read as ` +
79
- `text, convert it where you know what it means: \`date.toISOString()\`, \`list.join(' ')\`. ` +
80
- `A Date in particular serializes with the SERVER's timezone on one side and the browser's on ` +
81
- `the other, so it will not survive hydration.`);
405
+ /** The KIND only: the sentence is the shared `attribute-value` entry, printed by each call site with its area. */
406
+ return kind;
407
+ };
408
+
409
+ const PROSE$1 = {
410
+ 'spread-unsafe-name': (key) => [
411
+ `refusing ${key} — an attribute name cannot contain whitespace, a quote, \`<\`, \`>\`, \`/\`, \`=\` or a control character, and one that cannot be written into markup would not survive server rendering.`,
412
+ 'Spread names arrive at runtime; check where this key came from.',
413
+ ],
414
+ 'spread-inner-html': (key) => [
415
+ `refusing ${key} — spread names arrive at runtime, which is exactly the property that makes an HTML sink unreviewable.`,
416
+ 'Write it in the template — html`<div .innerHTML=${trusted}>` — sanitized first (renderer README, security note).',
417
+ ],
418
+ 'spread-not-object': (received) => [
419
+ `ignoring a props bag that is not a plain object — received ${received}. A string is iterated by character index, so \`spread('text')\` would set attributes named 0, 1, 2 and 3; anything else applies nothing at all.`,
420
+ 'This is usually an import or a property that resolved to something unexpected.',
421
+ ],
82
422
  };
83
423
 
84
424
  /**
85
- * `<div ${spread(props)}>` — bindings whose names are not known when the template is parsed.
425
+ * `<div ${spread(props)}>` — bindings whose NAMES are not known when the template is parsed.
86
426
  *
87
- * Template renderers bake attribute names in at parse time; that is what makes them small and fast,
88
- * and it is why neither this renderer nor lit-html has had spread. Lit's spread PR has sat open as a
89
- * draft since 2021, blocked on the questions answered below.
427
+ * Ships separately: the renderer holds one property read (a value at element position carrying
428
+ * `_$apply$` applies itself), so an app that never spreads pays only that. This entry imports nothing
429
+ * from the renderer and reaches it only through that protocol, so it works beside any renderer entry.
90
430
  *
91
- * **Why this ships separately.** The renderer holds one property read — a value at element position
92
- * carrying `_$apply$` applies itself — and nothing else, so a base bundle grows 16 B rather than
93
- * 176 B and an app that never spreads pays only that. Core and the renderer are the two packages
94
- * where weight is absolute; this is not one of them, but it is still measured.
431
+ * **One key, one rule, decided once.** A key's kind and name follow the renderer's template sigils
432
+ * exactly (`.prop`, `?bool`, `@event`, `&ref`, `!live`, `onClick`), and its verdict — including every
433
+ * refusal — is decided when its binding is first created, never again per render. The rules are
434
+ * repeated rather than imported from the renderer (the bundles cannot share state);
435
+ * `tests/spread-written-parity.test.mjs` drives both spellings against each other.
95
436
  *
96
- * The sigil rules are repeated here rather than shared through `@verajs/shared-utils`. That was
97
- * tried: a shared resolver has to hand back both a kind and a name, and the tuple it allocates cost
98
- * the renderer 10 B. Principle #5 permits deliberate duplication where two callers can legitimately
99
- * diverge; #7 decides it, because the renderer is where bytes are not negotiable.
437
+ * **Security: spread is where the template security model would break**, because its names arrive at
438
+ * runtime, often from data, and are neither greppable nor reviewable. So it refuses, on the client and
439
+ * in the server half (`_$attrs$`) alike: `.innerHTML`/`.outerHTML` (and `!`), `.__proto__`, the `srcdoc`
440
+ * attribute, inline-handler attributes (`onclick` in any casing — `on` + Capital is the event spelling
441
+ * and still works), names that cannot survive markup, and — as the renderer does — a `javascript:` URL
442
+ * where a browser navigates.
100
443
  */
101
444
  const ATTR = 0;
102
445
  const PROPERTY = 1;
@@ -105,496 +448,299 @@ const BOOLEAN = 2;
105
448
  const LIVE = 3;
106
449
  const EVENT = 4;
107
450
  const REF = 5;
108
- /** A binding gone inert — a get-only property refusal; `write` matches it against nothing. */
109
- const REFUSED = -1;
451
+ const REFUSED = 6;
110
452
  /**
111
- * A key that cannot be written into a tag, and therefore cannot be used at all.
112
- *
113
- * Measured in Chromium, `setAttribute` accepts `"`, `'` and `<` and rejects whitespace, `>`, `=`,
114
- * `/` and NUL — but a name carrying a quote or a `<` cannot survive **markup**, so `@verajs/ssr`
115
- * has to refuse it, and a key that works here and vanishes server-side is worse than one that works
116
- * nowhere. The rule is therefore the HTML attribute-name restriction (control characters,
117
- * whitespace, `"`, `'`, `>`, `/`, `=`) plus `<` and a backtick, applied identically on both sides.
118
- *
119
- * Skipped rather than thrown. `setAttribute` throws `InvalidCharacterError` on some of these, which
120
- * took down the whole render — for one bad key in a props bag, on a binding whose entire purpose is
121
- * names that are not known until runtime.
122
- *
123
- * The control-character range is the point of the rule, not a mistake in it: a name carrying one
124
- * is exactly what must never reach markup.
453
+ * A name that cannot be written into a tag: the HTML attribute-name restriction (control characters,
454
+ * whitespace, `"`, `'`, `>`, `/`, `=`) plus `<` and a backtick — refused identically on both sides, so a
455
+ * key cannot work here and vanish server-side. Skipped, never thrown: one bad key must not cost a render.
125
456
  */
126
457
 
127
458
  const UNSAFE_NAME = /^$|[\s"'>/=<`]|[\u0000-\u001f\u007f]/;
459
+ /** Development only: why a key was refused, by refusal code. */
128
460
  /**
129
- * **Sinks spread refuses, because spread is the one place the template security model breaks.**
130
- *
131
- * The renderer's posture on `.innerHTML` (README, "security") rests on three properties of the
132
- * template spelling: greppable, obviously yours, reviewable as the decision it is. A spread key
133
- * arrives at RUNTIME inside a props object — often built from data — and has none of the three:
134
- * `spread(fromJson)` carrying `.innerHTML` or an inline `onclick` attribute is markup or code
135
- * injection through a door no grep can see. So spread refuses the sinks and points at the template
136
- * spelling, which remains fully available to an author who means it.
137
- *
138
- * The list, deliberately minimal and named: `innerHTML`/`outerHTML` as property or live-property
139
- * keys; `srcdoc` as an attribute (an iframe's inline document); and any attribute whose name the
140
- * browser would treat as an inline handler (`on…` in any casing) — EXCEPT the documented event
141
- * spelling `on` + Capital, which the constructor converts to a real listener and which therefore
142
- * never becomes an attribute. The exemption mirrors the constructor's test byte for byte, because
143
- * `ONCLICK` must not slip through as "looks like the event spelling": the constructor only
144
- * converts a lowercase `on`, so only that exact shape is exempt.
145
- *
146
- * Returns the hint for the diagnostic, or null for a permitted key.
461
+ * A key's kind and name, and — for a refused key — why (`[REFUSED, code]`). The twin of the renderer's
462
+ * template construction; a refused key's verdict never changes, so it is decided once per binding.
147
463
  */
148
- const refusedSink = (key) => {
464
+ const resolve = (key) => {
149
465
  const first = key[0];
150
- if (first === '.' || first === '!') {
151
- const name = key.slice(1);
152
- if (name === 'innerHTML' || name === 'outerHTML')
153
- return 'write it in the template — html`<div .innerHTML=${trusted}>` — sanitized first (renderer README, security note)';
154
- /**
155
- * `element.__proto__ = value` is not a property write — it hits Object.prototype's
156
- * `__proto__` ACCESSOR and replaces the element's prototype, stripping every DOM method it
157
- * has. The element is bricked, and the crash lands LATER, in whatever binding next calls
158
- * `removeAttribute` on it — a data-driven render-kill with a stack that names the renderer
159
- * and not the data. Found by the run-14 payload probe; there is no legitimate use, so unlike
160
- * `.innerHTML` there is no template spelling to point at.
161
- */
162
- /** The deliberate twin of the same refusal in `AttrPart`'s constructor (`./renderer.ts`), for
163
- * the template spellings `.name` / `!name`. Independent bundles, neither imports the other, so
164
- * the rule is copied — and a fix visits both. `tests/dangerous-binding-matrix.test.mjs` holds
165
- * the two spellings to the same answer. */
166
- if (name === '__proto__')
167
- return "assigning __proto__ replaces the element's own prototype and destroys it — no property write does this, and no use of it is legitimate";
168
- return null;
466
+ let kind = first === '.' ? PROPERTY : first === '?' ? BOOLEAN : first === '@' ? EVENT : first === '&' ? REF : first === '!' ? LIVE : ATTR;
467
+ let name = kind === ATTR ? key : key.slice(1);
468
+ if (kind === ATTR && /^on[A-Z]/.test(key)) {
469
+ kind = EVENT;
470
+ name = key.slice(2).toLowerCase();
169
471
  }
170
- if (first === '?' || first === '@' || first === '&')
171
- return null;
172
- /** The event spelling the constructor converts: `on` + Capital, lowercase `on` only. */
173
- if (first === 'o' && key.charCodeAt(1) === 110 && key.charCodeAt(2) > 64 && key.charCodeAt(2) < 91)
174
- return null;
175
- const lower = key.toLowerCase();
176
- if (lower === 'srcdoc')
177
- return 'an inline iframe document is markup injection by definition — bind it in the template if you truly mean it';
178
- if (lower.length > 2 && lower.startsWith('on'))
179
- return 'an inline handler attribute is code from data — pass a function as `on` + Capital (onClick) or `@click` instead';
180
- return null;
181
- };
182
- /** Module-local: one identity comparison, not a global symbol-registry lookup per binding. */
183
- const UNSET = Symbol();
184
- /**
185
- * The deliberate twin of `commitAdopt` in `./renderer.ts` — independent bundles, neither imports
186
- * the other, so the rule is copied IN FULL and a fix visits both. Full reasoning there; the short
187
- * form: after the write, an accessor anywhere on the chain means something receives this property
188
- * and the binding can latch onto the plain write for good. Unreceived, the value is recorded under
189
- * the element-carried `_$props$` — the cross-bundle channel core's `init()` drains — and the latch
190
- * closes once the element is upgraded (its record is final) or has no realm. The development
191
- * clobber detector rides along, because a bag key and a written binding are the same mistake with
192
- * the same author watching.
193
- *
194
- * Returns the binding's NEXT kind, exactly as the twin does: `PROPERTY` to latch onto the plain
195
- * write, `REFUSED` to go inert (a get-only surface), `0` to keep adopting.
196
- */
197
- const adopt = (element, name, value) => {
198
- const el = element;
199
- /** The walk comes BEFORE the write — see the twin: a setter receives (its throw is the
200
- * component's own error), a getter with no setter refuses instead of throwing a raw TypeError
201
- * out of the render, and the dev warning defers to `_$adopt$`'s own refusal where it exists. */
202
- let carrier = el;
203
- while (carrier !== null) {
204
- const desc = Object.getOwnPropertyDescriptor(carrier, name);
205
- if (desc !== undefined) {
206
- if (desc.set !== undefined) {
207
- el[name] = value;
208
- return PROPERTY;
209
- }
210
- if (desc.get !== undefined) {
211
- if (el._$adopt$ !== undefined)
212
- el._$adopt$(name, value);
213
- else if (true )
214
- console.warn(`[vera] renderer: <${element.localName}> declares \`${name}\` as a getter with no ` +
215
- `setter — the value bound by \`.${name}\` cannot be delivered and the binding is ` +
216
- `ignored. Add a setter, or stop binding it.`);
217
- return REFUSED;
218
- }
219
- break; // a data property — an own field, or an inherited default: nothing receives it
220
- }
221
- carrier = Object.getPrototypeOf(carrier);
222
- }
223
- el[name] = value;
224
- /** An initialized component receives live through `_$adopt$` — a record after the drain would
225
- * never be read again. The door a spread bag's conditional key arrives through, reactive. */
226
- if (el._$adopt$ !== undefined) {
227
- el._$adopt$(name, value);
228
- return PROPERTY;
229
- }
230
- const record = (el._$props$ ??= {});
231
- const firstRecording = !Object.hasOwn(record, name);
232
- record[name] = value;
233
- /** Prototype, never `el.constructor` — a bag key named `constructor` shadows the real one with
234
- * an own property, and no property write can move a prototype (`__proto__` is refused above). */
235
- const win = element.ownerDocument.defaultView;
236
- const upgraded = win === null || Object.getPrototypeOf(el) !== win.HTMLElement.prototype;
237
- if (true && win !== null && !upgraded && firstRecording) {
238
- const tag = element.localName;
239
- win.customElements.whenDefined(tag).then(() => {
240
- /** Ownership is asked of the whole CHAIN — see the twin: a drain accessor, a handed-to
241
- * prototype pair, or a refused get-only surface all mean nothing is left to report. */
242
- let owner = el;
243
- let owned = false;
244
- while (owner !== null) {
245
- const desc = Object.getOwnPropertyDescriptor(owner, name);
246
- if (desc !== undefined) {
247
- owned = desc.get !== undefined || desc.set !== undefined;
248
- break;
249
- }
250
- owner = Object.getPrototypeOf(owner);
251
- }
252
- if (!owned && el[name] !== record[name])
253
- console.warn(`[vera] renderer: the value bound by \`.${name}\` on <${tag}> was replaced while the ` +
254
- `element upgraded. A class field is the usual cause: at ES2022 \`${name}?: …\` emits ` +
255
- `\`${name};\`, which runs during upgrade and overwrites whatever was set beforehand — ` +
256
- `write it \`declare ${name}?: …\` instead, which emits nothing. A component that ` +
257
- `calls init() adopts bound properties automatically and never sees this; this ` +
258
- `element did not. Ignore this if the component replaced the value on purpose.`);
259
- });
260
- }
261
- return upgraded ? PROPERTY : 0;
472
+ const property = kind === PROPERTY || kind === LIVE;
473
+ const refusal = UNSAFE_NAME.test(name)
474
+ ? 1
475
+ : property && (name === 'innerHTML' || name === 'outerHTML')
476
+ ? 2
477
+ : property && name === '__proto__'
478
+ ? 3
479
+ : kind === ATTR && name.toLowerCase() === 'srcdoc'
480
+ ? 4
481
+ : kind === ATTR && INLINE_HANDLER.test(name)
482
+ ? 5
483
+ : 0;
484
+ return refusal ? [REFUSED, refusal] : [kind, name];
262
485
  };
263
486
  /**
264
- * A class, not an object literal, so `handleEvent` exists once on the prototype. As a literal it was
265
- * a fresh closure per bound key — allocation proportional to the size of every props bag.
487
+ * How a key names a URL a browser navigates to — the renderer's rule, by the same numbers: 0 not one; 1 a custom
488
+ * element's property — often an object (`.data=${rows}`), so only a string is checked and nothing is converted; 2
489
+ * converted ONCE, and that string checked and written (so a `toString` that answers differently each time cannot pass
490
+ * the check as one URL and be written as another); 3 an animation's value (`to`, `values`…), converted once and
491
+ * checked item by item. A refused key needs no case: its name is a refusal code, which no URL
492
+ * attribute name matches.
266
493
  */
494
+ const urlRule = (kind, name, custom) => {
495
+ const sink = URL_SINK.exec(name);
496
+ return kind === BOOLEAN || kind === EVENT || kind === REF || sink === null ? 0 : kind !== ATTR && custom ? 1 : sink[1] ? 2 : 3;
497
+ };
498
+ /** What `checked` answers for a `javascript:` URL where the rule looks. */
499
+ const REFUSE = {};
500
+ /** `value` as it is checked AND written under `rule` — converted once, or left as it is — or `REFUSE`. */
501
+ const checked = (rule, value) => {
502
+ if (rule > 1 && value != null && typeof value !== 'string')
503
+ value = `${value}`;
504
+ return rule !== 0 && typeof value === 'string' && (rule === 3 ? SCRIPT_URL_ITEM : SCRIPT_URL).test(value) ? REFUSE : value;
505
+ };
506
+ const UNSET = {};
507
+ /** One key's binding on one element. It is also the `@event` listener — a stable object, so the platform dedupes re-adds. */
267
508
  class Binding {
268
509
  _kind;
269
510
  _name;
270
511
  _element;
271
- /** What the element held before this binding took over. Releasing puts it back. */
272
- _initial;
512
+ /** What the element held before the bag first wrote this key — restored when the key leaves the bag. */
513
+ _initial = null;
273
514
  _committed = UNSET;
274
515
  _handler = null;
275
- /** Twin of AttrPart's `PROP_ADOPT`: a property binding on a dashed tag goes through `adopt`
276
- * until something receives the property, then latches onto the plain write. Bindings persist
277
- * per element in `owned`, so the latch is safe here too. */
278
- _recording = false;
279
- constructor(element, key) {
280
- const first = key[0];
281
- let kind = first === '.'
282
- ? PROPERTY
283
- : first === '?'
284
- ? BOOLEAN
285
- : first === '@'
286
- ? EVENT
287
- : first === '&'
288
- ? REF
289
- : first === '!'
290
- ? LIVE
291
- : ATTR;
292
- let name = kind ? key.slice(1) : key;
293
- /** `on` + a capital: `onClick` ≡ `@click`. All-lowercase `onclick` never reaches here — it is
294
- * an inline-handler attribute, which `refusedSink` rejects before a binding exists. */
295
- if (kind === ATTR && first === 'o' && key.charCodeAt(1) === 110 && key.charCodeAt(2) > 64 && key.charCodeAt(2) < 91) {
296
- kind = EVENT;
297
- name = key.slice(2).toLowerCase();
298
- }
516
+ /** For `.prop`: where adoption stands (`adoptProperty`: 0 still adopting, 1 received, 2 refused). */
517
+ _state = 1;
518
+ /** How this key is checked as a URL (`urlRule`) — decided once, with the element in hand. */
519
+ _url;
520
+ /**
521
+ * On a custom element, a property read is the component's GETTER, so it goes through the `untracked` this binding was
522
+ * created with; `null` on a built-in element, whose getters read no state. Decided once.
523
+ */
524
+ _read;
525
+ constructor(element, key, untracked) {
526
+ const [resolved, name] = resolve(key);
527
+ /** A `<select>`'s selection is live, as in a template — the same rule, asked of the same function. */
528
+ const kind = (resolved === PROPERTY || resolved === LIVE) && isSelection(element, name) ? LIVE : resolved;
529
+ if (true && (resolved === PROPERTY || resolved === LIVE) && isSelection(element, name))
530
+ saySelectMultiple(element, name, 'spread');
299
531
  this._kind = kind;
300
532
  this._name = name;
301
533
  this._element = element;
302
- this._recording = kind === PROPERTY && element.localName.includes('-');
303
- this._initial =
304
- kind === ATTR
305
- ? element.getAttribute(name)
306
- : kind === BOOLEAN
307
- ? element.hasAttribute(name)
308
- : kind === PROPERTY || kind === LIVE
309
- ? element[name]
310
- : null;
534
+ const custom = element.localName.includes('-');
535
+ /** Core's `untracked` for a custom element's getter reads, and for an event key's handler (`dispatch`). */
536
+ this._read = custom || kind === EVENT ? untracked : null;
537
+ this._url = urlRule(kind, name, custom);
538
+ /** A content-replacing property beside content of the element's own: development refuses it, as a template does. */
539
+ if (true && (kind === PROPERTY || kind === LIVE) && CONTENT_PROPERTY.test(name) && ownsContent(element))
540
+ contentClash('spread', element.localName, name);
541
+ if (kind === REFUSED) {
542
+ if (true ) {
543
+ /** Each refusal written out, so the manifest (`diagnostics-tables`) reads every raise from the source. */
544
+ const at = `<${element.localName}>`;
545
+ const written = JSON.stringify(key);
546
+ const why = name;
547
+ if (why === 1)
548
+ console.warn(diagnostic('spread', at, 'spread-unsafe-name', true && PROSE$1['spread-unsafe-name'](written)));
549
+ else if (why === 2)
550
+ console.warn(diagnostic('spread', at, 'spread-inner-html', true && PROSE$1['spread-inner-html'](written)));
551
+ else if (why === 3)
552
+ console.warn(diagnostic('spread', at, 'proto-binding', true && protoBinding(written)));
553
+ else if (why === 4)
554
+ console.warn(diagnostic('spread', at, 'srcdoc-attribute', true && srcdocAttribute("'.srcdoc': trusted")));
555
+ else
556
+ console.warn(diagnostic('spread', at, 'handler-attribute', true && handlerAttribute(key, `\`'@${key.slice(2).toLowerCase()}': fn\` (or \`on${key.slice(2, 3).toUpperCase()}${key.slice(3)}\`)`)));
557
+ }
558
+ return;
559
+ }
560
+ if (kind === ATTR)
561
+ this._initial = element.getAttribute(name);
562
+ else if (kind === BOOLEAN)
563
+ this._initial = element.hasAttribute(name);
564
+ /** On a custom element this is the component's getter, run on the parent's behalf: read through `untracked`. */
565
+ else if (kind === PROPERTY || kind === LIVE)
566
+ this._initial = custom ? untracked(read, element, name) : element[name];
567
+ if (kind === PROPERTY && custom)
568
+ this._state = 0;
311
569
  }
312
- /**
313
- * **Two shapes, because `addEventListener` takes two** — the same rule `AttrPart.handleEvent`
314
- * applies, and it did not travel here when that one was fixed. A function is called with the
315
- * element as `this`; an object with a `handleEvent` method is invoked through it — the platform's
316
- * own `EventListenerObject` protocol, which every engine accepts. This called `.call()`
317
- * unconditionally, so `spread({ onClick: { handleEvent } })` bound without complaint, never
318
- * fired, and raised `this._handler.call is not a function` on **every** dispatch — while the
319
- * identical value through a written `@click` worked.
320
- *
321
- * Anything else is inert rather than throwing, exactly as there: development names it at the
322
- * binding (see the event branch in `write`), where the mistake still is.
323
- */
570
+ /** Runs the handler UNTRACKED (shared-utils' `dispatch`): `_read` holds core's `untracked` for an event key too. */
324
571
  handleEvent(event) {
325
- const handler = this._handler;
326
- if (typeof handler === 'function')
327
- handler.call(this._element, event);
328
- else if (typeof handler?.handleEvent === 'function')
329
- handler.handleEvent(event);
572
+ (this._read ?? call)(dispatch, this, event);
330
573
  }
331
574
  }
332
- /**
333
- * Keyed by the **part**, not the element.
334
- *
335
- * Keyed by element, `<div ${spread(a)} ${spread(b)}>` shares one map: whichever applies second sees
336
- * the other's keys as absent from its own props and releases them. Measured — the first spread's
337
- * attributes silently vanished. The part is one per element-position slot, which is exactly the
338
- * ownership boundary, and the renderer reuses it across renders.
339
- */
340
- const owned = new WeakMap();
341
- const write = (binding, value) => {
342
- /** One comparison per key per render — the same dirty check a written binding gets. */
575
+ const write = (binding, given, adopting) => {
576
+ const kind = binding._kind;
577
+ const value = checked(binding._url, given);
578
+ const name = binding._name;
579
+ /** One variable, typed for both uses: a cast alias survives minification as a second variable. */
580
+ const element = binding._element;
581
+ if (kind === REFUSED)
582
+ return;
343
583
  /**
344
- * A live property asks the element rather than its own memory — see `AttrPart` in the renderer.
345
- * The dirty check is what keeps a field someone typed into, and it is exactly wrong for a control
346
- * whose DOM state changes when a *sibling* is interacted with, a radio group being the case.
584
+ * **Adopting server markup** (hydration hands this in): a built-in control's state — `value`, `checked`, `selected`,
585
+ * `open`, by `.name` or `!name` — is RECORDED, not written: the server's default, and anything the user changed before
586
+ * the script arrived, stand, exactly as for a written binding (hydration's `FORM_STATE`, the same list — keep them
587
+ * equal). Any other name is written, and a component's property is always delivered.
347
588
  */
348
- if (binding._kind === LIVE) {
589
+ if (adopting && binding._read === null && (kind === LIVE || kind === PROPERTY) && /^(?:value|checked|selected|open)$/.test(name)) {
349
590
  binding._committed = value;
350
- const live = binding._element;
351
- if (live[binding._name] !== value)
352
- live[binding._name] = value;
591
+ return;
592
+ }
593
+ if (value === REFUSE) {
594
+ if (true && given !== binding._committed)
595
+ console.warn(diagnostic('spread', `<${element.localName}>`, 'script-url', true && scriptUrl(name)));
596
+ binding._committed = given;
597
+ element.removeAttribute(name);
598
+ return;
599
+ }
600
+ if (kind === LIVE) {
601
+ binding._committed = value;
602
+ /**
603
+ * A built-in is compared against its live property. A COMPONENT is compared against its current value — the raw one
604
+ * its store holds (`_$raw$`) for a name it received, else read through `untracked` — and receives a difference
605
+ * through `adoptProperty`. Inline, as the renderer's `commit` reads a template's `!name`: keep the two equal.
606
+ */
607
+ if (binding._read === null) {
608
+ if (element[name] !== value)
609
+ element[name] = value;
610
+ }
611
+ else {
612
+ const raw = element._$raw$;
613
+ if ((raw !== undefined && name in raw ? raw[name] : binding._read(read, element, name)) !== value)
614
+ adoptProperty(element, name, value);
615
+ }
353
616
  return;
354
617
  }
355
618
  if (value === binding._committed)
356
619
  return;
357
620
  binding._committed = value;
358
- const element = binding._element;
359
- const name = binding._name;
360
- const kind = binding._kind;
361
621
  if (kind === ATTR) {
362
622
  if (value == null)
363
623
  element.removeAttribute(name);
364
624
  else {
365
625
  if (true ) {
366
- const complaint = attributeValueComplaint(element.localName, name, value);
367
- if (complaint !== null)
368
- console.warn(`[vera] ${complaint}`);
626
+ const kind = attributeValueKind(element.localName, name, value);
627
+ if (kind !== null)
628
+ console.warn(diagnostic('spread', `<${element.localName}>`, 'attribute-value', true && attributeValue(name, kind, `'.${name}': value`)));
369
629
  }
370
- /**
371
- * `` `${value}` ``, never `String(value)` — the two differ on exactly one thing and it is the
372
- * one that matters here. `String(sym)` returns `"Symbol(s)"` while every DOM conversion and
373
- * `@verajs/ssr`'s own escaper throw, so this sink was the ONLY one of three that accepted a
374
- * symbol, writing to the client an attribute the server refuses to produce. The rule was
375
- * already recorded in `@verajs/ssr`'s `escapeHtml` — "serving Symbol(s) into markup the client
376
- * cannot reproduce does not make anything work, it moves the failure across the boundary and
377
- * strips the context" — and this file used the other form anyway. A house rule written down
378
- * in one of three homes is a house rule in none of them.
379
- */
380
630
  element.setAttribute(name, `${value}`);
381
631
  }
382
632
  }
383
633
  else if (kind === PROPERTY) {
384
- if (binding._recording) {
385
- const next = adopt(element, name, value);
386
- if (next !== 0) {
387
- binding._recording = false;
388
- if (next === REFUSED)
389
- binding._kind = REFUSED; // inert: `write` matches it against nothing
390
- }
391
- }
392
- else
634
+ if (binding._state === 1)
393
635
  element[name] = value;
636
+ else if (binding._state === 0)
637
+ binding._state = adoptProperty(element, name, value);
394
638
  }
395
- else if (kind === BOOLEAN) {
639
+ else if (kind === BOOLEAN)
396
640
  element.toggleAttribute(name, !!value);
397
- }
398
641
  else if (kind === REF) {
399
- /**
400
- * `&name` is the written form's ref sigil (`<input &field=${myRef} />`), and it was the one
401
- * binding kind a spread could not express: the key fell through to `ATTR` and
402
- * `setAttribute('&field', …)` threw on the client while the server wrote `&field="[object
403
- * Object]"` into the markup. A function is called with the element, an object gets it assigned
404
- * to `.value` — the same two shapes `AttrPart` handles.
405
- */
406
642
  if (typeof value === 'function')
407
643
  value(element);
408
644
  else if (value !== null && typeof value === 'object')
409
645
  value.value = element;
410
646
  }
411
647
  else {
412
- /**
413
- * A listener is validated when a *user* clicks, which in development may be never — so it is
414
- * checked where it is written, the same rule `AttrPart` applies to `@event`. `false` stays
415
- * silent: `{ onClick: enabled && onClick }` is the ordinary conditional form and already
416
- * behaves correctly, since `handleEvent` finds nothing callable and does nothing.
417
- */
418
648
  if (true && value != null && value !== false && typeof value !== 'function' &&
419
649
  typeof value?.handleEvent !== 'function')
420
- console.warn(`[vera] spread: @${name} on <${element.localName}> was given ` +
421
- `${typeof value === 'object' ? 'an object with no handleEvent method' : `a ${typeof value}`}, ` +
422
- `which cannot listen — the event will do nothing.\n` +
423
- `Pass a function, or an object with a handleEvent method. A missing handler is ` +
424
- `\`undefined\` or \`false\`, both of which are fine; this is neither.`);
650
+ console.warn(diagnostic('spread', `<${element.localName}>`, 'not-a-listener', true && notAListener(name, typeof value)));
425
651
  if (binding._handler === null && value != null)
426
652
  element.addEventListener(name, binding);
427
653
  binding._handler = value ?? null;
428
654
  }
429
655
  };
430
656
  /**
431
- * A key that disappeared between renders restores what the element held before the binding existed.
432
- *
433
- * This is the question Lit's PR is stuck on, and the trap is asking it as "what value means absent".
434
- * For a property there is no answer: assigning `undefined` runs through coercing setters, so
435
- * dropping `.value` yields `""` rather than reverting, and `delete` cannot remove a prototype
436
- * accessor. Asked instead as *"undo what this binding did"* it is well defined for every kind and
437
- * never invents a value the author did not write — the initial state was, by definition, acceptable
438
- * before the binding arrived.
439
- *
440
- * And asked that way it needs no code of its own: releasing is writing the initial value back.
441
- * `null` removes an attribute, `false` untoggles a boolean, `undefined` restores a property to
442
- * pristine, and an event handler falls to `null` — every case the existing commit already handles.
443
- * The separate per-kind teardown this replaced was fourteen lines saying the same thing twice.
444
- *
445
- * Deliberately unguarded by an ownership check (`is the value still the one we wrote?`). That only
446
- * matters when a component reassigns a property its parent is binding, which is already confused;
447
- * per principle #3 the machinery waits for evidence rather than being pre-built.
657
+ * Each binding is owned by the renderer's binding record it arrived through (the `key`), so one element can
658
+ * carry several spreads. A key that leaves the bag is written back to what the element held before.
448
659
  */
449
- function apply(element, part) {
660
+ const owned = new WeakMap();
661
+ /**
662
+ * `untracked` is `_$apply$`'s third argument — core's, through the renderer; `call` when a renderer leaves it out.
663
+ * Each binding keeps the one it was CREATED with, so nothing about it is paid per render, and an apply nested inside
664
+ * another (a component setter rendering a spread) can never change what the outer's bindings use.
665
+ */
666
+ function apply(element, key, untracked = call, adopting = false) {
450
667
  const props = this._props;
451
- let bindings = owned.get(part);
668
+ let bindings = owned.get(key);
452
669
  if (bindings === undefined)
453
- owned.set(part, (bindings = new Map()));
454
- /**
455
- * Counted here rather than with `Object.keys(props).length`, which allocates an array on every
456
- * render of every spread — garbage in the render path, for a number already being walked.
457
- */
670
+ owned.set(key, (bindings = new Map()));
458
671
  let count = 0;
459
- for (const key in props) {
672
+ for (const name in props) {
460
673
  count++;
461
- /**
462
- * Counted before it is skipped, so the size comparison below still describes the key set — a
463
- * refused key that changed the count would make every render look like a removal.
464
- */
465
- if (UNSAFE_NAME.test(key[0] === '.' || key[0] === '?' || key[0] === '@' || key[0] === '&' ? key.slice(1) : key)) {
466
- if (true )
467
- console.warn(`[vera] spread: ignoring the key ${JSON.stringify(key)} — an attribute name ` +
468
- `cannot contain whitespace, a quote, \`<\`, \`>\`, \`/\`, \`=\` or a control character, ` +
469
- `and one that cannot be written into markup would not survive server rendering.`);
470
- continue;
471
- }
472
- /** Counted above for the same reason the unsafe skip is. */
473
- const refused = refusedSink(key);
474
- if (refused !== null) {
475
- if (true )
476
- console.warn(`[vera] spread: refusing ${JSON.stringify(key)} — spread names arrive at runtime, which is ` +
477
- `exactly the property that makes this sink unreviewable; ${refused}.`);
478
- continue;
479
- }
480
- let binding = bindings.get(key);
674
+ let binding = bindings.get(name);
481
675
  if (binding === undefined)
482
- bindings.set(key, (binding = new Binding(element, key)));
483
- write(binding, props[key]);
484
- }
485
- /**
486
- * A size mismatch is the only way a key can have gone: every key in `props` was just visited, so
487
- * equal sizes means equal sets. The steady-state render of an unchanged shape — overwhelmingly the
488
- * common case — costs one integer comparison, not a scan.
489
- */
490
- if (bindings.size !== count) {
491
- for (const [key, binding] of bindings) {
492
- if (key in props)
493
- continue;
494
- bindings.delete(key);
495
- write(binding, binding._initial);
496
- }
676
+ bindings.set(name, (binding = new Binding(element, name, untracked)));
677
+ write(binding, props[name], adopting);
497
678
  }
679
+ if (bindings.size !== count)
680
+ for (const [name, binding] of bindings)
681
+ if (!(name in props)) {
682
+ bindings.delete(name);
683
+ write(binding, binding._initial);
684
+ }
498
685
  }
499
686
  /**
500
- * The server half of the protocol: hand back every binding, resolved, and let the renderer that
501
- * asked decide what belongs in markup.
502
- *
503
- * Deliberately *not* a serializer. This package knows what a key means — `.value` is a property,
504
- * `?disabled` a boolean, `onClick` an event — and nothing else. Whether a property belongs in
505
- * server markup (`value`, `checked`, `selected` do; the rest are client state) and how a value is
506
- * escaped are `@verajs/ssr`'s decisions, and principle #8 wants escaping in exactly one place. So
507
- * this returns data, never a string.
508
- *
509
- * Kinds are single characters rather than the module's numeric constants, because this crosses a
510
- * package boundary: `a`ttribute, `b`oolean, `p`roperty, `e`vent, `r`ef. A ref is client state with
511
- * no markup, exactly like an event, and the serializer drops both.
687
+ * The server half of the protocol: `[kind, name, value]` for each key `@verajs/ssr` should serialize —
688
+ * `a`ttribute, `b`oolean, `p`roperty, `e`vent, `r`ef — with every refusal and every refused URL already
689
+ * applied, by the same `resolve` the client uses, so the two cannot disagree.
512
690
  */
513
691
  function attributes() {
514
692
  const out = [];
515
693
  for (const key in this._props) {
516
- /** The client refusal, applied at the serializer boundary too — one predicate, both renders.
517
- * Without this, a refused key was merely inert in the browser and LIVE in server markup. */
518
- if (refusedSink(key) !== null)
694
+ const [kind, name] = resolve(key);
695
+ /** No element here: a property key is judged as a custom element's — the server only ever delivers one to a component. */
696
+ const rule = urlRule(kind, name, true);
697
+ const value = checked(rule, this._props[key]);
698
+ if (kind === REFUSED || value === REFUSE)
519
699
  continue;
520
- const first = key[0];
521
- /** `!` reports as a property: the server has nothing to re-read, so it serializes as `.` does. */
522
- const kind = first === '.' || first === '!'
523
- ? 'p'
524
- : first === '?'
525
- ? 'b'
526
- : first === '@'
527
- ? 'e'
528
- : first === '&'
529
- ? 'r'
530
- : 'a';
531
- if (kind !== 'a') {
532
- out.push([kind, key.slice(1), this._props[key]]);
533
- }
534
- else if (first === 'o' && key.charCodeAt(1) === 110 && key.charCodeAt(2) > 64 && key.charCodeAt(2) < 91) {
535
- out.push(['e', key.slice(2).toLowerCase(), this._props[key]]);
536
- }
537
- else {
538
- out.push(['a', key, this._props[key]]);
539
- }
700
+ out.push([kind === ATTR ? 'a' : kind === BOOLEAN ? 'b' : kind === EVENT ? 'e' : kind === REF ? 'r' : 'p', name, value]);
540
701
  }
541
702
  return out;
542
703
  }
704
+ /**
705
+ * Binds every key of `props` to the element it is placed on. Keys follow the template sigils — `.prop`,
706
+ * `?bool`, `@event` (or `onClick`), `&ref`, `!live` — and a plain key is an attribute.
707
+ *
708
+ * Already-branded input is returned as-is (JSX compiles `{...spread(x)}` to a spread of a spread). A
709
+ * value that is not a plain object is refused in BOTH builds — a string would otherwise be iterated by
710
+ * character index into attributes named `0`, `1`, `2` — and development says so.
711
+ */
543
712
  const spread = (props) => {
544
- /**
545
- * **Already branded → returned as-is.** `spread(spread(x))` arises legitimately: JSX compiles
546
- * `{...props({ date })}` to `spread(props({ date }))`, and `props()` below already returns the
547
- * branded result. Without this line the brand itself would be iterated as a bag and bind
548
- * attributes named `_props`, `_$apply$` and `_$attrs$`. Detected by the brand's PRESENCE, never
549
- * by identity with this bundle's `apply` — on a CDN page the renderer and a second copy of this
550
- * module are separate bundles with separate `apply` functions, and a result from either must
551
- * pass through both (the two-registry failure shape `tests/cdn-cross-bundle.test.mjs` guards).
552
- */
553
- if (props !== null && typeof props === 'object' && props._$apply$ !== undefined)
713
+ if (props !== null && typeof props === 'object' && typeof props._$apply$ === 'function')
554
714
  return props;
555
- /**
556
- * **A props bag that is not an object is iterated anyway, and a browser accepts the result.**
557
- *
558
- * Everything below reads `props` with `Object.keys`/`Object.entries`, which answer for any value:
559
- * a **string** yields its character indices, so `spread('text')` sets four attributes named `0`,
560
- * `1`, `2`, `3` — measured in Chromium, with no error and no warning. A number, a boolean and
561
- * `null` yield nothing at all, so `spread(someUndefinedVariable)` applies no props and says
562
- * nothing, which reads as a renderer that ignored the spread.
563
- *
564
- * **jsdom hides this rather than catching it.** It implements the XML Name production and throws
565
- * `InvalidCharacterError` on `setAttribute('0', …)`, so a probe under jsdom sees a loud failure
566
- * for the case a real engine performs silently — the inverse of the usual trap, and the reason
567
- * this was verified in a browser before being called a defect (`tests/browser/spread-names.test.js`
568
- * records the engines' actual rule).
569
- *
570
- * Warned and ignored rather than thrown, which is exactly what an unusable *key* already does a
571
- * few lines above: one bad props bag should not cost the render.
572
- *
573
- * **The message is `true `-only; the refusal is not.** They were both inside the guard, which
574
- * made the two builds behave differently for the same code — and differently in the direction that
575
- * hides the bug. Measured: `spread('text')` applies nothing in development, so the app under test
576
- * looks fine; in production the string is iterated by character index and the element ends up with
577
- * attributes named `0`, `1`, `2` and `3` (under jsdom, an `InvalidCharacterError` instead — the
578
- * usual inversion, and why this was measured against both builds rather than reasoned about).
579
- *
580
- * A diagnostic belongs in `true `. A guard that changes what the program does cannot, or the
581
- * development build stops being a faithful model of the production one, which is the property that
582
- * makes testing in it worth anything. Costs 27 B gzipped (842 → 869, A-B-A) and buys the two builds agreeing.
583
- */
584
715
  if (props === null || typeof props !== 'object' || Array.isArray(props)) {
585
716
  if (true )
586
- console.warn(`[vera] spread: ignoring a props bag that is not a plain object — received ` +
587
- `${Array.isArray(props) ? 'an array' : typeof props === 'object' ? 'null' : `a ${typeof props}`}. ` +
588
- `A string is iterated by character index, so \`spread('text')\` would set attributes named ` +
589
- `0, 1, 2 and 3; anything else applies nothing at all. This is usually an import or a ` +
590
- `property that resolved to something unexpected.`);
717
+ console.warn(diagnostic('spread', 'spread()', 'spread-not-object', true && PROSE$1['spread-not-object'](Array.isArray(props) ? 'an array' : typeof props === 'object' ? 'null' : `a ${typeof props}`)));
591
718
  props = {};
592
719
  }
593
- return {
594
- _props: props,
595
- _$apply$: apply,
596
- _$attrs$: attributes,
597
- };
720
+ return { _props: props, _$apply$: apply, _$attrs$: attributes };
721
+ };
722
+
723
+ const PROSE = {
724
+ 'tag-position': (tag) => [
725
+ `a tag (\`${tag}\`) may only stand in tag position — \`<\${T}>…</\${T}>\`.`,
726
+ 'Spliced anywhere else it would become text or part of an attribute, which a tag never means.',
727
+ ],
728
+ 'tag-interpolation': () => [
729
+ 'only another tag may be interpolated — a string cannot become markup.',
730
+ 'Interpolate a tag: tag`${Base}-card`, where Base is itself a tag.',
731
+ ],
732
+ 'tag-name': (text) => [
733
+ `${text} is not an element name. A tag names ONE element — letters, then letters, digits, '.', '_' or '-' — and nothing else becomes markup here.`,
734
+ 'Attributes and content belong in the template: html`<${heading} class="title">…</${heading}>`.',
735
+ ],
736
+ 'tag-key': () => [
737
+ '`key` does nothing on a tag component and has been dropped — a key marks a template for list reconciliation, and this call returns one rather than being one.',
738
+ 'In JSX, write it and the compiler handles it: `<Row key=${id}>` becomes `keyed(id, Row({…}))`. Calling by hand, wrap it yourself: `keyed(id, Row({…}))`.',
739
+ ],
740
+ 'tag-inner-html': () => [
741
+ '`dangerouslySetInnerHTML` is not available on a tag component and has been dropped. A tag binds through `spread`, whose names are only known at runtime — so it refuses `.innerHTML` outright rather than open an unreviewable HTML sink.',
742
+ "Write the element directly, with the value sanitized first: html`<${Tag} .innerHTML=${trusted}>` (see the renderer README's security note).",
743
+ ],
598
744
  };
599
745
 
600
746
  /**
@@ -623,6 +769,8 @@ const spread = (props) => {
623
769
  */
624
770
  /** The brand a tag carries. `_$…$` is exempt from this package's `/^_[a-z]/` property mangling. */
625
771
  const STATIC = '_$static$';
772
+ /** The 14 void elements — the renderer's development tag-shape pass reads the same list. */
773
+ const VOID_TAGS = /^(?:area|base|br|col|embed|hr|img|input|link|meta|source|track|wbr|param)$/i;
626
774
  /**
627
775
  * Spliced statics, keyed by the call site's own `strings` array and then by the tags in it.
628
776
  *
@@ -638,32 +786,21 @@ const caches = new WeakMap();
638
786
  * ordinary template shape and costs one loop.
639
787
  *
640
788
  * It builds `{ _$litType$: 1, strings, values }` directly rather than calling core's `html`, so this
641
- * entry keeps the renderer's independence from core. The consequence is that a `setHtml` swap does
642
- * not reach here — which is right, since a swapped `html` belongs to a different renderer and this
643
- * is a renderer feature.
789
+ * entry keeps the renderer's independence from core.
644
790
  */
645
791
  const html = (strings, ...values) => {
646
792
  let key = '';
647
793
  for (let i = 0; i < values.length; i++) {
648
794
  const value = values[i];
649
- if (value && value[STATIC] !== undefined)
795
+ if (value && value[STATIC] !== undefined) {
796
+ /**
797
+ * A tag belongs in TAG position only. Spliced anywhere else it became text, an attribute value, or an attribute
798
+ * NAME (`<p ${T}=${v}>`) — a route around the renderer's refusal of a name expression. Development only: the
799
+ * name text is fixed by source either way, so this is consistency, not safety.
800
+ */
801
+ if (true && !(strings[i].endsWith('<') || strings[i].endsWith('</')))
802
+ throw new Error(misuse('tag', 'tag-position', true && PROSE['tag-position'](value[STATIC])));
650
803
  key += `${i}:${value[STATIC]};`;
651
- /**
652
- * A non-tag in **tag position** — `<${name}>` with a string. The refusal is the whole security
653
- * property of this entry, and it lived only in `tag` itself, which guards interpolation into a
654
- * tag literal. Reaching the position through `html` instead produced no error and no element:
655
- * the base scanner reads the expression as an element ref on a tag with no name, and the page
656
- * gets escaped punctuation where the markup should be.
657
- *
658
- * The static before a value is what identifies the position, so this is the one place that can
659
- * see it. `true `-only; production carries neither the check nor the text.
660
- */
661
- else if (true && (strings[i].endsWith('<') || strings[i].endsWith('</'))) {
662
- throw new Error(`tag: a ${value === null ? 'null' : typeof value} cannot become markup. ` +
663
- `Only a tag may be interpolated into tag position:\n\n` +
664
- ` const heading = tag\`h\${level}\`; // built from other tags\n` +
665
- ` html\`<\${heading}>…</\${heading}>\`\n\n` +
666
- `That is what keeps the set of tags an app can produce fixed by its source.`);
667
804
  }
668
805
  }
669
806
  if (key === '')
@@ -685,6 +822,11 @@ const html = (strings, ...values) => {
685
822
  }
686
823
  }
687
824
  spliced.push(run);
825
+ /**
826
+ * A spliced array is a template's strings, so it carries `raw` as a tagged literal's does: that own property is
827
+ * how a renderer tells a template from data shaped like one (parsed JSON cannot give an array a `raw`).
828
+ */
829
+ spliced.raw = spliced;
688
830
  byTags.set(key, spliced);
689
831
  }
690
832
  const bindings = [];
@@ -706,26 +848,50 @@ const html = (strings, ...values) => {
706
848
  * build-time and runtime, and `tests/jsx-name-mapping.test.mjs` asserts they agree on every key —
707
849
  * which is the drift protection a shared module would have bought, without the dependency.
708
850
  */
709
- const NAME_MAP = { className: 'class', htmlFor: 'for' };
710
- const PROPERTIES = { value: '.value', checked: '.checked' };
711
- const DEFAULTS = { defaultValue: 'value', defaultChecked: '?checked' };
712
- /**
713
- * The props that name a BINDING rather than an attribute — and the reason this table is here and
714
- * not in the transform's twin.
715
- *
716
- * The compiler must NOT rewrite these on a component: `<Card ref={r}>` hands `ref` to `Card`, which
717
- * decides what it means, exactly as React does. But a tag's component forwards to a real element,
718
- * so at THIS boundary — and only here — `ref` has a binding to become. Before 2026-09-12 it had
719
- * none: it fell through to the attribute sink and `<H ref={r}>` wrote the FUNCTION'S SOURCE TEXT
720
- * into the DOM as `ref="el => (got = el)"`, which under SSR shipped the closure body to the client,
721
- * while the identical `<h1 ref={r}>` bound correctly.
722
- */
723
- const BINDINGS = { ref: '&ref' };
724
851
  const BOOLEAN_ATTRIBUTES = new Set([
725
852
  'disabled', 'hidden', 'readonly', 'required', 'open', 'selected', 'multiple',
726
853
  'autofocus', 'autoplay', 'controls', 'loop', 'muted', 'playsinline', 'inert', 'reversed',
727
854
  ]);
728
- const jsxName = (key) => NAME_MAP[key] ?? PROPERTIES[key] ?? DEFAULTS[key] ?? BINDINGS[key] ?? (BOOLEAN_ATTRIBUTES.has(key) ? `?${key}` : key);
855
+ /**
856
+ * ONE table, with no prototype: React's names (`className`, `htmlFor`), the form controls' properties and defaults,
857
+ * the booleans (`?disabled`), and `ref` — the prop that names a BINDING rather than an attribute. The compiler must
858
+ * not rewrite `ref` on a component (`<Card ref={r}>` hands it to `Card`), but a tag's component forwards to a real
859
+ * element, so at THIS boundary it has a binding to become; before 2026-09-12 it fell through to the attribute sink
860
+ * and wrote the function's SOURCE TEXT into the DOM.
861
+ *
862
+ * No prototype, because four plain object literals answered for `constructor`, `toString` and the rest of
863
+ * `Object.prototype` — those props were mapped to a function, refused as a name, and silently dropped.
864
+ */
865
+ const NAMES = {
866
+ __proto__: null,
867
+ className: 'class',
868
+ htmlFor: 'for',
869
+ /** Controlled, compared with the control's LIVE state — the compiler's twin (`@verajs/jsx`) maps them the same. */
870
+ value: '!value',
871
+ checked: '!checked',
872
+ defaultValue: 'value',
873
+ defaultChecked: '?checked',
874
+ ref: '&ref',
875
+ };
876
+ for (const name of BOOLEAN_ATTRIBUTES)
877
+ NAMES[name] = `?${name}`;
878
+ const jsxName = (key) => NAMES[key] ?? key;
879
+ /**
880
+ * **On a CUSTOM element a bare prop is a PROP** — exactly the rule `@verajs/jsx` compiles `<my-el foo={x}>` by: React's
881
+ * renames first (`className` → `class`, `htmlFor` → `for`), `ref` its binding, a sigil or `on…` passed through, and any
882
+ * other name that could be a JS property becomes `.name` — the HTML-control guesses (`?disabled`, `.value`) never reach
883
+ * a component, whose `disabled` is its own prop. A name that cannot be a property (`data-x`, `aria-label`) and the two
884
+ * names the DOM itself renamed (`class`, `for`) stay attributes.
885
+ */
886
+ const componentName = (key) => key === 'className'
887
+ ? 'class'
888
+ : key === 'htmlFor'
889
+ ? 'for'
890
+ : key === 'ref'
891
+ ? '&ref'
892
+ : /^[.?@&!]|^on[A-Z]/.test(key) || !/^[A-Za-z_$][\w$]*$/.test(key) || key === 'class' || key === 'for'
893
+ ? key
894
+ : `.${key}`;
729
895
  /**
730
896
  * Declares a tag name.
731
897
  *
@@ -740,20 +906,23 @@ const tag = (strings, ...values) => {
740
906
  * likelier mistake of the two and failed with `Cannot read properties of undefined (reading '0')`,
741
907
  * which says nothing about either.
742
908
  */
743
- if (true && (!strings || !Array.isArray(strings.raw)))
744
- throw new TypeError(`tag: expected a template literal and received ${String(strings)}. ` +
745
- "It is a tagged template — write tag`h1`, not tag('h1').");
909
+ /**
910
+ * In EVERY build: in production `tag('h1')` read the STRING's first character as the template's first static and
911
+ * named an `<h>`, silently — a wrong element only production renders. The explanation is development's.
912
+ */
913
+ if (!strings?.raw)
914
+ throw new TypeError(misuse('tag', 'tag-called', true && tagCalled('tag', typeof strings === 'string' ? JSON.stringify(strings) : String(strings), typeof strings === 'string' ? strings : 'h1')));
746
915
  let text = strings[0];
747
916
  for (let i = 0; i < values.length; i++) {
748
917
  const value = values[i];
749
918
  if (!value || value[STATIC] === undefined)
750
- throw new Error('tag: only another tag may be interpolated — a string cannot become markup');
919
+ throw new Error(misuse('tag', 'tag-interpolation', true && PROSE['tag-interpolation']()));
751
920
  text += value[STATIC] + strings[i + 1];
752
921
  }
753
922
  /**
754
923
  * **A tag's text must be an element NAME.** Until this, it was an unconstrained string spliced
755
924
  * straight into the statics — so `` tag`div onclick=x` `` produced markup rather than a tag, and
756
- * the name of this export was a description of intent rather than of behaviour.
925
+ * the name of this export was a description of intent rather than of behavior.
757
926
  *
758
927
  * The concrete failure it closes is a cache collision. Spliced statics key on
759
928
  * `` `${i}:${text};` `` per tag, joined with separators the text was free to contain, so two
@@ -777,11 +946,7 @@ const tag = (strings, ...values) => {
777
946
  * page never reaches. Core's static-render refusal is shaped the same way for the same
778
947
  * measurement.
779
948
  */
780
- true
781
- ? `tag: ${JSON.stringify(text)} is not an element name. A tag names ONE element — letters, ` +
782
- `then letters, digits, '.', '_' or '-' — and nothing else becomes markup here.\n` +
783
- `Attributes and content belong in the template: html\`<\${heading} class="title">…</\${heading}>\`.`
784
- : 'tag: not an element name');
949
+ misuse('tag', 'tag-name', true && PROSE['tag-name'](JSON.stringify(text))));
785
950
  /**
786
951
  * The tag is a function, which is what makes it a JSX component: the compiler emits `H({…})` for
787
952
  * a capitalized tag, and this is what receives that call. `children` is JSX's own key; everything
@@ -799,10 +964,7 @@ const tag = (strings, ...values) => {
799
964
  * looking, and dropping it silently would be a refusal with no channel, hence the warning.
800
965
  */
801
966
  if (true && key !== undefined)
802
- console.warn(`[vera] tag: \`key\` does nothing on a tag component and has been dropped — a key marks a ` +
803
- `template for list reconciliation, and this call returns one rather than being one.\n` +
804
- `In JSX, write it and the compiler handles it: \`<Row key=\${id}>\` becomes ` +
805
- `\`keyed(id, Row({…}))\`. Calling by hand, wrap it yourself: \`keyed(id, Row({…}))\`.`);
967
+ console.warn(diagnostic('tag', `<${text}>`, 'tag-key', true && PROSE['tag-key']()));
806
968
  /**
807
969
  * **`dangerouslySetInnerHTML` cannot work here, and that is a security property rather than a
808
970
  * gap.** A tag reaches its element through `spread`, and `spread` REFUSES `.innerHTML` on
@@ -811,16 +973,31 @@ const tag = (strings, ...values) => {
811
973
  * console message. Refused here instead, where the reason can be said.
812
974
  */
813
975
  if (true && rawHtml !== undefined)
814
- console.warn(`[vera] tag: \`dangerouslySetInnerHTML\` is not available on a tag component and has been ` +
815
- `dropped. A tag binds through \`spread\`, whose names are only known at runtime — so it ` +
816
- `refuses \`.innerHTML\` outright rather than open an unreviewable HTML sink.\n` +
817
- `Write the element directly, with the value sanitized first: ` +
818
- `html\`<\${Tag} .innerHTML=\${trusted}>\` (see the renderer README's security note).`);
819
- const mapped = {};
976
+ console.warn(diagnostic('tag', `<${text}>`, 'tag-inner-html', true && PROSE['tag-inner-html']()));
977
+ /** No prototype, and `__proto__` is no prop: a bag key by that name would otherwise reach `spread` as one. */
978
+ const mapped = { __proto__: null };
820
979
  for (const name in props)
821
- mapped[jsxName(name)] = props[name];
822
- return html `<${self} ${spread(mapped)}>${children}</${self}>`;
980
+ if (name !== '__proto__') {
981
+ /** The compiler refuses an object `style` at build time; written into the attribute it reads "[object Object]". */
982
+ if (true && name === 'style' && props[name] !== null && typeof props[name] === 'object')
983
+ throw new TypeError(misuse('tag', 'style-object', true && styleObject('style: `color:${c}`')));
984
+ mapped[(custom ? componentName : jsxName)(name)] = props[name];
985
+ }
986
+ /**
987
+ * A void element has no content and no end tag: `</br>` is read as a SECOND `<br>`, and a child anchor strays. So
988
+ * children given to one would vanish silently — development says so (an empty list is no content).
989
+ */
990
+ if (true && empty && children != null && !(Array.isArray(children) && children.length === 0))
991
+ throw new Error(misuse('tag', 'void-children', true && voidChildren(text, 'children given to it would vanish')));
992
+ return empty ? html `<${self} ${spread(mapped)}>` : html `<${self} ${spread(mapped)}>${children}</${self}>`;
823
993
  });
994
+ const empty = VOID_TAGS.test(text);
995
+ /**
996
+ * A custom element's props map by the compiler's component rule — never by the HTML-control guesses. A dash name is
997
+ * enough here: the compiler also excludes eight reserved SVG/MathML names (`font-face`, `annotation-xml`…), which
998
+ * cost 77 B to carry and which a tag essentially never names (Brian, 2026-10-01).
999
+ */
1000
+ const custom = text.includes('-');
824
1001
  self[STATIC] = text;
825
1002
  return self;
826
1003
  };