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

package/dist/hydration/hydration.api.json

@@ -195,11 +195,51 @@
           "excerptTokens": [
             {
               "kind": "Content",
-              "text": "export interface CaptureType "
+              "text": "export interface CaptureType<TSource = "
+            },
+            {
+              "kind": "Content",
+              "text": "any"
+            },
+            {
+              "kind": "Content",
+              "text": ", TParent = "
+            },
+            {
+              "kind": "Content",
+              "text": "any"
+            },
+            {
+              "kind": "Content",
+              "text": "> "
             }
           ],
           "fileUrlPath": "dist/dts/templating/template.d.ts",
           "releaseTag": "Public",
+          "typeParameters": [
+            {
+              "typeParameterName": "TSource",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "typeParameterName": "TParent",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              }
+            }
+          ],
           "name": "CaptureType",
           "preserveMemberOrder": false,
           "members": [],
@@ -1069,17 +1109,235 @@
             "endIndex": 3
           }
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@microsoft/fast-element!DOMAspectGuards:type",
+          "docComment": "/**\n * Aspect-specific guards for a DOM Policy.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type DOMAspectGuards = "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    ["
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMAspect.attribute",
+              "canonicalReference": "@microsoft/fast-element!~attribute"
+            },
+            {
+              "kind": "Content",
+              "text": "]?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMSinkGuards",
+              "canonicalReference": "@microsoft/fast-element!DOMSinkGuards:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n    ["
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMAspect.booleanAttribute",
+              "canonicalReference": "@microsoft/fast-element!~booleanAttribute"
+            },
+            {
+              "kind": "Content",
+              "text": "]?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMSinkGuards",
+              "canonicalReference": "@microsoft/fast-element!DOMSinkGuards:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n    ["
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMAspect.property",
+              "canonicalReference": "@microsoft/fast-element!~property"
+            },
+            {
+              "kind": "Content",
+              "text": "]?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMSinkGuards",
+              "canonicalReference": "@microsoft/fast-element!DOMSinkGuards:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n    ["
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMAspect.content",
+              "canonicalReference": "@microsoft/fast-element!~content"
+            },
+            {
+              "kind": "Content",
+              "text": "]?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMSinkGuards",
+              "canonicalReference": "@microsoft/fast-element!DOMSinkGuards:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n    ["
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMAspect.tokenList",
+              "canonicalReference": "@microsoft/fast-element!~tokenList"
+            },
+            {
+              "kind": "Content",
+              "text": "]?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMSinkGuards",
+              "canonicalReference": "@microsoft/fast-element!DOMSinkGuards:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n    ["
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMAspect.event",
+              "canonicalReference": "@microsoft/fast-element!~event"
+            },
+            {
+              "kind": "Content",
+              "text": "]?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMSinkGuards",
+              "canonicalReference": "@microsoft/fast-element!DOMSinkGuards:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n}"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/dts/dom-policy.d.ts",
+          "releaseTag": "Public",
+          "name": "DOMAspectGuards",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 26
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@microsoft/fast-element!DOMElementGuards:type",
+          "docComment": "/**\n * Element-specific guards for a DOM Policy.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type DOMElementGuards = "
+            },
+            {
+              "kind": "Reference",
+              "text": "Record",
+              "canonicalReference": "!Record:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<string, "
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMAspectGuards",
+              "canonicalReference": "@microsoft/fast-element!DOMAspectGuards:type"
+            },
+            {
+              "kind": "Content",
+              "text": ">"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/dts/dom-policy.d.ts",
+          "releaseTag": "Public",
+          "name": "DOMElementGuards",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 5
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@microsoft/fast-element!DOMGuards:type",
+          "docComment": "/**\n * Guard configuration for a DOM Policy.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type DOMGuards = "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    elements: "
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMElementGuards",
+              "canonicalReference": "@microsoft/fast-element!DOMElementGuards:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n    aspects: "
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMAspectGuards",
+              "canonicalReference": "@microsoft/fast-element!DOMAspectGuards:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n}"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/dts/dom-policy.d.ts",
+          "releaseTag": "Public",
+          "name": "DOMGuards",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 6
+          }
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@microsoft/fast-element!DOMPolicy:interface",
-          "docComment": "/**\n * A security policy that FAST can use to interact with the DOM.\n *\n * @public\n */\n",
+          "docComment": "/**\n * A policy that controls whether values can be written to DOM sinks.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
               "text": "export interface DOMPolicy "
             }
           ],
