fix: address PR review round 3

- Move hydrationEnabled guard above TSDoc so API Extractor
  attaches docs to enableHydration() correctly
- Make enableHydration() merge-safe — hook installs once, subsequent
  calls chain their options into the shared HydrationTracker via
  mergeOptions()
- Add ExecutionContext, SourceLifetime type exports to styles.js
- Add Notifier type export to arrays.js

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

Author: janechu

packages/fast-element/SIZES.md

@@ -4,7 +4,7 @@ Bundle sizes for `@microsoft/fast-element` exports.
 
 | Export | Minified | Gzip | Brotli |
 |--------|----------|------|--------|
-| CDN Rollup Bundle | 64.79 KB | 19.25 KB | 17.21 KB |
+| CDN Rollup Bundle | 65.04 KB | 19.35 KB | 17.30 KB |
 | FASTElement | 23.71 KB | 7.37 KB | 6.63 KB |
 | Updates | 473 B | 337 B | 287 B |
 | Observable | 6.70 KB | 2.49 KB | 2.22 KB |
@@ -19,6 +19,6 @@ Bundle sizes for `@microsoft/fast-element` exports.
 | repeat | 29.57 KB | 9.42 KB | 8.47 KB |
 | css | 2.43 KB | 1.00 KB | 911 B |
 | ElementStyles | 1.65 KB | 729 B | 623 B |
-| enableHydration | 42.96 KB | 13.12 KB | 11.80 KB |
+| enableHydration | 43.21 KB | 13.20 KB | 11.88 KB |
 | ArrayObserver | 12.51 KB | 4.45 KB | 4.01 KB |
-| declarativeTemplate | 85.40 KB | 26.14 KB | 23.03 KB |
+| declarativeTemplate | 85.65 KB | 26.21 KB | 23.10 KB |

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

