docs: split v3 migration guide

packages/fast-element/docs/declarative/design.md

@@ -622,7 +622,7 @@ sequenceDiagram
     participant Hydration as enableHydration().whenHydrated()
 
     App->>Hydration: const hydration = enableHydration() [optional]
-    App->>FER: await MyElement.define({name:'my-el', template: declarativeTemplate()}, [attributeMap(), observerMap()])
+    App->>FER: MyElement.define({name:'my-el', template: declarativeTemplate()}, [attributeMap(), observerMap()])
     note over FER: definition composed; resolver waits for template
 
     DOM->>FTE: f-template connected to DOM

packages/fast-element/docs/declarative/lifecycle.md

@@ -50,7 +50,7 @@ class MyComponent extends FASTElement {
 }
 
 // Register with the declarative template bridge
-await MyComponent.define({
+MyComponent.define({
     name: "my-component",
     template: declarativeTemplate(),
 });

packages/fast-element/docs/migration/fast-element-3.md

@@ -383,17 +383,17 @@ This is a **breaking change** for SSR output format. Any system that produces or
 
 | Removed | Replacement |
 |---|---|
-| `FASTElement.defineAsync()` | Subclass `define()` calls (now return `Promise<TType>`) |
+| `FASTElement.defineAsync()` | Subclass `define()` calls |
 | `FASTElement.compose()` and subclass `compose()` calls | Subclass `define()` calls |
 | `FASTElementDefinition.composeAsync()` | Subclass `define()` calls |
 | `FASTElementDefinition.registerAsync()` | `FASTElementDefinition.register()` (same `Promise<Function>` return type) |
 
 ### Changed behavior
 
-- Subclass **`define()`** calls now return `Promise<TType>`. When a concrete
-  template is provided at definition time, the Promise resolves immediately.
-  When `template: declarativeTemplate()` is used, the Promise resolves after
-  the matching `<f-template>` supplies the concrete template.
+- Subclass **`define()`** calls return `Promise<TType>` only for code that
+  explicitly needs to observe registration completion. When
+  `template: declarativeTemplate()` is used, that Promise resolves after the
+  matching `<f-template>` supplies the concrete template.
 - Subclass compose helpers are no longer part of the public authoring surface; use subclass `define()` for registration.
 - **`@customElement` decorator** calls `define()` internally but does not return the Promise (fire-and-forget). For complete definitions with a template, the element is registered via a microtask.
 
@@ -409,7 +409,7 @@ This is a **breaking change** for SSR output format. Any system that produces or
     });
 
     // After
-    await MyElement.define({
+    MyElement.define({
         name: "my-element",
         template: declarativeTemplate(),
     });
@@ -427,7 +427,7 @@ This is a **breaking change** for SSR output format. Any system that produces or
     }).define();
 
     // After
-    await MyElement.define({
+    MyElement.define({
         name: "my-element",
         template,
         styles,
@@ -446,7 +446,7 @@ This is a **breaking change** for SSR output format. Any system that produces or
    })).define();
 
    // After
-   await MyElement.define({
+   MyElement.define({
        name: "my-element",
        template,
        styles,
@@ -471,7 +471,7 @@ This is a **breaking change** for SSR output format. Any system that produces or
     FASTElementDefinition.compose(MyElement, options).define();
 
     // After
-    await MyElement.define(options);
+    MyElement.define(options);
    ```
 
 ## Dynamic stylesheet behaviors (v3)

packages/fast-element/docs/migration/fast-html.md

@@ -36,9 +36,9 @@ See the [`@microsoft/fast-element` migration guide](./fast-element-3.md#hydratio
 ### Migration steps
 
 1. Replace `RenderableFASTElement(MyComponent).defineAsync({...})` with
-   `await MyComponent.define({...})` and use `declarativeTemplate()` for
-   declarative templates. `declarativeTemplate()` is the waiting behavior: it
-   resolves the matching `<f-template>` before `define()` completes.
+   `MyComponent.define({...})` and use `declarativeTemplate()` for declarative
+   templates. If code explicitly observes the Promise returned by `define()`,
+   it resolves after the matching `<f-template>` supplies the concrete template.
 
    ```typescript
    // Before
@@ -49,7 +49,7 @@ See the [`@microsoft/fast-element` migration guide](./fast-element-3.md#hydratio
    });
 
    // After
-   await MyComponent.define({
+   MyComponent.define({
        name: "my-component",
        template: declarativeTemplate(),
    });

sites/website/src/docs/3.x/declarative-templates/server-rendering.md

@@ -422,8 +422,8 @@ offending marker.
 
 `declarativeTemplate()` waits for one connected `<f-template>` whose `name`
 matches the element definition. Template-first and definition-first loading both
-work, but the custom element definition does not finish until the matching
-template is available.
+work, but custom element registration completes only after the matching template
+is available.
 
 ```html
 <f-template name="user-card">
@@ -434,7 +434,7 @@ template is available.
 ```ts
 class UserCard extends FASTElement {}
 
-await UserCard.define({
+UserCard.define({
     name: "user-card",
     template: declarativeTemplate(),
 });