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

package/dist/esm/hydration/hydration-debugger.js

@@ -0,0 +1,112 @@
+import { DOMAspect } from "../dom.js";
+import { aspectLabelAttribute, aspectLabelBooleanAttribute, aspectLabelContent, aspectLabelEvent, aspectLabelProperty, aspectLabelTokenList, aspectLabelUnknown, formatAspect, formatExpectedTarget, formatRichMismatchMessage, unknownHostName, } from "./messages.js";
+const aspectLabelsByCode = Object.freeze({
+    [DOMAspect.attribute]: aspectLabelAttribute,
+    [DOMAspect.booleanAttribute]: aspectLabelBooleanAttribute,
+    [DOMAspect.property]: aspectLabelProperty,
+    [DOMAspect.content]: aspectLabelContent,
+    [DOMAspect.tokenList]: aspectLabelTokenList,
+    [DOMAspect.event]: aspectLabelEvent,
+});
+const defaultSnippetLength = 500;
+function describeAspect(aspectType, sourceAspect) {
+    var _a;
+    const base = aspectType !== undefined
+        ? ((_a = aspectLabelsByCode[aspectType]) !== null && _a !== void 0 ? _a : aspectLabelUnknown)
+        : aspectLabelUnknown;
+    return formatAspect(base, sourceAspect);
+}
+function describeExpectedTarget(factory) {
+    var _a;
+    const aspectType = factory.aspectType;
+    const sourceAspect = factory.sourceAspect;
+    return {
+        tagName: (_a = factory.targetTagName) !== null && _a !== void 0 ? _a : null,
+        aspect: describeAspect(aspectType, sourceAspect),
+    };
+}
+function stripEmptyComments(root) {
+    var _a;
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_COMMENT);
+    const empties = [];
+    let current;
+    while ((current = walker.nextNode()) !== null) {
+        if (current.data === "") {
+            empties.push(current);
+        }
+    }
+    for (const comment of empties) {
+        (_a = comment.parentNode) === null || _a === void 0 ? void 0 : _a.removeChild(comment);
+    }
+}
+function truncate(value, maxLength) {
+    return value.length > maxLength ? `${value.slice(0, maxLength)}…` : value;
+}
+function serializeNodeForError(node, maxLength = defaultSnippetLength) {
+    const wrapper = document.createElement("div");
+    wrapper.appendChild(node.cloneNode(true));
+    stripEmptyComments(wrapper);
+    return truncate(wrapper.innerHTML.trim(), maxLength);
+}
+function serializeRangeForError(first, last, maxLength = defaultSnippetLength) {
+    const wrapper = document.createElement("div");
+    let current = first;
+    while (current !== null) {
+        wrapper.appendChild(current.cloneNode(true));
+        if (current === last) {
+            break;
+        }
+        current = current.nextSibling;
+    }
+    stripEmptyComments(wrapper);
+    return truncate(wrapper.innerHTML.trim(), maxLength);
+}
+function formatMismatchMessage(hostName, expected, received) {
+    const host = (hostName !== null && hostName !== void 0 ? hostName : unknownHostName).toLowerCase();
+    const expectedText = typeof expected === "string"
+        ? expected
+        : formatExpectedTarget(expected.tagName, expected.aspect);
+    return formatRichMismatchMessage(host, expectedText, received.html);
+}
+const richDiagnostic = {
+    formatBindingMismatch(factory, firstChild, lastChild, hostName) {
+        const expected = describeExpectedTarget(factory);
+        const received = {
+            html: serializeRangeForError(firstChild, lastChild),
+        };
+        const result = {
+            message: formatMismatchMessage(hostName, expected, received),
+            expected,
+            received,
+        };
+        return result;
+    },
+    formatStructuralError(node, hostName, expectedDescription) {
+        const received = {
+            html: serializeNodeForError(node),
+        };
+        const result = {
+            message: formatMismatchMessage(hostName, expectedDescription, received),
+            expected: expectedDescription,
+            received,
+        };
+        return result;
+    },
+};
+/**
+ * Returns a {@link HydrationDebugger} that, when supplied to
+ * `enableHydration({ debugger })`, installs the rich hydration mismatch
+ * formatter: a single-line "Expected … / Received …" message plus an HTML
+ * snippet of the SSR DOM and structured `expected`/`received` fields on
+ * the thrown error (both `HydrationBindingError` and
+ * `HydrationTargetElementError`).
+ *
+ * Without the debugger, hydration errors emit only a minimal one-line
+ * message pointing at this function — keeping the runtime hydration cost
+ * small for production bundles that do not need rich diagnostics.
+ *
+ * @public
+ */
+export function hydrationDebugger() {
+    return { diagnostic: richDiagnostic };
+}