@@ -303,7 +303,7 @@ export interface ElementViewTemplate<TSource = any, TParent = any> {
 // @public
 export const emptyArray: readonly never[];
 
-// @public (undocumented)
+// @public
 export function enableHydration(options?: HydrationOptions): void;
 
 // @public
@@ -559,6 +559,7 @@ export interface HydrationOptions {
 export class HydrationTracker {
     constructor(options: HydrationOptions);
     add(element: HTMLElement): void;
+    mergeOptions(incoming: HydrationOptions): void;
     remove(element: HTMLElement): void;
 }
 

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

@@ -29,6 +29,14 @@ export interface LengthObserver extends Subscriber {
 // @public
 export function lengthOf<T>(array: readonly T[]): number;
 
+// @public
+export interface Notifier {
+    notify(args: any): void;
+    readonly subject: any;
+    subscribe(subscriber: Subscriber, propertyToWatch?: any): void;
+    unsubscribe(subscriber: Subscriber, propertyToUnwatch?: any): void;
+}
+
 // @public
 export class Sort {
     constructor(sorted?: number[] | undefined);
@@ -91,8 +99,6 @@ export interface Subscriber {
     handleChange(subject: any, args: any): void;
 }
 
-// Warning: (ae-forgotten-export) The symbol "Notifier" needs to be exported by the entry point arrays.d.ts
-//
 // @public
 export class SubscriberSet implements Notifier {
     constructor(subject: any, initialSubscriber?: Subscriber);

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

@@ -7,7 +7,7 @@
 // @beta
 export const deferHydrationAttribute = "defer-hydration";
 
-// @public (undocumented)
+// @public
 export function enableHydration(options?: HydrationOptions): void;
 
 // @public

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

@@ -66,16 +66,37 @@ export class ElementStyles {
     withStrategy(Strategy: ConstructibleStyleStrategy): this;
 }
 
+// @public
+export interface ExecutionContext<TParent = any> {
+    readonly event: Event;
+    eventDetail<TDetail>(): TDetail;
+    eventTarget<TTarget extends EventTarget>(): TTarget;
+    index: number;
+    readonly isEven: boolean;
+    readonly isFirst: boolean;
+    readonly isInMiddle: boolean;
+    readonly isLast: boolean;
+    readonly isOdd: boolean;
+    length: number;
+    parent: TParent;
+    parentContext: ExecutionContext<TParent>;
+}
+
+// @public
+export const ExecutionContext: Readonly<{
+    default: ExecutionContext<any>;
+    getEvent(): Event | null;
+    setEvent(event: Event | null): void;
+}>;
+
 // @public
 export interface ExpressionController<TSource = any, TParent = any> {
-    // Warning: (ae-forgotten-export) The symbol "ExecutionContext" needs to be exported by the entry point styles.d.ts
     readonly context: ExecutionContext<TParent>;
     readonly isBound: boolean;
     onUnbind(behavior: {
         unbind(controller: ExpressionController<TSource, TParent>): any;
     }): void;
     readonly source: TSource;
-    // Warning: (ae-forgotten-export) The symbol "SourceLifetime" needs to be exported by the entry point styles.d.ts
     readonly sourceLifetime?: SourceLifetime;
 }
 
@@ -97,6 +118,15 @@ export interface HostController<TSource = any> extends ExpressionController<TSou
     removeStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
 }
 
+// @public
+export const SourceLifetime: Readonly<{
+    readonly unknown: undefined;
+    readonly coupled: 1;
+}>;
+
+// @public
+export type SourceLifetime = (typeof SourceLifetime)[keyof typeof SourceLifetime];
+
 // @public
 export interface StyleStrategy {
     addStylesTo(target: StyleTarget): void;

packages/fast-element/src/arrays.ts

@@ -9,4 +9,4 @@ export {
     SpliceStrategySupport,
     sortedCount,
 } from "./observation/arrays.js";
-export type { Subscriber, SubscriberSet } from "./observation/notifier.js";
+export type { Notifier, Subscriber, SubscriberSet } from "./observation/notifier.js";

packages/fast-element/src/components/enable-hydration.ts

@@ -15,6 +15,9 @@ export type { HydrationOptions };
  */
 function noopAttributeHandler() {}
 
+let tracker: HydrationTracker | null = null;
+let hookInstalled = false;
+
 /**
  * Enables hydration support for prerendered FAST elements.
  *
@@ -23,6 +26,9 @@ function noopAttributeHandler() {}
  * logic is not active unless this function is called, keeping
  * `FASTElement` lightweight for client-side-only applications.
  *
+ * Safe to call multiple times — the hydration hook is installed once
+ * and subsequent calls merge their options into the shared tracker.
+ *
  * @example
  * ```ts
  * import { enableHydration } from "@microsoft/fast-element/hydration.js";
@@ -37,25 +43,22 @@ function noopAttributeHandler() {}
  * @param options - Optional callbacks for global hydration events.
  * @public
  */
-let hydrationEnabled = false;
-
 export function enableHydration(options?: HydrationOptions): void {
-    if (hydrationEnabled) {
-        return;
-    }
-    hydrationEnabled = true;
-
     ensureHydrationRuntime();
-    const tracker = new HydrationTracker(options ?? {});
 
-    ElementController.installHydrationHook(
+    if (!hookInstalled) {
+        tracker = new HydrationTracker(options ?? {});
+        hookInstalled = true;
+        const activeTracker = tracker;
+
+        ElementController.installHydrationHook(
         (controller, template, element, host) => {
             if (!isHydratable(template)) {
                 return false;
             }
 
             const callbacks = controller.definition.lifecycleCallbacks;
-            tracker.add(element);
+            activeTracker.add(element);
 
             try {
                 try {
@@ -96,12 +99,16 @@ export function enableHydration(options?: HydrationOptions): void {
                     // A lifecycle callback must never prevent post-hydration work.
                 }
             } finally {
-                tracker.remove(element);
+                activeTracker.remove(element);
             }
 
             return true;
         },
     );
+    } else if (options && tracker) {
+        // Merge options into existing tracker for subsequent calls
+        tracker.mergeOptions(options);
+    }
 }
 
 /**

packages/fast-element/src/components/hydration-tracker.ts

@@ -68,4 +68,34 @@ export class HydrationTracker {
             }, 0);
         }
     }
+
+    /**
+     * Merges additional options into the tracker, chaining
+     * callbacks so both the original and new callbacks fire.
+     */
+    public mergeOptions(incoming: HydrationOptions): void {
+        const prev = this.options;
+        this.options = {
+            hydrationStarted: chainCallback(
+                prev.hydrationStarted,
+                incoming.hydrationStarted,
+            ),
+            hydrationComplete: chainCallback(
+                prev.hydrationComplete,
+                incoming.hydrationComplete,
+            ),
+        };
+    }
+}
+
+function chainCallback(
+    first: (() => void) | undefined,
+    second: (() => void) | undefined,
+): (() => void) | undefined {
+    if (!first) return second;
+    if (!second) return first;
+    return () => {
+        first();
+        second();
+    };
 }

packages/fast-element/src/styles.ts

@@ -10,6 +10,10 @@ export {
     ElementStyles,
 } from "./styles/element-styles.js";
 export type { Constructable } from "./interfaces.js";
-export type { ExpressionController } from "./observation/observable.js";
+export type {
+    ExecutionContext,
+    ExpressionController,
+    SourceLifetime,
+} from "./observation/observable.js";
 export type { HostBehavior, HostController } from "./styles/host.js";
 export type { StyleStrategy, StyleTarget } from "./styles/style-strategy.js";

sites/website/src/docs/3.x/api/fast-element.enablehydration.md

@@ -15,6 +15,8 @@ navigationOptions:
 
 ## enableHydration() function
 
+Enables hydration support for prerendered FAST elements.
+
 **Signature:**
 
 ```typescript
@@ -51,7 +53,7 @@ options
 
 </td><td>
 
-_(Optional)_
+_(Optional)_ Optional callbacks for global hydration events.
 
 
 </td></tr>
@@ -60,3 +62,22 @@ _(Optional)_
 **Returns:**
 
 void
+
+## Remarks
+
+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.
+
+Safe to call multiple times — the hydration hook is installed once and subsequent calls merge their options into the shared tracker.
+
+## Example
+
+
+```ts
+import { enableHydration } from "@microsoft/fast-element/hydration.js";
+
+enableHydration({
+    hydrationComplete() {
+        console.log("hydration complete");
+    },
+});
+```