feat: add isHydrated promise and fix isPrerendered semantics

Split isPrerendered into two separate promises:
- isPrerendered: resolves true when DSD shadow root existed at connect
- isHydrated: resolves true only when hydration actually ran

Fix templates.html formatting that broke declarative bindings.
Update DESIGN.md, README.md, DECLARATIVE_RENDERING_LIFECYCLE.md,
migration guide, and lifecycle-callbacks docs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: janechu

packages/fast-element/DECLARATIVE_RENDERING_LIFECYCLE.md

@@ -96,10 +96,11 @@ Once the template is attached to the partial definition, the element completes i
 When custom elements are instantiated in the DOM, the following occurs:
 
 1. **Element Creation**: The platform creates instances of the custom element
-2. **Prerendered Content Detection**: `ElementController` detects the existing shadow root from SSR and sets `isPrerendered = true`
-3. **Concrete Template Ready**: Because `declarativeTemplate()` resolved during
+2. **Prerendered Content Detection**: `ElementController` detects the existing shadow root from SSR — `isPrerendered` resolves `true`
+3. **Hydration Check**: If `enableHydration()` was called and the template is hydratable, the element hydrates — `isHydrated` resolves `true`. Otherwise it falls back to client-side rendering.
+4. **Concrete Template Ready**: Because `declarativeTemplate()` resolved during
    definition, `connect()` starts with the final template already attached.
-4. **Hydration**: `ElementController` uses `template.hydrate()` to create a
+5. **Hydration**: `ElementController` uses `template.hydrate()` to create a
    `HydrationView` that maps existing DOM nodes to binding targets using `fe:b`
    / `fe:/b` markers
 

packages/fast-element/DESIGN.md

@@ -93,7 +93,7 @@ registry.
 - Extends `PropertyChangeNotifier` so the element itself participates in the observable system.
 - Holds the element's `FASTElementDefinition` (name, template, styles, observed attributes).
 - Manages a `Stages` state machine: `disconnected → connecting → connected → disconnecting → disconnected`.
-- Exposes `isPrerendered: Promise<boolean>` which resolves to `true` after prerendered content has been hydrated, or `false` when the component is client-side rendered. The `ViewController` interface also exposes `isPrerendered` as `Promise<boolean>` for custom directives. Attribute-skip logic during the hydration bind uses an internal `_skipAttrUpdates` flag that is never exposed as a public boolean.
+- Exposes `isPrerendered: Promise<boolean>` which resolves to `true` when the element had a declarative shadow root (DSD) at connect time, regardless of whether hydration ran. Exposes `isHydrated: Promise<boolean>` which resolves to `true` only when hydration actually ran successfully. The `ViewController` interface also exposes both `isPrerendered` and `isHydrated` as `Promise<boolean>` for custom directives. Attribute-skip logic during the hydration bind uses an internal `_skipAttrUpdates` flag that is never exposed as a public boolean.
 - On `connect()`: restores pre-upgrade observable values, calls `connectedCallback` on all `HostBehavior`s, renders the current template into the shadow root when one is available, and applies styles.
 - Rendering is split into two modular paths via `renderPrerendered()` and `renderClientSide()`:
   - **Prerendered**: `renderPrerendered()` is only reachable when hydration has been explicitly enabled via `enableHydration()`. It registers the element in the static hydration tracker, fires the definition's `elementWillHydrate` callback, swaps `onAttributeChangedCallback` to a no-op so the upgrade-time burst of callbacks is discarded, hydrates the existing DOM via `template.hydrate()`, fires `elementDidHydrate`, then restores the standard handler and removes the element from the tracker. The entire method is wrapped in `try/finally` to guarantee cleanup even if an error occurs during hydration. After this point, all future attribute changes flow through the real handler with zero overhead.
@@ -378,13 +378,13 @@ flowchart TD
 
     CONN[connectedCallback] --> STAGE[stage = connecting]
     STAGE --> PRERENDER{Existing shadow root\nfrom SSR/DSD?}
