fix: restore docs width before first paint

[tannerlinsley]

Saved expanded docs currently render at 900px before hydration restores the full width. Read the existing preference in the document head and use a CSS width variable so the server-rendered content starts at the right width. The toggle updates that variable and keeps the existing React state and persistence behavior. Missing, expired, invalid or unavailable storage retains the constrained default.

Fixes #948. Thanks to @azizbecha for the original report and the prepaint restoration approach in azizbecha#1.

Verified on current main in a credential-free local app with default Redact. Frame samples at 1700 × 950 reproduced 900px → 1240px before the fix. With the fix, expanded reloads stayed at 1240px from the first sampled frame through hydration, and constrained reloads stayed at 900px. Repeated toggles, navigation between Overview and Quick Start, and the 375px layout also passed. Navigation used public Router docs through the existing local-docs bridge after an unauthenticated GitHub fetch failed.

pnpm test passed: typechecking, lint, 552 unit tests, 2,269 chat tests and 20 desktop tests, with 4 unit and 1 desktop skips. Three new tests cover initial restoration, expiry and unavailable storage. Browser measurements were on the development app, not a deployed production build.

Summary by CodeRabbit

• New Features
  • Documentation pages now apply the saved full-width preference as the page loads, reducing layout shifts for readers who use that setting.
  • Switching between full-width and standard layouts updates the content width immediately; the standard layout remains 900px wide.
• Bug Fixes
  • Invalid, expired, or unavailable saved preferences no longer prevent the documentation page from initializing.

[changeset-bot]

⚠️ No Changeset found

Latest commit: c8f8318

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

📝 Walkthrough

The docs layout now updates its content-width CSS property when the width toggle changes. An inline head script applies an eligible saved full-width preference during document setup. Tests cover valid, invalid, expired, and unavailable storage cases.

Changes: Docs content width

Layer / File(s)	Summary
Restore saved width preference src/utils/docs-width.ts, src/routes/__root.tsx, tests/docs-width.test.ts	The document head runs a bootstrap script that reads the saved preference. It applies full width when the saved value is true and its TTL is absent or unexpired. Tests cover qualifying and non-qualifying values, expired preferences, and storage errors.
Update width from the layout toggle src/components/LibraryLayout.tsx	The toggle setter sets the CSS property to 100% or 900px. The content container uses that property, with a 900px default.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Low

Suggested reviewers: abeuty

Merge Risk: ⚪ Minimal · up to c8f83

The saved docs width and toggle use consistent values. No actionable merge-blocking risk is established.

Pre-merge checks: 3 · 2

Failed checks: 2 warnings

Check name	Status	Explanation	Resolution
Linked Issues check		Direct issue [#948] has three coding requirements: repeated clicks must continue to toggle the width, the icon must reflect the state, and the saved expanded width must apply before first paint. The P…	Update the width toggle so repeated clicks change the layout in both directions and the icon reflects isFullWidth. Add automated coverage for repeated toggles and icon state. Retain the prepaint restoration coverage.
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 3 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the primary change: restoring the saved documentation width before the first paint.
Out of Scope Changes check		The changed files support [#948]. LibraryLayout applies the width variable during toggle changes, __root.tsx injects the bootstrap script, docs-width.ts defines the restoration logic, and `tests…

Full details: Linked Issues check

Explanation

Direct issue [#948] has three coding requirements: repeated clicks must continue to toggle the width, the icon must reflect the state, and the saved expanded width must apply before first paint. The PR implements the prepaint width restoration through DOCS_WIDTH_BOOTSTRAP, the --docs-content-width CSS variable, and tests for saved, expired, invalid, and unavailable storage. The supplied change summary and PR objectives do not show a fix or automated test for the repeated-click or icon-update defects.

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	tanstack-com	c8f8318	Oct 15 2026, 11:21 PM

[coderabbitai]

🔇 Additional comments: 5

src/utils/docs-width.ts: 1

3-3: LGTM!

src/routes/__root.tsx: 1

58-58: LGTM!

The static analysis hint on Line 360 is a false positive. DOCS_WIDTH_BOOTSTRAP is a compile-time constant and does not contain user input. The existing THEME_BOOTSTRAP script uses the same pattern.

Also applies to: 360-360

tests/docs-width.test.ts: 1

25-25: Test coverage is acceptable. The test clock is deterministic.

Date.now is stubbed to a fixed value of 1000, so the TTL tests do not depend on system time. This matches the retrieved learning on deterministic time-based tests.

src/components/LibraryLayout.tsx: 2

1448-1454: 🎯 Functional Correctness

The setter and bootstrap script use compatible values and storage formats. useLocalStorage stores { value, ttl: null } when no TTL is supplied. The bootstrap script accepts that shape. It writes 100% for value: true; the constrained state uses the existing 900px CSS fallback. No change is required.

---

1448-1454: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

⚠️ Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

Move the width values into shared constants.

The setter hard-codes '100%' and '900px'. The container class on Line 1494 repeats 900px as the CSS fallback. The bootstrap script in src/utils/docs-width.ts likely sets the same variable. These values can drift apart. Export the widths from src/utils/docs-width.ts and reuse them here. Use a CSS variable default in the stylesheet for the class fallback.

The change is optional. The code works now.

Source: Learnings

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 76f39907-e626-4d77-b639-5ba14fd8f0c0

📥 Commits

Reviewing files that changed from the base of the PR and between b416acb and c8f8318.

📒 Files selected for processing: 4

• src/components/LibraryLayout.tsx
• src/routes/__root.tsx
• src/utils/docs-width.ts
• tests/docs-width.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.