foldkit 0.147.0 → 0.148.0

package/dist/html/index.js

@@ -1,6 +1,10 @@
 import { Array, Context, Data, Effect, Fiber, Function, Option, Schema as S, Stream, } from 'effect';
+import { restoreUncontrolledContent, synchronizeControlledDefault, } from '../controlledDomState.js';
+import { FOREIGN_REPRESENTABLE_PROPERTIES, assertStyleIsRepresentable, htmlAttributeValue, isHtmlPropertyRepresentable, normalizedStyleProperties, reflectedAttributeName, } from '../domReflection.js';
 import { MountTracker } from '../mount/index.js';
+import { hasTrustedInnerHtml, isClientOnlyProperty, markClientOnlyProperty, markTrustedInnerHtml, unmarkClientOnlyProperty, } from '../propertyProvenance.js';
 import { VNodeDataMask, h, vnodeDataMaskKey, } from '../snabbdom/index.js';
+import { tagNameFromSelector } from '../tagName.js';
 import { isChildAttribute } from './childAttribute.js';
 import { checkScheduledLeave, clearDragZoneAfterDrop, getDragZoneState, processDragEnter, processDragLeave, } from './dragZoneTracking.js';
 import { clearRuntime, requireBoundaryMappers, requireDispatch, requireRuntimeContext, requireUnmountResolver, setRuntime, } from './runtimeSingleton.js';
