Restrict fast-element path exports

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

Author: janechu

.github/skills/typescript/SKILL.md

@@ -146,7 +146,7 @@ both the initial shadow root template and the `<f-template>`:
 tracked by templates. `@volatile` marks getters whose dependencies change between calls:
 
 ```ts
-import { FASTElement } from "@microsoft/fast-element";
+import { FASTElement } from "@microsoft/fast-element/fast-element.js";
 import { attr, nullableNumberConverter } from "@microsoft/fast-element/attr.js";
 import { Observable, observable } from "@microsoft/fast-element/observable.js";
 import { volatile } from "@microsoft/fast-element/volatile.js";

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

@@ -1,4 +1,4 @@
-import { customElement, FASTElement } from "@microsoft/fast-element";
+import { customElement, FASTElement } from "@microsoft/fast-element/fast-element.js";
 import { observable } from "@microsoft/fast-element/observable.js";
 import { styles } from "./todo-form.styles.js";
 import { template } from "./todo-form.template.js";

packages/fast-element/DECLARATIVE_DESIGN.md

@@ -116,8 +116,9 @@ An optional layer that uses the `Schema` to automatically:
 - Propagate deep property mutations back through FAST's observable system so bindings re-render.
 
 Enabled via the `observerMap()` definition extension exported from
-`@microsoft/fast-element`. Calling `observerMap()` without arguments observes
-all root properties discovered in the template or supplied schema.
+`@microsoft/fast-element/observer-map.js`. Calling `observerMap()` without
+arguments observes all root properties discovered in the template or supplied
+schema.
 
 #### Path-level observation control
 
@@ -161,9 +162,8 @@ are observed.
 For non-declarative elements, pass a schema directly to `observerMap()`:
 
 ```typescript
-import { FASTElement } from "@microsoft/fast-element";
-import { Schema } from "@microsoft/fast-element";
-import { observerMap } from "@microsoft/fast-element";
+import { FASTElement, Schema } from "@microsoft/fast-element";
+import { observerMap } from "@microsoft/fast-element/observer-map.js";
 
 class MyElement extends FASTElement {}
 
@@ -199,11 +199,11 @@ An optional layer that uses the `Schema` to automatically register `@attr`-style
 - `FASTElementDefinition.attributeLookup` is keyed by the HTML attribute name, and `propertyLookup` is keyed by the JS property name so `attributeChangedCallback` correctly delegates to the new `AttributeDefinition`.
 
 Enabled via the `attributeMap()` definition extension exported from
-`@microsoft/fast-element`. Calling `attributeMap()` without arguments uses the
-default `"camelCase"` strategy. To preserve binding keys exactly as written,
-pass `attributeMap({ "attribute-name-strategy": "none" })`. Outside declarative
-templates, `attributeMap()` uses the optional `schema` on the FAST element
-definition.
+`@microsoft/fast-element/attribute-map.js`. Calling `attributeMap()` without
+arguments uses the default `"camelCase"` strategy. To preserve binding keys
+exactly as written, pass `attributeMap({ "attribute-name-strategy": "none" })`.
+Outside declarative templates, `attributeMap()` uses the optional `schema` on the
+FAST element definition.
 
 ### Syntax constants (`syntax.ts`)
 
