refactor: remove fast-element sideEffects metadata (#7493)

# Pull Request

## 📖 Description

This draft removes the remaining packaging-time side-effect assumptions from `@microsoft/fast-element` and flips the package to `"sideEffects": false`.

- make `declarative.js` import-pure by moving declarative runtime setup behind a lazy internal runtime hook
- convert `debug.js` to an explicit value-based entrypoint while keeping `index.debug.js` and `index.rollup.debug.js` opt-in debug behavior intact
- keep the shared FAST debug-message lookup and idle-callback setup working after the metadata flip
- update the directly related docs/tests and package metadata for the final sideEffects cleanup

## 👩‍�� Reviewer Notes

The main review points are `declarative/runtime.ts`, the debug entrypoint changes, and the package metadata flip in `package.json`. The important question is whether the package is now honestly safe to ship with `sideEffects: false`; the changed tests/builds are aimed at that exact concern.

## 📑 Test Plan

- `npm run build -w @microsoft/fast-element`
- `npm run test:chromium -w @microsoft/fast-element`
- `node build/biome-changed.mjs`
- `node build/biome-changed.mjs check`
- `npm run doc:ci -w @microsoft/fast-element`
- `npm run doc:exports:ci -w @microsoft/fast-element`
- `npm run test:playwright -w @microsoft/fast-element`

## ✅ Checklist

### General

- [x] I have included a change request file using `$ npm run change`
- [x] I have added tests for my changes.
- [x] I have tested my changes.
- [x] I have updated the project documentation to reflect my changes.
- [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/main/CONTRIBUTING.md) documentation and followed the [standards](https://github.com/microsoft/fast/blob/main/CODE_OF_CONDUCT.md#our-standards) for this project.

Author: janechu

change/@microsoft-fast-element-bf6e1587-06a9-4834-b906-54a625d2b446.json

@@ -0,0 +1,7 @@
+{
+  "type": "major",
+  "comment": "Make declarative runtime setup lazy and change @microsoft/fast-element/debug.js to require an explicit enableDebug() call.",
+  "packageName": "@microsoft/fast-element",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

packages/fast-element/DECLARATIVE_DESIGN.md

@@ -72,7 +72,7 @@ a waiting FAST element definition.
 
 ### `TemplateParser` — declarative HTML parser
 
-A standalone class that converts declarative HTML template markup into the `strings` and `values` arrays that `ViewTemplate.create()` consumes. It is used by `TemplateElement` internally but can also be used independently for programmatic template compilation. The parsing pipeline is fully synchronous — no promises are allocated during template resolution. A `StringsAccumulator` tracks the running concatenation of preceding HTML, eliminating repeated O(N) `join("")` calls at each binding site.
+A standalone class that converts declarative HTML template markup into the `strings` and `values` arrays that `ViewTemplate.create()` consumes. It is used by `TemplateElement` internally but can also be used independently for programmatic template compilation. The parsing pipeline is fully synchronous — no promises are allocated during template resolution. A `StringsAccumulator` tracks the running concatenation of preceding HTML, eliminating repeated O(N) `join("")` calls at each binding site. `createTemplate()` also performs the declarative runtime's lazy installation of hydratable `ViewTemplate` support and declarative debug messages.
 
 ### `Schema` — JSON schema builder
 
@@ -179,7 +179,7 @@ packages/fast-element/
 │   └── declarative/
 │       ├── index.ts           # Declarative barrel export
 │       ├── interfaces.ts      # Message enum (error codes)
-│       ├── debug.ts           # Human-readable debug messages registered with FAST
+│       ├── debug.ts           # Human-readable declarative debug messages
 │       ├── template.ts        # TemplateElement (<f-template>), lifecycle orchestration, options
 │       ├── template-parser.ts # TemplateParser — converts declarative HTML to ViewTemplate strings/values
 │       ├── schema.ts          # Schema class — JSON schema builder + schemaRegistry
@@ -361,7 +361,7 @@ sequenceDiagram
 | Method | Visibility | Role |
 |---|---|---|
 | `parse()` | public | Entry point: parses declarative HTML into `{ strings, values }`. |
-| `createTemplate()` | public | Creates a `ViewTemplate` from resolved strings and values. |
+| `createTemplate()` | public | Creates a `ViewTemplate` from resolved strings and values, lazily enabling declarative hydration support. |
 | `resolveStringsAndValues()` | private | Creates `strings`/`values` arrays and delegates to `resolveInnerHTML()`. |
 | `resolveInnerHTML()` | private | Recursive HTML parser that dispatches to data binding or template directive handlers. |
 | `resolveDataBinding()` | private | Thin dispatcher that routes to `resolveContentBinding()`, `resolveAttributeBinding()`, or `resolveAttributeDirectiveBinding()`. |

packages/fast-element/DECLARATIVE_HTML.md

@@ -20,14 +20,19 @@ server-side rendering, see the
 
 ## Template Structure
 
-After registering the declarative entrypoint as shown in the README, templates
-are associated with an element through
+After importing the declarative APIs as shown in the README, templates are
+associated with an element through
 `<f-template name="[custom-element-name]"><template>...</template></f-template>`.
 The host custom element should be defined with
 `template: declarativeTemplate()`. This automatically defines `<f-template>` in
 the relevant registry and waits for the matching declarative template when it is
 already present or inserted later.
 
+The `@microsoft/fast-element/declarative.js` entrypoint itself remains
+side-effect free at import time. The hydratable `ViewTemplate` runtime is
+installed lazily when `TemplateParser`, `TemplateElement`, or
+`declarativeTemplate()` first create a declarative template.
+
 Example:
 ```html
 <my-custom-element greeting="Hello world">

packages/fast-element/DESIGN.md

@@ -67,7 +67,7 @@ engines must install their own `globalThis` polyfill before FAST loads.
 
 - `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`)
+- `FAST.addMessages(dict)` – registers human-readable debug messages used by `enableDebug()` and declarative runtime diagnostics
 
 The `KernelServiceId` enum provides the fixed numeric keys used for shared
 services on the `FAST` global. These stable IDs let FAST instances on the same
@@ -344,9 +344,10 @@ the imperative `html` API:
 - `ObserverMap` and `AttributeMap` layer on top of the core observable and
   attribute-definition systems.
 
-The `src/declarative.ts` entrypoint owns the declarative-only side effects:
-registering debug messages and installing hydratable view templates. This keeps
-the root `@microsoft/fast-element` barrel free of declarative side effects and
+The `src/declarative.ts` entrypoint is pure at module evaluation time. The
+declarative runtime installs its debug messages and hydratable `ViewTemplate`
+hooks lazily from `TemplateParser.createTemplate()`, keeping the root
+`@microsoft/fast-element` barrel free of declarative side effects and
 utility-subpath collisions. See [`DECLARATIVE_DESIGN.md`](./DECLARATIVE_DESIGN.md)
 for the detailed architecture.
 
@@ -510,12 +511,12 @@ 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
-├── declarative.ts         # Declarative entrypoint (debug messages + hydratable view install)
+├── declarative.ts         # Pure declarative entrypoint
 ├── 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

packages/fast-element/MIGRATION.md

@@ -57,8 +57,8 @@ removed `@microsoft/fast-html` package.
 3. Keep importing core FAST Element APIs (for example `FASTElement`, `attr`,
      `observable`) from `@microsoft/fast-element`.
 4. Do not switch to the root `@microsoft/fast-element` barrel for declarative
-     APIs; the declarative entrypoint owns the debug-message and hydratable-view
-     side effects.
+    APIs; the declarative entrypoint owns the declarative runtime and installs
+    hydration support lazily when declarative templates are created.
 
 ## `TemplateOptions` removal (v3)
 
@@ -72,14 +72,33 @@ removed `@microsoft/fast-html` package.
 
 ### 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.
+- `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).
+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).
+
+## Debug entrypoint explicit enablement (v3)
+
+### Import changes
+
+| Before | After |
+|---|---|
+| `import "@microsoft/fast-element/debug.js";` | `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)
 
@@ -119,8 +138,8 @@ data source.
 | `@microsoft/fast-element/install-hydration.js` | No replacement needed — prerendered path is built into `ElementController` |
 
 The `install-hydratable-view-templates.js` side-effect import is still
-available and is applied automatically by
-`@microsoft/fast-element/declarative.js` for hydration marker support.
+available, but `@microsoft/fast-element/declarative.js` now installs the
+hydration runtime lazily when declarative APIs create a template.
 
 ### Changed behavior
 

packages/fast-element/README.md

@@ -61,6 +61,18 @@ internally, but it no longer patches `globalThis` for older engines. 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.
@@ -82,8 +94,9 @@ controller when styles need to change.
 FAST Element also publishes a declarative HTML runtime from
 `@microsoft/fast-element/declarative.js`. This entrypoint exports
 `declarativeTemplate()`, `TemplateElement`, `TemplateParser`, `Schema`,
-`ObserverMap`, and `AttributeMap`, and installs the hydratable `ViewTemplate`
-behavior without adding those side effects to the root
+`ObserverMap`, and `AttributeMap`. The entrypoint stays pure at import time and
+installs the hydratable `ViewTemplate` behavior lazily when declarative APIs
+actually create a template, without adding those side effects to the root
 `@microsoft/fast-element` import.
 
 ```ts

packages/fast-element/SIZES.md

@@ -4,17 +4,17 @@ Bundle sizes for `@microsoft/fast-element` exports.
 
 | Export | Minified | Gzip | Brotli |
 |--------|----------|------|--------|
-| CDN Rollup Bundle | 65.39 KB | 19.42 KB | 17.43 KB |
-| FASTElement | 25.59 KB | 7.93 KB | 7.19 KB |
-| Updates | 3.03 KB | 1.25 KB | 1.06 KB |
-| Observable | 7.55 KB | 2.76 KB | 2.48 KB |
-| observable | 7.58 KB | 2.77 KB | 2.50 KB |
-| attr | 2.98 KB | 1.18 KB | 1011 B |
-| children | 5.58 KB | 2.15 KB | 1.90 KB |
-| css | 4.06 KB | 1.60 KB | 1.39 KB |
-| ref | 4.55 KB | 1.81 KB | 1.60 KB |
-| slotted | 5.36 KB | 2.08 KB | 1.83 KB |
-| volatile | 7.64 KB | 2.79 KB | 2.51 KB |
+| CDN Rollup Bundle | 65.46 KB | 19.45 KB | 17.44 KB |
+| FASTElement | 25.69 KB | 7.98 KB | 7.22 KB |
+| Updates | 3.13 KB | 1.28 KB | 1.09 KB |
+| Observable | 7.65 KB | 2.79 KB | 2.51 KB |
+| observable | 7.68 KB | 2.81 KB | 2.53 KB |
+| attr | 1.28 KB | 634 B | 552 B |
+| children | 5.68 KB | 2.19 KB | 1.95 KB |
+| css | 2.36 KB | 1.05 KB | 964 B |
+| ref | 4.65 KB | 1.86 KB | 1.63 KB |
+| slotted | 5.46 KB | 2.12 KB | 1.87 KB |
+| volatile | 7.74 KB | 2.83 KB | 2.54 KB |
 | when | 1.99 KB | 770 B | 625 B |
-| html | 26.71 KB | 8.74 KB | 7.84 KB |
-| repeat | 30.37 KB | 9.67 KB | 8.70 KB |
+| html | 26.82 KB | 8.77 KB | 7.88 KB |
+| repeat | 30.48 KB | 9.70 KB | 8.74 KB |

packages/fast-element/package.json

@@ -79,12 +79,7 @@
     "./package.json": "./package.json"
   },
   "unpkg": "dist/fast-element.min.js",
