@microsoft/fast-element 2.10.4 → 3.0.0-rc.1

package/MIGRATION.md

@@ -0,0 +1,387 @@
+# Migrating from previous versions
+
+## FASTGlobal version tracking (v2 → v3)
+
+### Removed API
+
+| Removed | Replacement |
+|---|---|
+| `FAST.versions` | No replacement. Multiple FAST versions on the same page are unsupported in v3. |
+
+### Removed configuration
+
+| Removed | Replacement |
+|---|---|
+| `fast-kernel="share"` / `fast-kernel="share-v2"` / `fast-kernel="isolate"` | No replacement. FAST now uses a single shared kernel contract, and multiple FAST versions on the same page are unsupported. |
+
+### Migration steps
+
+1. Remove any runtime checks that read `FAST.versions`.
+2. Fix duplicate FAST installs in your bundler or dependency graph instead of relying on version tracking at runtime.
+3. Remove any `fast-kernel` script attributes. They no longer affect FAST initialization.
+
+## Native `globalThis` requirement (v2 → v3)
+
+### Changed behavior
+
+- **Native `globalThis` required**: `@microsoft/fast-element` no longer installs
+  a `globalThis` polyfill as a side effect. The package only keeps the
+  `requestIdleCallback` / `cancelIdleCallback` fallback for environments that
+  still lack those APIs.
+
+### Migration steps
+
+1. Verify that the browsers and JS runtimes you support provide native
+   `globalThis`.
+2. If you still target an older runtime without `globalThis`, load that
+   polyfill before importing `@microsoft/fast-element`.
+
+## Declarative HTML moved into fast-element (v3)
+
+Declarative HTML APIs now ship from `@microsoft/fast-element` instead of the
+removed `@microsoft/fast-html` package.
+
+### Import changes
+
+| Before | After |
+|---|---|
+| `@microsoft/fast-html` | `@microsoft/fast-element` |
+| `@microsoft/fast-html/utilities.js` | `@microsoft/fast-element` |
+
+Core FAST Element helpers are available from the root package export:
+
+| API | Import path |
+|---|---|
+| `Updates` | `@microsoft/fast-element` |
+| `Observable`, `observable` | `@microsoft/fast-element` |
+| `attr`, `AttributeDefinition`, converters, `ValueConverter` | `@microsoft/fast-element` |
+| `Binding`, `oneWay`, `oneTime`, `listener` | `@microsoft/fast-element` |
+| `DOM`, `DOMAspect`, `DOMPolicy` | `@microsoft/fast-element` |
+| `Schema`, `schemaRegistry`, schema types | `@microsoft/fast-element` |
+| `css` | `@microsoft/fast-element` |
+| `html`, `ViewTemplate`, `HTMLView` | `@microsoft/fast-element` |
+| `Compiler`, `HTMLDirective`, `htmlDirective`, templating/view types | `@microsoft/fast-element` |
+| `render`, `RenderBehavior`, `RenderDirective` | `@microsoft/fast-element` |
+| `enableHydration`, `HydrationTracker`, hydration types | `@microsoft/fast-element/hydration.js` |
+| `ArrayObserver` | `@microsoft/fast-element` |
+| `volatile` | `@microsoft/fast-element` |
+| `children` | `@microsoft/fast-element` |
+| `elements`, `NodeObservationDirective` | `@microsoft/fast-element` |
+| `ref` | `@microsoft/fast-element` |
+| `slotted` | `@microsoft/fast-element` |
+| `when` | `@microsoft/fast-element` |
+| `repeat` | `@microsoft/fast-element` |
+
+### Migration steps
+
+1. Update declarative runtime imports to
+   `@microsoft/fast-element/declarative.js`.
+2. Update declarative utility imports such as `deepMerge` to
+   `@microsoft/fast-element/declarative-utilities.js`.
+3. Keep importing FAST Element APIs such as `FASTElement`, `FAST`,
+   `ElementController`, definition/controller types, `attr`, `Schema`, and
+   `observable` from `@microsoft/fast-element`.
+4. Call `enableHydration()` from `@microsoft/fast-element/hydration.js` when
+   prerendered content should be hydrated.
+
+## `TemplateOptions` removal (v3)
+
+### Removed APIs
+
+| Removed | Replacement |
+|---|---|
+| `TemplateOptions` | No replacement |
+| `PartialFASTElementDefinition.templateOptions` | No replacement |
+| `FASTElementDefinition.templateOptions` | No replacement |
+
+### Changed behavior
+
+- `FASTElement.define()` no longer uses `templateOptions` to delay platform
+  definition or connection.
+- Elements can still be defined before a template is attached; a later
+  `FASTElementDefinition.template` update notifies connected elements so they
+  can render or hydrate with the new template.
+
+### Migration steps
+
+1. Remove `templateOptions` from element definitions.
+2. Continue calling `define({ name })` when a definition needs to exist before
+   its template is attached.
+3. If a template is supplied later, assign `FASTElementDefinition.template` (or
+   use the declarative runtime that does so for you).
+
+
+## Declarative TemplateElement API removal (v3)
+
+### Removed APIs
+
+| Removed | Replacement |
+|---|---|
+| `TemplateElement` public export | `declarativeTemplate()` on each FAST element definition |
+| `TemplateElement.define({ name: "f-template" })` | No manual definition; `declarativeTemplate()` defines FAST's internal `<f-template>` publisher in the target registry |
+| `TemplateElement.config(callbacks)` / `HydrationLifecycleCallbacks` | Per-element callbacks via `declarativeTemplate(callbacks)` and global callbacks via `enableHydration(options)` |
+| `TemplateElement.options(...)`, `ElementOptions`, `ElementOptionsDictionary` | Define extensions: `attributeMap(...)` and `observerMap(...)` passed as the second argument to `define()` |
+| `AttributeMap` / `ObserverMap` exports from the old declarative public surface | `attributeMap()` / `observerMap()` extension helpers and their config types |
+
+### Migration steps
+
+1. Replace manual `<f-template>` registration with `template: declarativeTemplate()`:
+
+   ```typescript
+   // Before
+   import { TemplateElement } from "@microsoft/fast-element";
+   TemplateElement.define({ name: "f-template" });
+
+   MyElement.define({ name: "my-element" });
+
+   // After
+   import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+
+   MyElement.define({
+       name: "my-element",
+       template: declarativeTemplate(),
+   });
+   ```
+
+2. Replace `TemplateElement.options()` with definition extensions:
+
+   ```typescript
+   import { attributeMap } from "@microsoft/fast-element/attribute-map.js";
+   import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+   import { observerMap } from "@microsoft/fast-element/observer-map.js";
+
+   MyElement.define(
+       {
+           name: "my-element",
+           template: declarativeTemplate(),
+       },
+       [attributeMap(), observerMap()],
+   );
+   ```
+
+   `attributeMap()` is imported from
+   `@microsoft/fast-element/attribute-map.js` and `observerMap()` from
+   `@microsoft/fast-element/observer-map.js` for declarative templates,
+   manually supplied schemas, or both. `FASTElementDefinition.schema` is optional;
+   `declarativeTemplate()` assigns it automatically, and `observerMap()` can
+   take a manual schema with `observerMap({ schema })`.
+
+3. Replace `TemplateElement.config()` with `declarativeTemplate(callbacks)` for
+   per-element callbacks and `enableHydration(options)` for global hydration
+   callbacks. Hydration is not installed by `declarative.js`; call
+   `enableHydration()` before elements connect when SSR content should hydrate.
+
+## Debug entrypoint explicit enablement (v3)
+
+### Import changes
+
+| Before | After |
+|---|---|
+| `import "@microsoft/fast-element";` | `import { enableDebug } from "@microsoft/fast-element/debug.js"; enableDebug();` |
+
+### Migration steps
+
+1. Replace setup-only `debug.js` imports with an explicit `enableDebug()` call.
+2. Keep using the root package `development` export or debug rollup bundle when
+   you want debug behavior enabled automatically.
+
+## Declarative event handler `e` removal (v3)
+
+### Removed behavior
+
+| Removed | Replacement |
+|---|---|
+| Bare `e` event arguments in declarative event handlers | `$e` |
+| `TemplateParser.hasDeprecatedEventSyntax` | No replacement |
+
+Only `$e` and `$c` are reserved event handler arguments in declarative
+templates. Bare `e` now resolves like any other binding path on the current
+data source.
+
+### Migration steps
+
+1. Replace declarative event bindings such as
+   `@click="{handleClick(e)}"` with `@click="{handleClick($e)}"`.
+2. Remove any `TemplateParser.hasDeprecatedEventSyntax` checks or warnings from
+   custom tooling.
+
+## Prerendered Content Optimization (v2 → v3)
+
+### Removed exports
+
+| Export | Replacement |
+|---|---|
+| `HydratableElementController` | `ElementController` (prerendered path built in) |
+| `HydrationControllerCallbacks` | `ElementHydrationCallbacks` via `ElementController.configHydration()` |
+| `needsHydrationAttribute` | `ElementController.isPrerendered` |
+| `deferHydrationAttribute` | Template-pending guard in `ElementController.connect()` |
+
+### Removed side-effect imports
+
+| Import | Replacement |
+|---|---|
+| `@microsoft/fast-element/install-hydration.js` | No replacement needed — prerendered path is built into `ElementController` |
+
+Use `enableHydration()` from `@microsoft/fast-element/hydration.js` when SSR
+content should hydrate. The declarative entrypoint no longer installs hydration
+automatically.
+
+### Changed behavior
+
+- **`attributeChangedCallback` during upgrade**: When `isPrerendered` is true and the element has not yet connected, attribute change callbacks are suppressed. After connection, all attribute changes are processed normally.
+- **Declarative template resolution**: `declarativeTemplate()` waits for the
+  matching `<f-template>` before `define()` completes, so connected elements
+  hydrate with a concrete template. No `defer-hydration` attribute is needed.
+- **Binding evaluation with existing shadow root**: When an existing shadow root is detected, `attribute` and `booleanAttribute` bindings skip their initial DOM update. All other binding types (event, content, property, tokenList) run normally.
+
+### New APIs
+
+- **`ElementController.isPrerendered`** (`Promise<boolean>`): Resolves to `true` after prerendered content has been hydrated, or `false` when the component is client-side rendered. Component authors can await this to know when the element is fully interactive.
+- **`ViewController.isPrerendered`** (`Promise<boolean> | undefined`): Available to custom directives. Resolves to `true` when the view's content was prerendered, `false` otherwise.
+
+### Migration steps
+
+1. Remove `HydratableElementController.install()` calls.
+2. Remove `import "@microsoft/fast-element/install-hydration.js"` side-effect imports.
+3. Replace `element.$fastController instanceof HydratableElementController` checks with `await element.$fastController.isPrerendered`.
+4. Remove `defer-hydration` and `needs-hydration` attributes from server-rendered markup.
+
+## Hydration Marker Format (v3)
+
+### Changed format
+
+The hydration markers embedded in SSR output have been simplified from verbose, index-embedded comment markers to compact, data-free sequential markers.
+
+#### Comment markers
+
+| Marker type | Old format | New format |
+|---|---|---|
+| Content binding start | `<!-- fe-b$$start$$<index>$$<scopeId>$$fe-b -->` | `<!--fe:b-->` |
+| Content binding end | `<!-- fe-b$$end$$<index>$$<scopeId>$$fe-b -->` | `<!--fe:/b-->` |
+| Repeat item start | `<!-- fe-repeat$$start$$<itemIndex>$$fe-repeat -->` | `<!--fe:r-->` |
+| Repeat item end | `<!-- fe-repeat$$end$$<itemIndex>$$fe-repeat -->` | `<!--fe:/r-->` |
+| Element boundary start | `<!-- fe-eb$$start$$<elementId>$$fe-eb -->` | `<!--fe:e-->` |
+| Element boundary end | `<!-- fe-eb$$end$$<elementId>$$fe-eb -->` | `<!--fe:/e-->` |
+
+#### Attribute binding markers
+
+| Old format | New format |
+|---|---|
+| `data-fe-b="0 1 2"` (space-separated indices) | `data-fe="N"` (binding count) |
+| `data-fe-b-0` (enumerated, one per factory) | `data-fe="N"` |
+| `data-fe-c-0-3` (compact, start index + count) | `data-fe="N"` |
+
+### Removed APIs
+
+| Export | Replacement |
+|---|---|
+| `HydrationMarkup.contentBindingStartMarker(index, scopeId)` | `HydrationMarkup.contentBindingStartMarker()` |
+| `HydrationMarkup.contentBindingEndMarker(index, scopeId)` | `HydrationMarkup.contentBindingEndMarker()` |
+| `HydrationMarkup.isContentBindingStartMarker(data)` | `HydrationMarkup.isContentBindingStartMarker(data)` (unchanged signature, new implementation) |
+| `HydrationMarkup.isContentBindingEndMarker(data)` | `HydrationMarkup.isContentBindingEndMarker(data)` (unchanged signature, new implementation) |
+| `HydrationMarkup.parseAttributeBinding(element)` | `HydrationMarkup.parseAttributeBindingCount(element)` |
+| `HydrationMarkup.parseRepeatStartMarker(data)` | `HydrationMarkup.isRepeatViewStartMarker(data)` |
+| `HydrationMarkup.parseRepeatEndMarker(data)` | `HydrationMarkup.isRepeatViewEndMarker(data)` |
+| `HydrationMarkup.parseElementBoundaryStartMarker(content)` | `HydrationMarkup.isElementBoundaryStartMarker(node)` |
+| `HydrationMarkup.parseElementBoundaryEndMarker(content)` | `HydrationMarkup.isElementBoundaryEndMarker(node)` |
+
+### Impact
+
+This is a **breaking change** for SSR output format. Any system that produces or parses hydration markers must be updated to use the new format. The `@microsoft/fast-build` Rust crate and WASM binary have been updated accordingly.
+
+- Marker parsing uses string equality checks (`data === "fe:b"`) instead of regex
+- Start/end pairing uses balanced depth counting instead of embedded IDs
+- The hydration walker uses a sequential factory pointer instead of index-based lookup
+- SSR and client versions must match — mixing old SSR output with new client code (or vice versa) will fail
+
+## Async define/compose/register API (v3)
+
+### Removed APIs
+
+| Removed | Replacement |
+|---|---|
+| `FASTElement.defineAsync()` | `FASTElement.define()` (now returns `Promise<TType>`) |
+| `FASTElementDefinition.composeAsync()` | `FASTElementDefinition.compose()` (now returns `Promise<FASTElementDefinition>`) |
+| `FASTElementDefinition.registerAsync()` | `FASTElementDefinition.register()` (same `Promise<Function>` return type) |
+
+### Changed behavior
+
+- **`FASTElement.define()`** now returns `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.
+- **`FASTElement.compose()`** now returns `Promise<FASTElementDefinition>`. The Promise always resolves immediately.
+- **`FASTElementDefinition.compose()`** now returns `Promise<FASTElementDefinition>`. The Promise always resolves immediately.
+- **`@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.
+
+### Migration steps
+
+1. Replace `defineAsync()` calls with `define()`:
+
+   ```typescript
+    // Before
+    MyElement.defineAsync({
+        name: "my-element",
+        templateOptions: "defer-and-hydrate",
+    });
+
+    // After
+    await MyElement.define({
+        name: "my-element",
+        template: declarativeTemplate(),
+    });
+   ```
+
+2. Replace `composeAsync()` calls with `compose()` and add `await`:
+
+   ```typescript
+   // Before
+   const def = await FASTElementDefinition.composeAsync(MyElement, name);
+
+   // After
+   const def = await FASTElementDefinition.compose(MyElement, name);
+   ```
+
+3. Replace `registerAsync()` calls with `register()`:
+
+   ```typescript
+   // Before
+   const el = await FASTElementDefinition.registerAsync(name);
+
+   // After
+   const el = await FASTElementDefinition.register(name);
+   ```
+
+4. Add `await` to `compose()` calls that chain `.define()`:
+
+   ```typescript
+    // Before
+    FASTElementDefinition.compose(MyElement, options).define();
+
+    // After
+    (await FASTElementDefinition.compose(MyElement, options)).define();
+   ```
+
+## Dynamic stylesheet behaviors (v3)
+
+### Removed API
+
+| Removed | Replacement |
+|---|---|
+| `ElementStyles.withBehaviors()` | Move the runtime condition into the element and call `this.$fastController.addStyles()` / `this.$fastController.removeStyles()` directly. |
+| `ElementStyles.behaviors` | Move any runtime behavior out of the stylesheet and into the element or controller lifecycle. |
+| CSS bindings in `css` (for example ``css`color: ${x => x.color}```) | Move the dynamic value into the element and update classes, attributes, or inline styles from element code. |
+| `CSSDirective.createCSS(add)` | Update directives to implement `createCSS()` and return only static CSS content. |
+
+### Changed behavior
+
+- `css` and `css.partial()` no longer compose `HostBehavior`s.
+- `css` no longer accepts function or `Binding` interpolations.
+- `ElementStyles` is now a fully static style container.
+
+### Migration steps
+
+1. Keep the conditional `ElementStyles` in a separate `css` value.
+2. Move the external listener or condition (for example `matchMedia()` or an app event subscription) into the element lifecycle.
+3. Call `this.$fastController.addStyles(styles)` when the condition is active and `this.$fastController.removeStyles(styles)` when it is inactive or during cleanup.
+4. If you previously interpolated bindings or behavior-producing directives into `css`, replace them with element state and standard DOM or controller updates.

