feat: Prerendered content binding optimization

[janechu]

Pull Request

📖 Description

Replace HydratableElementController with an automatic prerendered content optimization built into ElementController. When a component connects and already has an existing shadow root (from SSR or declarative shadow DOM), the system automatically:

• Hooks up event listeners (e.g., @click)
• Runs structural directives (when, repeat, ref, children, slotted)
• Subscribes to observable/attr properties for future change notifications
• Skips re-evaluating attribute and booleanAttribute binding expressions (DOM already has correct values)

No explicit configuration from component authors is required. The presence of an existing shadow root signals prerendered content.

This is a breaking change for both @microsoft/fast-element and @microsoft/fast-html. See the migration docs in packages/fast-element/MIGRATION.md and packages/fast-html/MIGRATION.md.

👩‍💻 Reviewer Notes

Breaking changes (@microsoft/fast-element)

Removed exports:

• HydratableElementController → use ElementController (prerendered path built in)
• HydrationControllerCallbacks → use TemplateElement.config() in @microsoft/fast-html
• needsHydrationAttribute → use ElementController.isPrerendered

New APIs:

• ElementController.isPrerendered (readonly boolean) — true when an existing shadow root was detected
• ViewController.isPrerendered (readonly boolean?) — available to directives during bind()

Changed behavior:

• ElementController.connect() adds a template-pending guard for defineAsync() flow
• ElementController.onAttributeChangedCallback() skips during initial upgrade when prerendered
• HTMLBindingDirective.bind() skips attribute/booleanAttribute updateTarget calls when controller.isPrerendered
• ViewTemplate.render() signature adds optional isPrerendered parameter

Breaking changes (@microsoft/fast-html)

Removed exports:

• RenderableFASTElement → extend FASTElement directly

Removed concepts:

• prepare() lifecycle hook → set state in connectedCallback
• defer-hydration / needs-hydration attributes → automatic detection
• waitForAncestorHydration() → not needed

Migration

See packages/fast-element/MIGRATION.md and packages/fast-html/MIGRATION.md for detailed migration steps.

Quick summary:

1. Replace RenderableFASTElement(MyComponent).defineAsync({...}) with MyComponent.defineAsync({...})
2. Remove HydratableElementController.install() calls
3. Remove defer-hydration and needs-hydration from server-rendered markup
4. Use $fastController.isPrerendered to detect prerendered components

📑 Test Plan

• All 1392 @microsoft/fast-element tests pass
• All 271 @microsoft/fast-html tests pass
• New tests for isPrerendered flag detection (CSR vs DSD) and template-pending guard
• Updated hydration lifecycle and performance metrics tests for the new flow
• All fixture main.ts files updated to use FASTElement directly

✅ Checklist

General

• I have included a change request file using $ npm run change
• I have added tests for my changes.
• I have tested my changes.
• I have updated the project documentation to reflect my changes.
• I have read the CONTRIBUTING documentation and followed the standards for this project.

⏭ Next Steps

• Update @microsoft/fast-build / @microsoft/fast-ssr to stop emitting defer-hydration / needs-hydration attributes
• Update example projects to use the new API
• Consider adding benchmarks comparing prerendered vs CSR initial render performance