feat: add compiler-driven interaction hydration

[Mohamed Mansour (mohamedmansour)]

Summary

• add neutral compiler work-policy metadata for interaction hydration and the combined lazy-render/interaction policy
• generate the singleton interaction marker for authored and routed roots across buffered and streaming rendering
• add the isolated @microsoft/webui-framework/interaction-hydration.js entry with pointer, focus, keyboard, and cancelable primary-click replay
• add framework-neutral @microsoft/webui-router/preload.js preparation, cancellation, bounded buffering, and single-use handoff
• preserve JSON and NDJSON streaming, inventory checks, cache completeness, startup retry, and no-duplicate-request behavior
• document when to choose eager, lazy render, interaction, or their explicit combined form

The router package has no WebUI Framework dependency; FAST or another runtime supplies its own onIntent readiness and adopts the same prepared response.

Authoring contract

UI shape	Policy	Tradeoff
Visible and commonly interactive	Eager default	Lowest first-use latency
Repeated or offscreen	w-render="lazy"	Initial JS loads; hydration and browser rendering wait for relevance
Visible SSR shell that may never be used	w-hydrate="interaction"	JS and heap wait; first use pays a cold wake
One offscreen singleton that may never be used	w-render="lazy" + reservation + w-hydrate="interaction"	Browser rendering, JS, and heap wait; first use pays the same cold wake

w-render="lazy" plus w-hydrate="lazy" remains invalid because rendering deferral already includes visibility hydration. The combined interaction form is code 4, retains content-visibility, and hydrates eagerly after its deferred module loads so click replay cannot race the visibility queue.

Paired performance evidence

All matrices used fresh Chromium processes, disabled cache, alternating case order, seven rounds, and three forced-GC passes before heap samples. Fast-4G used 40 ms latency, 10 Mbps down, and 5 Mbps up.

Visible WebUI todo boundary

Metric	Eager	Interaction	Delta
Executable JS before interaction	77,971 B	3,290 B	-95.8%
Forced-GC heap before interaction	1,415,320 B	1,117,392 B	-21.1%

Wake path	Local P50 / P95	Fast-4G P50 / P95
Pointer effect	9.4 / 22.3 ms	187.7 / 203.6 ms
Focus effect	19.0 / 21.9 ms	188.1 / 204.4 ms
Keyboard effect	21.5 / 24.6 ms	190.3 / 205.9 ms
Primary-click effect	21.8 / 22.7 ms	193.1 / 205.1 ms

Routed intent

Profile	Startup JS eager → intent	Heap eager → intent	Hit navigation eager → intent	Miss navigation eager → intent
Local	111,181 → 8,989 B (-91.9%)	1,434,128 → 1,168,140 B (-18.5%)	74.0 → 73.6 ms	43.1 → 58.6 ms
Fast-4G	108,512 → 8,989 B (-91.7%)	1,425,120 → 1,168,140 B (-18.0%)	75.3 → 218.8 ms	96.5 → 422.8 ms

Every hit/miss issued exactly one destination partial request. Cancellation replaced /alpha with /beta, aborted retained work, and still issued one /beta request.

1,000-row offscreen policy matrix

Fast-4G medians:

Policy	Pre-use JS	Pre-use heap	Initial layout	Layout objects	Initial task	First effect
Eager	73,964 B	1,447,760 B	14.079 ms	5,009	45.847 ms	0.2 ms
Lazy render	77,823 B	1,342,620 B	0.086 ms	5	26.565 ms	0.2 ms
Interaction	2,620 B	1,281,964 B	13.701 ms	5,009	42.175 ms	180.8 ms
Combined	2,620 B	1,281,964 B	0.101 ms	5	23.765 ms	180.2 ms

The combined form preserves interaction's -96.5% initial JS and -11.5% heap versus eager while eliminating 99.3% of initial offscreen layout time and 99.9% of layout objects. It adds no measured first-use cost over plain interaction. Lazy render remains the better choice when first-use latency matters.

Correctness

• pointer, focus, and keyboard start loading without cancellation
• an eligible primary click is cancelled and replayed once on its original composed-path target
• modified, non-cancelable, previously cancelled, and closed-shadow-ineligible clicks pass through
• native checkbox activation and nested/replaced boundary replay occur exactly once
• compiler markers are discovered through open Shadow DOM and released after terminal cleanup
• JSON and first-line NDJSON preloads transfer without early parse or duplicate fetch
• adopted navigation aborts, timeouts, malformed responses, stale inventory, and startup failure release owned resources
• router destroy/restart and superseded startup failures cannot poison a newer navigation

Validation

• pnpm --dir packages/webui-framework test
• pnpm --dir packages/webui-router test
• cargo xtask check
• independent framework, router, and compiler/protocol reviews completed with all findings addressed

Net PR diff: 45 files, +2,915 / -201.