[Mohamed Mansour (mohamedmansour)]

Dynamic Link-mode components could become visible before their stylesheet was ready during lazy creation or soft navigation. This change keeps the browser's native stylesheet link authoritative, prevents unstyled paint on the first client-created mount, and reuses an authorized constructable sheet for later mounts.

High-level design

The solution covers the three ways WebUI content reaches the browser:

• Full SSR page loads: continue using parser-discovered native stylesheets and declarative shadow roots. Hydration preserves the server-rendered DOM.
• Router navigation: JSON, streaming, and Router.ensureLoaded() template registration now expose a readiness handshake. The framework prepares Link styles before the router commits the new component, while stale navigations can still abort promptly.
• Static component assets: the compiler records final generated CSS hrefs for each asset root and its shared closure. The protocol carries that metadata to the handler, which publishes it for the existing defineComponentAssets().preload(tag) lifecycle. CSS, the root asset, the component module, and optional data can therefore start in parallel without application code knowing generated hashes.

For a first client-created Shadow DOM instance, the framework:

1. Uses <link rel="preload" as="style"> only to warm the matching style request.
2. Keeps the original <link rel="stylesheet"> authoritative for CSP, MIME, integrity, CORS, redirects, and service workers.
3. Guards the host until the native link is active, preventing unstyled paint.
4. Releases the guard immediately, then promotes browser-authorized CSSOM into a shared constructable sheet when safe.
5. Falls back to the original native links whenever promotion is unsupported or ambiguous.

Light-DOM component assets receive real, deduplicated document stylesheets because global CSS must be applied rather than merely preloaded. Failed asset or authored-module loads are evicted so a later preload or create call can retry.

Developer experience

There is no public raw-href API and no generated CSS filename in application code:

const assets = defineComponentAssets({
  'lazy-panel': {
    asset: './lazy-panel.webui.js',
    module: () => import('./lazy-panel.js'),
  },
});

assets.preload('lazy-panel');
panel.replaceChildren(await assets.create('lazy-panel'));

Bundlers may instead own the root asset import:

asset: () => import('./lazy-panel.webui.js')

Router-owned components continue using router template loading; component assets remain for non-routed deferred UI emitted through --emit-component-assets.

Measured impact

Independent Edge NTP retest of <ntp-waffle-menu>, with a fresh browser context per run, 4x CPU throttle, and 150 ms RTT:

Scenario	0.0.22 baseline	Final	Change
Cold click to styled paint	469.8 ms	241.4 ms	-49%
Warm reopen	222.3 ms	25.1 ms	-89%
50 ms intent dwell	-	167.9 ms	CSS and JS start in parallel

Every tested path made exactly one CSS request. Cold and warm runs produced 0/10 unstyled first paints, and constructable-sheet adoption succeeded in 10/10 cold runs. Instrumentation placed the framework CSS request start within about 1.6 ms of a directly injected preload; compiler-manifest parsing was not measurable.

Against origin/main in the 500-component responsiveness harness:

• Unstyled visible frames: 8 -> 0
• Cold styled paint: 140.38 -> 124.74 ms
• Warm mount: 6.25 -> 3.815 ms
• Main task time: 20.905 -> 16.975 ms
• Heap: +9,976 bytes total, about 20 bytes per component
• Backing storage: -169,200 bytes

JavaScript footprint is +4,514 gzip bytes in the main framework entry versus origin/main; the optional component-asset entry adds 271 gzip bytes versus the prior PR head.

Important behavior

• Constructable-sheet promotion is a progressive enhancement. Native links remain the fallback.
• A stylesheet error leaves a client-created component guarded instead of exposing unstyled content.
• Automatic early component-asset style preloading requires handler or Protocol rendered HTML containing the compiler-owned manifest. Using build artifacts without rendering that protocol remains paint-safe, but CSS starts after the root asset reveals its template metadata.
• Intent that never mounts may produce the browser's standard unused-preload warning before bounded cleanup removes the speculative node.

Validation

• Full @microsoft/webui-framework unit and Playwright suites
• Router unit and E2E coverage for JSON, streaming, stale navigation, and no-framework behavior
• Component asset compiler, protocol, handler, Shadow/Light, and retry regressions
• Developer documentation build
• cargo xtask check

[Copilot]

Pull request overview

Prevents flashes of unstyled content for dynamically registered / lazily mounted components by bridging router template registration with framework stylesheet readiness, and by guarding first Link-mode shadow mounts until native link CSS is usable (while still keeping the browser as the authority for CSP/MIME/redirect/SW behavior).

Changes:

• Router: template registration now supports a synchronous waitUntil() collector and awaits readiness (with abort-aware cancellation) before committing JSON/NDJSON navigations; NDJSON chunk-two state reading is deferred until after commit and is cancellable/cleanup-safe.
• Framework: adds Link-mode stylesheet preparation + guarded mounts, promoting authorized native CSSOM to shared constructable stylesheets when safe, with broad fallback cases preserved.
• Tests/docs/spec: expands Playwright and unit coverage for Link promotion/guarding, readiness waiting, and streaming cleanup; updates DESIGN/docs to describe the new contracts.

Reviewed changes

