@verajs/renderer 0.2.2 → 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 +711 -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 +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 +48 -96
  35. package/dist/development/vera-renderer-profiler.d.ts.map +1 -1
  36. package/dist/development/vera-renderer-profiler.js +2423 -2140
  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 +2400 -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
@@ -79,121 +79,73 @@ type OverlayOptions = {
79
79
  };
80
80
 
81
81
  /**
82
- * @verajs/renderer — a ground-up, keyed, template-identity renderer.
82
+ * @verajs/renderer — a template-identity renderer.
83
83
  *
84
- * Replaces the Reef-derived renderer, which flattened every template to an HTML string and
85
- * re-parsed it on each change — O(whole template) work for a one-row edit, measured at 85 ms for a
86
- * two-row swap that lit-html does in 3.5 ms.
84
+ * A tagged template's `strings` array is interned per call site, so it keys a parsed `<template>`.
85
+ * An instance clones it and binds the expression positions; every later render of the same shape
86
+ * commits only the values that changed. Lists reconcile by index here, by key through
87
+ * `@verajs/renderer/keyed`.
87
88
  *
88
- * The architecture here is the one that wins that benchmark:
89
+ * Contracts the speed pays for:
90
+ * - The renderer owns its container below the mount point: a part that owns a whole parent clears it
91
+ * with one `textContent = ''`.
92
+ * - Do not `normalize()` rendered content — child anchors are text nodes.
93
+ * - A string renders as text, never as markup. There is no `innerHTML` sink.
89
94
  *
90
- * 1. A tagged template literal's `strings` array is frozen and IDENTICAL for every call from the
91
- * same call site, so it is a cache key for the template's static shape. The shape is parsed
92
- * ONCE into a `<template>` element with markers where the expressions go.
93
- * 2. Rendering clones that template and binds "parts" to the marker positions. Every later render
94
- * of the same shape only compares and commits the dynamic values — static content is never
95
- * touched again.
96
- * 3. Arrays reconcile KEYED (see `keyed()`), with head/tail fast paths and map-based moves, so a
97
- * reorder moves nodes instead of rebuilding them.
98
- *
99
- * Built in, where lit-html requires directive imports: keyed list reconciliation (`keyed`),
100
- * element refs (element-position expressions), toggled-DOM preservation (`hold`), and a
101
- * whole-range fast clear — one `textContent = ''` where lit removes thousands of nodes one at a
102
- * time. Like-for-like (lit-html + repeat + ref + cache: 5 021 B gzip), this file is ~28% smaller.
103
- *
104
- * What it deliberately does NOT have, which is why it is smaller than lit-html: no directive
105
- * protocol, no `noChange`/`nothing` sentinels (in a single-expression attribute, `null`/`undefined`
106
- * REMOVE the attribute; in a child, they clear it), no sanitizer indirection, no async parts, no
107
- * dev-mode branches.
108
- *
109
- * Known limits, deliberate and shared with lit-html's envelope: no bindings inside comments (the
110
- * value is consumed and ignored), no dynamic tag names, and nested `<template>` elements' contents
111
- * are not traversed.
112
- *
113
- * CONTRACTS THE SPEED PAYS FOR — these are the trade, documented rather than discovered:
114
- *
115
- * - **The renderer owns its container below the mount point.** The whole-range fast clear wipes
116
- * everything in a parent the part fully owns, including nodes user code appended there by hand
117
- * (lit-html would preserve them). Same contract as mounting Vue or React into a container.
118
- * - **Do not call `Node.normalize()` on rendered content.** Child anchors are text nodes, and
119
- * normalize merges adjacent text — lit-html's comment anchors are immune to this; ours are not.
120
- * - **A plain string renders as text, never as HTML.** The Reef renderer parsed strings as markup;
121
- * this one has no innerHTML sink at all (an XSS class removed). The deliberate escape hatch for
122
- * trusted markup is a property binding: `.innerHTML=${trusted}`.
123
- * - **Hydration is automatic and markerless.** The first render into a container that already has
124
- * children adopts them as server output of the same template (statics matched byte-for-byte,
125
- * anchors installed by splitting live text at known value positions), falling back to a clean
126
- * render on any mismatch. Requires the initial client render to match server state — same
127
- * contract as React/Vue hydration.
128
- * - **No directive protocol.** The template language itself is closed to extension — Vera extends
129
- * at the framework layer (inserts) and through element refs, not inside the renderer's value
130
- * handling.
131
- * - Event handlers are invoked with `this` bound to the ELEMENT (lit binds its host).
132
- *
133
- * NAMING NOTE: internal class fields and methods are `_`-prefixed because the production build
134
- * mangles properties matching /^_[a-z]/ (see defaultRollupConfig). That is what lets this file use
135
- * full descriptive names while still shipping one-letter properties — locals and top-level names
136
- * are mangled by default anyway, but property names are not. `_$litType$` and `handleEvent`
137
- * deliberately do not match the pattern: the first is an interop wire format, the second is called
138
- * by the DOM itself.
95
+ * Internal members are `_`-prefixed because the production build mangles `/^_[a-z]/`. `$`-named
96
+ * members cross bundle boundaries (keyed, spread, slots) and survive mangling by not matching it.
139
97
  */