package/README.md

@@ -51,4 +51,211 @@ For simplicity, examples throughout the documentation will assume the library ha
 
 :::tip
 Looking for a quick guide on building components?  Check out [our Cheat Sheet](../resources/cheat-sheet.md#building-components).
-:::
+:::
+
+## Browser Requirements
+
+FAST Element v3 assumes a modern runtime with native `globalThis`. The `FAST`
+object is now a module-scoped export (not on `globalThis`). If you need to
+support an environment without `globalThis`, load that polyfill before
+importing `@microsoft/fast-element`.
+
+## Debug entrypoint
+
+`@microsoft/fast-element/debug.js` exports `enableDebug()` instead of configuring
+FAST at import time. The development root export and debug rollup bundle still
+enable debug behavior automatically.
+
+```ts
+import { enableDebug } from "@microsoft/fast-element/debug.js";
+
+enableDebug();
+```
+
+## Export Sizes
+
+Bundle sizes for each tree-shakeable export are tracked in [`SIZES.md`](./SIZES.md) and regenerated on every build. See the [Export Sizes](https://www.fast.design/docs/3.x/resources/export-sizes/) documentation page for the latest numbers.
+
+## Root Imports and Path Exports
+
+The root `@microsoft/fast-element` entrypoint exports the FAST Element
+implementation APIs, including the element base class, kernel, controller,
+definition APIs, template APIs, binding helpers, directives, styles, and schema
+helpers. Declarative, hydration, context, and dependency injection APIs are
+available from their focused path exports.
+
+Focused package path exports remain available for consumers that want to import
+a narrower entrypoint directly. The website's
+[Path Exports](https://www.fast.design/docs/3.x/advanced/path-exports/) page is
+generated from `package.json` and lists each supported path.
+
+## Dynamic Style Application
+
+Import `css`, `CSSTemplateTag`, `CSSValue`, and style APIs such as
+`ElementStyles`, `CSSDirective`, `cssDirective`, `ComposableStyles`,
+`HostBehavior`, `HostController`, `StyleStrategy`, and `StyleTarget` from
+`@microsoft/fast-element`:
+
+```ts
+import { ElementStyles, css } from "@microsoft/fast-element";
+```
+
+When runtime state or external signals need to add or remove styles, create the
+`ElementStyles` with `css` and toggle it through
+`this.$fastController.addStyles()` / `this.$fastController.removeStyles()` from
+the element lifecycle or change handlers.
+
+`css` templates remain static style definitions. Runtime CSS bindings and
+behavior-producing CSS directives are no longer supported; keep the condition on
+the element and toggle a separate `ElementStyles` instance through the
+controller when styles need to change.
+
+## Declarative HTML
+
+FAST Element publishes its declarative HTML runtime from
+`@microsoft/fast-element/declarative.js`. This entrypoint exports the
+functional APIs for declarative templates: `declarativeTemplate()`,
+`TemplateParser`, and related configuration types. `attributeMap()` and
+`observerMap()` are available from their own focused path exports. The
+declarative runtime is pure at import time; declarative APIs lazily install only
+declarative debug messages. Hydration is separate and remains opt-in through
+`enableHydration()` from `@microsoft/fast-element/hydration.js`.
+
+```ts
+import { FASTElement } from "@microsoft/fast-element";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+
+class MyElement extends FASTElement {}
+
+MyElement.define({
+    name: "my-element",
+    template: declarativeTemplate(),
+});
+```
+
+`declarativeTemplate()` automatically defines FAST's internal native
+`<f-template>` publisher in the relevant registry, resolves the matching
+`<f-template name="my-element">`, and keeps the definition template concrete
+before `define()` resolves. Consumers should not import or define the
+`<f-template>` implementation directly.
+
+Declarative schema behavior is enabled with define extensions:
+
+```ts
+import { attributeMap } from "@microsoft/fast-element/attribute-map.js";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+import { observerMap } from "@microsoft/fast-element/observer-map.js";
+
+MyElement.define(
+    {
+        name: "my-element",
+        template: declarativeTemplate(),
+    },
+    [attributeMap(), observerMap()],
+);
+```
+
+`attributeMap()` creates `@attr`-style accessors for leaf bindings, and
+`observerMap()` creates deep observable accessors for discovered root
+properties. Declarative templates assign `definition.schema` during template
+resolution so these extensions always have schema data when used with
+`declarativeTemplate()`. For non-declarative/manual schema use, import `Schema`
+from `@microsoft/fast-element` and pass it on the element definition;
+`observerMap()` can also receive
+`observerMap({ schema })` directly. When both extensions are present, attribute
+mapping runs before observer mapping.
+
+Declarative utilities such as `deepMerge` are available from
+`@microsoft/fast-element/declarative-utilities.js`. See
+[`DECLARATIVE_HTML.md`](./DECLARATIVE_HTML.md) for declarative implementation
+details and the
+[Declarative HTML docs](https://fast.design/docs/3.x/declarative-templates/overview/)
+for guides on writing f-templates, defining declarative elements, and
+server-side rendering. Declarative event bindings use `$e` for the DOM event
+object and `$c` for the execution context.
+
+## Prerendered Content Optimization
+
+Hydration of prerendered content is **opt-in**. Call `enableHydration()` from `@microsoft/fast-element/hydration.js` before any FAST elements connect to activate the hydration path:
+
+```typescript
+import { enableHydration } from "@microsoft/fast-element/hydration.js";
+
+enableHydration({
+    hydrationComplete() {
+        console.log("hydration complete");
+    },
+});
+```
+
+When hydration is enabled and a FAST element connects with an existing shadow root (from server-side rendering or declarative shadow DOM), `ElementController` detects this and hydrates instead of re-rendering. Two properties on the controller let you inspect the result:
+
+- **`isPrerendered: Promise<boolean>`** — resolves `true` when the element had a declarative shadow root (DSD) at connect time, regardless of whether hydration ran.
+- **`isHydrated: Promise<boolean>`** — resolves `true` only when hydration actually ran successfully.
+
+This enables several optimizations:
+
+- **Hydration instead of re-render**: The template uses `hydrate()` to map existing DOM nodes to binding targets rather than cloning new DOM.
+- **Declarative template resolution**: `declarativeTemplate()` waits for the
+  matching `<f-template>` before `define()` completes, so connected elements
+  hydrate with a concrete template.
+- **Attribute skip**: `onAttributeChangedCallback()` skips processing during initial upgrade when the element is prerendered, since server-rendered attribute values are already correct.
+- **Binding skip**: `HTMLBindingDirective.bind()` skips `updateTarget` for `attribute` and `booleanAttribute` aspect types when the view is prerendered.
+
+Per-element lifecycle callbacks can be passed directly to `declarativeTemplate()`:
+
+```typescript
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+
+MyComponent.define({
+    name: "my-component",
+    template: declarativeTemplate({
+        elementWillHydrate(source) {
+            console.log(`${source.localName} will hydrate`);
+        },
+        elementDidHydrate(source) {
+            console.log(`${source.localName} hydrated`);
+        },
+    }),
+});
+```
+
+Component authors can await both promises to distinguish prerendered content from successful hydration:
+
+```typescript
+const controller = this.$fastController;
+const prerendered = await controller.isPrerendered;
+const hydrated = await controller.isHydrated;
+
+if (prerendered && !hydrated) {
+    // Had DSD but hydration wasn't enabled — client-side rendered
+}
+```
+
+Custom directives can also await `controller.isPrerendered` and `controller.isHydrated` (both `Promise<boolean>` on the `ViewController` interface) to determine how the view's content was rendered.
+
+## Define Extensions
+
+`FASTElement.define()` accepts an optional second argument — an array of extension callbacks that are invoked with the resolved element definition before the element is registered with the platform. This enables a plugin pattern where reusable behaviors can hook into element registration.
+
+```typescript
+import { FASTElement, type FASTElementExtension } from "@microsoft/fast-element";
+
+function logger(): FASTElementExtension {
+    return definition => {
+        console.log(`Defining element: ${definition.name}`);
+    };
+}
+
+class MyComponent extends FASTElement {
+    // component code
+}
+
+// Method style
+MyComponent.define({ name: "my-component", template, styles }, [logger()]);
+
+// Static style
+FASTElement.define(MyComponent, { name: "my-component" }, [logger()]);
+```
+
+Each extension receives the full `FASTElementDefinition`, which includes the resolved element name, type, template, styles, and attribute metadata. Extensions run before `customElements.define()`, so any setup they perform is available when existing DOM elements are upgraded.

package/SIZES.md

@@ -0,0 +1,25 @@
+# Export Sizes
+
+Bundle sizes for `@microsoft/fast-element` exports.
+
+| Export | Minified | Gzip | Brotli |
+|--------|----------|------|--------|
+| CDN Rollup Bundle | 76.36 KB | 22.91 KB | 20.32 KB |
+| FASTElement (@microsoft/fast-element/fast-element.js) | 23.73 KB | 7.38 KB | 6.63 KB |
+| Updates (@microsoft/fast-element/updates.js) | 473 B | 335 B | 288 B |
+| Observable (@microsoft/fast-element/observable.js) | 6.70 KB | 2.50 KB | 2.22 KB |
+| observable (@microsoft/fast-element/observable.js) | 6.74 KB | 2.51 KB | 2.23 KB |
+| attr (@microsoft/fast-element/attr.js) | 477 B | 288 B | 244 B |
+| children (@microsoft/fast-element/children.js) | 4.81 KB | 1.86 KB | 1.64 KB |
+| ref (@microsoft/fast-element/ref.js) | 3.78 KB | 1.52 KB | 1.34 KB |
+| slotted (@microsoft/fast-element/slotted.js) | 4.60 KB | 1.79 KB | 1.58 KB |
+| volatile (@microsoft/fast-element/volatile.js) | 6.79 KB | 2.53 KB | 2.25 KB |
+| when (@microsoft/fast-element/when.js) | 1.82 KB | 712 B | 565 B |
+| html (@microsoft/fast-element/html.js) | 25.92 KB | 8.50 KB | 7.61 KB |
+| repeat (@microsoft/fast-element/repeat.js) | 29.57 KB | 9.41 KB | 8.47 KB |
+| css (@microsoft/fast-element/css.js) | 2.43 KB | 1.00 KB | 911 B |
+| enableHydration (@microsoft/fast-element/hydration.js) | 43.27 KB | 13.22 KB | 11.89 KB |
+| declarativeTemplate (@microsoft/fast-element/declarative.js) | 58.77 KB | 18.46 KB | 16.46 KB |
+| ArrayObserver (@microsoft/fast-element/array-observer.js) | 12.51 KB | 4.45 KB | 4.01 KB |
+| observerMap (@microsoft/fast-element/observer-map.js) | 20.41 KB | 7.26 KB | 6.52 KB |
+| attributeMap (@microsoft/fast-element/attribute-map.js) | 15.78 KB | 5.59 KB | 5.04 KB |

package/api-extractor.arrays.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+    "extends": "../../api-extractor.json",
+    "mainEntryPointFilePath": "./dist/dts/arrays.d.ts",
+    "dtsRollup": { "enabled": false },
+    "apiReport": {
+        "enabled": true,
+        "reportFolder": "<projectFolder>/docs/arrays",
+        "reportFileName": "api-report"
+    },
+    "docModel": {
+        "enabled": true,
+        "apiJsonFilePath": "<projectFolder>/dist/arrays/arrays.api.json"
+    }
+}

package/api-extractor.context.json

@@ -2,6 +2,7 @@
     "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
     "extends": "../../api-extractor.json",
     "mainEntryPointFilePath": "./dist/dts/context.d.ts",
+    "dtsRollup": { "enabled": false },
     "apiReport": {
         "enabled": true,
         "reportFolder": "<projectFolder>/docs/context",

package/api-extractor.declarative.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+    "extends": "../../api-extractor.json",
+    "mainEntryPointFilePath": "./dist/dts/declarative/index.d.ts",
+    "dtsRollup": { "enabled": false },
+    "apiReport": {
+        "enabled": true,
+        "reportFolder": "<projectFolder>/docs/declarative",
+        "reportFileName": "api-report"
+    },
+    "docModel": {
+        "enabled": true,
+        "apiJsonFilePath": "<projectFolder>/dist/declarative/declarative.api.json"
+    }
+}

package/api-extractor.di.json

@@ -2,6 +2,7 @@
     "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
     "extends": "../../api-extractor.json",
     "mainEntryPointFilePath": "./dist/dts/di/di.d.ts",
+    "dtsRollup": { "enabled": false },
     "apiReport": {
         "enabled": true,
         "reportFolder": "<projectFolder>/docs/di",