@@ -110,11 +114,45 @@ const setModuleData = (ctx, key, value, dataMask) => {
 // NOTE: single-key fast paths. The bulk of attribute handlers set exactly
 // one prop, attr, or event handler; writing it directly into the vnode data
 // avoids allocating a `{ key: value }` literal and merging it per attribute.
-const setDataProp = (ctx, key, value) => {
+const writeDataProp = (ctx, key, value) => {
     /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
     const props = (ctx.data.props ??= {});
-    props[key] = value;
+    Object.defineProperty(props, key, {
+        configurable: true,
+        enumerable: true,
+        value,
+        writable: true,
+    });
     addVNodeDataMask(ctx, VNodeDataMask.Props);
+    return props;
+};
+// A typed attribute builder writes the DOM property that reflects the HTML
+// attribute it is named after, so the server serializer can emit it as that
+// attribute even on a custom element, where a same-named component property
+// would mean something else entirely. Overwriting a property a generic write
+// left behind takes the name back, so the mark always describes the value that
+// is actually in the bag. The unmark is a no-op unless a generic write happened
+// on this element, which keeps the common path free of any bookkeeping.
+const setDataProp = (ctx, key, value) => {
+    const props = writeDataProp(ctx, key, value);
+    unmarkClientOnlyProperty(props, key);
+};
+// `Prop` writes a DOM property and claims nothing about what it means: the
+// value may be a client-only component property, and the name may collide with
+// one an attribute builder owns. `CustomElement.define` property factories
+// produce `Prop`, so a declared component property lands here too.
+const setClientOnlyDataProp = (ctx, key, value) => {
+    const props = writeDataProp(ctx, key, value);
+    markClientOnlyProperty(props, key);
+};
+// NOTE: `h.InnerHTML` marks the value it wrote as markup the view author intends
+// to be parsed as HTML, which is what lets the server serializer write it to the
+// raw sink. A custom-element property or raw `Prop` named `innerHTML` marks the
+// same key client-only instead. The marks are mutually exclusive, so the last
+// builder owns the key even when both builders wrote exactly the same string.
+const setTrustedInnerHtml = (ctx, value) => {
+    const props = writeDataProp(ctx, 'innerHTML', value);
+    markTrustedInnerHtml(props, value);
 };
 const setDataAttr = (ctx, key, value) => {
     /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
@@ -176,6 +214,62 @@ const updateDataOn = (ctx, on) => {
         }
     }
 };
+// The values a numeric builder accepts, per property.
+//
+// The server writes these as attribute text and a browser parses them; the
+// client assigns them through the DOM property. The two do not agree
+// everywhere. Assigning a negative `maxLength` throws IndexSizeError while the
+// attribute parses to -1; `size = 0` throws while the attribute falls back to
+// 20; `Infinity` and `NaN` become 0 through the property and the attribute's own
+// default through the parser; and past 2^31 the property conversions wrap while
+// the attribute clamps.
+//
+// The bounds below were measured in Chromium: within them, a parsed attribute
+// and a direct assignment produce the same property for every builder here.
+// Outside them the two disagree or the assignment throws, so the value is
+// refused where it is written rather than diverging once served.
+const SIGNED_LONG_MAXIMUM = 2147483647;
+const SIGNED_LONG_MINIMUM = -SIGNED_LONG_MAXIMUM - 1;
+const NUMERIC_PROPERTY_RANGES = {
+    cols: { minimum: 0, maximum: SIGNED_LONG_MAXIMUM },
+    colSpan: { minimum: 0, maximum: SIGNED_LONG_MAXIMUM },
+    maxLength: { minimum: 0, maximum: SIGNED_LONG_MAXIMUM },
+    minLength: { minimum: 0, maximum: SIGNED_LONG_MAXIMUM },
+    rows: { minimum: 0, maximum: SIGNED_LONG_MAXIMUM },
+    rowSpan: { minimum: 0, maximum: SIGNED_LONG_MAXIMUM },
+    size: { minimum: 0, maximum: SIGNED_LONG_MAXIMUM },
+    span: { minimum: 0, maximum: SIGNED_LONG_MAXIMUM },
+    // An ordered list may start anywhere, and negatives agree on both sides.
+    start: { minimum: SIGNED_LONG_MINIMUM, maximum: SIGNED_LONG_MAXIMUM },
+    // Any element can carry one, and the two sides agree across the whole signed
+    // long range. Outside it they part company in a way no value hints at: an
+    // out-of-range assignment wraps (2147483648 becomes -2147483648) while the
+    // attribute falls back to the element's default, which is 0 on a focusable
+    // element and -1 on any other, so the same view yields a focusable served
+    // element and an unreachable fresh one.
+    tabIndex: { minimum: SIGNED_LONG_MINIMUM, maximum: SIGNED_LONG_MAXIMUM },
+};
+const numericPropertyRefusal = (propName, value) => `[foldkit] ${propName} was given ${String(value)}, which a browser reads ` +
+    'differently depending on whether it arrives as parsed markup or as a ' +
+    'property assignment, and which can throw outright when assigned. ';
+const setNumericDataProp = (ctx, propName, value) => {
+    const range = NUMERIC_PROPERTY_RANGES[propName];
+    if (range !== undefined &&
+        !(Number.isInteger(value) &&
+            value >= range.minimum &&
+            value <= range.maximum)) {
+        throw new Error(numericPropertyRefusal(propName, value) +
+            `Use an integer from ${String(range.minimum)} to ` +
+            `${String(range.maximum)}.`);
+    }
+    setDataProp(ctx, propName, value);
+};
+const setFiniteNumericDataProp = (ctx, propName, value) => {
+    if (!Number.isFinite(value)) {
+        throw new Error(numericPropertyRefusal(propName, value) + 'Use a finite number.');
+    }
+    setDataProp(ctx, propName, value);
+};
 const updatePropsWithPostpatch = (ctx, propName, value) => {
     setDataProp(ctx, propName, value);
     ctx.getPostpatchProps().push({ propName, value });
@@ -238,7 +332,7 @@ const attributeHandlers = {
     Title: ({ value }, ctx) => setDataProp(ctx, 'title', value),
     Lang: ({ value }, ctx) => setDataProp(ctx, 'lang', value),
     Dir: ({ value }, ctx) => setDataProp(ctx, 'dir', value),
-    Tabindex: ({ value }, ctx) => setDataProp(ctx, 'tabIndex', value),
+    Tabindex: ({ value }, ctx) => setNumericDataProp(ctx, 'tabIndex', value),
     Hidden: ({ value }, ctx) => setDataProp(ctx, 'hidden', value),
     Contenteditable: ({ value }, ctx) => setDataAttr(ctx, 'contenteditable', value),
     Draggable: ({ value }, ctx) => setDataProp(ctx, 'draggable', value),
@@ -536,11 +630,11 @@ const attributeHandlers = {
     Accept: ({ value }, ctx) => setDataProp(ctx, 'accept', value),
     Autocomplete: ({ value }, ctx) => setDataProp(ctx, 'autocomplete', value),
     Pattern: ({ value }, ctx) => setDataProp(ctx, 'pattern', value),
-    Maxlength: ({ value }, ctx) => setDataProp(ctx, 'maxLength', value),
-    Minlength: ({ value }, ctx) => setDataProp(ctx, 'minLength', value),
-    Size: ({ value }, ctx) => setDataProp(ctx, 'size', value),
-    Cols: ({ value }, ctx) => setDataProp(ctx, 'cols', value),
-    Rows: ({ value }, ctx) => setDataProp(ctx, 'rows', value),
+    Maxlength: ({ value }, ctx) => setNumericDataProp(ctx, 'maxLength', value),
+    Minlength: ({ value }, ctx) => setNumericDataProp(ctx, 'minLength', value),
+    Size: ({ value }, ctx) => setNumericDataProp(ctx, 'size', value),
+    Cols: ({ value }, ctx) => setNumericDataProp(ctx, 'cols', value),
+    Rows: ({ value }, ctx) => setNumericDataProp(ctx, 'rows', value),
     Max: ({ value }, ctx) => setDataProp(ctx, 'max', value),
     Min: ({ value }, ctx) => setDataProp(ctx, 'min', value),
     Step: ({ value }, ctx) => setDataProp(ctx, 'step', value),
@@ -560,12 +654,12 @@ const attributeHandlers = {
     Formnovalidate: ({ value }, ctx) => setDataProp(ctx, 'formNoValidate', value),
     Formtarget: ({ value }, ctx) => setDataProp(ctx, 'formTarget', value),
     Formenctype: ({ value }, ctx) => setDataProp(ctx, 'formEnctype', value),
-    Colspan: ({ value }, ctx) => setDataProp(ctx, 'colSpan', value),
-    Rowspan: ({ value }, ctx) => setDataProp(ctx, 'rowSpan', value),
+    Colspan: ({ value }, ctx) => setNumericDataProp(ctx, 'colSpan', value),
+    Rowspan: ({ value }, ctx) => setNumericDataProp(ctx, 'rowSpan', value),
     Scope: ({ value }, ctx) => setDataAttr(ctx, 'scope', value),
     Headers: ({ value }, ctx) => setDataAttr(ctx, 'headers', value),
-    Span: ({ value }, ctx) => setDataProp(ctx, 'span', value),
-    Start: ({ value }, ctx) => setDataProp(ctx, 'start', value),
+    Span: ({ value }, ctx) => setNumericDataProp(ctx, 'span', value),
+    Start: ({ value }, ctx) => setNumericDataProp(ctx, 'start', value),
     Reversed: ({ value }, ctx) => setDataProp(ctx, 'reversed', value),
     CiteAttr: ({ value }, ctx) => setDataProp(ctx, 'cite', value),
     Datetime: ({ value }, ctx) => setDataProp(ctx, 'dateTime', value),
@@ -596,9 +690,9 @@ const attributeHandlers = {
     Poster: ({ value }, ctx) => setDataProp(ctx, 'poster', value),
     Preload: ({ value }, ctx) => setDataProp(ctx, 'preload', value),
     Playsinline: ({ value }, ctx) => setDataProp(ctx, 'playsInline', value),
-    High: ({ value }, ctx) => setDataProp(ctx, 'high', value),
-    Low: ({ value }, ctx) => setDataProp(ctx, 'low', value),
-    Optimum: ({ value }, ctx) => setDataProp(ctx, 'optimum', value),
+    High: ({ value }, ctx) => setFiniteNumericDataProp(ctx, 'high', value),
+    Low: ({ value }, ctx) => setFiniteNumericDataProp(ctx, 'low', value),
+    Optimum: ({ value }, ctx) => setFiniteNumericDataProp(ctx, 'optimum', value),
     Usemap: ({ value }, ctx) => setDataAttr(ctx, 'usemap', value),
     Ismap: ({ value }, ctx) => setDataProp(ctx, 'isMap', value),
     Role: ({ value }, ctx) => setDataAttr(ctx, 'role', value),
@@ -650,8 +744,8 @@ const attributeHandlers = {
     AriaValuetext: ({ value }, ctx) => setDataAttr(ctx, 'aria-valuetext', value),
     Attribute: ({ key, value }, ctx) => setDataAttr(ctx, key, value),
     DataAttribute: ({ key, value }, ctx) => setDataAttr(ctx, `data-${key}`, value),
-    Style: ({ value }, ctx) => setModuleData(ctx, 'style', value, VNodeDataMask.Style),
-    InnerHTML: ({ value }, ctx) => setDataProp(ctx, 'innerHTML', value),
+    Style: ({ value }, ctx) => setModuleData(ctx, 'style', normalizedStyleProperties(value), VNodeDataMask.Style),
+    InnerHTML: ({ value }, ctx) => setTrustedInnerHtml(ctx, value),
     ViewBox: ({ value }, ctx) => setDataAttr(ctx, 'viewBox', value),
     Xmlns: ({ value }, ctx) => setDataAttr(ctx, 'xmlns', value),
     Fill: ({ value }, ctx) => setDataAttr(ctx, 'fill', value),
@@ -742,7 +836,7 @@ const attributeHandlers = {
     RefY: ({ value }, ctx) => setDataAttr(ctx, 'refY', value),
     Orient: ({ value }, ctx) => setDataAttr(ctx, 'orient', value),
     PreserveAspectRatio: ({ value }, ctx) => setDataAttr(ctx, 'preserveAspectRatio', value),
-    Prop: ({ key, value }, ctx) => setDataProp(ctx, key, value),
+    Prop: ({ key, value }, ctx) => setClientOnlyDataProp(ctx, key, value),
     OnCustomEvent: ({ name, f: toMessage }, ctx) => updateDataOn(ctx, {
         [name]: (event) => {
             if (event instanceof CustomEvent) {
@@ -868,19 +962,58 @@ const capturedContextOrEmpty = () => {
         return Context.empty();
     }
 };
+// NOTE: reasserted on `insert` as well as on `postpatch`. The props module sets
+// a controlled property while the element is being created, before its children
+// exist, and a `<select>`'s `value` setter has nothing to match against until
+// its `<option>`s are there, so a fresh render left the select on the browser's
+// own default until some later patch corrected it. The server instead marks the
+// matching option, so the served page was right and the fresh one was not.
+// `insert` fires once the subtree is built, which is where the two agree.
+const applyControlledProps = (vnode, controlledProps) => {
+    if (!vnode.elm) {
+        return;
+    }
+    Array.forEach(controlledProps, ({ propName, value }) => {
+        const isOutputValue = vnode.elm instanceof Element &&
+            vnode.elm.localName === 'output' &&
+            propName === 'value';
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        if (isOutputValue || vnode.elm[propName] !== value) {
+            /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+            ;
+            vnode.elm[propName] = value;
+        }
+        if (vnode.elm instanceof Element) {
+            synchronizeControlledDefault(vnode.elm, propName, value);
+        }
+    });
+};
 const attachPostpatchHook = (data, postpatchProps) => {
+    const existingInsert = data.hook?.insert;
     data.hook = {
         ...data.hook,
+        insert: vnode => {
+            applyControlledProps(vnode, postpatchProps);
+            existingInsert?.(vnode);
+        },
         postpatch: (_oldVnode, vnode) => {
-            if (vnode.elm) {
-                Array.forEach(postpatchProps, ({ propName, value }) => {
-                    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
-                    if (vnode.elm[propName] !== value) {
-                        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
-                        ;
-                        vnode.elm[propName] = value;
-                    }
-                });
+            applyControlledProps(vnode, postpatchProps);
+        },
+    };
+};
+const attachControlledContentOwnershipHook = (data) => {
+    const existingPostpatch = data.hook?.postpatch;
+    data.hook = {
+        ...data.hook,
+        postpatch: (oldVnode, vnode) => {
+            existingPostpatch?.(oldVnode, vnode);
+            const oldProperties = oldVnode.data?.props;
+            const properties = vnode.data?.props;
+            if (oldProperties !== undefined &&
+                Object.hasOwn(oldProperties, 'value') &&
+                (properties === undefined || !Object.hasOwn(properties, 'value')) &&
+                vnode.elm instanceof Element) {
+                restoreUncontrolledContent(vnode.elm, vnode);
             }
         },
     };
@@ -956,14 +1089,288 @@ const copyChildrenDroppingEmpty = (children) => {
     }
     return next;
 };
-const createElement = (tagName, attributes = [], children = []) => h(tagName, buildVNodeData(attributes), copyChildrenDroppingEmpty(children));
+// Elements whose content a controlled `value` owns. Giving one both a value and
+// trusted raw HTML asks two mechanisms to own the same text.
+const CONTROLLED_CONTENT_ELEMENTS = new Set([
+    'output',
+    'select',
+    'textarea',
+]);
+// Elements that carry no content at all, so raw HTML written into one cannot be
+// represented in served markup. Assigning the property in a browser can still
+// build child nodes, which is a difference no server render can reproduce.
+const VOID_CONTENT_ELEMENTS = new Set([
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'param',
+    'source',
+    'track',
+    'wbr',
+]);
+// One owner per element's content. Both `h.InnerHTML` and a client-only
+// `innerHTML` property hand the element an opaque subtree. A view that also
+// declares children or a controlled value gives the differ child vnodes for
+// nodes the property replaces, leaving those vnodes detached and making a later
+// patch unable to restore the declared children. Trusted `h.InnerHTML` also
+// disagrees with the server serializer in these combinations. Rejecting at the
+// builder makes the server render, a fresh client render, and hydration refuse
+// the same self-contradictory view.
+const assertSingleContentOwner = (tagName, data, children) => {
+    const lowerTagName = tagName.toLowerCase();
+    if ((lowerTagName === 'textarea' || lowerTagName === 'output') &&
+        data.props?.['value'] !== undefined &&
+        children.length > 0) {
+        throw new Error(`[foldkit] <${lowerTagName}> was given both a controlled value and ` +
+            'children. Both own the element content, so a property assignment ' +
+            'replaces the child nodes the differ expects to patch. Keep one owner.');
+    }
+    const properties = data.props;
+    if (properties === undefined || !Object.hasOwn(properties, 'innerHTML')) {
+        return;
+    }
+    const innerHtmlOwner = hasTrustedInnerHtml(properties)
+        ? 'h.InnerHTML'
+        : 'a client-only innerHTML property';
+    if (children.length > 0) {
+        throw new Error(`[foldkit] <${lowerTagName}> was given both ${innerHtmlOwner} and children. ` +
+            'innerHTML owns the whole of an element\u2019s content, so the two ' +
+            'cannot both describe it: server rendering emits the raw HTML alone ' +
+            'for h.InnerHTML, while a browser property assignment replaces the ' +
+            'nodes the differ expects to patch. Keep one content owner.');
+    }
+    if (CONTROLLED_CONTENT_ELEMENTS.has(lowerTagName) &&
+        data.props?.['value'] !== undefined) {
+        throw new Error(`[foldkit] <${lowerTagName}> was given both ${innerHtmlOwner} and a ` +
+            'controlled value. Both own this element\u2019s content, and they ' +
+            'disagree once the client reasserts the value. Keep one of them.');
+    }
+    if (VOID_CONTENT_ELEMENTS.has(lowerTagName)) {
+        throw new Error(`[foldkit] <${lowerTagName}> cannot hold content, so ${innerHtmlOwner} ` +
+            'on it ' +
+            'has no representation in served HTML. A browser can still build ' +
+            'child nodes from the property, which no server render reproduces. ' +
+            'Remove the innerHTML value.');
+    }
+};
+const assertSingleStyleOwner = (data) => {
+    if (data.style === undefined ||
+        htmlAttributeValue(data.attrs, 'style') === undefined) {
+        return;
+    }
+    throw new Error('[foldkit] An element was given both h.Style and a raw ' +
+        "h.Attribute('style', ...). They are two owners of one declaration " +
+        'block, and CSS parsing can make one swallow or override the other. ' +
+        'Keep all inline declarations in one of them.');
+};
+// The state an element would be in once it exists, read from the tag, the raw
+// attributes, and the typed properties together. A builder on its own cannot
+// decide any of this: `h.Value` is a string on an input and a number on a
+// meter, `type="file"` refuses the value an input takes everywhere else, and a
+// raw attribute means nothing until something says which property claims the
+// same name.
+//
+// Each rule below marks a view whose server render and fresh client render
+// cannot agree. Refusing it where it is written is what makes the two, plus a
+// hydration of the first by the second, fail the same way rather than diverge
+// quietly.
+// A number both a parser and an assignment read identically: ASCII digits, one
+// optional leading minus, an optional fraction, an optional exponent. Anything
+// else parts the two: `0x10` is 16 to `Number` and invalid to the parser, a
+// leading `+` or surrounding whitespace is accepted by one and not the other,
+// and `Infinity` throws on assignment while the attribute falls back to the
+// element's default.
+const DECIMAL_NUMBER = /^-?[0-9]+(\.[0-9]+)?([eE][-+]?[0-9]+)?$/;
+const DECIMAL_INTEGER = /^-?[0-9]+$/;
+// Properties the DOM defines as numbers on these elements and as strings
+// elsewhere, so the same builder means different things depending on where it
+// is written.
+const DOUBLE_IDL_PROPERTIES = {
+    meter: new Set(['high', 'low', 'max', 'min', 'optimum', 'value']),
+    progress: new Set(['max', 'value']),
+};
+const LONG_IDL_PROPERTIES = {
+    li: new Set(['value']),
+};
+const assertDoubleIdlValue = (tagName, propName, value) => {
+    const isRepresentable = typeof value === 'number'
+        ? Number.isFinite(value)
+        : typeof value === 'string' &&
+            DECIMAL_NUMBER.test(value) &&
+            Number.isFinite(Number(value));
+    if (!isRepresentable) {
+        throw new Error(`[foldkit] <${tagName}> reads ${propName} as a number, and ` +
+            `${JSON.stringify(value)} is not one a browser reads the same way from ` +
+            'markup and from a property assignment. Use a finite decimal number.');
+    }
+};
+const assertLongIdlValue = (tagName, propName, value) => {
+    const parsed = typeof value === 'number'
+        ? value
+        : typeof value === 'string' && DECIMAL_INTEGER.test(value)
+            ? Number(value)
+            : Number.NaN;
+    if (!Number.isInteger(parsed) ||
+        parsed < SIGNED_LONG_MINIMUM ||
+        parsed > SIGNED_LONG_MAXIMUM) {
+        throw new Error(`[foldkit] <${tagName}> reads ${propName} as an integer, and ` +
+            `${JSON.stringify(value)} is not one a browser reads the same way from ` +
+            'markup and from a property assignment. Use an integer from ' +
+            `${String(SIGNED_LONG_MINIMUM)} to ${String(SIGNED_LONG_MAXIMUM)}.`);
+    }
+};
+const effectiveInputType = (data) => {
+    const typed = data.props?.['type'];
+    if (typeof typed === 'string') {
+        return typed.toLowerCase();
+    }
+    const raw = htmlAttributeValue(data.attrs, 'type');
+    return typeof raw === 'string' ? raw.toLowerCase() : undefined;
+};
+const assertElementStateIsRepresentable = (tagName, data) => {
+    const props = data.props;
+    if (props === undefined) {
+        return;
+    }
+    const lowerTagName = tagName.toLowerCase();
+    const doubleIdl = DOUBLE_IDL_PROPERTIES[lowerTagName];
+    const longIdl = LONG_IDL_PROPERTIES[lowerTagName];
+    for (const propName of Object.keys(props)) {
+        const value = props[propName];
+        if (value === undefined || propName === 'innerHTML') {
+            continue;
+        }
+        if (doubleIdl?.has(propName) === true) {
+            assertDoubleIdlValue(lowerTagName, propName, value);
+        }
+        if (longIdl?.has(propName) === true) {
+            assertLongIdlValue(lowerTagName, propName, value);
+        }
+        if (lowerTagName === 'input' && propName === 'size' && value === 0) {
+            throw new Error(numericPropertyRefusal(propName, value) +
+                `Use an integer from 1 to ${String(SIGNED_LONG_MAXIMUM)} on an input.`);
+        }
+        // A raw attribute and a typed builder that name the same attribute are two
+        // owners of one piece of state, and their served form has no source
+        // spelling. `h.Attribute('checked', '')` with `h.Checked(false)` serves no
+        // attribute at all, so the served element has `defaultChecked` false while
+        // a fresh render parses the attribute and has it true: `form.reset()`,
+        // `:default`, and an attribute selector then read the two pages
+        // differently. A client-only property carries no such claim, so a
+        // `CustomElement.define` property never conflicts with an attribute.
+        const attributeName = reflectedAttributeName(propName);
+        if (attributeName !== undefined &&
+            !isClientOnlyProperty(props, propName) &&
+            htmlAttributeValue(data.attrs, attributeName) !== undefined) {
+            throw new Error(`[foldkit] <${lowerTagName}> was given both a typed ${propName} and a ` +
+                `raw h.Attribute('${attributeName}', ...). They are two owners of ` +
+                'one attribute, and the state they describe together has no spelling ' +
+                'in served HTML: the property decides what is served while a fresh ' +
+                'render parses the attribute as the default too. Keep one of them.');
+        }
+    }
+    if (lowerTagName === 'input' && effectiveInputType(data) === 'file') {
+        const value = props['value'];
+        if (typeof value === 'string' && value !== '') {
+            throw new Error('[foldkit] <input type="file"> was given a value. A file input takes ' +
+                'no value from markup or from the Model: the served attribute is ' +
+                'ignored and assigning the property throws InvalidStateError, so the ' +
+                'view crashes on a fresh render and on hydration. Drop the value.');
+        }
+    }
+};
+// NOTE: A typed property on an HTML element whose native interface does not own it
+// has always been a client-side expando. For example, RadioGroup deliberately
+// includes `h.Type('button')` in an attribute bundle that consumers may spread
+// onto a button, div, or span. Mark the wrong-element case as client-only so
+// server rendering omits it and hydration applies the same expando a fresh
+// render does, without turning a pre-existing client pattern into live markup.
+const markUnreflectedHtmlPropertiesClientOnly = (tagName, data) => {
+    const props = data.props;
+    if (props === undefined) {
+        return;
+    }
+    for (const propName of Object.keys(props)) {
+        if (reflectedAttributeName(propName) !== undefined &&
+            !isHtmlPropertyRepresentable(tagName, propName)) {
+            markClientOnlyProperty(props, propName);
+        }
+    }
+};
+// The same question in SVG and MathML, where the answer is decided by the
+// namespace rather than by the tag. A foreign element has none of the HTML
+// interface members a typed builder writes, apart from the three measured to
+// reflect there. Assigning `href` on an SVG `<a>` throws, since bundled code is
+// strict and `SVGAElement.href` is readonly; assigning `title` sets an expando
+// no attribute ever sees. The serializer would have written an attribute for
+// both. Raw `h.Attribute` is the mechanism SVG and MathML use, and it behaves
+// identically on both sides.
+//
+// The namespace is only known once the `svg` or `math` element that introduces
+// it is built, because that is when it propagates down. The walk stops where
+// the namespace stops, so an HTML integration point such as `<foreignObject>`
+// keeps ordinary HTML rules for its content.
+const assertForeignPropertiesAreRepresentable = (node) => {
+    const data = node.data;
+    if (data === undefined || data.ns === undefined) {
+        return;
+    }
+    const props = data.props;
+    if (props !== undefined) {
+        for (const propName of Object.keys(props)) {
+            if (props[propName] === undefined ||
+                propName === 'innerHTML' ||
+                FOREIGN_REPRESENTABLE_PROPERTIES.has(propName) ||
+                reflectedAttributeName(propName) === undefined) {
+                continue;
+            }
+            throw new Error(`[foldkit] <${tagNameFromSelector(node.sel ?? '')}> is in the SVG or ` +
+                `MathML namespace, where ${propName} is not a property the element ` +
+                'has. Assigning it on the client sets a value no attribute reflects, ' +
+                'or throws outright, while server rendering writes the attribute, so ' +
+                `the two disagree. Write it as h.Attribute('${propName}', ...), ` +
+                'which foreign content reads the same way on both sides.');
+        }
+    }
+    for (const child of node.children ?? []) {
+        if (typeof child !== 'string') {
+            assertForeignPropertiesAreRepresentable(child);
+        }
+    }
+};
+const buildElement = (tagName, data, children) => {
+    const copiedChildren = copyChildrenDroppingEmpty(children);
+    markUnreflectedHtmlPropertiesClientOnly(tagName, data);
+    assertSingleContentOwner(tagName, data, copiedChildren);
+    assertSingleStyleOwner(data);
+    if (data.style !== undefined) {
+        assertStyleIsRepresentable(data.style);
+    }
+    assertElementStateIsRepresentable(tagName, data);
+    if (tagName.toLowerCase() === 'select' ||
+        tagName.toLowerCase() === 'textarea' ||
+        tagName.toLowerCase() === 'output') {
+        attachControlledContentOwnershipHook(data);
+    }
+    const built = h(tagName, data, copiedChildren);
+    assertForeignPropertiesAreRepresentable(built);
+    return built;
+};
+const createElement = (tagName, attributes = [], children = []) => buildElement(tagName, buildVNodeData(attributes), children);
 const element = () => (tagName) => (attributes = [], children = []) => createElement(tagName, attributes, children);
 export const customElement = () => (tagName) => (attributes = [], children = []) => createElement(tagName, attributes, children);
 const voidElement = () => (tagName) => (attributes = []) => createElement(tagName, attributes, []);
 const keyed = () => (tagName) => (key, attributes = [], children = []) => {
     const data = buildVNodeData(attributes);
     data.key = key;
-    return h(tagName, data, copyChildrenDroppingEmpty(children));
+    return buildElement(tagName, data, children);
 };
 const htmlElements = () => {
     const el = element();

package/dist/hydrate.d.ts

@@ -1,4 +1,4 @@
 import type { VNode } from './snabbdom/index.js';
 export declare const __elementSignature: (element: Element, vnode: VNode) => string;
-export declare const __hydrateVNode: (hydrationRoot: Element, nextVNode: VNode | null, seen?: Set<object>) => VNode;
+export declare const __hydrateVNode: (hydrationRoot: Element, nextVNode: VNode | null, seen: Set<object> | undefined, buildId: string) => VNode;
 //# sourceMappingURL=hydrate.d.ts.map

package/dist/hydrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAsJhD,eAAO,MAAM,kBAAkB,GAAI,SAAS,OAAO,EAAE,OAAO,KAAK,KAAG,MA6BnE,CAAA;AAsbD,eAAO,MAAM,cAAc,GACzB,eAAe,OAAO,EACtB,WAAW,KAAK,GAAG,IAAI,EACvB,OAAO,GAAG,CAAC,MAAM,CAAC,KACjB,KAwCF,CAAA"}
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAwPhD,eAAO,MAAM,kBAAkB,GAAI,SAAS,OAAO,EAAE,OAAO,KAAK,KAAG,MA4BnE,CAAA;AAmsBD,eAAO,MAAM,cAAc,GACzB,eAAe,OAAO,EACtB,WAAW,KAAK,GAAG,IAAI,EACvB,MAAM,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,EAC7B,SAAS,MAAM,KACd,KAwDF,CAAA"}