@microsoft/fast-element 3.0.0-rc.1 → 3.0.0-rc.2

package/dist/fast-element.js

@@ -18,6 +18,7 @@ var Message;
     Message[Message["cannotSetTemplatePolicyAfterCompilation"] = 1208] = "cannotSetTemplatePolicyAfterCompilation";
     Message[Message["blockedByDOMPolicy"] = 1209] = "blockedByDOMPolicy";
     Message[Message["invalidHydrationAttributeMarker"] = 1210] = "invalidHydrationAttributeMarker";
+    Message[Message["duplicateRenderInstruction"] = 1211] = "duplicateRenderInstruction";
     // 1301 - 1400 Styles
     // 1401 - 1500 Components
     Message[Message["missingElementDefinition"] = 1401] = "missingElementDefinition";
@@ -251,10 +252,40 @@ const DOM = Object.freeze({
     },
 });
 
+const surroundingWhitespaceAndControlChars = /^[\u0000-\u0020\u007F]+|[\u0000-\u0020\u007F]+$/g;
+const whitespaceAndControlChars = /[\u0000-\u0020\u007F]+/g;
+const unsafeURLProtocol = /^(?:javascript|vbscript|data):/;
+function trimURL(value) {
+    return value.replace(surroundingWhitespaceAndControlChars, "");
+}
+function decodeURL(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch (_a) {
+        return value;
+    }
+}
+function hasUnsafeURLProtocol(value) {
+    let normalized = trimURL(value);
+    for (let i = 0; i < 3; ++i) {
+        const decoded = decodeURL(normalized);
+        if (decoded === normalized) {
+            break;
+        }
+        normalized = trimURL(decoded);
+    }
+    normalized = normalized.replace(whitespaceAndControlChars, "").toLowerCase();
+    return unsafeURLProtocol.test(normalized);
+}
+function sanitizeURL(value) {
+    const trimmed = trimURL(value);
+    return hasUnsafeURLProtocol(trimmed) ? "" : trimmed;
+}
 function safeURL(tagName, aspect, aspectName, sink) {
     return (target, name, value, ...rest) => {
         if (isString(value)) {
-            value = value.replace(/(javascript:|vbscript:|data:)/, "");
+            value = sanitizeURL(value);
         }
         sink(target, name, value, ...rest);
     };
@@ -516,7 +547,7 @@ function createElementGuards(config, defaults) {
                 break;
             case undefined:
                 // keep the default
-                result[tag] = createDOMAspectGuards(overrideValue, {});
+                result[tag] = createDOMAspectGuards(defaultValue, {});
                 break;
             default:
                 // override the default aspects
@@ -1170,14 +1201,10 @@ const AttributeConfiguration = Object.freeze({
  */
 const booleanConverter = {
     toView(value) {
-        return value ? "true" : "false";
+        return value ? "" : null;
     },
     fromView(value) {
-        return !(value === null ||
-            value === void 0 ||
-            value === "false" ||
-            value === false ||
-            value === 0);
+        return !!value;
     },
 };
 /**
@@ -1217,7 +1244,7 @@ const nullableNumberConverter = {
     fromView: toNumber,
 };
 /**
- * An implementation of `Accessor` that supports reactivity,
+ * An implementation of {@link Accessor} that supports reactivity,
  * change callbacks, attribute reflection, and type conversion for
  * custom elements.
  * @public
@@ -1280,7 +1307,15 @@ class AttributeDefinition {
             return;
         }
         this.guards.add(element);
-        this.setValue(element, value);
+        if (this.mode === booleanMode) {
+            // Native HTML boolean attribute semantics: presence of the attribute
+            // (any string value, including "") means `true`; `null` (the value
+            // passed by the platform on `removeAttribute`) means `false`.
+            this.setValue(element, value !== null);
+        }
+        else {
+            this.setValue(element, value);
+        }
         this.guards.delete(element);
     }
     tryReflectToAttribute(element) {
@@ -1829,8 +1864,11 @@ const defaultShadowOptions = { mode: "open" };
 const defaultElementOptions = {};
 const fastElementBaseTypes = new Set();
 /**
- * The FAST custom element registry
- * @internal
+ * The FAST custom element registry.
+ * @remarks
+ * This registry stores FAST element definitions by constructor so consumers can
+ * look up the `FASTElementDefinition` associated with an element type or instance.
+ * @public
  */
 const fastElementRegistry = createTypeRegistry();
 const templateResolvers = new WeakMap();
@@ -2095,7 +2133,7 @@ FASTElementDefinition.getForInstance = fastElementRegistry.getForInstance;
  * @param name - The name of the defined custom element.
  * @alpha
  */
-FASTElementDefinition.register = (name, registry = customElements) => __awaiter(void 0, void 0, void 0, function* () {
+FASTElementDefinition.register = (name_1, ...args_1) => __awaiter(void 0, [name_1, ...args_1], void 0, function* (name, registry = customElements) {
     const registeredTypes = getRegisteredTypes(registry);
     if (!Object.prototype.hasOwnProperty.call(registeredTypes, name)) {
         Observable.defineProperty(registeredTypes, name);
@@ -2595,7 +2633,8 @@ class ElementController {
      * customElements.define() completed.
      */
     observeLateAttributes() {
-        if (getLateAttributeLookup(this.definition) === null) {
+        const lateAttributes = getLateAttributeLookup(this.definition);
+        if (lateAttributes === null) {
             return;
         }
         const element = this.source;
@@ -2616,7 +2655,10 @@ class ElementController {
                 controller.onAttributeChangedCallback(attributeName, null, element.getAttribute(attributeName));
             }
         });
-        element[lateAttributeObserver].observe(element, { attributes: true });
+        element[lateAttributeObserver].observe(element, {
+            attributes: true,
+            attributeFilter: Object.keys(lateAttributes),
+        });
     }
     /**
      * Connects any existing behaviors on the associated element.
@@ -3023,6 +3065,7 @@ const baseDebugMessages = {
     [1208 /* cannotSetTemplatePolicyAfterCompilation */]: "The DOM Policy cannot be set after a template is compiled.",
     [1209 /* blockedByDOMPolicy */]: "'${aspectName}' on '${tagName}' is blocked by the current DOMPolicy.",
     [1210 /* invalidHydrationAttributeMarker */]: "Invalid data-fe attribute value '${value}'. Expected a positive integer.",
+    [1211 /* duplicateRenderInstruction */]: "Replacing existing RenderInstruction for '${type}' with name '${name}'.",
     [1401 /* missingElementDefinition */]: "Missing FASTElement definition.",
     [1501 /* noRegistrationForContext */]: "No registration for Context/Interface '${name}'.",
     [1502 /* noFactoryForResolver */]: "Dependency injection resolver for '${key}' returned a null factory.",
@@ -3465,7 +3508,17 @@ const ref = (propertyName) => new RefDirective(propertyName);
  * Attribute bindings use a single `data-fe` attribute whose value is
  * the count of attribute binding factories targeting the element:
  *   <div data-fe="3"> (3 attribute bindings)
+ *
+ * WebUI versions that predate the data-free marker format still emit indexed
+ * markers. The parser below accepts those legacy markers so existing WebUI SSR
+ * output can hydrate against the newer FAST runtime.
  */
+const legacyBindingStartMarker = /fe-b\$\$start\$\$(\d+)\$\$(.+)\$\$fe-b/;
+const legacyBindingEndMarker = /fe-b\$\$end\$\$(\d+)\$\$(.+)\$\$fe-b/;
+const legacyRepeatViewStartMarker = /fe-repeat\$\$start\$\$(\d+)\$\$fe-repeat/;
+const legacyRepeatViewEndMarker = /fe-repeat\$\$end\$\$(\d+)\$\$fe-repeat/;
+const legacyElementBoundaryStartMarker = /^(?:.{0,1000})fe-eb\$\$start\$\$(.+?)\$\$fe-eb/;
+const legacyElementBoundaryEndMarker = /fe-eb\$\$end\$\$(.{0,1000})\$\$fe-eb(?:.{0,1000})$/;
 function isComment$1(node) {
     return node && node.nodeType === Node.COMMENT_NODE;
 }
@@ -3476,6 +3529,8 @@ function isComment$1(node) {
 const HydrationMarkup = Object.freeze({
     // Single attribute marker format (count only)
     attributeMarkerName: "data-fe",
+    legacyAttributeMarkerName: "data-fe-b",
+    legacyCompactAttributeMarkerName: "data-fe-c",
     // Content binding markers (no arguments)
     contentBindingStartMarker() {
         return "fe:b";
@@ -3499,22 +3554,24 @@ const HydrationMarkup = Object.freeze({
     },
     // Detection — simple string equality
     isContentBindingStartMarker(data) {
-        return data === "fe:b";
+        return data === "fe:b" || legacyBindingStartMarker.test(data);
     },
     isContentBindingEndMarker(data) {
-        return data === "fe:/b";
+        return data === "fe:/b" || legacyBindingEndMarker.test(data);
     },
     isRepeatViewStartMarker(data) {
-        return data === "fe:r";
+        return data === "fe:r" || legacyRepeatViewStartMarker.test(data);
     },
     isRepeatViewEndMarker(data) {
-        return data === "fe:/r";
+        return data === "fe:/r" || legacyRepeatViewEndMarker.test(data);
     },
     isElementBoundaryStartMarker(node) {
-        return isComment$1(node) && node.data === "fe:e";
+        return (isComment$1(node) &&
+            (node.data === "fe:e" || legacyElementBoundaryStartMarker.test(node.data)));
     },
     isElementBoundaryEndMarker(node) {
-        return isComment$1(node) && node.data === "fe:/e";
+        return (isComment$1(node) &&
+            (node.data === "fe:/e" || legacyElementBoundaryEndMarker.test(node.data)));
     },
     /**
      * Returns the count of attribute bindings on the element, or null
@@ -3542,7 +3599,72 @@ const HydrationMarkup = Object.freeze({
         }
         return count;
     },
+    parseLegacyAttributeBindingIndices(node) {
+        const indices = [];
+        const attr = node.getAttribute(this.legacyAttributeMarkerName);
+        if (attr !== null) {
+            for (const value of attr.trim().split(/\s+/)) {
+                if (value === "") {
+                    continue;
+                }
+                const index = Number(value);
+                if (!Number.isInteger(index) || index < 0) {
+                    throw FAST.error(Message.invalidHydrationAttributeMarker, {
+                        value: attr,
+                    });
+                }
+                indices.push(index);
+            }
+        }
+        const enumeratedPrefix = `${this.legacyAttributeMarkerName}-`;
+        const compactPrefix = `${this.legacyCompactAttributeMarkerName}-`;
+        for (const name of node.getAttributeNames()) {
+            if (name.startsWith(enumeratedPrefix)) {
+                const index = Number(name.slice(enumeratedPrefix.length));
+                if (!Number.isInteger(index) || index < 0) {
+                    throw FAST.error(Message.invalidHydrationAttributeMarker, {
+                        value: name,
+                    });
+                }
+                indices.push(index);
+            }
+            else if (name.startsWith(compactPrefix)) {
+                const [start, count] = name
+                    .slice(compactPrefix.length)
+                    .split("-")
+                    .map(value => Number(value));
+                if (!Number.isInteger(start) ||
+                    !Number.isInteger(count) ||
+                    start < 0 ||
+                    count < 1) {
+                    throw FAST.error(Message.invalidHydrationAttributeMarker, {
+                        value: name,
+                    });
+                }
+                for (let i = 0; i < count; i++) {
+                    indices.push(start + i);
+                }
+            }
+        }
+        return indices.length === 0 ? null : indices;
+    },
+    removeLegacyAttributeBindingMarkers(node) {
+        node.removeAttribute(this.legacyAttributeMarkerName);
+        for (const name of node.getAttributeNames()) {
+            if (name.startsWith(`${this.legacyAttributeMarkerName}-`) ||
+                name.startsWith(`${this.legacyCompactAttributeMarkerName}-`)) {
+                node.removeAttribute(name);
+            }
+        }
+    },
+    parseLegacyContentBindingStartIndex(data) {
+        return parseLegacyIntMarker(legacyBindingStartMarker, data);
+    },
 });
+function parseLegacyIntMarker(pattern, data) {
+    const match = pattern.exec(data);
+    return match === null ? null : Number(match[1]);
+}
 /**
  * @internal
  */
@@ -4209,6 +4331,94 @@ function sortedCount(array) {
     return array.sorted;
 }
 
+/**
+ * Centralized hydration mismatch message strings used by both the default
+ * minimal `HydrationDiagnostic` and the opt-in `hydrationDebugger` rich
+ * formatter, and by the structural-error throw sites in
+ * `target-builder.ts`.
+ *
+ * Static text is exported as a plain `const`; interpolated text is exported
+ * as a small builder function. Plain `export const` declarations tree-shake
+ * better than frozen-object property bags, so unused strings drop out of
+ * bundles cleanly.
+ */
+/**
+ * Fallback host tag name used when a hydration mismatch is detected on a
+ * node that is not inside a shadow root.
+ */
+const unknownHostName = "unknown";
+/**
+ * Default minimal hydration mismatch message used when the
+ * `hydrationDebugger` opt-in is not installed. The optional `detail` string
+ * carries the structural expectation surfaced by `target-builder.ts`.
+ */
+function formatDefaultMismatchMessage(hostName, detail) {
+    const suffix = detail ? `: ${detail}` : "";
+    return (`Hydration mismatch in <${hostName}>${suffix}. Install ` +
+        `hydrationDebugger() from "@microsoft/fast-element/hydration.js" and ` +
+        `pass it as enableHydration({ debugger: hydrationDebugger() }) for an ` +
+        `"Expected / Received" report including the SSR HTML snippet.`);
+}
+// -- Structural expectations (used by target-builder.ts throw sites) ---------
+const expectedContentAfterStartMarker = "content following `<!--fe:b-->` content binding marker";
+const expectedContentEndMarker = "matching `<!--fe:/b-->` content binding close marker";
+const expectedElementBoundaryEndMarker = "matching `<!--fe:/e-->` element boundary close marker";
+/**
+ * Builds the "no more attribute bindings" structural expectation message
+ * thrown when an element's `data-fe` count claims more attribute bindings
+ * than the compiled template defines.
+ */
+function formatNoMoreAttributeBindings(factoryCount) {
+    return `no more attribute bindings (template defines ${factoryCount})`;
+}
+/**
+ * Builds the "no more content bindings" structural expectation message
+ * thrown when the SSR DOM contains more content binding markers than the
+ * compiled template defines.
+ */
+function formatNoMoreContentBindings(factoryCount) {
+    return `no more content bindings (template defines ${factoryCount})`;
+}
+
+function formatMinimalMessage(hostName, detail) {
+    const host = (hostName !== null && hostName !== void 0 ? hostName : unknownHostName).toLowerCase();
+    return formatDefaultMismatchMessage(host, detail);
+}
+const defaultDiagnostic = {
+    formatBindingMismatch(_factory, _firstChild, _lastChild, hostName) {
+        return {
+            message: formatMinimalMessage(hostName, undefined),
+        };
+    },
+    formatStructuralError(_node, hostName, expectedDescription) {
+        return {
+            message: formatMinimalMessage(hostName, expectedDescription),
+        };
+    },
+};
+let activeDiagnostic = defaultDiagnostic;
+/**
+ * Returns the currently active {@link HydrationDiagnostic} — either the
+ * minimal default or one installed by an opt-in debugger.
+ * @internal
+ */
+function getHydrationDiagnostic() {
+    return activeDiagnostic;
+}
+/**
+ * Reads the host element's tag name from any node inside a hydration view.
+ * Returns `undefined` when the node is not inside a shadow root.
+ * @internal
+ */
+function getHostName(node) {
+    var _a;
+    if (!node) {
+        return undefined;
+    }
+    const root = node.getRootNode();
+    return (_a = root.host) === null || _a === void 0 ? void 0 : _a.nodeName;
+}
+
 class HydrationTargetElementError extends Error {
     constructor(
     /**
@@ -4222,10 +4432,24 @@ class HydrationTargetElementError extends Error {
     /**
      * The node to target factory.
      */
-    node) {
+    node, 
+    /**
+     * Structured description of the binding the hydration walk was
+     * attempting to apply when the mismatch was detected. Free-form
+     * string for structural errors that do not correspond to a single
+     * binding factory.
+     */
+    expected, 
+    /**
+     * Structured description of the server-rendered DOM that was
+     * encountered at the mismatch point.
+     */
+    received) {
         super(message);
         this.factories = factories;
         this.node = node;
+        this.expected = expected;
+        this.received = received;
     }
 }
 function isComment(node) {
@@ -4274,7 +4498,6 @@ function createRangeForNodes(first, last) {
  * @returns - A {@link ViewBehaviorTargets } object for the factories in the view.
  */
 function buildViewBindingTargets(firstNode, lastNode, factories) {
-    var _a, _b;
     const range = createRangeForNodes(firstNode, lastNode);
     const treeRoot = range.commonAncestorContainer;
     const walker = document.createTreeWalker(treeRoot, NodeFilter.SHOW_ELEMENT + NodeFilter.SHOW_COMMENT + NodeFilter.SHOW_TEXT, {
@@ -4287,36 +4510,63 @@ function buildViewBindingTargets(firstNode, lastNode, factories) {
     const targets = {};
     const boundaries = {};
     // Sequential factory pointer — skip host bindings at the start
-    let factoryPointer = getHydrationIndexOffset(factories);
+    const hydrationIndexOffset = getHydrationIndexOffset(factories);
+    let factoryPointer = hydrationIndexOffset;
     let node = (walker.currentNode = firstNode);
     while (node !== null) {
         switch (node.nodeType) {
             case Node.ELEMENT_NODE: {
-                const count = HydrationMarkup.parseAttributeBindingCount(node);
+                const element = node;
+                const legacyIndices = HydrationMarkup.parseLegacyAttributeBindingIndices(element);
+                if (legacyIndices !== null) {
+                    for (const index of legacyIndices) {
+                        const factoryIndex = index + hydrationIndexOffset;
+                        const factory = factories[factoryIndex];
+                        if (!factory) {
+                            const expected = formatNoMoreAttributeBindings(factories.length);
+                            const result = getHydrationDiagnostic().formatStructuralError(node, getHostName(node), expected);
+                            throw new HydrationTargetElementError(result.message, factories, element, result.expected, result.received);
+                        }
+                        targetFactory(factory, node, targets);
+                        factoryPointer = Math.max(factoryPointer, factoryIndex + 1);
+                    }
+                    HydrationMarkup.removeLegacyAttributeBindingMarkers(element);
+                    break;
+                }
+                const count = HydrationMarkup.parseAttributeBindingCount(element);
                 if (count !== null) {
                     for (let i = 0; i < count; i++) {
                         const factory = factories[factoryPointer++];
                         if (!factory) {
-                            throw new HydrationTargetElementError(`HydrationView was unable to successfully target factory on ${node.nodeName} inside ${node.getRootNode().host.nodeName}. This likely indicates a template mismatch between SSR rendering and hydration.`, factories, node);
+                            const expected = formatNoMoreAttributeBindings(factories.length);
+                            const result = getHydrationDiagnostic().formatStructuralError(node, getHostName(node), expected);
+                            throw new HydrationTargetElementError(result.message, factories, node, result.expected, result.received);
                         }
                         targetFactory(factory, node, targets);
                     }
-                    node.removeAttribute(HydrationMarkup.attributeMarkerName);
+                    element.removeAttribute(HydrationMarkup.attributeMarkerName);
                 }
                 break;
             }
             case Node.COMMENT_NODE: {
                 const data = node.data;
-                if (data === "fe:e") {
+                if (HydrationMarkup.isElementBoundaryStartMarker(node)) {
                     // Element boundary — clear start marker and skip subtree
                     node.data = "";
                     skipToElementBoundaryEnd(walker, factories, node);
                 }
-                else if (data === "fe:b") {
+                else if (HydrationMarkup.isContentBindingStartMarker(data)) {
                     // Content binding — consume next factory
-                    const factory = factories[factoryPointer++];
+                    const legacyIndex = HydrationMarkup.parseLegacyContentBindingStartIndex(data);
+                    const factoryIndex = legacyIndex === null
+                        ? factoryPointer++
+                        : legacyIndex + hydrationIndexOffset;
+                    const factory = factories[factoryIndex];
+                    factoryPointer = Math.max(factoryPointer, factoryIndex + 1);
                     if (!factory) {
-                        throw new HydrationTargetElementError(`HydrationView ran out of factories while processing a content binding marker inside ${(_b = (_a = node.getRootNode().host) === null || _a === void 0 ? void 0 : _a.nodeName) !== null && _b !== void 0 ? _b : "unknown"}. This likely indicates a template mismatch between SSR rendering and hydration.`, factories, node);
+                        const expected = formatNoMoreContentBindings(factories.length);
+                        const result = getHydrationDiagnostic().formatStructuralError(node, getHostName(node), expected);
+                        throw new HydrationTargetElementError(result.message, factories, node, result.expected, result.received);
                     }
                     targetContentBinding(node, walker, factory, factories, targets, boundaries);
                 }
@@ -4329,22 +4579,23 @@ function buildViewBindingTargets(firstNode, lastNode, factories) {
     return { targets, boundaries };
 }
 function targetContentBinding(node, walker, factory, factories, targets, boundaries) {
-    var _a, _b, _c, _d;
     const nodes = [];
     let current = walker.nextSibling();
     node.data = "";
     if (current === null) {
-        throw new HydrationTargetElementError(`Error hydrating content binding inside "${(_b = (_a = node.getRootNode().host) === null || _a === void 0 ? void 0 : _a.nodeName) !== null && _b !== void 0 ? _b : "unknown"}": no sibling found after content binding start marker.`, factories, node);
+        const expected = expectedContentAfterStartMarker;
+        const result = getHydrationDiagnostic().formatStructuralError(node, getHostName(node), expected);
+        throw new HydrationTargetElementError(result.message, factories, node, result.expected, result.received);
     }
     const first = current;
     // Balanced depth counting for nested content markers
     let depth = 0;
     while (current !== null) {
         if (isComment(current)) {
-            if (current.data === "fe:b") {
+            if (HydrationMarkup.isContentBindingStartMarker(current.data)) {
                 depth++;
             }
-            else if (current.data === "fe:/b") {
+            else if (HydrationMarkup.isContentBindingEndMarker(current.data)) {
                 if (depth === 0)
                     break;
                 depth--;
@@ -4354,7 +4605,9 @@ function targetContentBinding(node, walker, factory, factories, targets, boundar
         current = walker.nextSibling();
     }
     if (current === null) {
-        throw new HydrationTargetElementError(`Error hydrating content binding inside "${(_d = (_c = node.getRootNode().host) === null || _c === void 0 ? void 0 : _c.nodeName) !== null && _d !== void 0 ? _d : "unknown"}": missing fe:/b end marker.`, factories, node);
+        const expected = expectedContentEndMarker;
+        const result = getHydrationDiagnostic().formatStructuralError(node, getHostName(node), expected);
+        throw new HydrationTargetElementError(result.message, factories, node, result.expected, result.received);
     }
     current.data = "";
     if (nodes.length === 1 && isText(nodes[0])) {
@@ -4380,16 +4633,15 @@ function targetContentBinding(node, walker, factory, factories, targets, boundar
  * depth counting to handle nested element boundaries correctly.
  */
 function skipToElementBoundaryEnd(walker, factories, startNode) {
-    var _a, _b;
     let depth = 0;
     let current = walker.nextSibling();
     while (current !== null) {
         if (isComment(current)) {
-            if (current.data === "fe:e") {
+            if (HydrationMarkup.isElementBoundaryStartMarker(current)) {
                 current.data = "";
                 depth++;
             }
-            else if (current.data === "fe:/e") {
+            else if (HydrationMarkup.isElementBoundaryEndMarker(current)) {
                 if (depth === 0) {
                     current.data = "";
                     return;
@@ -4400,7 +4652,9 @@ function skipToElementBoundaryEnd(walker, factories, startNode) {
         }
         current = walker.nextSibling();
     }
-    throw new HydrationTargetElementError(`HydrationView could not find the end of an element boundary inside ${(_b = (_a = startNode.getRootNode().host) === null || _a === void 0 ? void 0 : _a.nodeName) !== null && _b !== void 0 ? _b : "unknown"}. This likely indicates a template mismatch between SSR rendering and hydration.`, factories, startNode);
+    const expected = expectedElementBoundaryEndMarker;
+    const result = getHydrationDiagnostic().formatStructuralError(startNode, getHostName(startNode), expected);
+    throw new HydrationTargetElementError(result.message, factories, startNode, result.expected, result.received);
 }
 /**
  * Counts how many factories at the start of the array are host bindings (targetNodeId='h').
@@ -4638,7 +4892,7 @@ class HTMLView extends DefaultExecutionContext {
      * @param context - The execution context to run the behaviors within.
      */
     bind(source, context = this) {
-        if (this.source === source) {
+        if (this.source === source && this.context === context) {
             return;
         }
         let behaviors = this.behaviors;
@@ -4732,11 +4986,23 @@ class HydrationBindingError extends Error {
      * String representation of the HTML in the template that
      * threw the binding error.
      */
-    templateString) {
+    templateString, 
+    /**
+     * Structured description of the binding the hydration walk was
+     * attempting to apply when the mismatch was detected.
+     */
+    expected, 
+    /**
+     * Structured description of the server-rendered DOM that was
+     * encountered at the mismatch point.
+     */
+    received) {
         super(message);
         this.factory = factory;
         this.fragment = fragment;
         this.templateString = templateString;
+        this.expected = expected;
+        this.received = received;
     }
 }
 class HydrationView extends DefaultExecutionContext {
@@ -4822,13 +5088,12 @@ class HydrationView extends DefaultExecutionContext {
         fragment.appendChild(end);
     }
     bind(source, context = this) {
-        var _b;
+        if (this.source === source && this.context === context) {
+            return;
+        }
         if (this.hydrationStage !== HydrationStage.hydrated) {
             this._hydrationStage = HydrationStage.hydrating;
         }
-        if (this.source === source) {
-            return;
-        }
         let behaviors = this.behaviors;
         if (behaviors === null) {
             this.source = source;
@@ -4866,28 +5131,9 @@ class HydrationView extends DefaultExecutionContext {
                     if (typeof templateString !== "string") {
                         templateString = templateString.innerHTML;
                     }
-                    const hostElement = ((_b = this.firstChild) === null || _b === void 0 ? void 0 : _b.getRootNode())
-                        .host;
-                    const hostName = (hostElement === null || hostElement === void 0 ? void 0 : hostElement.nodeName) || "unknown";
-                    const factoryInfo = factory;
-                    // Build detailed error message
-                    const details = [
-                        `HydrationView was unable to successfully target bindings inside "<${hostName.toLowerCase()}>".`,
-                        `\nMismatch Details:`,
-                        `  - Expected target node ID: "${factory.targetNodeId}"`,
-                        `  - Available target IDs: [${Object.keys(this.targets).join(", ") || "none"}]`,
-                    ];
-                    if (factory.targetTagName) {
-                        details.push(`  - Expected tag name: "${factory.targetTagName}"`);
-                    }
-                    if (factoryInfo.sourceAspect) {
-                        details.push(`  - Source aspect: "${factoryInfo.sourceAspect}"`);
-                    }
-                    if (factoryInfo.aspectType !== undefined) {
-                        details.push(`  - Aspect type: ${factoryInfo.aspectType}`);
-                    }
-                    details.push(`\nThis usually means:`, `  1. The server-rendered HTML doesn't match the client template`, `  2. The hydration markers are missing or corrupted`, `  3. The DOM structure was modified before hydration`, `\nTemplate: ${templateString.slice(0, 200)}${templateString.length > 200 ? "..." : ""}`);
-                    throw new HydrationBindingError(details.join("\n"), factory, createRangeForNodes(this.firstChild, this.lastChild).cloneContents(), templateString);
+                    const fragment = createRangeForNodes(this.firstChild, this.lastChild).cloneContents();
+                    const result = getHydrationDiagnostic().formatBindingMismatch(factory, this.firstChild, this.lastChild, getHostName(this.firstChild));
+                    throw new HydrationBindingError(result.message, factory, fragment, templateString, result.expected, result.received);
                 }
             }
         }
@@ -4955,6 +5201,21 @@ function bindWithPositioning(view, items, index, controller) {
 function isCommentNode(node) {
     return node.nodeType === Node.COMMENT_NODE;
 }
+function removeNodeRange(first, last) {
+    const parentNode = first.parentNode;
+    if (parentNode === null) {
+        return;
+    }
+    let current = first;
+    while (current !== null) {
+        const next = current.nextSibling;
+        parentNode.removeChild(current);
+        if (current === last) {
+            break;
+        }
+        current = next;
+    }
+}
 class HydrationRepeatError extends Error {
     constructor(
     /**
@@ -5214,23 +5475,26 @@ class RepeatBehavior {
         }
     }
     hydrateViews(template) {
+        var _a;
         if (!this.items) {
             return;
         }
-        const itemCount = this.items.length;
-        this.views = new Array(itemCount);
+        const items = this.items;
+        const itemCount = items.length;
+        const views = (this.views = new Array(itemCount));
         // First pass: collect all repeat marker pairs by walking backward.
-        // Each entry is { start: Node, end: Node } for the item content range.
+        // Each entry tracks both the item content range and its SSR markers.
         const itemRanges = [];
         let current = this.location.previousSibling;
         while (current !== null) {
-            if (!isCommentNode(current) || current.data !== "fe:/r") {
+            if (!isCommentNode(current) ||
+                !HydrationMarkup.isRepeatViewEndMarker(current.data)) {
                 current = current.previousSibling;
                 continue;
             }
-            // Found repeat end marker
-            current.data = "";
-            const end = current.previousSibling;
+            const endMarker = current;
+            endMarker.data = "";
+            const end = endMarker.previousSibling;
             if (!end) {
                 throw new Error(`Error when hydrating inside "${this.location.getRootNode().host.nodeName}": end should never be null.`);
             }
@@ -5239,18 +5503,23 @@ class RepeatBehavior {
             let depth = 0;
             while (start !== null) {
                 if (isCommentNode(start)) {
-                    if (start.data === "fe:/r") {
+                    if (HydrationMarkup.isRepeatViewEndMarker(start.data)) {
                         depth++;
                     }
-                    else if (start.data === "fe:r") {
+                    else if (HydrationMarkup.isRepeatViewStartMarker(start.data)) {
                         if (depth === 0) {
                             const startMarker = start;
                             startMarker.data = "";
                             current = startMarker.previousSibling;
-                            const itemStart = startMarker.nextSibling;
+                            const itemStart = (_a = startMarker.nextSibling) !== null && _a !== void 0 ? _a : endMarker;
                             // Empty item: start and end markers are adjacent.
                             const itemEnd = end === startMarker ? itemStart : end;
-                            itemRanges.push({ start: itemStart, end: itemEnd });
+                            itemRanges.push({
+                                start: itemStart,
+                                end: itemEnd,
+                                startMarker,
+                                endMarker,
+                            });
                             break;
                         }
                         depth--;
@@ -5266,11 +5535,22 @@ class RepeatBehavior {
         // Reverse so index 0 = first SSR item.
         itemRanges.reverse();
         // Hydrate each SSR item at its correct index (0-based from start).
-        for (let i = 0; i < itemRanges.length && i < itemCount; i++) {
+        const hydrationCount = Math.min(itemRanges.length, itemCount);
+        for (let i = 0; i < hydrationCount; i++) {
             const { start, end } = itemRanges[i];
             const view = template.hydrate(start, end);
-            this.views[i] = view;
-            this.bindView(view, this.items, i, this.controller);
+            views[i] = view;
+            this.bindView(view, items, i, this.controller);
+        }
+        for (let i = hydrationCount; i < itemCount; i++) {
+            const view = template.create();
+            views[i] = view;
+            this.bindView(view, items, i, this.controller);
+            view.insertBefore(this.location);
+        }
+        for (let i = itemCount, ii = itemRanges.length; i < ii; i++) {
+            const { startMarker, endMarker } = itemRanges[i];
+            removeNodeRange(startMarker, endMarker);
         }
     }
 }
@@ -6127,12 +6407,12 @@ class HTMLBindingDirective {
      * @param dataBinding - The binding configuration to apply.
      */
     constructor(dataBinding) {
-        this.dataBinding = dataBinding;
         this.updateTarget = null;
         /**
          * The type of aspect to target.
          */
         this.aspectType = DOMAspect.content;
+        this.dataBinding = dataBinding;
     }
     /**
      * Creates HTML to be used within a template.
@@ -6780,11 +7060,10 @@ class RenderBehavior {
             if (viewNodes) {
                 this.view = this.template.hydrate(viewNodes.first, viewNodes.last);
                 this.bindView(this.view);
+                return;
             }
         }
-        else {
-            this.refreshView();
-        }
+        this.refreshView();
     }
     /**
      * Unbinds this behavior.
@@ -6901,6 +7180,32 @@ function instructionToTemplate(def) {
     }
     return def.template;
 }
+function resolveTemplateBindingValue(result, dataBinding, source, context) {
+    var _a;
+    if (isString(result)) {
+        return instructionToTemplate(getForInstance(dataBinding.evaluate(source, context), result));
+    }
+    if (result instanceof Node) {
+        return (_a = result.$fastTemplate) !== null && _a !== void 0 ? _a : new NodeTemplate(result);
+    }
+    return result;
+}
+function adaptTemplateBinding(binding, dataBinding) {
+    const evaluateTemplate = binding.evaluate;
+    const adapter = Object.create(Object.getPrototypeOf(binding));
+    for (const propertyName of Object.getOwnPropertyNames(binding)) {
+        if (propertyName !== "evaluate") {
+            Object.defineProperty(adapter, propertyName, Object.getOwnPropertyDescriptor(binding, propertyName));
+        }
+    }
+    Object.defineProperty(adapter, "evaluate", {
+        configurable: true,
+        enumerable: true,
+        value: (source, context) => resolveTemplateBindingValue(evaluateTemplate(source, context), dataBinding, source, context),
+        writable: true,
+    });
+    return adapter;
+}
 function getByType(type, name) {
     const entries = typeToInstructionLookup.get(type);
     if (entries === void 0) {
@@ -7003,19 +7308,7 @@ function render(value, template) {
         });
     }
     else if (template instanceof Binding) {
-        const evaluateTemplate = template.evaluate;
-        template.evaluate = (s, c) => {
-            var _a;
-            let result = evaluateTemplate(s, c);
-            if (isString(result)) {
-                result = instructionToTemplate(getForInstance(dataBinding.evaluate(s, c), result));
-            }
-            else if (result instanceof Node) {
-                result = (_a = result.$fastTemplate) !== null && _a !== void 0 ? _a : new NodeTemplate(result);
-            }
-            return result;
-        };
-        templateBinding = template;
+        templateBinding = adaptTemplateBinding(template, dataBinding);
     }
     else {
         templateBinding = oneTime((s, c) => template);