@@ -275,42 +275,48 @@ Schema transforms run in deterministic order. `attributeMap()` runs before
 import {
     declarativeTemplate,
     TemplateParser,
+    type ResolvedStringsAndValues,
+} from "@microsoft/fast-element/declarative.js";
+import {
     Schema,
     schemaRegistry,
     type CachedPathMap,
-    type FASTElementExtension,
     type JSONSchema,
-    type ResolvedStringsAndValues,
+} from "@microsoft/fast-element/schema.js";
+import {
+    type FASTElementExtension,
     type TemplateLifecycleCallbacks,
+} from "@microsoft/fast-element";
+import {
     attributeMap,
     type AttributeMapConfig,
+} from "@microsoft/fast-element/attribute-map.js";
+import {
     observerMap,
     type ObserverMapConfig,
     type ObserverMapPathEntry,
     type ObserverMapPathNode,
-} from "@microsoft/fast-element";
+} from "@microsoft/fast-element/observer-map.js";
 ```
 
-The root entrypoint exports the declarative template helpers, map helpers, and
-their configuration types. Focused path exports are also available for direct
-entrypoint imports.
+Declarative template helpers, map helpers, and their configuration types are
+available from focused path exports.
 
-Primary exports from `@microsoft/fast-element` intended for
-application code:
+Primary declarative exports intended for application code:
 
 | Export | Purpose |
 |---|---|
-| `declarativeTemplate()` | Template resolver for `FASTElement.define()`; auto-defines the internal `<f-template>` publisher and waits for the matching template. |
-| `TemplateParser` | Standalone parser that converts declarative HTML into `ViewTemplate` strings/values. Can be used independently of `<f-template>` for programmatic template compilation. |
-| `Schema` | JSON schema builder that records binding paths discovered during template parsing. Each instance owns its own schema map and registers itself in the `schemaRegistry` for cross-element `$ref` resolution. |
-| `schemaRegistry` | Module-level `Map<string, Map<string, JSONSchema>>` that indexes schemas by custom element name. Used for cross-element lookups (e.g. nested component `$ref` resolution). |
+| `declarativeTemplate()` | `@microsoft/fast-element/declarative.js` template resolver for `FASTElement.define()`; auto-defines the internal `<f-template>` publisher and waits for the matching template. |
+| `TemplateParser` | `@microsoft/fast-element/declarative.js` standalone parser that converts declarative HTML into `ViewTemplate` strings/values. Can be used independently of `<f-template>` for programmatic template compilation. |
+| `Schema` | `@microsoft/fast-element/schema.js` JSON schema builder that records binding paths discovered during template parsing. Each instance owns its own schema map and registers itself in the `schemaRegistry` for cross-element `$ref` resolution. |
+| `schemaRegistry` | `@microsoft/fast-element/schema.js` module-level `Map<string, Map<string, JSONSchema>>` that indexes schemas by custom element name. Used for cross-element lookups (e.g. nested component `$ref` resolution). |
 
 Primary map extension exports:
 
 | Export | Import path | Purpose |
 |---|---|---|
-| `attributeMap()` | `@microsoft/fast-element` | Define extension that registers `@attr`-style properties for leaf bindings discovered during parsing or supplied by `definition.schema`. |
-| `observerMap()` | `@microsoft/fast-element` | Define extension that defines observable root properties and proxy-based deep change tracking from `config.schema`, `definition.schema`, or a declarative template schema. |
+| `attributeMap()` | `@microsoft/fast-element/attribute-map.js` | Define extension that registers `@attr`-style properties for leaf bindings discovered during parsing or supplied by `definition.schema`. |
+| `observerMap()` | `@microsoft/fast-element/observer-map.js` | Define extension that defines observable root properties and proxy-based deep change tracking from `config.schema`, `definition.schema`, or a declarative template schema. |
 
 The implementation element class (`<f-template>`), `TemplateElement.config()`,
 `TemplateElement.options()`, `ElementOptions*`, and
@@ -329,14 +335,14 @@ Additionally, `@microsoft/fast-element` exports these types:
 | `JSONSchema` | `components/schema.ts` | JSON Schema interface used by `Schema` for property structure. |
 | `CachedPathMap` | `components/schema.ts` | `Map<string, Map<string, JSONSchema>>` — the shape of the schema registry. |
 
-The root entrypoint exports the map configuration types:
+The map configuration types are exported from the same map-specific paths:
 
 | Type | Import path | Purpose |
 |---|---|---|
-| `ObserverMapConfig` | `@microsoft/fast-element` | Configuration object for `observerMap()`; accepts optional `schema` and `properties` keys. |
-| `ObserverMapPathEntry` | `@microsoft/fast-element` | `boolean \| ObserverMapPathNode` — a node in the observation path tree. |
-| `ObserverMapPathNode` | `@microsoft/fast-element` | Object node with optional `$observe` and child property overrides. |
-| `AttributeMapConfig` | `@microsoft/fast-element` | Configuration object for `attributeMap()`; accepts `attribute-name-strategy`. |
+| `ObserverMapConfig` | `@microsoft/fast-element/observer-map.js` | Configuration object for `observerMap()`; accepts optional `schema` and `properties` keys. |
+| `ObserverMapPathEntry` | `@microsoft/fast-element/observer-map.js` | `boolean \| ObserverMapPathNode` — a node in the observation path tree. |
+| `ObserverMapPathNode` | `@microsoft/fast-element/observer-map.js` | Object node with optional `$observe` and child property overrides. |
+| `AttributeMapConfig` | `@microsoft/fast-element/attribute-map.js` | Configuration object for `attributeMap()`; accepts `attribute-name-strategy`. |
 
 ---
 

packages/fast-element/DECLARATIVE_HTML.md

@@ -76,7 +76,7 @@ Hydration is opt-in. Call `enableHydration()` before FAST elements connect when
 you want prerendered Declarative Shadow DOM to be reused:
 
 ```typescript
