@verajs/ssr 0.2.0 → 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 (63) hide show
  1. package/README.md +510 -373
  2. package/dist/vera/diagnostics.d.ts +20 -0
  3. package/dist/vera/diagnostics.js +98 -0
  4. package/dist/vera/escaping.d.ts +142 -0
  5. package/dist/vera/escaping.js +267 -0
  6. package/dist/vera/events.d.ts +41 -0
  7. package/dist/vera/events.js +162 -0
  8. package/dist/vera/frames.d.ts +38 -0
  9. package/dist/vera/frames.js +195 -0
  10. package/dist/vera/index.d.ts +48 -0
  11. package/dist/vera/index.js +480 -0
  12. package/{types → dist/vera}/nodes.d.ts +397 -300
  13. package/dist/vera/nodes.js +2322 -0
  14. package/dist/vera/parse.d.ts +37 -0
  15. package/dist/vera/parse.js +390 -0
  16. package/dist/vera/reflections.d.ts +566 -0
  17. package/dist/vera/reflections.js +820 -0
  18. package/dist/vera/registry.d.ts +14 -0
  19. package/{src → dist}/vera/registry.js +5 -1
  20. package/dist/vera/report.d.ts +27 -0
  21. package/dist/vera/report.js +56 -0
  22. package/dist/vera/scan.d.ts +37 -0
  23. package/dist/vera/scan.js +143 -0
  24. package/dist/vera/select.d.ts +40 -0
  25. package/dist/vera/select.js +261 -0
  26. package/dist/vera/serializer.d.ts +39 -0
  27. package/dist/vera/serializer.js +1372 -0
  28. package/dist/vera/shim.d.ts +42 -0
  29. package/dist/vera/shim.js +853 -0
  30. package/dist/vera/slots.d.ts +5 -0
  31. package/dist/vera/slots.js +104 -0
  32. package/dist/vera/stylesheets.d.ts +62 -0
  33. package/dist/vera/stylesheets.js +180 -0
  34. package/dist/vera/tokenizer.d.ts +32 -0
  35. package/dist/vera/tokenizer.js +528 -0
  36. package/dist/vera/types.d.ts +117 -0
  37. package/dist/vera/views.d.ts +63 -0
  38. package/dist/vera/views.js +245 -0
  39. package/package.json +12 -13
  40. package/src/vera/escaping.js +0 -135
  41. package/src/vera/events.js +0 -164
  42. package/src/vera/frames.js +0 -102
  43. package/src/vera/index.js +0 -1171
  44. package/src/vera/nodes.js +0 -2270
  45. package/src/vera/parse.js +0 -381
  46. package/src/vera/reflections.js +0 -811
  47. package/src/vera/select.js +0 -234
  48. package/src/vera/serializer.js +0 -928
  49. package/src/vera/shim.js +0 -761
  50. package/src/vera/stylesheets.js +0 -155
  51. package/src/vera/views.js +0 -240
  52. package/types/escaping.d.ts +0 -27
  53. package/types/events.d.ts +0 -4
  54. package/types/frames.d.ts +0 -12
  55. package/types/index.d.ts +0 -13
  56. package/types/parse.d.ts +0 -19
  57. package/types/reflections.d.ts +0 -657
  58. package/types/registry.d.ts +0 -8
  59. package/types/select.d.ts +0 -5
  60. package/types/serializer.d.ts +0 -26
  61. package/types/shim.d.ts +0 -23
  62. package/types/stylesheets.d.ts +0 -53
  63. package/types/views.d.ts +0 -26