-          "fileUrlPath": "dist/dts/dom.d.ts",
+          "fileUrlPath": "dist/dts/dom-policy.d.ts",
           "releaseTag": "Public",
           "name": "DOMPolicy",
           "preserveMemberOrder": false,
@@ -1229,88 +1487,254 @@
           "extendsTokenRanges": []
         },
         {
-          "kind": "TypeAlias",
-          "canonicalReference": "@microsoft/fast-element!DOMSink:type",
-          "docComment": "/**\n * A function used to send values to a DOM sink.\n *\n * @public\n */\n",
+          "kind": "Variable",
+          "canonicalReference": "@microsoft/fast-element!DOMPolicy:var",
+          "docComment": "/**\n * A helper for creating DOM policies.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
-              "text": "export type DOMSink = "
+              "text": "DOMPolicy: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Readonly",
+              "canonicalReference": "!Readonly:type"
             },
             {
               "kind": "Content",
-              "text": "(target: "
+              "text": "<{\n    create(options?: "
             },
             {
               "kind": "Reference",
-              "text": "Node",
-              "canonicalReference": "!Node:interface"
+              "text": "DOMPolicyOptions",
+              "canonicalReference": "@microsoft/fast-element!DOMPolicyOptions:type"
             },
             {
               "kind": "Content",
-              "text": ", aspectName: string, value: any, ...args: any[]) => void"
+              "text": "): "
+            },
+            {
+              "kind": "Reference",
+              "text": "Readonly",
+              "canonicalReference": "!Readonly:type"
             },
             {
               "kind": "Content",
-              "text": ";"
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMPolicy",
+              "canonicalReference": "@microsoft/fast-element!DOMPolicy:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ">;\n}>"
             }
           ],
-          "fileUrlPath": "dist/dts/dom.d.ts",
+          "fileUrlPath": "dist/dts/dom-policy.d.ts",
+          "isReadonly": true,
           "releaseTag": "Public",
-          "name": "DOMSink",
-          "typeTokenRange": {
+          "name": "DOMPolicy",
+          "variableTypeTokenRange": {
             "startIndex": 1,
-            "endIndex": 4
+            "endIndex": 9
           }
         },
         {
-          "kind": "Interface",
-          "canonicalReference": "@microsoft/fast-element!ElementView:interface",
-          "docComment": "/**\n * A View representing DOM nodes specifically for rendering the view of a custom element.\n *\n * @public\n */\n",
+          "kind": "TypeAlias",
+          "canonicalReference": "@microsoft/fast-element!DOMPolicyOptions:type",
+          "docComment": "/**\n * Options for creating a DOM Policy.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
-              "text": "export interface ElementView<TSource = "
+              "text": "export type DOMPolicyOptions = "
             },
             {
               "kind": "Content",
-              "text": "any"
+              "text": "{\n    trustedType?: "
             },
             {
-              "kind": "Content",
-              "text": ", TParent = "
+              "kind": "Reference",
+              "text": "TrustedTypesPolicy",
+              "canonicalReference": "@microsoft/fast-element!TrustedTypesPolicy:type"
             },
             {
               "kind": "Content",
-              "text": "any"
+              "text": ";\n    guards?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Partial",
+              "canonicalReference": "!Partial:type"
             },
             {
               "kind": "Content",
-              "text": "> extends "
+              "text": "<"
             },
             {
               "kind": "Reference",
-              "text": "View",
-              "canonicalReference": "@microsoft/fast-element!View:interface"
+              "text": "DOMGuards",
+              "canonicalReference": "@microsoft/fast-element!DOMGuards:type"
             },
             {
               "kind": "Content",
-              "text": "<TSource, TParent>"
+              "text": ">;\n}"
             },
             {
               "kind": "Content",
-              "text": " "
+              "text": ";"
             }
           ],
-          "fileUrlPath": "dist/dts/templating/view.d.ts",
+          "fileUrlPath": "dist/dts/dom-policy.d.ts",
           "releaseTag": "Public",
