@microsoft/fast-element 2.10.1 → 2.10.3

package/dist/dts/templating/html-directive.d.ts

@@ -143,7 +143,13 @@ export declare const HTMLDirective: Readonly<{
      */
     define<TType extends Constructable<HTMLDirective>>(type: TType, options?: PartialHTMLDirectiveDefinition): TType;
     /**
-     *
+     * Determines the DOM aspect type for a directive based on attribute name prefix.
+     * The prefix convention maps to aspect types as follows:
+     *   - No prefix (e.g. "class")  → DOMAspect.attribute
+     *   - ":" prefix (e.g. ":value") → DOMAspect.property (":classList" → DOMAspect.tokenList)
+     *   - "?" prefix (e.g. "?disabled") → DOMAspect.booleanAttribute
+     *   - `@` prefix (e.g. `@click`) → DOMAspect.event
+     *   - Falsy or absent value → DOMAspect.content (see remarks)
      * @param directive - The directive to assign the aspect to.
      * @param value - The value to base the aspect determination on.
      * @remarks

package/dist/dts/templating/template.d.ts

@@ -142,7 +142,25 @@ export declare class ViewTemplate<TSource = any, TParent = any> implements Eleme
      */
     render(source: TSource, host: Node, hostBindingTarget?: Element): HTMLView<TSource, TParent>;
     /**
-     * Creates a template based on a set of static strings and dynamic values.
+     * Processes the tagged template literal's static strings and interpolated values and
+     * creates a ViewTemplate.
+     *
+     * For each interpolated value:
+     * 1. Functions (binding expressions, e.g., `x => x.name`) → wrapped in a one-way HTMLBindingDirective
+     * 2. Binding instances → wrapped in an HTMLBindingDirective
+     * 3. HTMLDirective instances → used as-is
+     * 4. Static values (strings, numbers) → wrapped in a one-time HTMLBindingDirective
+     *
+     * Each directive's createHTML() is called with an `add` callback that registers
+     * the factory in the factories record under a unique ID and returns that ID.
+     * The directive inserts a placeholder marker (e.g., `fast-abc123{0}fast-abc123`) into
+     * the HTML string so the compiler can later find and associate it with the factory.
+     *
+     * Aspect detection happens here too: the `lastAttributeNameRegex` checks whether
+     * the placeholder appears inside an attribute value, and if so, assignAspect()
+     * sets the correct DOMAspect (attribute, property, event, etc.) based on the
+     * attribute name prefix.
+     *
      * @param strings - The static strings to create the template with.
      * @param values - The dynamic values to create the template with.
      * @param policy - The DOMPolicy to associated with the template.

package/dist/dts/templating/view.d.ts

@@ -197,6 +197,17 @@ export declare class HTMLView<TSource = any, TParent = any> extends DefaultExecu
     }): void;
     /**
      * Binds a view's behaviors to its binding source.
+     *
+     * On the first call, this iterates through all compiled factories, calling
+     * createBehavior() on each to produce a ViewBehavior instance (e.g., an
+     * HTMLBindingDirective), and then immediately binds it. This is where event
+     * listeners are registered, expression observers are created, and initial
+     * DOM values are set.
+     *
+     * On subsequent calls with a new source, existing behaviors are re-bound
+     * to the new data source, which re-evaluates all binding expressions and
+     * updates the DOM accordingly.
+     *
      * @param source - The binding source for the view's binding behaviors.
      * @param context - The execution context to run the behaviors within.
      */

package/dist/dts/testing/models.d.ts

@@ -0,0 +1,20 @@
+declare class ChildModel {
+    value: string;
+}
+declare class Model {
+    childChangedCalled: boolean;
+    trigger: number;
+    value: number;
+    child: ChildModel;
+    child2: ChildModel;
+    childChanged(): void;
+    incrementTrigger(): void;
+    decrementTrigger(): void;
+    get ifConditional(): number;
+}
+declare class DerivedModel extends Model {
+    child2ChangedCalled: boolean;
+    child2Changed(): void;
+    derivedChild: ChildModel;
+}
+export { ChildModel, DerivedModel, Model };

package/dist/dts/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.47.0"
+      "packageVersion": "7.57.7"
     }
   ]
 }

package/dist/esm/components/element-controller.js

