@verajs/renderer 0.1.2 → 0.1.3

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.
@@ -0,0 +1,173 @@
1
+ /**
2
+ * The profiler's in-page panel — live counts and the current churn list, in the corner of the app
3
+ * you are already clicking through.
4
+ *
5
+ * Three constraints shaped this:
6
+ *
7
+ * 1. **It must not render itself with the renderer.** Doing so would fold the overlay's own
8
+ * commits into the numbers it reports. Everything here is plain DOM, updated in place.
9
+ * 2. **It must not restyle the app.** It lives in a closed shadow root and sets every property it
10
+ * depends on, so neither direction leaks.
11
+ * 3. **It must work with no toolchain**, like everything else here — no CSS file, no framework,
12
+ * one import.
13
+ */
14
+
15
+ interface OverlayOptions {
16
+ /** Corner to pin to. Default `bottom-right`. */
17
+ corner?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
18
+ /** How often to repaint, in milliseconds. Default 400. */
19
+ interval?: number;
20
+ /** Churn rows to show before collapsing the rest into a count. Default 4. */
21
+ rows?: number;
22
+ }
23
+
24
+ /**
25
+ * @verajs/renderer — a ground-up, keyed, template-identity renderer.
26
+ *
27
+ * Replaces the Reef-derived renderer, which flattened every template to an HTML string and
28
+ * re-parsed it on each change — O(whole template) work for a one-row edit, measured at 85 ms for a
29
+ * two-row swap that lit-html does in 3.5 ms.
30
+ *
31
+ * The architecture here is the one that wins that benchmark:
32
+ *
33
+ * 1. A tagged template literal's `strings` array is frozen and IDENTICAL for every call from the
34
+ * same call site, so it is a cache key for the template's static shape. The shape is parsed
35
+ * ONCE into a `<template>` element with markers where the expressions go.
36
+ * 2. Rendering clones that template and binds "parts" to the marker positions. Every later render
37
+ * of the same shape only compares and commits the dynamic values — static content is never
38
+ * touched again.
39
+ * 3. Arrays reconcile KEYED (see `keyed()`), with head/tail fast paths and map-based moves, so a
40
+ * reorder moves nodes instead of rebuilding them.
41
+ *
42
+ * Built in, where lit-html requires directive imports: keyed list reconciliation (`keyed`),
43
+ * element refs (element-position expressions), toggled-DOM preservation (`hold`), and a
44
+ * whole-range fast clear — one `textContent = ''` where lit removes thousands of nodes one at a
45
+ * time. Like-for-like (lit-html + repeat + ref + cache: 5 021 B gzip), this file is ~28% smaller.
46
+ *
47
+ * What it deliberately does NOT have, which is why it is smaller than lit-html: no directive
48
+ * protocol, no `noChange`/`nothing` sentinels (in a single-expression attribute, `null`/`undefined`
49
+ * REMOVE the attribute; in a child, they clear it), no sanitizer indirection, no async parts, no
50
+ * dev-mode branches.
51
+ *
52
+ * Known limits, deliberate and shared with lit-html's envelope: no bindings inside comments (the
53
+ * value is consumed and ignored), no dynamic tag names, and nested `<template>` elements' contents
54
+ * are not traversed.
55
+ *
56
+ * CONTRACTS THE SPEED PAYS FOR — these are the trade, documented rather than discovered:
57
+ *
58
+ * - **The renderer owns its container below the mount point.** The whole-range fast clear wipes
59
+ * everything in a parent the part fully owns, including nodes user code appended there by hand
60
+ * (lit-html would preserve them). Same contract as mounting Vue or React into a container.
61
+ * - **Do not call `Node.normalize()` on rendered content.** Child anchors are text nodes, and
62
+ * normalize merges adjacent text — lit-html's comment anchors are immune to this; ours are not.
63
+ * - **A plain string renders as text, never as HTML.** The Reef renderer parsed strings as markup;
64
+ * this one has no innerHTML sink at all (an XSS class removed). The deliberate escape hatch for
65
+ * trusted markup is a property binding: `.innerHTML=${trusted}`.
66
+ * - **Hydration is automatic and markerless.** The first render into a container that already has
67
+ * children adopts them as server output of the same template (statics matched byte-for-byte,
68
+ * anchors installed by splitting live text at known value positions), falling back to a clean
69
+ * render on any mismatch. Requires the initial client render to match server state — same
70
+ * contract as React/Vue hydration.
71
+ * - **No directive protocol.** The template language itself is closed to extension — Vera extends
72
+ * at the framework layer (inserts) and through element refs, not inside the renderer's value
73
+ * handling.
74
+ * - Event handlers are invoked with `this` bound to the ELEMENT (lit binds its host).
75
+ *
76
+ * NAMING NOTE: internal class fields and methods are `_`-prefixed because the production build
77
+ * mangles properties matching /^_[a-z]/ (see defaultRollupConfig). That is what lets this file use
78
+ * full descriptive names while still shipping one-letter properties — locals and top-level names
79
+ * are mangled by default anyway, but property names are not. `_$litType$` and `handleEvent`
80
+ * deliberately do not match the pattern: the first is an interop wire format, the second is called
81
+ * by the DOM itself.
82
+ */
83
+ type TemplateResult = {
84
+ /** 1 = html, 2 = svg, 3 = mathml — the markers core's built-in tags produce. */
85
+ _$litType$?: number;
86
+ strings: TemplateStringsArray;
87
+ values: unknown[];
88
+ /** Set by `keyed()`; drives keyed list reconciliation. */
89
+ key?: unknown;
90
+ };
91
+ /**
92
+ * Marks a template result with a stable key so list reconciliation moves it instead of rewriting
93
+ * it. Key all items in a list or none — mixing is undefined behaviour, as are duplicate keys.
94
+ *
95
+ * ```js
96
+ * rows.map((r) => keyed(r.id, html`<tr>...</tr>`))
97
+ * ```
98
+ */
99
+ declare const keyed: <T>(key: unknown, result: T) => T;
100
+ /**
101
+ * Preserves the DOM of templates a child position toggles away from, instead of destroying it —
102
+ * form values, scroll positions and media playback survive the round trip (lit-html calls this
103
+ * `cache`). Stashed DOM is parked in its instance's own fragment and re-adopted on return.
104
+ *
105
+ * ```js
106
+ * html`<div>${hold(editing ? editor() : viewer())}</div>`
107
+ * ```
108
+ */
109
+ declare const hold: (result: TemplateResult) => {
110
+ $h: TemplateResult;
111
+ };
112
+ /**
113
+ * Renders a template result into a container. Slots into Vera via `setRenderer(render)`; core's
114
+ * built-in `html` tag already produces the accepted shape, so no `setHtml` call is required —
115
+ * though lit-html's `html` also works, its results being structurally identical.
116
+ *
117
+ * HYDRATION lives in `@verajs/renderer/hydrate` — a drop-in superset entry whose `render` adopts
118
+ * existing server-rendered children on first render. SSR apps import from there instead of here;
119
+ * this entry carries zero hydration code.
120
+ */
121
+ declare const render: (result: unknown, container: Node) => void;
122
+
123
+ /** One template identity replacing another at the same position, and how often. */
124
+ interface Churn {
125
+ /** The template that was torn down, rendered readably. */
126
+ from: string;
127
+ /** The template that replaced it. */
128
+ to: string;
129
+ /** How many times this exact swap happened while profiling. */
130
+ count: number;
131
+ /** Where in the DOM it happened, e.g. `main#app > ul.list`. First occurrence only. */
132
+ where: string;
133
+ }
134
+ interface ProfileReport {
135
+ /** Completed top-level `render()` calls. Nested renders are folded into their outermost frame. */
136
+ frames: number;
137
+ /** Total milliseconds spent inside `render()`. */
138
+ ms: number;
139
+ /** The slowest single frame, in milliseconds. */
140
+ slowestFrameMs: number;
141
+ /** Templates committed in place — the good path. */
142
+ updates: number;
143
+ /** Templates rendered into a slot that held nothing. Unavoidable and not a problem. */
144
+ creates: number;
145
+ /** Templates that replaced a *different* template — a teardown, not an update. */
146
+ rebuilds: number;
147
+ /** Rebuilds grouped by template pair, worst first. */
148
+ churn: Churn[];
149
+ }
150
+ /** Begin collecting. Calling this while already profiling restarts the collection. */
151
+ declare const startProfiling: () => void;
152
+ /** What has been measured so far, without ending the session. Drives the live overlay. */
153
+ declare const getReport: () => ProfileReport;
154
+ /** Stop collecting and return what was measured. Safe to call when not profiling. */
155
+ declare const stopProfiling: () => ProfileReport;
156
+ declare const isProfiling: () => boolean;
157
+ /** Profile one synchronous stretch of work. */
158
+ declare const profile: <T>(fn: () => T) => {
159
+ result: T;
160
+ report: ProfileReport;
161
+ };
162
+ /**
163
+ * Mounts a live panel in the corner of the page and starts profiling. Returns a function that
164
+ * removes it and stops. Plain DOM in a closed shadow root — it never renders itself through the
165
+ * renderer, which would fold its own commits into the numbers it reports.
166
+ */
167
+ declare const showProfiler: (options?: OverlayOptions) => (() => void);
168
+ /** Human-readable summary. The overlay renders the same data; this is for a console or a log. */
169
+ declare const formatReport: (report: ProfileReport) => string;
170
+
171
+ export { formatReport, getReport, hold, isProfiling, keyed, profile, render, showProfiler, startProfiling, stopProfiling };
172
+ export type { Churn, OverlayOptions, ProfileReport, TemplateResult };
173
+ //# sourceMappingURL=vera-renderer-profiler.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"vera-renderer-profiler.d.ts","sources":["../../../../../../src/overlay.ts","../../../../../../src/renderer.ts","../../../../../../src/profiler.ts"],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;ACxBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DG;AAWH,KAAA,cAAA;;;;;;;AAOG;AACH;AACG;AACD;AACF;AAEA;;;;;;;;AAQG;AACH;AAEA;;;AAGG;AACH,kBAAe,WAAc,cAAc;AAC3C,QAAA,cAAA;AACA;;;;;;AA2IU;;AAGA;;oBAED,+BAAA,IAAA;;;;;;;;;;;;;;;;;;;;;;;;;;ACvNN;AACH,WACE,KAAA;AAQF;AAKA;AAgCA,cAAa,cAAM;AACnB;AACA,cAAc,SAAE,QAAA,aAAA;AAChB;AACA,cAAY,aAAK,QAAA,aAAA;AACjB,cAAc,WAAE;AAChB;AACA,cAAc,OAAA;AACd;AACA,YAAY,aAAyB;AAErC;AACA;AACA;AACA;;;AAEwB,cAAI,YAAc,aAAa,cAAG;AACxD;AACF,cAAE,YAAA,WAAA,aAAA;;;;","names":[]}