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

package/DESIGN.md

@@ -10,7 +10,7 @@ For deep dives into specific areas, see the linked detailed documents.
 
 1. [High-Level Overview](#high-level-overview)
 2. [Core Concepts](#core-concepts)
-   - [FAST Global](#fast-global)
+   - [FAST Object](#fast-object)
    - [FASTElement & ElementController](#fastelement--elementcontroller)
    - [Observables & Notifiers](#observables--notifiers)
    - [Bindings](#bindings)
@@ -42,35 +42,33 @@ For deep dives into specific areas, see the linked detailed documents.
 | Element authoring | `FASTElement` base class + `@customElement`, `@attr`, `@observable` decorators |
 | Reactive data binding | `Observable`, `ExpressionNotifier`, `oneWay`/`oneTime`/`listener` bindings |
 | Declarative templating | `html` tagged template literal → `ViewTemplate` → compiled `HTMLView` |
+| Declarative HTML runtime | `@microsoft/fast-element/declarative.js` → `declarativeTemplate()`, `TemplateParser`; `@microsoft/fast-element/schema.js` → `Schema` |
+| Schema-driven extensions | `@microsoft/fast-element/attribute-map.js` and `@microsoft/fast-element/observer-map.js` → map helpers usable with declarative or manually supplied schemas |
 | Async DOM updates | `Updates` queue (batched, `requestAnimationFrame`-aligned) |
 | Scoped styles | `css` tagged template literal → `ElementStyles` → `adoptedStylesheets` / `<style>` |
 | Dependency injection | `DI` container, `@inject`, `@singleton`, `@transient`, resolvers |
 | Context protocol | W3C community Context protocol (`Context.create`, `Context.for`) |
 | Reactive state helpers | `state()`, `watch()` (beta) |
 
-The library's kernel (the `FAST` global, the `Updates` queue, and the `Observable` system) is stored on `globalThis.FAST` and can be shared across multiple versions of the library loaded on the same page.
+The library's kernel is module-scoped rather than stored on `globalThis`: import `FAST` from `@microsoft/fast-element`, `Updates` from `@microsoft/fast-element`, and `Observable` from `@microsoft/fast-element`.
+
+The root entrypoint exports the FAST Element implementation APIs. Focused package
+path exports remain available when a consumer wants a narrower entrypoint.
 
 ---
 
 ## Core Concepts
 
-### FAST Global
+### FAST Object
 
 **File**: `src/platform.ts`, `src/interfaces.ts`
 
-`FAST` is a singleton object attached to `globalThis`. It provides:
+`FAST` is a module-scoped singleton exported from `@microsoft/fast-element`. It is **not** attached to `globalThis`. It provides:
 
-- `FAST.getById(id, initializer)` – shared kernel slot registry (used to share the update queue and observable system across FAST instances)
 - `FAST.warn(code, values)` / `FAST.error(code, values)` – structured diagnostic messages
-- `FAST.addMessages(dict)` – registers human-readable debug messages (imported by `src/debug.ts`)
-
-The `KernelServiceId` object controls which numeric/string keys are used for shared services. Three modes are supported via a `fast-kernel` attribute on the current `<script>` tag:
+- `FAST.addMessages(dict)` – registers human-readable debug messages used by `enableDebug()` and declarative runtime diagnostics
 
-| Mode | Behaviour |
-|---|---|
-| `share` | Share the kernel across any FAST version |
-| `share-v2` | Share only with other v2 instances |
-| *(default)* | Fully isolated instance with a random postfix |
+The previous `FAST.getById()` slot registry, `FASTGlobal` type, and `KernelServiceId` enum have been removed. Kernel services (update queue, observable system, etc.) are resolved through standard ES module imports rather than a shared global registry.
 
 ---
 
@@ -88,14 +86,40 @@ The `KernelServiceId` object controls which numeric/string keys are used for sha
 
 `ElementController` is the real workhorse. It:
 
-- Extends `PropertyChangeNotifier` so the element itself participates in the observable system.
+- Uses composition with an internal `_notifier` field (rather than extending `PropertyChangeNotifier`) and implements the `Notifier` interface directly, so the element still participates in the observable system.
 - Holds the element's `FASTElementDefinition` (name, template, styles, observed attributes).
 - Manages a `Stages` state machine: `disconnected → connecting → connected → disconnecting → disconnected`.
-- On `connect()`: restores pre-upgrade observable values, calls `connectedCallback` on all `HostBehavior`s, renders the template into the shadow root, and applies styles.
+- Exposes `isPrerendered: Promise<boolean>` which resolves to `true` when the element had a declarative shadow root (DSD) at connect time, regardless of whether hydration ran. Exposes `isHydrated: Promise<boolean>` which resolves to `true` only when hydration actually ran successfully. The `ViewController` interface also exposes both `isPrerendered` and `isHydrated` as `Promise<boolean>` for custom directives. Attribute-skip logic during the hydration bind uses an internal `_skipAttrUpdates` flag that is never exposed as a public boolean.
+- On `connect()`: restores pre-upgrade observable values, calls `connectedCallback` on all `HostBehavior`s, renders the current template into the shadow root when one is available, and applies styles.
+- Rendering is split into two modular paths. Hydration is pluggable: `enableHydration()` from `@microsoft/fast-element/hydration.js` installs a hook via `ElementController.installHydrationHook()`, keeping zero hydration imports in the core controller:
+  - **Prerendered**: The hydration hook (installed by `enableHydration()`) registers the element in the static hydration tracker, fires the definition's `elementWillHydrate` callback, swaps `onAttributeChangedCallback` to a no-op so the upgrade-time burst of callbacks is discarded, hydrates the existing DOM via `template.hydrate()`, fires `elementDidHydrate`, then restores the standard handler and removes the element from the tracker. The entire method is wrapped in `try/finally` to guarantee cleanup even if an error occurs during hydration. After this point, all future attribute changes flow through the real handler with zero overhead.
+  - **Client-side**: `renderClientSide()` clones the compiled fragment, binds, and appends to the host — the standard path with no prerender logic.
+- **Static hydration tracking**: Hydration is opt-in via `enableHydration()` from `@microsoft/fast-element/hydration.js`, which creates a `HydrationTracker` and installs a pluggable hydration hook on `ElementController` via `ElementController.installHydrationHook()`. Until this is called, `renderTemplate()` always uses the client-side path — even if the element has a pre-existing shadow root. `HydrationTracker` manages a `Set<HTMLElement>` of pending elements, fires global callbacks (`hydrationStarted`, `hydrationComplete`), and fires `hydrationComplete` via a debounced `setTimeout(0)` after the last element finishes binding — ensuring all async template batches settle first. Per-element hydration callbacks (`elementWillHydrate`, `elementDidHydrate`) are stored on the `FASTElementDefinition.lifecycleCallbacks` and fired directly by the hydration hook.
 - On `disconnect()`: calls `disconnectedCallback` on behaviors, unbinds the view.
+- `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()` and registered globally via `fastElementRegistry`.
+`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<InstanceType<TType>>` or a `FASTElementTemplateResolver<TType>` function that receives the composed definition and returns the concrete template (sync or async). `FASTElementDefinition.template` always stores the concrete `ElementViewTemplate<InstanceType<TType>>` after composition or resolver settlement. `FASTElement.define()` returns `Promise<TType>` — resolving immediately for complete definitions or definitions without an initial template, and resolving async 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()`. `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;
+```
+
+Extensions are typically produced by factory functions:
+
+```typescript
+function myPlugin() {
+    return (definition: FASTElementDefinition) => {
+        console.log(`Registering: ${definition.name}`);
+    };
+}
+
+MyComponent.define({ name: "my-component" }, [myPlugin()]);
+```
 
 ---
 
@@ -227,7 +251,7 @@ See [src/templating/TEMPLATE-BINDINGS.md](./src/templating/TEMPLATE-BINDINGS.md)
 
 **Exported as**: `Updates`
 
-`Updates` is a shared, batched task queue used to synchronise writes to the DOM. It is stored on the `FAST` global (under `KernelServiceId.updateQueue`) so multiple FAST instances on the same page share a single flush cycle.
+`Updates` is a shared, batched task queue used to synchronise writes to the DOM. It is resolved through standard ES module imports so multiple parts of the application share a single flush cycle.
 
 - `Updates.enqueue(callable)` – schedules a task for the next batch.
 - `Updates.process()` – forces immediate synchronous flush (useful in tests).
@@ -246,7 +270,19 @@ See [ARCHITECTURE_UPDATES.md](./ARCHITECTURE_UPDATES.md) for more detail.
 
 **Files**: `src/styles/css.ts`, `src/styles/element-styles.ts`, `src/styles/css-directive.ts`
 
-The `css` tag (analogous to `html`) builds `ElementStyles` objects. During `ElementController.connect()`, styles are applied to the element's shadow root either via `adoptedStylesheets` (preferred) or an appended `<style>` node, depending on platform support. Styles can also contain dynamic `CSSDirective`s (e.g., CSS custom property bindings) that register as `HostBehavior`s and connect/disconnect alongside the element.
+**Exported from**: `@microsoft/fast-element`
+
+The `css` tag, `ElementStyles`, `CSSDirective`, `cssDirective`,
+`ComposableStyles`, `HostBehavior`, `HostController`, `StyleStrategy`, and
+`StyleTarget` are imported from `@microsoft/fast-element`. The `css` tag
+(analogous to `html`) builds `ElementStyles` objects. During
+`ElementController.connect()`, styles are applied to the element's shadow root
+either via `adoptedStylesheets` (preferred) or an appended `<style>` node,
+depending on platform support. `CSSDirective`s can contribute additional static
+CSS during template composition, but runtime CSS bindings and style-attached
+`HostBehavior`s are not supported. Arbitrary runtime style toggling is handled
+through `ElementController.addStyles()` / `removeStyles()`; `ElementStyles`
+itself is a static container.
 
 ---
 
@@ -296,13 +332,52 @@ See `docs/di/api-report.api.md` for the full public API surface.
 
 ---
 
+### Declarative HTML
+
+**Files**: `src/declarative/index.ts`, `src/declarative/*`
+
+FAST Element also owns the declarative HTML runtime that previously lived in a
+separate package. `@microsoft/fast-element` exports the declarative runtime API:
+`declarativeTemplate()`, `TemplateParser`, `Schema`, `schemaRegistry`, and
+related parser/schema types. Map helpers are also exported from the root so they
+can be used with declarative templates or manually supplied schemas. The
+`<f-template>` element is an internal native `HTMLElement` publisher that
+`declarativeTemplate()` defines in the target registry; it is not part of the
+public API.
+
+The declarative runtime intentionally reuses the same FAST Element primitives as
+the imperative `html` API:
+
+- The internal `<f-template>` publisher parses HTML and returns concrete
+  `ViewTemplate` instances through the registry-aware declarative template
+  bridge.
+- `TemplateParser` lowers declarative syntax to the same `strings` / `values`
+  shape used by `ViewTemplate.create()`.
+- `attributeMap()` and `observerMap()` are `FASTElementExtension` factories
+  exported from `@microsoft/fast-element/attribute-map.js` and
+  `@microsoft/fast-element/observer-map.js`. With `declarativeTemplate()` they
+  register schema transforms on the element definition, and those transforms run
+  after parsing in deterministic order (`attributeMap()` before
+  `observerMap()`). Outside declarative templates, `attributeMap()` uses
+  `definition.schema`, while `observerMap()` can use either `definition.schema`
+  or `observerMap({ schema })`.
+
+The `src/declarative/index.ts` entrypoint is pure at module evaluation time. Running a
+declarative API lazily installs declarative debug messages only. Hydration hooks
+and hydratable `ViewTemplate` support are installed exclusively by
+`enableHydration()` from `@microsoft/fast-element/hydration.js`. See
+[`DECLARATIVE_DESIGN.md`](./DECLARATIVE_DESIGN.md) for the detailed
+architecture.
+
+---
+
 ## Data Flow Diagrams
 
 ### Module Load & Registration
 
 ```mermaid
 flowchart TD
-    A([Browser loads script]) --> B[FAST global created on globalThis]
+    A([Browser loads script]) --> B[FAST module initialises singleton]
     B --> C[FASTElement subclass executes FASTElement.compose]
     C --> D[Observable decorators register accessors on the prototype]
     C --> E[Attribute decorators push AttributeDefinition to the class]
@@ -320,13 +395,22 @@ flowchart TD
     EC --> ATTACH[Controller captures element + definition, sets $fastController]
 
     CONN[connectedCallback] --> STAGE[stage = connecting]
-    STAGE --> OBS[Restore pre-upgrade observable values]
+    STAGE --> PRERENDER{Existing shadow root\nfrom SSR/DSD?}
+    PRERENDER -->|yes| SETFLAG[isPrerendered = true\nisHydrated = pending]
+    PRERENDER -->|no| NORMAL[isPrerendered = false\nisHydrated = false]
+    SETFLAG --> OBS[Restore pre-upgrade observable values]
+    NORMAL --> OBS
     OBS --> BEHAV[Connect HostBehaviors]
-    BEHAV --> RENDER[renderTemplate → ViewTemplate.render → HTMLView.appendTo shadow root]
-    RENDER --> STYLES[Apply ElementStyles to shadow root]
+    BEHAV --> RENDER{isPrerendered AND\ntemplate is hydratable?}
+    RENDER -->|yes| HYDRATE[template.hydrate → HydrationView\nmaps existing DOM to binding targets\nisHydrated = true]
+    RENDER -->|no| CLONE[ViewTemplate.render → HTMLView.appendTo shadow root]
+    HYDRATE --> STYLES[Apply ElementStyles to shadow root]
+    CLONE --> STYLES
     STYLES --> DONE[stage = connected]
 
-    ATTR[attributeChangedCallback] --> ACD[AttributeDefinition.onAttributeChangedCallback]
+    ATTR[attributeChangedCallback] --> ATTRGUARD{isPrerendered AND\nneedsInitialization?}
+    ATTRGUARD -->|yes| SKIP[Skip — server-rendered values already correct]
+    ATTRGUARD -->|no| ACD[AttributeDefinition.onAttributeChangedCallback]
     ACD --> ENQ[Updates.enqueue – reflect new value via Observable accessor]
 
     DISC[disconnectedCallback] --> DBEHAV[Disconnect HostBehaviors]
@@ -386,10 +470,10 @@ Below is a conceptual map of the major subsystems and their relationships:
 
 ```
 ┌──────────────────────────────────────────────────────────────────────────────┐
-│                           FAST Global (globalThis.FAST)                      │
-│  KernelServiceIds → Updates queue, Observable system, Element registry       │
+│                      FAST (module-scoped singleton)                          │
+│  warn / error / addMessages — diagnostic messaging                           │
 └────────────────────┬─────────────────────────────────────────────────────────┘
-                     │ shared kernel slots
+                     │ ES module imports
          ┌───────────┴───────────┐
          │                       │
 ┌────────▼──────────┐   ┌────────▼────────────────────┐
@@ -432,7 +516,7 @@ Below is a conceptual map of the major subsystems and their relationships:
 1. Developer writes a class extending `FASTElement`, decorates properties with `@observable` / `@attr`, and calls `FASTElement.define({ name, template, styles })`.
 2. `FASTElement.define` → `FASTElementDefinition.compose(...).define()` registers the element with the Custom Element Registry.
 3. When the browser upgrades the element, `ElementController.forCustomElement(element)` is called in the constructor.
-4. On `connectedCallback`, the controller renders the template (`ViewTemplate.render`) into the shadow root. Compilation is lazy: the first render call triggers `Compiler.compile()`, subsequent calls clone the already-compiled `DocumentFragment`.
+4. On `connectedCallback`, the controller renders the template into the shadow root. If the element already has a shadow root from SSR (prerendered content) and hydration has been enabled via `enableHydration()`, the installed hydration hook uses `template.hydrate()` to map existing DOM nodes to binding targets instead of cloning new DOM. If no template is available yet, the element connects without rendering until a later `definition.template` update recreates the controller. Compilation is lazy: the first render call triggers `Compiler.compile()`, subsequent calls clone the already-compiled `DocumentFragment`.
 5. `HTMLView.bind(source)` wires up each `ViewBehavior`. `oneWay` bindings create `ExpressionNotifier`s that track observable dependencies automatically.
 6. When an observed property changes, its notifier fans out to all subscribers. Each binding enqueues a DOM update via `Updates`. The next animation frame drains the queue and applies the mutations.
 7. On `disconnectedCallback`, `HTMLView.unbind()` tears down all bindings; behaviors disconnect; styles are removed.
@@ -443,13 +527,14 @@ Below is a conceptual map of the major subsystems and their relationships:
 
 ```
 src/
-├── interfaces.ts          # Core types: Callable, Constructable, FASTGlobal, Message codes
-├── platform.ts            # FAST global initialisation, KernelServiceId, TypeRegistry
+├── interfaces.ts          # Core types: Callable, Constructable, Message codes
+├── platform.ts            # FAST module-scoped singleton, TypeRegistry
+├── declarative/           # Pure declarative entrypoint and map helpers
 ├── dom.ts                 # DOMAspect enum, DOMPolicy, DOMSink
 ├── dom-policy.ts          # Default DOM security policy (TrustedTypes integration)
 ├── metadata.ts            # Reflect-based metadata helpers
 ├── utilities.ts           # UnobservableMutationObserver and other helpers
-├── debug.ts               # Adds human-readable error messages to FAST global
+├── debug.ts               # Exports enableDebug() for human-readable FAST errors
 ├── observation/
 │   ├── observable.ts      # Observable, @observable, ExpressionNotifier, ExecutionContext
 │   ├── notifier.ts        # Subscriber, Notifier, SubscriberSet, PropertyChangeNotifier
@@ -482,12 +567,25 @@ src/
 ├── components/
 │   ├── fast-element.ts    # FASTElement, @customElement
 │   ├── element-controller.ts  # ElementController, Stages
-│   ├── fast-definitions.ts    # FASTElementDefinition, TemplateOptions
-│   ├── attributes.ts          # AttributeDefinition, @attr, converters
-│   └── hydration.ts           # SSR hydration helpers
+│   ├── fast-definitions.ts    # FASTElementDefinition, optional definition schema
+│   ├── schema.ts              # Schema class and schemaRegistry
+│   ├── definition-schema-transforms.ts # Definition-scoped schema transform storage
+│   └── attributes.ts          # AttributeDefinition, @attr, converters
+├── extensions/
+│   ├── observer-map.ts    # observerMap() extension and proxy-backed observation helpers
+│   └── attribute-map.ts   # attributeMap() extension and automatic @attr helpers
 ├── di/
 │   └── di.ts              # DI container, decorators, resolvers, Registration
 ├── context.ts             # Context, FASTContext, Context protocol
+├── declarative/
+│   ├── template.ts        # declarativeTemplate() and internal f-template publisher
+│   ├── template-parser.ts # Declarative HTML parser → ViewTemplate strings/values
+│   ├── schema.ts          # Compatibility re-export for Schema
+│   ├── definition-options.ts # Compatibility re-export for schema transforms
+│   ├── observer-map.ts    # Internal observer-map extension alias (not a package export)
+│   ├── attribute-map.ts   # Internal attribute-map extension alias (not a package export)
+│   ├── utilities.ts       # Declarative parsing utilities
+│   └── syntax.ts          # Declarative syntax constants
 ├── state/
 │   ├── state.ts           # state() helper (beta)
 │   └── watch.ts           # watch() helper (beta)
@@ -506,5 +604,12 @@ src/
 | [ARCHITECTURE_FASTELEMENT.md](./ARCHITECTURE_FASTELEMENT.md) | FASTElement & ElementController lifecycle in detail |
 | [ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md](./ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md) | `html` tag, directives, binding pre-processing |
 | [ARCHITECTURE_UPDATES.md](./ARCHITECTURE_UPDATES.md) | Updates queue, attribute and observable change batching |
+| [DECLARATIVE_DESIGN.md](./DECLARATIVE_DESIGN.md) | Declarative HTML runtime, parser, schema, maps, and fixture architecture |
 | [src/templating/TEMPLATE-BINDINGS.md](./src/templating/TEMPLATE-BINDINGS.md) | Full template binding pipeline: authoring → compilation → binding → DOM updates |
 | [docs/fast-element-2-changes.md](./docs/fast-element-2-changes.md) | Breaking changes from v1 to v2 |
+
+---
+
+## Bundle Size Reporting
+
+The build generates a `SIZES.md` file that records minified, gzip, and brotli sizes for the CDN rollup bundle and each individually tree-shaken export. Sizes are measured using `esbuild` for per-export bundles and from the Rollup minified output for the CDN rollup bundle. Compression sizes use Node.js `node:zlib`. The documentation site copies this file into the resources section during its prebuild step.