-import { enableHydration } from "@microsoft/fast-element";
+import { enableHydration } from "@microsoft/fast-element/hydration.js";
 
 enableHydration({
     hydrationStarted() {
@@ -91,7 +91,7 @@ enableHydration({
 Pass per-element lifecycle callbacks directly to `declarativeTemplate()`:
 
 ```typescript
-import { declarativeTemplate } from "@microsoft/fast-element";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
 
 MyComponent.define({
     name: "my-component",
@@ -140,7 +140,7 @@ For non-declarative/manual schemas, import from `@microsoft/fast-element` and
 pass `observerMap({ schema })`.
 
 ```typescript
-import { observerMap } from "@microsoft/fast-element";
+import { observerMap } from "@microsoft/fast-element/observer-map.js";
 ```
 
 For finer control, pass a configuration object with a `properties` key that maps root property names to a recursive path tree:
@@ -195,9 +195,8 @@ are observed.
 Manual schema example:
 
 ```typescript
-import { FASTElement } from "@microsoft/fast-element";
-import { Schema } from "@microsoft/fast-element";
-import { observerMap } from "@microsoft/fast-element";
+import { FASTElement, Schema } from "@microsoft/fast-element";
+import { observerMap } from "@microsoft/fast-element/observer-map.js";
 
 class MyElement extends FASTElement {}
 
@@ -227,7 +226,7 @@ on the FAST element definition and import `attributeMap()` from
 `@microsoft/fast-element`.
 
 ```typescript
-import { attributeMap } from "@microsoft/fast-element";
+import { attributeMap } from "@microsoft/fast-element/attribute-map.js";
 ```
 
 By default, the binding key is treated as a camelCase property name and the HTML

packages/fast-element/DECLARATIVE_MIGRATION.md

@@ -174,7 +174,7 @@ implementation is internal and is defined automatically by `declarativeTemplate(
 | `AttributeMap` / `ObserverMap` class exports from the old declarative public surface | `attributeMap()` / `observerMap()` extension helpers and their config types |
 
 Hydration is also no longer installed by `@microsoft/fast-element`.
-Call `enableHydration()` from `@microsoft/fast-element` before FAST
+Call `enableHydration()` from `@microsoft/fast-element/hydration.js` before FAST
 elements connect when prerendered Declarative Shadow DOM should be reused.
 
 ## Schema-driven maps and optional definition schema
@@ -184,8 +184,8 @@ factored away from declarative templating. Import them from
 `@microsoft/fast-element` for declarative or non-declarative use:
 
 ```ts
-import { attributeMap } from "@microsoft/fast-element";
-import { observerMap } from "@microsoft/fast-element";
+import { attributeMap } from "@microsoft/fast-element/attribute-map.js";
+import { observerMap } from "@microsoft/fast-element/observer-map.js";
 ```
 
 `FASTElementDefinition.schema` is optional. `declarativeTemplate()` assigns it
@@ -194,9 +194,8 @@ a schema in the element definition, and `observerMap()` can also take a schema
 directly in configuration:
 
 ```ts
-import { FASTElement } from "@microsoft/fast-element";
-import { Schema } from "@microsoft/fast-element";
-import { observerMap } from "@microsoft/fast-element";
+import { FASTElement, Schema } from "@microsoft/fast-element";
+import { observerMap } from "@microsoft/fast-element/observer-map.js";
 
 class MyElement extends FASTElement {}
 

packages/fast-element/DECLARATIVE_RENDERING.md

@@ -22,7 +22,7 @@ Add a Dependency Injection service in your bundle to access properties in your s
 
 Simple example (`initial-state.ts`):
 ```typescript
-import { DI } from "@microsoft/fast-element";
+import { DI } from "@microsoft/fast-element/di.js";
 
 interface InitialState {
     text: string;
@@ -60,15 +60,13 @@ Include the DI service to your component.
 
 Example:
 ```typescript
-import { FASTElement } from "@microsoft/fast-element";
-import { attr } from "@microsoft/fast-element";
-import { Observable } from "@microsoft/fast-element";
+import { attr, FASTElement, Observable } from "@microsoft/fast-element";
 import {
     initialStateFactory,
     InitialStateService,
     type IInitialStateService,
 } from "./initial-state.js";
-import { inject } from '@microsoft/fast-element';
+import { inject } from "@microsoft/fast-element/di.js";
 
 export class MyComponent extends FASTElement {
     @inject(initialStateFactory) initialStateService!: InitialStateService;

packages/fast-element/DECLARATIVE_RENDERING_LIFECYCLE.md

@@ -62,7 +62,7 @@ Key characteristics of this phase:
 
 ### Phase 2: Declarative Template Bridge
 
-`declarativeTemplate()` from `@microsoft/fast-element`
+`declarativeTemplate()` from `@microsoft/fast-element/declarative.js`
 automatically ensures that `f-template` is defined in the same registry as the
 FAST element being composed.
 
@@ -203,8 +203,8 @@ Hydration must be explicitly opted into by calling `enableHydration()`. Per-elem
 callbacks are passed directly to `declarativeTemplate()`:
 
 ```typescript
-import { enableHydration } from "@microsoft/fast-element";
-import { declarativeTemplate } from "@microsoft/fast-element";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+import { enableHydration } from "@microsoft/fast-element/hydration.js";
 
 // Global hydration events
 enableHydration({
@@ -246,8 +246,8 @@ MyComponent.define({
 
 **Performance Monitoring:**
 ```typescript
-import { enableHydration } from "@microsoft/fast-element";
-import { declarativeTemplate } from "@microsoft/fast-element";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+import { enableHydration } from "@microsoft/fast-element/hydration.js";
 
 enableHydration({
     hydrationComplete() {

packages/fast-element/DECLARATIVE_SCHEMA_OBSERVER_MAP.md

@@ -161,11 +161,11 @@ The Schema and Observer Map classes integrate seamlessly with the f-template sys
 ### Configuration
 
 Observer Map functionality is enabled through the `observerMap()` definition
-extension exported from `@microsoft/fast-element`:
+extension exported from `@microsoft/fast-element/observer-map.js`:
 
 ```typescript
-import { declarativeTemplate } from "@microsoft/fast-element";
-import { observerMap } from "@microsoft/fast-element";
+import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
+import { observerMap } from "@microsoft/fast-element/observer-map.js";
 
 MyElement.define(
   {
@@ -184,9 +184,8 @@ For non-declarative/manual schema use, pass the schema in the observer map
 configuration:
 
 ```typescript
-import { FASTElement } from "@microsoft/fast-element";
-import { Schema } from "@microsoft/fast-element";
-import { observerMap } from "@microsoft/fast-element";
+import { FASTElement, Schema } from "@microsoft/fast-element";
+import { observerMap } from "@microsoft/fast-element/observer-map.js";
 
 class MyElement extends FASTElement {}
 
@@ -475,8 +474,7 @@ To verify that observer mapping ran, inspect the generated schema and the
 observable accessors on the element prototype:
 
 ```typescript
-import { schemaRegistry } from "@microsoft/fast-element";
-import { Observable } from "@microsoft/fast-element";
+import { Observable, schemaRegistry } from "@microsoft/fast-element";
 
 const schemas = schemaRegistry.get("my-element");
 const accessors = Observable.getAccessors(MyElement.prototype).map(a => a.name);