refactor: add template resolver pipeline

Move FASTElement definition orchestration to a function-based template resolver pipeline so extensions run before template resolution and concrete templates are assigned before registration.

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

Author: janechu

change/@microsoft-fast-element-df226ab5-6e68-4362-b8ac-35046f0fc68b.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "add function-based template resolver sequencing",
+  "packageName": "@microsoft/fast-element",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

packages/fast-element/DESIGN.md

@@ -103,11 +103,11 @@ registry.
 - `onAttributeChangedCallback()` is the standard handler that processes attribute changes. During the prerendered bind, it is temporarily swapped to a no-op (see above) to avoid redundant processing of server-rendered attribute values.
 - Exposes `addBehavior` / `removeBehavior` for dynamic `HostBehavior` management (used by `ElementStyles`).
 
-`FASTElementDefinition` wraps all the metadata for a custom element class: its tag name, template, styles, and observed attribute list. It is created by `FASTElement.compose()` (which returns `Promise<FASTElementDefinition>`, always resolving immediately) and registered globally via `fastElementRegistry`. `FASTElement.define()` returns `Promise<TType>` — resolving immediately for complete definitions or deferring when `templateOptions` is `"defer-and-hydrate"` and no template is provided. `FASTElementDefinition.register()` returns `Promise<Function>` — resolving when a definition with the given name has been registered.
+`FASTElementDefinition` wraps all the metadata for a custom element class: its tag name, template, styles, and observed attribute list. It is created by `FASTElement.compose()` (which returns `Promise<FASTElementDefinition>`, always resolving immediately) and registered globally via `fastElementRegistry`. `PartialFASTElementDefinition.template` may be either a concrete `ElementViewTemplate` or a `FASTElementTemplateResolver` function that receives the composed definition and returns the concrete template (sync or async). `FASTElement.define()` returns `Promise<TType>` — resolving immediately for complete definitions, deferring when `templateOptions` is `"defer-and-hydrate"` and no template is provided, and resolving template resolver functions only after extensions have had a chance to update the definition. `FASTElementDefinition.register()` returns `Promise<Function>` — resolving when a definition with the given name has been registered.
 
 #### Extensions
 
