@verajs/ssr 0.2.1 → 0.3.1

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 +522 -390
  2. package/dist/vera/diagnostics.d.ts +20 -0
  3. package/dist/vera/diagnostics.js +102 -0
  4. package/dist/vera/escaping.d.ts +155 -0
  5. package/dist/vera/escaping.js +293 -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 +389 -302
  13. package/dist/vera/nodes.js +2339 -0
  14. package/dist/vera/parse.d.ts +53 -0
  15. package/dist/vera/parse.js +485 -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 +1521 -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 +553 -0
  36. package/dist/vera/types.d.ts +121 -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 -1187
  44. package/src/vera/nodes.js +0 -2294
  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 -1080
  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
package/src/vera/parse.js DELETED
@@ -1,381 +0,0 @@
1
- /**
2
- * A conservative HTML fragment parser, for giving markup a node view.
3
- *
4
- * **This exists to answer `querySelector`, not to render.** Markup assigned as a string used to have
5
- * no nodes at all, so `children` was empty and every query answered `null` while the content sat
6
- * plainly in the output. Parsing it is what closes that.
7
- *
8
- * Three rules shape everything here:
9
- *
10
- * 1. **Never change what the page renders.** Each element keeps the exact source text of its own
11
- * tags, so re-serialising a parsed tree reproduces the input byte for byte — quoting style,
12
- * entity spelling, attribute order and interior whitespace included. Only an element somebody
13
- * *mutates* falls back to canonical output, which is the same rule the rest of this DOM follows.
14
- * The caller re-serialises and compares anyway (`nodes.js`), so a defect here costs a declined
15
- * parse rather than a corrupted page.
16
- * 2. **Decline rather than guess.** Anything needing the HTML spec's error recovery — misnested
17
- * formatting, foster parenting, foreign content — returns `null` and the markup stays a string.
18
- * A wrong tree is far worse than no tree: it would answer a query confidently and be wrong.
19
- * 3. **Never disagree with a real parser.** `tests/ssr-parse-differential.test.mjs` runs a corpus
20
- * through both this and parse5 and fails on any input where the two produce *different* trees.
21
- * Declining is allowed; disagreeing is not. parse5 is a devDependency and stays one — it is the
22
- * oracle, never a runtime dependency.
23
- */
24
- import { RAW_TEXT_ELEMENTS, VOID_ELEMENTS } from './escaping.js';
25
-
26
- /** The entity spellings this package emits, plus the handful every document uses. */
27
- const NAMED = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
28
- const ENTITY = /&(?:#(\d+)|#[xX]([0-9a-fA-F]+)|([a-zA-Z]+));/g;
29
-
30
- /**
31
- * **Character references, decoded — owned here and shared.** Decimal, hex and the named refs this
32
- * package can emit. `index.js` kept a lesser copy (decimal only, and `String.fromCharCode`, which
33
- * TRUNCATES above U+FFFF) that was safe only while `escapeHtml`'s table stayed decimal and BMP —
34
- * an invariant no test held. One decoder instead, so a change to what this package escapes cannot
35
- * silently outrun what it can decode (arc-2 run 3).
36
- */
37
- export const decode = (text) =>
38
- text.includes('&')
39
- ? text.replace(ENTITY, (match, decimal, hex, name) =>
40
- decimal
41
- ? String.fromCodePoint(Number(decimal))
42
- : hex
43
- ? String.fromCodePoint(parseInt(hex, 16))
44
- : (NAMED[name] ?? match)
45
- )
46
- : text;
47
-
48
- /**
49
- * **Implied end tags.** A start tag in the value set closes an open element of the key's name — the
50
- * rule that makes `<li>a<li>b` two siblings rather than a nest. This is the part of the spec that
51
- * well-formed markup actually depends on; everything past it is error recovery.
52
- */
53
- const CLOSED_BY = {
54
- li: new Set(['li']),
55
- dt: new Set(['dt', 'dd']),
56
- dd: new Set(['dt', 'dd']),
57
- option: new Set(['option', 'optgroup']),
58
- optgroup: new Set(['optgroup']),
59
- td: new Set(['td', 'th']),
60
- th: new Set(['td', 'th']),
61
- tr: new Set(['tr', 'td', 'th']),
62
- thead: new Set(['tbody', 'tfoot']),
63
- tbody: new Set(['tbody', 'tfoot']),
64
- tfoot: new Set(['tbody']),
65
- rt: new Set(['rt', 'rp']),
66
- rp: new Set(['rt', 'rp']),
67
- };
68
-
69
- /**
70
- * Elements whose end tag the spec makes optional, so finding one still open at the end of a fragment
71
- * is well-formed markup rather than error recovery. `<ul><li>a<li>b</ul>` and a trailing `<p>text`
72
- * are both ordinary hand-written HTML and both end with something open.
73
- */
74
- const OPTIONAL_END_TAG = new Set([
75
- 'p', 'li', 'dt', 'dd', 'option', 'optgroup', 'thead', 'tbody', 'tfoot', 'tr', 'td', 'th', 'rt', 'rp',
76
- ]);
77
-
78
- /** A `<p>` is closed by any of these opening, which is the one implied-end rule with a long list. */
79
- const CLOSES_P = new Set([
80
- 'address', 'article', 'aside', 'blockquote', 'details', 'div', 'dl', 'fieldset', 'figcaption',
81
- 'figure', 'footer', 'form', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'hgroup', 'hr', 'main',
82
- 'menu', 'nav', 'ol', 'p', 'pre', 'section', 'table', 'ul',
83
- ]);
84
-
85
- /** Nothing is refused outright any more — see `OPAQUE` for what `<template>` does instead. */
86
- const REFUSED = new Set();
87
-
88
- /**
89
- * **Foreign content is kept whole.** `svg` and `math` switch the spec into rules this parser does
90
- * not implement — self-closing tags mean something different, names stay case-sensitive, and
91
- * attributes are adjusted (`viewBox`, not `viewbox`). Guessing at the interior would produce a tree
92
- * a real parser disagrees with.
93
- *
94
- * So the element itself is modelled and its **content is kept as one opaque chunk**: the surrounding
95
- * markup parses normally, the icon is an element you can find and style, and nothing inside it is
96
- * claimed. Refusing the whole fragment instead — which is what this used to do — meant a card with
97
- * an icon in it got no node view at all, which is a great deal to give up for one `<svg>`.
98
- */
99
- const FOREIGN = new Set(['svg', 'math']);
100
-
101
- /**
102
- * **`<template>` is kept opaque too, for the same reason and by the same mechanism.**
103
- *
104
- * Its content is a separate document fragment, which this DOM does not model — so the parse used to
105
- * REFUSE any markup containing one. That is the heavier version of the mistake the `<svg>` comment
106
- * above describes: declining the whole fragment meant a component with a `<template>` anywhere in
107
- * its markup got no node view at all, so every `querySelector` on it answered emptily. Measured
108
- * against a real DOM, one empty `<template>` was enough to turn `querySelectorAll('*')` from three
109
- * elements into none — silently.
110
- *
111
- * That cost real behaviour. `@verajs/renderer/slots` finds a component's `<slot>` positions with a
112
- * query, so a light-DOM component whose markup held a `<template>` distributed on the client and
113
- * not on the server: a server/client divergence, from markup nobody would suspect.
114
- *
115
- * Keeping the interior opaque is also the honest answer rather than merely the convenient one. A
116
- * real DOM does not match template content from the host either — `host.querySelector('b')` never
117
- * finds a `<b>` inside a `<template>` — so on the question this parser exists to answer, an opaque
118
- * chunk and a content fragment agree. What is given up is reaching INTO one (`template.content
119
- * .querySelector`), which is a far smaller loss than the whole tree.
120
- */
121
- const OPAQUE = new Set([...FOREIGN, 'template']);
122
-
123
- const TAG_NAME = /^[a-zA-Z][^\s/>]*/;
124
- /**
125
- * **The attribute-name charset, owned here and shared.** Everything a start tag can carry as a
126
- * name: anything that is not whitespace, `/`, `>`, `=`, a quote, or `<`. Deliberately WIDE — every
127
- * real engine accepts `a.b`, `a(b)`, `a|b` and `a?b` (recorded in the repo's conventions), so a
128
- * narrower charset does not reject those names, it MIS-PARSES them.
129
- *
130
- * Exported because `index.js` scans the same grammar when it rebuilds a nested component from the
131
- * open tag this module wrote. It kept its own `[\w:-]+` copy, which split `data-a.b="v"` into
132
- * `data-a=""` and `b="v"` — the child then read the wrong attributes, server-side only (arc-2
133
- * run 2). Same fact, two spellings, one of them wrong: CODE-PRINCIPLES #5, and the same fix
134
- * `RAW_TEXT_ELEMENTS` already got in this package.
135
- */
136
- export const ATTRIBUTE_NAME = "[^\\s/>=\"'<]+";
137
- const ATTRIBUTE = new RegExp(`^(${ATTRIBUTE_NAME})(?:\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]*)))?`);
138
-
139
- /**
140
- * Parse a fragment into entries — elements and raw text.
141
- *
142
- * @param {string} markup
143
- * @param {{element: (name: string) => any, text: (data: string) => any, comment: (data: string) => any}} create
144
- * node factories; the caller owns node identity, so this file never imports the DOM it builds
145
- * @returns {Array<any> | null} entries, or `null` when the markup needs more than this will guess at
146
- */
147
- export const parseFragment = (markup, create) => {
148
- if (typeof markup !== 'string' || markup === '') return null;
149
-
150
- const root = { children: /** @type {Array<any>} */ ([]), localName: '#root' };
151
- /** @type {Array<any>} */
152
- const stack = [root];
153
- const open = () => stack[stack.length - 1];
154
- let index = 0;
155
- let text = '';
156
-
157
- /**
158
- * A text run becomes a node carrying **both** its decoded value and the bytes it came from — the
159
- * value is what `textContent` should answer, and the bytes are what re-serialising has to write
160
- * back. Keeping only the bytes made `textContent` return `a &amp; b`; keeping only the value
161
- * would have rewritten the page as `a &#38; b`.
162
- */
163
- const flushText = () => {
164
- if (text !== '') {
165
- const node = create.text(decode(text));
166
- node._source = text;
167
- open().children.push(node);
168
- }
169
- text = '';
170
- };
171
-
172
- while (index < markup.length) {
173
- const next = markup.indexOf('<', index);
174
- if (next === -1) {
175
- text += markup.slice(index);
176
- break;
177
- }
178
- text += markup.slice(index, next);
179
-
180
- /** A comment or a doctype is content this DOM has no node for; keep the bytes and move on. */
181
- if (markup.startsWith('<!--', next)) {
182
- const end = markup.indexOf('-->', next + 4);
183
- if (end === -1) return null;
184
- flushText();
185
- const node = create.comment(markup.slice(next + 4, end));
186
- node._source = markup.slice(next, end + 3);
187
- open().children.push(node);
188
- index = end + 3;
189
- continue;
190
- }
191
- if (markup.startsWith('<!', next)) {
192
- const end = markup.indexOf('>', next);
193
- if (end === -1) return null;
194
- text += markup.slice(next, end + 1);
195
- index = end + 1;
196
- continue;
197
- }
198
-
199
- /* ── an end tag ──────────────────────────────────────────────────────────────────────────── */
200
- if (markup.startsWith('</', next)) {
201
- const end = markup.indexOf('>', next);
202
- if (end === -1) return null;
203
- const name = markup.slice(next + 2, end).trim().toLowerCase();
204
- if (!name) return null;
205
- flushText();
206
- /** Close through anything the spec would have closed implicitly; anything else is recovery. */
207
- let depth = stack.length - 1;
208
- while (depth > 0 && stack[depth].localName !== name) {
209
- if (!CLOSED_BY[stack[depth].localName] && stack[depth].localName !== 'p') return null;
210
- depth--;
211
- }
212
- if (depth === 0) return null;
213
- stack[depth].closeTag = markup.slice(next, end + 1);
214
- stack.length = depth;
215
- index = end + 1;
216
- continue;
217
- }
218
-
219
- /* ── a start tag ─────────────────────────────────────────────────────────────────────────── */
220
- const nameMatch = TAG_NAME.exec(markup.slice(next + 1));
221
- if (!nameMatch) {
222
- /** A bare `<` that is not a tag is text in the spec, and text is all it can be here. */
223
- text += '<';
224
- index = next + 1;
225
- continue;
226
- }
227
- const name = nameMatch[0].toLowerCase();
228
- if (REFUSED.has(name)) return null;
229
-
230
- let cursor = next + 1 + nameMatch[0].length;
231
- /** @type {Array<[string, string]>} */
232
- const attributes = [];
233
- for (;;) {
234
- const rest = markup.slice(cursor);
235
- const space = /^\s+/.exec(rest);
236
- if (space) {
237
- cursor += space[0].length;
238
- continue;
239
- }
240
- if (markup.startsWith('/>', cursor) || markup[cursor] === '>') break;
241
- const attribute = ATTRIBUTE.exec(markup.slice(cursor));
242
- if (!attribute || cursor >= markup.length) return null;
243
- const value = attribute[2] ?? attribute[3] ?? attribute[4] ?? '';
244
- attributes.push([attribute[1].toLowerCase(), decode(value)]);
245
- cursor += attribute[0].length;
246
- }
247
- const selfClosing = markup.startsWith('/>', cursor);
248
- const end = markup.indexOf('>', cursor);
249
- if (end === -1) return null;
250
- const openTag = markup.slice(next, end + 1);
251
-
252
- flushText();
253
- /** The implied end tags, before this element joins the stack. */
254
- for (;;) {
255
- const current = open().localName;
256
- const closes = CLOSED_BY[name]?.has(current) || (current === 'p' && CLOSES_P.has(name));
257
- if (!closes || stack.length === 1) break;
258
- stack.pop();
259
- }
260
-
261
- /**
262
- * **A row directly inside `<table>` is declined.** The spec inserts an implied `<tbody>` there,
263
- * and this parser cannot both reproduce the input byte for byte (which forbids inventing that
264
- * tag) and agree with a real parser about the tree (which requires it). Markup that writes the
265
- * section itself parses normally, so the common explicit form is unaffected.
266
- */
267
- if ((name === 'tr' || name === 'td' || name === 'th') && open().localName === 'table') return null;
268
-
269
- /**
270
- * **A name the DOM rejects is a DECLINE, never a throw.** `TAG_NAME` is deliberately loose
271
- * (`[a-zA-Z][^\s/>]*`) so recovery can see odd names, but that lets a malformed start tag
272
- * like `<p<div>` yield the name `p<div`, which `createElement` refuses with a DOMException —
273
- * and an uncaught throw here takes the whole server render down, naming createElement rather
274
- * than the component. This file's contract is "match a real parser or decline (return null)";
275
- * a throw is neither. So a rejected name declines the fragment, landing on the same
276
- * "could not be parsed" path a stray close tag does. Found by the run-26 adversarial probe.
277
- */
278
- let element;
279
- try {
280
- element = create.element(name);
281
- } catch {
282
- return null;
283
- }
284
- for (const [attributeName, value] of attributes) element.setAttribute(attributeName, value);
285
- element._sourceOpenTag = openTag;
286
- /**
287
- * **`''` means "no end tag in the source", which is different from "not parsed".** `<li>a<li>b`
288
- * closes the first item implicitly and writing `</li>` back would add bytes the input never had
289
- * — the round-trip would fail and this whole parse would be discarded for markup that is
290
- * perfectly ordinary. An element built by `createElement` has no source close tag at all and
291
- * still gets the canonical one.
292
- */
293
- const node = { element, children: /** @type {Array<any>} */ ([]), localName: name, closeTag: '', foreign: false };
294
- open().children.push(node);
295
- index = end + 1;
296
-
297
- /** A void element never has children and never has an end tag. */
298
- if (VOID_ELEMENTS.has(name)) continue;
299
- /**
300
- * `<div/>` is **not** self-closing in HTML — the slash is ignored and the element stays open.
301
- * Treating it as closed is a common and quiet way to build the wrong tree, so it declines.
302
- */
303
- if (selfClosing) return null;
304
-
305
- /**
306
- * Foreign content runs to its matching end tag and is kept verbatim, nesting counted so an
307
- * `<svg>` inside an `<svg>` closes the right one.
308
- */
309
- if (OPAQUE.has(name)) {
310
- let depth = 1;
311
- let closeAt = -1;
312
- const opener = new RegExp(`<(/?)${name}\\b`, 'giu');
313
- opener.lastIndex = index;
314
- for (let found = opener.exec(markup); found; found = opener.exec(markup)) {
315
- depth += found[1] ? -1 : 1;
316
- if (depth === 0) {
317
- closeAt = found.index;
318
- break;
319
- }
320
- }
321
- if (closeAt === -1) return null;
322
- const closeEnd = markup.indexOf('>', closeAt);
323
- if (closeEnd === -1) return null;
324
- if (index !== closeAt) node.children.push(markup.slice(index, closeAt));
325
- node.closeTag = markup.slice(closeAt, closeEnd + 1);
326
- node.foreign = true;
327
- index = closeEnd + 1;
328
- continue;
329
- }
330
-
331
- /** Raw text runs to its own end tag and is never parsed as markup. */
332
- if (RAW_TEXT_ELEMENTS.has(name)) {
333
- const close = markup.toLowerCase().indexOf(`</${name}`, index);
334
- if (close === -1) return null;
335
- const closeEnd = markup.indexOf('>', close);
336
- if (closeEnd === -1) return null;
337
- /** Raw text is not markup and is never decoded — a `<script>` means its bytes exactly. */
338
- if (index !== close) {
339
- const raw = create.text(markup.slice(index, close));
340
- raw._source = markup.slice(index, close);
341
- node.children.push(raw);
342
- }
343
- node.closeTag = markup.slice(close, closeEnd + 1);
344
- index = closeEnd + 1;
345
- continue;
346
- }
347
- stack.push(node);
348
- }
349
- flushText();
350
- /**
351
- * What is still open at the end is fine if the spec would have closed it implicitly, and is error
352
- * recovery otherwise — an unclosed `<div>` is a mistake this parser will not guess about.
353
- */
354
- while (stack.length > 1 && OPTIONAL_END_TAG.has(open().localName)) stack.pop();
355
- if (stack.length !== 1) return null;
356
-
357
- /** Build the real nodes now that the shape is known to be sound. */
358
- const build = (node) => {
359
- for (const child of node.children) {
360
- if (typeof child === 'string' || typeof child.markup === 'function') {
361
- node.element._entries.push(child);
362
- if (typeof child !== 'string') child._parent = node.element;
363
- } else {
364
- build(child);
365
- /**
366
- * Pushed rather than appended: `appendChild` marks an unrendered registered component so
367
- * the scan can find that instance, which would write a marker attribute into markup this
368
- * parse must reproduce exactly — and would enrol a node nobody is going to render.
369
- */
370
- node.element._entries.push(child.element);
371
- child.element._parent = node.element;
372
- }
373
- }
374
- node.element._sourceCloseTag = node.closeTag;
375
- /** Marked so anything comparing this tree knows the interior is not modelled. */
376
- return node.element;
377
- };
378
- return root.children.map((child) =>
379
- typeof child === 'string' || typeof child.markup === 'function' ? child : build(child)
380
- );
381
- };