fix: consolidate fast-element export entrypoints

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

Author: janechu

.github/skills/typescript/SKILL.md

@@ -18,7 +18,7 @@ import { type Constructable, isFunction } from "../interfaces.js";
 Sub-entry-points expose focused APIs through the `exports` map:
 
 ```ts
-import { twoWay } from "@microsoft/fast-element/binding/two-way.js";
+import { twoWay } from "@microsoft/fast-element/binding.js";
 import { reactive } from "@microsoft/fast-element/state.js";
 import { composedParent } from "@microsoft/fast-element/utilities.js";
 ```
@@ -95,7 +95,7 @@ export const template = html<MyElement>`
 Two-way bindings require a sub-entry-point import:
 
 ```ts
-import { twoWay } from "@microsoft/fast-element/binding/two-way.js";
+import { twoWay } from "@microsoft/fast-element/binding.js";
 ```
 
 ### Partial HTML

examples/todo-app/src/todo-app.template.ts

@@ -1,5 +1,5 @@
 import { html, repeat } from "@microsoft/fast-element";
-import { twoWay } from "@microsoft/fast-element/binding/two-way.js";
+import { twoWay } from "@microsoft/fast-element/binding.js";
 import type { TodoApp } from "./todo-app.js";
 import type { Todo } from "./todo-list.js";
 import "./todo-form.js";
@@ -34,7 +34,7 @@ export const template = html<TodoApp>`
                         &times;
                     </button>
                 </li>
-            `
+            `,
         )}
     </ul>
 `;

examples/todo-app/src/todo-form.template.ts

@@ -1,5 +1,5 @@
 import { html } from "@microsoft/fast-element";
-import { twoWay } from "@microsoft/fast-element/binding/two-way.js";
+import { twoWay } from "@microsoft/fast-element/binding.js";
 import type { TodoForm } from "./todo-form.js";
 
 export const template = html<TodoForm>`

packages/fast-element/ARCHITECTURE_INTRO.md

@@ -1,10 +1,13 @@
 # Introduction
 
-This document (and the linked documents) explains how the exports and side effects of `@microsoft/fast-element` are used to create custom elements.
+This document (and the linked documents) explains how the exports and side
+effects of `@microsoft/fast-element` are used to create custom elements,
+including the focused `binding.js`, `hydration.js`, and `declarative.js`
+sub-entrypoints.
 
 ## Glossary
 
 - [Overview](./ARCHITECTURE_OVERVIEW.md): How the `@microsoft/fast-element` should be used by a developer and what code is executed during the first render.
 - [`FASTElement`](./ARCHITECTURE_FASTELEMENT.md): How the `FASTElement` is architected.
 - [`html` tagged template literal](./ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md): How the `html` tagged template literal takes and converts the contents into a `ViewTemplate`.
-- [`Updates` queue](./ARCHITECTURE_UPDATES.md): How updates to attributes and observables are processed.
+- [`Updates` queue](./ARCHITECTURE_UPDATES.md): How updates to attributes and observables are processed.

packages/fast-element/DESIGN.md

@@ -174,6 +174,12 @@ This gives FAST automatic, fine-grained dependency tracking without explicit dec
 
 `normalizeBinding(value)` converts raw arrow functions or static values into a `Binding` object.
 
+The focused public binding entrypoint
+`@microsoft/fast-element/binding.js` is implemented by
+`src/binding/exports.ts`. It groups the optional `signal` and `twoWay`
+helpers with the core binding primitives so callers no longer need nested
+subpath imports.
+
 ---
 
 ### html Tagged Template Literal
@@ -350,8 +356,11 @@ the imperative `html` API:
 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.
+utility-subpath collisions, while `src/hydration/exports.ts` backs the grouped
+`@microsoft/fast-element/hydration.js` entrypoint for low-level hydration
+utilities and manual install hooks. See
+[`DECLARATIVE_DESIGN.md`](./DECLARATIVE_DESIGN.md) for the detailed
+architecture.
 
 ---
 
@@ -528,6 +537,7 @@ src/
 │   └── update-queue.ts    # Updates (UpdateQueue)
 ├── binding/
 │   ├── binding.ts         # Binding abstract base class, BindingDirective
+│   ├── exports.ts         # Focused binding entrypoint (binding.js)
 │   ├── one-way.ts         # oneWay, listener
 │   ├── one-time.ts        # oneTime
 │   └── normalize.ts       # normalizeBinding helper