Copilot reviewed 34 out of 35 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/webui-router/tests/router-e2e.spec.ts	Adds e2e coverage ensuring ensureLoaded() waits for link stylesheet readiness.
packages/webui-router/src/templates.ts	Makes template registration dispatch optionally awaitable via waitUntil(); adds abort-aware readiness helper.
packages/webui-router/src/templates.test.ts	New unit tests for readiness collection, abort behavior, and streaming/readiness interactions.
packages/webui-router/src/streaming.ts	Refactors NDJSON handling to defer chunk-two consumption until after commit; adds cancellable deferred stream control.
packages/webui-router/src/router.ts	Integrates readiness waits and deferred-stream lifecycle into navigation commit flow.
packages/webui-router/src/router.test.ts	Extends router unit tests to ensure deferred readers don’t start before caching and can be started explicitly.
packages/webui-router/src/preload.ts	Ensures speculative preloads can start/cancel deferred NDJSON tails after caching chunk one.
packages/webui-router/README.md	Documents readiness waiting behavior and deferred-stream semantics.
packages/webui-framework/tests/fixtures/css-link/sw-css.js	Adds SW fixture to validate service-worker-backed stylesheets remain native.
packages/webui-framework/tests/fixtures/css-link/styles/relative.css	Adds fixture CSS exercising relative asset URL rewriting behavior.
packages/webui-framework/tests/fixtures/css-link/state.json	Expands fixture state for new coverage scenarios.
packages/webui-framework/tests/fixtures/css-link/src/test-style-block-child/test-style-block-child.html	Adds mixed <link> + <style> fixture to validate cascade preservation/fallback.
packages/webui-framework/tests/fixtures/css-link/src/test-link-event-child/test-link-event-child.html	Adds compiled-event-on-link fixture to force native fallback behavior.
packages/webui-framework/tests/fixtures/css-link/src/test-link-dynamic-child/test-link-dynamic-child.html	Adds dynamically bound link attribute fixture to validate native retention and re-arming.
packages/webui-framework/tests/fixtures/css-link/src/test-link-child/test-link-child.html	Updates base child fixture to include a relative asset probe and parameterized content.
packages/webui-framework/tests/fixtures/css-link/src/test-lifecycle-style-child/test-lifecycle-style-child.html	Adds lifecycle-added-style fixture to validate cascade boundaries and warm-mount fallback.
packages/webui-framework/tests/fixtures/css-link/src/index.html	Extends fixture page to mount additional test components by state.
packages/webui-framework/tests/fixtures/css-link/relative-marker.svg	Adds relative asset used to prove correct URL resolution behavior.
packages/webui-framework/tests/fixtures/css-link/alternate.css	Adds alternate CSS used in dynamic-href swap readiness test.
packages/webui-framework/tests/fixtures/css-link/element.ts	Expands fixture elements to support hydration/lifecycle assertions and dynamic link attributes.
packages/webui-framework/tests/fixtures/css-link/css-link.spec.ts	Large Playwright expansion covering guarding, promotion safety constraints, CSP cases, and cancellation semantics.
packages/webui-framework/src/template.ts	Hooks template registration event to prepare Link styles and register readiness via waitUntil().
packages/webui-framework/src/template-events.ts	Extends template registration detail parsing to include optional waitUntil.
packages/webui-framework/src/template-element.ts	Integrates guarded Link-mode mounts and deferred hydration completion for CSP-blocked guard scenarios.
packages/webui-framework/src/template-content.ts	New shared template-content cache + stylesheet descriptor extraction for link analysis.
packages/webui-framework/src/element/styles.ts	Updates Link strategy docs to reflect guarded native loading + promotion model.
packages/webui-framework/src/element/link-styles.ts	New implementation: cache warmup, safety heuristics, guard install, native-CSSOM construction, and promotion/adoption logic.
packages/webui-framework/src/element/link-styles.test.ts	New unit tests for top-level @import detection and safe URL rewriting behavior.
packages/webui-framework/src/component-asset/loader.ts	Ensures component-asset registration awaits link-style preparation when present.
packages/webui-framework/README.md	Documents guarded Link behavior and lifecycle implications ($ready, hydratedCallback) under CSP/native fallback.
examples/app/component-assets/tests/component-assets.spec.ts	Adds browser coverage ensuring lazy asset insertion waits for link warmup before mount.
docs/guide/concepts/routing.md	Documents waitUntil() readiness bridge and its interaction with JSON/NDJSON commits and deferred state.
docs/ai/SKILL.md	Updates AI guidance/examples to reflect ensureLoaded() readiness semantics with the framework present.
DESIGN.md	Updates spec for readiness waiting, NDJSON streaming ordering, and Link promotion constraints/guarantees.
deny.toml	Adds an advisory ignore entry and normalizes formatting.

Suppressed comments (1)

packages/webui-router/src/streaming.ts:171

• The _deferredStream marker is never cleared when the deferred reader finishes naturally. Since router/preload use this marker to decide whether to import streaming.js, leaving it set causes avoidable dynamic imports for already-consumed cached entries.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

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

Suppressed comments (1)

packages/webui-framework/src/element/link-styles.ts:578

• releaseStylesheetPreload() leaves a tombstone entry in speculativeStylesheetPreloads by calling .set(preload.href, undefined). Because preloadComponentAssetStyles() uses preloads.has(href) to dedupe, a stylesheet that was cleaned up after the TTL can never be speculatively preloaded again (and the Map can only grow over time). Deleting the key avoids the permanent dedupe and keeps the cache bounded.

    if (speculative.cleanupTimer !== undefined) {
      clearTimeout(speculative.cleanupTimer);
    }
    speculativeStylesheetPreloads?.set(preload.href, undefined);
  }