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

package/CHANGELOG.md

@@ -1,9 +1,59 @@
 # Change Log - @microsoft/fast-element
 
-<!-- This log was last generated on Fri, 17 Apr 2026 00:26:37 GMT and should not be manually modified. -->
+<!-- This log was last generated on Fri, 19 Jun 2026 22:15:55 GMT and should not be manually modified. -->
 
 <!-- Start content -->
 
+## 3.0.0-rc.2
+
+Fri, 19 Jun 2026 22:15:55 GMT
+
+### Changes
+
+- Filter late attribute MutationObserver records. (7559015+janechu@users.noreply.github.com)
+- fix: align @attr({ mode: 'boolean' }) and booleanConverter with native HTML boolean attribute semantics (7559015+janechu@users.noreply.github.com)
+- feat: expose declarative HTML syntax constants from declarative utilities (7559015+janechu@users.noreply.github.com)
+- fix: restore CaptureType generic type capture for template directives (7559015+janechu@users.noreply.github.com)
+- feat: change default attribute-name-strategy from none to camelCase (7559015+janechu@users.noreply.github.com)
+- feat: auto-escape `{` and `}` inside `<code>` elements so binding-like syntax in code samples renders as literal text (mirrors webui-press and the server-side `escape_code_sample_elements` pass in `@microsoft/fast-build`, which additionally handles `<f-when>`/`<f-repeat>` directive tags) (7559015+janechu@users.noreply.github.com)
+- Improve hydration mismatch behaviour: render() falls back to client rendering when SSR view boundaries are empty, repeat() reconciles SSR/client item-count mismatches by creating missing client views or removing extra SSR ranges, and unrecoverable mismatches throw via a pluggable HydrationDiagnostic. Opt in to the rich 'Expected / Received' format with the SSR HTML snippet and structured expected/received fields on HydrationBindingError / HydrationTargetElementError by passing enableHydration({ debugger: hydrationDebugger() }) (hydrationDebugger is exported from '@microsoft/fast-element/hydration.js'). (7559015+janechu@users.noreply.github.com)
+- Add hydration configuration for streamed Declarative Shadow DOM. (7559015+janechu@users.noreply.github.com)
+- Avoid mutating render template bindings (7559015+janechu@users.noreply.github.com)
+- feat: propagate shadowroot attributes from f-template to declarative shadow DOM template (7559015+janechu@users.noreply.github.com)
+- Preserve view context when rebinding the same source. (7559015+janechu@users.noreply.github.com)
+- feat: warn when duplicate render instruction registrations replace existing entries (7559015+janechu@users.noreply.github.com)
+- Add a registry path export for FAST element definition lookups. (7559015+janechu@users.noreply.github.com)
+- Bump @microsoft/fast-build to v0.8.0-fast-element-v3-rc-20260615
+
+## 3.0.0-rc.1
+
+Tue, 28 Apr 2026 04:42:02 GMT
+
+### Major changes
+
+- remove FASTGlobal version tracking (7559015+janechu@users.noreply.github.com)
+- Remove hydration view template side effect and unused export paths (7559015+janechu@users.noreply.github.com)
+- Move optional helpers to dedicated flat fast-element subpath exports such as @microsoft/fast-element/children.js, @microsoft/fast-element/repeat.js, @microsoft/fast-element/two-way.js, @microsoft/fast-element/signal.js, @microsoft/fast-element/attribute-map.js, and @microsoft/fast-element/observer-map.js while keeping controller and definition internals on the root entrypoint. (7559015+janechu@users.noreply.github.com)
+- Remove the public declarative TemplateElement configuration APIs and make declarative templates use an internal native f-template publisher with explicit hydration opt-in. (7559015+janechu@users.noreply.github.com)
+- Replace HydratableElementController with automatic prerendered content optimization. When a component connects with an existing shadow root, bindings skip attribute/booleanAttribute DOM updates during initial render while still setting up event listeners, observers, and dependency tracking. Added isPrerendered flag to ElementController and ViewController. Added template-pending guard for defineAsync flow. (7559015+janechu@users.noreply.github.com)
+- Move declarative HTML APIs into @microsoft/fast-element/declarative.js, expose schema map helpers from extension subpaths, and remove the @microsoft/fast-html package. (7559015+janechu@users.noreply.github.com)
+- Remove ElementStyles.withBehaviors, CSS style behaviors, and CSS bindings in fast-element. (7559015+janechu@users.noreply.github.com)
+- Remove TemplateOptions from fast-element definitions and drop templateOptions-based connection/define waiting. (7559015+janechu@users.noreply.github.com)
+- Simplify hydration markers to data-free sequential format (fe:b, fe:/b, fe:r, fe:/r, fe:e, fe:/e). Replace regex parsing with string equality checks. Single data-fe attribute replaces three old formats. Breaking change: SSR output format changed. (7559015+janechu@users.noreply.github.com)
+- remove deprecated declarative event e support (7559015+janechu@users.noreply.github.com)
+- Make declarative runtime setup lazy and change @microsoft/fast-element/debug.js to require an explicit enableDebug() call. (7559015+janechu@users.noreply.github.com)
+- Remove defineAsync and composeAsync — define() and compose() now return Promises (7559015+janechu@users.noreply.github.com)
+- Remove the built-in globalThis polyfill; fast-element v3 now requires native globalThis (7559015+janechu@users.noreply.github.com)
+- fix: remove the fast-kernel multi-kernel modes. Breaking change: FAST no longer supports configuring isolated or version-scoped kernels via the script attribute. (7559015+janechu@users.noreply.github.com)
+
+### Minor changes
+
+- Add schema-driven attributeMap and observerMap extension subpaths, optional definition schema, and observerMap schema configuration. (7559015+janechu@users.noreply.github.com)
+- add declarativeTemplate for auto-resolving <f-template> markup (7559015+janechu@users.noreply.github.com)
+- Add extensions array argument to FASTElement.define() and FASTElementDefinition.define() (7559015+janechu@users.noreply.github.com)
+- feat: modularize hydration and expose lifecycle callbacks via enableHydration() and declarativeTemplate() (7559015+janechu@users.noreply.github.com)
+- add function-based template resolver sequencing (7559015+janechu@users.noreply.github.com)
+
 ## 2.10.4
 
 Fri, 17 Apr 2026 00:26:37 GMT