-          "typeParameters": [
-            {
-              "typeParameterName": "TSource",
-              "constraintTokenRange": {
-                "startIndex": 0,
-                "endIndex": 0
-              },
+          "name": "DOMPolicyOptions",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 8
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@microsoft/fast-element!DOMSink:type",
+          "docComment": "/**\n * A function used to send values to a DOM sink.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type DOMSink = "
+            },
+            {
+              "kind": "Content",
+              "text": "(target: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Node",
+              "canonicalReference": "!Node:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ", aspectName: string, value: any, ...args: any[]) => void"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/dts/dom.d.ts",
+          "releaseTag": "Public",
+          "name": "DOMSink",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 4
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@microsoft/fast-element!DOMSinkGuards:type",
+          "docComment": "/**\n * A specific DOM sink guard for a node aspect.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type DOMSinkGuards = "
+            },
+            {
+              "kind": "Reference",
+              "text": "Record",
+              "canonicalReference": "!Record:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<string, (tagName: string | null, aspect: "
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMAspect",
+              "canonicalReference": "@microsoft/fast-element!DOMAspect:type"
+            },
+            {
+              "kind": "Content",
+              "text": ", aspectName: string, sink: "
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMSink",
+              "canonicalReference": "@microsoft/fast-element!DOMSink:type"
+            },
+            {
+              "kind": "Content",
+              "text": ") => "
+            },
+            {
+              "kind": "Reference",
+              "text": "DOMSink",
+              "canonicalReference": "@microsoft/fast-element!DOMSink:type"
+            },
+            {
+              "kind": "Content",
+              "text": ">"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/dts/dom-policy.d.ts",
+          "releaseTag": "Public",
+          "name": "DOMSinkGuards",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 9
+          }
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@microsoft/fast-element!ElementView:interface",
+          "docComment": "/**\n * A View representing DOM nodes specifically for rendering the view of a custom element.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface ElementView<TSource = "
+            },
+            {
+              "kind": "Content",
+              "text": "any"
+            },
+            {
+              "kind": "Content",
+              "text": ", TParent = "
+            },
+            {
+              "kind": "Content",
+              "text": "any"
+            },
+            {
+              "kind": "Content",
+              "text": "> extends "
+            },
+            {
+              "kind": "Reference",
+              "text": "View",
+              "canonicalReference": "@microsoft/fast-element!View:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<TSource, TParent>"
+            },
+            {
+              "kind": "Content",
+              "text": " "
+            }
+          ],
+          "fileUrlPath": "dist/dts/templating/view.d.ts",
+          "releaseTag": "Public",
+          "typeParameters": [
+            {
+              "typeParameterName": "TSource",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
               "defaultTypeTokenRange": {
                 "startIndex": 1,
                 "endIndex": 2
@@ -1663,7 +2087,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@microsoft/fast-element!enableHydration:function(1)",
-          "docComment": "/**\n * Enables hydration support for prerendered FAST elements.\n *\n * @remarks\n *\n * Call this before any FAST elements connect to the DOM. Hydration logic is not active unless this function is called, keeping `FASTElement` lightweight for client-side-only applications.\n *\n * Safe to call multiple times — the hydration hook is installed once and subsequent calls merge their options into the shared tracker.\n *\n * @param options - Optional callbacks for global hydration events.\n *\n * @example\n * ```ts\n * import { enableHydration } from \"@microsoft/fast-element/hydration.js\";\n *\n * enableHydration({\n *     hydrationComplete() {\n *         console.log(\"hydration complete\");\n *     },\n * });\n * ```\n *\n * @public\n */\n",
+          "docComment": "/**\n * Enables hydration support for prerendered FAST elements.\n *\n * @remarks\n *\n * Call this before any FAST elements connect to the DOM. Hydration logic is not active unless this function is called, keeping `FASTElement` lightweight for client-side-only applications.\n *\n * Safe to call multiple times — the hydration hook is installed once and subsequent calls merge their options into the shared tracker. By default, the hook stops hydrating new prerendered elements after the global `hydrationComplete` callback. Set `stopHydration` to `StopHydration.never` for streaming scenarios that append hydratable Declarative Shadow DOM after the initial batch.\n *\n * Pass `debugger: hydrationDebugger()` to swap the default minimal hydration mismatch error message for a rich \"Expected / Received\" report including the SSR HTML snippet and structured `expected`/`received` fields on `HydrationBindingError` / `HydrationTargetElementError`. The debugger module is tree-shaken out of production hydration bundles unless explicitly imported.\n *\n * @param options - Optional global hydration callbacks and behavior.\n *\n * @example\n * ```ts\n * import { enableHydration, StopHydration } from \"@microsoft/fast-element/hydration.js\";\n *\n * enableHydration({\n *     stopHydration: StopHydration.never,\n *     hydrationComplete() {\n *         console.log(\"hydration complete\");\n *     },\n * });\n * ```\n *\n * @example\n *\n * Rich hydration mismatch diagnostics\n * ```ts\n * import { enableHydration, hydrationDebugger } from \"@microsoft/fast-element/hydration.js\";\n *\n * enableHydration({ debugger: hydrationDebugger() });\n * ```\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -2137,7 +2561,7 @@
             },
             {
               "kind": "Content",
-              "text": "<any>;\n    getEvent(): "
+              "text": ";\n    getEvent(): "
             },
             {
               "kind": "Reference",
@@ -2820,6 +3244,10 @@
               "text": "ElementView",
               "canonicalReference": "@microsoft/fast-element!ElementView:interface"
             },
+            {
+              "kind": "Content",
+              "text": "<TSource, TParent>"
+            },
             {
               "kind": "Content",
               "text": ", "
@@ -2829,6 +3257,10 @@
               "text": "SyntheticView",
               "canonicalReference": "@microsoft/fast-element!SyntheticView:interface"
             },
+            {
+              "kind": "Content",
+              "text": "<TSource, TParent>"
+            },
             {
               "kind": "Content",
               "text": ", "
@@ -2989,15 +3421,15 @@
           "extendsTokenRanges": [
             {
               "startIndex": 5,
-              "endIndex": 6
+              "endIndex": 7
             },
             {
-              "startIndex": 7,
-              "endIndex": 8
+              "startIndex": 8,
+              "endIndex": 10
             },
             {
-              "startIndex": 9,
-              "endIndex": 11
+              "startIndex": 11,
+              "endIndex": 13
             }
           ]
         },
@@ -3145,6 +3577,32 @@
                   "kind": "Content",
                   "text": "string"
                 },
+                {
+                  "kind": "Content",
+                  "text": ", \n    expected?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HydrationMismatchExpectation",
+                  "canonicalReference": "@microsoft/fast-element!HydrationMismatchExpectation:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", \n    received?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HydrationMismatchActual",
+                  "canonicalReference": "@microsoft/fast-element!HydrationMismatchActual:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined"
+                },
                 {
                   "kind": "Content",
                   "text": ");"
@@ -3185,9 +3643,60 @@
                     "endIndex": 8
                   },
                   "isOptional": false
+                },
+                {
+                  "parameterName": "expected",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 9,
+                    "endIndex": 11
+                  },
+                  "isOptional": true
+                },
+                {
+                  "parameterName": "received",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 12,
+                    "endIndex": 14
+                  },
+                  "isOptional": true
                 }
               ]
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@microsoft/fast-element!HydrationBindingError#expected:member",
+              "docComment": "/**\n * Structured description of the binding the hydration walk was attempting to apply when the mismatch was detected.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly expected?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HydrationMismatchExpectation",
+                  "canonicalReference": "@microsoft/fast-element!HydrationMismatchExpectation:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "expected",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@microsoft/fast-element!HydrationBindingError#factory:member",
@@ -3250,6 +3759,41 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@microsoft/fast-element!HydrationBindingError#received:member",
+              "docComment": "/**\n * Structured description of the server-rendered DOM that was encountered at the mismatch point.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly received?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HydrationMismatchActual",
+                  "canonicalReference": "@microsoft/fast-element!HydrationMismatchActual:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "received",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@microsoft/fast-element!HydrationBindingError#templateString:member",
@@ -3287,33 +3831,552 @@
           },
           "implementsTokenRanges": []
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@microsoft/fast-element!hydrationDebugger:function(1)",
+          "docComment": "/**\n * 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`).\n *\n * 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.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function hydrationDebugger(): "
+            },
+            {
+              "kind": "Reference",
+              "text": "HydrationDebugger",
+              "canonicalReference": "@microsoft/fast-element!HydrationDebugger:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/dts/hydration/hydration-debugger.d.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [],
+          "name": "hydrationDebugger"
+        },
         {
           "kind": "Interface",
-          "canonicalReference": "@microsoft/fast-element!HydrationOptions:interface",
-          "docComment": "/**\n * Options for configuring global hydration lifecycle events.\n *\n * @public\n */\n",
+          "canonicalReference": "@microsoft/fast-element!HydrationDebugger:interface",
+          "docComment": "/**\n * Opt-in hydration debugger configuration. Pass to `enableHydration` to install the rich \"Expected / Received\" hydration mismatch formatter:\n * ```ts\n * import { enableHydration, hydrationDebugger } from \"@microsoft/fast-element/hydration.js\";\n *\n * enableHydration({ debugger: hydrationDebugger() });\n * ```\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
-              "text": "export interface HydrationOptions "
+              "text": "export interface HydrationDebugger "
             }
           ],
