feat: make Light DOM a global CSS opt-in

[Mohamed Mansour (mohamedmansour)]

Current behavior

WebUI uses Shadow DOM for unwrapped components by default. This PR makes explicit --dom=light a first-class mode for authored/global Light CSS:

• Unwrapped components under --dom=light render directly into the host and use ordinary CSS in their owning Document or ShadowRoot CSS tree.
• A sole bare top-level <template> is an explicit Light-mode wrapper even when the fallback is --dom=shadow; WebUI removes the wrapper before rendering and hydration.
• A sole <template shadowrootmode="open"> explicitly selects native Shadow DOM in either build mode.
• Templates with attributes, w-render/w-hydrate policy wrappers, and nested templates do not select a mode; they retain their ordinary/policy meaning.
• Light CSS is not selector-rewritten, marker-scoped, wrapped in compiler-generated @scope, or namespaced for keyframes/layers. Normal cascade and inheritance apply across Light components in the same CSS tree.
• :host, :host(...), :host-context(...), and ::slotted(...) in effective Light CSS fail at build time with unsupported-light-css and actionable help to use a normal selector or opt into Shadow.
• Ordered CSS closures remain the delivery contract across SSR, routes, streaming, partial navigation, hydration, and component assets. Link/Style/Module delivery, compatible bundling, active Document head hoisting, and ShadowRoot preloads are preserved.
• FAST 2/3 continues to require effective Shadow components; the WebUI plugin supports global Light CSS.

Benchmark: representative 432-instance fixture

Eight browser cycles and eight release-server cycles were run on the current head with 48 component types, nested Light/Shadow variants, shared selectors, container queries, and bundled/unbundled Link delivery. Computed-style parity was identical across all 48 component types.

Metric	Light	Shadow	Light delta
Release render, unbundled	0.09 ms	0.12 ms	-29.5%
Release render, bundled	0.08 ms	0.12 ms	-30.5%
SSR output	1.09 MiB	1.15 MiB	-5.1%
Protocol, unbundled	140.91 KiB	144.06 KiB	-2.2%
Bundled DOMContentLoaded	39.85 ms	546.60 ms	-92.7%
Bundled stylesheet requests	1	48	-97.9%
Bundled style recalculation	4,170.52 ms	849.03 ms	+391.2%
Bundled host class workload	317.05 ms	139.90 ms	+126.6%
Bundled host attribute workload	354.85 ms	178.95 ms	+98.3%

Global Light improves server rendering, output size, stylesheet consolidation, and document readiness. Native Shadow remains the stronger CSS-engine boundary for CSS-heavy or frequently restyled trees; this PR does not claim Light is universally faster.

Validation

• cargo xtask check
• 601 parser tests
• 273 framework unit tests
• 222 framework E2E tests
• 28 router E2E tests
• 58 Node package tests
• 24 WASM tests

Closes #410
Closes #433

[Copilot]

Pull request overview

This PR makes Light DOM the default rendering mode across WebUI, introduces a required componentStyles catalog (resources + ordered closures) as the unified CSS delivery contract, and updates the full stack (parser → protocol → handler → router/framework → assets → docs/tests/examples) to match the new default and style-delivery model.

Changes:

• Switch default DOM strategy to Light, while preserving explicit --dom=shadow / dom: "shadow" and per-component Shadow opt-in via a sole top-level <template shadowrootmode="open">.
• Replace legacy templateStyles / inference with required, versioned componentStyles (resources + closures) and plumb it through SSR, streaming checkpoints, partial navigation, and component assets (v3).
• Update tests, fixtures, examples, and documentation to align with the new default and new CSS/style installation behavior.

Reviewed changes