@@ -567,9 +577,11 @@ 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/
+    ├── exports.ts         # Focused hydration entrypoint (hydration.js)
     └── target-builder.ts  # Hydration target resolution
 ```
 

packages/fast-element/MIGRATION.md

@@ -53,6 +53,33 @@ removed `@microsoft/fast-html` package.
    APIs; the declarative entrypoint owns the debug-message and hydratable-view
    side effects.
 
+## Focused export paths (v3)
+
+FAST Element now groups optional bindings and hydration helpers behind dedicated
+sub-entrypoints instead of exposing multiple nested legacy paths.
+
+### Removed exports
+
+| Import | Replacement |
+|---|---|
+| `@microsoft/fast-element/binding/two-way.js` | `@microsoft/fast-element/binding.js` |
+| `@microsoft/fast-element/binding/signal.js` | `@microsoft/fast-element/binding.js` |
+| `@microsoft/fast-element/element-hydration.js` | `@microsoft/fast-element/hydration.js` |
+| `@microsoft/fast-element/install-element-hydration.js` | `@microsoft/fast-element/hydration.js` |
+| `@microsoft/fast-element/install-hydratable-view-templates.js` | `@microsoft/fast-element/hydration.js` |
+| `@microsoft/fast-element/metadata.js` | No public replacement |
+| `@microsoft/fast-element/pending-task.js` | No public replacement |
+
+### Migration steps
+
+1. Update two-way and signal imports to `@microsoft/fast-element/binding.js`.
+2. Update hydration utility imports to `@microsoft/fast-element/hydration.js`.
+3. Replace manual side-effect imports with
+   `installElementHydration()` or `installHydratableViewTemplates()` from
+   `@microsoft/fast-element/hydration.js` only when you need those hooks
+   outside `@microsoft/fast-element/declarative.js`.
+4. Remove any direct imports from `metadata.js` or `pending-task.js`.
+
 ## Prerendered Content Optimization (v2 → v3)
 
 ### Removed exports
@@ -70,9 +97,10 @@ removed `@microsoft/fast-html` package.
 |---|---|
 | `@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.
+Hydratable `ViewTemplate` support is still applied automatically by
+`@microsoft/fast-element/declarative.js`. For manual installation, import
+`installHydratableViewTemplates()` from
+`@microsoft/fast-element/hydration.js`.
 
 ### Changed behavior
 

packages/fast-element/README.md

@@ -65,6 +65,28 @@ 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.
 
