perf(start): compact deferred hydration private state

[Sheraff]

Summary

• shorten descriptive, module-private prefetch-controller keys in Solid's generic hydrator
• replace two one-field closure state wrappers with named locals while preserving synchronous-cleanup behavior
• store private visible-observer registry entries as labeled tuples, destructured immediately at use sites
• add focused lifecycle coverage for synchronous completion, races, cleanup-once behavior, observer sharing, teardown, and recreation

Public APIs and declaration-facing types are unchanged. The controller keys are Solid-only; the representation changes in Start client core retain the same React and Solid behavior.

Bundle impact

Scenario	Raw	Initial gzip	Gzip	Brotli
solid-start.deferred-hydration	-361 B	0 B	-55 B	-119 B

The other 16 bundle scenarios are byte-identical. Each production hunk independently improves raw and gzip size; the composed result was remeasured in the full matrix.

Validation

• Start client core: 86 unit tests passed; type suite passed on TS 5.6 through 7.0; ESLint has 0 errors
• Solid Start client: 8 unit tests passed; type suite passed on TS 5.6 through 7.0; ESLint passed
• deferred-hydration e2e: 45 tests passed across Vite SSR, Rsbuild SSR, and Vite
• full 17-scenario bundle matrix passed
• five independent review passes approved semantics, observer lifecycle, attribution, publishability, and maintainability

Full attribution and validation details are in RESULT-optimization-solid-hydration-private-state.md.

Summary by CodeRabbit

• Bug Fixes
  • Improved hydration prefetch handling when operations complete immediately or are interrupted.
  • Prevented hydration strategies from starting after cancellation.
  • Improved cleanup reliability to avoid repeated or incomplete resource disposal.
  • Preserved consistent visible-content hydration behavior when multiple elements are observed or cleaned up.
• Tests
  • Added coverage for hydration timing, cancellation, cleanup, visibility tracking, and observer lifecycle scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2c0a5b27-bb9e-48a3-b855-7589da7f083e

📥 Commits

Reviewing files that changed from the base of the PR and between 222834d and 6985f84.

📒 Files selected for processing (1)

• .changeset/shaky-berries-admire.md

---

📝 Walkthrough

Walkthrough

The changes update hydration prefetch cleanup handling, refactor visible observer registry entries into tuples, rename Solid hydration controller fields, and add tests for synchronous completion, races, aborts, observer sharing, and cleanup.

Changes

Hydration prefetch maintenance

Layer / File(s)	Summary
Prefetch settlement and cleanup packages/start-client-core/src/hydration/runtime.ts, packages/start-client-core/tests/hydration-runtime.test.ts, .changeset/shaky-berries-admire.md	The runtime stores disposal state directly, runs cleanup after synchronous completion, ignores repeated completion, and handles abort races and already-aborted signals. Tests cover these behaviors. The changeset records patch releases for both affected packages.
Visible observer registry packages/start-client-core/src/hydration/visible.ts, packages/start-client-core/tests/hydration-visible.test.ts	Visible observer entries use [observer, elements] tuples. Tests cover shared observers, callback removal, disconnection, and observer replacement.
Solid hydration controller alignment packages/solid-start-client/src/GenericHydrate.tsx	Hydration-prefetch logic uses the renamed abort, listeners, requested, and resolvePending controller fields.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: reducing private deferred-hydration state.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/solid-hydration-private-state

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 9c44de1

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	21m 23s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	2m 25s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-08-06 15:20:48 UTC

[github-actions]

🚀 Changeset Version Preview

2 package(s) bumped directly, 12 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/solid-start-client	1.168.19 → 1.168.20	Changeset
@tanstack/start-client-core	1.170.17 → 1.170.18	Changeset
@tanstack/react-start	1.168.38 → 1.168.39	Dependent
@tanstack/react-start-client	1.168.19 → 1.168.20	Dependent
@tanstack/react-start-rsc	0.1.37 → 0.1.38	Dependent
@tanstack/react-start-server	1.167.26 → 1.167.27	Dependent
@tanstack/solid-start	1.168.37 → 1.168.38	Dependent
@tanstack/solid-start-server	1.167.26 → 1.167.27	Dependent
@tanstack/start-plugin-core	1.171.29 → 1.171.30	Dependent
@tanstack/start-server-core	1.169.21 → 1.169.22	Dependent
@tanstack/start-static-server-functions	1.167.22 → 1.167.23	Dependent
@tanstack/vue-start	1.168.36 → 1.168.37	Dependent
@tanstack/vue-start-client	1.167.22 → 1.167.23	Dependent
@tanstack/vue-start-server	1.167.26 → 1.167.27	Dependent

[github-actions]

Bundle Size Benchmarks

• Commit: b08629334216
• Measured at: 2026-08-06T15:00:34.029Z
• Baseline source: history:abf9b81b1f14
• Dashboard: bundle-size history

