npm - foldkit - Versions diffs - 0.146.0 → 0.148.0 - Mend

foldkit 0.146.0 → 0.148.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (91) hide show

package/README.md +5 -2
package/dist/buildToken.d.ts +3 -0
package/dist/buildToken.d.ts.map +1 -0
package/dist/buildToken.js +21 -0
package/dist/controlledDomState.d.ts +25 -0
package/dist/controlledDomState.d.ts.map +1 -0
package/dist/controlledDomState.js +240 -0
package/dist/cssStyleProperties.d.ts +6 -0
package/dist/cssStyleProperties.d.ts.map +1 -0
package/dist/cssStyleProperties.js +91 -0
package/dist/customElement/index.d.ts.map +1 -1
package/dist/customElement/index.js +23 -0
package/dist/domReflection.d.ts +73 -0
package/dist/domReflection.d.ts.map +1 -0
package/dist/domReflection.js +557 -0
package/dist/experimental/index.d.ts +1 -0
package/dist/experimental/index.d.ts.map +1 -1
package/dist/experimental/index.js +1 -0
package/dist/experimental/machine/machine.d.ts +22 -3
package/dist/experimental/machine/machine.d.ts.map +1 -1
package/dist/experimental/machine/machine.js +8 -0
package/dist/experimental/server/entry.d.ts +73 -0
package/dist/experimental/server/entry.d.ts.map +1 -0
package/dist/experimental/server/entry.js +41 -0
package/dist/experimental/server/host.d.ts +136 -0
package/dist/experimental/server/host.d.ts.map +1 -0
package/dist/experimental/server/host.js +359 -0
package/dist/experimental/server/index.d.ts +5 -0
package/dist/experimental/server/index.d.ts.map +1 -0
package/dist/experimental/server/index.js +4 -0
package/dist/experimental/server/public.d.ts +3 -0
package/dist/experimental/server/public.d.ts.map +1 -0
package/dist/experimental/server/public.js +1 -0
package/dist/experimental/server/serialize.d.ts +43 -0
package/dist/experimental/server/serialize.d.ts.map +1 -0
package/dist/experimental/server/serialize.js +786 -0
package/dist/experimental/server/server.d.ts +242 -0
package/dist/experimental/server/server.d.ts.map +1 -0
package/dist/experimental/server/server.js +946 -0
package/dist/experimental/server/template.d.ts +53 -0
package/dist/experimental/server/template.d.ts.map +1 -0
package/dist/experimental/server/template.js +617 -0
package/dist/html/index.d.ts +5 -0
package/dist/html/index.d.ts.map +1 -1
package/dist/html/index.js +474 -33
package/dist/hydrate.d.ts +4 -0
package/dist/hydrate.d.ts.map +1 -0
package/dist/hydrate.js +850 -0
package/dist/hydrationMarker.d.ts +10 -0
package/dist/hydrationMarker.d.ts.map +1 -0
package/dist/hydrationMarker.js +9 -0
package/dist/hydrationMarkers.d.ts +15 -0
package/dist/hydrationMarkers.d.ts.map +1 -0
package/dist/hydrationMarkers.js +70 -0
package/dist/nativeInnerHtml.d.ts +13 -0
package/dist/nativeInnerHtml.d.ts.map +1 -0
package/dist/nativeInnerHtml.js +30 -0
package/dist/propertyProvenance.d.ts +33 -0
package/dist/propertyProvenance.d.ts.map +1 -0
package/dist/propertyProvenance.js +78 -0
package/dist/propsModule.d.ts.map +1 -1
package/dist/propsModule.js +149 -15
package/dist/runtime/public.d.ts +2 -2
package/dist/runtime/public.d.ts.map +1 -1
package/dist/runtime/public.js +1 -1
package/dist/runtime/runtime.d.ts +99 -36
package/dist/runtime/runtime.d.ts.map +1 -1
package/dist/runtime/runtime.js +412 -71
package/dist/snabbdom/attributes.d.ts.map +1 -1
package/dist/snabbdom/attributes.js +65 -37
package/dist/snabbdom/h.d.ts +1 -0
package/dist/snabbdom/h.d.ts.map +1 -1
package/dist/snabbdom/h.js +85 -4
package/dist/snabbdom/style.d.ts.map +1 -1
package/dist/snabbdom/style.js +53 -34
package/dist/snabbdom/tovnode.d.ts.map +1 -1
package/dist/snabbdom/tovnode.js +5 -1
package/dist/tagName.d.ts +6 -0
package/dist/tagName.d.ts.map +1 -0
package/dist/tagName.js +11 -0
package/dist/test/apps/attributes.d.ts +1 -0
package/dist/test/apps/attributes.d.ts.map +1 -1
package/dist/test/apps/attributes.js +8 -1
package/dist/test/apps/login.js +1 -1
package/dist/test/matchers.d.ts.map +1 -1
package/dist/test/matchers.js +2 -1
package/dist/test/scene.d.ts.map +1 -1
package/dist/test/scene.js +2 -1
package/dist/vdom.d.ts.map +1 -1
package/dist/vdom.js +25 -1
package/package.json +9 -2

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

