feat: modularize FASTElement for smaller bundle size

Breaking changes to reduce FASTElement bundle size:

- Remove globalThis.FAST singleton — FAST is now a module-scoped
  export, no side-effecting global mutation
- Remove FAST.getById(), FASTGlobal type, KernelServiceId enum
- Remove requestIdleCallback polyfill (native in all modern browsers)
- Move HydrationView to separate module (hydration-view.ts)
- Move renderPrerendered to pluggable hydration hook in
  enable-hydration.ts — ElementController has zero hydration imports
- Move CSS/styles to ./styles.js subpath export
- Move array observation to ./arrays.js subpath export
- Move deferHydrationAttribute to ./hydration.js subpath
  (retained for intersection observer viewport hydration rendering)
- ElementController uses composition instead of inheritance
  for PropertyChangeNotifier
- Update DESIGN.md, README.md, migration guide, 3.x docs
- Fix fast-router and todo-app imports for new subpaths
- Update platform.pw.spec.ts and debug.pw.spec.ts for module FAST

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

Author: janechu

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/SIZES.md

@@ -4,17 +4,17 @@ Bundle sizes for `@microsoft/fast-element` exports.
 
 | Export | Minified | Gzip | Brotli |
 |--------|----------|------|--------|
-| 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 |
-| attr | 1.28 KB | 634 B | 552 B |
-| children | 5.68 KB | 2.19 KB | 1.95 KB |
-| css | 2.36 KB | 1.05 KB | 964 B |
-| ref | 4.65 KB | 1.86 KB | 1.63 KB |
-| 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.86 KB | 8.79 KB | 7.89 KB |
-| repeat | 30.51 KB | 9.71 KB | 8.75 KB |
+| CDN Rollup Bundle | 63.66 KB | 19.00 KB | 17.01 KB |
+| FASTElement | 22.83 KB | 7.19 KB | 6.49 KB |
+| Updates | 473 B | 337 B | 287 B |
+| Observable | 6.70 KB | 2.49 KB | 2.22 KB |
+| observable | 6.74 KB | 2.50 KB | 2.24 KB |
+| attr | 477 B | 288 B | 244 B |
+| children | 4.81 KB | 1.86 KB | 1.64 KB |
+| css | 0 B | 20 B | 1 B |
+| ref | 3.78 KB | 1.53 KB | 1.33 KB |
+| slotted | 4.60 KB | 1.79 KB | 1.58 KB |
+| volatile | 6.79 KB | 2.53 KB | 2.25 KB |
+| when | 1.82 KB | 712 B | 568 B |
+| html | 25.92 KB | 8.50 KB | 7.61 KB |
+| repeat | 29.57 KB | 9.42 KB | 8.47 KB |

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