-          "fileUrlPath": "dist/dts/components/hydration-tracker.d.ts",
+          "fileUrlPath": "dist/dts/hydration/hydration-debugger.d.ts",
           "releaseTag": "Public",
-          "name": "HydrationOptions",
+          "name": "HydrationDebugger",
           "preserveMemberOrder": false,
           "members": [
             {
-              "kind": "MethodSignature",
-              "canonicalReference": "@microsoft/fast-element!HydrationOptions#hydrationComplete:member(1)",
-              "docComment": "/**\n * Called after all prerendered elements have completed hydration.\n */\n",
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/fast-element!HydrationDebugger#diagnostic:member",
+              "docComment": "/**\n * The {@link HydrationDiagnostic} the debugger installs when consumed by `enableHydration`.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "hydrationComplete?(): "
+                  "text": "readonly diagnostic: "
                 },
                 {
-                  "kind": "Content",
-                  "text": "void"
+                  "kind": "Reference",
+                  "text": "HydrationDiagnostic",
+                  "canonicalReference": "@microsoft/fast-element!HydrationDiagnostic:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "diagnostic",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@microsoft/fast-element!HydrationDiagnostic:interface",
+          "docComment": "/**\n * Pluggable formatter for hydration mismatch errors. The default implementation is a minimal one-line message; install {@link hydrationDebugger} to swap in the rich \"Expected … / Received …\" formatter with an HTML snippet of the SSR DOM.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface HydrationDiagnostic "
+            }
+          ],
+          "fileUrlPath": "dist/dts/hydration/diagnostics.d.ts",
+          "releaseTag": "Public",
+          "name": "HydrationDiagnostic",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@microsoft/fast-element!HydrationDiagnostic#formatBindingMismatch:member(1)",
+              "docComment": "/**\n * Format a binding-resolution mismatch (a factory whose `targetNodeId` has no entry in the resolved targets after the SSR DOM walk).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "formatBindingMismatch(factory: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ViewBehaviorFactory",
+                  "canonicalReference": "@microsoft/fast-element!ViewBehaviorFactory:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", firstChild: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Node",
+                  "canonicalReference": "!Node:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", lastChild: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Node",
+                  "canonicalReference": "!Node:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", hostName: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HydrationDiagnosticResult",
+                  "canonicalReference": "@microsoft/fast-element!HydrationDiagnosticResult:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 9,
+                "endIndex": 10
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "factory",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "firstChild",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "lastChild",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 5,
+                    "endIndex": 6
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "hostName",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 7,
+                    "endIndex": 8
+                  },
+                  "isOptional": false
+                }
+              ],
+              "name": "formatBindingMismatch"
+            },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@microsoft/fast-element!HydrationDiagnostic#formatStructuralError:member(1)",
+              "docComment": "/**\n * Format a structural error encountered during the SSR DOM walk (e.g. attribute binding count overflow, missing close marker).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "formatStructuralError(node: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Node",
+                  "canonicalReference": "!Node:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", hostName: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", expectedDescription: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HydrationDiagnosticResult",
+                  "canonicalReference": "@microsoft/fast-element!HydrationDiagnosticResult:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 7,
+                "endIndex": 8
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "node",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "hostName",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "expectedDescription",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 5,
+                    "endIndex": 6
+                  },
+                  "isOptional": false
+                }
+              ],
+              "name": "formatStructuralError"
+            }
+          ],
+          "extendsTokenRanges": []
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@microsoft/fast-element!HydrationDiagnosticResult:interface",
+          "docComment": "/**\n * Result of a hydration-mismatch diagnostic format call.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface HydrationDiagnosticResult "
+            }
+          ],
+          "fileUrlPath": "dist/dts/hydration/diagnostics.d.ts",
+          "releaseTag": "Public",
+          "name": "HydrationDiagnosticResult",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/fast-element!HydrationDiagnosticResult#expected:member",
+              "docComment": "/**\n * Structured description of the binding the hydration walk was attempting to apply. The default diagnostic leaves this `undefined`; install `hydrationDebugger()` to populate it.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "expected?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HydrationMismatchExpectation",
+                  "canonicalReference": "@microsoft/fast-element!HydrationMismatchExpectation:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "expected",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/fast-element!HydrationDiagnosticResult#message:member",
+              "docComment": "/**\n * The error message to attach to the thrown hydration error.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "message: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "message",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/fast-element!HydrationDiagnosticResult#received:member",
+              "docComment": "/**\n * Structured description of the server-rendered DOM that was encountered at the mismatch point. The default diagnostic leaves this `undefined`; install `hydrationDebugger()` to populate it.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "received?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HydrationMismatchActual",
+                  "canonicalReference": "@microsoft/fast-element!HydrationMismatchActual:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "received",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@microsoft/fast-element!HydrationMismatchActual:interface",
+          "docComment": "/**\n * Structured description of the DOM hydration actually encountered at the mismatch point.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface HydrationMismatchActual "
+            }
+          ],
+          "fileUrlPath": "dist/dts/hydration/diagnostics.d.ts",
+          "releaseTag": "Public",
+          "name": "HydrationMismatchActual",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/fast-element!HydrationMismatchActual#html:member",
+              "docComment": "/**\n * Serialized HTML snippet of the server-rendered DOM where the mismatch was detected. Truncated with an ellipsis when long.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "html: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "html",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@microsoft/fast-element!HydrationMismatchExpectation:interface",
+          "docComment": "/**\n * Structured description of the binding hydration was expecting to apply when a mismatch is detected.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface HydrationMismatchExpectation "
+            }
+          ],
+          "fileUrlPath": "dist/dts/hydration/diagnostics.d.ts",
+          "releaseTag": "Public",
+          "name": "HydrationMismatchExpectation",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/fast-element!HydrationMismatchExpectation#aspect:member",
+              "docComment": "/**\n * Human-readable description of the binding aspect, for example `\"content\"`, `\"property className\"`, or `\"attribute aria-label\"`.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "aspect: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "aspect",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/fast-element!HydrationMismatchExpectation#tagName:member",
+              "docComment": "/**\n * The tag name of the element the binding was expecting (e.g. `\"SPAN\"`), or `null` when the binding does not target a specific element (host or template-level bindings).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "tagName: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "tagName",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@microsoft/fast-element!HydrationOptions:interface",
+          "docComment": "/**\n * Options for configuring global hydration lifecycle events and behavior.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface HydrationOptions "
+            }
+          ],
+          "fileUrlPath": "dist/dts/components/hydration-tracker.d.ts",
+          "releaseTag": "Public",
+          "name": "HydrationOptions",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/fast-element!HydrationOptions#debugger:member",
+              "docComment": "/**\n * Optional opt-in debugger that swaps the default minimal hydration mismatch error message for a rich \"Expected … / Received …\" report including an HTML snippet of the SSR DOM and structured `expected`/`received` fields on `HydrationBindingError` / `HydrationTargetElementError`. Obtained via `hydrationDebugger()` from `@microsoft/fast-element/hydration.js`.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "debugger?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HydrationDebugger",
+                  "canonicalReference": "@microsoft/fast-element!HydrationDebugger:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "debugger",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@microsoft/fast-element!HydrationOptions#hydrationComplete:member(1)",
+              "docComment": "/**\n * Called after all prerendered elements in a hydration batch complete.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "hydrationComplete?(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
                 },
                 {
                   "kind": "Content",
@@ -3333,7 +4396,7 @@
             {
               "kind": "MethodSignature",
               "canonicalReference": "@microsoft/fast-element!HydrationOptions#hydrationStarted:member(1)",
-              "docComment": "/**\n * Called once when the first prerendered element begins hydrating.\n */\n",
+              "docComment": "/**\n * Called when a prerendered hydration batch begins.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -3357,6 +4420,34 @@
               "overloadIndex": 1,
               "parameters": [],
               "name": "hydrationStarted"
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@microsoft/fast-element!HydrationOptions#stopHydration:member",
+              "docComment": "/**\n * Indicates when the hydration hook should stop handling new prerendered elements.\n *\n * @defaultValue StopHydration.hydrationComplete\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "stopHydration?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "StopHydration",
+                  "canonicalReference": "@microsoft/fast-element!StopHydration:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "stopHydration",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
             }
           ],
           "extendsTokenRanges": []