-  "sideEffects": [
-    "./dist/esm/debug.js",
-    "./dist/esm/declarative.js",
-    "./dist/esm/polyfills.js",
-    "./dist/esm/interfaces.js"
-  ],
+  "sideEffects": false,
   "scripts": {
     "clean": "clean dist temp test-results",
     "doc": "api-extractor run --local",

packages/fast-element/src/debug.pw.spec.ts

@@ -1,9 +1,11 @@
 import { expect, test } from "@playwright/test";
-import "./debug.js";
+import { enableDebug } from "./debug.js";
 import type { FASTGlobal } from "./interfaces.js";
 
 declare const FAST: FASTGlobal;
 
+enableDebug();
+
 test.describe("The debug module", () => {
     let keyBase = 1111111111;
 

packages/fast-element/src/debug.ts

@@ -1,17 +1,6 @@
-import type { FASTGlobal } from "./interfaces.js";
+import { FAST, getDebugMessageLookup } from "./platform.js";
 
-if (globalThis.FAST === void 0) {
-    Reflect.defineProperty(globalThis, "FAST", {
-        value: Object.create(null),
-        configurable: false,
-        enumerable: false,
-        writable: false,
-    });
-}
-
-const FAST: FASTGlobal = globalThis.FAST;
-
-const debugMessages = {
+const baseDebugMessages = {
     [1101 /* needsArrayObservation */]:
         "Must call ArrayObserver.enable() before observing arrays.",
     [1201 /* onlySetDOMPolicyOnce */]: "The DOM Policy can only be set once.",
@@ -82,16 +71,26 @@ function formatMessage(message: string, values: Record<string, any>) {
         .join("");
 }
 
-Object.assign(FAST, {
-    addMessages(messages: Record<number, string>) {
-        Object.assign(debugMessages, messages);
-    },
-    warn(code: number, values: Record<string, any> = noValues) {
-        const message = debugMessages[code] ?? "Unknown Warning";
-        console.warn(formatMessage(message, values));
-    },
-    error(code: number, values: Record<string, any> = noValues) {
-        const message = debugMessages[code] ?? "Unknown Error";
-        return new Error(formatMessage(message, values));
-    },
-});
+/**
+ * Enables human-readable FAST debug messages.
+ * @public
+ */
+export function enableDebug(): void {
+    const debugMessages = getDebugMessageLookup();
+
+    Object.assign(debugMessages, baseDebugMessages);
+
+    Object.assign(FAST, {
+        addMessages(messages: Record<number, string>) {
+            Object.assign(debugMessages, messages);
+        },
+        warn(code: number, values: Record<string, any> = noValues) {
+            const message = debugMessages[code] ?? "Unknown Warning";
+            console.warn(formatMessage(message, values));
+        },
+        error(code: number, values: Record<string, any> = noValues) {
+            const message = debugMessages[code] ?? "Unknown Error";
+            return new Error(formatMessage(message, values));
+        },
+    });
+}