foldkit 0.147.0 → 0.148.0

package/dist/experimental/server/server.js

@@ -1,9 +1,13 @@
 import { Array as Array_, Context, Data, Effect, Option, Predicate, Schema, pipe, } from 'effect';
-import { parseFragment } from 'parse5';
+import { html as Parse5Html, defaultTreeAdapter, parse, parseFragment, } from 'parse5';
+import { HYDRATION_BUILD_ATTRIBUTE } from '../../buildToken.js';
+import { MATHML_NAMESPACE, SVG_NAMESPACE, parsedAttributeName, } from '../../domReflection.js';
 import { beginRender, createBoundaryRegistry } from '../../html/boundary.js';
 import { __htmlBuilder as htmlBuilderFor, textDirectionToAttribute, } from '../../html/index.js';
 import { clearRuntime, setRuntime, } from '../../html/runtimeSingleton.js';
 import { FOLDKIT_APP_ATTRIBUTE, FOLDKIT_FLAGS_ATTRIBUTE, } from '../../hydrationMarker.js';
+import { HYDRATION_IDENTITY_ATTRIBUTE, HYDRATION_KEY_ATTRIBUTE, } from '../../hydrationMarkers.js';
+import { hasTrustedInnerHtml } from '../../propertyProvenance.js';
 import { tagNameFromSelector } from '../../tagName.js';
 import { fromString } from '../../url/index.js';
 import { controlledValueContent, escapeAttributeValue, serializeHtml, } from './serialize.js';
@@ -123,6 +127,14 @@ const structureMismatch = (parsed) => {
         'mismatch. Write the structure HTML parsing produces, such as explicit ' +
         'table sections.');
 };
+const expectedParsedTagName = (vnode) => {
+    const tagName = tagNameFromSelector(vnode.sel ?? '');
+    return vnode.data?.ns === undefined ? tagName.toLowerCase() : tagName;
+};
+const foreignTagNameMismatch = (parsedTagName, authoredTagName) => new Error(`[foldkit] HTML parsing changed the foreign-content tag ` +
+    `<${authoredTagName}> to <${parsedTagName}>. SVG and MathML tag names ` +
+    'are case-sensitive when the client creates them. Use the canonical ' +
+    'tag spelling so the served and fresh client DOM agree.');
 // Compare the child structure the browser parsed against the structure the
 // view declared, recursively. The top-level check rejects a root that splits
 // into siblings; this rejects a parser correction inside the root, whether an