Copilot reviewed 111 out of 111 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/webui/test/integration.test.ts	Update integration expectations for Light default and componentStyles.
packages/webui/src/index.ts	Add dom build option and default it to "light" in Node API wrapper.
packages/webui/README.md	Document Light default + Shadow opt-in + componentStyles return shape.
packages/webui-test-support/src/fixture-render.ts	Add per-fixture dom override behavior (shadow vs default vs explicit light).
packages/webui-router/src/types.ts	Define ComponentStyles and expose registration bridge types.
packages/webui-router/src/templates.ts	Switch router registration flow to componentStyles and bridge integration.
packages/webui-router/src/streaming.ts	Remove legacy injected module-style set from streaming context usage.
packages/webui-router/src/router.ts	Remove router-level module-style tracking; keep SSR styles array for framework lazy dedupe.
packages/webui-router/src/router.test.ts	Update tests for componentStyles + bridge ordering and SSR styles retention.
packages/webui-router/src/index.ts	Re-export ComponentStyles and related public types.
packages/webui-router/src/cache.ts	Replace templateStyles with required componentStyles in partial response shape.
packages/webui-router/README.md	Update partial/streaming response contract docs to componentStyles.
packages/webui-framework/tests/fixtures/slot-shadow/webui.config.json	Add fixture-level global Shadow config for slot coverage.
packages/webui-framework/tests/fixtures/slot-shadow/src/test-slot-btn/test-slot-btn.html	Wrap slot component in Shadow opt-in template.
packages/webui-framework/tests/fixtures/slot-shadow/slot-shadow.spec.ts	Add regression asserting explicit global Shadow still wraps templates.
packages/webui-framework/tests/fixtures/README.md	Update fixture authoring guidance for new default + Shadow opt-in rules.
packages/webui-framework/tests/fixtures/light-dom/webui.config.json	Configure fixture to test product default without passing dom option.
packages/webui-framework/tests/fixtures/light-dom/state.json	Add fixture state for Light pipeline coverage.
packages/webui-framework/tests/fixtures/light-dom/src/test-shadow-opt-in/test-shadow-opt-in.html	Add component-level Shadow opt-in fixture component.
packages/webui-framework/tests/fixtures/light-dom/src/test-shadow-opt-in/test-shadow-opt-in.css	Add Shadow-scoped ::slotted styling in fixture.
packages/webui-framework/tests/fixtures/light-dom/src/test-shadow-light-child/test-shadow-light-child.html	Add nested Light child component markup for mixed-mode test.
packages/webui-framework/tests/fixtures/light-dom/src/test-shadow-light-child/test-shadow-light-child.css	Add nested Light child styling for mixed-mode test.
packages/webui-framework/tests/fixtures/light-dom/src/test-light-dom/test-light-dom.html	Add Light root fixture with client-side child spawning and Shadow opt-in.
packages/webui-framework/tests/fixtures/light-dom/src/test-light-dom/test-light-dom.css	Add scoped Light CSS validation in fixture.
packages/webui-framework/tests/fixtures/light-dom/src/test-light-child/test-light-child.html	Add Light child fixture component markup.
packages/webui-framework/tests/fixtures/light-dom/src/test-light-child/test-light-child.css	Add Light child fixture styling.
packages/webui-framework/tests/fixtures/light-dom/src/index.html	Add fixture entry document for real-pipeline Light rendering.
packages/webui-framework/tests/fixtures/light-dom/light-dom.spec.ts	Rewrite E2E to validate Light default, scoped CSS, closures order, Shadow opt-in, and slot projection.
packages/webui-framework/tests/fixtures/light-dom/element.ts	Switch fixture to real pipeline (define components + behaviors) instead of manual registration.
packages/webui-framework/tests/fixtures/css-module/css-module.spec.ts	Update comment to reflect new module install function naming/behavior.
packages/webui-framework/src/template.ts	Add componentStyles registration + bridge integration into template registry.
packages/webui-framework/src/template.test.ts	Update SSR bootstrap parsing test data to include componentStyles.
packages/webui-framework/src/template-types.ts	Remove sa from template metadata surface.
packages/webui-framework/src/template-events.ts	Include componentStyles in templates-registered event payload.
packages/webui-framework/src/template-element.ts	Install component style closures during hydration and add Light host marker for client-created Light elements.
packages/webui-framework/src/template-element.test.ts	Adjust HTMLElement/document mocks for root detection and ownership.
packages/webui-framework/src/streaming-protocol.ts	Make streaming bootstrap require componentStyles.
packages/webui-framework/src/streaming-pipeline.test.ts	Add coverage for halting stream when checkpoint omits componentStyles.
packages/webui-framework/src/streaming-bootstrap.ts	Register componentStyles during boundary bootstrap and avoid merging it into ephemeral state.
packages/webui-framework/src/index.ts	Export componentStyles APIs/types from framework package surface.
packages/webui-framework/src/element/styles.test.ts	Add unit test suite for componentStyles catalogs (Document/ShadowRoot install, module importmaps, nonce, dedupe).
packages/webui-framework/src/element/markers.ts	Ensure ordinal walker skips compiler-emitted style fallback markers.
packages/webui-framework/src/element/markers.test.ts	Add test ensuring data-webui-resource elements are skipped in ordinal counting.
packages/webui-framework/src/component-asset/resources.ts	Remove legacy component-asset templateStyles importmap injection implementation.
packages/webui-framework/src/component-asset/loader.ts	Switch component-asset loading to required componentStyles + graph validation.
packages/webui-framework/src/component-asset/asset.ts	Bump component assets to v3 and require componentStyles.
packages/webui-framework/src/component-asset.test.ts	Update component asset tests to validate v3 + componentStyles installation/validation.
packages/webui-framework/RENDERING.md	Update rendering spec docs for componentStyles/closures and Light default.
packages/webui-framework/README.md	Update authoring + DOM selection docs and remove sa references.
examples/app/service-worker/scripts/check-render.ts	Update render check to assert new data-webui-resource style markers.
examples/app/contact-book-manager/src/atoms/cb-icon-button/cb-icon-button.html	Wrap slot usage in Shadow opt-in template.
examples/app/contact-book-manager/src/atoms/cb-button/cb-button.html	Wrap slot usage in Shadow opt-in template.
examples/app/commerce/server/src/server.rs	Update server tests to validate new componentStyles resource shapes.
docs/guide/why.md	Refresh platform-primitive messaging for Light default + scoped CSS.
docs/guide/integrations/wasm.md	Update sample component to wrap <slot> in Shadow opt-in template.
docs/guide/integrations/rust.md	Document dom default Light and Shadow selection rules.
docs/guide/integrations/node.md	Update Node integration defaults + Shadow opt-in guidance.
docs/guide/index.md	Update guide intro to reflect Light default + optional Shadow.
docs/guide/concepts/routing.md	Update routing payload examples/field table to componentStyles.
docs/guide/concepts/react-comparison.md	Update styling comparison for scoped Light + Shadow opt-in.
docs/guide/concepts/plugins/index.md	Update plugin contract to include ComponentTemplateContext with effective DOM mode.
docs/guide/concepts/performance.md	Update DOM-mode guidance to reflect Light default and Shadow selection.
docs/guide/concepts/interactivity.md	Update template wrapper guidance and styling section for new model.
docs/guide/concepts/how-it-works.md	Update SSR/hydration description for Light default + component style installation.
docs/guide/concepts/components/index.md	Update component authoring docs for Light default and Shadow opt-in rules.
docs/guide/concepts/best-practices.md	Update best practices for Light default and slot-in-Shadow constraint.
docs/guide/cli/index.md	Update CLI docs for --dom default and new CSS resource delivery contract.
docs/ai/SKILL.md	Update AI authoring guidance for Light default + slot-in-Shadow rule.
docs/.webui-press/components/code-comparison/code-comparison.html	Wrap slots in Shadow opt-in template for docs component.
crates/webui/src/server.rs	Update Rust server tests to validate componentStyles resources across CSS strategies.
crates/webui/src/component_assets/serialize.rs	Emit v3 component assets with componentStyles resources + closures.
crates/webui/src/component_assets/render.rs	Thread protocol context into asset rendering options.
crates/webui/src/component_assets/payload.rs	Render style resources based on CssStrategy instead of legacy templateStyles importmap.
crates/webui/src/component_assets.rs	Prune/validate style closures when retaining entry protocol; add tests.
crates/webui/README.md	Update Rust crate README for Light default and doc table updates.
crates/webui-wasm/src/parser.rs	Snapshot/apply effective component DOM strategies and style closure metadata in WASM parser output.
crates/webui-wasm/src/lib.rs	Update WASM tests for slot-in-Shadow and new style marker output.
crates/webui-protocol/src/gen_webui.rs	Add effective_dom_strategy, style_closures, and flip DomStrategy enum values (Light=0).
crates/webui-protocol/proto/webui.proto	Update proto schema for effective_dom_strategy + style_closures; flip DomStrategy enum ordering.
crates/webui-press/README.md	Update docs generator narrative for Light default + Shadow opt-in.
crates/webui-press/components/webui-press-tabs/webui-press-tabs.html	Wrap slots in Shadow opt-in template.
crates/webui-press/components/webui-press-tab/webui-press-tab.html	Wrap slots in Shadow opt-in template.
crates/webui-press/components/webui-press-tab-panel/webui-press-tab-panel.html	Wrap slots in Shadow opt-in template.
crates/webui-press/components/webui-blockquote/webui-blockquote.html	Wrap slots in Shadow opt-in template.
crates/webui-press/components/code-block/code-block.html	Wrap slot component in Shadow opt-in template.
crates/webui-parser/src/plugin/webui.rs	Resolve/store per-component effective DOM strategy and remove sa emission.
crates/webui-parser/src/plugin/mod.rs	Extend plugin contract with ComponentTemplateContext and require effective_dom_strategy in artifacts.
crates/webui-parser/src/plugin/fast_v3.rs	Plumb effective DOM strategy through FAST v3 artifacts.
crates/webui-parser/src/plugin/fast_v2.rs	Plumb effective DOM strategy through FAST v2 artifacts.
crates/webui-parser/src/diagnostic.rs	Add diagnostic codes for Light DOM slot, invalid Shadow wrapper, unsupported light CSS, etc.
crates/webui-parser/src/component_registry.rs	Preserve authored CSS for diagnostics when processed CSS is replaced.
crates/webui-parser/benches/parser_bench.rs	Update benches for new parser options + add Light CSS boundary benchmark.
crates/webui-node/src/lib.rs	Update Node binding docs/tests for Light default and slot constraints.
crates/webui-handler/src/streaming/session.rs	Track CSS strategy + style closure roots during streaming; ensure style metadata present.
crates/webui-handler/src/streaming/checkpoint.rs	Emit componentStyles at checkpoints; gate module importmap emission by strategy.
crates/webui-handler/src/html_encode.rs	Add safe CSS style text writer to prevent premature </style> termination.
crates/webui-handler/README.md	Update handler README for componentStyles return shape.
crates/webui-handler/benches/bootstrap_state_bench.rs	Update benchmark payload shapes to include componentStyles.
crates/webui-cli/src/commands/serve.rs	Update comment for JSON partial contents.
crates/webui-cli/src/commands/common.rs	Default CLI --dom to Light and add parsing tests.
crates/webui-cli/src/commands/build.rs	Default build command to Light; update tests and asset version assertions.
.github/skills/webui-dev/SKILL.md	Update skill guidance to reflect Light default + Shadow opt-in wrapper rule.
.github/skills/testing/SKILL.md	Update fixture guidance for Light default and Shadow opt-in patterns.