@@ -731,6 +731,9 @@ export class HydratableElementController extends ElementController {
         // Initialize needsHydration on first connect
         this.needsHydration =
             (_a = this.needsHydration) !== null && _a !== void 0 ? _a : this.source.hasAttribute(needsHydrationAttribute);
+        if (this.needsHydration) {
+            this.addHydratingInstance();
+        }
         // If the `defer-hydration` attribute exists on the source,
         // wait for it to be removed before continuing connection behavior.
         if (this.source.hasAttribute(deferHydrationAttribute)) {

package/dist/esm/components/hydration.js

@@ -1,4 +1,21 @@
 import { FAST } from "../platform.js";
+/**
+ * Regex patterns for parsing hydration markers embedded as HTML comments by the SSR renderer.
+ * Each marker type encodes factory indices so the client can map markers back to ViewBehaviorFactories.
+ *
+ * Content binding markers bracket text/template content:
+ *   <!-- fe-b$$start$$<factoryIndex>$$<uniqueId>$$fe-b -->
+ *   ...content...
+ *   <!-- fe-b$$end$$<factoryIndex>$$<uniqueId>$$fe-b -->
+ *
+ * Repeat markers bracket each repeated item:
+ *   <!-- fe-repeat$$start$$<itemIndex>$$fe-repeat -->
+ *   <!-- fe-repeat$$end$$<itemIndex>$$fe-repeat -->
+ *
+ * Element boundary markers demarcate nested custom elements so parent walkers can skip them:
+ *   <!-- fe-eb$$start$$<elementId>$$fe-eb -->
+ *   <!-- fe-eb$$end$$<elementId>$$fe-eb -->
+ */
 const bindingStartMarker = /fe-b\$\$start\$\$(\d+)\$\$(.+)\$\$fe-b/;
 const bindingEndMarker = /fe-b\$\$end\$\$(\d+)\$\$(.+)\$\$fe-b/;
 const repeatViewStartMarker = /fe-repeat\$\$start\$\$(\d+)\$\$fe-repeat/;

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

@@ -43,7 +43,23 @@ function isShadowRoot(node) {
     return node instanceof DocumentFragment && "mode" in node;
 }
 /**
- * Maps {@link CompiledViewBehaviorFactory} ids to the corresponding node targets for the view.
+ * Maps compiled ViewBehaviorFactory IDs to their corresponding DOM nodes in the
+ * server-rendered shadow root. Uses a TreeWalker to scan the existing DOM between
+ * firstNode and lastNode, parsing hydration markers to build the targets map.
+ *
+ * For element nodes: parses `data-fe-b` (or variant) attributes to identify which
+ * factories target each element, then removes the marker attribute.
+ *
+ * For comment nodes: parses content binding markers (`fe-b$$start/end$$`) to find
+ * the DOM range controlled by each content binding. Single text nodes become the
+ * direct target; multi-node ranges are stored in boundaries for structural directives.
+ * Element boundary markers (`fe-eb$$start/end$$`) cause the walker to skip over
+ * nested custom elements that handle their own hydration.
+ *
+ * Host bindings (targetNodeId='h') appear at the start of the factories array but
+ * have no SSR markers — getHydrationIndexOffset() computes how many to skip so that
+ * marker indices align with the correct non-host factories.
+ *
  * @param firstNode - The first node of the view.
  * @param lastNode -  The last node of the view.
  * @param factories - The Compiled View Behavior Factories that belong to the view.
@@ -169,6 +185,11 @@ function skipToElementBoundaryEndMarker(node, walker) {
         current = walker.nextSibling();
     }
 }
+/**
+ * Counts how many factories at the start of the array are host bindings (targetNodeId='h').
+ * Host bindings target the custom element itself and are not represented by SSR markers,
+ * so the marker indices must be offset by this count to align with the correct factory.
+ */
 function getHydrationIndexOffset(factories) {
     let offset = 0;
     for (let i = 0, ii = factories.length; i < ii; ++i) {

package/dist/esm/templating/compiler.js

@@ -7,6 +7,12 @@ import { HTMLBindingDirective } from "./html-binding-directive.js";
 import { HTMLDirective, } from "./html-directive.js";
 import { nextId, Parser } from "./markup.js";
 import { HTMLView } from "./view.js";
+/**
+ * Builds a hierarchical node ID by appending the child index to the parent's ID.
+ * For example, the third child of root is "r.2", and its first child is "r.2.0".
+ * These IDs are used as property names on the targets prototype so that each
+ * binding's target DOM node can be lazily resolved via a chain of childNodes lookups.
+ */
 const targetIdFrom = (parentId, nodeIndex) => `${parentId}.${nodeIndex}`;
 const descriptorCache = {};
 // used to prevent creating lots of objects just to track node and index while compiling
@@ -56,6 +62,13 @@ class CompilationContext {
         this.proto = Object.create(null, this.descriptors);
         return this;
     }
+    /**
+     * Registers a lazy getter on the targets prototype that resolves a DOM node
+     * by navigating from its parent's childNodes at the given index. Getters are
+     * chained: accessing targets["r.0.2"] first resolves targets["r.0"] (which
+     * resolves targets["r"]), then returns childNodes[2]. Results are cached so
+     * each node is resolved at most once per view instance.
+     */
     addTargetDescriptor(parentId, targetId, targetIndex) {
         const descriptors = this.descriptors;
         if (targetId === "r" || // root
@@ -66,7 +79,7 @@ class CompilationContext {
         if (!descriptors[parentId]) {
             const index = parentId.lastIndexOf(".");
             const grandparentId = parentId.substring(0, index);
-            const childIndex = parseInt(parentId.substring(index + 1));
+            const childIndex = parseInt(parentId.substring(index + 1), 10);
             this.addTargetDescriptor(grandparentId, parentId, childIndex);
         }
         let descriptor = descriptorCache[targetId];
@@ -81,13 +94,20 @@ class CompilationContext {
         }
         descriptors[targetId] = descriptor;
     }
+    /**
+     * Creates a new HTMLView by cloning the compiled DocumentFragment and building
+     * a targets object. The targets prototype contains lazy getters that resolve
+     * each binding's target DOM node via childNodes traversal. Accessing every
+     * registered nodeId eagerly triggers the getter chain so all nodes are resolved
+     * before behaviors are bound.
+     */
     createView(hostBindingTarget) {
         const fragment = this.fragment.cloneNode(true);
         const targets = Object.create(this.proto);
-        targets.r = fragment;
-        targets.h = hostBindingTarget !== null && hostBindingTarget !== void 0 ? hostBindingTarget : warningHost;
+        targets.r = fragment; // root — the cloned DocumentFragment
+        targets.h = hostBindingTarget !== null && hostBindingTarget !== void 0 ? hostBindingTarget : warningHost; // host — the custom element
         for (const id of this.nodeIds) {
-            targets[id]; // trigger locator
+            Reflect.get(targets, id); // trigger lazy getter to resolve and cache the DOM node
         }
         return new HTMLView(fragment, this.factories, targets);
     }
@@ -107,7 +127,6 @@ function compileAttributes(context, parentId, node, nodeId, nodeIndex, includeBa
             }
         }
         else {
-            /* eslint-disable-next-line @typescript-eslint/no-use-before-define */
             result = Compiler.aggregate(parseResult, context.policy);
         }
         if (result !== null) {
@@ -152,7 +171,6 @@ function compileChildren(context, parent, parentId) {
     let nodeIndex = 0;
     let childNode = parent.firstChild;
     while (childNode) {
-        /* eslint-disable-next-line @typescript-eslint/no-use-before-define */
         const result = compileNode(context, parentId, childNode, nodeIndex);
         childNode = result.node;
         nodeIndex = result.index;
@@ -167,14 +185,14 @@ function compileNode(context, parentId, node, nodeIndex) {
             break;
         case 3: // text node
             return compileContent(context, node, parentId, nodeId, nodeIndex);
-        case 8: // comment
+        case 8: {
+            // comment
             const parts = Parser.parse(node.data, context.directives);
             if (parts !== null) {
-                context.addFactory(
-                /* eslint-disable-next-line @typescript-eslint/no-use-before-define */
-                Compiler.aggregate(parts), parentId, nodeId, nodeIndex, null);
+                context.addFactory(Compiler.aggregate(parts), parentId, nodeId, nodeIndex, null);
             }
             break;
+        }
     }
     next.index = nodeIndex + 1;
     next.node = node.nextSibling;
@@ -182,7 +200,7 @@ function compileNode(context, parentId, node, nodeIndex) {
 }
 function isMarker(node, directives) {
     return (node &&
-        node.nodeType == 8 &&
+        node.nodeType === 8 &&
         Parser.parse(node.data, directives) !== null);
 }
 const templateTag = "TEMPLATE";

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

@@ -9,6 +9,14 @@ import { HydrationStage } from "./view.js";
 function isContentTemplate(value) {
     return value.create !== undefined;
 }
+/**
+ * Sink function for DOMAspect.content bindings (text content interpolation).
+ * Handles two cases:
+ * - If the value is a ContentTemplate (has a create() method), it composes a child
+ *   view into the DOM, managing view lifecycle (create/reuse/remove/bind).
+ * - If the value is a primitive, it sets target.textContent directly, first removing
+ *   any previously composed view.
+ */
 function updateContent(target, aspect, value, controller) {
     // If there's no actual value, then this equates to the
     // empty string for the purposes of content bindings.
@@ -77,6 +85,12 @@ function updateContent(target, aspect, value, controller) {
         target.textContent = value;
     }
 }
+/**
+ * Sink function for DOMAspect.tokenList bindings (e.g., :classList).
+ * Uses a versioning scheme to efficiently track which CSS classes were added
+ * in the current update vs. the previous one. Classes from the previous version
+ * that aren't present in the new value are automatically removed.
+ */
 function updateTokenList(target, aspect, value) {
     var _a;
     const lookup = `${this.id}-t`;
@@ -109,6 +123,12 @@ function updateTokenList(target, aspect, value) {
         }
     }
 }
+/**
+ * Maps each DOMAspect type to its corresponding DOM update ("sink") function.
+ * When a binding value changes, the sink function for the binding's aspect type
+ * is called to push the new value into the DOM. Events are handled separately
+ * via addEventListener in bind(), so the event sink is a no-op.
+ */
 const sinkLookup = {
     [DOMAspect.attribute]: DOM.setAttribute,
     [DOMAspect.booleanAttribute]: DOM.setBooleanAttribute,
@@ -118,7 +138,18 @@ const sinkLookup = {
     [DOMAspect.event]: () => void 0,
 };
 /**
- * A directive that applies bindings.
+ * The central binding directive that bridges data expressions and DOM updates.
+ *
+ * HTMLBindingDirective fulfills three roles simultaneously:
+ * - **HTMLDirective**: Produces placeholder HTML via createHTML() during template authoring.
+ * - **ViewBehaviorFactory**: Creates behaviors (returns itself) during view creation.
+ * - **ViewBehavior / EventListener**: Attaches to a DOM node during bind, manages
+ *   expression observers for reactive updates, and handles DOM events directly.
+ *
+ * The aspectType (set by HTMLDirective.assignAspect during template processing)
+ * determines which DOM "sink" function is used to apply values — e.g.,
+ * setAttribute for attributes, addEventListener for events, textContent for content.
+ *
  * @public
  */
 export class HTMLBindingDirective {
@@ -157,7 +188,18 @@ export class HTMLBindingDirective {
         }
         return this;
     }
-    /** @internal */
+    /**
+     * Attaches this binding to its target DOM node.
+     * - For events: stores the controller reference on the target element and registers
+     *   this directive as the EventListener via addEventListener. The directive's
+     *   handleEvent() method will be called when the event fires.
+     * - For content bindings: registers an unbind handler, then falls through to the
+     *   default path.
+     * - For all non-event bindings: creates (or reuses) an ExpressionObserver, evaluates
+     *   the binding expression, and applies the result to the DOM via the updateTarget
+     *   sink function. The observer will call handleChange() on future data changes.
+     * @internal
+     */
     bind(controller) {
         var _a;
         const target = controller.targets[this.targetNodeId];
@@ -196,7 +238,14 @@ export class HTMLBindingDirective {
             view.needsBindOnly = true;
         }
     }
-    /** @internal */
+    /**
+     * Implements the EventListener interface. When a DOM event fires on the target
+     * element, this method retrieves the ViewController stored on the element,
+     * sets the event on the ExecutionContext so `c.event` is available to the
+     * binding expression, and evaluates the expression. If the expression returns
+     * anything other than `true`, the event's default action is prevented.
+     * @internal
+     */
     handleEvent(event) {
         const controller = event.currentTarget[this.data];
         if (controller.isBound) {
@@ -208,7 +257,13 @@ export class HTMLBindingDirective {
             }
         }
     }
-    /** @internal */
+    /**
+     * Called by the ExpressionObserver when a tracked dependency changes.
+     * Re-evaluates the binding expression via observer.bind() and pushes
+     * the new value to the DOM through the updateTarget sink function.
+     * This is the reactive update path that keeps the DOM in sync with data.
+     * @internal
+     */
     handleChange(binding, observer) {
         const target = observer.target;
         const controller = observer.controller;

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

@@ -29,7 +29,13 @@ export const HTMLDirective = Object.freeze({
         return type;
     },
     /**
-     *
+     * Determines the DOM aspect type for a directive based on attribute name prefix.
+     * The prefix convention maps to aspect types as follows:
+     *   - No prefix (e.g. "class")  → DOMAspect.attribute
+     *   - ":" prefix (e.g. ":value") → DOMAspect.property (":classList" → DOMAspect.tokenList)
+     *   - "?" prefix (e.g. "?disabled") → DOMAspect.booleanAttribute
+     *   - `@` prefix (e.g. `@click`) → DOMAspect.event
+     *   - Falsy or absent value → DOMAspect.content (see remarks)
      * @param directive - The directive to assign the aspect to.
      * @param value - The value to base the aspect determination on.
      * @remarks

package/dist/esm/templating/install-hydratable-view-templates.js

@@ -5,6 +5,12 @@ import { HydrationView } from "./view.js";
 // and a hydrate method. Augmenting the hydration features is done by
 // property assignment instead of class extension to better allow the
 // hydration feature to be tree-shaken.
+//
+// When hydrate() is called, it creates a HydrationView that wraps the
+// pre-rendered DOM range (firstChild → lastChild) instead of cloning a
+// compiled DocumentFragment. The HydrationView will then use
+// buildViewBindingTargets() to scan for hydration markers and attach
+// reactive bindings to the existing DOM nodes.
 Object.defineProperties(ViewTemplate.prototype, {
     [Hydratable]: { value: Hydratable, enumerable: false, configurable: false },
     hydrate: {

package/dist/esm/templating/markup.js

@@ -1,3 +1,9 @@
+/**
+ * A unique per-session random marker string used to create placeholder tokens in HTML.
+ * Bindings embedded in template literals are replaced with interpolation markers
+ * of the form `fast-xxxxxx{id}fast-xxxxxx` so the compiler can later locate them in the
+ * parsed DOM and associate each marker with its ViewBehaviorFactory.
+ */
 const marker = `fast-${Math.random().toString(36).substring(2, 8)}`;
 const interpolationStart = `${marker}{`;
 const interpolationEnd = `}${marker}`;
@@ -49,6 +55,8 @@ export const Parser = Object.freeze({
      * directives or null if no directives are found in the string.
      */
     parse(value, factories) {
+        // Split on the interpolation start marker. If there's only one part,
+        // no placeholders exist and we return null to signal "no directives here."
         const parts = value.split(interpolationStart);
         if (parts.length === 1) {
             return null;

package/dist/esm/templating/template.js

@@ -122,7 +122,25 @@ export class ViewTemplate {
         return view;
     }
     /**
-     * Creates a template based on a set of static strings and dynamic values.
+     * Processes the tagged template literal's static strings and interpolated values and
+     * creates a ViewTemplate.
+     *
+     * For each interpolated value:
+     * 1. Functions (binding expressions, e.g., `x => x.name`) → wrapped in a one-way HTMLBindingDirective
+     * 2. Binding instances → wrapped in an HTMLBindingDirective
+     * 3. HTMLDirective instances → used as-is
+     * 4. Static values (strings, numbers) → wrapped in a one-time HTMLBindingDirective
+     *
+     * Each directive's createHTML() is called with an `add` callback that registers
+     * the factory in the factories record under a unique ID and returns that ID.
+     * The directive inserts a placeholder marker (e.g., `fast-abc123{0}fast-abc123`) into
+     * the HTML string so the compiler can later find and associate it with the factory.
+     *
+     * Aspect detection happens here too: the `lastAttributeNameRegex` checks whether
+     * the placeholder appears inside an attribute value, and if so, assignAspect()
+     * sets the correct DOMAspect (attribute, property, event, etc.) based on the
+     * attribute name prefix.
+     *
      * @param strings - The static strings to create the template with.
      * @param values - The dynamic values to create the template with.
      * @param policy - The DOMPolicy to associated with the template.

package/dist/esm/templating/view.js

@@ -177,6 +177,17 @@ export class HTMLView extends DefaultExecutionContext {
     }
     /**
      * Binds a view's behaviors to its binding source.
+     *
+     * On the first call, this iterates through all compiled factories, calling
+     * createBehavior() on each to produce a ViewBehavior instance (e.g., an
+     * HTMLBindingDirective), and then immediately binds it. This is where event
+     * listeners are registered, expression observers are created, and initial
+     * DOM values are set.
+     *
+     * On subsequent calls with a new source, existing behaviors are re-bound
+     * to the new data source, which re-evaluates all binding expressions and
+     * updates the DOM accordingly.
+     *
      * @param source - The binding source for the view's binding behaviors.
      * @param context - The execution context to run the behaviors within.
      */
@@ -186,6 +197,8 @@ export class HTMLView extends DefaultExecutionContext {
         }
         let behaviors = this.behaviors;
         if (behaviors === null) {
+            // First bind: create behaviors from factories and bind each one.
+            // The view (this) acts as the ViewController, providing targets and source.
             this.source = source;
             this.context = context;
             this.behaviors = behaviors = new Array(this.factories.length);

package/dist/esm/testing/models.js

@@ -0,0 +1,58 @@
+import { Observable, observable } from "../observation/observable.js";
+class ChildModel {
+}
+observable(ChildModel.prototype, "value");
+ChildModel.prototype.value = "value";
+class Model {
+    constructor() {
+        this.childChangedCalled = false;
+    }
+    childChanged() {
+        this.childChangedCalled = true;
+    }
+    incrementTrigger() {
+        this.trigger++;
+    }
+    decrementTrigger() {
+        this.trigger--;
+    }
+    get ifConditional() {
+        Observable.trackVolatile();
+        if (this.trigger < 1) {
+            return 42;
+        }
+        return this.value;
+    }
+}
+observable(Model.prototype, "child");
+Model.prototype.child = new ChildModel();
+observable(Model.prototype, "child2");
+Model.prototype.child2 = new ChildModel();
+observable(Model.prototype, "trigger");
+Model.prototype.trigger = 0;
+observable(Model.prototype, "value");
+Model.prototype.value = 10;
+Object.defineProperty(Model.prototype, "ternaryConditional", {
+    get() {
+        Observable.trackVolatile();
+        return this.trigger < 1 ? 42 : this.value;
+    },
+});
+Object.defineProperty(Model.prototype, "andCondition", {
+    get() {
+        Observable.trackVolatile();
+        return this.trigger && this.value;
+    },
+});
+class DerivedModel extends Model {
+    constructor() {
+        super(...arguments);
+        this.child2ChangedCalled = false;
+    }
+    child2Changed() {
+        this.child2ChangedCalled = true;
+    }
+}
+observable(DerivedModel.prototype, "derivedChild");
+DerivedModel.prototype.derivedChild = new ChildModel();
+export { ChildModel, DerivedModel, Model };

package/dist/fast-element.api.json

@@ -1,7 +1,7 @@
 {
   "metadata": {
     "toolPackage": "@microsoft/api-extractor",
-    "toolVersion": "7.47.0",
+    "toolVersion": "7.57.7",
     "schemaVersion": 1011,
     "oldestForwardsCompatibleVersion": 1001,
     "tsdocConfig": {
@@ -114,6 +114,22 @@
           "tagName": "@virtual",
           "syntaxKind": "modifier"
         },
+        {
+          "tagName": "@jsx",
+          "syntaxKind": "block"
+        },
+        {
+          "tagName": "@jsxRuntime",
+          "syntaxKind": "block"
+        },
+        {
+          "tagName": "@jsxFrag",
+          "syntaxKind": "block"
+        },
+        {
+          "tagName": "@jsxImportSource",
+          "syntaxKind": "block"
+        },
         {
           "tagName": "@betaDocumentation",
           "syntaxKind": "modifier"
@@ -10541,7 +10557,7 @@
         {
           "kind": "Class",
           "canonicalReference": "@microsoft/fast-element!HTMLBindingDirective:class",
-          "docComment": "/**\n * A directive that applies bindings.\n *\n * @public\n */\n",
+          "docComment": "/**\n * The central binding directive that bridges data expressions and DOM updates.\n *\n * HTMLBindingDirective fulfills three roles simultaneously: - **HTMLDirective**: Produces placeholder HTML via createHTML() during template authoring. - **ViewBehaviorFactory**: Creates behaviors (returns itself) during view creation. - **ViewBehavior / EventListener**: Attaches to a DOM node during bind, manages expression observers for reactive updates, and handles DOM events directly.\n *\n * The aspectType (set by HTMLDirective.assignAspect during template processing) determines which DOM \"sink\" function is used to apply values — e.g., setAttribute for attributes, addEventListener for events, textContent for content.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -11807,7 +11823,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/fast-element!HTMLView#bind:member(1)",
-              "docComment": "/**\n * Binds a view's behaviors to its binding source.\n *\n * @param source - The binding source for the view's binding behaviors.\n *\n * @param context - The execution context to run the behaviors within.\n */\n",
+              "docComment": "/**\n * Binds a view's behaviors to its binding source.\n *\n * On the first call, this iterates through all compiled factories, calling createBehavior() on each to produce a ViewBehavior instance (e.g., an HTMLBindingDirective), and then immediately binds it. This is where event listeners are registered, expression observers are created, and initial DOM values are set.\n *\n * On subsequent calls with a new source, existing behaviors are re-bound to the new data source, which re-evaluates all binding expressions and updates the DOM accordingly.\n *\n * @param source - The binding source for the view's binding behaviors.\n *\n * @param context - The execution context to run the behaviors within.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -23074,7 +23090,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/fast-element!ViewTemplate.create:member(1)",
-              "docComment": "/**\n * Creates a template based on a set of static strings and dynamic values.\n *\n * @remarks\n *\n * This API should not be used directly under normal circumstances because constructing a template in this way, if not done properly, can open up the application to XSS attacks. When using this API, provide a strong DOMPolicy that can properly sanitize and also be sure to manually sanitize all static strings particularly if they can come from user input.\n *\n * @param strings - The static strings to create the template with.\n *\n * @param values - The dynamic values to create the template with.\n *\n * @param policy - The DOMPolicy to associated with the template.\n *\n * @returns A ViewTemplate.\n */\n",
+              "docComment": "/**\n * Processes the tagged template literal's static strings and interpolated values and creates a ViewTemplate.\n *\n * For each interpolated value: 1. Functions (binding expressions, e.g., `x => x.name`) → wrapped in a one-way HTMLBindingDirective 2. Binding instances → wrapped in an HTMLBindingDirective 3. HTMLDirective instances → used as-is 4. Static values (strings, numbers) → wrapped in a one-time HTMLBindingDirective\n *\n * Each directive's createHTML() is called with an `add` callback that registers the factory in the factories record under a unique ID and returns that ID. The directive inserts a placeholder marker (e.g., `fast-abc123{0}fast-abc123`) into the HTML string so the compiler can later find and associate it with the factory.\n *\n * Aspect detection happens here too: the `lastAttributeNameRegex` checks whether the placeholder appears inside an attribute value, and if so, assignAspect() sets the correct DOMAspect (attribute, property, event, etc.) based on the attribute name prefix.\n *\n * @remarks\n *\n * This API should not be used directly under normal circumstances because constructing a template in this way, if not done properly, can open up the application to XSS attacks. When using this API, provide a strong DOMPolicy that can properly sanitize and also be sure to manually sanitize all static strings particularly if they can come from user input.\n *\n * @param strings - The static strings to create the template with.\n *\n * @param values - The dynamic values to create the template with.\n *\n * @param policy - The DOMPolicy to associated with the template.\n *\n * @returns A ViewTemplate.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",