[Jane Chu (janechu)]

Pull Request

📖 Description

Use the existing DOM sink guards as FAST's internal default so ESM root,
development, focused, declarative, and bundled entrypoints consistently protect
binding sinks without application setup.

Reuse the existing Trusted Types policy and remove redundant bundle policy
installation, preserving the application's one-time DOM.setPolicy() override.
Public API signatures and explicit template/binding policy precedence are
unchanged.

Keep baseline guard execution separate from custom-policy configuration, and
route aspect-only directive imports through the dependency-neutral module.
Focused imports retain only the policy code they need, without duplicating or
weakening the existing guards.

Use compact, aspect-aware element rules and direct global guard selection.
Custom policies snapshot only supplied overrides and resolve missing guards
through the same built-in selectors, preserving null removals, undefined
fallback, property casing, and element-before-global precedence.

Coerce non-nullish guarded URL values once before validation and pass the
validated string to the sink. This closes an existing bypass where arrays or
objects skipped string-only checks and were later coerced by the DOM. Preserve
null/undefined behavior and application policy overrides.

Include migration guidance, updated export-size reports, a patch change file,
and cross-browser regressions. The declarative rich-HTML fixture now explicitly
allows only its known static markup and checks fresh client rendering as well
as server-rendered markup.

🎫 Issues

No existing issue is linked.

👩‍💻 Reviewer Notes

This intentionally tightens behavior for previously unconfigured ESM consumers:
guarded URL bindings reject unsafe protocols, and known dangerous sinks such as
:innerHTML and inline handler bindings require an explicit appropriate policy.
Normal text bindings and @click listeners remain supported. The baseline is
not an HTML sanitizer and does not make untrusted template source safe.

Check that applications can still install a custom global policy, including
when using the bundles. Entry-point regressions run under a CSP that disallows
duplicate fast-html policy creation.

The dependency optimization removes custom-policy configuration code from core imports
and prevents standalone directives from initializing DOM policies. Regenerated
package reports show these gzip sizes:

Export	Before this PR	Initial PR	Previous PR head	Compact dispatch
FASTElement	7.27 KB	8.38 KB	8.15 KB	8.14 KB
html	9.38 KB	10.48 KB	10.25 KB	10.21 KB
ref	1.54 KB	2.70 KB	1.34 KB	1.34 KB
children	1.88 KB	3.01 KB	1.67 KB	1.67 KB
slotted	1.81 KB	2.94 KB	1.61 KB	1.61 KB
repeat	10.40 KB	11.51 KB	10.26 KB	10.26 KB
CDN bundle	24.01 KB	24.01 KB	24.03 KB	23.98 KB

Compared with c9ff0ed51, compact dispatch saves 341–342 minified bytes,
14–41 gzip bytes, and 21–32 Brotli bytes in each affected focused export.
The CDN bundle saves 502 minified bytes, 47 gzip bytes, and 13 Brotli bytes.
All other measured exports are unchanged; no measured minified, gzip, or
Brotli size increases. These are modest savings, not removal of baseline
protection.

Core and template imports still include baseline protection, so their remaining
increase over main is intentional. All original guard rules and URL-validation
behavior are preserved.

Before the URL-coercion follow-up, local Chromium comparison against the main-branch implementation, using medians
of nine alternating samples with detached DOM and synchronous binding updates:

Workload	Before	After
50,000 text/title updates	9.9 ms	10.4 ms
50,000 guarded URL updates	8.4 ms	18.0 ms
1,000 fresh template compile/render/dispose operations	13.4 ms	13.7 ms

These are synthetic local measurements, not application-level guarantees.
URL validation adds about 0.19 microseconds per write in this workload; the
compile/render samples were noisy. Ordinary sinks remain unwrapped, and guard
selection is cached when binding behaviors are created.

📑 Test Plan

New regressions cover eight representative entrypoints, URL attributes and properties,
blocked HTML/inline-handler sinks, normal text and events, restrictive Trusted
Types CSP, custom global policies, and rejection of a second override. The
rich-HTML fixture also asserts fresh client rendering and no page errors.

Five additional dependency regressions verify that FASTElement and html do
not import the custom-policy builder and that ref, children, and slotted
do not import DOM policy initialization.

Three URL-coercion regressions cover both default and custom policies, attribute
and property sinks, unsafe arrays/boxed strings/objects, safe coercible values,
nullish behavior, a single stateful coercion, and initial/later binding updates.
All three failed on the previous PR head before the fix.

Three compact-dispatch regressions cover the complete element guard matrix,
case-sensitive property distinctions, guard removals and global fallback,
undefined overrides, and configuration snapshots at every map level. A local
comparison against the previous head also matched 1,067,430 default/custom
sink/value combinations, including every blocked event name and all six aspects.

Command	Result
npm run build	Passed: 8 successful tasks; 1 skipped by Lage
npm run test	Passed: 5 successful tasks; 9 skipped by Lage; updated fast-element and test-harness browser suites executed
npm exec -w @microsoft/fast-element -- playwright test src/dom-policy.pw.spec.ts --project=chromium --retries=0	Before the fix: all 8 new regressions failed as expected; 10 existing tests passed
npm exec -w @microsoft/fast-element -- playwright test src/dom-policy.pw.spec.ts --project=chromium --grep 'focused entrypoint policy dependencies' --retries=0	Before the optimization: all 5 dependency regressions failed as expected
npm exec -w @microsoft/fast-element -- playwright test src/dom-policy.pw.spec.ts --project=chromium --grep 'validates coerced URL' --retries=0	Before the URL-coercion fix: all 3 new regressions failed as expected
npx playwright test --config packages/fast-element/playwright.config.ts packages/fast-element/src/dom-policy.pw.spec.ts --retries=0 --reporter=line	Passed: 87 tests across Chromium, Firefox, and WebKit
npm run build:tsc -w @microsoft/fast-element && npm run build:rollup -w @microsoft/fast-element && npm run build:sizes -w @microsoft/fast-element	Passed: regenerated package export sizes; byte-level comparison confirmed no minified, gzip, or Brotli increases
npm exec -w @microsoft/fast-element -- playwright test --config=playwright.declarative.config.ts test/declarative/fixtures/bindings/content/content.spec.ts --retries=0	Passed: 6 tests across Chromium, Firefox, and WebKit
npm run biome:check	Passed; changed TypeScript files also checked explicitly and by the pre-commit hook
npm run format:check	Passed
npm run checkchange	Passed with the committed fast-element patch change file

✅ Checklist

General

• I have included a change request file using $ npm run change
• I have added tests for my changes.
• I have tested my changes.
• I have updated the project documentation to reflect my changes.
• I have read the CONTRIBUTING documentation and followed the standards for this project.

Agents

• I have linked to an existing issue in this project that this change addresses
• I have read the skills
• I have read the DESIGN.md file(s) in packages relevant to my changes
• I have updated the DESIGN.md file(s) in packages relevant to my changes

⏭ Next Steps

None required.