@@ -3579,6 +4670,36 @@
               "isOptional": false,
               "isAbstract": false,
               "name": "remove"
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@microsoft/fast-element!HydrationTracker#shouldHydrate:member",
+              "docComment": "/**\n * Indicates whether the hydration hook should attempt to hydrate prerendered elements.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "get shouldHydrate(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "shouldHydrate",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
             }
           ],
           "implementsTokenRanges": []
@@ -3975,6 +5096,78 @@
             "endIndex": 3
           }
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@microsoft/fast-element!StopHydration:type",
+          "docComment": "/**\n * Describes when FAST should stop hydrating newly connected prerendered elements.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type StopHydration = "
+            },
+            {
+              "kind": "Content",
+              "text": "(typeof "
+            },
+            {
+              "kind": "Reference",
+              "text": "StopHydration",
+              "canonicalReference": "@microsoft/fast-element!StopHydration:var"
+            },
+            {
+              "kind": "Content",
+              "text": ")[keyof typeof "
+            },
+            {
+              "kind": "Reference",
+              "text": "StopHydration",
+              "canonicalReference": "@microsoft/fast-element!StopHydration:var"
+            },
+            {
+              "kind": "Content",
+              "text": "]"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/dts/components/hydration-tracker.d.ts",
+          "releaseTag": "Public",
+          "name": "StopHydration",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 6
+          }
+        },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@microsoft/fast-element!StopHydration:var",
+          "docComment": "/**\n * Describes when FAST should stop hydrating newly connected prerendered elements.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "StopHydration: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Readonly",
+              "canonicalReference": "!Readonly:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<{\n    readonly hydrationComplete: \"hydration-complete\";\n    readonly never: \"never\";\n}>"
+            }
+          ],
+          "fileUrlPath": "dist/dts/components/hydration-tracker.d.ts",
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "StopHydration",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 3
+          }
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@microsoft/fast-element!SyntheticView:interface",
@@ -4283,6 +5476,10 @@
                   "text": "CaptureType",
                   "canonicalReference": "@microsoft/fast-element!CaptureType:interface"
                 },
+                {
+                  "kind": "Content",
+                  "text": "<TSource, TParent>"
+                },
                 {
                   "kind": "Content",
                   "text": ";"
@@ -4291,7 +5488,7 @@
               "isOptional": false,
               "returnTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 2
+                "endIndex": 3
               },
               "releaseTag": "Public",
               "overloadIndex": 1,
@@ -4301,6 +5498,32 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@microsoft/fast-element!TrustedTypesPolicy:type",
+          "docComment": "/**\n * A policy for use with the standard trustedTypes platform API.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type TrustedTypesPolicy = "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    createHTML(html: string): string;\n}"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/dts/interfaces.d.ts",
+          "releaseTag": "Public",
+          "name": "TrustedTypesPolicy",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@microsoft/fast-element!View:interface",