The following scenarios have bundle-size changes compared with the baseline:

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
solid-start.deferred-hydration	51.14 KiB	-56 B (-0.11%)	47.86 KiB	148.35 KiB	45.54 KiB	████▂▂▂▂▁▁▁▁

Current gzip tracks all emitted client JS chunks. Initial gzip tracks only the entry/import graph. Trend sparkline is historical current gzip ending with this PR measurement; lower is better.

[pkg-pr-new]

More templates

• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsbuild
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-example-rscs
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query
• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc
• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc

@tanstack/arktype-adapter

npm i https://pkg.pr.new/@tanstack/arktype-adapter@7980

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@7980

@tanstack/eslint-plugin-start

npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@7980

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@7980

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/@tanstack/nitro-v2-vite-plugin@7980

@tanstack/react-router

npm i https://pkg.pr.new/@tanstack/react-router@7980

@tanstack/react-router-devtools

npm i https://pkg.pr.new/@tanstack/react-router-devtools@7980

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@7980

@tanstack/react-start

npm i https://pkg.pr.new/@tanstack/react-start@7980

@tanstack/react-start-client

npm i https://pkg.pr.new/@tanstack/react-start-client@7980

@tanstack/react-start-rsc

npm i https://pkg.pr.new/@tanstack/react-start-rsc@7980

@tanstack/react-start-server

npm i https://pkg.pr.new/@tanstack/react-start-server@7980

@tanstack/router-cli

npm i https://pkg.pr.new/@tanstack/router-cli@7980

@tanstack/router-core

npm i https://pkg.pr.new/@tanstack/router-core@7980

@tanstack/router-devtools

npm i https://pkg.pr.new/@tanstack/router-devtools@7980

@tanstack/router-devtools-core

npm i https://pkg.pr.new/@tanstack/router-devtools-core@7980

@tanstack/router-generator

npm i https://pkg.pr.new/@tanstack/router-generator@7980

@tanstack/router-plugin

npm i https://pkg.pr.new/@tanstack/router-plugin@7980

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@7980

@tanstack/router-utils

npm i https://pkg.pr.new/@tanstack/router-utils@7980

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/@tanstack/router-vite-plugin@7980

@tanstack/solid-router

npm i https://pkg.pr.new/@tanstack/solid-router@7980

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/@tanstack/solid-router-devtools@7980

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@7980

@tanstack/solid-start

npm i https://pkg.pr.new/@tanstack/solid-start@7980

@tanstack/solid-start-client

npm i https://pkg.pr.new/@tanstack/solid-start-client@7980

@tanstack/solid-start-server

npm i https://pkg.pr.new/@tanstack/solid-start-server@7980

@tanstack/start-client-core

npm i https://pkg.pr.new/@tanstack/start-client-core@7980

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/@tanstack/start-fn-stubs@7980

@tanstack/start-plugin-core

npm i https://pkg.pr.new/@tanstack/start-plugin-core@7980

@tanstack/start-server-core

npm i https://pkg.pr.new/@tanstack/start-server-core@7980

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/@tanstack/start-static-server-functions@7980

@tanstack/start-storage-context

npm i https://pkg.pr.new/@tanstack/start-storage-context@7980

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@7980

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@7980

@tanstack/vue-router

npm i https://pkg.pr.new/@tanstack/vue-router@7980

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/@tanstack/vue-router-devtools@7980

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@7980

@tanstack/vue-start

npm i https://pkg.pr.new/@tanstack/vue-start@7980

@tanstack/vue-start-client

npm i https://pkg.pr.new/@tanstack/vue-start-client@7980

@tanstack/vue-start-server

npm i https://pkg.pr.new/@tanstack/vue-start-server@7980

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@7980

commit: 9c44de1

[codspeed-hq]

Merging this PR will regress 5 benchmarks

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 4 improved benchmarks
❌ 5 regressed benchmarks
✅ 165 untouched benchmarks
⏩ 6 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	Memory	mem server error-paths not-found (solid)	416.9 KB	746.7 KB	-44.17%
❌	Memory	mem server serialization-payload (react)	3.3 MB	3.6 MB	-8.16%
❌	Memory	mem server error-paths redirect (solid)	273.1 KB	288.9 KB	-5.48%
❌	Memory	mem server server-fn-churn (react)	265 KB	276.1 KB	-4.02%
❌	Memory	mem server error-paths unmatched (react)	263.2 KB	272.2 KB	-3.3%
⚡	Memory	mem server request-churn (react)	940 KB	498.4 KB	+88.62%
⚡	Memory	mem server error-paths redirect (vue)	358.2 KB	293 KB	+22.24%
⚡	Memory	mem client unique-location-churn (react)	762.5 KB	665 KB	+14.66%
⚡	Memory	mem server server-fn-churn (vue)	274.7 KB	263.1 KB	+4.4%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing codex/solid-hydration-private-state (9c44de1) with main (abf9b81)}

Footnotes

1. 6 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