@verajs/renderer 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,9 @@
1
+ # @verajs/renderer
2
+
3
+ A keyed, template-identity renderer (~3.6 KB gzip): tagged templates, `.prop`/`?bool`/`@event`
4
+ and React-style `onClick` bindings, element refs, `keyed()` lists, `hold()` DOM preservation.
5
+ `@verajs/renderer/hydrate` is a drop-in superset whose first render ADOPTS server-rendered DOM —
6
+ markerless hydration (no framework comments in server HTML). SSR apps import from `/hydrate`;
7
+ everyone else pays zero hydration bytes.
8
+
9
+ Wire once: `setRenderer(render)` from `@verajs/core`.
@@ -0,0 +1,99 @@
1
+ /**
2
+ * @verajs/renderer — a ground-up, keyed, template-identity renderer.
3
+ *
4
+ * Replaces the Reef-derived renderer, which flattened every template to an HTML string and
5
+ * re-parsed it on each change — O(whole template) work for a one-row edit, measured at 85 ms for a
6
+ * two-row swap that lit-html does in 3.5 ms.
7
+ *
8
+ * The architecture here is the one that wins that benchmark:
9
+ *
10
+ * 1. A tagged template literal's `strings` array is frozen and IDENTICAL for every call from the
11
+ * same call site, so it is a cache key for the template's static shape. The shape is parsed
12
+ * ONCE into a `<template>` element with markers where the expressions go.
13
+ * 2. Rendering clones that template and binds "parts" to the marker positions. Every later render
14
+ * of the same shape only compares and commits the dynamic values — static content is never
15
+ * touched again.
16
+ * 3. Arrays reconcile KEYED (see `keyed()`), with head/tail fast paths and map-based moves, so a
17
+ * reorder moves nodes instead of rebuilding them.
18
+ *
19
+ * Built in, where lit-html requires directive imports: keyed list reconciliation (`keyed`),
20
+ * element refs (element-position expressions), toggled-DOM preservation (`hold`), and a
21
+ * whole-range fast clear — one `textContent = ''` where lit removes thousands of nodes one at a
22
+ * time. Like-for-like (lit-html + repeat + ref + cache: 5 021 B gzip), this file is ~28% smaller.
23
+ *
24
+ * What it deliberately does NOT have, which is why it is smaller than lit-html: no directive
25
+ * protocol, no `noChange`/`nothing` sentinels (in a single-expression attribute, `null`/`undefined`
26
+ * REMOVE the attribute; in a child, they clear it), no sanitizer indirection, no async parts, no
27
+ * dev-mode branches.
28
+ *
29
+ * Known limits, deliberate and shared with lit-html's envelope: no bindings inside comments (the
30
+ * value is consumed and ignored), no dynamic tag names, and nested `<template>` elements' contents
31
+ * are not traversed.
32
+ *
33
+ * CONTRACTS THE SPEED PAYS FOR — these are the trade, documented rather than discovered:
34
+ *
35
+ * - **The renderer owns its container below the mount point.** The whole-range fast clear wipes
36
+ * everything in a parent the part fully owns, including nodes user code appended there by hand
37
+ * (lit-html would preserve them). Same contract as mounting Vue or React into a container.
38
+ * - **Do not call `Node.normalize()` on rendered content.** Child anchors are text nodes, and
39
+ * normalize merges adjacent text — lit-html's comment anchors are immune to this; ours are not.
40
+ * - **A plain string renders as text, never as HTML.** The Reef renderer parsed strings as markup;
41
+ * this one has no innerHTML sink at all (an XSS class removed). The deliberate escape hatch for
42
+ * trusted markup is a property binding: `.innerHTML=${trusted}`.
43
+ * - **Hydration is automatic and markerless.** The first render into a container that already has
44
+ * children adopts them as server output of the same template (statics matched byte-for-byte,
45
+ * anchors installed by splitting live text at known value positions), falling back to a clean
46
+ * render on any mismatch. Requires the initial client render to match server state — same
47
+ * contract as React/Vue hydration.
48
+ * - **No directive protocol.** The template language itself is closed to extension — Vera extends
49
+ * at the framework layer (inserts) and through element refs, not inside the renderer's value
50
+ * handling.
51
+ * - Event handlers are invoked with `this` bound to the ELEMENT (lit binds its host).
52
+ *
53
+ * NAMING NOTE: internal class fields and methods are `_`-prefixed because the production build
54
+ * mangles properties matching /^_[a-z]/ (see defaultRollupConfig). That is what lets this file use
55
+ * full descriptive names while still shipping one-letter properties — locals and top-level names
56
+ * are mangled by default anyway, but property names are not. `_$litType$` and `handleEvent`
57
+ * deliberately do not match the pattern: the first is an interop wire format, the second is called
58
+ * by the DOM itself.
59
+ */
60
+ type TemplateResult = {
61
+ /** 1 = html, 2 = svg, 3 = mathml — the markers core's built-in tags produce. */
62
+ _$litType$?: number;
63
+ strings: TemplateStringsArray;
64
+ values: unknown[];
65
+ /** Set by `keyed()`; drives keyed list reconciliation. */
66
+ key?: unknown;
67
+ };
68
+ /**
69
+ * Marks a template result with a stable key so list reconciliation moves it instead of rewriting
70
+ * it. Key all items in a list or none — mixing is undefined behaviour, as are duplicate keys.
71
+ *
72
+ * ```js
73
+ * rows.map((r) => keyed(r.id, html`<tr>...</tr>`))
74
+ * ```
75
+ */
76
+ declare const keyed: <T>(key: unknown, result: T) => T;
77
+ /**
78
+ * Preserves the DOM of templates a child position toggles away from, instead of destroying it —
79
+ * form values, scroll positions and media playback survive the round trip (lit-html calls this
80
+ * `cache`). Stashed DOM is parked in its instance's own fragment and re-adopted on return.
81
+ *
82
+ * ```js
83
+ * html`<div>${hold(editing ? editor() : viewer())}</div>`
84
+ * ```
85
+ */
86
+ declare const hold: (result: TemplateResult) => {
87
+ $h: TemplateResult;
88
+ };
89
+
90
+ /**
91
+ * The hydrating `render`: a drop-in for the base entry's. The first render into a container that
92
+ * already has children adopts them; any mismatch clears (keeping `<style vera-styles>`) and falls
93
+ * through to a clean base render. After the first render, this IS the base render.
94
+ */
95
+ declare const render: (result: unknown, container: Node) => void;
96
+
97
+ export { hold, keyed, render };
98
+ export type { TemplateResult };
99
+ //# sourceMappingURL=vera-renderer-hydrate.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"vera-renderer-hydrate.d.ts","sources":["../../../../../../src/renderer.ts"],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DG;AAWH,KAAA,cAAA;;;;;;;AAOG;AACH;AACG;AACD;AACF;AAEA;;;;;;;;AAQG;AACH;AAEA;;;AAGG;AACH,kBAAe,WAAc,cAAc;AAC3C,QAAA,cAAA;AACA;;;;;;;;;;;","names":[]}