fix: restore anchor scrolling on initial page load (CLO-805)

[roomote]

Fixes deep-linking to doc sub-sections (anchor links like #commands).

Problem

Docusaurus's built-in scroll handler skips hash-based scrolling on initial page load because previousLocation is null. It assumes the browser handles native hash scrolling, but React hydration resets the scroll position before the browser finishes its native anchor scroll. This means URLs like docs.roocode.com/roo-code-cloud/environments#commands land at the top of the page instead of the targeted section.

Solution

Added a Docusaurus clientModule (src/clientModules/scrollToAnchor.ts) that explicitly scrolls to the hash target after hydration settles:

• Only runs on initial page load (when previousLocation is null) so it does not duplicate the core router's behavior for subsequent navigations
• Uses requestAnimationFrame to wait for the DOM to settle after hydration
• Falls back to a retry after 150ms for lazily-rendered content
• Uses scrollIntoView() which respects the scroll-margin-top already set by Docusaurus's anchorTargetStickyNavbar class

Changes

• src/clientModules/scrollToAnchor.ts -- new client module
• docusaurus.config.ts -- registers the client module via clientModules

Verification

• pnpm build passes
• pnpm run check-types passes
• pnpm run lint passes
• Client module confirmed present in built JS bundle

---

View task on Roo Code Cloud

---

Important

Fixes initial page load hash-based scrolling in Docusaurus by adding a client module to handle scrolling after React hydration.

• Behavior:
  • Fixes hash-based scrolling on initial page load by adding scrollToAnchorModule in src/clientModules/scrollToAnchor.ts.
  • Uses requestAnimationFrame and a 150ms retry to ensure scrolling after React hydration.
  • Only activates when previousLocation is null to avoid interfering with subsequent navigations.
• Configuration:
  • Registers scrollToAnchorModule in docusaurus.config.ts under clientModules.

^{This description was created by for 6725136. You can customize this summary. It will automatically update as commits are pushed.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
roo-code-docs	Ready	Preview, Comment	Feb 9, 2026 1:52pm

[roomote]

Rooviewer   See task

Reviewed the anchor scrolling fix. One minor defensive-coding issue found:

• decodeURIComponent in scrollToAnchor.ts can throw URIError on malformed hashes -- wrap in try-catch

_{Mention @roomote in a comment to request specific changes to this pull request or fix all unresolved issues.}

[roomote]

decodeURIComponent throws a URIError when the hash contains a malformed percent-encoded sequence (e.g. #%ZZ). If someone shares or bookmarks such a URL, the unhandled exception would crash this callback and could prevent other client module hooks from running. Wrapping it in a try-catch keeps things defensive.

Suggested change

	const id = decodeURIComponent(hash.substring(1));
	if (!id) {
	return;
	}
	let id: string;
	try {
	id = decodeURIComponent(hash.substring(1));
	} catch {
	return;
	}
	if (!id) {
	return;
	}

_{Fix it with Roo Code or mention @roomote and request a fix.}

[roomote]

Rooviewer   See task

Reviewed the anchor scrolling fix. Implementation correctly uses the ClientModule interface, properly gates on initial page load, and the requestAnimationFrame + retry strategy is sound. No new issues found beyond the prior review.

• decodeURIComponent in scrollToAnchor.ts can throw URIError on malformed hashes -- wrap in try-catch (flagged in prior review)

_{Mention @roomote in a comment to request specific changes to this pull request or fix all unresolved issues.}