-    PRERENDER -->|yes| SETFLAG[isPrerendered = true]
-    PRERENDER -->|no| NORMAL[isPrerendered = false]
+    PRERENDER -->|yes| SETFLAG[isPrerendered = true\nisHydrated = pending]
+    PRERENDER -->|no| NORMAL[isPrerendered = false\nisHydrated = false]
     SETFLAG --> OBS[Restore pre-upgrade observable values]
     NORMAL --> OBS
     OBS --> BEHAV[Connect HostBehaviors]
     BEHAV --> RENDER{isPrerendered AND\ntemplate is hydratable?}
-    RENDER -->|yes| HYDRATE[template.hydrate → HydrationView\nmaps existing DOM to binding targets]
+    RENDER -->|yes| HYDRATE[template.hydrate → HydrationView\nmaps existing DOM to binding targets\nisHydrated = true]
     RENDER -->|no| CLONE[ViewTemplate.render → HTMLView.appendTo shadow root]
     HYDRATE --> STYLES[Apply ElementStyles to shadow root]
     CLONE --> STYLES

packages/fast-element/README.md

@@ -140,7 +140,12 @@ enableHydration({
 });
 ```
 
-When hydration is enabled and a FAST element connects with an existing shadow root (from server-side rendering or declarative shadow DOM), `ElementController` detects this and hydrates instead of re-rendering. The `isPrerendered` property on the controller is a `Promise<boolean>` that resolves to `true` after prerendered content has been hydrated, or `false` when the component is client-side rendered. This enables several optimizations:
+When hydration is enabled and a FAST element connects with an existing shadow root (from server-side rendering or declarative shadow DOM), `ElementController` detects this and hydrates instead of re-rendering. Two properties on the controller let you inspect the result:
+
+- **`isPrerendered: Promise<boolean>`** — resolves `true` when the element had a declarative shadow root (DSD) at connect time, regardless of whether hydration ran.
+- **`isHydrated: Promise<boolean>`** — resolves `true` only when hydration actually ran successfully.
+
+This enables several optimizations:
 
 - **Hydration instead of re-render**: The template uses `hydrate()` to map existing DOM nodes to binding targets rather than cloning new DOM.
 - **Declarative template resolution**: `declarativeTemplate()` waits for the
@@ -167,17 +172,19 @@ MyComponent.define({
 });
 ```
 
-Component authors can await the promise to know when hydration is complete:
+Component authors can await both promises to distinguish prerendered content from successful hydration:
 
 ```typescript
-this.$fastController.isPrerendered.then(prerendered => {
-    if (!prerendered) {
-        this.fetchData();
-    }
-});
+const controller = this.$fastController;
+const prerendered = await controller.isPrerendered;
+const hydrated = await controller.isHydrated;
+
+if (prerendered && !hydrated) {
+    // Had DSD but hydration wasn't enabled — client-side rendered
+}
 ```
 
-Custom directives can also await `controller.isPrerendered` (a `Promise<boolean>` on the `ViewController` interface) to determine whether the view's content was prerendered.
+Custom directives can also await `controller.isPrerendered` and `controller.isHydrated` (both `Promise<boolean>` on the `ViewController` interface) to determine how the view's content was rendered.
 
 ## Define Extensions
 

packages/fast-element/SIZES.md

@@ -4,8 +4,8 @@ Bundle sizes for `@microsoft/fast-element` exports.
 
 | Export | Minified | Gzip | Brotli |
 |--------|----------|------|--------|
-| CDN Rollup Bundle | 65.53 KB | 19.50 KB | 17.47 KB |
-| FASTElement | 25.15 KB | 7.86 KB | 7.11 KB |
+| CDN Rollup Bundle | 65.72 KB | 19.53 KB | 17.50 KB |
+| FASTElement | 25.31 KB | 7.88 KB | 7.13 KB |
 | Updates | 3.13 KB | 1.28 KB | 1.09 KB |
 | Observable | 7.65 KB | 2.79 KB | 2.51 KB |
 | observable | 7.68 KB | 2.81 KB | 2.53 KB |
@@ -16,5 +16,5 @@ Bundle sizes for `@microsoft/fast-element` exports.
 | slotted | 5.46 KB | 2.12 KB | 1.87 KB |
 | volatile | 7.74 KB | 2.83 KB | 2.54 KB |
 | when | 1.99 KB | 771 B | 637 B |