package/README.md

@@ -55,11 +55,17 @@ Looking for a quick guide on building components?  Check out [our Cheat Sheet](.
 
 ## 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
+FAST Element v3 assumes a client-side browser `Window` runtime with native
+`globalThis`, Custom Elements, DOM, Shadow DOM, and `requestAnimationFrame`.
+The `FAST` object is now a module-scoped export (not on `globalThis`). If you
+need to support an older browser without `globalThis`, load that polyfill before
 importing `@microsoft/fast-element`.
 
+The FAST Element client runtime is not intended to execute in workers,
+server-side JavaScript runtimes, or other non-window hosts. Use server-side
+rendering tools to produce HTML for the browser, and run FAST Element in the
+client window where custom elements connect, render, update, and hydrate.
+
 ## Debug entrypoint
 
 `@microsoft/fast-element/debug.js` exports `enableDebug()` instead of configuring
@@ -74,15 +80,17 @@ 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.
+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/2.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.
+helpers. The FAST element registry is also available from
+`@microsoft/fast-element/registry.js` for focused definition lookups.
+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
@@ -136,8 +144,10 @@ MyElement.define({
 `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.
+before `define()` resolves. If multiple matching `<f-template>` elements are
+connected, the first connected element supplies the template and later duplicates
+do not reassign it. Consumers should not import or define the `<f-template>`
+implementation directly.
 
 Declarative schema behavior is enabled with define extensions:
 
@@ -188,6 +198,18 @@ enableHydration({
 });
 ```
 
+By default, hydration handles the initial prerendered batch and then no-ops
+after `hydrationComplete` fires. If your app streams Declarative Shadow DOM
+after the initial batch, keep the hydration hook active:
+
+```typescript
+import { enableHydration, StopHydration } from "@microsoft/fast-element/hydration.js";
+
+enableHydration({
+    stopHydration: StopHydration.never,
+});
+```
+
 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.
@@ -202,6 +224,25 @@ This enables several optimizations:
 - **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.
 
+### Hydration Mismatch Diagnostics
+
+If a prerendered DOM diverges from the client template in a way FAST cannot
+reconcile (the `render()` empty-boundary and `repeat()` count-mismatch cases
+recover silently), `HydrationBindingError` or `HydrationTargetElementError` is
+thrown. By default the message is a single line pointing at the opt-in
+`hydrationDebugger()`. Install the debugger to get a rich
+"Expected … / Received …" report with the SSR HTML snippet and structured
+`expected` / `received` fields on the thrown error:
+
+```typescript
+import { enableHydration, hydrationDebugger } from "@microsoft/fast-element/hydration.js";
+
+enableHydration({ debugger: hydrationDebugger() });
+```
+
+The debugger module is tree-shaken out of production hydration bundles when
+not imported, so the rich diagnostic helpers only land in builds that opt in.
+
 Per-element lifecycle callbacks can be passed directly to `declarativeTemplate()`:
 
 ```typescript
@@ -236,7 +277,7 @@ Custom directives can also await `controller.isPrerendered` and `controller.isHy
 
 ## 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.
+The static `define()` method on a `FASTElement` subclass 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";
@@ -251,11 +292,6 @@ 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/dist/context/context.api.json

@@ -252,7 +252,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T>;\n    create<T_1 = unknown>(name: string, initialValue?: T_1 | undefined): "
+              "text": "<T>;\n    create<T = unknown>(name: string, initialValue?: T): "
             },
             {
               "kind": "Reference",
@@ -261,7 +261,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_1>;\n    setDefaultRequestStrategy(strategy: "
+              "text": "<T>;\n    setDefaultRequestStrategy(strategy: "
             },
             {
               "kind": "Reference",
@@ -270,7 +270,7 @@
             },
             {
               "kind": "Content",
-              "text": "): void;\n    get<T_2 extends "
+              "text": "): void;\n    get<T extends "
             },
             {
               "kind": "Reference",
@@ -288,7 +288,7 @@
             },
             {
               "kind": "Content",
-              "text": ", context: T_2): "
+              "text": ", context: T): "
             },
             {
               "kind": "Reference",
@@ -297,7 +297,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_2>;\n    request<T_3 extends "
+              "text": "<T>;\n    request<T extends "
             },
             {
               "kind": "Reference",
@@ -315,7 +315,7 @@
             },
             {
               "kind": "Content",
-              "text": ", context: T_3, callback: "
+              "text": ", context: T, callback: "
             },
             {
               "kind": "Reference",
@@ -333,7 +333,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_3>>, multiple?: boolean): void;\n    dispatch<T_4 extends "
+              "text": "<T>>, multiple?: boolean): void;\n    dispatch<T extends "
             },
             {
               "kind": "Reference",
@@ -351,7 +351,7 @@
             },
             {
               "kind": "Content",
-              "text": ", context: T_4, callback: "
+              "text": ", context: T, callback: "
             },
             {
               "kind": "Reference",
@@ -369,7 +369,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_4>>, multiple?: boolean): void;\n    provide<T_5 extends "
+              "text": "<T>>, multiple?: boolean): void;\n    provide<T extends "
             },
             {
               "kind": "Reference",
@@ -387,7 +387,7 @@
             },
             {
               "kind": "Content",
-              "text": ", context: T_5, value: "
+              "text": ", context: T, value: "
             },
             {
               "kind": "Reference",
@@ -396,7 +396,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_5>): void;\n    handle<T_6 extends "
+              "text": "<T>): void;\n    handle<T extends "
             },
             {
               "kind": "Reference",
@@ -423,7 +423,7 @@
             },
             {
               "kind": "Content",
-              "text": "<T_6>) => void, context?: T_6 | undefined): void;\n    defineProperty<T_7 extends "
+              "text": "<T>) => void, context?: T): void;\n    defineProperty<T extends "
             },
             {
               "kind": "Reference",
@@ -459,7 +459,7 @@
             },
             {
               "kind": "Content",
-              "text": ", propertyName: string, context: T_7): void;\n}>"
+              "text": ", propertyName: string, context: T): void;\n}>"
             }
           ],
           "fileUrlPath": "dist/dts/context.d.ts",