-`FASTElement.define()` and `FASTElementDefinition.define()` accept an optional array of **extension callbacks** (`FASTElementExtension`). Each extension is a function that receives the resolved `FASTElementDefinition` and is invoked **before** the element is registered with the platform via `customElements.define()`. This allows plugins to inspect or act on the definition metadata (name, template, styles, attributes) before any existing DOM elements are upgraded.
+`FASTElement.define()` and `FASTElementDefinition.define()` accept an optional array of **extension callbacks** (`FASTElementExtension`). Each extension is a function that receives the resolved `FASTElementDefinition` and is invoked **before** the element is registered with the platform via `customElements.define()`. `FASTElement.define()` also invokes extensions before any template resolver function is asked to produce a concrete `ElementViewTemplate`, so plugins can attach state that affects template resolution without leaving non-template values on `definition.template`.
 
 ```typescript
 type FASTElementExtension = (definition: FASTElementDefinition) => void;

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

@@ -426,7 +426,7 @@ export const FASTElement: {
 export class FASTElementDefinition<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> {
     readonly attributeLookup: Record<string, AttributeDefinition>;
     readonly attributes: ReadonlyArray<AttributeDefinition>;
-    static compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): Promise<FASTElementDefinition<TType>>;
+    static compose<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition<TType>): Promise<FASTElementDefinition<TType>>;
     define(registry?: CustomElementRegistry, extensions?: FASTElementExtension[]): this;
     readonly elementOptions: ElementDefinitionOptions;
     static readonly getByType: (key: Function) => FASTElementDefinition<Constructable<HTMLElement>> | undefined;
@@ -457,6 +457,9 @@ export type FASTElementExtension = (definition: FASTElementDefinition) => void;
 // @internal
 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;
@@ -725,15 +728,16 @@ export const Parser: Readonly<{
 }>;
 
 // @public
-export interface PartialFASTElementDefinition {
+export interface PartialFASTElementDefinition<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> {
     readonly attributes?: (AttributeConfiguration | string)[];
     readonly elementOptions?: ElementDefinitionOptions;
     readonly lifecycleCallbacks?: TemplateLifecycleCallbacks;
     readonly name: string;
     readonly registry?: CustomElementRegistry;
     readonly shadowOptions?: Partial<ShadowRootOptions> | null;
     readonly styles?: ComposableStyles | ComposableStyles[];
-    readonly template?: ElementViewTemplate;
+    // Warning: (ae-forgotten-export) The symbol "FASTElementTemplateInput" needs to be exported by the entry point index.d.ts
+    readonly template?: FASTElementTemplateInput<TType>;
     // @alpha
     readonly templateOptions?: TemplateOptions;
 }

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

@@ -389,4 +389,110 @@ test.describe("FASTElementDefinition", () => {
             expect(extendsFASTElement).toBe(true);
         });
     });
+
+    test.describe("template resolvers", () => {
+        test("keeps resolver-backed templates unresolved until define-time", async ({
+            page,
+        }) => {
+            await page.goto("/");
+
+            const result = await page.evaluate(async () => {
+                // @ts-expect-error: Client module.
+                const { FASTElement, FASTElementDefinition, html, uniqueElementName } =
+                    await import("/main.js");
+
+                let resolveTemplate!: (value: any) => void;
+
+                class TestElement extends FASTElement {}
+
+                const elName = uniqueElementName();
+                const template = html<TestElement>`<span>resolved</span>`;
+                const templatePromise = new Promise<any>(resolve => {
+                    resolveTemplate = resolve;
+                });
+
+                const definition = await FASTElementDefinition.compose(TestElement, {
+                    name: elName,
+                    template: () => templatePromise,
+                });
+
+                const templateBeforeResolve = definition.template === undefined;
+                const definedBeforeResolve = customElements.get(elName) !== undefined;
+
+                definition.define();
+
+                resolveTemplate(template);
+                await customElements.whenDefined(elName);
+
+                const element = document.createElement(elName) as any;
+                document.body.appendChild(element);
+                await new Promise(resolve => requestAnimationFrame(resolve));
+
+                return {
+                    templateBeforeResolve,
+                    definedBeforeResolve,
+                    resolvedTemplateMatches: definition.template === template,
+                    shadowText: element.shadowRoot?.textContent ?? "",
+                };
+            });
+
+            expect(result.templateBeforeResolve).toBe(true);
+            expect(result.definedBeforeResolve).toBe(false);
+            expect(result.resolvedTemplateMatches).toBe(true);
+            expect(result.shadowText).toContain("resolved");
+        });
+
+        test("applies extensions only once while async registration is pending", async ({
+            page,
+        }) => {
+            await page.goto("/");
+
+            const result = await page.evaluate(async () => {
+                // @ts-expect-error: Client module.
+                const { FASTElement, FASTElementDefinition, html, uniqueElementName } =
+                    await import("/main.js");
+
+                let resolveTemplate!: (value: any) => void;
+                const extensionCalls: string[] = [];
+
+                class TestElement extends FASTElement {}
+
+                const elName = uniqueElementName();
+                const template = html<TestElement>`<span>resolved</span>`;
+                const templatePromise = new Promise<any>(resolve => {
+                    resolveTemplate = resolve;
+                });
+
+                const definition = await FASTElementDefinition.compose(TestElement, {
+                    name: elName,
+                    template: () => templatePromise,
+                });
+
+                const extension = () => {
+                    extensionCalls.push("called");
+                };
+
+                definition.define(customElements, [extension]);
+                definition.define(customElements, [extension]);
+
+                await Promise.resolve();
+
+                const definedWhilePending = customElements.get(elName) !== undefined;
+                const callCountWhilePending = extensionCalls.length;
+
+                resolveTemplate(template);
+                await customElements.whenDefined(elName);
+
+                return {
+                    definedWhilePending,
+                    callCountWhilePending,
+                    finalCallCount: extensionCalls.length,
+                };
+            });
+
+            expect(result.definedWhilePending).toBe(false);
+            expect(result.callCountWhilePending).toBe(1);
+            expect(result.finalCallCount).toBe(1);
+        });
+    });
 });