feat: modularize FASTElement with opt-in hydration and subpath exports (#7497)

# Pull Request

## 📖 Description

Modularizes `@microsoft/fast-element` to reduce core bundle size and make hydration, styles, and array observation opt-in through subpath exports.

**Hydration is now opt-in** — `enableHydration()` from `@microsoft/fast-element/hydration.js` activates hydration via a pluggable hook. Without it, `ElementController` has zero hydration imports or logic.

**New subpath exports** split heavy features out of the main barrel:
- `./styles.js` — `css`, `ElementStyles`, `CSSDirective`, style strategies
- `./arrays.js` — `ArrayObserver`, `Splice`, `SpliceStrategy`, array utilities  
- `./hydration.js` — `enableHydration`, `deferHydrationAttribute`

**`globalThis.FAST` removed** — `FAST` is now a module-scoped export with no side-effecting global mutation. `FAST.getById()`, `FASTGlobal`, `KernelServiceId`, and the `requestIdleCallback` polyfill are all removed.

**Per-element lifecycle callbacks** are passed directly to `declarativeTemplate()`, and `isPrerendered` / `isHydrated` are now separate promises with clear semantics.

## 👩‍💻 Reviewer Notes

- `TemplateElement.config()` is preserved as a deprecated shim for backward compatibility.
- `ElementController` now uses composition for `PropertyChangeNotifier` instead of inheritance.
- The hydration rendering path (`renderPrerendered`) moved entirely into `enable-hydration.ts` via `ElementController.installHydrationHook()`.
- `isPrerendered` resolves `true` when a DSD shadow root existed (independent of hydration). `isHydrated` resolves `true` only when hydration actually ran.
- Declarative template `{{ }}` bindings with spaces inside braces do not work — the templates.html files must use `{{binding}}` without spaces.

## 📑 Test Plan

- 1396 Playwright tests pass (chromium)
- 176 declarative fixture tests pass (chromium)
- New `declarative-no-hydration` fixture (5 tests) verifies client-side rendering, lifecycle callbacks without hydration, and `isPrerendered`/`isHydrated` semantics
- Updated `platform.pw.spec.ts` and `debug.pw.spec.ts` for module-scoped FAST
- Updated `lifecycle-callbacks` and `performance-metrics` fixtures for new API

## ✅ Checklist

### General

- [x] I have included a change request file using `$ npm run change`
- [x] I have added tests for my changes.
- [x] I have tested my changes.
- [x] I have updated the project documentation to reflect my changes.
- [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/main/CONTRIBUTING.md) documentation and followed the [standards](https://github.com/microsoft/fast/blob/main/CODE_OF_CONDUCT.md#our-standards) for this project.

## ⏭ Next Steps

- Run full CI across all browsers (Firefox, WebKit)
- Remove `TemplateElement.config()` deprecated shim in a future release
- Consider lazy-loading the `Compiler` on first render for further size reduction

Author: janechu

change/@microsoft-fast-element-bfa58c92-2d69-4eea-b132-64dbe65d1663.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: modularize hydration and expose lifecycle callbacks via enableHydration() and declarativeTemplate()",
+  "packageName": "@microsoft/fast-element",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

change/@microsoft-fast-router-de58ce36-92f3-4c7f-86a2-43a66a522f81.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Update imports for styles.js subpath export",
+  "packageName": "@microsoft/fast-router",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

examples/todo-app/src/todo-app.styles.ts

@@ -1,4 +1,4 @@
-import { css } from "@microsoft/fast-element";
+import { css } from "@microsoft/fast-element/styles.js";
 
 export const styles = css`
     :host {

examples/todo-app/src/todo-form.styles.ts

@@ -1,4 +1,4 @@
-import { css } from "@microsoft/fast-element";
+import { css } from "@microsoft/fast-element/styles.js";
 
 export const styles = css`
     form {

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
 
@@ -154,23 +155,21 @@ FAST HTML provides a set of lifecycle callbacks that allow you to hook into vari
 
 ### Available Callbacks
 
-The lifecycle callbacks are organized into three categories:
+The lifecycle callbacks are split between two APIs:
 
-**Template Registration Callbacks:**
+**Per-element callbacks** — passed to `declarativeTemplate()`:
 - `elementDidRegister(name: string)` - Called after the JavaScript class definition has been registered as a partial definition
 - `templateWillUpdate(name: string)` - Called before the template has been evaluated and assigned to the definition
-
-**Template Processing Callbacks:**
 - `templateDidUpdate(name: string)` - Called after the template has been assigned to the definition
 - `elementDidDefine(name: string)` - Called after the custom element has been fully defined with the platform
-
-**Hydration Callbacks:**
-- `hydrationStarted()` - Called once when the first prerendered element begins hydrating
 - `elementWillHydrate(source: HTMLElement)` - Called before an element begins hydration
 - `elementDidHydrate(source: HTMLElement)` - Called after an element completes hydration
+
+**Global hydration callbacks** — passed to `enableHydration()`:
+- `hydrationStarted()` - Called once when the first prerendered element begins hydrating
 - `hydrationComplete()` - Called once after all prerendered elements have completed hydration
 
-Hydration callbacks are tracked at the element level by `ElementController`. The `hydrationComplete` callback fires only after every prerendered element has finished binding.
+The `hydrationComplete` callback fires only after every prerendered element has finished binding.
 
 ### Callback Execution Order
 
@@ -186,7 +185,7 @@ Template Processing Phase (asynchronous):
   4. templateDidUpdate(name)
   5. elementDidDefine(name)
   
-Hydration Phase (per element):
+Hydration Phase (per element, only when enableHydration() has been called):
   6. hydrationStarted()           [once, on first element]
   7. elementWillHydrate(source)
   8. [Hydration occurs]
@@ -200,64 +199,90 @@ Completion (called once for all elements):
 
 ### Configuring Callbacks
 
-Configure callbacks using `TemplateElement.config()` before defining the template element:
+Hydration must be explicitly opted into by calling `enableHydration()`. Per-element
+callbacks are passed directly to `declarativeTemplate()`:
 
 ```typescript
-import { TemplateElement, type HydrationLifecycleCallbacks } from "@microsoft/fast-element/declarative.js";
+import { enableHydration } from "@microsoft/fast-element/hydration.js";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
 
-TemplateElement.config({
-    elementDidRegister(name) {
-        console.log(`${name} registered`);
-    },
-    templateWillUpdate(name) {
-        console.log(`${name} template updating`);
-    },
-    templateDidUpdate(name) {
-        console.log(`${name} template updated`);
-    },
-    elementDidDefine(name) {
-        console.log(`${name} fully defined`);
-    },
-    elementWillHydrate(source) {
-        console.log(`${source.localName} starting hydration`);
-    },
-    elementDidHydrate(source) {
-        console.log(`${source.localName} hydrated`);
+// Global hydration events
+enableHydration({
+    hydrationStarted() {
+        console.log("Hydration started");
     },
     hydrationComplete() {
-        console.log('All elements hydrated');
-    }
+        console.log("All elements hydrated");
+    },
+});
+
+// Per-element lifecycle callbacks
+MyComponent.define({
+    name: "my-component",
+    template: declarativeTemplate({
+        elementDidRegister(name) {
+            console.log(`${name} registered`);
+        },
+        templateWillUpdate(name) {
+            console.log(`${name} template updating`);
+        },
+        templateDidUpdate(name) {
+            console.log(`${name} template updated`);
+        },
+        elementDidDefine(name) {
+            console.log(`${name} fully defined`);
+        },
+        elementWillHydrate(source) {
+            console.log(`${source.localName} starting hydration`);
+        },
+        elementDidHydrate(source) {
+            console.log(`${source.localName} hydrated`);
+        },
+    }),
 });
 ```
 
 ### Use Cases
 
 **Performance Monitoring:**
 ```typescript
-TemplateElement.config({
-    elementWillHydrate(source) {
-        performance.mark(`${source.localName}-hydration-start`);
-    },
-    elementDidHydrate(source) {
-        performance.mark(`${source.localName}-hydration-end`);
-        performance.measure(`${source.localName}-hydration`, `${source.localName}-hydration-start`, `${source.localName}-hydration-end`);
-    },
+import { enableHydration } from "@microsoft/fast-element/hydration.js";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+
+enableHydration({
     hydrationComplete() {
-        const measures = performance.getEntriesByType('measure');
+        const measures = performance.getEntriesByType("measure");
         // Send metrics to analytics
-    }
+    },
+});
+
+MyComponent.define({
+    name: "my-component",
+    template: declarativeTemplate({
+        elementWillHydrate(source) {
+            performance.mark(`${source.localName}-hydration-start`);
+        },
+        elementDidHydrate(source) {
+            performance.mark(`${source.localName}-hydration-end`);
+            performance.measure(
+                `${source.localName}-hydration`,
+                `${source.localName}-hydration-start`,
+                `${source.localName}-hydration-end`,
+            );
+        },
+    }),
 });
 ```
 
 **Loading State Management:**
 ```typescript
-TemplateElement.config({
+enableHydration({
     hydrationStarted() {
-        document.body.classList.add('hydrating');
+        document.body.classList.add("hydrating");
     },
     hydrationComplete() {
-        document.body.classList.remove('hydrating');
-        document.body.classList.add('interactive');
-    }
+        document.body.classList.remove("hydrating");
+        document.body.classList.add("interactive");
+    },
 });
 ```