Refresh docs for focused fast-element exports

Update package docs, website content, generated API pages, and size reports to match the new fast-element entrypoint structure.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: janechu

packages/fast-element/DECLARATIVE_RENDERING.md

@@ -60,7 +60,9 @@ Include the DI service to your component.
 
 Example:
 ```typescript
-import { attr, FASTElement, Observable } from "@microsoft/fast-element";
+import { FASTElement } from "@microsoft/fast-element";
+import { attr } from "@microsoft/fast-element/attr.js";
+import { Observable } from "@microsoft/fast-element/observable.js";
 import {
     initialStateFactory,
     InitialStateService,

packages/fast-element/DESIGN.md

@@ -61,7 +61,7 @@ engines must install their own `globalThis` polyfill before FAST loads.
 
 ### FAST Global
 
-**File**: `src/platform.ts`, `src/interfaces.ts`
+**File**: `src/platform.ts`, `src/kernel.ts`
 
 `FAST` is a singleton object attached to `globalThis`. It provides:
 
@@ -171,6 +171,10 @@ This gives FAST automatic, fine-grained dependency tracking without explicit dec
 
 `normalizeBinding(value)` converts raw arrow functions or static values into a `Binding` object.
 
+Optional binding helpers remain on dedicated public subpaths:
+`@microsoft/fast-element/binding/two-way.js` and
+`@microsoft/fast-element/binding/signal.js`.
+
 ---
 
 ### html Tagged Template Literal
@@ -344,11 +348,14 @@ 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
-utility-subpath collisions. See [`DECLARATIVE_DESIGN.md`](./DECLARATIVE_DESIGN.md)
-for the detailed architecture.
+The `src/declarative.ts` entrypoint owns the declarative-only exports and
+registers debug messages for that runtime. This keeps the root
+`@microsoft/fast-element` barrel free of declarative APIs, while hydration
+support stays built into `ViewTemplate` and low-level hydration APIs remain on
+the dedicated `src/components/hydration.ts` and
+`src/components/hydration-tracker.ts` modules. See
+[`DECLARATIVE_DESIGN.md`](./DECLARATIVE_DESIGN.md) for the detailed
+architecture.
 
 ---
 
@@ -510,9 +517,10 @@ 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)
+├── kernel.ts              # FASTGlobal and KernelServiceId
+├── interfaces.ts          # Core types: Callable, Constructable, Message codes
+├── platform.ts            # FAST global initialisation and TypeRegistry
+├── declarative.ts         # Declarative entrypoint (debug messages + declarative exports)
 ├── dom.ts                 # DOMAspect enum, DOMPolicy, DOMSink
 ├── dom-policy.ts          # Default DOM security policy (TrustedTypes integration)
 ├── metadata.ts            # Reflect-based metadata helpers
@@ -525,11 +533,13 @@ src/
 │   └── update-queue.ts    # Updates (UpdateQueue)
 ├── binding/
 │   ├── binding.ts         # Binding abstract base class, BindingDirective
+│   ├── signal.ts          # signal() and Signal
+│   ├── two-way.ts         # twoWay()
 │   ├── one-way.ts         # oneWay, listener
 │   ├── one-time.ts        # oneTime
 │   └── normalize.ts       # normalizeBinding helper
 ├── templating/
-│   ├── template.ts        # ViewTemplate, html tag, InlineTemplateDirective
+│   ├── template.ts        # ViewTemplate, html tag, InlineTemplateDirective, hydration
 │   ├── compiler.ts        # Compiler, CompilationContext
 │   ├── view.ts            # HTMLView, ElementView, SyntheticView
 │   ├── html-directive.ts  # HTMLDirective, ViewBehavior, ViewBehaviorFactory
@@ -551,6 +561,7 @@ src/
 │   ├── fast-element.ts    # FASTElement, @customElement
 │   ├── element-controller.ts  # ElementController, Stages
 │   ├── fast-definitions.ts    # FASTElementDefinition, TemplateOptions
+│   ├── hydration.ts       # HydrationMarkup and hydration helpers
 │   └── attributes.ts          # AttributeDefinition, @attr, converters
 ├── di/
 │   └── di.ts              # DI container, decorators, resolvers, Registration
@@ -564,6 +575,7 @@ src/
 │   ├── utilities.ts       # Declarative parsing and proxy utilities
 │   └── syntax.ts          # Declarative syntax constants
 ├── state/
+│   ├── exports.ts         # Focused state entrypoint (state.js)
 │   ├── state.ts           # state() helper (beta)
 │   └── watch.ts           # watch() helper (beta)
 └── hydration/

packages/fast-element/MIGRATION.md

@@ -54,11 +54,44 @@ removed `@microsoft/fast-html` package.
    `@microsoft/fast-element/declarative.js`.
 2. Update declarative utility imports such as `deepMerge` to
    `@microsoft/fast-element/declarative/utilities.js`.
-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.
+3. Import core FAST Element helpers from focused entrypoints such as
+   `@microsoft/fast-element/attr.js`,
+   `@microsoft/fast-element/observable.js`, and
+   `@microsoft/fast-element/template.js`. The root
+   `@microsoft/fast-element` export now only provides `FASTElement`.
+4. Keep declarative APIs on `@microsoft/fast-element/declarative.js`; they are
+   still separate from the root export surface.
+
+## Export path cleanup (v3)
+
+Optional binding helpers remain on their dedicated public sub-entrypoints, and
+hydration utilities now live on `@microsoft/fast-element/hydration.js`:
+
+- `@microsoft/fast-element/binding/two-way.js`
+- `@microsoft/fast-element/binding/signal.js`
+- `@microsoft/fast-element/hydration.js`
+
+### Removed exports
+
+| Import | Replacement |
+|---|---|
+| `@microsoft/fast-element/testing.js` | No public replacement |
+| `@microsoft/fast-element/element-hydration.js` | `@microsoft/fast-element/hydration.js` |
+| `@microsoft/fast-element/install-element-hydration.js` | No replacement needed |
+| `@microsoft/fast-element/install-hydratable-view-templates.js` | No replacement needed |
+| `@microsoft/fast-element/metadata.js` | No public replacement |
+| `@microsoft/fast-element/pending-task.js` | No public replacement |
+
+### Migration steps
+
+1. Move `attr`, `observable`, `html`, `css`, and other helpers off the root
+   `@microsoft/fast-element` barrel onto focused subpaths.
+2. Replace `@microsoft/fast-element/element-hydration.js` with
+   `@microsoft/fast-element/hydration.js`.
+3. Remove any direct imports from `metadata.js`, `testing.js`,
+   `pending-task.js`, `install-element-hydration.js`, or
+   `install-hydratable-view-templates.js`.
+4. Keep optional binding helpers on their dedicated `binding/*` subpaths.
 
 ## Declarative event handler `e` removal (v3)
 
@@ -95,11 +128,11 @@ data source.
 
 | Import | Replacement |
 |---|---|
-| `@microsoft/fast-element/install-hydration.js` | No replacement needed — prerendered path is built into `ElementController` |
+| `@microsoft/fast-element/install-element-hydration.js` | No replacement needed — prerendered path is built into `ElementController` |
+| `@microsoft/fast-element/install-hydratable-view-templates.js` | No replacement needed — `ViewTemplate.hydrate()` is built into the template runtime |
 
-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.
+`@microsoft/fast-element/declarative.js` still exposes declarative-only APIs,
+but it no longer patches hydration behavior through installer side effects.
 
 ### Changed behavior
 
@@ -115,7 +148,9 @@ available and is applied automatically by
 ### Migration steps
 
 1. Remove `HydratableElementController.install()` calls.
-2. Remove `import "@microsoft/fast-element/install-hydration.js"` side-effect imports.
+2. Remove `import "@microsoft/fast-element/install-element-hydration.js"` and
+   `import "@microsoft/fast-element/install-hydratable-view-templates.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.
 

packages/fast-element/README.md

@@ -18,7 +18,7 @@ npm install --save @microsoft/fast-element
 Within your JavaScript or TypeScript code, you can then import library APIs like this:
 
 ```ts
-import { FASTElement } from '@microsoft/fast-element';
+import { FASTElement } from "@microsoft/fast-element";
 ```
 
 ### From CDN
@@ -65,6 +65,26 @@ importing `@microsoft/fast-element`.
 
 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.
 
+## Dedicated Entry Points
+
+`@microsoft/fast-element` only exports `FASTElement`. Import decorators,
+templating, styling, binding, and hydration APIs from focused sub-entrypoints:
+
+```ts
+import { FASTElement } from "@microsoft/fast-element";
+import { attr } from "@microsoft/fast-element/attr.js";
+import { css } from "@microsoft/fast-element/css.js";
+import { html } from "@microsoft/fast-element/template.js";
+import { twoWay } from "@microsoft/fast-element/binding/two-way.js";
+import { HydrationMarkup } from "@microsoft/fast-element/hydration.js";
+```
+
+Hydratable `ViewTemplate` support is built into the template runtime, so no
+installer import is needed. The legacy `metadata.js`, `testing.js`,
+`pending-task.js`, `element-hydration.js`, `install-element-hydration.js`, and
+`install-hydratable-view-templates.js` subpaths are no longer part of the
+public export map.
+
 ## Dynamic Style Application
 
 When runtime state or external signals need to add or remove styles, create the
@@ -82,8 +102,8 @@ controller when styles need to change.
 FAST Element also publishes a declarative HTML runtime from
 `@microsoft/fast-element/declarative.js`. This entrypoint defines `<f-template>`,
 exports `TemplateElement`, `TemplateParser`, `Schema`, `ObserverMap`, and
-`AttributeMap`, and installs the hydratable `ViewTemplate` behavior without
-adding those side effects to the root `@microsoft/fast-element` import.
+`AttributeMap`, while keeping declarative-only APIs off the root
+`@microsoft/fast-element` import.
 
 ```ts
 import { FASTElement } from "@microsoft/fast-element";
@@ -101,7 +121,10 @@ TemplateElement.define({ name: "f-template" });
 
 Declarative utilities such as `deepMerge` are available from
 `@microsoft/fast-element/declarative/utilities.js`. See
-[`DECLARATIVE_HTML.md`](./DECLARATIVE_HTML.md) for declarative usage details.
+[`DECLARATIVE_RENDERING.md`](./DECLARATIVE_RENDERING.md) for declarative usage
+details.
+Declarative event bindings use `$e` for the DOM event object and `$c` for the
+execution context.
 Declarative event bindings use `$e` for the DOM event object and `$c` for the
 execution context.
 
@@ -132,7 +155,7 @@ Custom directives can also await `controller.isPrerendered` (a `Promise<boolean>
 
 ```typescript
 import { FASTElement } from "@microsoft/fast-element";
-import type { FASTElementExtension } from "@microsoft/fast-element";
+import type { FASTElementExtension } from "@microsoft/fast-element/fast-definitions.js";
 
 function logger(): FASTElementExtension {
     return definition => {

packages/fast-element/SIZES.md

@@ -4,17 +4,17 @@ Bundle sizes for `@microsoft/fast-element` exports.
 
 | Export | Minified | Gzip | Brotli |
 |--------|----------|------|--------|
-| CDN Rollup Bundle | 62.60 KB | 18.64 KB | 16.77 KB |
-| FASTElement | 22.88 KB | 7.14 KB | 6.46 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.40 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 |
-| 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 |
+| CDN Rollup Bundle | 63.66 KB | 18.97 KB | 17.02 KB |
+| FASTElement | 23.82 KB | 7.48 KB | 6.76 KB |
+| Updates | 3.53 KB | 1.48 KB | 1.25 KB |
+| Observable | 8.05 KB | 2.97 KB | 2.67 KB |
+| observable | 8.08 KB | 2.98 KB | 2.68 KB |
+| attr | 8.79 KB | 3.25 KB | 2.91 KB |
+| children | 5.49 KB | 2.14 KB | 1.90 KB |
+| css | 3.97 KB | 1.58 KB | 1.39 KB |
+| ref | 4.46 KB | 1.80 KB | 1.58 KB |
+| slotted | 5.27 KB | 2.07 KB | 1.82 KB |
+| volatile | 8.14 KB | 3.00 KB | 2.69 KB |
+| when | 1.82 KB | 712 B | 565 B |
+| html | 27.29 KB | 8.95 KB | 8.04 KB |
+| repeat | 30.89 KB | 9.84 KB | 8.87 KB |