foldkit 0.147.0 → 0.148.1

package/dist/experimental/server/serialize.js

@@ -1,4 +1,7 @@
 import { Array as Array_ } from 'effect';
+import { BOOLEAN_PROPERTIES, FOREIGN_REPRESENTABLE_PROPERTIES, GLOBAL_ATTRIBUTE_PROPERTIES, HTML_NAMESPACE, PASSTHROUGH_PROPERTIES, RENAMED_PROPERTY_ATTRIBUTES, assertStyleIsRepresentable, htmlAttributeValue, isHtmlPropertyRepresentable, parsedAttributeName, serializedHtmlPropertyValue, serializedStyleAttribute, } from '../../domReflection.js';
+import { HYDRATION_IDENTITY_ATTRIBUTE, HYDRATION_KEY_ATTRIBUTE, hydrationIdentityMarker, hydrationKeyMarker, } from '../../hydrationMarkers.js';
+import { hasTrustedInnerHtml, isClientOnlyProperty, } from '../../propertyProvenance.js';
 import { tagNameFromSelector } from '../../tagName.js';
 const VOID_ELEMENTS = new Set([
     'area',
@@ -18,10 +21,17 @@ const VOID_ELEMENTS = new Set([
 ]);
 const RAW_TEXT_ELEMENTS = new Set([
     'iframe',
+    'noembed',
+    'noframes',
     'noscript',
     'script',
     'style',
+    'xmp',
 ]);
+// RCDATA elements decode entities but still end at their own closing tag, so
+// escaping their text is correct while a closing sequence inside trusted raw
+// HTML would break out of the element exactly as it does for raw text.
+const RCDATA_ELEMENTS = new Set(['textarea', 'title']);
 // NOTE: raw-text elements parse their content as text until the first
 // `</tagname`, so HTML entities are not decoded and a closing-tag sequence in
 // the content ends the element early. Escaping a text child, correct for a
@@ -30,10 +40,12 @@ const RAW_TEXT_ELEMENTS = new Set([
 // view. The content is therefore emitted verbatim, and a closing-tag sequence,
 // which would break out into live markup on the server, is a hard error since
 // there is no valid escaping for it. `<noscript>` is raw text only while
-// scripting is enabled, which is exactly the hydrating client's state, so it
-// serializes the same way; its text (including `&`, `<`, and `>`) round-trips
-// verbatim, and element children it cannot represent still fail the structure
-// check.
+// scripting is enabled, the hydrating client's state, so plain text round-trips
+// verbatim. With scripting disabled, the state noscript targets, a browser
+// parses noscript content as ordinary HTML, so a `<` in its text would become
+// live markup; text carrying one is refused (see `assertNoscriptTextIsSafe`).
+// Element children it cannot represent still fail the structure check, and
+// intended fallback markup is authored through `h.InnerHTML`.
 const rawTextClosingSequence = (tagName) => new RegExp(`</${tagName}(?=[\\t\\n\\f\\r />]|$)`, 'i');
 // NOTE: `<script>` content has more parser states than the closing-tag check
 // covers. A `<!--` sequence moves the tokenizer into the script-data-escaped
@@ -56,6 +68,27 @@ const assertRawTextIsSafe = (tagName, content) => {
             '</script> tag no longer ends the element. Remove the <!-- sequence ' +
             'from the content.');
     }
+    assertRepresentable(content, `<${tagName}> content`);
+    assertNoCarriageReturn(content, `<${tagName}> content`);
+};
+// NOTE: `<noscript>` is raw text only with scripting enabled. With scripting
+// disabled, the state noscript exists for, a browser parses its content as HTML,
+// so markup-significant text (a `<meta>`, `<style>`, `<iframe>`, `<form>`, or an
+// image with an `onerror`) would become live for exactly the users noscript
+// targets. Plain text without a `<` is identical in both parser modes and safe;
+// text carrying a `<` is refused. Intended fallback markup is authored through
+// `h.InnerHTML`, which is trusted and rendered as raw HTML.
+// A `<` opens a tag, comment, or end tag only when followed by an ASCII letter,
+// `!`, `/`, or `?`. A bare `<` (as in `a < b` or `<3`) is literal text in both
+// parser modes, so it is left alone.
+const NOSCRIPT_MARKUP_OPENER = /<[A-Za-z!/?]/;
+const assertNoscriptTextIsSafe = (content) => {
+    if (NOSCRIPT_MARKUP_OPENER.test(content)) {
+        throw new Error('[foldkit] <noscript> text content contains markup (a "<" that opens a ' +
+            'tag or comment), which a browser with scripting disabled parses as ' +
+            'live markup. Remove the markup, or author trusted fallback markup with ' +
+            'h.InnerHTML.');
+    }
 };
 // NOTE: comment text has no escaping either: it ends at the first `-->` or
 // `--!>`, and must not start with `>` or `->` nor end with `<!-`. A
@@ -63,6 +96,8 @@ const assertRawTextIsSafe = (tagName, content) => {
 // markup on the server, so it is refused the same way raw-text content is.
 const COMMENT_TERMINATOR = /--!?>/;
 const assertCommentTextIsSafe = (text) => {
+    assertRepresentable(text, 'comment content');
+    assertNoCarriageReturn(text, 'comment content');
     if (text.startsWith('>') ||
         text.startsWith('->') ||
         COMMENT_TERMINATOR.test(text) ||
@@ -72,88 +107,6 @@ const assertCommentTextIsSafe = (text) => {
             'content.');
     }
 };
-const BOOLEAN_PROPERTIES = new Set([
-    'autofocus',
-    'autoplay',
-    'checked',
-    'controls',
-    'disabled',
-    'formNoValidate',
-    'hidden',
-    'inert',
-    'isMap',
-    'loop',
-    'multiple',
-    'muted',
-    'noValidate',
-    'open',
-    'playsInline',
-    'readOnly',
-    'required',
-    'reversed',
-    'selected',
-]);
-const RENAMED_PROPERTY_ATTRIBUTES = {
-    colSpan: 'colspan',
-    dateTime: 'datetime',
-    formAction: 'formaction',
-    formEnctype: 'formenctype',
-    formMethod: 'formmethod',
-    formNoValidate: 'formnovalidate',
-    formTarget: 'formtarget',
-    htmlFor: 'for',
-    isMap: 'ismap',
-    maxLength: 'maxlength',
-    minLength: 'minlength',
-    noValidate: 'novalidate',
-    playsInline: 'playsinline',
-    readOnly: 'readonly',
-    rowSpan: 'rowspan',
-    tabIndex: 'tabindex',
-};
-const PASSTHROUGH_PROPERTIES = new Set([
-    'accept',
-    'action',
-    'alt',
-    'autocomplete',
-    'cite',
-    'cols',
-    'dir',
-    'download',
-    'enctype',
-    'high',
-    'href',
-    'id',
-    'label',
-    'lang',
-    'low',
-    'max',
-    'method',
-    'min',
-    'name',
-    'optimum',
-    'pattern',
-    'placeholder',
-    'poster',
-    'preload',
-    'rel',
-    'rows',
-    'size',
-    'span',
-    'src',
-    'start',
-    'step',
-    'target',
-    'title',
-    'type',
-    'value',
-    'wrap',
-]);
-const STYLE_LIFECYCLE_KEYS = new Set([
-    'delayed',
-    'remove',
-    'destroy',
-]);
 const CAPS_REGEX = /[A-Z]/g;
 const ATTRIBUTE_NAME_PATTERN = /^[A-Za-z_:][A-Za-z0-9_.:-]*$/;
 // NOTE: the tag name is written verbatim into the opening and closing markup,
@@ -177,17 +130,67 @@ const ATTRIBUTE_ESCAPES = {
     '&': '&amp;',
     '"': '&quot;',
     '<': '&lt;',
+    // As in text, a carriage return is normalized away (CR and CRLF collapse to LF
+    // before tokenization) unless encoded as a character reference, which decodes
+    // back to the original after normalization.
+    '\r': '&#13;',
+};
+// NUL (U+0000) has no HTML representation: the tokenizer replaces it with U+FFFD
+// or drops it, so it can never round-trip. It is rejected wherever a value is
+// escaped for output rather than silently corrupted.
+const assertNoNul = (value, context) => {
+    if (value.includes('\u0000')) {
+        throw new Error(`[foldkit] ${context} contains a NUL (U+0000) character, which has no ` +
+            'HTML representation and cannot round-trip. Remove it from the value.');
+    }
+};
+// A high surrogate with no low one after it, or a low surrogate with no high one
+// before it. Such a code unit is not a character: encoding the page as UTF-8,
+// which every HTTP response and generated file does, replaces it with U+FFFD, so
+// what a visitor receives is not what the view rendered.
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+const assertNoLoneSurrogate = (value, context) => {
+    if (LONE_SURROGATE.test(value)) {
+        throw new Error(`[foldkit] ${context} contains an unpaired surrogate code unit, which ` +
+            'is not a character. Encoding the page as UTF-8 replaces it with ' +
+            'U+FFFD, so the served text would not be the text the view rendered. ' +
+            'Remove it from the value.');
+    }
+};
+// Everything a serialized value must satisfy to survive the trip through an
+// HTML parser and a UTF-8 encoder unchanged.
+const assertRepresentable = (value, context) => {
+    assertNoNul(value, context);
+    assertNoLoneSurrogate(value, context);
+};
+// A carriage return in a sink that has no escaping. Escaped text emits `&#13;`
+// so a `\r` round-trips; raw text and comment content are emitted verbatim,
+// where a browser's input preprocessing turns CR and CRLF into LF before the
+// tokenizer ever sees them. The character cannot be represented there, so it is
+// refused rather than silently normalized.
+const assertNoCarriageReturn = (value, context) => {
+    if (value.includes('\r')) {
+        throw new Error(`[foldkit] ${context} contains a carriage return, which HTML input ` +
+            'preprocessing turns into a line feed before parsing and which has no ' +
+            'escape in this position. Remove it from the value.');
+    }
 };
 /** Escapes a string for use as HTML text content.
  *
  * @internal Shared with the template injector; not part of the `foldkit/experimental/server` surface.
  */
-export const escapeText = (value) => value.replace(/[&<>\r]/g, character => TEXT_ESCAPES[character] ?? character);
+export const escapeText = (value) => {
+    assertRepresentable(value, 'text content');
+    return value.replace(/[&<>\r]/g, character => TEXT_ESCAPES[character] ?? character);
+};
 /** Escapes a string for use inside a double-quoted HTML attribute value.
  *
  * @internal Shared with the template injector; not part of the `foldkit/experimental/server` surface.
  */
-export const escapeAttributeValue = (value) => value.replace(/[&"<]/g, character => ATTRIBUTE_ESCAPES[character] ?? character);
+export const escapeAttributeValue = (value) => {
+    assertRepresentable(value, 'attribute value');
+    return value.replace(/[&"<\r]/g, character => ATTRIBUTE_ESCAPES[character] ?? character);
+};
 const toKebabCase = (value) => value.replace(CAPS_REGEX, '-$&').toLowerCase();
 const setAttribute = (attributes, name, value) => {
     if (!ATTRIBUTE_NAME_PATTERN.test(name)) {
@@ -211,12 +214,18 @@ const appendStyle = (attributes, addition) => {
     attributes.set('style', existing === undefined ? addition : `${existing}${separator}${addition}`);
 };
 const collectDataAttributes = (attributes, data) => {
-    const isForeignNamespace = data.ns !== undefined;
+    const namespace = data.ns ?? HTML_NAMESPACE;
     const plainAttributes = data.attrs;
     if (plainAttributes !== undefined) {
+        const normalizedAttributes = new Map();
         for (const rawName of Object.keys(plainAttributes)) {
+            const name = parsedAttributeName(namespace, rawName);
             const value = plainAttributes[rawName];
-            const name = isForeignNamespace ? rawName : rawName.toLowerCase();
+            if (value !== undefined) {
+                normalizedAttributes.set(name, value);
+            }
+        }
+        for (const [name, value] of normalizedAttributes) {
             if (value === true) {
                 setAttribute(attributes, name, '');
             }
@@ -250,55 +259,73 @@ const collectDataAttributes = (attributes, data) => {
         }
     }
 };
-const collectPropertyAttributes = (attributes, tagName, properties) => {
+const collectPropertyAttributes = (attributes, tagName, properties, isCustomElement, isForeignNamespace) => {
     for (const name of Object.keys(properties)) {
         const value = properties[name];
         if (value === undefined || name === 'innerHTML') {
             continue;
         }
+        if (isCustomElement &&
+            !(GLOBAL_ATTRIBUTE_PROPERTIES.has(name) &&
+                !isClientOnlyProperty(properties, name))) {
+            continue;
+        }
+        if (!isForeignNamespace &&
+            !isCustomElement &&
+            !isHtmlPropertyRepresentable(tagName, name)) {
+            continue;
+        }
+        // An SVG or MathML element has the HTML interface members below only where
+        // the measured table says so. Emitting an attribute for one it does not have
+        // would serve state the client cannot reach: assigning the property there
+        // sets an expando, or throws on a readonly `SVGAnimatedString`. The builders
+        // refuse to build such a view, and this is the same rule on the serializing
+        // side.
+        if (isForeignNamespace && !FOREIGN_REPRESENTABLE_PROPERTIES.has(name)) {
+            continue;
+        }
         // NOTE: `value` on textarea/output/select is not a serializable attribute
         // (textarea and output render it as text content, select reflects the
-        // selected option), and on an input an empty value matches the element's
-        // default so the attribute is redundant. It stays meaningful elsewhere,
-        // e.g. `<option value="">`.
+        // selected option), and on an input an empty value is the element's own
+        // default. In every one of those cases the property still decides, so a raw
+        // `h.Attribute('value', ...)` written alongside it is removed rather than
+        // left standing: the client assigns the property over whatever the
+        // attribute said, and leaving the attribute would serve a value the
+        // hydrated page immediately contradicts.
         if (name === 'value' &&
-            (tagName === 'textarea' ||
-                tagName === 'output' ||
-                tagName === 'select' ||
-                (tagName === 'input' && value === ''))) {
+            (tagName === 'textarea' || tagName === 'output' || tagName === 'select')) {
+            attributes.delete('value');
             continue;
         }
         if (BOOLEAN_PROPERTIES.has(name)) {
+            // A property set to `false` is not an absent property. The client leaves
+            // the element unchecked, closed, or enabled, so a raw attribute saying
+            // otherwise has to go: serving it made the browser check a box the Model
+            // says is clear, and submit it before hydration could correct anything.
+            const attributeName = RENAMED_PROPERTY_ATTRIBUTES[name] ?? name;
             if (value === true) {
-                setAttribute(attributes, RENAMED_PROPERTY_ATTRIBUTES[name] ?? name, '');
+                setAttribute(attributes, attributeName, '');
+            }
+            else {
+                attributes.delete(attributeName);
             }
         }
         else if (name === 'draggable') {
             setAttribute(attributes, name, value === true ? 'true' : 'false');
         }
         else if (name in RENAMED_PROPERTY_ATTRIBUTES) {
-            setAttribute(attributes, RENAMED_PROPERTY_ATTRIBUTES[name] ?? name, String(value));
+            setAttribute(attributes, RENAMED_PROPERTY_ATTRIBUTES[name] ?? name, serializedHtmlPropertyValue(tagName, name, value));
         }
         else if (PASSTHROUGH_PROPERTIES.has(name)) {
-            setAttribute(attributes, name, String(value));
+            setAttribute(attributes, name, serializedHtmlPropertyValue(tagName, name, value));
         }
     }
 };
 const collectStyleAttribute = (attributes, style) => {
-    const declarations = [];
-    for (const name of Object.keys(style)) {
-        if (STYLE_LIFECYCLE_KEYS.has(name)) {
-            continue;
-        }
-        const value = style[name];
-        if (typeof value !== 'string' || value === '') {
-            continue;
-        }
-        const propertyName = name.startsWith('--') ? name : toKebabCase(name);
-        declarations.push(`${propertyName}: ${value}`);
-    }
-    if (Array_.isArrayNonEmpty(declarations)) {
-        appendStyle(attributes, declarations.join('; '));
+    assertStyleIsRepresentable(style);
+    const serialized = serializedStyleAttribute(style);
+    if (serialized !== undefined) {
+        appendStyle(attributes, serialized);
     }
 };
 const serializeAttributes = (output, attributes) => {
@@ -342,6 +369,13 @@ const NEWLINE_DROPPING_ELEMENTS = new Set([
     'pre',
     'listing',
 ]);
+// The same set plus <textarea>, which the ordinary path handles in its own
+// branch but which trusted raw HTML reaches through the shared one.
+const LEADING_NEWLINE_DROPPING_ELEMENTS = new Set([
+    'listing',
+    'pre',
+    'textarea',
+]);
 // The text the serialized content begins with, used to decide whether a
 // newline-dropping element (`pre`, `listing`, `textarea`) needs an extra
 // leading newline to survive the parser's leading-newline strip. Empty string
@@ -378,11 +412,11 @@ const leadingTextOf = (node) => {
 // real view and refused past the limit, so a hostile input becomes a typed
 // SerializationError rather than a stack overflow.
 const MAX_RENDER_DEPTH = 1000;
-const serializeChildren = (output, node, depth, selectValue) => {
+const serializeChildren = (output, context, node, depth, selectValue) => {
     const children = node.children;
     if (children !== undefined) {
         for (const child of children) {
-            serializeNode(output, child, depth + 1, undefined, selectValue);
+            serializeNode(output, context, child, depth + 1, undefined, selectValue);
         }
     }
     else if (node.text !== undefined) {
@@ -393,14 +427,106 @@ const serializeChildren = (output, node, depth, selectValue) => {
 // DOM does: `option.value` reflects the text content with ASCII whitespace
 // stripped and internal runs collapsed, so a label wrapped across source
 // lines still matches the select value.
+// NOTE: ASCII whitespace only, which is what the platform's option-value
+// algorithm strips and collapses. `String.prototype.trim` also removes a
+// non-breaking space and other Unicode whitespace, so an option labelled with
+// one computed a different value here than in a browser and the select's
+// controlled value matched the wrong option or none at all.
+const ASCII_WHITESPACE_RUN = /[\t\n\f\r ]+/g;
+const LEADING_ASCII_WHITESPACE = /^[\t\n\f\r ]+/;
+const TRAILING_ASCII_WHITESPACE = /[\t\n\f\r ]+$/;
+// The state an element is in once it exists, read from the typed property and
+// the raw attribute together rather than from either alone.
+//
+// A typed property decides, because the client assigns it over whatever the
+// attribute said and the serializer writes it over whatever the attribute said.
+// A raw attribute stands only where no typed property claims the same name, and
+// it is matched ASCII-case-insensitively, because that is how a parser and
+// `setAttribute` read an HTML attribute name: `h.Attribute('MULTIPLE', '')`
+// names the same attribute as `h.Attribute('multiple', '')`, and reading only
+// the literal spelling took a select a browser renders multi-line for a
+// single-line one.
+const effectiveAttribute = (node, name) => {
+    const raw = htmlAttributeValue(node.data?.attrs, name);
+    return typeof raw === 'string' ? raw : undefined;
+};
+const effectiveBoolean = (node, propertyName, attributeName) => {
+    const property = node.data?.props?.[propertyName];
+    if (typeof property === 'boolean') {
+        return property;
+    }
+    return htmlAttributeValue(node.data?.attrs, attributeName) !== undefined;
+};
+// A non-negative integer attribute the way a browser parses one: leading ASCII
+// whitespace is skipped, the leading run of ASCII digits is the number, and the
+// rest is ignored, so `1.5` is 1 and ` 4 ` is 4. A value past the unsigned long
+// range leaves the attribute invalid and the element on its own default.
+// `Number.parseInt` alone read `0x10` as 16 and `4e9` as 4, neither of which a
+// browser reads that way here. Every case below was measured in Chromium.
+const LEADING_DIGIT_RUN = /^[\t\n\f\r ]*([0-9]+)/;
+const UNSIGNED_LONG_MAXIMUM = 4294967295;
+const parsedNonNegativeInteger = (text) => {
+    const digits = LEADING_DIGIT_RUN.exec(text)?.[1];
+    if (digits === undefined) {
+        return undefined;
+    }
+    const parsed = Number(digits);
+    return parsed > UNSIGNED_LONG_MAXIMUM ? undefined : parsed;
+};
 const optionValue = (node) => {
     const value = node.data?.props?.['value'];
     if (typeof value === 'string') {
         return value;
     }
+    const rawValue = effectiveAttribute(node, 'value');
+    if (rawValue !== undefined) {
+        return rawValue;
+    }
     return collectRawText(node)
-        .replace(/[\t\n\f\r ]+/g, ' ')
-        .trim();
+        .replace(ASCII_WHITESPACE_RUN, ' ')
+        .replace(LEADING_ASCII_WHITESPACE, '')
+        .replace(TRAILING_ASCII_WHITESPACE, '');
+};
+// A `<select>` that is `multiple`, or that shows more than one row, can render
+// with nothing selected. A plain single-line select cannot: HTML gives the
+// first option the selection when no option carries `selected`, so a controlled
+// value naming no option has no representation in source markup.
+// Whether the element can render with nothing selected. A raw attribute counts
+// as much as a typed property: the browser reads either the same way, so
+// analysing only `data.props` accepted a controlled missing value on a select
+// that a browser renders single-line.
+//
+// A select with no options at all is included. Both a served empty select and a
+// freshly built one hold no selection, so a controlled value matching nothing
+// is not a disagreement there.
+const displayedRowCount = (node, isMultiple) => {
+    const property = node.data?.props?.['size'];
+    const size = typeof property === 'number'
+        ? property
+        : (() => {
+            const raw = effectiveAttribute(node, 'size');
+            return raw === undefined ? undefined : parsedNonNegativeInteger(raw);
+        })();
+    if (size !== undefined && size > 0) {
+        return size;
+    }
+    // A `size` of zero, absent, or unreadable leaves the browser's own default,
+    // which is four rows for a multiple select and one for a single-line one.
+    return isMultiple ? MULTIPLE_SELECT_DEFAULT_ROWS : 1;
+};
+const MULTIPLE_SELECT_DEFAULT_ROWS = 4;
+const hasOptionDescendant = (node) => (node.children ?? []).some(child => {
+    if (typeof child === 'string' || child.sel === undefined) {
+        return false;
+    }
+    const tagName = tagNameFromSelector(child.sel).toLowerCase();
+    return tagName === 'option' || hasOptionDescendant(child);
+});
+const allowsNoSelection = (node) => {
+    const isMultiple = effectiveBoolean(node, 'multiple', 'multiple');
+    return (isMultiple ||
+        displayedRowCount(node, isMultiple) > 1 ||
+        !hasOptionDescendant(node));
 };
 const selectValueForChildren = (tagName, node, inherited) => {
     if (tagName !== 'select') {
@@ -408,38 +534,73 @@ const selectValueForChildren = (tagName, node, inherited) => {
     }
     const value = node.data?.props?.['value'];
     if (typeof value === 'string') {
-        return { value, consumed: false };
+        return {
+            value,
+            consumed: false,
+            allowsNoSelection: allowsNoSelection(node),
+        };
     }
     return undefined;
 };
-const serializeElement = (output, node, selector, depth, extraAttributes, selectValue) => {
-    const tagName = tagNameFromSelector(selector);
-    if (!TAG_NAME_PATTERN.test(tagName)) {
-        throw new Error(`[foldkit] Cannot serialize the invalid tag name "${tagName}". Tag ` +
+const serializeElement = (output, context, node, selector, depth, extraAttributes, selectValue) => {
+    const authoredTagName = tagNameFromSelector(selector);
+    if (!TAG_NAME_PATTERN.test(authoredTagName)) {
+        throw new Error(`[foldkit] Cannot serialize the invalid tag name "${authoredTagName}". Tag ` +
             'names must start with a letter and use only letters, numbers, ' +
             'hyphens, dots, and underscores.');
     }
     const data = node.data;
     const isForeignNamespace = data?.ns !== undefined;
+    // NOTE: HTML tag names are ASCII case-insensitive. Canonicalize them before
+    // applying element-specific serialization rules so a dynamic `SELECT`
+    // behaves like the `HTMLSelectElement` a fresh client render creates. SVG
+    // and MathML names remain case-sensitive; the parse-equivalence check rejects
+    // a spelling that the HTML parser would adjust.
+    const tagName = isForeignNamespace
+        ? authoredTagName
+        : authoredTagName.toLowerCase();
+    const isCustomElement = !isForeignNamespace && tagName.includes('-');
     const attributes = new Map();
     if (data !== undefined) {
         collectDataAttributes(attributes, data);
         const properties = data.props;
         if (properties !== undefined) {
-            collectPropertyAttributes(attributes, tagName, properties);
+            collectPropertyAttributes(attributes, tagName, properties, isCustomElement, isForeignNamespace);
         }
         const style = data.style;
         if (style !== undefined) {
+            if (htmlAttributeValue(data.attrs, 'style') !== undefined) {
+                throw new Error('[foldkit] An element was given both typed style data and a raw ' +
+                    'style attribute. Keep one owner for the inline declaration block.');
+            }
             collectStyleAttribute(attributes, style);
         }
     }
+    // A controlled `<select>` owns which option is selected, the way the DOM
+    // `value` setter does: it takes the first option whose value matches and
+    // leaves every other one unselected. An option's own `selected` is therefore
+    // cleared inside a controlled select, since keeping both would let a browser
+    // give the later `selected` option ownership while a fresh client render
+    // reasserted the select's value and chose the earlier one.
     if (!isForeignNamespace &&
         tagName === 'option' &&
-        selectValue !== undefined &&
-        !selectValue.consumed &&
-        optionValue(node) === selectValue.value) {
-        setAttribute(attributes, 'selected', '');
-        selectValue.consumed = true;
+        selectValue !== undefined) {
+        const optionProperties = node.data?.props;
+        if (hasTrustedInnerHtml(optionProperties) &&
+            optionProperties?.['value'] === undefined) {
+            throw new Error('[foldkit] An <option> inside a controlled <select> was given ' +
+                'h.InnerHTML and no value. The option\u2019s value would come from ' +
+                'text this render cannot see inside the raw fragment, so the select ' +
+                'could select the wrong option or none at all. Give the option an ' +
+                'explicit h.Value.');
+        }
+        if (!selectValue.consumed && optionValue(node) === selectValue.value) {
+            setAttribute(attributes, 'selected', '');
+            selectValue.consumed = true;
+        }
+        else {
+            attributes.delete('selected');
+        }
     }
     if (extraAttributes !== undefined) {
         for (const name of Object.keys(extraAttributes)) {
@@ -449,6 +610,33 @@ const serializeElement = (output, node, selector, depth, extraAttributes, select
             }
         }
     }
+    // The server HTML does not otherwise carry a vnode's key or identity, so
+    // hydration would adopt keyed children positionally. Stamp a fingerprint of
+    // each so hydration can verify it is adopting the same logical entity without
+    // the raw key or source identity appearing in public markup; it strips the
+    // markers as it adopts.
+    if (context.emitHydrationMarkers) {
+        if (node.key !== undefined) {
+            const keyMarker = hydrationKeyMarker(node.key);
+            if (keyMarker === undefined) {
+                if (typeof node.key === 'number' && Number.isNaN(node.key)) {
+                    throw new Error('[foldkit] Cannot server-render an element keyed by NaN as ' +
+                        'hydratable. NaN is not equal to itself, so hydration cannot ' +
+                        'tell whether the server and client mean the same element. ' +
+                        'Key hydratable elements by a string or a number other than NaN.');
+                }
+                throw new Error('[foldkit] Cannot server-render an element keyed by a symbol. A ' +
+                    'symbol key cannot be compared across the server and the client ' +
+                    '(a local symbol is a new value in every realm, so hydration ' +
+                    'could not tell two rows apart). Key hydratable elements by a ' +
+                    'string or a number.');
+            }
+            setAttribute(attributes, HYDRATION_KEY_ATTRIBUTE, keyMarker);
+        }
+        if (node.identity !== undefined) {
+            setAttribute(attributes, HYDRATION_IDENTITY_ATTRIBUTE, hydrationIdentityMarker(node.identity));
+        }
+    }
     output.push(`<${tagName}`);
     serializeAttributes(output, attributes);
     output.push('>');
@@ -466,11 +654,30 @@ const serializeElement = (output, node, selector, depth, extraAttributes, select
         ? undefined
         : selectValueForChildren(tagName, node, selectValue);
     const isHtmlRawText = !isForeignNamespace && RAW_TEXT_ELEMENTS.has(tagName);
+    const isHtmlRcdata = !isForeignNamespace && RCDATA_ELEMENTS.has(tagName);
     const innerHtml = data?.props?.['innerHTML'];
-    if (typeof innerHtml === 'string') {
-        if (isHtmlRawText) {
+    if (typeof innerHtml === 'string' && hasTrustedInnerHtml(data?.props)) {
+        // Trusted raw HTML still cannot end the element that holds it. An RCDATA
+        // element ends at its own closing tag exactly as a raw-text one does, so
+        // markup written into a <textarea> or <title> would otherwise close it and
+        // put the rest of the fragment in the document.
+        if (isHtmlRawText || isHtmlRcdata) {
             assertRawTextIsSafe(tagName, innerHtml);
         }
+        // NOTE: one literal newline, always, for the elements whose parser drops
+        // one. The document parser consumes exactly this prefix, so whatever the
+        // fragment itself begins with survives unchanged, which is what assigning
+        // the same string to `element.innerHTML` on the client produces.
+        //
+        // Testing whether the fragment starts with a literal `\n` is not enough:
+        // tokenization also produces a leading newline from a character reference
+        // (`&#10;`, `&#xA;`, `&NewLine;`) and from input preprocessing turning CR
+        // or CRLF into LF, none of which is a literal newline in the source bytes.
+        // An unconditional prefix covers every one of them, and costs an empty
+        // fragment nothing.
+        if (!isForeignNamespace && LEADING_NEWLINE_DROPPING_ELEMENTS.has(tagName)) {
+            output.push('\n');
+        }
         output.push(innerHtml);
     }
     else if (!isForeignNamespace && tagName === 'textarea') {
@@ -485,7 +692,7 @@ const serializeElement = (output, node, selector, depth, extraAttributes, select
             if (leadingTextOf(node)?.startsWith('\n')) {
                 output.push('\n');
             }
-            serializeChildren(output, node, depth, childSelectValue);
+            serializeChildren(output, context, node, depth, childSelectValue);
         }
     }
     else if (!isForeignNamespace && tagName === 'output') {
@@ -497,26 +704,40 @@ const serializeElement = (output, node, selector, depth, extraAttributes, select
             output.push(escapeText(content));
         }
         else {
-            serializeChildren(output, node, depth, childSelectValue);
+            serializeChildren(output, context, node, depth, childSelectValue);
         }
     }
     else if (!isForeignNamespace && NEWLINE_DROPPING_ELEMENTS.has(tagName)) {
         if (leadingTextOf(node)?.startsWith('\n')) {
             output.push('\n');
         }
-        serializeChildren(output, node, depth, childSelectValue);
+        serializeChildren(output, context, node, depth, childSelectValue);
     }
     else if (isHtmlRawText) {
         const rawText = collectRawText(node);
         assertRawTextIsSafe(tagName, rawText);
+        if (tagName === 'noscript') {
+            assertNoscriptTextIsSafe(rawText);
+        }
         output.push(rawText);
     }
     else {
-        serializeChildren(output, node, depth, childSelectValue);
+        serializeChildren(output, context, node, depth, childSelectValue);
+    }
+    if (childSelectValue !== undefined &&
+        childSelectValue !== selectValue &&
+        !childSelectValue.consumed &&
+        !childSelectValue.allowsNoSelection) {
+        throw new Error(`[foldkit] A <select> has the controlled value "${childSelectValue.value}" ` +
+            'but no option carries it. A single-line select cannot render with ' +
+            'nothing selected: HTML gives the first option the selection, while ' +
+            'the client sets `value` and lands on no selection at all, so the ' +
+            'served page and the hydrated one would disagree. Render an option ' +
+            'with that value, add a placeholder option, or use `multiple`.');
     }
     output.push(`</${tagName}>`);
 };
-const serializeNode = (output, node, depth, extraAttributes, selectValue) => {
+const serializeNode = (output, context, node, depth, extraAttributes, selectValue) => {
     if (depth > MAX_RENDER_DEPTH) {
         throw new Error(`[foldkit] renderToString exceeded the maximum render depth of ${MAX_RENDER_DEPTH}. ` +
             'A view nesting elements this deeply, often from mapping untrusted ' +
@@ -543,13 +764,18 @@ const serializeNode = (output, node, depth, extraAttributes, selectValue) => {
         output.push(`<!--${commentText}-->`);
         return;
     }
-    serializeElement(output, node, selector, depth, extraAttributes, selectValue);
+    serializeElement(output, context, node, selector, depth, extraAttributes, selectValue);
 };
-/** Serializes a view-produced vnode tree to an HTML string. Event handlers,
- *  hooks, keys, and identity are behavior, not markup, and are skipped;
- *  attrs, class, dataset, prop-backed attributes, and inline style are
- *  emitted in that order. A `null` tree serializes to an empty comment,
- *  mirroring how the runtime patches `null` as a comment node.
+/** Serializes a view-produced vnode tree to an HTML string. Event handlers and
+ *  hooks are behavior, not markup, and are skipped; attrs, class, dataset,
+ *  prop-backed attributes, and inline style are emitted in that order. A `null`
+ *  tree serializes to an empty comment, mirroring how the runtime patches
+ *  `null` as a comment node.
+ *
+ * A hydratable render also stamps a fingerprint of each vnode's key and
+ * identity, so hydration can tell one logical entity from another; the raw key
+ * and the compiler's source identity never appear in the markup. A render that
+ * is not hydratable emits neither.
  *
  * @internal Not part of the `foldkit/experimental/server` surface; `renderToString` is the public entry to serialization.
  */
@@ -557,7 +783,10 @@ export const serializeHtml = (root, options) => {
     if (root === null) {
         return '<!---->';
     }
+    const context = {
+        emitHydrationMarkers: options?.emitHydrationMarkers ?? false,
+    };
     const output = [];
-    serializeNode(output, root, 0, options?.rootAttributes);
+    serializeNode(output, context, root, 0, options?.rootAttributes);
     return output.join('');
 };