-| html | 26.82 KB | 8.78 KB | 7.88 KB |
-| repeat | 30.48 KB | 9.70 KB | 8.74 KB |
+| html | 26.86 KB | 8.79 KB | 7.89 KB |
+| repeat | 30.51 KB | 9.71 KB | 8.75 KB |

packages/fast-element/docs/api-report.api.md

@@ -276,6 +276,7 @@ export class ElementController<TElement extends HTMLElement = HTMLElement> exten
     protected hasExistingShadowRoot: boolean;
     get isBound(): boolean;
     get isConnected(): boolean;
+    readonly isHydrated: Promise<boolean>;
     readonly isPrerendered: Promise<boolean>;
     get mainStyles(): ElementStyles | null;
     set mainStyles(value: ElementStyles | null);
@@ -557,6 +558,7 @@ export class HTMLView<TSource = any, TParent = any> extends DefaultExecutionCont
     firstChild: Node;
     insertBefore(node: Node): void;
     isBound: boolean;
+    isHydrated: Promise<boolean>;
     isPrerendered: Promise<boolean>;
     lastChild: Node;
     // (undocumented)
@@ -1055,6 +1057,7 @@ export type ViewBehaviorTargets = {
 
 // @public
 export interface ViewController<TSource = any, TParent = any> extends ExpressionController<TSource, TParent> {
+    readonly isHydrated?: Promise<boolean>;
     readonly isPrerendered?: Promise<boolean>;
     // @internal
     readonly _skipAttrUpdates?: boolean;

packages/fast-element/src/components/element-controller.ts

@@ -100,26 +100,28 @@ export class ElementController<TElement extends HTMLElement = HTMLElement>
     private _resolvePrerendered!: (value: boolean) => void;
 
     /**
-     * A promise that resolves with `true` after prerendered content has
-     * been hydrated, or `false` immediately when the component is
-     * client-side rendered. Component authors can await this to know
-     * when the element is fully interactive:
-     *
-     * ```typescript
-     * connectedCallback() {
-     *     super.connectedCallback();
-     *     this.$fastController.isPrerendered.then(prerendered => {
-     *         if (!prerendered) {
-     *             this.fetchData();
-     *         }
-     *     });
-     * }
-     * ```
+     * Resolves the isHydrated promise.
+     */
+    private _resolveHydrated!: (value: boolean) => void;
+
+    /**
+     * Resolves `true` when the element had an existing shadow root
+     * (from SSR or declarative shadow DOM) at connect time, `false`
+     * otherwise.
      */
     public readonly isPrerendered: Promise<boolean> = new Promise<boolean>(resolve => {
         this._resolvePrerendered = resolve;
     });
 
+    /**
+     * Resolves `true` after prerendered content has been successfully
+     * hydrated, or `false` when the component is client-side rendered
+     * or hydration is not enabled.
+     */
+    public readonly isHydrated: Promise<boolean> = new Promise<boolean>(resolve => {
+        this._resolveHydrated = resolve;
+    });
+
     /**
      * The template used to render the component.
      */
@@ -761,11 +763,12 @@ export class ElementController<TElement extends HTMLElement = HTMLElement>
         }
 
         if (template) {
+            const hasPrerenderedContent =
+                this.hasExistingShadowRoot && this.needsInitialization;
             const tracker = ElementController.hydrationTracker;
             const didHydrate =
+                hasPrerenderedContent &&
                 tracker !== null &&
-                this.hasExistingShadowRoot &&
-                this.needsInitialization &&
                 isHydratable(template);
 
             if (didHydrate) {
@@ -774,9 +777,11 @@ export class ElementController<TElement extends HTMLElement = HTMLElement>
                 this.renderClientSide(template, element, host);
             }
 
-            this._resolvePrerendered(didHydrate);
+            this._resolvePrerendered(hasPrerenderedContent);
+            this._resolveHydrated(didHydrate);
         } else if (this.needsInitialization) {
             this._resolvePrerendered(false);
+            this._resolveHydrated(false);
         }
     }
 
@@ -819,6 +824,7 @@ export class ElementController<TElement extends HTMLElement = HTMLElement>
                 // DOM updates during bind, and set the public promise.
                 (this.view as any)._skipAttrUpdates = true;
                 (this.view as any).isPrerendered = Promise.resolve(true);
