@verajs/ssr 0.1.4 → 0.2.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.
@@ -0,0 +1,748 @@
1
+ export function serializeElement(element: any): any;
2
+ export class TextShim extends CharacterDataShim {
3
+ get nodeType(): number;
4
+ get nodeName(): string;
5
+ get wholeText(): string;
6
+ markup(): string;
7
+ cloneNode(): TextShim;
8
+ /** Splits at `offset`, leaving this node with the first half and inserting the second after it. */
9
+ splitText(offset: any): TextShim;
10
+ }
11
+ export class CommentShim extends CharacterDataShim {
12
+ get nodeType(): number;
13
+ get nodeName(): string;
14
+ markup(): string;
15
+ cloneNode(): CommentShim;
16
+ }
17
+ export class ContainerShim extends EventTarget {
18
+ /**
19
+ * **Children are entries, not one string.** Each entry is either a retained node or a chunk of
20
+ * raw markup. Serialisation happens when `innerHTML` is *read*, not when a child is appended —
21
+ * appending used to serialise immediately and drop the node, so `appendChild(kid)` followed by
22
+ * `kid.textContent = 'x'` rendered `<b></b>` and lost the text with no diagnostic.
23
+ */
24
+ _entries: any[];
25
+ _parent: any;
26
+ /** A server-rendered node is in the document being built, so it is connected. */
27
+ isConnected: boolean;
28
+ /**
29
+ * Registered here rather than on the platform's `EventTarget`; see `events.js`.
30
+ * @override
31
+ */
32
+ override addEventListener(type: any, callback: any, options: any): void;
33
+ /** @override */
34
+ override removeEventListener(type: any, callback: any, options: any): void;
35
+ /** @override */
36
+ override dispatchEvent(event: any): boolean;
37
+ set innerHTML(markup: string);
38
+ get innerHTML(): string;
39
+ /** New markup has not been looked at yet, whatever was true of the markup it replaced. */
40
+ _parsed: boolean | undefined;
41
+ appendChild(node: any): any;
42
+ /**
43
+ * **Position a node among the children**, which needed a tree and now has one. `reference` of
44
+ * `null` appends, as the platform says, and a reference that is not a child is a `NotFoundError`
45
+ * rather than a silent append — the difference between "put it at the end" and "you asked about
46
+ * a node I do not have" is exactly the kind of thing a server should not paper over.
47
+ */
48
+ insertBefore(node: any, reference: any): any;
49
+ /**
50
+ * **`moveBefore` is `insertBefore` with a precondition**: the node must already have a parent.
51
+ * Measured on Chromium and Firefox, which agree on all of it (WebKit does not implement it yet):
52
+ * an unparented node is a `HierarchyRequestError`, and a *parented* node with a reference that is
53
+ * not a child here is a `NotFoundError` — a different error from the same call depending on which
54
+ * argument is wrong, and checked in that order.
55
+ *
56
+ * The point of the API in a browser is moving a node without tearing down its state. There is no
57
+ * state to preserve on a server, so this is a move; having it means code written for the browser
58
+ * runs here rather than hitting a missing method.
59
+ */
60
+ moveBefore(node: any, reference: any): any;
61
+ replaceChild(node: any, old: any): any;
62
+ /**
63
+ * **Where each node sits relative to another**, as the spec's bit field. Two nodes with no common
64
+ * root are `DISCONNECTED | IMPLEMENTATION_SPECIFIC` plus a direction the spec leaves to the
65
+ * implementation, so only the disconnected bit is worth comparing across implementations.
66
+ */
67
+ compareDocumentPosition(other: any): number;
68
+ /** Remove a node from this container's entries without touching its own parent pointer. */
69
+ _detach(node: any): void;
70
+ /**
71
+ * **Absent until nodes were retained**, so `host.removeChild(kid)` was a `TypeError` — there was
72
+ * nothing to remove, the child having been flattened into a string at append time.
73
+ */
74
+ removeChild(node: any): any;
75
+ /**
76
+ * What a node with no tree above or below it answers — shared, because an element and a shadow
77
+ * root answer these identically and two copies is how they came to disagree in the first place.
78
+ *
79
+ * Every one is the truthful answer rather than a placeholder: a detached node has no parent, no
80
+ * siblings and no box, and a browser returns exactly these. They are here because their
81
+ * *absence* was a `TypeError` that took the whole render down — `this.parentElement && …` is
82
+ * ordinary defensive code and it crashed.
83
+ */
84
+ get parentNode(): any;
85
+ /** `null` when the parent is not an element — a shadow root is a parent and not an element. */
86
+ get parentElement(): any;
87
+ get firstChild(): any;
88
+ get lastChild(): any;
89
+ get lastElementChild(): any;
90
+ /**
91
+ * **The siblings are real now.** These answered `null` unconditionally, which was truthful while a
92
+ * child was flattened into its parent's markup and became a lie the moment nodes were retained —
93
+ * `element.nextSibling` on the middle of three children reported nothing at all. There are no text
94
+ * nodes in this DOM, so the element-wise and node-wise spellings answer the same list.
95
+ */
96
+ get nextSibling(): any;
97
+ get previousSibling(): any;
98
+ get nextElementSibling(): any;
99
+ get previousElementSibling(): any;
100
+ /** @param {number} step @param {(container: any) => Array<any>} view */
101
+ _siblingAt(step: number, view?: (container: any) => Array<any>): any;
102
+ /**
103
+ * **The slot this node is projected into**, which needs the host's shadow root and the node's own
104
+ * `slot` name — both of which are here. It answered `null` for every node, so a component asking
105
+ * where its light DOM had landed was told "nowhere".
106
+ */
107
+ get assignedSlot(): any;
108
+ get offsetParent(): null;
109
+ get childElementCount(): number;
110
+ hasChildNodes(): boolean;
111
+ get nodeValue(): null;
112
+ get baseURI(): string;
113
+ get namespaceURI(): string;
114
+ get prefix(): null;
115
+ get ownerDocument(): Document;
116
+ /**
117
+ * **Walks the parent chain**, as the platform does. It compared identity only, so
118
+ * `host.contains(child)` was `false` for a child the host plainly held — ordinary defensive code
119
+ * reading as "this is not mine".
120
+ */
121
+ contains(node: any): boolean;
122
+ /** The `ChildNode` trio, shared with text and comments through `insertAround`. */
123
+ before(...nodes: any[]): void;
124
+ after(...nodes: any[]): void;
125
+ replaceWith(...nodes: any[]): void;
126
+ isSameNode(node: any): boolean;
127
+ /**
128
+ * **Structural equality, not identity** — that is what `isSameNode` is for, and this answered the
129
+ * same thing, so two elements built identically reported themselves different. The spec compares
130
+ * type, name, attributes as a set, and children pairwise.
131
+ */
132
+ isEqualNode(node: any): any;
133
+ /**
134
+ * **Merges adjacent text and drops the empty**, which is what it is for. It was a no-op because
135
+ * there were no text nodes to merge — appending two of them left two entries a browser would have
136
+ * joined into one, so `childNodes.length` disagreed after the most ordinary DOM building there is.
137
+ */
138
+ normalize(): void;
139
+ /**
140
+ * The furthest ancestor, which is the shadow root for anything a component rendered into one —
141
+ * unless `composed` is asked for, which keeps going out through the root's host as a browser does.
142
+ */
143
+ getRootNode(options: any): any;
144
+ /** Needs layout, which a string does not have; a browser with no box returns nothing either. */
145
+ elementFromPoint(): null;
146
+ elementsFromPoint(): never[];
147
+ getSelection(): null;
148
+ /** `append` takes several nodes, and strings as text — the modern spelling of `appendChild`. */
149
+ /**
150
+ * A string is markup to escape and keep as a chunk. It used to go through `innerHTML +=`, which
151
+ * now reads every retained node back into text and writes it as one chunk — flattening the tree
152
+ * this class exists to keep. Pushing the chunk is the same bytes and keeps the nodes.
153
+ */
154
+ append(...nodes: any[]): void;
155
+ replaceChildren(...nodes: any[]): void;
156
+ /** Splices the entries rather than concatenating markup, for the reason `append` gives. */
157
+ /**
158
+ * **The restore has to survive a throw.** `append` can reject a node — an ancestor of `this` is a
159
+ * `HierarchyRequestError` — and the children were already moved aside by then, so the final
160
+ * `push` never ran and **every existing child was destroyed by a call that failed**.
161
+ *
162
+ * Measured against jsdom: `child.prepend(root)` throws on both, and afterwards jsdom still holds
163
+ * the child's text while this held nothing. A failed operation that mutates is worse than one that
164
+ * does the wrong thing, because the caller has already handled the error and moved on.
165
+ *
166
+ * `finally`, not a validity pre-pass: matching the spec exactly would mean checking every argument
167
+ * before inserting any, so that a second bad node undoes a first good one. That difference is
168
+ * narrower than this one and is left alone deliberately — what is fixed here is the destruction of
169
+ * children that were never arguments.
170
+ *
171
+ * Found by fuzzing sequences of tree mutations against jsdom; the failing sequence ended
172
+ * `prepend(n1, root)` and the loss showed up as a missing text node four operations later.
173
+ */
174
+ prepend(...nodes: any[]): void;
175
+ /**
176
+ * **Answers from the node view**, which markup assigned as a string now has. Every query used to
177
+ * return nothing whatever was asked, so a component branched the wrong way with nothing said.
178
+ * A selector this DOM cannot answer honestly throws rather than answering `null` — see
179
+ * `select.js`.
180
+ */
181
+ querySelector(selector: any): any;
182
+ querySelectorAll(selector: any): any[];
183
+ getElementById(id: any): any;
184
+ /**
185
+ * **Only retained nodes.** Every entry this DOM holds as an element *is* an element, so `children`
186
+ * and `childNodes` answer the same list — there are no text nodes to separate them, and markup
187
+ * kept as a string is not nodes at all (`nodesOf` says so).
188
+ */
189
+ get children(): any[];
190
+ get childNodes(): any[];
191
+ get firstElementChild(): any;
192
+ }
193
+ /**
194
+ * A fragment is a container and nothing more.
195
+ *
196
+ * Its own class rather than a reused `ElementShim`, so `instanceof DocumentFragment` answers `false`
197
+ * for an element — a check the renderer makes, and one that a shared class would have made true for
198
+ * everything.
199
+ */
200
+ export class FragmentShim extends ContainerShim {
201
+ get nodeType(): number;
202
+ get nodeName(): string;
203
+ }
204
+ export class ShadowRootShim extends ContainerShim {
205
+ constructor(init: any);
206
+ mode: any;
207
+ _init: any;
208
+ /** Set by `attachShadow`; a shadow root's `host` is part of the contract the router reads. */
209
+ _host: any;
210
+ _styles: any[];
211
+ /** `shadowrootmode` plus whatever else the root was opened with, as the parser expects them. */
212
+ templateAttributes(): string;
213
+ /** A shadow root's `host` is part of the contract `@verajs/router` reads. */
214
+ get host(): any;
215
+ /**
216
+ * The options it was opened with, readable the way a browser exposes them.
217
+ *
218
+ * These are already serialized into the declarative template — they have to be, because
219
+ * `attachShadow` reuses a declarative root and ignores the options it is handed. A component
220
+ * that *reads* them back, to decide whether to manage focus itself, saw `undefined`.
221
+ */
222
+ get delegatesFocus(): boolean;
223
+ get clonable(): boolean;
224
+ get serializable(): boolean;
225
+ get slotAssignment(): any;
226
+ get nodeType(): number;
227
+ get nodeName(): string;
228
+ /** Nothing is focused on a server, and nothing is in a top layer. */
229
+ get activeElement(): null;
230
+ get fullscreenElement(): null;
231
+ get pointerLockElement(): null;
232
+ get pictureInPictureElement(): null;
233
+ /** `<style>` elements appended here; the constructed ones are `adoptedStyleSheets`. */
234
+ get styleSheets(): (StyleSheetShim & {
235
+ cssText: any;
236
+ })[];
237
+ set textContent(value: string);
238
+ /** A shadow root's text is its content's text, and setting it replaces the content. */
239
+ get textContent(): string;
240
+ /**
241
+ * Constructed sheets land here; serialized alongside string styles.
242
+ *
243
+ * **Checked, because the platform checks.** A browser raises `TypeError` for a value that is not
244
+ * a sequence and for an entry that is not a `CSSStyleSheet`, and taking anything meant that
245
+ * `root.adoptedStyleSheets = sheet` — the single missing `[…]`, and the most likely way to get
246
+ * this wrong — was accepted here and threw in the browser, after the server had already rendered.
247
+ */
248
+ set adoptedStyleSheets(sheets: any);
249
+ get adoptedStyleSheets(): any;
250
+ _adopted: any;
251
+ /**
252
+ * The `<style>` tags, kept separate from the content.
253
+ *
254
+ * They used to be concatenated here and the whole string handed to the nested-component scan,
255
+ * which then read the stylesheet as markup: CSS containing a registered tag name — a
256
+ * `content: "<some-comp>"` is enough — had that component **rendered inside the stylesheet**.
257
+ * A scan for elements has no business reading a raw-text element.
258
+ */
259
+ styleTags(): string;
260
+ }
261
+ export namespace NODE_CONSTANTS {
262
+ let ELEMENT_NODE: number;
263
+ let ATTRIBUTE_NODE: number;
264
+ let TEXT_NODE: number;
265
+ let CDATA_SECTION_NODE: number;
266
+ let ENTITY_REFERENCE_NODE: number;
267
+ let ENTITY_NODE: number;
268
+ let PROCESSING_INSTRUCTION_NODE: number;
269
+ let COMMENT_NODE: number;
270
+ let DOCUMENT_NODE: number;
271
+ let DOCUMENT_TYPE_NODE: number;
272
+ let DOCUMENT_FRAGMENT_NODE: number;
273
+ let NOTATION_NODE: number;
274
+ let DOCUMENT_POSITION_DISCONNECTED: number;
275
+ let DOCUMENT_POSITION_PRECEDING: number;
276
+ let DOCUMENT_POSITION_FOLLOWING: number;
277
+ let DOCUMENT_POSITION_CONTAINS: number;
278
+ let DOCUMENT_POSITION_CONTAINED_BY: number;
279
+ let DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: number;
280
+ }
281
+ export class ElementShim extends ContainerShim {
282
+ constructor(localName?: string, namespaceURI?: string);
283
+ _ns: string;
284
+ localName: string;
285
+ _attributes: Map<any, any>;
286
+ _shadowRoot: ShadowRootShim | null;
287
+ /**
288
+ * The bytes this element's own tags were parsed from, when it came from markup rather than
289
+ * `createElement`. Declared here so every element has the same shape — and so a type-checker
290
+ * knows about a field the parser is what assigns.
291
+ */
292
+ _sourceOpenTag: string | null;
293
+ _sourceCloseTag: string | null;
294
+ /**
295
+ * An attribute name as this element stores it.
296
+ *
297
+ * A browser lower-cases the name inside `setAttribute` on an HTML element, so `setAttribute('Data-Flag', '1')`
298
+ * and `getAttribute('data-flag')` are the *same* attribute. Storing the name as written made them two,
299
+ * and a component that set one spelling and read another got `null` on the server and `'1'` in the
300
+ * browser — a lifecycle divergence with no symptom until the two renders disagreed. Worse, an
301
+ * attribute handed in as `{ 'User-ID': … }` never matched an `observedAttributes` entry, so
302
+ * `attributeChangedCallback` simply did not fire.
303
+ */
304
+ _name(name: any): string;
305
+ /**
306
+ * **`mode: 'closed'` means `element.shadowRoot` is `null`** — that is the entire difference between
307
+ * the two modes, and it was not honoured: a closed root was handed straight back, so a component
308
+ * guarding on `this.shadowRoot` took the branch the browser will not, and anything holding the
309
+ * element could reach inside a root the platform hides. The root is kept on `_shadowRoot`, because
310
+ * it still has to be serialized — declarative shadow DOM expresses `closed` perfectly well
311
+ * (`<template shadowrootmode="closed">`) and the client's parser re-creates it just as hidden.
312
+ */
313
+ get shadowRoot(): ShadowRootShim | null;
314
+ /**
315
+ * Both refusals are the platform's. `mode` is a required member, and an element that already has
316
+ * a root raises `NotSupportedError` rather than getting a second one — which matters here because
317
+ * silently replacing the first root discards everything rendered into it, on the server only.
318
+ * `@verajs/core` already guards against calling this twice *because* the browser throws; the shim
319
+ * accepting it meant the server was the one place that guard was not being checked.
320
+ */
321
+ attachShadow(init?: {}): ShadowRootShim;
322
+ getAttribute(name: any): any;
323
+ setAttribute(name: any, value: any): void;
324
+ hasAttribute(name: any): boolean;
325
+ /**
326
+ * `force` decides, and when the attribute is already in the wanted state **nothing happens** —
327
+ * no write, no callback. This used to reset the value to `''` on `toggleAttribute(name, true)`
328
+ * for an attribute that was already there, which silently erased it.
329
+ */
330
+ toggleAttribute(name: any, force: any): any;
331
+ /**
332
+ * Upgrade, the way the parser does it: `attributeChangedCallback` fires once per **present**
333
+ * observed attribute, before `connectedCallback`, with a `null` old value.
334
+ *
335
+ * It never fired at all on the server. `attributeChangedCallback` is the only reactive-attribute
336
+ * mechanism a plain custom element has, so a component that derives its state there rendered
337
+ * its *initial* state into the page and then corrected itself on the client — a hydration
338
+ * mismatch on every such component, and a flash of the wrong content for anyone without JS.
339
+ */
340
+ upgrade(): void;
341
+ _observed: string[] | undefined;
342
+ _upgraded: boolean | undefined;
343
+ /**
344
+ * And it keeps firing afterwards, because a browser does: a component that changes its own
345
+ * attribute during a render sees the callback on the client and must see it here.
346
+ *
347
+ * Guarded on `_upgraded` first, which is the common case for the renderer's attribute writes —
348
+ * an element mid-upgrade has no observers yet, and one that observes nothing never reaches the
349
+ * `includes`.
350
+ */
351
+ _attributeChanged(name: any, previous: any): void;
352
+ /** Enough of a `NamedNodeMap` to iterate, which is what component code does with it. */
353
+ /**
354
+ * An array rather than a live `NamedNodeMap` — already a recorded difference, since there is
355
+ * nothing to be live over in a single render pass. **The map's own methods are on it**, though:
356
+ * `attributes.getNamedItem('x')` is how a good deal of existing code reads an attribute, and it
357
+ * was simply missing, so that code got a `TypeError` on the server and worked in a browser.
358
+ */
359
+ get attributes(): any;
360
+ getAttributeNames(): any[];
361
+ /**
362
+ * `this.dataset.x = 'y'` and `this.style.color = 'red'` both change the markup, so both write
363
+ * through to the attribute they are a view of. A plain object would accept the assignment and
364
+ * lose it.
365
+ */
366
+ get dataset(): {};
367
+ /**
368
+ * The platform's `style` is `[SameObject, PutForwards=cssText]` — `el.style = 'color: red'`
369
+ * assigns THROUGH to `cssText` in every engine (and in jsdom, the regression net). The shim
370
+ * declared only the getter, so the ordinary spelling threw `Cannot set property` server-side:
371
+ * a component-prop delivery of `.style` was refused as read-only while the client accepted and
372
+ * reflected it — the exact server/client divergence the differential rule exists to catch.
373
+ * `[LegacyNullToEmptyString]` rides the same IDL attribute, so `null` means `''`.
374
+ */
375
+ set style(value: {});
376
+ get style(): {};
377
+ removeAttribute(name: any): void;
378
+ /**
379
+ * The rest of the surface an ordinary custom element reaches for.
380
+ *
381
+ * The shim was built as "the smallest DOM core's server path touches", which is the wrong bar:
382
+ * the code that runs here is *user* code, and a component that emits an event, reads its
383
+ * `tagName`, or adds a class in `connectedCallback` is doing nothing unusual. Each of these threw
384
+ * a `TypeError` that took the whole render down — measured: `dispatchEvent`, `ownerDocument`,
385
+ * `tagName`, `children`, `classList`, `closest` and `getRootNode`, all of them.
386
+ *
387
+ * They answer the way a detached, childless element would, because that is what this is.
388
+ */
389
+ get tagName(): string;
390
+ get nodeType(): number;
391
+ get nodeName(): string;
392
+ /** Walks the real parent chain, which exists now that children are nodes. */
393
+ closest(selector: any): any;
394
+ matches(selector: any): any;
395
+ /**
396
+ * **A no-op until nodes were retained** — an appended child had been flattened into its parent's
397
+ * markup, so there was no parent to ask and nothing to take out. It silently left the element on
398
+ * the page.
399
+ */
400
+ remove(): void;
401
+ /** `[PutForwards=value]`, for the same reason as `part`. */
402
+ set classList(value: {
403
+ add: (...names: any[]) => void;
404
+ remove: (...names: any[]) => void;
405
+ toggle: (name: any, force: any) => any;
406
+ replace: (oldToken: any, newToken: any) => boolean;
407
+ contains: (name: any) => any;
408
+ supports: () => never;
409
+ item: (index: any) => any;
410
+ forEach: (callback: any, thisArg: any) => any;
411
+ keys: () => any;
412
+ values: () => any;
413
+ entries: () => any;
414
+ toString: () => any;
415
+ value: any;
416
+ readonly length: any;
417
+ [Symbol.iterator]: () => any;
418
+ });
419
+ /**
420
+ * Backed by the `class` attribute, so a class added during `connectedCallback` reaches the
421
+ * markup — which it now can, because the opening tag is written from these attributes rather
422
+ * than copied from the source text.
423
+ */
424
+ get classList(): {
425
+ add: (...names: any[]) => void;
426
+ remove: (...names: any[]) => void;
427
+ toggle: (name: any, force: any) => any;
428
+ replace: (oldToken: any, newToken: any) => boolean;
429
+ contains: (name: any) => any;
430
+ supports: () => never;
431
+ item: (index: any) => any;
432
+ forEach: (callback: any, thisArg: any) => any;
433
+ keys: () => any;
434
+ values: () => any;
435
+ entries: () => any;
436
+ toString: () => any;
437
+ value: any;
438
+ readonly length: any;
439
+ [Symbol.iterator]: () => any;
440
+ };
441
+ /**
442
+ * What a **detached, childless** element answers.
443
+ *
444
+ * Every one of these is the truthful answer for this element, not a placeholder: an element with
445
+ * no parent has no siblings and no parent, an element outside a document has no box, and a
446
+ * childless one contains nothing. A browser returns exactly these values for a detached element.
447
+ * They are here because their *absence* was a `TypeError` that took the whole render down —
448
+ * `this.parentElement && …` is ordinary defensive code and it crashed.
449
+ */
450
+ /** No layout on a server, and none for a detached element in a browser either. */
451
+ getBoundingClientRect(): {
452
+ x: number;
453
+ y: number;
454
+ top: number;
455
+ left: number;
456
+ right: number;
457
+ bottom: number;
458
+ width: number;
459
+ height: number;
460
+ toJSON: () => {};
461
+ };
462
+ getClientRects(): never[];
463
+ checkVisibility(): boolean;
464
+ /**
465
+ * **The collection queries answer from the tree.** Each returned an empty array whatever the tree
466
+ * held — the same placeholder shape `querySelector` had, and just as silent. They are live
467
+ * `HTMLCollection`s in a browser and plain arrays here, a deliberate difference recorded in the
468
+ * README: there is nothing to be live *over* while a render is a single pass. (That comment said
469
+ * "already recorded" while the README said nothing about it — the difference is written down now,
470
+ * along with the `item()`/`namedItem()` half of it that was a side effect rather than a decision.)
471
+ */
472
+ getElementsByTagName(name: any): any[];
473
+ getElementsByTagNameNS(namespace: any, name: any): any[];
474
+ getElementsByClassName(names: any): any[];
475
+ /**
476
+ * Namespaces collapse to the plain attribute methods. This DOM serializes HTML, where an
477
+ * `xml:lang` or `xlink:href` is one attribute with a colon in its name — which is how the
478
+ * serializer already treats it, and how the markup reads it back.
479
+ */
480
+ getAttributeNS(_namespace: any, name: any): any;
481
+ setAttributeNS(_namespace: any, name: any, value: any): void;
482
+ hasAttributeNS(_namespace: any, name: any): boolean;
483
+ removeAttributeNS(_namespace: any, name: any): void;
484
+ hasAttributes(): boolean;
485
+ getAttributeNode(name: any): {
486
+ name: any;
487
+ value: any;
488
+ } | null;
489
+ getAttributeNodeNS(_namespace: any, name: any): {
490
+ name: any;
491
+ value: any;
492
+ } | null;
493
+ setAttributeNode(node: any): null;
494
+ setAttributeNodeNS(node: any): null;
495
+ removeAttributeNode(node: any): any;
496
+ /** Aliases the engines still carry. */
497
+ webkitMatchesSelector(): boolean;
498
+ mozMatchesSelector(): boolean;
499
+ /**
500
+ * Interaction, which a server has none of — but the calls are ordinary and must not throw.
501
+ *
502
+ * `click()` is the exception: it *dispatches an event*, and now that listeners are real, a
503
+ * component that clicks itself to seed its own state gets the same result on both sides.
504
+ */
505
+ focus(): void;
506
+ blur(): void;
507
+ click(): void;
508
+ scrollIntoView(): void;
509
+ scroll(): void;
510
+ scrollTo(): void;
511
+ scrollBy(): void;
512
+ /**
513
+ * All four positions. `beforebegin`/`afterend` used to be refused outright on the claim that
514
+ * this element has no parent — true for a component root, and FALSE for everything inside one:
515
+ * `_parent` is live for any nested element (the `outerHTML` setter below runs on it), so a
516
+ * component doing `this.querySelector(…).insertAdjacentHTML('afterend', …)` worked in the
517
+ * browser and took the whole server render down. The two positions now splice into the parent's
518
+ * entries exactly as `outerHTML=` does, and only a genuine orphan refuses — with the platform's
519
+ * own answer, `NoModificationAllowedError`, measured on jsdom and Chromium (the spec raises it
520
+ * for a null or Document parent; a bare `Error` here was a second divergence inside the first).
521
+ *
522
+ * **A markup sink, deliberately** (CODE-PRINCIPLES #8). It writes what it is given, exactly as
523
+ * the DOM's own `insertAdjacentHTML` does, because a component calling it has already decided
524
+ * that: the same call on the client is the same sink, and a server that escaped where the browser
525
+ * does not would render one page and hydrate into another. `insertAdjacentText` escapes, which is
526
+ * the difference between the two methods and the one to reach for with anything from a request.
527
+ */
528
+ insertAdjacentHTML(position: any, markup: any): void;
529
+ insertAdjacentText(position: any, text: any): void;
530
+ insertAdjacentElement(position: any, element: any): any;
531
+ /**
532
+ * **Replaces this element in its parent with the given markup.** Assigning it used to be a
533
+ * `TypeError` — there was no setter — so `element.outerHTML = '<p>x</p>'`, an ordinary way to swap
534
+ * a node out, did nothing on the server and worked in the browser.
535
+ *
536
+ * **With no parent it returns silently**, which is what the spec says and what all three engines
537
+ * do — measured, because the obvious guess was a `NoModificationAllowedError` and that is wrong:
538
+ * the spec raises it only when the parent is a *Document*, not when there is no parent at all.
539
+ */
540
+ set outerHTML(markup: any);
541
+ /** The element's own markup, which the serializer builds anyway. */
542
+ get outerHTML(): any;
543
+ /**
544
+ * **A line break becomes a `<br>`, which is the whole difference from `textContent`.** Every
545
+ * engine splits the assigned string on `\r\n`, `\r` and `\n` and joins the escaped pieces with
546
+ * `<br>`; assigning through `textContent` instead left a literal newline, which collapses to a
547
+ * single space when the page is laid out. So a component that set `innerText` rendered its lines
548
+ * run together on the server and correctly broken on the client — a visible difference in the
549
+ * markup itself, not merely in what a property reads back.
550
+ *
551
+ * Measured on Chromium, Firefox and WebKit, attached and detached, in
552
+ * `tests/browser/inner-text.test.js`.
553
+ */
554
+ set innerText(value: string);
555
+ get innerText(): string;
556
+ /**
557
+ * **Assignable, because the IDL says `[PutForwards=value]`.** Both `part` and `classList` are
558
+ * declared that way, so `element.part = 'a b'` is a legal operation in every engine and writes
559
+ * the attribute. A getter with no setter made it a `TypeError` here instead — a server that
560
+ * refuses what the browser performs, which is the same failure as being too permissive with the
561
+ * direction reversed.
562
+ */
563
+ set part(value: {
564
+ add: (...names: any[]) => void;
565
+ remove: (...names: any[]) => void;
566
+ toggle: (name: any, force: any) => any;
567
+ replace: (oldToken: any, newToken: any) => boolean;
568
+ contains: (name: any) => any;
569
+ supports: () => never;
570
+ item: (index: any) => any;
571
+ forEach: (callback: any, thisArg: any) => any;
572
+ keys: () => any;
573
+ values: () => any;
574
+ entries: () => any;
575
+ toString: () => any;
576
+ value: any;
577
+ readonly length: any;
578
+ [Symbol.iterator]: () => any;
579
+ });
580
+ /** `part` is a token list over the `part` attribute, exactly as `classList` is over `class`. */
581
+ get part(): {
582
+ add: (...names: any[]) => void;
583
+ remove: (...names: any[]) => void;
584
+ toggle: (name: any, force: any) => any;
585
+ replace: (oldToken: any, newToken: any) => boolean;
586
+ contains: (name: any) => any;
587
+ supports: () => never;
588
+ item: (index: any) => any;
589
+ forEach: (callback: any, thisArg: any) => any;
590
+ keys: () => any;
591
+ values: () => any;
592
+ entries: () => any;
593
+ toString: () => any;
594
+ value: any;
595
+ readonly length: any;
596
+ [Symbol.iterator]: () => any;
597
+ };
598
+ /**
599
+ * Form-associated custom elements.
600
+ *
601
+ * `attachInternals()` not existing meant `static formAssociated = true` — the standard way to
602
+ * write a custom form control — threw during `connectedCallback` and took the page with it. None
603
+ * of what internals carry reaches markup (form value, validity and implicit ARIA are all
604
+ * internal state), so this is inert by design rather than by omission: the component runs, and
605
+ * the client's real internals take over on hydration.
606
+ */
607
+ attachInternals(): any;
608
+ /**
609
+ * The element's own opening tag, written from the attributes it holds **now**.
610
+ *
611
+ * Copying the source text instead meant everything a component did to itself during
612
+ * `connectedCallback` was thrown away: `setAttribute('role', 'button')`, a class, an `aria-*` —
613
+ * present on the client after hydration, absent in the server markup, so the two disagreed on
614
+ * every one.
615
+ */
616
+ /**
617
+ * **A copy that shares nothing.** The reason this was out of scope was that a copy sharing the
618
+ * markup string would alias it; entries are an array now, so a deep clone copies them. The source
619
+ * text rides along, so a cloned subtree still reproduces the markup it was parsed from.
620
+ */
621
+ cloneNode(deep?: boolean): any;
622
+ /** This element's own markup, end tag included — the call every node kind answers. */
623
+ /**
624
+ * A `<slot>` shows the host's children that name it; see `assignedTo`.
625
+ *
626
+ * **Getters returning `undefined` off a slot**, because these live on `HTMLSlotElement` and this
627
+ * DOM has one element class. Defining them as plain methods put them on every element, where
628
+ * `typeof element.assignedNodes === 'function'` — the ordinary way to ask "is this a slot" —
629
+ * answered yes for a `<div>`. Being present where the platform has nothing is the same kind of
630
+ * divergence as answering wrongly, and it is the one a feature check walks straight into.
631
+ */
632
+ get assignedNodes(): ((options: any) => any) | undefined;
633
+ get assignedElements(): ((options: any) => any) | undefined;
634
+ markup(): any;
635
+ openTag(): string;
636
+ /**
637
+ * Escaped for an ordinary element, stored as-is for a raw-text one.
638
+ *
639
+ * `@verajs/styles` sets a `<style>` element's `textContent` to the stylesheet, and escaping it
640
+ * turned every `>` into `&#62;` and every `"` into `&#34;`. A browser does not decode those inside
641
+ * `<style>`, so a component with `static styles = '.a > .b { … }'` shipped a broken stylesheet —
642
+ * every child selector, every attribute selector, every `content: "…"`. The client never had it:
643
+ * there, `textContent` sets real text and the serializer of a raw-text element emits it verbatim.
644
+ */
645
+ /**
646
+ * **`null` and `undefined` are the empty string, not their own names.** `textContent` is a
647
+ * nullable `DOMString` with `[LegacyNullToEmptyString]`, and WebIDL converts `undefined` to `null`
648
+ * for a nullable type — so both erase the content in every engine. This wrote the text `null`,
649
+ * which meant `this.textContent = maybeMissing` put the word on the page server-side and nothing
650
+ * client-side: a hydration mismatch produced by ordinary defensive code.
651
+ */
652
+ set textContent(value: string);
653
+ /**
654
+ * Tags stripped and the escaping undone, so what goes in comes back out.
655
+ *
656
+ * Reading back what `textContent` had just written returned `&#60;b&#62;` for `<b>` — the setter
657
+ * escapes and the getter did not decode, so the round trip a component may reasonably rely on was
658
+ * broken. Only the numeric references the setter emits need undoing; anything else in there came
659
+ * from author markup and is text as written.
660
+ */
661
+ get textContent(): string;
662
+ }
663
+ export function createElement(localName: any, namespaceURI?: string): any;
664
+ /**
665
+ * Instances handed to `appendChild` before they have rendered, so the scan renders **them** rather
666
+ * than a fresh copy built from their markup.
667
+ *
668
+ * The nested-component scan reads emitted markup and instantiates what it finds, which is right for
669
+ * a tag written in a template and wrong for an element the component built itself: everything
670
+ * assigned to it — `kid.rows = data`, the ordinary way to hand structured data to a child — was
671
+ * lost, because an attribute cannot carry it and a fresh instance never saw it. The marker attribute
672
+ * is the handle, and `renderComponent` removes it as it renders.
673
+ */
674
+ export const pendingInstances: Map<any, any>;
675
+ /**
676
+ * The marker's **name** carries a per-process random token, because the markup it is written into is
677
+ * not all ours.
678
+ *
679
+ * `children` and the string form of `attributes` are raw markup by design, so a caller passing
680
+ * request data through either hands an attacker a way to write attributes into this document. With a
681
+ * fixed name, injected markup could claim a component's prepared instance — and win, because it is
682
+ * already in the markup when the real one is appended, and the scan reads in order. Demonstrated: an
683
+ * injected `<x-y vera-ssr-instance="1">` rendered with the parent's data while the parent's own
684
+ * child fell back to defaults. A name nothing outside this module can guess closes it, and
685
+ * `renderComponent` also refuses a marker whose instance is not the tag being rendered.
686
+ *
687
+ * Import-time rather than per-render: an attacker cannot read either, and the output never contains
688
+ * the marker, so nothing observable depends on it.
689
+ */
690
+ export const INSTANCE_ATTRIBUTE: string;
691
+ export function markPending(node: any): string;
692
+ /**
693
+ * **Text and comments are nodes.**
694
+ *
695
+ * They were not: `createTextNode` returned an object literal with an `innerHTML` string, so it had
696
+ * no identity, no parent and no `nodeType`, and appending one inlined its markup and lost the node.
697
+ * `childNodes` therefore reported `1` for `text <b>bold</b> tail`, where every browser says `3`.
698
+ *
699
+ * Like an element, a parsed one keeps **the exact bytes it came from** so re-serialising reproduces
700
+ * the input — `&amp;` stays `&amp;` rather than becoming this package's `&#38;` — and falls back to
701
+ * escaping its data the moment somebody writes to it.
702
+ */
703
+ declare class CharacterDataShim extends EventTarget {
704
+ constructor(data: any);
705
+ _data: string;
706
+ _source: string | null;
707
+ _parent: any;
708
+ isConnected: boolean;
709
+ /**
710
+ * Registered here rather than on the platform's `EventTarget`; see `events.js`.
711
+ * @override
712
+ */
713
+ override addEventListener(type: any, callback: any, options: any): void;
714
+ /** @override */
715
+ override removeEventListener(type: any, callback: any, options: any): void;
716
+ /** @override */
717
+ override dispatchEvent(event: any): boolean;
718
+ set data(value: string);
719
+ get data(): string;
720
+ set nodeValue(value: string);
721
+ get nodeValue(): string;
722
+ set textContent(value: string);
723
+ get textContent(): string;
724
+ get length(): number;
725
+ get parentNode(): any;
726
+ get parentElement(): any;
727
+ get childNodes(): never[];
728
+ get firstChild(): null;
729
+ get lastChild(): null;
730
+ hasChildNodes(): boolean;
731
+ get ownerDocument(): Document;
732
+ get nextSibling(): any;
733
+ get previousSibling(): any;
734
+ /** @param {number} step @param {(container: any) => Array<any>} view */
735
+ _siblingAt(step: number, view?: (container: any) => Array<any>): any;
736
+ remove(): void;
737
+ before(...nodes: any[]): void;
738
+ after(...nodes: any[]): void;
739
+ replaceWith(...nodes: any[]): void;
740
+ isSameNode(node: any): boolean;
741
+ isEqualNode(node: any): boolean;
742
+ contains(node: any): boolean;
743
+ getRootNode(): any;
744
+ appendData(value: any): void;
745
+ substringData(offset: any, count: any): string;
746
+ }
747
+ import { StyleSheetShim } from './stylesheets.js';
748
+ export {};