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

foldkit 0.147.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 (61) hide show

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/domReflection.d.ts +73 -0
package/dist/domReflection.d.ts.map +1 -0
package/dist/domReflection.js +557 -0
package/dist/experimental/server/host.d.ts +102 -8
package/dist/experimental/server/host.d.ts.map +1 -1
package/dist/experimental/server/host.js +203 -13
package/dist/experimental/server/public.d.ts +2 -2
package/dist/experimental/server/public.d.ts.map +1 -1
package/dist/experimental/server/public.js +1 -1
package/dist/experimental/server/serialize.d.ts +15 -5
package/dist/experimental/server/serialize.d.ts.map +1 -1
package/dist/experimental/server/serialize.js +367 -144
package/dist/experimental/server/server.d.ts +55 -14
package/dist/experimental/server/server.d.ts.map +1 -1
package/dist/experimental/server/server.js +544 -21
package/dist/experimental/server/template.d.ts +8 -0
package/dist/experimental/server/template.d.ts.map +1 -1
package/dist/experimental/server/template.js +437 -2
package/dist/html/index.d.ts.map +1 -1
package/dist/html/index.js +436 -29
package/dist/hydrate.d.ts +1 -1
package/dist/hydrate.d.ts.map +1 -1
package/dist/hydrate.js +449 -121
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 +1 -1
package/dist/runtime/public.d.ts.map +1 -1
package/dist/runtime/runtime.d.ts +30 -6
package/dist/runtime/runtime.d.ts.map +1 -1
package/dist/runtime/runtime.js +230 -27
package/dist/snabbdom/attributes.d.ts.map +1 -1
package/dist/snabbdom/attributes.js +65 -37
package/dist/snabbdom/style.d.ts.map +1 -1
package/dist/snabbdom/style.js +53 -34
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/package.json +2 -2

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

	@@ -1 +1 @@
1	- {"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/template.ts"],"names":[],"mappings":"~~AAIA~~,OAAO,~~EAAE~~,KAAK,mBAAmB,~~EAAE~~,MAAM,aAAa,CAAA;~~AAgHtD~~;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C;iDAC6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAC,CAAA;AAEF~~;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG~~;AACH,eAAO,MAAM,kBAAkB,GAC7B,UAAU,MAAM,EAChB,UAAU,mBAAmB,EAC7B,UAAU,yBAAyB,KAClC,~~MA0IF~~,CAAA"}
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 CHANGED Viewed

@@ -1,6 +1,16 @@
-import { parse } from 'parse5';
+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 = [];
@@ -17,8 +27,256 @@ const collectMatching = (root, predicate) => {
     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) {
@@ -45,6 +303,132 @@ const applyMutations = (template, mutations) => {
 // 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' &&
@@ -72,6 +456,14 @@ const isContainerPlaceholder = (element, containerId) => element.tagName === 'di
  * 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.
@@ -95,6 +487,38 @@ export const injectIntoTemplate = (template, rendered, options) => {
         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. ` +
@@ -114,6 +538,10 @@ export const injectIntoTemplate = (template, rendered, options) => {
     }
     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({
@@ -178,5 +606,12 @@ export const injectIntoTemplate = (template, rendered, options) => {
             });
         }
     }
-    return applyMutations(template, mutations);
+    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;
 };