package/dist/esm/hydration/messages.js

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ */
+export const unknownHostName = "unknown";
+// -- Aspect labels (consumed by the opt-in hydrationDebugger) ----------------
+export const aspectLabelAttribute = "attribute";
+export const aspectLabelBooleanAttribute = "boolean attribute";
+export const aspectLabelProperty = "property";
+export const aspectLabelContent = "content";
+export const aspectLabelTokenList = "token list";
+export const aspectLabelEvent = "event";
+/** Fallback used when the aspectType is missing or unknown. */
+export const aspectLabelUnknown = "binding";
+/**
+ * Combines an aspect label with the original source aspect identifier from
+ * markup (e.g. `"property className"`). Returns the bare label when no
+ * source aspect was captured.
+ */
+export function formatAspect(label, sourceAspect) {
+    return sourceAspect ? `${label} \`${sourceAspect}\`` : label;
+}
+/**
+ * Formats the "Expected" half of the rich hydration mismatch message, e.g.
+ * `"<span> with content binding"` or `"content binding"` when no tag is
+ * associated with the binding factory.
+ */
+export function formatExpectedTarget(tagName, aspect) {
+    return tagName
+        ? `<${tagName.toLowerCase()}> with ${aspect} binding`
+        : `${aspect} binding`;
+}
+/**
+ * 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`.
+ */
+export 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.`);
+}
+/**
+ * Rich `Expected … / Received …` hydration mismatch message format produced
+ * by the `hydrationDebugger` formatter.
+ */
+export function formatRichMismatchMessage(hostName, expectedText, receivedHtml) {
+    return (`Hydration mismatch in <${hostName}>.\n` +
+        `  Expected: ${expectedText}\n` +
+        `  Received: ${receivedHtml}`);
+}
+// -- Structural expectations (used by target-builder.ts throw sites) ---------
+export const expectedContentAfterStartMarker = "content following `<!--fe:b-->` content binding marker";
+export const expectedContentEndMarker = "matching `<!--fe:/b-->` content binding close marker";
+export 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.
+ */
+export 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.
+ */
+export function formatNoMoreContentBindings(factoryCount) {
+    return `no more content bindings (template defines ${factoryCount})`;
+}

package/dist/esm/hydration/target-builder.js

@@ -1,4 +1,6 @@
 import { HydrationMarkup } from "../components/hydration.js";
+import { getHostName, getHydrationDiagnostic, } from "./diagnostics.js";
+import { expectedContentAfterStartMarker, expectedContentEndMarker, expectedElementBoundaryEndMarker, formatNoMoreAttributeBindings, formatNoMoreContentBindings, } from "./messages.js";
 export class HydrationTargetElementError extends Error {
     constructor(
     /**
@@ -12,10 +14,24 @@ export 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) {
@@ -64,7 +80,6 @@ export function createRangeForNodes(first, last) {
  * @returns - A {@link ViewBehaviorTargets } object for the factories in the view.
  */
 export 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, {
@@ -77,36 +92,63 @@ export 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);
                 }
@@ -119,22 +161,23 @@ export 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--;
@@ -144,7 +187,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])) {
@@ -170,16 +215,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;
@@ -190,7 +234,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').

package/dist/esm/hydration.js

@@ -1,4 +1,6 @@
-export { deferHydrationAttribute, enableHydration, } from "./components/enable-hydration.js";
+export { deferHydrationAttribute, enableHydration, StopHydration, } from "./components/enable-hydration.js";
 export { isHydratable } from "./components/hydration.js";
 export { HydrationTracker } from "./components/hydration-tracker.js";
+export { DOMPolicy, } from "./dom-policy.js";
+export { hydrationDebugger } from "./hydration/hydration-debugger.js";
 export { HydrationBindingError, HydrationStage, } from "./templating/hydration-view.js";

package/dist/esm/index.js

@@ -1,3 +1,7 @@
+/**
+ * Core APIs for building standards-based Web Components with FAST Element.
+ * @packageDocumentation
+ */
 // Kernel
 // Components
 export { AttributeConfiguration, AttributeDefinition, attr, booleanConverter, nullableBooleanConverter, nullableNumberConverter, } from "./attr.js";
@@ -10,7 +14,7 @@ export { Signal, signal } from "./binding/signal.js";
 export { TwoWaySettings, twoWay, } from "./binding/two-way.js";
 export { ElementController, Stages, } from "./components/element-controller.js";
 export { FASTElementDefinition, fastElementRegistry, } from "./components/fast-definitions.js";
-export { customElement, FASTElement } from "./components/fast-element.js";
+export { customElement, FASTElement, } from "./components/fast-element.js";
 export { enableDebug } from "./debug.js";
 // Directives
 export { ChildrenDirective, children, } from "./directives/children.js";
@@ -19,7 +23,7 @@ export { RefDirective, ref } from "./directives/ref.js";
 export { RepeatBehavior, RepeatDirective, repeat, } from "./directives/repeat.js";
 export { SlottedDirective, slotted, } from "./directives/slotted.js";
 export { when } from "./directives/when.js";
-export * from "./dom.js";
+export { DOM, DOMAspect } from "./dom.js";
 export { DOMPolicy, } from "./dom-policy.js";
 export { ArrayObserver, lengthOf, Sort, Splice, SpliceStrategy, SpliceStrategySupport, sortedCount, } from "./observation/arrays.js";
 // Observation

package/dist/esm/interfaces.js

@@ -18,6 +18,7 @@ export 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";

package/dist/esm/metadata.js

@@ -34,19 +34,13 @@ export const Metadata = Object.freeze({
      * @param Type - The type to get the metadata for.
      * @returns The metadata array or a frozen empty array if no metadata is found.
      */
-    getDesignParamTypes: (Type) => {
-        var _a;
-        return ((_a = Reflect.getOwnMetadata(designParamTypesKey, Type)) !== null && _a !== void 0 ? _a : emptyArray);
-    },
+    getDesignParamTypes: (Type) => { var _a; return ((_a = Reflect.getOwnMetadata(designParamTypesKey, Type)) !== null && _a !== void 0 ? _a : emptyArray); },
     /**
      * Gets the "annotation:paramtypes" metadata for the specified type.
      * @param Type - The type to get the metadata for.
      * @returns The metadata array or a frozen empty array if no metadata is found.
      */
-    getAnnotationParamTypes: (Type) => {
-        var _a;
-        return ((_a = Reflect.getOwnMetadata(annotationParamTypesKey, Type)) !== null && _a !== void 0 ? _a : emptyArray);
-    },
+    getAnnotationParamTypes: (Type) => { var _a; return ((_a = Reflect.getOwnMetadata(annotationParamTypesKey, Type)) !== null && _a !== void 0 ? _a : emptyArray); },
     /**
      * Gets the "annotation:paramtypes" metadata for the specified type. If none is found,
      * an empty, mutable metadata array is created and added.

package/dist/esm/observation/notifier.js

@@ -138,12 +138,10 @@ export class PropertyChangeNotifier {
         var _a, _b;
         let subscribers;
         if (propertyToWatch) {
-            subscribers =
-                (_a = this.subscribers[propertyToWatch]) !== null && _a !== void 0 ? _a : (this.subscribers[propertyToWatch] = new SubscriberSet(this.subject));
+            subscribers = (_a = this.subscribers[propertyToWatch]) !== null && _a !== void 0 ? _a : (this.subscribers[propertyToWatch] = new SubscriberSet(this.subject));
         }
         else {
-            subscribers =
-                (_b = this.subjectSubscribers) !== null && _b !== void 0 ? _b : (this.subjectSubscribers = new SubscriberSet(this.subject));
+            subscribers = (_b = this.subjectSubscribers) !== null && _b !== void 0 ? _b : (this.subjectSubscribers = new SubscriberSet(this.subject));
         }
         subscribers.subscribe(subscriber);
     }

package/dist/esm/registry.js

@@ -0,0 +1 @@
+export { FASTElementDefinition, fastElementRegistry, } from "./components/fast-definitions.js";

package/dist/esm/templating/html-binding-directive.js

@@ -158,12 +158,12 @@ export 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.

package/dist/esm/templating/hydration-view.js

@@ -1,5 +1,6 @@
 var _a;
 import { Hydratable } from "../components/hydration.js";
+import { getHostName, getHydrationDiagnostic, } from "../hydration/diagnostics.js";
 import { buildViewBindingTargets, createRangeForNodes, HydrationTargetElementError, targetFactory, } from "../hydration/target-builder.js";
 import { SourceLifetime } from "../observation/observable.js";
 import { makeSerializationNoop } from "../platform.js";
@@ -30,11 +31,23 @@ export 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;
     }
 }
 export class HydrationView extends DefaultExecutionContext {
@@ -120,13 +133,12 @@ export 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;
@@ -164,28 +176,9 @@ export 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);
                 }
             }
         }

package/dist/esm/templating/render.js

@@ -4,11 +4,12 @@ import { oneTime } from "../binding/one-time.js";
 import { oneWay } from "../binding/one-way.js";
 import { FASTElementDefinition } from "../components/fast-definitions.js";
 import { isHydratable } from "../components/hydration.js";
-import { isFunction, isString } from "../interfaces.js";
+import { isFunction, isString, Message } from "../interfaces.js";
+import { FAST } from "../platform.js";
 import { HTMLDirective, } from "./html-directive.js";
+import { HydrationStage } from "./hydration-view.js";
 import { Markup } from "./markup.js";
 import { html, ViewTemplate, } from "./template.js";
-import { HydrationStage } from "./hydration-view.js";
 /**
  * A Behavior that enables advanced rendering.
  * @public
@@ -45,11 +46,10 @@ export 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.
@@ -172,6 +172,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 createElementTemplate(tagName, options) {
     const markup = [];
     const values = [];
@@ -251,6 +277,13 @@ function register(optionsOrInstruction) {
     const instruction = instanceOf(optionsOrInstruction)
         ? optionsOrInstruction
         : create(optionsOrInstruction);
+    if (lookup[instruction.name] !== void 0) {
+        const typeName = instruction.type.name || "(anonymous)";
+        FAST.warn(Message.duplicateRenderInstruction, {
+            type: typeName,
+            name: instruction.name,
+        });
+    }
     return (lookup[instruction.name] = instruction);
 }
 function getByType(type, name) {
@@ -425,19 +458,7 @@ export 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);