+                (this.view as any).isHydrated = Promise.resolve(true);
                 this.view!.bind(this.source);
                 (this.view as any)._skipAttrUpdates = false;
             } finally {

packages/fast-element/src/components/hydration.pw.spec.ts

@@ -30,15 +30,17 @@ test.describe("The prerendered content optimization", () => {
 
             return {
                 isPrerendered: await element.$fastController.isPrerendered,
+                isHydrated: await element.$fastController.isHydrated,
                 shadowContent: element.shadowRoot?.innerHTML ?? "",
             };
         });
 
         expect(result.isPrerendered).toBe(false);
+        expect(result.isHydrated).toBe(false);
         expect(result.shadowContent).toContain("hello");
     });
 
-    test("should set isPrerendered to false when DSD exists but hydration is not enabled", async ({
+    test("should detect DSD but not hydrate when hydration is not enabled", async ({
         page,
     }) => {
         await page.goto("/");
@@ -76,12 +78,15 @@ test.describe("The prerendered content optimization", () => {
             return {
                 hasShadowRootBefore,
                 isPrerendered: await element.$fastController.isPrerendered,
+                isHydrated: await element.$fastController.isHydrated,
             };
         });
 
         expect(result.hasShadowRootBefore).toBe(true);
-        // Without enableHydration(), prerendered content is not hydrated
-        expect(result.isPrerendered).toBe(false);
+        // DSD exists, so isPrerendered is true
+        expect(result.isPrerendered).toBe(true);
+        // Without enableHydration(), content is not hydrated
+        expect(result.isHydrated).toBe(false);
     });
 
     test("should connect immediately when a template is assigned later", async ({

packages/fast-element/src/templating/html-directive.ts

@@ -33,11 +33,16 @@ export interface ViewController<TSource = any, TParent = any>
     readonly _skipAttrUpdates?: boolean;
 
     /**
-     * A promise that resolves with `true` after prerendered content
-     * has been hydrated, or `false` when the view is client-side
-     * rendered.
+     * Resolves `true` when the view's host element had prerendered
+     * content (existing shadow root).
      */
     readonly isPrerendered?: Promise<boolean>;
+
+    /**
+     * Resolves `true` after prerendered content has been hydrated,
+     * `false` when client-side rendered or hydration not enabled.
+     */
+    readonly isHydrated?: Promise<boolean>;
 }
 
 /**

packages/fast-element/src/templating/view.ts

@@ -255,6 +255,12 @@ export class HTMLView<TSource = any, TParent = any>
      */
     public isPrerendered: Promise<boolean> = Promise.resolve(false);
 
+    /**
+     * Resolves `true` after prerendered content has been hydrated,
+     * `false` when client-side rendered or hydration not enabled.
+     */
+    public isHydrated: Promise<boolean> = Promise.resolve(false);
+
     /**
      * The execution context the view is running within.
      */

packages/fast-element/test/declarative/fixtures/ecosystem/declarative-no-hydration/declarative-no-hydration.spec.ts

@@ -75,19 +75,25 @@ test.describe("Declarative Template Without Hydration", () => {
         expect(hydrationEvents).toHaveLength(0);
     });
 
-    test("isPrerendered should resolve false without hydration", async ({ page }) => {
+    test("isPrerendered should resolve true with DSD, isHydrated should resolve false without enableHydration", async ({
+        page,
+    }) => {
         const allDefined = page.waitForFunction(
             () => (window as any).allDefined === true,
         );
         await page.goto("/fixtures/ecosystem/declarative-no-hydration/");
         await allDefined;
 
-        const isPrerendered = await page.evaluate(async () => {
+        const result = await page.evaluate(async () => {
             const el = document.querySelector("basic-element") as any;
-            return el.$fastController.isPrerendered;
+            return {
+                isPrerendered: await el.$fastController.isPrerendered,
+                isHydrated: await el.$fastController.isHydrated,
+            };
         });
 
-        expect(isPrerendered).toBe(false);
+        expect(result.isPrerendered).toBe(true);
+        expect(result.isHydrated).toBe(false);
     });
 
     test("should support interactivity after client-side render", async ({ page }) => {