feat: avoid re-evaluating the hydrate platform closure on every SSR render

[Armand-Lluka]

Prerequisites

• I have read the Contributing Guidelines.
• I agree to follow the Code of Conduct.
• I have searched for existing issues that already include this feature request, without success.

Describe the Feature Request

Every call to renderToString() / hydrateDocument() from the dist-hydrate-script output re-executes hydrateAppClosure and constructs a fresh MockWindow. hydrateAppClosure is the function in the generated hydrate module that wraps the whole Stencil platform (runtime, vdom) and every component class in the library. The closure exists so the platform can capture the per-call window/document, but re-evaluating it on each render is a fixed cost that scales with the size of the component library rather than with the content being rendered.

This request is for two changes:

1. Cache the evaluated closure per window (transparent, no API change): in HYDRATE_FACTORY_OUTRO, store the result of hydrateAppClosure(win) on the window object and reuse it when the same window is passed again.
2. Add an opt-in reuseWindow?: boolean hydrate option. When set, hydrateDocument/renderToString reuse a pooled MockWindow across calls instead of creating and destroying one per render. The pool is keyed by the serializeShadowRoot configuration, because 'scoped' permanently ORs shadowNeedsScopedCss into cmpMeta flags inside the evaluated closure. Fresh head/body elements are swapped in per render, so the rootAppliedStyles WeakMap (keyed on the head node) resets correctly, and renders against a shared window are serialized through an internal queue.

Describe the Use Case

We maintain a design system (~300 shadow components, hydrate module >10 MB) consumed by high-traffic Next.js (App Router) sites via @stencil/react-output-target. Its SSR integration (createComponentForServerSideRendering) calls renderToString once per component boundary in the React tree, so a page with 150 Stencil component boundaries pays the fixed per-call overhead 150 times per request.

Measured with the attached reproduction (300 components, @stencil/core 4.43.5, Node 22):

• The fixed overhead is ~0.5 ms median per renderToString call. A page with one component instance costs 6% of a page with 200 instances, so the per-call cost comes from platform re-evaluation and window construction, not from rendering.
• A simulated request (150 component boundaries) spends ~54-62 ms in pure hydrate overhead before any application work.
• A CPU profile of 500 small renders under the V8 sampling profiler puts 42-49% of all sampled time inside hydrateAppClosure (platform re-evaluation, with registerComponents alone at 19.6% self time), plus ~17% in garbage collection caused by the allocation churn. MockWindow construction is ~6.5%.
• With both proposed changes the simulated request drops to 7.9 ms (6.7x), the p95 of single-component renders drops from 1.60 ms to 0.19 ms, and hydrateAppClosure and MockWindow fall to 0.0% of profile samples.

Single large one-shot renders are unaffected (1.03x), since their time is real rendering work. The win is specific to the many-small-renders SSR pattern that production React/Next.js integrations use.

Describe Preferred Solution

Implementation is complete on a branch (test/hydrate-platform-reuse, happy to open a PR):

• src/compiler/output-targets/dist-hydrate-script/hydrate-factory-closure.ts caches hydrateAppClosure(win) on the window object in the factory outro.
• src/hydrate/runner/render.ts adds the reuseWindow support: a Map of pooled MockWindows keyed by serialized serializeShadowRoot options. Per render, fresh head/body elements are swapped in via replaceChild and the render is queued behind any in-flight render on the same window. destroyWindow/destroyDocument are forced off for pooled windows.
• src/declarations/stencil-public-compiler.ts documents the new reuseWindow?: boolean option on HydrateDocumentOptions (default false, fully backwards compatible).

Existing test suites pass (test.jest, test.end-to-end).

Describe Alternatives

• Userland window pooling via the existing destroyWindow: false option is not enough. The platform closure is still re-evaluated per call (the cache in change 1 is not reachable from userland), and internal state such as rootAppliedStyles and the mode/flag mutations under serializeShadowRoot: 'scoped' make naive window reuse incorrect.
• Caching rendered HTML at the application layer only helps repeated identical pages; personalised and dynamic pages still pay the full cost.

Related Code

Reproduction repo: https://github.com/Armand-Lluka/stencil-hydrate-perf-repro. Run npm install && npm run generate && npm run build && npm run bench. The benchmark prints the baseline table above and, when run against a build containing the proposed changes, a comparison section. node profile.mjs produces the CPU profile attribution.

Additional Information

• The closure cache (change 1) alone benefits any consumer that passes the same window twice; reuseWindow (change 2) is what makes it reachable through the public renderToString/hydrateDocument API.
• Concurrency: parallel renderToString calls with reuseWindow: true are serialized per pooled window; callers wanting parallelism can keep the default behaviour.

[Armand-Lluka]

Our team would love to get something like this in since this would be part of a greater effort in improving SSR, especially for the next.js output-target, performance.

I've opened a PR with changes here: #6794

There is also a benchmark in the repro highlighting why I believe this to be necessary.

If anyone could take a look at this it would be greatly appreciated, happy to take feedback onboard & refine further 👍

@johnjenkins