@@ -130,9 +142,12 @@ const structureMismatch = (parsed) => {
 // foster-parented text, which hydration would otherwise see as a whole-subtree
 // mismatch.
 const assertStructureMatches = (parsed, vnode) => {
-    // InnerHTML owns an opaque, parser-produced subtree that the vnode does not
-    // model as children, so it is left unwalked.
-    if (vnode.data?.props?.['innerHTML'] !== undefined) {
+    // `h.InnerHTML` owns an opaque, parser-produced subtree that the vnode does
+    // not model as children, so it is left unwalked. A property that merely
+    // carries the name is not that: the serializer emits the vnode's own children
+    // for it, so they are walked like any others.
+    if (hasTrustedInnerHtml(vnode.data?.props)) {
+        assertInnerHtmlContextMatches(parsed, vnode);
         return;
     }
     const parsedChildren = normalizeParsedChildren(parsed);
@@ -148,11 +163,16 @@ const assertStructureMatches = (parsed, vnode) => {
             throw structureMismatch(parsed);
         }
         if (parsedChild.kind === 'Element' && vnodeChild.kind === 'Element') {
-            const expectedTag = tagNameFromSelector(vnodeChild.vnode.sel ?? '').toLowerCase();
+            const expectedTag = expectedParsedTagName(vnodeChild.vnode);
             const expectedNamespace = typeof vnodeChild.vnode.data?.ns === 'string'
                 ? vnodeChild.vnode.data.ns
                 : HTML_NAMESPACE;
-            if (parsedChild.element.tagName.toLowerCase() !== expectedTag ||
+            if (expectedNamespace !== HTML_NAMESPACE &&
+                parsedChild.element.namespaceURI === expectedNamespace &&
+                parsedChild.element.tagName !== expectedTag) {
+                throw foreignTagNameMismatch(parsedChild.element.tagName, expectedTag);
+            }
+            if (parsedChild.element.tagName !== expectedTag ||
                 parsedChild.element.namespaceURI !== expectedNamespace) {
                 throw new Error(`[foldkit] HTML parsing produced <${parsedChild.element.tagName}> ` +
                     `where the view declared <${expectedTag}> inside ` +
@@ -190,6 +210,419 @@ const buildDivFragmentContext = () => {
     return onlyChild;
 };
 const DIV_FRAGMENT_CONTEXT = buildDivFragmentContext();
+// After serialization, confirm the root closes cleanly. An unterminated element
+// inside the root (an unclosed `<textarea>`, `<script>`, `<style>`, comment, or
+// `<plaintext>`, typically from an incomplete `InnerHTML` fragment) does not end
+// at the root's own close tag, so it would swallow the Flags payload, the client
+// entry, and everything after the root when the served document is parsed. The
+// per-element structure walk skips `InnerHTML` subtrees, so this parses the root
+// markup with a trailing sentinel comment and requires the sentinel to survive
+// as a top-level sibling: if the root consumed it, so would the rest of the page.
+//
+// NOTE: the parse runs twice, because `<noscript>` has two parser modes and the
+// document has to survive both. With scripting enabled, the state a hydrating
+// visitor's browser is in, noscript content is raw text. With scripting
+// disabled, the state noscript exists to serve, the same content parses as HTML,
+// so an unterminated element inside a noscript fallback swallows the rest of the
+// page for exactly the visitors the fallback was written for. Both modes are
+// checked, so a fallback that frames cleanly for one visitor cannot break the
+// document for the other.
+const TRAILING_SENTINEL_DATA = 'foldkit-trailing-boundary';
+const TRAILING_SENTINEL = `<!--${TRAILING_SENTINEL_DATA}-->`;
+const closesCleanly = (html, isScriptingEnabled) => {
+    const fragment = parseFragment(DIV_FRAGMENT_CONTEXT, html + TRAILING_SENTINEL, {
+        scriptingEnabled: isScriptingEnabled,
+    });
+    const significant = fragment.childNodes.filter(node => !isIgnorableText(node));
+    const last = significant[significant.length - 1];
+    return (last !== undefined &&
+        last.nodeName === '#comment' &&
+        'data' in last &&
+        last.data === TRAILING_SENTINEL_DATA);
+};
+// Framing is not the only thing `<noscript>` can break. An element the fallback
+// leaves open does not have to reach the end of the document to do damage: with
+// scripting disabled an unclosed `<form>` or `<table>` stops at the root's close
+// tag, so the document still frames cleanly, while everything between it and
+// that close tag is pulled inside the fallback and disappears from the page a
+// visitor without JavaScript sees.
+//
+// The check is a comparison rather than a scan, because the two parser modes
+// have to agree on everything except the one place they are meant to differ.
+// The serialized root is parsed both ways and the trees compared, descending
+// into every element except `<noscript>`, whose content is raw text in one mode
+// and markup in the other by design. What must match is where each `<noscript>`
+// sits and what follows it. Comparing the parsed output rather than the declared
+// vnodes also covers a `<noscript>` that arrives inside an `h.InnerHTML`
+// fragment, which no walk over the view's own children can see.
+// `<noscript>` means something to the parser only in the HTML namespace. Inside
+// SVG or MathML an element of that name is an ordinary foreign element whose
+// content parses the same way in both modes, so skipping it there would leave a
+// real HTML `<noscript>` nested below it unchecked. `<template>` holds its
+// children in a separate content fragment rather than in `childNodes`, so its
+// content is traversed explicitly; a fallback inside one is invisible otherwise,
+// and declarative shadow DOM makes that content live in the page.
+const isHtmlNoscript = (element) => element.tagName.toLowerCase() === 'noscript' &&
+    element.namespaceURI === HTML_NAMESPACE;
+const traversableContent = (element) => {
+    if (element.tagName.toLowerCase() === 'template' &&
+        element.namespaceURI === HTML_NAMESPACE &&
+        'content' in element) {
+        const content = element.content;
+        if (Predicate.isObject(content) &&
+            Predicate.hasProperty(content, 'childNodes')) {
+            /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+            return content;
+        }
+    }
+    return element;
+};
+const parsedChildrenAgree = (scripted, unscripted) => {
+    const scriptedChildren = normalizeParsedChildren(scripted);
+    const unscriptedChildren = normalizeParsedChildren(unscripted);
+    if (scriptedChildren.length !== unscriptedChildren.length) {
+        return false;
+    }
+    for (const [scriptedChild, unscriptedChild] of Array_.zip(scriptedChildren, unscriptedChildren)) {
+        if (scriptedChild.kind !== unscriptedChild.kind) {
+            return false;
+        }
+        if (scriptedChild.kind === 'Element' &&
+            unscriptedChild.kind === 'Element') {
+            const tagName = scriptedChild.element.tagName.toLowerCase();
+            if (tagName !== unscriptedChild.element.tagName.toLowerCase() ||
+                scriptedChild.element.namespaceURI !==
+                    unscriptedChild.element.namespaceURI ||
+                !parsedAttributesAgree(scriptedChild.element, unscriptedChild.element)) {
+                return false;
+            }
+            if (isHtmlNoscript(scriptedChild.element)) {
+                continue;
+            }
+            if (!parsedChildrenAgree(traversableContent(scriptedChild.element), traversableContent(unscriptedChild.element))) {
+                return false;
+            }
+        }
+        else if (scriptedChild.kind === 'Text' &&
+            unscriptedChild.kind === 'Text') {
+            if (scriptedChild.text !== unscriptedChild.text) {
+                return false;
+            }
+        }
+        else if (scriptedChild.kind === 'Comment' &&
+            unscriptedChild.kind === 'Comment') {
+            if (scriptedChild.text !== unscriptedChild.text) {
+                return false;
+            }
+        }
+    }
+    return true;
+};
+const parsedAttributesAgree = (left, right) => {
+    const signature = (element) => element.attrs
+        .map(attribute => JSON.stringify([
+        attribute.namespace ?? '',
+        attribute.prefix ?? '',
+        attribute.name,
+        attribute.value,
+    ]))
+        .sort();
+    const leftAttributes = signature(left);
+    const rightAttributes = signature(right);
+    return (leftAttributes.length === rightAttributes.length &&
+        leftAttributes.every((attribute, index) => attribute === rightAttributes[index]));
+};
+const assertInnerHtmlContextMatches = (parsed, vnode) => {
+    const innerHtml = vnode.data?.props?.['innerHTML'];
+    if (typeof innerHtml !== 'string') {
+        return;
+    }
+    const context = defaultTreeAdapter.createElement(parsed.tagName, parsed.namespaceURI, parsed.attrs.map(attribute => ({ ...attribute })));
+    const freshChildren = parseFragment(context, innerHtml, {
+        scriptingEnabled: true,
+    });
+    if (parsedChildrenAgree(traversableContent(parsed), freshChildren)) {
+        return;
+    }
+    throw new Error(`[foldkit] h.InnerHTML on <${parsed.tagName}> parses differently when ` +
+        'assigned to a fresh element than when the serialized page is parsed ' +
+        'under its ancestors. Ancestor parser state can insert, move, or drop ' +
+        'nodes from the server DOM (for example, a nested <form> is dropped ' +
+        'under an existing form), so the server and client cannot describe one ' +
+        'tree. Move the fragment outside that context or build the content with ' +
+        'ordinary view children.');
+};
+const assertNoscriptModesAgree = (html) => {
+    const scripted = parseFragment(DIV_FRAGMENT_CONTEXT, html, {
+        scriptingEnabled: true,
+    });
+    const unscripted = parseFragment(DIV_FRAGMENT_CONTEXT, html, {
+        scriptingEnabled: false,
+    });
+    if (parsedChildrenAgree(scripted, unscripted)) {
+        return;
+    }
+    throw new Error('[foldkit] <noscript> content changes the rest of the page when a browser ' +
+        'parses it with scripting disabled. Its content is raw text while ' +
+        'scripting is enabled and ordinary HTML when it is not, so fallback ' +
+        'markup that leaves an element open (a <form>, <table>, <textarea>, ' +
+        '<style>, or comment) pulls the markup that follows the <noscript> ' +
+        'inside it, and the visitors the fallback was written for never see it. ' +
+        'Ensure the fallback is complete and balanced.');
+};
+// Declarative shadow DOM is refused rather than modeled. A browser turns a
+// `<template shadowrootmode>` into a shadow root as it parses, moving its
+// content out of the light DOM entirely, which neither the parser these checks
+// use nor hydration's own probe reproduces. The served page and the tree
+// hydration reconciles would stop describing the same ownership structure.
+//
+// The scan runs on the rendered markup, so it covers a fragment that arrived
+// through `h.InnerHTML` as well as elements the view declared. It descends into
+// template content, where a nested declaration would otherwise sit unseen, and
+// it parses both scripting modes, because a `<noscript>` holds raw text in one
+// and live markup in the other.
+const DECLARATIVE_SHADOW_ROOT_ATTRIBUTES = [
+    'shadowrootmode',
+    'shadowroot',
+];
+const declaresShadowRoot = (element) => element.tagName.toLowerCase() === 'template' &&
+    element.namespaceURI === HTML_NAMESPACE &&
+    DECLARATIVE_SHADOW_ROOT_ATTRIBUTES.some(name => element.attrs.some(attribute => attribute.name === name));
+// NOTE: one recursion per element. `traversableContent` returns a template's
+// content fragment and the element itself for everything else, so descending
+// into both it and the element visits an ordinary subtree twice, which doubles
+// the work at every level. A tree the serializer accepts (depth up to 1000) took
+// most of a second at depth 24 and would have blocked the event loop well before
+// the depth limit.
+const hasDeclarativeShadowRoot = (node) => node.childNodes.some(child => isParse5Element(child) &&
+    (declaresShadowRoot(child) ||
+        hasDeclarativeShadowRoot(traversableContent(child))));
+export const __assertNoDeclarativeShadowRoot = (html) => {
+    const declaresInEitherMode = [true, false].some(scriptingEnabled => hasDeclarativeShadowRoot(parseFragment(DIV_FRAGMENT_CONTEXT, html, { scriptingEnabled })));
+    if (!declaresInEitherMode) {
+        return;
+    }
+    throw new Error('[foldkit] A rendered <template> declares a shadow root, which server ' +
+        'rendering does not support. A browser turns it into a shadow root ' +
+        'while parsing, moving its content out of the light DOM, so the served ' +
+        'page and the tree hydration reconciles no longer describe the same ' +
+        'thing. Attach shadow roots from a custom element instead.');
+};
+// A <base> parsed anywhere in the live HTML tree changes how every relative URL
+// after it resolves, including the client entry a host writes after the rendered
+// application. The browser applies a base element in body before hydration can
+// remove it, so a view could redirect its own bootstrap module to another
+// origin. Template content is inert and does not participate in URL resolution;
+// declarative shadow templates are refused separately.
+const hasLiveBaseElement = (node) => {
+    for (const child of node.childNodes) {
+        if (!isParse5Element(child)) {
+            continue;
+        }
+        const tagName = child.tagName.toLowerCase();
+        if (child.namespaceURI === HTML_NAMESPACE && tagName === 'base') {
+            return true;
+        }
+        if (child.namespaceURI === HTML_NAMESPACE && tagName === 'template') {
+            continue;
+        }
+        if (hasLiveBaseElement(child)) {
+            return true;
+        }
+    }
+    return false;
+};
+export const __assertNoLiveBaseElement = (html) => {
+    const hasBaseInEitherMode = [true, false].some(scriptingEnabled => hasLiveBaseElement(parseFragment(DIV_FRAGMENT_CONTEXT, html, { scriptingEnabled })));
+    if (!hasBaseInEitherMode) {
+        return;
+    }
+    throw new Error('[foldkit] Rendered application markup contains a live HTML <base> ' +
+        'element. A browser applies it before hydration, so it changes every ' +
+        'relative URL that follows the application, including the client entry ' +
+        'module, and can redirect startup to another origin. Put <base> in the ' +
+        'HTML template head under host control instead.');
+};
+// A page the rendered markup is placed into, with a probe element standing
+// where the application root goes. Parsing the whole document is what makes a
+// structural escape visible: `<html>` and `<body>` start tags inside the markup
+// are dropped by a fragment parse, so a check that only ever sees a fragment
+// reads them as harmless. A browser instead merges their attributes onto the
+// document's own elements and hoists their content, which puts them outside the
+// application's ownership entirely.
+const DOCUMENT_PROBE_ID = 'foldkit-document-probe';
+const DOCUMENT_PROBE_PREFIX = '<!doctype html><html><head><title>probe</title></head><body><div id="' +
+    DOCUMENT_PROBE_ID +
+    '">';
+const DOCUMENT_PROBE_SUFFIX = '</div></body></html>';
+const childElementsOf = (node) => node.childNodes.filter(isParse5Element);
+const findByTag = (node, tagName) => childElementsOf(node).find(element => element.tagName.toLowerCase() === tagName);
+const escapesDocumentStructure = (html, scriptingEnabled) => {
+    const document = parse(`${DOCUMENT_PROBE_PREFIX}${html}${DOCUMENT_PROBE_SUFFIX}`, { scriptingEnabled });
+    const documentElement = findByTag(document, 'html');
+    if (documentElement === undefined) {
+        return true;
+    }
+    const head = findByTag(documentElement, 'head');
+    const body = findByTag(documentElement, 'body');
+    if (head === undefined || body === undefined) {
+        return true;
+    }
+    const probe = childElementsOf(body)[0];
+    return (documentElement.attrs.length > 0 ||
+        body.attrs.length > 0 ||
+        head.attrs.length > 0 ||
+        childElementsOf(head).length !== 1 ||
+        childElementsOf(body).length !== 1 ||
+        probe === undefined ||
+        probe.attrs.find(attribute => attribute.name === 'id')?.value !==
+            DOCUMENT_PROBE_ID);
+};
+export const __assertNoDocumentStructureEscape = (html) => {
+    if (![true, false].some(mode => escapesDocumentStructure(html, mode))) {
+        return;
+    }
+    throw new Error('[foldkit] The rendered markup changes the document it is placed into. ' +
+        'An <html>, <head>, <body>, or <frameset> tag inside it, typically from ' +
+        'an InnerHTML fragment, is not rendered where it is written: a browser ' +
+        "merges its attributes onto the page's own elements and hoists its " +
+        'content out of the application root, so the result is neither the ' +
+        'markup the view wrote nor anything the application owns. Remove those ' +
+        'tags from the fragment.');
+};
+const assertRootClosesCleanly = (html) => {
+    if (closesCleanly(html, true) && closesCleanly(html, false)) {
+        return;
+    }
+    throw new Error('[foldkit] The rendered root does not close cleanly. An unterminated ' +
+        'element (an unclosed <textarea>, <script>, <style>, comment, or ' +
+        '<plaintext>, typically inside an InnerHTML fragment) would swallow the ' +
+        'Flags payload, the client entry, and the rest of the document when the ' +
+        'page is parsed. The check covers <noscript> fallback markup with ' +
+        'scripting disabled too, where the content parses as HTML rather than as ' +
+        'raw text. Ensure InnerHTML fragments are complete and balanced.');
+};
+// The tags that name a document's own structure. A browser builds these from
+// the served document, not from markup spliced into it: a `<body>` or `<head>`
+// start tag encountered inside the document body is dropped and its children
+// are hoisted, an `<html>` start tag only merges its attributes onto the
+// document element, and `<frameset>` replaces the body outright. A view rooted
+// at one of them therefore serializes to markup no template can hold, so it is
+// refused by name rather than surfacing later as a parser-rearranged root.
+const DOCUMENT_STRUCTURE_TAGS = new Set([
+    'body',
+    'frameset',
+    'head',
+    'html',
+]);
+const assertRootIsNotDocumentStructure = (root) => {
+    const tagName = tagNameFromSelector(root.sel ?? '').toLowerCase();
+    if (!DOCUMENT_STRUCTURE_TAGS.has(tagName)) {
+        return;
+    }
+    throw new Error(`[foldkit] The view root is <${tagName}>, which names the structure of a ` +
+        'document rather than content placed into one. A browser builds those ' +
+        'elements from the document it parses, so the tag is dropped, merged, ' +
+        'or replaces the body when the rendered markup is spliced into a ' +
+        'template, and the served root is not the element the view wrote. This ' +
+        'holds for static output too. Root the view at an ordinary element ' +
+        'such as a <div> or <main>, and set the document title, lang, and dir ' +
+        'through the Document the view returns.');
+};
+const RESERVED_HANDOFF_ATTRIBUTES = new Set([
+    FOLDKIT_APP_ATTRIBUTE,
+    HYDRATION_BUILD_ATTRIBUTE,
+    FOLDKIT_FLAGS_ATTRIBUTE,
+    HYDRATION_KEY_ATTRIBUTE,
+    HYDRATION_IDENTITY_ATTRIBUTE,
+]);
+const reservedHandoffAttributeIn = (node) => {
+    for (const child of node.childNodes) {
+        if (!isParse5Element(child)) {
+            continue;
+        }
+        const marker = child.attrs.find(attribute => RESERVED_HANDOFF_ATTRIBUTES.has(attribute.name));
+        if (marker !== undefined) {
+            return marker.name;
+        }
+        const nested = reservedHandoffAttributeIn(traversableContent(child));
+        if (nested !== undefined) {
+            return nested;
+        }
+    }
+    return undefined;
+};
+const hasScriptElement = (node) => node.childNodes.some(child => isParse5Element(child) &&
+    (child.tagName.toLowerCase() === 'script' ||
+        hasScriptElement(traversableContent(child))));
+const assertViewDoesNotAuthorReservedContent = (node) => {
+    const attrs = node.data?.attrs;
+    if (attrs !== undefined) {
+        for (const name of Object.keys(attrs)) {
+            const parsedName = parsedAttributeName(node.data?.ns, name);
+            if (RESERVED_HANDOFF_ATTRIBUTES.has(parsedName)) {
+                throw new Error(`[foldkit] The view authored ${parsedName}, which is reserved for ` +
+                    'Foldkit\u2019s server-to-client hydration handoff. Application ' +
+                    'markup cannot own root, build, Flags, key, or identity markers. ' +
+                    'Remove the attribute.');
+            }
+        }
+    }
+    const innerHtml = node.data?.props?.['innerHTML'];
+    if (typeof innerHtml === 'string' && hasTrustedInnerHtml(node.data?.props)) {
+        const tagName = expectedParsedTagName(node);
+        const namespace = node.data?.ns === SVG_NAMESPACE
+            ? Parse5Html.NS.SVG
+            : node.data?.ns === MATHML_NAMESPACE
+                ? Parse5Html.NS.MATHML
+                : Parse5Html.NS.HTML;
+        const context = defaultTreeAdapter.createElement(tagName, namespace, []);
+        const parsedFragments = [true, false].map(scriptingEnabled => parseFragment(context, innerHtml, { scriptingEnabled }));
+        const marker = parsedFragments
+            .map(reservedHandoffAttributeIn)
+            .find(candidate => candidate !== undefined);
+        if (marker !== undefined) {
+            throw new Error(`[foldkit] h.InnerHTML on <${tagName}> authored ${marker}, which is ` +
+                'reserved for Foldkit\u2019s server-to-client hydration handoff. ' +
+                'Application markup cannot own root, build, Flags, key, or identity ' +
+                'markers. Remove the attribute.');
+        }
+        if (parsedFragments.some(hasScriptElement)) {
+            throw new Error(`[foldkit] h.InnerHTML on <${tagName}> contains a <script> element. ` +
+                'A script element created while parsing served HTML is not ' +
+                'equivalent to one created by assigning innerHTML. Executable forms ' +
+                'can run only on the server path, and other script types have ' +
+                'type-specific processing that Foldkit does not model. Foldkit ' +
+                'therefore refuses classic, module, import-map, speculation-rules, ' +
+                'and data-block scripts at this boundary. Build the script as an ' +
+                'ordinary view element or move it to the HTML template instead.');
+        }
+    }
+    for (const child of node.children ?? []) {
+        if (typeof child !== 'string') {
+            assertViewDoesNotAuthorReservedContent(child);
+        }
+    }
+};
+const elementsAtAndBelow = (element) => {
+    const elements = [element];
+    for (const child of traversableContent(element).childNodes) {
+        if (isParse5Element(child)) {
+            elements.push(...elementsAtAndBelow(child));
+        }
+    }
+    return elements;
+};
+const elementsCarrying = (root, attributeName) => elementsAtAndBelow(root).filter(element => element.attrs.some(attribute => attribute.name === attributeName));
+const assertNoReservedHandoffMarkers = (root) => {
+    const maybeMarker = Array_.findFirst(Array_.fromIterable(RESERVED_HANDOFF_ATTRIBUTES), attributeName => elementsCarrying(root, attributeName).length > 0);
+    if (Option.isNone(maybeMarker)) {
+        return;
+    }
+    throw new Error(`[foldkit] Static output contains ${maybeMarker.value}, which is reserved for ` +
+        'Foldkit\u2019s server-to-client hydration handoff. A render that no ' +
+        'client will hydrate must not carry hydration markers.');
+};
 // After serialization, parse the stamped root markup with the same HTML parser
 // a browser uses and require it to describe exactly one element: the stamped
 // root, with the tag and namespace the view produced. A view can serialize a
@@ -198,7 +631,9 @@ const DIV_FRAGMENT_CONTEXT = buildDivFragmentContext();
 // moving nodes outside the element the client hydrates. Hydration owns only
 // that root, so it cannot remove escaped siblings; rejecting here keeps the
 // invariant that the served root parses back to the single intended element.
-const assertSingleStampedRoot = (html, runtimeId, root) => {
+// The single element the served markup parses back to, or a refusal naming what
+// the parser did to it instead.
+const parsedRootOf = (html, root) => {
     const fragment = parseFragment(DIV_FRAGMENT_CONTEXT, html, {});
     const significant = fragment.childNodes.filter(node => !isIgnorableText(node));
     const only = significant[0];
@@ -209,23 +644,58 @@ const assertSingleStampedRoot = (html, runtimeId, root) => {
             'splits into more than one top-level node. An element the parser ' +
             'moves out of its parent (a block element inside a <p>, a stray ' +
             'element inside a <table>, or an HTML element inside an <svg>) ' +
-            'leaves content outside the application root that hydration cannot ' +
-            'own. Keep the view root a single, structurally valid element tree.');
-    }
-    const stamp = only.attrs.find(attribute => attribute.name === FOLDKIT_APP_ATTRIBUTE);
-    if (stamp?.value !== runtimeId) {
-        throw new Error('[foldkit] HTML parsing moved the hydration marker off the rendered ' +
-            'root, so the served DOM would not carry the stamp the client ' +
-            'adopts. Keep the view root a single, structurally valid element.');
+            'leaves content outside the application root. Keep the view root a ' +
+            'single, structurally valid element tree.');
     }
-    const expectedTag = tagNameFromSelector(root.sel ?? '').toLowerCase();
+    const expectedTag = expectedParsedTagName(root);
     const expectedNamespace = typeof root.data?.ns === 'string' ? root.data.ns : HTML_NAMESPACE;
-    if (only.tagName.toLowerCase() !== expectedTag ||
-        only.namespaceURI !== expectedNamespace) {
+    if (expectedNamespace !== HTML_NAMESPACE &&
+        only.namespaceURI === expectedNamespace &&
+        only.tagName !== expectedTag) {
+        throw foreignTagNameMismatch(only.tagName, expectedTag);
+    }
+    if (only.tagName !== expectedTag || only.namespaceURI !== expectedNamespace) {
         throw new Error('[foldkit] HTML parsing reinterpreted the rendered root as a ' +
             `<${only.tagName}>, not the view's <${expectedTag}>. Keep the view ` +
             'root a single, structurally valid element.');
     }
+    return only;
+};
+// After serialization, parse the root markup with the same HTML parser a browser
+// uses and require it to describe the tree the view wrote. A view can serialize
+// a structurally invalid shape the parser rearranges (a block element inside a
+// `<p>`, a bare `<tr>` in a `<table>`, text foster-parented out of a table),
+// moving or dropping nodes the view declared.
+//
+// This runs for a static render too. Hydration is what would otherwise rebuild a
+// reshaped subtree, so without it a dropped subtree is simply lost, with nothing
+// left to notice. What stays conditional is the marker check below: only a
+// hydratable render emits a stamp for the parser to move.
+const assertParsedRootMatchesView = (html, root) => {
+    const parsed = parsedRootOf(html, root);
+    assertNoReservedHandoffMarkers(parsed);
+    assertStructureMatches(parsed, root);
+};
+const assertSingleStampedRoot = (html, runtimeId, buildId, root) => {
+    const only = parsedRootOf(html, root);
+    const applicationMarkers = elementsCarrying(only, FOLDKIT_APP_ATTRIBUTE);
+    const buildMarkers = elementsCarrying(only, HYDRATION_BUILD_ATTRIBUTE);
+    const flagsMarkers = elementsCarrying(only, FOLDKIT_FLAGS_ATTRIBUTE);
+    const stamp = only.attrs.find(attribute => attribute.name === FOLDKIT_APP_ATTRIBUTE);
+    const buildStamp = only.attrs.find(attribute => attribute.name === HYDRATION_BUILD_ATTRIBUTE);
+    if (applicationMarkers.length !== 1 ||
+        applicationMarkers[0] !== only ||
+        stamp?.value !== runtimeId ||
+        buildMarkers.length !== 1 ||
+        buildMarkers[0] !== only ||
+        buildStamp?.value !== buildId ||
+        flagsMarkers.length !== 0) {
+        throw new Error('[foldkit] The rendered root does not carry exactly one Foldkit root ' +
+            'and build marker on the root itself, or application markup contains ' +
+            'a reserved root, build, or Flags marker below it. The client could ' +
+            'resolve an ambiguous root or payload and refuse the page. Remove ' +
+            'application-authored data-foldkit handoff markers.');
+    }
     assertStructureMatches(only, root);
 };
 export { FOLDKIT_APP_ATTRIBUTE, FOLDKIT_FLAGS_ATTRIBUTE };
@@ -265,6 +735,19 @@ export class InvalidRuntimeId extends Data.TaggedError('InvalidRuntimeId') {
  */
 export class InvalidHydrationRoot extends Data.TaggedError('InvalidHydrationRoot') {
 }
+/** Failure of a hydratable render that was given no build id. Hydration
+ * compares the id on the served root with the client's own to refuse a page
+ * from another deployment, so a render that carries none has no such
+ * protection. Supply one from a value the deployment already has, such as a
+ * commit or a release tag, through `@foldkit/vite-plugin`'s `buildId` option or
+ * the `FOLDKIT_BUILD_ID` environment variable, and pass
+ * `import.meta.env.FOLDKIT_BUILD_ID` to `renderToString` and `Runtime.hydrate`.
+ * A render that nothing will hydrate (`isHydratable: false`) needs none.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export class MissingBuildId extends Data.TaggedError('MissingBuildId') {
+}
 const noOpDispatch = () => { };
 // NOTE: the html builder reads its dispatch context from a process-wide
 // frame stack (`setRuntime` / `clearRuntime`) rather than an argument, so
@@ -367,6 +850,18 @@ export function renderToString(config, options) {
         const hasRouting = config.routing !== undefined;
         const FlagsCodec = config.Flags;
         const isHydratable = options?.isHydratable ?? true;
+        // A hydratable render must say which deployment it came from. Deriving it
+        // here is not possible: the render cannot see the sources, the
+        // configuration, or the dependencies that decide what the view produced, so
+        // an id it invented would either differ between the client and server
+        // builds of one deployment or be shared by two that render differently.
+        // Refusing is the only honest answer, and it names what to supply.
+        const configuredBuildId = options?.buildId;
+        if (isHydratable &&
+            (configuredBuildId === undefined || configuredBuildId === '')) {
+            return yield* Effect.fail(new MissingBuildId());
+        }
+        const buildId = configuredBuildId ?? '';
         const url = hasRouting ? yield* parseUrl(options?.url ?? '') : undefined;
         const flagsHandoff = isHydratable && FlagsCodec !== undefined
             ? yield* encodeFlagsHandoff(FlagsCodec, options?.flags, runtimeId)
@@ -387,11 +882,39 @@ export function renderToString(config, options) {
         }
         const rootHtml = yield* Effect.try({
             try: () => {
+                // Checked for every render, hydratable or not: static markup is placed
+                // into a document the same way, so a document-structure root is
+                // rearranged by the parser either way.
+                if (nextDocument.body !== null) {
+                    assertRootIsNotDocumentStructure(nextDocument.body);
+                    assertViewDoesNotAuthorReservedContent(nextDocument.body);
+                }
+                // The build id rides on the root so hydration can refuse a page from
+                // another deployment before it adopts any of its DOM.
                 const html = serializeHtml(nextDocument.body, isHydratable
-                    ? { rootAttributes: { [FOLDKIT_APP_ATTRIBUTE]: runtimeId } }
+                    ? {
+                        rootAttributes: {
+                            [FOLDKIT_APP_ATTRIBUTE]: runtimeId,
+                            [HYDRATION_BUILD_ATTRIBUTE]: buildId,
+                        },
+                        emitHydrationMarkers: true,
+                    }
                     : {});
-                if (isHydratable && nextDocument.body !== null) {
-                    assertSingleStampedRoot(html, runtimeId, nextDocument.body);
+                // Framing is checked for every render, hydratable or not. Static markup
+                // is placed into a document the same way, so a root that does not close
+                // cleanly swallows whatever the host writes after it either way.
+                assertRootClosesCleanly(html);
+                assertNoscriptModesAgree(html);
+                __assertNoDeclarativeShadowRoot(html);
+                __assertNoDocumentStructureEscape(html);
+                __assertNoLiveBaseElement(html);
+                if (nextDocument.body !== null) {
+                    if (isHydratable) {
+                        assertSingleStampedRoot(html, runtimeId, buildId, nextDocument.body);
+                    }
+                    else {
+                        assertParsedRootMatchesView(html, nextDocument.body);
+                    }
                 }
                 return html;
             },

package/dist/experimental/server/template.d.ts

@@ -30,6 +30,14 @@ export type InjectIntoTemplateOptions = Readonly<{
  * element in its head. Throws when either required location is missing or
  * appears more than once.
  *
+ * Pass the `RenderedApplication` returned by `renderToString` unchanged. A
+ * hydratable value must parse as exactly one top-level element carrying one
+ * nonempty root stamp and build stamp, optionally followed by one matching
+ * top-level JSON Flags script. Static output may contain one element, text, or
+ * comment root, or no body output. The helper rejects additional top-level
+ * content, ambiguous handoff markers, and source that the HTML parser drops,
+ * splits, moves, or reconstructs before insertion.
+ *
  * This helper is pure with no module state, so a host process may import it
  * directly even when the render itself must stay inside the server entry's
  * module graph.