140
98
 
141
99
  /**
142
- * Preserves the DOM of templates a child position toggles away from, instead of destroying it —
143
- * form values, scroll positions and media playback survive the round trip (lit-html calls this
144
- * `cache`). Stashed DOM is parked in its instance's own fragment and re-adopted on return.
100
+ * Preserves the DOM of a template a position toggles away from, instead of destroying it — form values
101
+ * and media state survive the round trip. Anything that is not a template passes straight through, so
102
+ * `hold(editing && editor())` is fine.
145
103
  *
146
104
  * ```js
147
105
  * html`<div>${hold(editing ? editor() : viewer())}</div>`
148
106
  * ```
149
- *
150
- * **Anything that is not a template passes straight through.** There is nothing to park for a
151
- * string, a list, `null` or `false`, and the branch that produces one is the ordinary shape of the
152
- * expression this wraps — `hold(editing && editor())`, `hold(row ?? null)`. Wrapping those handed
153
- * the renderer a `{ $h }` carrying a non-template, which reached the held-commit path and threw on
154
- * `result.strings`: a whole render lost, from a value the same expression renders happily one
155
- * character to the left. Decided here rather than in the renderer so the hot path pays nothing.
156
107
  */
157
108
  declare const hold: <T>(result: T) => T | {
158
109
  $h: TemplateResult;
159
110
  };
111
+ declare const renderInto: (result: unknown, container: Node, owns?: boolean) => void;
112
+ type Registry = {
113
+ get(name: never): unknown;
114
+ $S?: unknown;
115
+ $F?: unknown;
116
+ };
160
117
  /**
161
- * Writes a template result into a container. The renderer's imperative draw: no reactivity, no
162
- * lifecycle, no knowledge of components. Slots into Vera via `wire([renderer])`; core's built-in
163
- * `html` tag already produces the accepted shape, so no `setHtml` call is required — though
164
- * lit-html's `html` also works, its results being structurally identical.
165
- *
166
- * **It owns its own range and nothing else.** The first call appends a marker and anchors a root
167
- * part there; later calls with the same container reuse that part and walk only the value slots, so
168
- * nodes are updated in place rather than rebuilt. Content that was already in the container stays.
169
- *
170
- * **Named for the relationship, not the act.** It was `render` until 0.2.0, which collided with
171
- * core's `render` — a different function, with a different arity, that declares a *reactive*
172
- * template and commits a component's setup. Both were public and both were documented, so a reader
173
- * who knew one misread the other. `renderElement` and `renderDom` were considered and rejected: this
174
- * renders *into* a container, and the container is a `Node` — a shadow root and a fragment are both
175
- * valid, so "element" would be a lie in the type. Argument order is lit-html's on purpose.
176
- *
177
- * HYDRATION lives in `@verajs/renderer/hydrate` — a drop-in superset entry whose `renderInto` adopts
178
- * existing server-rendered children on first render. SSR apps import from there instead of here;
179
- * this entry carries zero hydration code.
118
+ * What a consumer's TypeScript sees — the shape `wire` accepts (`Wireable`, structurally: this package imports no
119
+ * types from `@verajs/inserts`): a DESCRIPTOR, `on: 'render'`, callable with options to give `[renderer, a connector]`.
120
+ * On a server `on` is in fact `undefined` (decided at load, below) — a runtime decision the type does not carry, as
121
+ * the previous `on: 'render' | undefined` did: that matched neither a descriptor nor a connector, so `wire([renderer])`
122
+ * stopped compiling in a consumer's project (tests/consumer, 2026-10-10).
180
123
  */