@@ -14,23 +14,6 @@ export interface Accessor {
 // @public
 export type AddViewBehaviorFactory = (factory: ViewBehaviorFactory) => string;
 
-// @public
-export interface ArrayObserver extends SubscriberSet {
-    addSort(sort: Sort): void;
-    addSplice(splice: Splice): void;
-    flush(): void;
-    readonly lengthObserver: LengthObserver;
-    reset(oldCollection: any[] | undefined): void;
-    readonly sortObserver: SortObserver;
-    strategy: SpliceStrategy | null;
-}
-
-// @public
-export const ArrayObserver: Readonly<{
-    readonly sorted: 0;
-    readonly enable: () => void;
-}>;
-
 // @public
 export interface Aspected {
     aspectType: DOMAspect;
@@ -151,19 +134,11 @@ export const Compiler: {
     aggregate(parts: (string | ViewBehaviorFactory)[], policy?: DOMPolicy): ViewBehaviorFactory;
 };
 
-// @public
-export type ComposableStyles = string | ElementStyles | CSSStyleSheet;
-
 // @public
 export type Constructable<T = {}> = {
     new (...args: any[]): T;
 };
 
-// @public
-export type ConstructibleStyleStrategy = {
-    new (styles: (string | CSSStyleSheet)[]): StyleStrategy;
-};
-
 // @public
 export interface ContentTemplate {
     create(): ContentView;
@@ -179,46 +154,12 @@ export interface ContentView {
     unbind(): void;
 }
 
-// @public
-export const css: CSSTemplateTag;
-
-// @public
-export interface CSSDirective {
-    createCSS(): ComposableStyles;
-}
-
-// @public
-export const CSSDirective: Readonly<{
-    getForInstance: (object: any) => CSSDirectiveDefinition<Constructable<CSSDirective>> | undefined;
-    getByType: (key: Function) => CSSDirectiveDefinition<Constructable<CSSDirective>> | undefined;
-    define<TType extends Constructable<CSSDirective>>(type: any): TType;
-}>;
-
-// @public
-export function cssDirective(): (type: Constructable<CSSDirective>) => void;
-
-// @public
-export interface CSSDirectiveDefinition<TType extends Constructable<CSSDirective> = Constructable<CSSDirective>> {
-    readonly type: TType;
-}
-
-// @public
-export type CSSTemplateTag = ((strings: TemplateStringsArray, ...values: CSSValue[]) => ElementStyles) & {
-    partial(strings: TemplateStringsArray, ...values: CSSValue[]): CSSDirective;
-};
-
-// @public
-export type CSSValue = ComposableStyles | CSSDirective;
-
 // @public
 export function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Constructable<HTMLElement>) => void;
 
 // @public
 export type DecoratorAttributeConfiguration = Omit<AttributeConfiguration, "property">;
 
-// @beta
-export const deferHydrationAttribute = "defer-hydration";
-
 // @public
 export interface Disposable {
     dispose(): void;
@@ -255,12 +196,15 @@ export interface DOMPolicy {
 // @public
 export type DOMSink = (target: Node, aspectName: string, value: any, ...args: any[]) => void;
 
+// Warning: (ae-forgotten-export) The symbol "HostController" needs to be exported by the entry point index.d.ts
+//
 // @public
-export class ElementController<TElement extends HTMLElement = HTMLElement> extends PropertyChangeNotifier implements HostController<TElement> {
+export class ElementController<TElement extends HTMLElement = HTMLElement> implements Notifier, HostController<TElement> {
     // @internal
     constructor(element: TElement, definition: FASTElementDefinition);
     addBehavior(behavior: HostBehavior<TElement>): void;
     addStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
+    // Warning: (ae-forgotten-export) The symbol "HostBehavior" needs to be exported by the entry point index.d.ts
     protected behaviors: Map<HostBehavior<TElement>, number> | null;
     protected bindObservables(): void;
     protected captureBoundObservables(): void;
@@ -271,16 +215,19 @@ export class ElementController<TElement extends HTMLElement = HTMLElement> exten
     disconnect(): void;
     protected disconnectBehaviors(): void;
     emit(type: string, detail?: any, options?: Omit<CustomEventInit, "detail">): void | boolean;
-    static enableHydration(tracker: HydrationTracker): void;
     static forCustomElement(element: HTMLElement, override?: boolean): ElementController;
     protected hasExistingShadowRoot: boolean;
+    // @internal
+    static installHydrationHook(hook: (controller: ElementController, template: ElementViewTemplate, element: HTMLElement, host: Node) => boolean): void;
     get isBound(): boolean;
     get isConnected(): boolean;
     readonly isHydrated: Promise<boolean>;
     readonly isPrerendered: Promise<boolean>;
+    // Warning: (ae-forgotten-export) The symbol "ElementStyles" needs to be exported by the entry point index.d.ts
     get mainStyles(): ElementStyles | null;
     set mainStyles(value: ElementStyles | null);
     protected needsInitialization: boolean;
+    notify(args: any): void;
     protected observeLateAttributes(): void;
     onAttributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     onUnbind(behavior: {
@@ -295,9 +242,12 @@ export class ElementController<TElement extends HTMLElement = HTMLElement> exten
     readonly source: TElement;
     get sourceLifetime(): SourceLifetime | undefined;
     protected stage: Stages;
+    get subject(): TElement;
+    subscribe(subscriber: Subscriber, propertyToWatch?: any): void;
     protected syncLateAttributes(): void;
     get template(): ElementViewTemplate<TElement> | null;
     set template(value: ElementViewTemplate<TElement> | null);
+    unsubscribe(subscriber: Subscriber, propertyToUnwatch?: any): void;
     readonly view: ElementView<TElement> | null;
 }
 
@@ -313,24 +263,6 @@ export const elements: (selector?: string) => ElementsFilter;
 // @public
 export type ElementsFilter = (value: Node, index?: number, array?: Node[]) => boolean;
 
-// @public
-export class ElementStyles {
-    constructor(styles: ReadonlyArray<ComposableStyles>);
-    // @internal (undocumented)
-    addStylesTo(target: StyleTarget): void;
-    // @internal (undocumented)
-    isAttachedTo(target: StyleTarget): boolean;
-    static normalize(styles: ComposableStyles | ComposableStyles[] | undefined): ElementStyles | undefined;
-    // @internal (undocumented)
-    removeStylesFrom(target: StyleTarget): void;
-    static setDefaultStrategy(Strategy: ConstructibleStyleStrategy): void;
-    get strategy(): StyleStrategy;
-    // (undocumented)
-    readonly styles: ReadonlyArray<ComposableStyles>;
-    static readonly supportsAdoptedStyleSheets: boolean;
-    withStrategy(Strategy: ConstructibleStyleStrategy): this;
-}
-
 // @public
 export interface ElementView<TSource = any, TParent = any> extends View<TSource, TParent> {
     appendTo(node: Node): void;
@@ -402,7 +334,11 @@ export interface ExpressionObserver<TSource = any, TReturn = any, TParent = any>
 }
 
 // @public
-export const FAST: FASTGlobal;
+export const FAST: {
+    warn(_code: number, _values?: Record<string, any>): void;
+    error(code: number, _values?: Record<string, any>): Error;
+    addMessages(messages: Record<number, string>): void;
+};
 
 // @public
 export interface FASTElement extends HTMLElement {
@@ -457,34 +393,6 @@ export const fastElementRegistry: TypeRegistry<FASTElementDefinition>;
 // @public
 export type FASTElementTemplateResolver<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> = (definition: FASTElementDefinition<TType>) => ElementViewTemplate<InstanceType<TType>> | Promise<ElementViewTemplate<InstanceType<TType>>>;
 
-// @public
-export interface FASTGlobal {
-    addMessages(messages: Record<number, string>): void;
-    error(code: number, values?: Record<string, any>): Error;
-    getById<T>(id: string | number): T | null;
-    // (undocumented)
-    getById<T>(id: string | number, initialize: () => T): T;
-    warn(code: number, values?: Record<string, any>): void;
-}
-
-// @public
-export interface HostBehavior<TSource = any> {
-    addedCallback?(controller: HostController<TSource>): void;
-    connectedCallback?(controller: HostController<TSource>): void;
-    disconnectedCallback?(controller: HostController<TSource>): void;
-    removedCallback?(controller: HostController<TSource>): void;
-}
-
-// @public
-export interface HostController<TSource = any> extends ExpressionController<TSource> {
-    addBehavior(behavior: HostBehavior<TSource>): void;
-    addStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
-    readonly isConnected: boolean;
-    mainStyles: ElementStyles | null;
-    removeBehavior(behavior: HostBehavior<TSource>, force?: boolean): void;
-    removeStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
-}
-
 // @public
 export const html: HTMLTemplateTag;
 
@@ -641,14 +549,6 @@ export function isHydratable<TSource = any, TParent = any>(template: ElementView
 // @beta (undocumented)
 export function isHydratable(template: ContentTemplate): template is HydratableContentTemplate;
 
-// @public
-export interface LengthObserver extends Subscriber {
-    length: number;
-}
-
-// @public
-export function lengthOf<T>(array: readonly T[]): number;
-
 // @public
 export function listener<T = any>(expression: Expression<T>, options?: AddEventListenerOptions): Binding<T>;
 
@@ -738,6 +638,7 @@ export interface PartialFASTElementDefinition<TType extends Constructable<HTMLEl
     readonly name: string;
     readonly registry?: CustomElementRegistry;
     readonly shadowOptions?: Partial<ShadowRootOptions> | null;
+    // Warning: (ae-forgotten-export) The symbol "ComposableStyles" needs to be exported by the entry point index.d.ts
     readonly styles?: ComposableStyles | ComposableStyles[];
     readonly template?: ElementViewTemplate<InstanceType<TType>> | FASTElementTemplateResolver<TType>;
 }
@@ -798,6 +699,8 @@ export function repeat<TSource = any, TArray extends ReadonlyArray<any> = Readon
 export class RepeatBehavior<TSource = any> implements ViewBehavior, Subscriber {
     constructor(directive: RepeatDirective);
     bind(controller: ViewController): void;
+    // Warning: (ae-forgotten-export) The symbol "Splice" needs to be exported by the entry point index.d.ts
+    // Warning: (ae-forgotten-export) The symbol "Sort" needs to be exported by the entry point index.d.ts
     handleChange(source: any, args: Splice[] | Sort[] | ExpressionObserver): void;
     unbind(): void;
     // @internal (undocumented)
@@ -846,21 +749,6 @@ export class SlottedDirective extends NodeObservationDirective<SlottedDirectiveO
 export interface SlottedDirectiveOptions<T = any> extends NodeBehaviorOptions<T>, AssignedNodesOptions {
 }
 
-// @public
-export class Sort {
-    constructor(sorted?: number[] | undefined);
-    // (undocumented)
-    sorted?: number[] | undefined;
-}
-
-// @public
-export function sortedCount<T>(array: readonly T[]): number;
-
-// @public
-export interface SortObserver extends Subscriber {
-    sorted: number;
-}
-
 // @public
 export const SourceLifetime: Readonly<{
     readonly unknown: undefined;
@@ -870,48 +758,6 @@ export const SourceLifetime: Readonly<{
 // @public
 export type SourceLifetime = (typeof SourceLifetime)[keyof typeof SourceLifetime];
 
-// @public
-export class Splice {
-    constructor(index: number, removed: any[], addedCount: number);
-    // (undocumented)
-    addedCount: number;
-    adjustTo(array: any[]): this;
-    // (undocumented)
-    index: number;
-    // (undocumented)
-    removed: any[];
-    reset?: boolean;
-}
-
-// @public
-export interface SpliceStrategy {
-    normalize(previous: unknown[] | undefined, current: unknown[], changes: Splice[] | undefined): readonly Splice[];
-    pop(array: any[], observer: ArrayObserver, pop: typeof Array.prototype.pop, args: any[]): any;
-    push(array: any[], observer: ArrayObserver, push: typeof Array.prototype.push, args: any[]): any;
-    reverse(array: any[], observer: ArrayObserver, reverse: typeof Array.prototype.reverse, args: any[]): any;
-    shift(array: any[], observer: ArrayObserver, shift: typeof Array.prototype.shift, args: any[]): any;
-    sort(array: any[], observer: ArrayObserver, sort: typeof Array.prototype.sort, args: any[]): any[];
-    splice(array: any[], observer: ArrayObserver, splice: typeof Array.prototype.splice, args: any[]): any;
-    readonly support: SpliceStrategySupport;
-    unshift(array: any[], observer: ArrayObserver, unshift: typeof Array.prototype.unshift, args: any[]): any[];
-}
-
-// @public
-export const SpliceStrategy: Readonly<{
-    readonly reset: Splice[];
-    readonly setDefaultStrategy: (strategy: SpliceStrategy) => void;
-}>;
-
-// @public
-export const SpliceStrategySupport: Readonly<{
-    readonly reset: 1;
-    readonly splice: 2;
-    readonly optimized: 3;
-}>;
-
-// @public
-export type SpliceStrategySupport = (typeof SpliceStrategySupport)[keyof typeof SpliceStrategySupport];
-
 // @public
 export const enum Stages {
     connected = 1,
@@ -930,20 +776,6 @@ export abstract class StatelessAttachedAttributeDirective<TOptions> implements H
     protected options: TOptions;
 }
 
-// @public
-export interface StyleStrategy {
-    addStylesTo(target: StyleTarget): void;
-    removeStylesFrom(target: StyleTarget): void;
-}
-
-// @public
-export interface StyleTarget extends Pick<Node, "getRootNode"> {
-    adoptedStyleSheets?: CSSStyleSheet[];
-    append(styles: HTMLStyleElement): void;
-    querySelectorAll<E extends Element = Element>(selectors: string): NodeListOf<E>;
-    removeChild(styles: HTMLStyleElement): void;
-}
-
 // @public
 export interface Subscriber {
     handleChange(subject: any, args: any): void;

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

@@ -4,6 +4,9 @@
 
 ```ts
 
+// @beta
+export const deferHydrationAttribute = "defer-hydration";
+
 // @public
 export function enableHydration(options?: HydrationOptions): void;