@@ -0,0 +1,53 @@
+import { type RenderedApplication } from './server.js';
+/** Options for {@link injectIntoTemplate}.
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export type InjectIntoTemplateOptions = Readonly<{
+    /** The `id` of the exact `<div id="..."></div>` placeholder the rendered
+     *  markup replaces. Defaults to `'root'`. */
+    containerId?: string;
+}>;
+/**
+ * Places a rendered page into an HTML template.
+ *
+ * The rendered markup (root element plus the flags payload script) replaces
+ * the empty container element, so the booting runtime finds the root by its
+ * `data-foldkit-app` stamp and hydrates in place. The `Document` head fields
+ * are stamped into the shell so the served HTML is correct before the runtime
+ * boots: `title` replaces the `<title>` text, `lang` and `dir` are set on the
+ * `<html>` element, `canonical` replaces the `href` of a
+ * `<link rel="canonical">` element, and `ogUrl` replaces the `content` of a
+ * `<meta property="og:url">` element. A field the render omits, or a head
+ * element the template does not carry, leaves the template untouched at that
+ * spot.
+ *
+ * The template is parsed with an HTML tokenizer, so every mutation targets a
+ * real element rather than a byte pattern. The container contract is
+ * deliberately exact: the template must contain one `<div id="root"></div>`
+ * placeholder, or the equivalent for `containerId`, with no additional
+ * attributes and no content. It must also contain exactly one `<title>`
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * const page = injectIntoTemplate(template, rendered)
+ * ```
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export declare const injectIntoTemplate: (template: string, rendered: RenderedApplication, options?: InjectIntoTemplateOptions) => string;
+//# sourceMappingURL=template.d.ts.map

package/dist/experimental/server/template.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/template.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,KAAK,mBAAmB,EAIzB,MAAM,aAAa,CAAA;AA6oBpB;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C;iDAC6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,kBAAkB,GAC7B,UAAU,MAAM,EAChB,UAAU,mBAAmB,EAC7B,UAAU,yBAAyB,KAClC,MA0MF,CAAA"}

package/dist/experimental/server/template.js ADDED Viewed

@@ -0,0 +1,617 @@
+import { html as Parse5Html, defaultTreeAdapter, parse, parseFragment, } from 'parse5';
+import { HYDRATION_BUILD_ATTRIBUTE } from '../../buildToken.js';
+import { FOLDKIT_APP_ATTRIBUTE, FOLDKIT_FLAGS_ATTRIBUTE, } from '../../hydrationMarker.js';
+import { escapeAttributeValue, escapeText } from './serialize.js';
+import { __assertNoDeclarativeShadowRoot, __assertNoDocumentStructureEscape, __assertNoLiveBaseElement, } from './server.js';
+const DEFAULT_CONTAINER_ID = 'root';
+const HTML_NAMESPACE = 'http://www.w3.org/1999/xhtml';
+const RENDERED_FRAGMENT_CONTEXT = defaultTreeAdapter.createElement('div', Parse5Html.NS.HTML, []);
+// NOTE: assembled by concatenation rather than through String.replace, whose
+// replacement string reads `$&` and `` $` `` as patterns. Rendered markup is
+// application data and may contain either.
+const NEUTRAL_CONTEXT_PREFIX = '<!doctype html><html><head><title>x</title></head><body>';
+const NEUTRAL_CONTEXT_SUFFIX = '</body></html>';
+const isElement = (node) => 'tagName' in node;
+const collectMatching = (root, predicate) => {
+    const found = [];
+    const walk = (node) => {
+        for (const child of node.childNodes) {
+            if (isElement(child)) {
+                if (predicate(child)) {
+                    found.push(child);
+                }
+                walk(child);
+            }
+        }
+    };
+    walk(root);
+    return found;
+};
+const collectMatchingIncludingTemplateContent = (root, predicate) => {
+    const found = [];
+    const walk = (node) => {
+        for (const child of node.childNodes) {
+            if (!isElement(child)) {
+                continue;
+            }
+            if (predicate(child)) {
+                found.push(child);
+            }
+            walk(child);
+            if (child.tagName === 'template' && 'content' in child) {
+                walk(child.content);
+            }
+        }
+    };
+    walk(root);
+    return found;
+};
+const firstMatching = (root, predicate) => collectMatching(root, predicate)[0];
+const attributeValue = (element, name) => element.attrs.find(attribute => attribute.name === name)?.value;
+const elementChildren = (node) => node.childNodes.filter(isElement);
+const parentOf = (element) => {
+    const parent = element.parentNode;
+    return parent !== null && 'tagName' in parent ? parent : undefined;
+};
+// Each step names the element itself and where it sits among its parent's
+// element children, outermost last.
+const ancestorPath = (element) => {
+    const path = [];
+    let current = element;
+    while (current !== undefined) {
+        const parent = parentOf(current);
+        path.push({
+            tagName: current.tagName.toLowerCase(),
+            index: parent === undefined ? 0 : elementChildren(parent).indexOf(current),
+        });
+        if (parent === undefined) {
+            break;
+        }
+        current = parent;
+    }
+    return path;
+};
+// Each step is resolved by the index it recorded, not by the first element that
+// happens to carry the tag name. Two sibling `<section>`s are an ordinary
+// template, and taking the first would both reject the valid one and let an
+// earlier same-tag sibling stand in for the position the placeholder actually
+// held, so a corrupted injection could be validated against an intact copy.
+const elementAtPath = (document, path) => {
+    let node;
+    let children = elementChildren(document);
+    for (const step of [...path].reverse()) {
+        const child = children[step.index];
+        if (child === undefined ||
+            child.tagName.toLowerCase() !== step.tagName ||
+            (node !== undefined && child.namespaceURI !== node.namespaceURI)) {
+            return undefined;
+        }
+        node = child;
+        children = elementChildren(child);
+    }
+    return node;
+};
+const shapeOfElement = (element) => ({
+    kind: 'Element',
+    tagName: element.tagName.toLowerCase(),
+    namespace: element.namespaceURI,
+    attributes: [...element.attrs]
+        .map(attribute => [attribute.name, attribute.value])
+        .sort(([left], [right]) => left.localeCompare(right)),
+    children: shapesOf(element),
+});
+const shapesOf = (node) => {
+    const shapes = [];
+    let text = '';
+    const flush = () => {
+        if (text !== '') {
+            shapes.push({ kind: 'Text', text });
+        }
+        text = '';
+    };
+    for (const child of node.childNodes) {
+        if (isElement(child)) {
+            flush();
+            shapes.push(shapeOfElement(child));
+        }
+        else if (child.nodeName === '#text' && 'value' in child) {
+            text += child.value;
+        }
+        else if (child.nodeName === '#comment' && 'data' in child) {
+            flush();
+            shapes.push({ kind: 'Comment', text: child.data });
+        }
+    }
+    flush();
+    return shapes;
+};
+const isSameShape = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+// The insertion contexts this API supports, stated rather than inferred. A
+// placeholder reached from `<body>` through nothing but flow containers parses
+// the same way a body does, which is the context `renderToString` already
+// validated the rendered markup against. Every other context (a `<form>`, a
+// `<table>`, a `<select>`, foreign content, template content) makes the final
+// parse depend on where the markup landed, and is refused with a clear error
+// rather than modeled.
+const NEUTRAL_ANCESTOR_TAGS = new Set([
+    'article',
+    'aside',
+    'body',
+    'div',
+    'footer',
+    'header',
+    'main',
+    'section',
+]);
+const assertNeutralInsertionContext = (container, containerId) => {
+    let current = parentOf(container);
+    while (current !== undefined) {
+        const tagName = current.tagName.toLowerCase();
+        if (tagName === 'html') {
+            return;
+        }
+        if (!NEUTRAL_ANCESTOR_TAGS.has(tagName) ||
+            current.namespaceURI !== HTML_NAMESPACE) {
+            throw new Error(`[foldkit] injectIntoTemplate found the <div id="${containerId}"></div> placeholder inside <${tagName}>, which is not a supported insertion context. ` +
+                'HTML parsing rearranges what an element with a restrictive content ' +
+                'model may hold, so the rendered application could be moved, dropped, ' +
+                'or reshaped once it sat there. Place the placeholder in the body or ' +
+                'inside plain flow containers (div, main, section, article, aside, ' +
+                'header, footer).');
+        }
+        current = parentOf(current);
+    }
+};
+// Declarative shadow DOM is refused by `renderToString` itself, which is where
+// every rendered page passes through. The same check runs here as well, since
+// `injectIntoTemplate` accepts any `RenderedApplication` a caller hands it,
+// including one this process did not produce.
+// The rendered markup describes a subtree. Whether the finished page still
+// describes it depends on where the placeholder sat: HTML parsing drops a
+// `<form>` nested in another `<form>`, foster-parents a `<div>` out of a
+// `<table>`, and empties a `<select>` of anything that is not an option. The
+// splice itself is always correct, so the only way to see any of that is to
+// parse the finished page and compare.
+//
+// The comparison is of the placeholder's whole parent, not of the root alone.
+// What the template says that parent should hold after injection is its own
+// children with the placeholder replaced by what the rendered markup describes
+// on its own, in the neutral context `renderToString` already validated it
+// against. Comparing the whole parent covers the rendered subtree, the nodes
+// around it, and the boundaries between them, and it identifies the injection by
+// the position its placeholder held rather than by any attribute, so a marker
+// authored inside the markup cannot stand in for a root the parser dropped, and
+// another application's root elsewhere in the document is not counted against
+// this one.
+//
+// Both parses run with scripting enabled and disabled, because a `<noscript>`
+// in the rendered markup changes the tree for exactly the visitors it targets.
+const renderedShapes = (renderedHtml, isScriptingEnabled) => {
+    const neutral = parse(`${NEUTRAL_CONTEXT_PREFIX}${renderedHtml}${NEUTRAL_CONTEXT_SUFFIX}`, { scriptingEnabled: isScriptingEnabled });
+    const body = firstMatching(neutral, element => element.tagName === 'body');
+    return body === undefined ? [] : shapesOf(body);
+};
+// Adjacent text runs merge, because a parser reads back-to-back text as one
+// node however it was written. Splicing the rendered shapes into the template's
+// own children can put text beside text, so the result is merged the same way
+// before it is compared.
+const mergeAdjacentText = (shapes) => {
+    const merged = [];
+    for (const shape of shapes) {
+        const previous = merged[merged.length - 1];
+        if (shape.kind === 'Text' && previous?.kind === 'Text') {
+            merged[merged.length - 1] = {
+                kind: 'Text',
+                text: previous.text + shape.text,
+            };
+            continue;
+        }
+        merged.push(shape);
+    }
+    return merged.filter(shape => shape.kind !== 'Text' || shape.text !== '');
+};
+// The shapes of a node's children, plus where in that list a given child lands.
+const shapesAround = (parent, child) => {
+    const shapes = shapesOf(parent);
+    let index = 0;
+    let isTextOpen = false;
+    for (const candidate of parent.childNodes) {
+        if (isElement(candidate)) {
+            if (candidate === child) {
+                return { shapes, index };
+            }
+            isTextOpen = false;
+            index += 1;
+        }
+        else if (candidate.nodeName === '#text' && 'value' in candidate) {
+            if (!isTextOpen && candidate.value !== '') {
+                isTextOpen = true;
+                index += 1;
+            }
+        }
+        else if (candidate.nodeName === '#comment') {
+            isTextOpen = false;
+            index += 1;
+        }
+    }
+    return { shapes, index };
+};
+const assertInjectionIsFaithful = (page, template, renderedHtml, containerId, isScriptingEnabled) => {
+    const parsedTemplate = parse(template, {
+        scriptingEnabled: isScriptingEnabled,
+    });
+    const container = firstMatching(parsedTemplate, element => isContainerPlaceholder(element, containerId));
+    const containerParent = container === undefined ? undefined : parentOf(container);
+    if (container === undefined || containerParent === undefined) {
+        // The placeholder does not survive this parser mode at all, so whatever
+        // replaced it does not either: markup before it swallowed the rest of the
+        // shell. Losing the application root for the visitors of one mode is the
+        // failure this check exists to catch, not a reason to skip it.
+        throw new Error(`[foldkit] The <div id="${containerId}"></div> placeholder does not survive when a browser parses the template with scripting ${isScriptingEnabled ? 'enabled' : 'disabled'}. ` +
+            'Markup before it leaves an element open (an unterminated <textarea>, ' +
+            '<style>, or comment inside a <noscript> fallback), so the application ' +
+            'root and the rest of the shell are swallowed as its content. Ensure ' +
+            'the template is complete and balanced in both parser modes.');
+    }
+    const { shapes: templateShapes, index } = shapesAround(containerParent, container);
+    const expected = mergeAdjacentText([
+        ...templateShapes.slice(0, index),
+        ...renderedShapes(renderedHtml, isScriptingEnabled),
+        ...templateShapes.slice(index + 1),
+    ]);
+    const parsedPage = parse(page, { scriptingEnabled: isScriptingEnabled });
+    const pageParent = elementAtPath(parsedPage, ancestorPath(containerParent));
+    const actual = pageParent === undefined ? [] : mergeAdjacentText(shapesOf(pageParent));
+    const isFaithful = expected.length === actual.length &&
+        expected.every((shape, offset) => {
+            const candidate = actual[offset];
+            return candidate !== undefined && isSameShape(shape, candidate);
+        });
+    if (!isFaithful) {
+        throw new Error(`[foldkit] injectIntoTemplate produced a page that no longer describes the rendered markup${isScriptingEnabled ? '' : ' when a browser parses it with scripting disabled'}. ` +
+            'HTML parsing moved, dropped, or reshaped the rendered nodes once they ' +
+            `sat where the <div id="${containerId}"></div> placeholder was, which ` +
+            'happens when the placeholder is nested inside an element with a ' +
+            'restrictive content model (a <form> inside another <form>, anything ' +
+            'inside a <table> or <select>, or foreign content such as <svg> or ' +
+            '<math>). Move the placeholder to the body or another neutral container.');
+    }
+};
+const withAttribute = (attributes, name, value) => {
+    const exists = attributes.some(attribute => attribute.name === name);
+    if (exists) {
+        return attributes.map(attribute => attribute.name === name ? { name, value } : attribute);
+    }
+    return [...attributes, { name, value }];
+};
+const renderAttributes = (attributes) => attributes
+    .map(attribute => ` ${attribute.name}="${escapeAttributeValue(attribute.value)}"`)
+    .join('');
+const renderStartTag = (tagName, attributes) => `<${tagName}${renderAttributes(attributes)}>`;
+const renderVoidElement = (tagName, attributes) => `<${tagName}${renderAttributes(attributes)} />`;
+const applyMutations = (template, mutations) => {
+    const ordered = [...mutations].sort((left, right) => right.start - left.start);
+    let result = template;
+    for (const mutation of ordered) {
+        result =
+            result.slice(0, mutation.start) +
+                mutation.replacement +
+                result.slice(mutation.end);
+    }
+    return result;
+};
+// A valid container is `<div id="{containerId}"></div>` with no other
+// attributes and no children, so the rendered application replaces the exact
+// placeholder and nothing else.
+const ASCII_WHITESPACE_ONLY = /^[ \t\n\f\r]*$/;
+const isIgnorableTopLevelText = (node) => node.nodeName === '#text' &&
+    'value' in node &&
+    ASCII_WHITESPACE_ONLY.test(node.value);
+const sourceLocationOf = (node) => {
+    if (!('sourceCodeLocation' in node)) {
+        return undefined;
+    }
+    const location = node.sourceCodeLocation;
+    return location === null || location === undefined ? undefined : location;
+};
+const hasGeneratedDescendant = (node) => {
+    for (const child of node.childNodes) {
+        if (sourceLocationOf(child) === undefined) {
+            return true;
+        }
+        if (isElement(child)) {
+            if (hasGeneratedDescendant(child)) {
+                return true;
+            }
+            if (child.tagName === 'template' &&
+                'content' in child &&
+                hasGeneratedDescendant(child.content)) {
+                return true;
+            }
+        }
+    }
+    return false;
+};
+const assertRenderedSourceIsPreserved = (renderedHtml, parsed) => {
+    let endOffset = 0;
+    for (const child of parsed.childNodes) {
+        const location = sourceLocationOf(child);
+        if (location === undefined || location.startOffset < endOffset) {
+            throw new Error('[foldkit] injectIntoTemplate received rendered markup that a browser ' +
+                'reshapes before insertion. The rendered application must be one ' +
+                'complete parser-stable root, with only its optional Flags payload ' +
+                'beside it.');
+        }
+        if (!ASCII_WHITESPACE_ONLY.test(renderedHtml.slice(endOffset, location.startOffset))) {
+            throw new Error('[foldkit] injectIntoTemplate received rendered markup whose source ' +
+                'does not survive parsing. An element was dropped, moved, or split ' +
+                'before the application reached the template.');
+        }
+        endOffset = location.endOffset;
+    }
+    if (!ASCII_WHITESPACE_ONLY.test(renderedHtml.slice(endOffset))) {
+        throw new Error('[foldkit] injectIntoTemplate received rendered markup whose trailing ' +
+            'source does not survive parsing. An element was dropped, moved, or ' +
+            'split before the application reached the template.');
+    }
+    if (hasGeneratedDescendant(parsed)) {
+        throw new Error('[foldkit] injectIntoTemplate received rendered markup that makes the ' +
+            'HTML parser insert or reconstruct nodes. Pass the unchanged output ' +
+            'of renderToString rather than hand-authored or parser-unstable markup.');
+    }
+};
+// The runtime id the rendered markup stamps on its root, or `undefined` when it
+// carries no stamp (a render that nothing will hydrate).
+const runtimeIdInMode = (renderedHtml, isScriptingEnabled) => {
+    const parsed = parseFragment(RENDERED_FRAGMENT_CONTEXT, renderedHtml, {
+        scriptingEnabled: isScriptingEnabled,
+        sourceCodeLocationInfo: true,
+    });
+    assertRenderedSourceIsPreserved(renderedHtml, parsed);
+    const applicationMarkers = collectMatchingIncludingTemplateContent(parsed, element => attributeValue(element, FOLDKIT_APP_ATTRIBUTE) !== undefined);
+    const flagsMarkers = collectMatchingIncludingTemplateContent(parsed, element => attributeValue(element, FOLDKIT_FLAGS_ATTRIBUTE) !== undefined);
+    const buildMarkers = collectMatchingIncludingTemplateContent(parsed, element => attributeValue(element, HYDRATION_BUILD_ATTRIBUTE) !== undefined);
+    if (applicationMarkers.length === 0 && flagsMarkers.length === 0) {
+        if (buildMarkers.length > 0) {
+            throw new Error('[foldkit] injectIntoTemplate received a build marker without a ' +
+                'matching server-rendered application root.');
+        }
+        const significant = parsed.childNodes.filter(node => !isIgnorableTopLevelText(node));
+        if (significant.length > 1) {
+            throw new Error('[foldkit] injectIntoTemplate received static rendered markup with ' +
+                'more than one top-level node. renderToString produces one static ' +
+                'root, one text or comment root, or no body output.');
+        }
+        return undefined;
+    }
+    const root = applicationMarkers.at(0);
+    const runtimeId = root === undefined ? undefined : attributeValue(root, FOLDKIT_APP_ATTRIBUTE);
+    const isTopLevelRoot = root !== undefined && parsed.childNodes.some(node => node === root);
+    const areFlagsTopLevel = flagsMarkers.every(element => parsed.childNodes.some(node => node === element));
+    const isFlagsPairValid = flagsMarkers.every(element => element.tagName === 'script' &&
+        attributeValue(element, 'type') === 'application/json' &&
+        attributeValue(element, FOLDKIT_FLAGS_ATTRIBUTE) === runtimeId);
+    const buildId = root === undefined
+        ? undefined
+        : attributeValue(root, HYDRATION_BUILD_ATTRIBUTE);
+    const isBuildPairValid = buildId !== undefined &&
+        buildId !== '' &&
+        buildMarkers.length === 1 &&
+        buildMarkers.at(0) === root;
+    const significant = parsed.childNodes.filter(node => !isIgnorableTopLevelText(node));
+    const hasOnlyOwnedTopLevelNodes = significant.every(node => node === root || (isElement(node) && flagsMarkers.includes(node)));
+    if (runtimeId === undefined ||
+        runtimeId === '' ||
+        applicationMarkers.length !== 1 ||
+        !isTopLevelRoot ||
+        flagsMarkers.length > 1 ||
+        !areFlagsTopLevel ||
+        !isFlagsPairValid ||
+        !isBuildPairValid ||
+        !hasOnlyOwnedTopLevelNodes ||
+        significant.length !== 1 + flagsMarkers.length) {
+        throw new Error('[foldkit] injectIntoTemplate received rendered markup with ambiguous ' +
+            'Foldkit root or Flags markers. A rendered application must carry ' +
+            'exactly one top-level data-foldkit-app root with a nonempty ' +
+            'data-foldkit-build marker, at most one matching top-level ' +
+            'script[type="application/json"][data-foldkit-flags] payload, and no ' +
+            'other top-level content. Application content cannot author any of ' +
+            'those markers.');
+    }
+    return runtimeId;
+};
+const runtimeIdOf = (renderedHtml) => {
+    const enabled = runtimeIdInMode(renderedHtml, true);
+    const disabled = runtimeIdInMode(renderedHtml, false);
+    if (enabled !== disabled) {
+        throw new Error('[foldkit] injectIntoTemplate received rendered markup whose root and ' +
+            'Flags ownership changes when scripting is disabled.');
+    }
+    return enabled;
+};
+const isContainerPlaceholder = (element, containerId) => element.tagName === 'div' &&
+    element.attrs.length === 1 &&
+    element.attrs[0]?.name === 'id' &&
+    element.attrs[0]?.value === containerId &&
+    element.childNodes.length === 0;
+/**
+ * Places a rendered page into an HTML template.
+ *
+ * The rendered markup (root element plus the flags payload script) replaces
+ * the empty container element, so the booting runtime finds the root by its
+ * `data-foldkit-app` stamp and hydrates in place. The `Document` head fields
+ * are stamped into the shell so the served HTML is correct before the runtime
+ * boots: `title` replaces the `<title>` text, `lang` and `dir` are set on the
+ * `<html>` element, `canonical` replaces the `href` of a
+ * `<link rel="canonical">` element, and `ogUrl` replaces the `content` of a
+ * `<meta property="og:url">` element. A field the render omits, or a head
+ * element the template does not carry, leaves the template untouched at that
+ * spot.
+ *
+ * The template is parsed with an HTML tokenizer, so every mutation targets a
+ * real element rather than a byte pattern. The container contract is
+ * deliberately exact: the template must contain one `<div id="root"></div>`
+ * placeholder, or the equivalent for `containerId`, with no additional
+ * attributes and no content. It must also contain exactly one `<title>`
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * const page = injectIntoTemplate(template, rendered)
+ * ```
+ *
+ * @experimental Ships from `foldkit/experimental/server`; expect breaking changes while the API settles.
+ */
+export const injectIntoTemplate = (template, rendered, options) => {
+    const containerId = options?.containerId ?? DEFAULT_CONTAINER_ID;
+    const document = parse(template, { sourceCodeLocationInfo: true });
+    const containers = collectMatching(document, element => isContainerPlaceholder(element, containerId));
+    if (containers.length === 0) {
+        throw new Error(`[foldkit] injectIntoTemplate found no exact <div id="${containerId}"></div> placeholder in the template. ` +
+            'Add that markup where the application root belongs, or pass the container id the template uses.');
+    }
+    if (containers.length > 1) {
+        throw new Error(`[foldkit] injectIntoTemplate found more than one <div id="${containerId}"></div> placeholder in the template. ` +
+            'Keep exactly one placeholder for each application root.');
+    }
+    // The runtime id names an application across the whole page: it pairs a root
+    // with its Flags payload, and it keys the Model and scroll position HMR
+    // preserves. Two roots sharing one is not a second application, it is the
+    // same application claimed twice, so the second injection is refused rather
+    // than producing a page whose parts silently take each other's state. This
+    // holds whether or not either application declares Flags.
+    //
+    // Distinct ids are not a licence to hydrate two applications on one page.
+    // Each page-owning application rewrites the document's metadata and installs
+    // its own navigation listeners, which no id divides between them.
+    const renderedRuntimeId = runtimeIdOf(rendered.html);
+    if (renderedRuntimeId !== undefined) {
+        const existing = collectMatching(document, element => attributeValue(element, FOLDKIT_APP_ATTRIBUTE) === renderedRuntimeId);
+        if (existing.length > 0) {
+            throw new Error(`[foldkit] injectIntoTemplate is placing an application stamped ` +
+                `"${renderedRuntimeId}", but the page already holds a root with ` +
+                'that id. A runtime id names one application for the whole page: it ' +
+                'pairs a root with its Flags payload and keys the Model and scroll ' +
+                'position hot reloading preserves, so two roots sharing one would ' +
+                "take each other's state. Give each application its own " +
+                '`runtimeId` when rendering.');
+        }
+        const existingFlags = collectMatching(document, element => attributeValue(element, FOLDKIT_FLAGS_ATTRIBUTE) === renderedRuntimeId);
+        if (existingFlags.length > 0) {
+            throw new Error(`[foldkit] injectIntoTemplate is placing an application stamped ` +
+                `"${renderedRuntimeId}", but the page already holds a Flags ` +
+                'payload with that id. A runtime id pairs exactly one root with at ' +
+                'most one generated payload, so a stale or application-authored ' +
+                'marker would make hydration ambiguous. Remove the conflicting ' +
+                'script[data-foldkit-flags].');
+        }
+    }
+    const idMatches = collectMatching(document, element => attributeValue(element, 'id') === containerId);
+    if (idMatches.length > 1) {
+        throw new Error(`[foldkit] injectIntoTemplate found more than one element with id="${containerId}" in the template. ` +
+            'The runtime finds the application root by this id once the placeholder is replaced, so a second element sharing it would resolve to the wrong element. Keep the id unique to the placeholder.');
+    }
+    const head = firstMatching(document, element => element.tagName === 'head');
+    const titles = head === undefined
+        ? []
+        : collectMatching(head, element => element.tagName === 'title');
+    if (titles.length === 0) {
+        throw new Error('[foldkit] injectIntoTemplate found no <title> element in the template head. ' +
+            'Add exactly one <title> where the rendered Document title belongs.');
+    }
+    if (titles.length > 1) {
+        throw new Error('[foldkit] injectIntoTemplate found more than one <title> element in the template head. ' +
+            'Keep exactly one title for the rendered Document.');
+    }
+    const mutations = [];
+    const container = containers[0];
+    assertNeutralInsertionContext(container, containerId);
+    __assertNoDeclarativeShadowRoot(rendered.html);
+    __assertNoDocumentStructureEscape(rendered.html);
+    __assertNoLiveBaseElement(rendered.html);
+    const containerLocation = container.sourceCodeLocation;
+    if (containerLocation != null) {
+        mutations.push({
+            start: containerLocation.startOffset,
+            end: containerLocation.endOffset,
+            replacement: rendered.html,
+        });
+    }
+    const title = titles[0];
+    const titleLocation = title.sourceCodeLocation;
+    if (titleLocation?.startTag != null && titleLocation.endTag != null) {
+        mutations.push({
+            start: titleLocation.startTag.endOffset,
+            end: titleLocation.endTag.startOffset,
+            replacement: escapeText(rendered.title),
+        });
+    }
+    const html = firstMatching(document, element => element.tagName === 'html');
+    if (rendered.lang !== undefined || rendered.dir !== undefined) {
+        // HTML lets the <html> start tag be omitted, in which case parse5 builds an
+        // implicit html element with no start-tag location to mutate. Rather than
+        // silently drop the language or direction the page requested, fail so the
+        // author adds an explicit tag.
+        const startTag = html?.sourceCodeLocation?.startTag;
+        if (html === undefined || startTag == null) {
+            throw new Error('[foldkit] injectIntoTemplate cannot stamp the language or direction ' +
+                'because the template has no explicit <html> start tag to mutate. ' +
+                'Add an <html> tag to the template so lang and dir can be set.');
+        }
+        let attributes = html.attrs;
+        if (rendered.lang !== undefined) {
+            attributes = withAttribute(attributes, 'lang', rendered.lang);
+        }
+        if (rendered.dir !== undefined) {
+            attributes = withAttribute(attributes, 'dir', rendered.dir);
+        }
+        mutations.push({
+            start: startTag.startOffset,
+            end: startTag.endOffset,
+            replacement: renderStartTag('html', attributes),
+        });
+    }
+    if (rendered.canonical !== undefined && head !== undefined) {
+        const canonical = firstMatching(head, element => element.tagName === 'link' &&
+            attributeValue(element, 'rel')?.toLowerCase() === 'canonical');
+        if (canonical?.sourceCodeLocation != null) {
+            mutations.push({
+                start: canonical.sourceCodeLocation.startOffset,
+                end: canonical.sourceCodeLocation.endOffset,
+                replacement: renderVoidElement('link', withAttribute(canonical.attrs, 'href', rendered.canonical)),
+            });
+        }
+    }
+    if (rendered.ogUrl !== undefined && head !== undefined) {
+        const ogUrl = firstMatching(head, element => element.tagName === 'meta' &&
+            attributeValue(element, 'property')?.toLowerCase() === 'og:url');
+        if (ogUrl?.sourceCodeLocation != null) {
+            mutations.push({
+                start: ogUrl.sourceCodeLocation.startOffset,
+                end: ogUrl.sourceCodeLocation.endOffset,
+                replacement: renderVoidElement('meta', withAttribute(ogUrl.attrs, 'content', rendered.ogUrl)),
+            });
+        }
+    }
+    const page = applyMutations(template, mutations);
+    // Checked for every render, hydratable or not. Static markup is placed into a
+    // document the same way, and markup the parser drops is lost with no
+    // hydration to rebuild it.
+    for (const isScriptingEnabled of [true, false]) {
+        assertInjectionIsFaithful(page, template, rendered.html, containerId, isScriptingEnabled);
+    }
+    return page;
+};