181
- declare const renderInto: (result: unknown, container: Node) => void;
182
- declare const renderer: {
183
- name: string;
184
- on: "render";
124
+ type RendererModule = ((options?: {
125
+ shadow?: 'open' | 'closed' | false | ShadowRootInit;
126
+ foreignNodes?: 'preserve' | 'drop';
127
+ }) => readonly [RendererModule, (registry: Registry) => void]) & {
128
+ readonly on: 'render';
185
129
  fn: never;
186
130
  priority: number;
187
- /**
188
- * Typed against the registry `wire` actually hands over, not a narrower shape that happens to
189
- * describe the one lookup this makes. A structural `{ get(name: 'value'): … }` is **not**
190
- * assignable from `Inserts`, so `wire([renderer])` failed to compile in a consumer's project while
191
- * this repo's own typecheck — which reads sources, not the shipped `.d.ts` — saw nothing.
192
- */
193
- connect: (given: {
194
- get(name: never): unknown;
195
- }) => void;
131
+ connect: (given: Registry) => void;
196
132
  };
133
+ /**
134
+ * **`renderer` is a DUAL** — `wire([renderer])` as it always was, or `wire([renderer({ shadow: 'open' })])` to set the
135
+ * app's default root: every component whose own `shadow` option says nothing gets it (core's `init` reads it after the
136
+ * component's own and before light DOM). `renderer({ foreignNodes: 'preserve' })` is the same for `foreignNodes`, and sets
137
+ * COMPONENT roots only — a container handed to `renderInto` (`document.body`, `#app`) always keeps foreign nodes. Called, it returns `[renderer, a connector setting the default]` — `wire`
138
+ * takes nested arrays — so the module is one function with its descriptor fields on it, and nothing is made per call
139
+ * but that connector.
140
+ *
141
+ * **On a server it declines its render insert** (Brian's (b′), 2026-10-10): `@verajs/ssr` renders with its own renderer,
142
+ * and a client one wired in shared app code used to DISPLACE it, breaking every server render. There `on` is undefined,
143
+ * which makes `wire` hand this function the registry as a CONNECTOR: it still CONNECTS — the registry, `untracked`, the
144
+ * hydration hand-off: a process that loaded ssr may install a client DOM and call renderInto directly (tests/spread-ssr
145
+ * does) — and only the render INSERT is declined, so one shared `wire([renderer({ shadow })])` carries the same default
146
+ * to both sides. Development says so once per process.
147
+ */
148
+ declare const renderer: RendererModule;
197
149
 
198
150
  /** Begin collecting. Calling this while already profiling restarts the collection. */
199
151
  declare const startProfiling: () => void;
@@ -1 +1 @@
1
- {"version":3,"file":"vera-renderer-profiler.d.ts","sources":["../../src/types.ts","../../src/renderer.ts","../../src/profiler.ts"],"mappings":"AAAA;;;;;;;;;;;;;;;;;AAiBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACjBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DG;;;;;;;;;;;;;;;;AAwBA;AACH;AAEI,kBAAgC;sBACvB;AAEb;;AA+cM;AAEN;AAEA;AAEA;AACE;;AAsBA;AACE;AACA;;;AAGA;AACA;AACA;AACE;;;AAEA;;AAGF;;;;;AAKG;AACH;;AAEA;AACA;;AAEE;AACE;AACA;;AAEJ;AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC/jBD;AACH;AASA,cAAS,YAAc,2BAAqB;AAK5C;AAIA,cAAa,YAAM,WAAA,aAAA;;;;","names":[]}
1
+ {"version":3,"file":"vera-renderer-profiler.d.ts","sources":["../../src/types.ts","../../src/renderer.ts","../../src/profiler.ts"],"mappings":"AAAA;;;;;;;;;;;;;;;;;AAiBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACjBH;;;;;;;;;;;;;;;;AAgBG;;AAqPC;;;;AAIG;AACH;AACA;AACA;;cAEE,IAAI;sBACM;AACV;AAYA,cAAA,UAAU,+BAAW,IAAA;AACrB,KAAA,QAAA;;;AAEA;;;;AAIA;AACA;AACE;;;AAEA,KAAA,cAAE;AACF,yCAAyB,cAAA;AACvB;8BAA6B,aAAc,QAAC;AACvC;;;AAEH,qBAAA,QAAI;AAAwD;AAC5D;;;;;AAGG;;AAEL;AACE;;;AAEK;;;AAEL;wBACA,cAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACxRrB;AACH;AASA;AAKA;AAIA,cAAa,YAAM,aAAA,cAAA;AACnB;AACA,cAAc,YAAE,WAAA,aAAA;;;;","names":[]}