fix: keep fast-element exports explicit

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.js";
+import { twoWay } from "@microsoft/fast-element/binding/two-way.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.js";
+import { twoWay } from "@microsoft/fast-element/binding/two-way.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.js";
+import { twoWay } from "@microsoft/fast-element/binding/two-way.js";
 import type { TodoApp } from "./todo-app.js";
 import type { Todo } from "./todo-list.js";
 import "./todo-form.js";

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.js";
+import { twoWay } from "@microsoft/fast-element/binding/two-way.js";
 import type { TodoForm } from "./todo-form.js";
 
 export const template = html<TodoForm>`

packages/fast-element/ARCHITECTURE_INTRO.md

@@ -2,7 +2,7 @@
 
 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`
+including the dedicated binding, hydration, and `declarative.js`
 sub-entrypoints.
 
 ## Glossary

packages/fast-element/DESIGN.md

@@ -174,11 +174,9 @@ 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.
+Optional binding helpers remain on dedicated public subpaths:
+`@microsoft/fast-element/binding/two-way.js` and
+`@microsoft/fast-element/binding/signal.js`.
 
 ---
 
@@ -356,9 +354,9 @@ 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, while `src/hydration/exports.ts` backs the grouped
-`@microsoft/fast-element/hydration.js` entrypoint for low-level hydration
-utilities and manual install hooks. See
+utility-subpath collisions, while low-level hydration APIs stay on the dedicated
+`src/components/hydration.ts`, `src/components/install-hydration.ts`, and
+`src/templating/install-hydratable-view-templates.ts` modules. See
 [`DECLARATIVE_DESIGN.md`](./DECLARATIVE_DESIGN.md) for the detailed
 architecture.
 
@@ -537,7 +535,8 @@ src/
 │   └── update-queue.ts    # Updates (UpdateQueue)
 ├── binding/
 │   ├── binding.ts         # Binding abstract base class, BindingDirective
-│   ├── exports.ts         # Focused binding entrypoint (binding.js)
+│   ├── signal.ts          # signal() and Signal
+│   ├── two-way.ts         # twoWay()
 │   ├── one-way.ts         # oneWay, listener
 │   ├── one-time.ts        # oneTime
 │   └── normalize.ts       # normalizeBinding helper
@@ -564,6 +563,8 @@ src/
 │   ├── fast-element.ts    # FASTElement, @customElement
 │   ├── element-controller.ts  # ElementController, Stages
 │   ├── fast-definitions.ts    # FASTElementDefinition, TemplateOptions
+│   ├── hydration.ts       # HydrationMarkup and hydration helpers
+│   ├── install-hydration.ts   # Legacy hydration install side-effect module
 │   └── attributes.ts          # AttributeDefinition, @attr, converters
 ├── di/
 │   └── di.ts              # DI container, decorators, resolvers, Registration
@@ -581,7 +582,6 @@ src/
 │   ├── 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,32 +53,28 @@ removed `@microsoft/fast-html` package.
    APIs; the declarative entrypoint owns the debug-message and hydratable-view
    side effects.
 
-## Focused export paths (v3)
+## Export path cleanup (v3)
 
-FAST Element now groups optional bindings and hydration helpers behind dedicated
-sub-entrypoints instead of exposing multiple nested legacy paths.
+Optional binding and hydration helpers remain on their dedicated public
+sub-entrypoints:
+
+- `@microsoft/fast-element/binding/two-way.js`
+- `@microsoft/fast-element/binding/signal.js`
+- `@microsoft/fast-element/element-hydration.js`
+- `@microsoft/fast-element/install-element-hydration.js`
+- `@microsoft/fast-element/install-hydratable-view-templates.js`
 
 ### 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`.
+1. Keep optional binding and hydration imports on their dedicated subpaths.
+2. Remove any direct imports from `metadata.js` or `pending-task.js`.
 
 ## Prerendered Content Optimization (v2 → v3)
 
@@ -97,10 +93,9 @@ sub-entrypoints instead of exposing multiple nested legacy paths.
 |---|---|
 | `@microsoft/fast-element/install-hydration.js` | No replacement needed — prerendered path is built into `ElementController` |
 
-Hydratable `ViewTemplate` support is still applied automatically by
-`@microsoft/fast-element/declarative.js`. For manual installation, import
-`installHydratableViewTemplates()` from
-`@microsoft/fast-element/hydration.js`.
+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.
 
 ### Changed behavior
 

packages/fast-element/README.md

@@ -65,24 +65,17 @@ 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
+## Dedicated 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";
+import { twoWay } from "@microsoft/fast-element/binding/two-way.js";
+import { HydrationMarkup } from "@microsoft/fast-element/element-hydration.js";
+import "@microsoft/fast-element/install-hydratable-view-templates.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.

packages/fast-element/SIZES.md

@@ -4,17 +4,17 @@ Bundle sizes for `@microsoft/fast-element` exports.
 
 | Export | Minified | Gzip | Brotli |
 |--------|----------|------|--------|
-| 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 |
+| 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 |
 | when | 2.40 KB | 978 B | 786 B |
-| html | 26.97 KB | 8.80 KB | 7.89 KB |
-| repeat | 30.52 KB | 9.71 KB | 8.72 KB |
+| html | 27.14 KB | 8.88 KB | 7.96 KB |
+| repeat | 30.79 KB | 9.81 KB | 8.82 KB |

packages/fast-element/package.json

@@ -40,9 +40,13 @@
       "test": "./src/declarative/utilities.ts",
       "default": "./dist/esm/declarative/utilities.js"
     },
-    "./binding.js": {
-      "types": "./dist/dts/binding/exports.d.ts",
-      "default": "./dist/esm/binding/exports.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"
     },
     "./render.js": {
       "types": "./dist/dts/templating/render.d.ts",
@@ -68,9 +72,17 @@
       "types": "./dist/dts/di/di.d.ts",
       "default": "./dist/esm/di/di.js"
     },
-    "./hydration.js": {
-      "types": "./dist/dts/hydration/exports.d.ts",
-      "default": "./dist/esm/hydration/exports.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"
     },
     "./dom-policy.js": {
       "types": "./dist/dts/dom-policy.d.ts",
@@ -84,7 +96,12 @@
   },
   "unpkg": "dist/fast-element.min.js",
   "sideEffects": [
-    "./dist/esm/debug.js"
+    "./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"
   ],
   "scripts": {
     "clean": "clean dist temp test-results",