@@ -0,0 +1,5 @@
1
+ import type { ElementShim } from './nodes.js';
2
+ type Child = ElementShim['childNodes'][number];
3
+ /** Distributes `source` — the host's light children, held out of its render — into the host's rendered slots. */
4
+ export declare const distributeLight: (host: ElementShim, source: Child[]) => void;
5
+ export {};
@@ -0,0 +1,104 @@
1
+ /**
2
+ * **Light-DOM slots, distributed on the server** — while `@verajs/renderer/slots` is wired (its `'slot'` insert is the
3
+ * marker), once a light host's render is final. The browser module distributes in the browser; this writes the end state
4
+ * it leaves, plus the one thing the DOM alone cannot say, and hydration (`@verajs/renderer/hydration`) adopts it in place.
5
+ *
6
+ * Each filled slot is written exactly as the client leaves it: its region's two markers around the assigned content, the
7
+ * `<slot>` stepped out; an unfilled slot stays, showing its fallback. The markers keep text from merging across a
8
+ * range's edge; INSIDE a range (or the carrier) two text light children written side by side would merge in the
9
+ * browser's parser — `<b slot="h">H1</b>t1<b slot="h">H2</b>t2` puts `t1t2` in the default range, one node where the
10
+ * statement counts two — so an empty comment goes between them (`separate`). Hydration needs no rule for it: a range's
11
+ * comments are never light content.
12
+ *
13
+ * What the DOM alone cannot say is written once, on the host: `data-vm-light`, `FORMAT:runs` — for each light child in
14
+ * light-tree order, the index of the range it went into (ranges numbered in document order, the unassigned carrier
15
+ * last), run-length encoded as `index*count`. Distribution loses which nodes are light children at all (a component's own
16
+ * elements can carry `slot` too) and their order ACROSS slots; this is both. `FORMAT` bumps only when the format changes,
17
+ * and hydration renders such a host fresh, with the fix, when it meets another number.
18
+ *
19
+ * **Deliberate twins** of the browser side's names — the markers and the carrier are slots', the attribute and the
20
+ * number hydration's. ssr does not import the renderer at runtime, so they are copied, not shared;
21
+ * `tests/slots-ssr-client-parity.test.mjs` fails if the two sides ever disagree.
22
+ */
23
+ import { CommentShim, createElement, slotName } from './nodes.js';
24
+ const FORMAT = '1';
25
+ const RANGE_START = '[';
26
+ const RANGE_END = ']';
27
+ const UNASSIGNED = 'data-vm-unassigned';
28
+ const LIGHT_ATTR = 'data-vm-light';
29
+ /** Inserts `node` before `ref`, after an empty comment if the node before it there is text too — or they would merge. */
30
+ const separate = (parent, node, ref) => {
31
+ if (node.nodeType === 3 && (ref === null ? parent.lastChild : ref.previousSibling)?.nodeType === 3)
32
+ parent.insertBefore(new CommentShim(''), ref);
33
+ parent.insertBefore(node, ref);
34
+ };
35
+ /** Distributes `source` — the host's light children, held out of its render — into the host's rendered slots. */
36
+ export const distributeLight = (host, source) => {
37
+ const buckets = new Map();
38
+ const light = [];
39
+ for (const node of source) {
40
+ const name = slotName(node);
41
+ if (name === null)
42
+ continue;
43
+ light.push(node);
44
+ let bucket = buckets.get(name);
45
+ if (bucket === undefined)
46
+ buckets.set(name, (bucket = []));
47
+ bucket.push(node);
48
+ node.parentNode?.removeChild(node);
49
+ }
50
+ const filled = new Set();
51
+ /** How many ranges received content, numbered in document order — see `data-vm-light`. */
52
+ let ranges = 0;
53
+ const rangeOf = new Map();
54
+ /** Collected first: the live list mutates as slots are unwrapped. */
55
+ for (const slot of [...host.querySelectorAll('slot')]) {
56
+ const parent = slot.parentNode;
57
+ if (parent === null)
58
+ continue; // already unwrapped as another slot's assigned content
59
+ const name = slot.getAttribute('name') ?? '';
60
+ const assigned = !filled.has(name) ? buckets.get(name) : undefined;
61
+ if (assigned !== undefined && assigned.length > 0) {
62
+ filled.add(name);
63
+ /** The client's own region, exactly: its two markers around the content, the slot stepped out. */
64
+ parent.insertBefore(new CommentShim(RANGE_START), slot);
65
+ for (const node of assigned) {
66
+ separate(parent, node, slot);
67
+ rangeOf.set(node, ranges);
68
+ }
69
+ ranges++;
70
+ parent.insertBefore(new CommentShim(RANGE_END), slot);
71
+ parent.removeChild(slot);
72
+ }
73
+ /** A slot with nothing assigned STAYS, showing its fallback — as the client keeps it (Brian, 2026-10-02). */
74
+ }
75
+ /**
76
+ * **Whatever no slot claimed is PRESERVED, in the client's own container** — `<ins hidden data-vm-unassigned>`, the
77
+ * host's first child, in light-tree order, exactly where the client keeps it: present and connected, unrendered, as
78
+ * native leaves an unassigned light child. It is the last range of the statement.
79
+ */
80
+ let carrier = null;
81
+ for (const node of light)
82
+ if (!rangeOf.has(node)) {
83
+ if (carrier === null) {
84
+ carrier = createElement('ins');
85
+ carrier.setAttribute('hidden', '');
86
+ carrier.setAttribute(UNASSIGNED, '');
87
+ }
88
+ separate(carrier, node, null);
89
+ rangeOf.set(node, ranges);
90
+ }
91
+ if (carrier !== null)
92
+ host.insertBefore(carrier, host.firstChild);
93
+ /** The light order, run-length encoded — written on every light host, empty after the number when it has none. */
94
+ const runs = [];
95
+ for (let k = 0; k < light.length;) {
96
+ const index = rangeOf.get(light[k]);
97
+ let n = 1;
98
+ while (k + n < light.length && rangeOf.get(light[k + n]) === index)
99
+ n++;
100
+ runs.push(n === 1 ? `${index}` : `${index}*${n}`);
101
+ k += n;
102
+ }
103
+ host.setAttribute(LIGHT_ATTR, `${FORMAT}:${runs.join(',')}`);
104
+ };
@@ -0,0 +1,62 @@
1
+ /**
2
+ * Light-DOM `@scope` styles hoisted during renders, **keyed by the component that hoisted them**, so a
3
+ * render returns only the CSS of the page it built — a flat list returned every style the process had
4
+ * ever hoisted, request one's CSS in request two's response.
5
+ */
6
+ export declare const hoistedStyles: Map<string, string[]>;
7
+ export declare const setRenderingTag: (tag: string) => string;
8
+ /** The component rendering right now — the key a warning is said once per. */
9
+ export declare const currentRenderingTag: () => string;
10
+ export declare const beginHoisting: () => void;
11
+ export declare class StyleSheetShim {
12
+ cssText: string;
13
+ constructor();
14
+ /**
15
+ * **`cssText` is always a string**, because the platform's argument is a `USVString` and it
16
+ * parses what it is given. Assigning the caller's value straight through left a number, an array
17
+ * or a plain object sitting on `cssText`, which then reached the `<style>` block by concatenation
18
+ * — so the wrong text appeared a long way from the call that caused it. Template coercion also
19
+ * refuses a symbol with a `TypeError`, which is what every engine does
20
+ * (`tests/browser/dom-string-coercion.test.js`).
21
+ */
22
+ replaceSync(cssText: unknown): void;
23
+ /** The async spelling of the same thing; `adoptStyles` uses `replaceSync`, a component may not. */
24
+ replace(cssText: unknown): Promise<this>;
25
+ insertRule(rule: string): number;
26
+ /**
27
+ * There is no rule *list* — this holds the stylesheet as text, which is all the markup needs —
28
+ * so a rule cannot be addressed by index. Deleting one is refused rather than silently ignored.
29
+ */
30
+ deleteRule(): never;
31
+ /** The pre-standard spellings, which are still what some libraries reach for. */
32
+ addRule(selector: string, style?: string): number;
33
+ removeRule(): void;
34
+ get cssRules(): never[];
35
+ get rules(): never[];
36
+ get ownerRule(): null;
37
+ get ownerNode(): null;
38
+ get parentStyleSheet(): null;
39
+ get href(): null;
40
+ get title(): null;
41
+ get media(): never[];
42
+ get type(): string;
43
+ disabled: boolean;
44
+ }
45
+ /**
46
+ * Records a hoisted sheet against the component mid-render. A tag already established by an earlier
47
+ * render keeps what it had — and if the new CSS DIFFERS, that is said once: CSS that varies per request
48
+ * (a theme, a prop) cannot be hoisted per class, and dropping the variation silently served every later
49
+ * request the first request's styles.
50
+ */
51
+ export declare const hoist: (cssText: string) => void;
52
+ /** What a read of `document.adoptedStyleSheets` answers: the list itself, with indexed writes checked and hoisted. */
53
+ export declare const documentAdoptedSheets: StyleSheetShim[];
54
+ /**
55
+ * **What `adoptedStyleSheets` accepts, on the document and a shadow root alike: any iterable OBJECT of
56
+ * `CSSStyleSheet`s** — WebIDL's sequence conversion, which every engine applies
57
+ * (`tests/browser/adopted-sheets-sequence.test.js`): an array, a `Set` and a generator are accepted; an array-like,
58
+ * a lone sheet, a string and a non-sheet entry are a `TypeError`. Accepting only an array refused working client code.
59
+ */
60
+ export declare const toSheetSequence: (sheets: unknown) => StyleSheetShim[];
61
+ /** What an assignment to `document.adoptedStyleSheets` does. */
62
+ export declare const setDocumentAdoptedSheets: (sheets: unknown) => void;
@@ -0,0 +1,180 @@
1
+ /**
2
+ * `CSSStyleSheet`, and the styles a render hoists out of the components it touched.
3
+ *
4
+ * The `StyleSheetShim` class is the DOM half — audited in place. The hoisting half (which component a
5
+ * sheet belongs to, per request) is SSR orchestration, rebuilt from this floor.
6
+ */
7
+ import { PROSE } from './diagnostics.js';
8
+ import { once, own, ssrMisuse, ssrWarning } from './report.js';
9
+ /**
10
+ * Light-DOM `@scope` styles hoisted during renders, **keyed by the component that hoisted them**, so a
11
+ * render returns only the CSS of the page it built — a flat list returned every style the process had
12
+ * ever hoisted, request one's CSS in request two's response.
13
+ */
14
+ export const hoistedStyles = new Map();
15
+ /** The component rendering right now, so a hoist can be attributed to it (renders take turns). */
16
+ let renderingTag = '';
17
+ export const setRenderingTag = (tag) => {
18
+ const previous = renderingTag;
19
+ renderingTag = tag;
20
+ return previous;
21
+ };
22
+ /** The component rendering right now — the key a warning is said once per. */
23
+ export const currentRenderingTag = () => renderingTag;
24
+ /**
25
+ * The tags that hoisted during the render in progress. `@verajs/styles` hoists once per class, so a tag
26
+ * whose sheets were recorded by an earlier request keeps them — but a component that appends its own
27
+ * `<style>` every render has no such guard, and without a per-render rule its sheets accumulated per
28
+ * PROCESS, request thirty shipping twenty-nine requests of other people's CSS.
29
+ */
30
+ const hoistedThisRender = new Set();
31
+ export const beginHoisting = () => {
32
+ hoistedThisRender.clear();
33
+ /** Each render is its own page, and a page starts with no adopted sheets — which also bounds the list. */
34
+ documentSheets.length = 0;
35
+ };
36
+ export class StyleSheetShim {
37
+ constructor() {
38
+ this.cssText = '';
39
+ }
40
+ /**
41
+ * **`cssText` is always a string**, because the platform's argument is a `USVString` and it
42
+ * parses what it is given. Assigning the caller's value straight through left a number, an array
43
+ * or a plain object sitting on `cssText`, which then reached the `<style>` block by concatenation
44
+ * — so the wrong text appeared a long way from the call that caused it. Template coercion also
45
+ * refuses a symbol with a `TypeError`, which is what every engine does
46
+ * (`tests/browser/dom-string-coercion.test.js`).
47
+ */
48
+ replaceSync(cssText) {
49
+ this.cssText = `${cssText}`;
50
+ refill(this);
51
+ }
52
+ /** The async spelling of the same thing; `adoptStyles` uses `replaceSync`, a component may not. */
53
+ async replace(cssText) {
54
+ this.replaceSync(cssText);
55
+ return this;
56
+ }
57
+ insertRule(rule) {
58
+ this.cssText += rule;
59
+ refill(this);
60
+ return 0;
61
+ }
62
+ /**
63
+ * There is no rule *list* — this holds the stylesheet as text, which is all the markup needs —
64
+ * so a rule cannot be addressed by index. Deleting one is refused rather than silently ignored.
65
+ */
66
+ deleteRule() {
67
+ throw own(new Error(ssrMisuse('ssr-sheet-text', PROSE['ssr-sheet-text']())));
68
+ }
69
+ /** The pre-standard spellings, which are still what some libraries reach for. */
70
+ addRule(selector, style) {
71
+ this.insertRule(`${selector} { ${style ?? ''} }`);
72
+ return -1;
73
+ }
74
+ removeRule() {
75
+ this.deleteRule();
76
+ }
77
+ get cssRules() {
78
+ return [];
79
+ }
80
+ get rules() {
81
+ return this.cssRules;
82
+ }
83
+ get ownerRule() {
84
+ return null;
85
+ }
86
+ get ownerNode() {
87
+ return null;
88
+ }
89
+ get parentStyleSheet() {
90
+ return null;
91
+ }
92
+ get href() {
93
+ return null;
94
+ }
95
+ get title() {
96
+ return null;
97
+ }
98
+ get media() {
99
+ return [];
100
+ }
101
+ get type() {
102
+ return 'text/css';
103
+ }
104
+ disabled = false;
105
+ }
106
+ /**
107
+ * Records a hoisted sheet against the component mid-render. A tag already established by an earlier
108
+ * render keeps what it had — and if the new CSS DIFFERS, that is said once: CSS that varies per request
109
+ * (a theme, a prop) cannot be hoisted per class, and dropping the variation silently served every later
110
+ * request the first request's styles.
111
+ */
112
+ export const hoist = (cssText) => {
113
+ const sheets = hoistedStyles.get(renderingTag);
114
+ if (sheets && !hoistedThisRender.has(renderingTag)) {
115
+ /** Once per tag. */
116
+ if (!sheets.includes(cssText) && once('ssr-styles-vary', renderingTag))
117
+ console.warn(ssrWarning(`<${renderingTag}>`, 'ssr-styles-vary', PROSE['ssr-styles-vary']()));
118
+ return;
119
+ }
120
+ hoistedThisRender.add(renderingTag);
121
+ const list = sheets ?? [];
122
+ if (!list.includes(cssText))
123
+ list.push(cssText);
124
+ hoistedStyles.set(renderingTag, list);
125
+ };
126
+ /**
127
+ * **`document.adoptedStyleSheets`: a live list, and every sheet that joins it is hoisted.** It was an empty array
128
+ * on every read, and its setter hoisted only the LAST sheet assigned — right for `@verajs/styles`, which appends one
129
+ * at a time, and wrong for `document.adoptedStyleSheets = [a, b]`, which served `b` and dropped `a`. Now a write —
130
+ * assignment, or an indexed write such as `push`, which the platform allows on its observable array — hoists each sheet
131
+ * not already in the list, attributed to the component rendering, and a read answers what was adopted this render.
132
+ * Checked as the platform checks: a value that is not a sequence, or an entry that is not a `CSSStyleSheet`, is a
133
+ * `TypeError`, before anything changes.
134
+ */
135
+ const documentSheets = [];
136
+ /**
137
+ * **A sheet already adopted whose text changes is served with its new text** — construct, adopt, then fill is legal,
138
+ * and its CSS was silently dropped (a flash of unstyled content at hydration). The new text is hoisted after the old,
139
+ * so a rule it changed wins the cascade exactly as the browser applies it.
140
+ */
141
+ const refill = (sheet) => {
142
+ if (sheet.cssText && documentSheets.includes(sheet))
143
+ hoist(sheet.cssText);
144
+ };
145
+ const checkSheet = (sheet) => {
146
+ if (!(sheet instanceof StyleSheetShim))
147
+ throw new TypeError(`Failed to set the 'adoptedStyleSheets' property: the provided value is not of type 'CSSStyleSheet'.`);
148
+ return sheet;
149
+ };
150
+ const adopt = (sheet) => {
151
+ if (!documentSheets.includes(sheet) && sheet.cssText)
152
+ hoist(sheet.cssText);
153
+ };
154
+ /** What a read of `document.adoptedStyleSheets` answers: the list itself, with indexed writes checked and hoisted. */
155
+ export const documentAdoptedSheets = new Proxy(documentSheets, {
156
+ set(target, key, value) {
157
+ if (typeof key === 'string' && /^\d+$/.test(key))
158
+ adopt(checkSheet(value));
159
+ return Reflect.set(target, key, value);
160
+ },
161
+ });
162
+ /**
163
+ * **What `adoptedStyleSheets` accepts, on the document and a shadow root alike: any iterable OBJECT of
164
+ * `CSSStyleSheet`s** — WebIDL's sequence conversion, which every engine applies
165
+ * (`tests/browser/adopted-sheets-sequence.test.js`): an array, a `Set` and a generator are accepted; an array-like,
166
+ * a lone sheet, a string and a non-sheet entry are a `TypeError`. Accepting only an array refused working client code.
167
+ */
168
+ export const toSheetSequence = (sheets) => {
169
+ if (sheets === null || (typeof sheets !== 'object' && typeof sheets !== 'function') || typeof sheets[Symbol.iterator] !== 'function')
170
+ throw new TypeError(`Failed to set the 'adoptedStyleSheets' property: the provided value cannot be converted to a sequence.`);
171
+ return [...sheets].map(checkSheet);
172
+ };
173
+ /** What an assignment to `document.adoptedStyleSheets` does. */
174
+ export const setDocumentAdoptedSheets = (sheets) => {
175
+ const checked = toSheetSequence(sheets);
176
+ for (const sheet of checked)
177
+ adopt(sheet);
178
+ documentSheets.length = 0;
179
+ documentSheets.push(...checked);
180
+ };
@@ -0,0 +1,32 @@
1
+ /**
2
+ * **The server's one tag scanner** — the HTML tokenizer's own states, from a `<` to its tag's `>`, plus the tree-builder
3
+ * facts that change how the next character parses: raw text, comments, `<template>` content, foreign content and its
4
+ * HTML integration points. Every reader of markup on the server reads it through this: the template compiler
5
+ * (`serializer.ts` — where a hole is text, an attribute value or raw text), the `.innerHTML` inertness scan (`fortify`),
6
+ * and the component scanner (`scan.ts` — where a registered component tag is live). They each ran their own copy
7
+ * once, and every copy drifted from the tokenizer differently; one scanner cannot disagree with itself.
8
+ */
9
+ import type { ScanResult, ScanStart, ScanState, ScannedTag } from './types.js';
10
+ /**
11
+ * `edits`, when given, collects the positions `fortify` rewrites — a start tag's name end where it is `script`, and
12
+ * a `<template>` start tag's `shadowroot`/`shadowrootmode` attribute names. They are reported from THIS scan, so the
13
+ * `.innerHTML` scan and the template scan cannot disagree about what is a tag: they are one scan. `tags`, when given,
14
+ * collects the component scan's candidates the same way (see `ScannedTag` and `scan.ts`).
15
+ */
16
+ export declare const scanTag: (text: string, state: ScanState, edits?: number[], tags?: ScannedTag[]) => ScanResult;
17
+ /** The end-of-input closers a scan state owes: its open comment or raw-text or text-only element, then every element it opened that changes parsing (svg, math, noscript, template, an integration point), innermost first. Shared by `compile` and `fortify`. */
18
+ export declare const closersOf: (end: ScanState) => string;
19
+ /** A scan state at foreign depth `depth` and nothing else open — its own `opens`, since `scanTag` mutates it. */
20
+ export declare const freshScan: (depth: number) => ScanStart;
21
+ /**
22
+ * What the template compiler reads of this module besides the scan itself — exported as SEPARATE bindings. The scan
23
+ * reads its own constants on every character, and V8 reaches an exported module variable through a cell rather than
24
+ * the module's context: exporting these directly cost compile 4% and a 50 KB \`.innerHTML\` value 11%.
25
+ */
26
+ export declare const RAW_TEXT_TAGS: Set<string>;
27
+ export declare const TEXT_ONLY_TAGS: Set<string>;
28
+ export declare const PHASE_TAG_OPEN = 1;
29
+ export declare const PHASE_END_TAG_OPEN = 2;
30
+ export declare const PHASE_TAG_NAME = 3;
31
+ export declare const isTokenizerSpace: (c: string | undefined) => boolean;
32
+ export declare const INERT_EDIT = 0;