[Copilot]

Pull request overview

Copilot reviewed 111 out of 111 changed files in this pull request and generated no new comments.

Suppressed comments (1)

crates/webui/src/component_assets.rs:210

• This new unit test asserts on a specific error string fragment ("requires missing ..."), which is brittle and will break on harmless wording changes. Prefer asserting on the error variant and (optionally) a stable substring describing the condition, rather than the full rendered error text.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 164 out of 164 changed files in this pull request and generated no new comments.

Suppressed comments (1)

packages/webui-framework/tests/fixtures/README.md:97

• The fixtures README says webui.config.json supports a dom key, but the fixture renderer only reads css and script (see packages/webui-test-support/src/fixture-render.ts:62-83 and :113-120). Keeping dom here is misleading and suggests a build option that no longer exists.

[Copilot]

Pull request overview

Copilot reviewed 164 out of 164 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 166 out of 170 changed files in this pull request and generated no new comments.

Suppressed comments (1)

packages/webui-router/src/router.ts:67

• isRouteStyleMarker requires a data-webui-strategy attribute, but the client runtime’s style installer (packages/webui-framework/src/element/styles.ts, appendResource) only sets data-webui-resource on inserted <link>/<style> markers (SSR may include the strategy attribute, but client-installed markers often won’t). As a result, mountedRouteComponent() / clearRouteContent() can treat real style markers as ordinary content and remove them when remounting routes, breaking route-scoped CSS on navigation.