+## Focused Entry Points
+
+Use the dedicated sub-entrypoints when you only need optional binding or
+hydration APIs:
+
+```ts
+import { twoWay } from "@microsoft/fast-element/binding.js";
+import {
+    HydrationMarkup,
+    installHydratableViewTemplates,
+} from "@microsoft/fast-element/hydration.js";
+```
+
+`binding.js` groups the optional binding helpers (`twoWay`, `signal`,
+`Signal`, and related types) behind a single public path. `hydration.js`
+groups the low-level hydration utilities and the manual install hooks used
+outside `declarative.js`.
+
+`@microsoft/fast-element/declarative.js` still installs hydratable
+`ViewTemplate` support automatically. The legacy `metadata.js` and
+`pending-task.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

packages/fast-element/SIZES.md

@@ -4,17 +4,17 @@ Bundle sizes for `@microsoft/fast-element` exports.
 
 | Export | Minified | Gzip | Brotli |
 |--------|----------|------|--------|
-| CDN Rollup Bundle | 63.06 KB | 18.80 KB | 16.88 KB |
-| FASTElement | 23.30 KB | 7.32 KB | 6.60 KB |
-| Updates | 3.45 KB | 1.43 KB | 1.21 KB |
-| Observable | 7.96 KB | 2.94 KB | 2.62 KB |
-| observable | 8.00 KB | 2.95 KB | 2.62 KB |
-| attr | 3.39 KB | 1.37 KB | 1.13 KB |
-| children | 5.99 KB | 2.29 KB | 2.01 KB |
-| css | 4.47 KB | 1.78 KB | 1.54 KB |
-| ref | 4.96 KB | 1.96 KB | 1.71 KB |
-| slotted | 5.78 KB | 2.22 KB | 1.95 KB |
-| volatile | 8.05 KB | 2.97 KB | 2.63 KB |
+| CDN Rollup Bundle | 63.16 KB | 18.83 KB | 16.88 KB |
+| FASTElement | 23.03 KB | 7.22 KB | 6.50 KB |
+| Updates | 3.18 KB | 1.32 KB | 1.10 KB |
+| Observable | 7.69 KB | 2.83 KB | 2.52 KB |
+| observable | 7.73 KB | 2.85 KB | 2.53 KB |
+| attr | 933 B | 481 B | 417 B |
+| children | 5.72 KB | 2.17 KB | 1.92 KB |
+| css | 1.99 KB | 919 B | 819 B |
+| ref | 4.69 KB | 1.85 KB | 1.62 KB |
+| slotted | 5.51 KB | 2.11 KB | 1.85 KB |
+| volatile | 7.78 KB | 2.87 KB | 2.54 KB |
 | when | 2.40 KB | 978 B | 786 B |
-| html | 27.14 KB | 8.88 KB | 7.96 KB |
-| repeat | 30.79 KB | 9.81 KB | 8.82 KB |
+| html | 26.97 KB | 8.80 KB | 7.89 KB |
+| repeat | 30.52 KB | 9.71 KB | 8.72 KB |

packages/fast-element/package.json

@@ -40,13 +40,9 @@
       "test": "./src/declarative/utilities.ts",
       "default": "./dist/esm/declarative/utilities.js"
     },
-    "./binding/two-way.js": {
-      "types": "./dist/dts/binding/two-way.d.ts",
-      "default": "./dist/esm/binding/two-way.js"
-    },
-    "./binding/signal.js": {
-      "types": "./dist/dts/binding/signal.d.ts",
-      "default": "./dist/esm/binding/signal.js"
+    "./binding.js": {
+      "types": "./dist/dts/binding/exports.d.ts",
+      "default": "./dist/esm/binding/exports.js"
     },
     "./render.js": {
       "types": "./dist/dts/templating/render.d.ts",
@@ -64,10 +60,6 @@
       "types": "./dist/dts/context.d.ts",
       "default": "./dist/esm/context.js"
     },
-    "./metadata.js": {
-      "types": "./dist/dts/metadata.d.ts",
-      "default": "./dist/esm/metadata.js"
-    },
     "./testing.js": {
       "types": "./dist/dts/testing/exports.d.ts",
       "default": "./dist/esm/testing/exports.js"
@@ -76,21 +68,9 @@
       "types": "./dist/dts/di/di.d.ts",
       "default": "./dist/esm/di/di.js"
     },
-    "./element-hydration.js": {
-      "types": "./dist/dts/components/hydration.d.ts",
-      "default": "./dist/esm/components/hydration.js"
-    },
-    "./install-element-hydration.js": {
-      "types": "./dist/dts/components/install-hydration.d.ts",
-      "default": "./dist/esm/components/install-hydration.js"
-    },
-    "./install-hydratable-view-templates.js": {
-      "types": "./dist/dts/templating/install-hydratable-view-templates.d.ts",
-      "default": "./dist/esm/templating/install-hydratable-view-templates.js"
-    },
-    "./pending-task.js": {
-      "types": "./dist/dts/pending-task.d.ts",
-      "default": "./dist/esm/pending-task.js"
+    "./hydration.js": {
+      "types": "./dist/dts/hydration/exports.d.ts",
+      "default": "./dist/esm/hydration/exports.js"
     },
     "./dom-policy.js": {
       "types": "./dist/dts/dom-policy.d.ts",
@@ -104,12 +84,7 @@
   },
   "unpkg": "dist/fast-element.min.js",
   "sideEffects": [
-    "./dist/esm/debug.js",
-    "./dist/esm/declarative.js",
-    "./dist/esm/polyfills.js",
-    "./dist/esm/components/install-hydration.js",
-    "./dist/esm/templating/install-hydratable-view-templates.js",
-    "./dist/esm/interfaces.js"
+    "./dist/esm/debug.js"
   ],
   "scripts": {
     "clean": "clean dist temp test-results",

packages/fast-element/src/binding/exports.ts

@@ -0,0 +1,12 @@
+/**
+ * Binding exports for focused access to FAST binding APIs.
+ * @public
+ */
+export type { BindingDirective } from "./binding.js";
+export { Binding } from "./binding.js";
+export { normalizeBinding } from "./normalize.js";
+export { oneTime } from "./one-time.js";
+export { listener, oneWay } from "./one-way.js";
+export { Signal, signal } from "./signal.js";
+export type { TwoWayBindingOptions } from "./two-way.js";
+export { TwoWaySettings, twoWay } from "./two-way.js";