From 04dad9350eb9c15a5fd8b2c80750dbd04f9042e6 Mon Sep 17 00:00:00 2001
From: John Kreitlow <863023+radium-v@users.noreply.github.com>
Date: Fri, 13 Feb 2026 15:35:34 -0800
Subject: [PATCH 1/5] feat(playwright): add device projects for cross-browser
 testing

---
 packages/fast-html/playwright.config.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/packages/fast-html/playwright.config.ts b/packages/fast-html/playwright.config.ts
index cc5227dbd6b..3328388a589 100644
--- a/packages/fast-html/playwright.config.ts
+++ b/packages/fast-html/playwright.config.ts
@@ -1,9 +1,14 @@
-import { defineConfig } from "@playwright/test";
+import { defineConfig, devices } from "@playwright/test";
 
 export default defineConfig({
     testDir: ".",
     testMatch: "**/*.spec.ts",
     retries: 3,
+    projects: [
+        { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+        { name: "firefox", use: { ...devices["Desktop Firefox"] } },
+        { name: "webkit", use: { ...devices["Desktop Safari"] } },
+    ],
     webServer: {
         command: "npm run test-server",
         port: 5173,

From bc83f617feb5a4ac6479dc5fd05799ac177533da Mon Sep 17 00:00:00 2001
From: John Kreitlow <863023+radium-v@users.noreply.github.com>
Date: Fri, 13 Feb 2026 15:44:48 -0800
Subject: [PATCH 2/5] feat(hydration): add hydrationStarted callback and update
 documentation

---
 packages/fast-element/docs/api-report.api.md  |   1 +
 .../src/components/element-controller.ts      | 100 ++++++++----------
 ...oncontrollercallbacks.elementdidhydrate.md |   2 +-
 ...ncontrollercallbacks.elementwillhydrate.md |   2 +-
 ...ioncontrollercallbacks.hydrationstarted.md |  27 +++++
 ...st-element.hydrationcontrollercallbacks.md |  15 ++-
 6 files changed, 88 insertions(+), 59 deletions(-)
 create mode 100644 sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.hydrationstarted.md

diff --git a/packages/fast-element/docs/api-report.api.md b/packages/fast-element/docs/api-report.api.md
index 64499803df7..986594dec9c 100644
--- a/packages/fast-element/docs/api-report.api.md
+++ b/packages/fast-element/docs/api-report.api.md
@@ -631,6 +631,7 @@ export interface HydrationControllerCallbacks<TElement extends HTMLElement = HTM
     elementDidHydrate?(source: TElement): void;
     elementWillHydrate?(source: TElement): void;
     hydrationComplete?(): void;
+    hydrationStarted?(): void;
 }
 
 // @public
diff --git a/packages/fast-element/src/components/element-controller.ts b/packages/fast-element/src/components/element-controller.ts
index 30fec6355c1..ef268d42d14 100644
--- a/packages/fast-element/src/components/element-controller.ts
+++ b/packages/fast-element/src/components/element-controller.ts
@@ -830,12 +830,20 @@ export interface HydrationControllerCallbacks<
     TElement extends HTMLElement = HTMLElement
 > {
     /**
-     * Called before hydration has started
+     * Called once when the first element enters the hydration pipeline.
+     * This is the earliest point at which we know a component has been
+     * async-defined with `defer-and-hydrate`, a template is pending via
+     * `<f-template>`, and the element has `needs-hydration`.
+     */
+    hydrationStarted?(): void;
+
+    /**
+     * Called before an individual element's hydration begins
      */
     elementWillHydrate?(source: TElement): void;
 
     /**
-     * Called after hydration has finished
+     * Called after an individual element's hydration has finished
      */
     elementDidHydrate?(source: TElement): void;
 
@@ -887,6 +895,11 @@ export class HydratableElementController<
      */
     public static lifecycleCallbacks: HydrationControllerCallbacks = {};
 
+    /**
+     * Whether the hydrationStarted callback has already been invoked.
+     */
+    private static hydrationStarted: boolean = false;
+
     /**
      * An idle callback ID used to track hydration completion
      */
@@ -946,7 +959,11 @@ export class HydratableElementController<
 
         // If there are no more hydrating instances, invoke the hydrationComplete callback
         if (HydratableElementController.hydratingInstances?.size === 0) {
-            HydratableElementController.notifyHydrationComplete();
+            try {
+                HydratableElementController.lifecycleCallbacks.hydrationComplete?.();
+            } catch {
+                // A lifecycle callback must never prevent post-hydration cleanup.
+            }
 
             // Reset to the default strategy after hydration is complete
             ElementController.setStrategy(ElementController);
@@ -986,7 +1003,23 @@ export class HydratableElementController<
             return;
         }
 
-        this.notifyWillHydrate();
+        if (!HydratableElementController.hydrationStarted) {
+            HydratableElementController.hydrationStarted = true;
+
+            try {
+                HydratableElementController.lifecycleCallbacks.hydrationStarted?.();
+            } catch {
+                // A lifecycle callback must never prevent hydration.
+            }
+        }
+
+        try {
+            HydratableElementController.lifecycleCallbacks.elementWillHydrate?.(
+                this.source
+            );
+        } catch {
+            // A lifecycle callback must never prevent hydration.
+        }
 
         this.stage = Stages.connecting;
 
@@ -1053,11 +1086,17 @@ export class HydratableElementController<
             return;
         }
 
+        try {
+            HydratableElementController.lifecycleCallbacks.elementDidHydrate?.(
+                this.source
+            );
+        } catch {
+            // A lifecycle callback must never prevent hydration.
+        }
+
         const name = this.definition.name;
         const instances = HydratableElementController.hydratingInstances.get(name);
 
-        this.notifyDidHydrate();
-
         if (instances) {
             instances.delete(this.source);
 
@@ -1076,55 +1115,6 @@ export class HydratableElementController<
         }
     }
 
-    /**
-     * Notifies that hydration is about to start for this element.
-     * Safely invokes the configured elementWillHydrate callback, if any.
-     */
-    private notifyWillHydrate(): void {
-        const callback =
-            HydratableElementController.lifecycleCallbacks.elementWillHydrate;
-
-        if (callback) {
-            try {
-                callback(this.source);
-            } catch {
-                // A lifecycle callback must never prevent hydration.
-            }
-        }
-    }
-
-    /**
-     * Notifies that hydration has finished for this element.
-     * Safely invokes the configured elementDidHydrate callback, if any.
-     */
-    private notifyDidHydrate(): void {
-        const callback = HydratableElementController.lifecycleCallbacks.elementDidHydrate;
-
-        if (callback) {
-            try {
-                callback(this.source);
-            } catch {
-                // A lifecycle callback must never prevent hydration.
-            }
-        }
-    }
-
-    /**
-     * Notifies that all elements have completed hydration.
-     * Safely invokes the configured hydrationComplete callback, if any.
-     */
-    private static notifyHydrationComplete(): void {
-        const callback = HydratableElementController.lifecycleCallbacks.hydrationComplete;
-
-        if (callback) {
-            try {
-                callback();
-            } catch {
-                // A lifecycle callback must never prevent post-hydration cleanup.
-            }
-        }
-    }
-
     /**
      * Unregisters the hydration observer when the element is disconnected.
      */
diff --git a/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.elementdidhydrate.md b/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.elementdidhydrate.md
index 17ac8049802..c52ed5bafb8 100644
--- a/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.elementdidhydrate.md
+++ b/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.elementdidhydrate.md
@@ -15,7 +15,7 @@ navigationOptions:
 
 ## HydrationControllerCallbacks.elementDidHydrate() method
 
-Called after hydration has finished
+Called after an individual element's hydration has finished
 
 **Signature:**
 
diff --git a/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.elementwillhydrate.md b/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.elementwillhydrate.md
index ac4fe89d424..95a284416bd 100644
--- a/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.elementwillhydrate.md
+++ b/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.elementwillhydrate.md
@@ -15,7 +15,7 @@ navigationOptions:
 
 ## HydrationControllerCallbacks.elementWillHydrate() method
 
-Called before hydration has started
+Called before an individual element's hydration begins
 
 **Signature:**
 
diff --git a/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.hydrationstarted.md b/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.hydrationstarted.md
new file mode 100644
index 00000000000..f80b9f82b1a
--- /dev/null
+++ b/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.hydrationstarted.md
@@ -0,0 +1,27 @@
+---
+id: "fast-element.hydrationcontrollercallbacks.hydrationstarted"
+title: "HydrationControllerCallbacks.hydrationStarted() method"
+layout: 2x-api
+eleventyNavigation:
+  key: "api2xfast-element.hydrationcontrollercallbacks.hydrationstarted"
+  parent: "api2xfast-element"
+  title: "HydrationControllerCallbacks.hydrationStarted() method"
+navigationOptions:
+  activeKey: "api2xfast-element.hydrationcontrollercallbacks.hydrationstarted"
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[@microsoft/fast-element](../fast-element/index.html) &gt; [HydrationControllerCallbacks](../fast-element.hydrationcontrollercallbacks/index.html) &gt; [hydrationStarted](../fast-element.hydrationcontrollercallbacks.hydrationstarted/index.html)
+
+## HydrationControllerCallbacks.hydrationStarted() method
+
+Called once when the first element enters the hydration pipeline. This is the earliest point at which we know a component has been async-defined with `defer-and-hydrate`<!-- -->, a template is pending via `<f-template>`<!-- -->, and the element has `needs-hydration`<!-- -->.
+
+**Signature:**
+
+```typescript
+hydrationStarted?(): void;
+```
+**Returns:**
+
+void
diff --git a/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.md b/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.md
index 87416ef4a76..4755712e88f 100644
--- a/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.md
+++ b/sites/website/src/docs/2.x/api/fast-element.hydrationcontrollercallbacks.md
@@ -43,7 +43,7 @@ Description
 
 </td><td>
 
-_(Optional)_ Called after hydration has finished
+_(Optional)_ Called after an individual element's hydration has finished
 
 
 </td></tr>
@@ -54,7 +54,7 @@ _(Optional)_ Called after hydration has finished
 
 </td><td>
 
-_(Optional)_ Called before hydration has started
+_(Optional)_ Called before an individual element's hydration begins
 
 
 </td></tr>
@@ -68,5 +68,16 @@ _(Optional)_ Called before hydration has started
 _(Optional)_ Called after all elements have completed hydration
 
 
+</td></tr>
+<tr><td>
+
+[hydrationStarted()?](../fast-element.hydrationcontrollercallbacks.hydrationstarted/)
+
+
+</td><td>
+
+_(Optional)_ Called once when the first element enters the hydration pipeline. This is the earliest point at which we know a component has been async-defined with `defer-and-hydrate`<!-- -->, a template is pending via `<f-template>`<!-- -->, and the element has `needs-hydration`<!-- -->.
+
+
 </td></tr>
 </tbody></table>

From c466ce4d983a0faa671c6ad7db321ffba938cf07 Mon Sep 17 00:00:00 2001
From: John Kreitlow <863023+radium-v@users.noreply.github.com>
Date: Fri, 13 Feb 2026 15:55:43 -0800
Subject: [PATCH 3/5] test(performance-metrics): enhance performance tracking
 and add hydration metrics

---
 .../performance-metrics/fast-card.css         |   4 +
 .../fixtures/performance-metrics/index.html   | 210 +++++++++++++++-
 .../test/fixtures/performance-metrics/main.ts |  57 ++++-
 .../performance-metrics.spec.ts               | 229 +++++++++++++++++-
 packages/fast-html/test/index.html            |   1 +
 5 files changed, 474 insertions(+), 27 deletions(-)

diff --git a/packages/fast-html/test/fixtures/performance-metrics/fast-card.css b/packages/fast-html/test/fixtures/performance-metrics/fast-card.css
index b010b61ae08..8215ab5168e 100644
--- a/packages/fast-html/test/fixtures/performance-metrics/fast-card.css
+++ b/packages/fast-html/test/fixtures/performance-metrics/fast-card.css
@@ -3,4 +3,8 @@
     width: 200px;
     height: 200px;
     border: 1px solid #ccc;
+
+    dd {
+        display: inline-block;
+    }
 }
diff --git a/packages/fast-html/test/fixtures/performance-metrics/index.html b/packages/fast-html/test/fixtures/performance-metrics/index.html
index 9086294f970..a8ada05573a 100644
--- a/packages/fast-html/test/fixtures/performance-metrics/index.html
+++ b/packages/fast-html/test/fixtures/performance-metrics/index.html
@@ -3,9 +3,10 @@
     <head>
         <meta charset="utf-8" />
         <title>Performance Metrics Test</title>
+        <link rel="preload" as="style" href="./fast-card.css" />
     </head>
     <body>
-        <fast-card defer-delay="0">
+        <fast-card needs-hydration defer-hydration defer-delay="0">
             <template shadowrootmode="open">
                 <link rel="stylesheet" href="./fast-card.css" />
                 <dl>
@@ -20,12 +21,205 @@
                 </dl>
             </template>
         </fast-card>
-        <fast-card defer-delay="100">
+
+        <fast-card needs-hydration defer-hydration defer-delay="0">
+            <template shadowrootmode="open">
+                <link rel="stylesheet" href="./fast-card.css" />
+                <dl>
+                    <dt>Configured Delay</dt>
+                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->0ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
+                    <dt>Element Will Hydrate</dt>
+                    <dd><!--fe-b$$start$$1$$willhydrate$$fe-b-->0ms<!--fe-b$$end$$1$$willhydrate$$fe-b--></dd>
+                    <dt>Element Did Hydrate</dt>
+                    <dd><!--fe-b$$start$$2$$didhydrate$$fe-b-->0ms<!--fe-b$$end$$2$$didhydrate$$fe-b--></dd>
+                    <dt>Element Hydration Duration</dt>
+                    <dd><!--fe-b$$start$$3$$hydrationduration$$fe-b-->0ms<!--fe-b$$end$$3$$hydrationduration$$fe-b--></dd>
+                </dl>
+            </template>
+        </fast-card>
+
+        <fast-card needs-hydration defer-hydration defer-delay="0">
+            <template shadowrootmode="open">
+                <link rel="stylesheet" href="./fast-card.css" />
+                <dl>
+                    <dt>Configured Delay</dt>
+                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->0ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
+                    <dt>Element Will Hydrate</dt>
+                    <dd><!--fe-b$$start$$1$$willhydrate$$fe-b-->0ms<!--fe-b$$end$$1$$willhydrate$$fe-b--></dd>
+                    <dt>Element Did Hydrate</dt>
+                    <dd><!--fe-b$$start$$2$$didhydrate$$fe-b-->0ms<!--fe-b$$end$$2$$didhydrate$$fe-b--></dd>
+                    <dt>Element Hydration Duration</dt>
+                    <dd><!--fe-b$$start$$3$$hydrationduration$$fe-b-->0ms<!--fe-b$$end$$3$$hydrationduration$$fe-b--></dd>
+                </dl>
+            </template>
+        </fast-card>
+
+        <fast-card needs-hydration defer-hydration defer-delay="0">
+            <template shadowrootmode="open">
+                <link rel="stylesheet" href="./fast-card.css" />
+                <dl>
+                    <dt>Configured Delay</dt>
+                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->0ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
+                    <dt>Element Will Hydrate</dt>
+                    <dd><!--fe-b$$start$$1$$willhydrate$$fe-b-->0ms<!--fe-b$$end$$1$$willhydrate$$fe-b--></dd>
+                    <dt>Element Did Hydrate</dt>
+                    <dd><!--fe-b$$start$$2$$didhydrate$$fe-b-->0ms<!--fe-b$$end$$2$$didhydrate$$fe-b--></dd>
+                    <dt>Element Hydration Duration</dt>
+                    <dd><!--fe-b$$start$$3$$hydrationduration$$fe-b-->0ms<!--fe-b$$end$$3$$hydrationduration$$fe-b--></dd>
+                </dl>
+            </template>
+        </fast-card>
+
+        <fast-card needs-hydration defer-hydration defer-delay="0">
+            <template shadowrootmode="open">
+                <link rel="stylesheet" href="./fast-card.css" />
+                <dl>
+                    <dt>Configured Delay</dt>
+                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->0ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
+                    <dt>Element Will Hydrate</dt>
+                    <dd><!--fe-b$$start$$1$$willhydrate$$fe-b-->0ms<!--fe-b$$end$$1$$willhydrate$$fe-b--></dd>
+                    <dt>Element Did Hydrate</dt>
+                    <dd><!--fe-b$$start$$2$$didhydrate$$fe-b-->0ms<!--fe-b$$end$$2$$didhydrate$$fe-b--></dd>
+                    <dt>Element Hydration Duration</dt>
+                    <dd><!--fe-b$$start$$3$$hydrationduration$$fe-b-->0ms<!--fe-b$$end$$3$$hydrationduration$$fe-b--></dd>
+                </dl>
+            </template>
+        </fast-card>
+
+        <fast-card needs-hydration defer-hydration defer-delay="150">
+            <template shadowrootmode="open">
+                <link rel="stylesheet" href="./fast-card.css" />
+                <dl>
+                    <dt>Configured Delay</dt>
+                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->150ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
+                    <dt>Element Will Hydrate</dt>
+                    <dd><!--fe-b$$start$$1$$willhydrate$$fe-b-->0ms<!--fe-b$$end$$1$$willhydrate$$fe-b--></dd>
+                    <dt>Element Did Hydrate</dt>
+                    <dd><!--fe-b$$start$$2$$didhydrate$$fe-b-->0ms<!--fe-b$$end$$2$$didhydrate$$fe-b--></dd>
+                    <dt>Element Hydration Duration</dt>
+                    <dd><!--fe-b$$start$$3$$hydrationduration$$fe-b-->0ms<!--fe-b$$end$$3$$hydrationduration$$fe-b--></dd>
+                </dl>
+            </template>
+        </fast-card>
+
+        <fast-card needs-hydration defer-hydration defer-delay="150">
+            <template shadowrootmode="open">
+                <link rel="stylesheet" href="./fast-card.css" />
+                <dl>
+                    <dt>Configured Delay</dt>
+                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->150ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
+                    <dt>Element Will Hydrate</dt>
+                    <dd><!--fe-b$$start$$1$$willhydrate$$fe-b-->0ms<!--fe-b$$end$$1$$willhydrate$$fe-b--></dd>
+                    <dt>Element Did Hydrate</dt>
+                    <dd><!--fe-b$$start$$2$$didhydrate$$fe-b-->0ms<!--fe-b$$end$$2$$didhydrate$$fe-b--></dd>
+                    <dt>Element Hydration Duration</dt>
+                    <dd><!--fe-b$$start$$3$$hydrationduration$$fe-b-->0ms<!--fe-b$$end$$3$$hydrationduration$$fe-b--></dd>
+                </dl>
+            </template>
+        </fast-card>
+
+        <fast-card needs-hydration defer-hydration defer-delay="150">
+            <template shadowrootmode="open">
+                <link rel="stylesheet" href="./fast-card.css" />
+                <dl>
+                    <dt>Configured Delay</dt>
+                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->150ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
+                    <dt>Element Will Hydrate</dt>
+                    <dd><!--fe-b$$start$$1$$willhydrate$$fe-b-->0ms<!--fe-b$$end$$1$$willhydrate$$fe-b--></dd>
+                    <dt>Element Did Hydrate</dt>
+                    <dd><!--fe-b$$start$$2$$didhydrate$$fe-b-->0ms<!--fe-b$$end$$2$$didhydrate$$fe-b--></dd>
+                    <dt>Element Hydration Duration</dt>
+                    <dd><!--fe-b$$start$$3$$hydrationduration$$fe-b-->0ms<!--fe-b$$end$$3$$hydrationduration$$fe-b--></dd>
+                </dl>
+            </template>
+        </fast-card>
+
+        <fast-card needs-hydration defer-hydration defer-delay="150">
+            <template shadowrootmode="open">
+                <link rel="stylesheet" href="./fast-card.css" />
+                <dl>
+                    <dt>Configured Delay</dt>
+                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->150ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
+                    <dt>Element Will Hydrate</dt>
+                    <dd><!--fe-b$$start$$1$$willhydrate$$fe-b-->0ms<!--fe-b$$end$$1$$willhydrate$$fe-b--></dd>
+                    <dt>Element Did Hydrate</dt>
+                    <dd><!--fe-b$$start$$2$$didhydrate$$fe-b-->0ms<!--fe-b$$end$$2$$didhydrate$$fe-b--></dd>
+                    <dt>Element Hydration Duration</dt>
+                    <dd><!--fe-b$$start$$3$$hydrationduration$$fe-b-->0ms<!--fe-b$$end$$3$$hydrationduration$$fe-b--></dd>
+                </dl>
+            </template>
+        </fast-card>
+
+        <fast-card needs-hydration defer-hydration defer-delay="300">
+            <template shadowrootmode="open">
+                <link rel="stylesheet" href="./fast-card.css" />
+                <dl>
+                    <dt>Configured Delay</dt>
+                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->300ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
+                    <dt>Element Will Hydrate</dt>
+                    <dd><!--fe-b$$start$$1$$willhydrate$$fe-b-->0ms<!--fe-b$$end$$1$$willhydrate$$fe-b--></dd>
+                    <dt>Element Did Hydrate</dt>
+                    <dd><!--fe-b$$start$$2$$didhydrate$$fe-b-->0ms<!--fe-b$$end$$2$$didhydrate$$fe-b--></dd>
+                    <dt>Element Hydration Duration</dt>
+                    <dd><!--fe-b$$start$$3$$hydrationduration$$fe-b-->0ms<!--fe-b$$end$$3$$hydrationduration$$fe-b--></dd>
+                </dl>
+            </template>
+        </fast-card>
+
+        <fast-card needs-hydration defer-hydration defer-delay="300">
             <template shadowrootmode="open">
                 <link rel="stylesheet" href="./fast-card.css" />
                 <dl>
                     <dt>Configured Delay</dt>
-                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->100ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
+                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->300ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
+                    <dt>Element Will Hydrate</dt>
+                    <dd><!--fe-b$$start$$1$$willhydrate$$fe-b-->0ms<!--fe-b$$end$$1$$willhydrate$$fe-b--></dd>
+                    <dt>Element Did Hydrate</dt>
+                    <dd><!--fe-b$$start$$2$$didhydrate$$fe-b-->0ms<!--fe-b$$end$$2$$didhydrate$$fe-b--></dd>
+                    <dt>Element Hydration Duration</dt>
+                    <dd><!--fe-b$$start$$3$$hydrationduration$$fe-b-->0ms<!--fe-b$$end$$3$$hydrationduration$$fe-b--></dd>
+                </dl>
+            </template>
+        </fast-card>
+
+        <fast-card needs-hydration defer-hydration defer-delay="300">
+            <template shadowrootmode="open">
+                <link rel="stylesheet" href="./fast-card.css" />
+                <dl>
+                    <dt>Configured Delay</dt>
+                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->300ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
+                    <dt>Element Will Hydrate</dt>
+                    <dd><!--fe-b$$start$$1$$willhydrate$$fe-b-->0ms<!--fe-b$$end$$1$$willhydrate$$fe-b--></dd>
+                    <dt>Element Did Hydrate</dt>
+                    <dd><!--fe-b$$start$$2$$didhydrate$$fe-b-->0ms<!--fe-b$$end$$2$$didhydrate$$fe-b--></dd>
+                    <dt>Element Hydration Duration</dt>
+                    <dd><!--fe-b$$start$$3$$hydrationduration$$fe-b-->0ms<!--fe-b$$end$$3$$hydrationduration$$fe-b--></dd>
+                </dl>
+            </template>
+        </fast-card>
+
+        <fast-card needs-hydration defer-hydration defer-delay="300">
+            <template shadowrootmode="open">
+                <link rel="stylesheet" href="./fast-card.css" />
+                <dl>
+                    <dt>Configured Delay</dt>
+                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->300ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
+                    <dt>Element Will Hydrate</dt>
+                    <dd><!--fe-b$$start$$1$$willhydrate$$fe-b-->0ms<!--fe-b$$end$$1$$willhydrate$$fe-b--></dd>
+                    <dt>Element Did Hydrate</dt>
+                    <dd><!--fe-b$$start$$2$$didhydrate$$fe-b-->0ms<!--fe-b$$end$$2$$didhydrate$$fe-b--></dd>
+                    <dt>Element Hydration Duration</dt>
+                    <dd><!--fe-b$$start$$3$$hydrationduration$$fe-b-->0ms<!--fe-b$$end$$3$$hydrationduration$$fe-b--></dd>
+                </dl>
+            </template>
+        </fast-card>
+
+        <fast-card needs-hydration defer-hydration defer-delay="300">
+            <template shadowrootmode="open">
+                <link rel="stylesheet" href="./fast-card.css" />
+                <dl>
+                    <dt>Configured Delay</dt>
+                    <dd><!--fe-b$$start$$0$$displayDelay$$fe-b-->300ms<!--fe-b$$end$$0$$displayDelay$$fe-b--></dd>
                     <dt>Element Will Hydrate</dt>
                     <dd><!--fe-b$$start$$1$$willhydrate$$fe-b-->0ms<!--fe-b$$end$$1$$willhydrate$$fe-b--></dd>
                     <dt>Element Did Hydrate</dt>
@@ -40,14 +234,14 @@
             <template>
                 <link rel="stylesheet" href="./fast-card.css" />
                 <dl>
-                    <dt>Configured Defer Delay</dt>
-                    <dd id="defer-delay">{{displayDelay}}ms</dd>
+                    <dt>Configured Delay</dt>
+                    <dd>{{displayDelay}}</dd>
                     <dt>Element Will Hydrate</dt>
-                    <dd id="hydration-started">{{willHydrate}}</dd>
+                    <dd>{{willHydrate}}</dd>
                     <dt>Element Did Hydrate</dt>
-                    <dd id="hydration-completed">{{didHydrate}}</dd>
+                    <dd>{{didHydrate}}</dd>
                     <dt>Element Hydration Duration</dt>
-                    <dd id="hydration-duration">{{hydrationDuration}}</dd>
+                    <dd>{{hydrationDuration}}</dd>
                 </dl>
             </template>
         </f-template>
diff --git a/packages/fast-html/test/fixtures/performance-metrics/main.ts b/packages/fast-html/test/fixtures/performance-metrics/main.ts
index c3a5760a461..f8702c800d3 100644
--- a/packages/fast-html/test/fixtures/performance-metrics/main.ts
+++ b/packages/fast-html/test/fixtures/performance-metrics/main.ts
@@ -1,6 +1,10 @@
 import { attr, FASTElement, observable, volatile } from "@microsoft/fast-element";
 import { RenderableFASTElement, TemplateElement } from "@microsoft/fast-html";
 
+let hydrationMarks: WeakMap<HTMLElement, string>;
+let markId = 0;
+let markSequence = 0;
+
 class FastCard extends RenderableFASTElement(FASTElement) {
     @attr({ attribute: "defer-delay" })
     deferDelay!: number;
@@ -22,8 +26,28 @@ class FastCard extends RenderableFASTElement(FASTElement) {
     @observable
     hydrationDuration: string = "";
 
+    // Set inside prepare(), not as a field initializer, because prepare()
+    // runs during super() before field initializers execute.
+    private uniqueId!: string;
+
     async prepare() {
-        await new Promise(resolve => setTimeout(resolve, this.deferDelay));
+        this.uniqueId = Math.random().toString(16).slice(2);
+        const markName = `element-prepare-start:${this.localName}:${this.uniqueId}`;
+        performance.mark(markName);
+
+        // Read from the DOM attribute directly because prepare() runs during
+        // super() before boundObservables are applied, so this.deferDelay is
+        // still undefined at this point.
+        const delay = Number(this.getAttribute("defer-delay")) || 0;
+
+        if (delay > 0) {
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+
+        performance.measure(`element-prepared:${this.localName}:${this.uniqueId}`, {
+            start: markName,
+            detail: { delay },
+        });
     }
 }
 
@@ -32,15 +56,32 @@ FastCard.defineAsync({
     templateOptions: "defer-and-hydrate",
 });
 
-let hydrationMarks: WeakMap<HTMLElement, string>;
-let markId = 0;
-
 TemplateElement.config({
+    hydrationStarted(): void {
+        hydrationMarks = new WeakMap<HTMLElement, string>();
+        performance.mark("hydration:started", { detail: { sequence: markSequence++ } });
+    },
+
     templateWillUpdate(name: string) {
-        if (!hydrationMarks) {
-            hydrationMarks = new WeakMap<HTMLElement, string>();
-            performance.mark("hydration:started");
-        }
+        performance.mark(`template-update:${name}:start`, {
+            detail: { sequence: markSequence++ },
+        });
+    },
+
+    templateDidUpdate(name) {
+        performance.measure(`template-update:${name}`, `template-update:${name}:start`);
+    },
+
+    elementDidDefine(name) {
+        performance.mark(`element-define:${name}`, {
+            detail: { sequence: markSequence++ },
+        });
+    },
+
+    elementDidRegister(name) {
+        performance.mark(`element-register:${name}`, {
+            detail: { sequence: markSequence++ },
+        });
     },
 
     elementWillHydrate(source: HTMLElement): void {
diff --git a/packages/fast-html/test/fixtures/performance-metrics/performance-metrics.spec.ts b/packages/fast-html/test/fixtures/performance-metrics/performance-metrics.spec.ts
index c63916a7da6..3ef7960a7f0 100644
--- a/packages/fast-html/test/fixtures/performance-metrics/performance-metrics.spec.ts
+++ b/packages/fast-html/test/fixtures/performance-metrics/performance-metrics.spec.ts
@@ -16,9 +16,9 @@ test.describe("Performance Metrics via Lifecycle Callbacks", () => {
         );
 
         const cards = page.locator("fast-card");
-        await expect(cards).toHaveCount(2);
+        await expect(cards).toHaveCount(14);
 
-        expect(measures).toHaveLength(2);
+        expect(measures).toHaveLength(14);
     });
 
     test("should create a single hydration:complete measure", async ({ page }) => {
@@ -31,20 +31,227 @@ test.describe("Performance Metrics via Lifecycle Callbacks", () => {
         expect(measure).toHaveLength(1);
     });
 
-    test("the hydration:complete measure should have a duration greater than or equal to the longest hydration:fast-card measure", async ({ page }) => {
-        const completeMeasure = await page.evaluate(() =>
-            performance.getEntriesByType("measure").find(m => m.name === "hydration:complete")
+    test("element-register should precede template-update", async ({ page }) => {
+        const { regTime, tmplTime, regSeq, tmplSeq } = await page.evaluate(() => {
+            const entries = performance.getEntriesByType("mark") as PerformanceMark[];
+            const reg = entries.find(m => m.name === "element-register:fast-card");
+            const tmpl = entries.find(m =>
+                m.name === "template-update:fast-card:start"
+            );
+            return {
+                regTime: reg?.startTime,
+                tmplTime: tmpl?.startTime,
+                regSeq: (reg?.detail as any)?.sequence as number | undefined,
+                tmplSeq: (tmpl?.detail as any)?.sequence as number | undefined,
+            };
+        });
+
+        expect(regTime).toBeDefined();
+        expect(tmplTime).toBeDefined();
+        expect(regSeq).toBeDefined();
+        expect(tmplSeq).toBeDefined();
+
+        // Timestamps may collide due to timer coarsening; use sequence as
+        // tiebreaker to verify ordering.
+        expect(regTime).toBeLessThanOrEqual(tmplTime!);
+        expect(regSeq).toBeLessThan(tmplSeq!);
+    });
+
+    test("template-update should precede element-define", async ({ page }) => {
+        const { templateEnd, defineTime, templateEndSeq, defineSeq } =
+            await page.evaluate(() => {
+                const marks =
+                    performance.getEntriesByType("mark") as PerformanceMark[];
+                const measures = performance.getEntriesByType("measure");
+                const tmpl = measures.find(
+                    m => m.name === "template-update:fast-card"
+                );
+                const def = marks.find(
+                    m => m.name === "element-define:fast-card"
+                );
+                // template-update:start fires before template-update (the
+                // measure), and element-define fires after.  Compare the
+                // start-mark sequence against the define-mark sequence.
+                const startMark = marks.find(
+                    m => m.name === "template-update:fast-card:start"
+                );
+                return {
+                    templateEnd: tmpl
+                        ? tmpl.startTime + tmpl.duration
+                        : undefined,
+                    defineTime: def?.startTime,
+                    templateEndSeq: (startMark?.detail as any)
+                        ?.sequence as number | undefined,
+                    defineSeq: (def?.detail as any)
+                        ?.sequence as number | undefined,
+                };
+            });
+
+        expect(templateEnd).toBeDefined();
+        expect(defineTime).toBeDefined();
+        expect(templateEnd).toBeLessThanOrEqual(defineTime!);
+
+        expect(templateEndSeq).toBeDefined();
+        expect(defineSeq).toBeDefined();
+        expect(templateEndSeq).toBeLessThan(defineSeq!);
+    });
+
+    test("element-define should precede hydration:started", async ({ page }) => {
+        const { defineTime, hsTime, defineSeq, hsSeq } = await page.evaluate(
+            () => {
+                const marks =
+                    performance.getEntriesByType("mark") as PerformanceMark[];
+                const def = marks.find(
+                    m => m.name === "element-define:fast-card"
+                );
+                const hs = marks.find(m => m.name === "hydration:started");
+                return {
+                    defineTime: def?.startTime,
+                    hsTime: hs?.startTime,
+                    defineSeq: (def?.detail as any)
+                        ?.sequence as number | undefined,
+                    hsSeq: (hs?.detail as any)
+                        ?.sequence as number | undefined,
+                };
+            }
         );
 
-        const cardMeasures = await page.evaluate(() =>
+        expect(defineTime).toBeDefined();
+        expect(hsTime).toBeDefined();
+        expect(defineTime).toBeLessThanOrEqual(hsTime!);
+
+        expect(defineSeq).toBeDefined();
+        expect(hsSeq).toBeDefined();
+        expect(defineSeq).toBeLessThan(hsSeq!);
+    });
+
+    test("hydration:started should precede all individual element hydration measures", async ({
+        page,
+    }) => {
+        const { hydrationStarted, firstCardHydration } = await page.evaluate(() => {
+            const marks = performance.getEntriesByType("mark");
+            const measures = performance.getEntriesByType("measure");
+            const hs = marks.find(m => m.name === "hydration:started");
+            const cardMeasures = measures.filter(
+                m => m.name === "hydration:fast-card"
+            );
+            const earliest = Math.min(...cardMeasures.map(m => m.startTime));
+            return { hydrationStarted: hs?.startTime, firstCardHydration: earliest };
+        });
+
+        expect(hydrationStarted).toBeDefined();
+        expect(hydrationStarted).toBeLessThanOrEqual(firstCardHydration);
+    });
+
+    test("all individual element hydrations should complete before hydration:complete ends", async ({
+        page,
+    }) => {
+        const { lastCardEnd, completeEnd } = await page.evaluate(() => {
+            const measures = performance.getEntriesByType("measure");
+            const cardMeasures = measures.filter(
+                m => m.name === "hydration:fast-card"
+            );
+            const complete = measures.find(m => m.name === "hydration:complete");
+            return {
+                lastCardEnd: Math.max(
+                    ...cardMeasures.map(m => m.startTime + m.duration)
+                ),
+                completeEnd: complete
+                    ? complete.startTime + complete.duration
+                    : undefined,
+            };
+        });
+
+        expect(completeEnd).toBeDefined();
+        expect(completeEnd).toBeGreaterThanOrEqual(lastCardEnd);
+    });
+
+    test("should create an element-prepared measure for each element", async ({
+        page,
+    }) => {
+        const count = await page.evaluate(() =>
             performance
                 .getEntriesByType("measure")
-                .filter(m => m.name === "hydration:fast-card")
+                .filter(m => m.name.startsWith("element-prepared:fast-card:")).length
         );
 
-        expect(cardMeasures).toHaveLength(2);
-        expect(completeMeasure!.duration).toBeGreaterThanOrEqual(
-            Math.max(...cardMeasures.map(m => m.duration))
-        );
+        expect(count).toBe(14);
+    });
+
+    test("at least one element-prepared measure should complete before hydration:started", async ({
+        page,
+    }) => {
+        const { earliestPreparedEnd, hydrationStarted } = await page.evaluate(() => {
+            const marks = performance.getEntriesByType("mark");
+            const measures = performance.getEntriesByType("measure");
+            const prepared = measures.filter(m =>
+                m.name.startsWith("element-prepared:fast-card:")
+            );
+            const hs = marks.find(m => m.name === "hydration:started");
+            return {
+                earliestPreparedEnd: Math.min(
+                    ...prepared.map(m => m.startTime + m.duration)
+                ),
+                hydrationStarted: hs?.startTime,
+            };
+        });
+
+        expect(hydrationStarted).toBeDefined();
+        expect(earliestPreparedEnd).toBeLessThanOrEqual(hydrationStarted!);
+    });
+
+    test("elements with defer-delay should have longer prepare durations than those without", async ({
+        page,
+    }) => {
+        const { zeroDurations, delayedDurations } = await page.evaluate(() => {
+            const measures = performance.getEntriesByType(
+                "measure"
+            ) as PerformanceMeasure[];
+            const prepared = measures.filter(m =>
+                m.name.startsWith("element-prepared:fast-card:")
+            );
+
+            const zero: number[] = [];
+            const delayed: number[] = [];
+
+            for (const m of prepared) {
+                const delay = (m.detail as any)?.delay ?? 0;
+                if (delay === 0) {
+                    zero.push(m.duration);
+                } else {
+                    delayed.push(m.duration);
+                }
+            }
+
+            return { zeroDurations: zero, delayedDurations: delayed };
+        });
+
+        const maxZero = Math.max(...zeroDurations);
+        const minDelayed = Math.min(...delayedDurations);
+
+        // Zero-delay elements should be substantially faster than delayed ones.
+        expect(maxZero).toBeLessThan(minDelayed);
+    });
+
+    test("every hydrated element should have willHydrate and didHydrate values set", async ({
+        page,
+    }) => {
+        const cards = page.locator("fast-card");
+        const count = await cards.count();
+
+        expect(count).toBe(14);
+
+        for (let i = 0; i < count; i++) {
+            const card = cards.nth(i);
+            const willHydrate = await card.evaluate(
+                (el: any) => el.willHydrate
+            );
+            const didHydrate = await card.evaluate(
+                (el: any) => el.didHydrate
+            );
+
+            expect(willHydrate, `card ${i} willHydrate`).toBeTruthy();
+            expect(didHydrate, `card ${i} didHydrate`).toBeTruthy();
+        }
     });
 });
diff --git a/packages/fast-html/test/index.html b/packages/fast-html/test/index.html
index 7c0cc135b39..4cab47e5c1c 100644
--- a/packages/fast-html/test/index.html
+++ b/packages/fast-html/test/index.html
@@ -18,6 +18,7 @@ <h1>FAST HTML Test Suite</h1>
             <li><a href="/fixtures/lifecycle-callbacks/">lifecycle-callbacks</a></li>
             <li><a href="/fixtures/nested-elements/">nested-elements</a></li>
             <li><a href="/fixtures/observer-map/">observer-map</a></li>
+            <li><a href="/fixtures/performance-metrics/">performance-metrics</a></li>
             <li><a href="/fixtures/ref/">ref</a></li>
             <li><a href="/fixtures/repeat/">repeat</a></li>
             <li><a href="/fixtures/slotted/">slotted</a></li>

From 68f1862bc8b6aa03039d3c50f4a9b9ee0dbfe182 Mon Sep 17 00:00:00 2001
From: John Kreitlow <863023+radium-v@users.noreply.github.com>
Date: Fri, 13 Feb 2026 15:56:45 -0800
Subject: [PATCH 4/5] Change files

---
 ...-fast-element-70d07072-14fe-484f-817c-1ca791c5f9ba.json | 7 +++++++
 ...oft-fast-html-1e35899c-c956-4da3-8da6-b6400d330580.json | 7 +++++++
 2 files changed, 14 insertions(+)
 create mode 100644 change/@microsoft-fast-element-70d07072-14fe-484f-817c-1ca791c5f9ba.json
 create mode 100644 change/@microsoft-fast-html-1e35899c-c956-4da3-8da6-b6400d330580.json

diff --git a/change/@microsoft-fast-element-70d07072-14fe-484f-817c-1ca791c5f9ba.json b/change/@microsoft-fast-element-70d07072-14fe-484f-817c-1ca791c5f9ba.json
new file mode 100644
index 00000000000..1449005f7cd
--- /dev/null
+++ b/change/@microsoft-fast-element-70d07072-14fe-484f-817c-1ca791c5f9ba.json
@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat(hydration): add hydrationStarted callback and update documentation",
+  "packageName": "@microsoft/fast-element",
+  "email": "863023+radium-v@users.noreply.github.com",
+  "dependentChangeType": "none"
+}
diff --git a/change/@microsoft-fast-html-1e35899c-c956-4da3-8da6-b6400d330580.json b/change/@microsoft-fast-html-1e35899c-c956-4da3-8da6-b6400d330580.json
new file mode 100644
index 00000000000..1bae0b196d2
--- /dev/null
+++ b/change/@microsoft-fast-html-1e35899c-c956-4da3-8da6-b6400d330580.json
@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "test(performance-metrics): enhance performance tracking and add hydration metrics",
+  "packageName": "@microsoft/fast-html",
+  "email": "863023+radium-v@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

From ff68c0ecddea06347d92969d8b140356d1747de4 Mon Sep 17 00:00:00 2001
From: John Kreitlow <863023+radium-v@users.noreply.github.com>
Date: Fri, 13 Feb 2026 16:37:43 -0800
Subject: [PATCH 5/5] fix(ci): install Playwright with dependencies in CI
 workflow

---
 .github/workflows/ci-validate-platforms.yml | 2 +-
 .github/workflows/ci-validate-pr.yml        | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci-validate-platforms.yml b/.github/workflows/ci-validate-platforms.yml
index 73aa4feddaf..ccc4249c754 100644
--- a/.github/workflows/ci-validate-platforms.yml
+++ b/.github/workflows/ci-validate-platforms.yml
@@ -62,7 +62,7 @@ jobs:
 
       - name: Install playwright dependencies and browsers
         run: |
-          npx playwright install
+          npx playwright install --with-deps
 
       - name: Run tests in all Packages
         run: npm run test
diff --git a/.github/workflows/ci-validate-pr.yml b/.github/workflows/ci-validate-pr.yml
index 4f061f8ab6d..620a0254649 100644
--- a/.github/workflows/ci-validate-pr.yml
+++ b/.github/workflows/ci-validate-pr.yml
@@ -49,7 +49,7 @@ jobs:
 
     - name: Install playwright dependencies and browsers
       run: |
-        npx playwright install
+        npx playwright install --with-deps
 
     - name: Testing unit tests
       run: npm run test