[Copilot]

Pull request overview

Copilot reviewed 165 out of 170 changed files in this pull request and generated no new comments.

Suppressed comments (3)

crates/webui-cli/src/utils/output.rs:312

• After switching force_colors() to an RAII guard, these tests should stop manually toggling console::set_colors_enabled(prev) and just keep the guard alive for the duration of the assertion block.

        let (_guard, prev) = force_colors();
        let (_display, message) = build_error_renderings(&template_error());
        console::set_colors_enabled(prev);

crates/webui-cli/src/utils/output.rs:328

• After switching force_colors() to an RAII guard, this test can just bind the guard for the scope and avoid manually restoring console color state.

        let (_guard, prev) = force_colors();
        let (display, _message) = build_error_renderings(&template_error());
        console::set_colors_enabled(prev);

crates/webui-cli/src/utils/output.rs:288

• force_colors() relies on callers to restore console::set_colors_enabled(prev). If the test panics between enabling and restoring, the process-global color setting can leak into later tests (even though the mutex prevents concurrent runs). Prefer an RAII guard that restores the previous state in Drop so restoration happens even on panic.

This issue also appears in the following locations of the same file:

• line 310
• line 326

    fn force_colors() -> (MutexGuard<'static, ()>, bool) {
        let guard = COLOR_LOCK
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        let previous = console::colors_enabled();