fix: prevent stale navbar height cache causing scroll-spy URL mismatch on direct page load

[Copilot]

On direct page load/refresh, clicking a sidebar item correctly scrolls the content but sets the URL to the previous menu entry instead of the clicked one. SPA navigation is unaffected.

Root cause

Redoc's normalizeScrollYOffset captures the navbar height once at AppStore construction time when given a CSS selector string:

const r = t && t.getBoundingClientRect().bottom || 0;
return () => r; // stale closure

On direct load, Docusaurus's useIsBrowser() starts false then flips to true, triggering a second AppStore creation inside a useMemo during React's render phase — before the current render is committed. At that moment getBoundingClientRect() may return pre-commit navbar dimensions, so the cached scrollYOffset is wrong. The scroll-spy then resolves against the wrong threshold and activates item N-1 instead of N. SPA navigation always enters with isBrowser = true, so only one store is ever created, bypassing the window.

Fix

In useSpecOptions.ts, convert CSS selector strings to a dynamic function on the client instead of forwarding the raw string to Redoc. The function is invoked on every scroll event, reading the current navbar height from the DOM each time:

// before
scrollYOffset:
  !isBrowser && typeof redocOptions.scrollYOffset === 'string'
    ? 0
    : redocOptions.scrollYOffset,

// after
scrollYOffset:
  typeof redocOptions.scrollYOffset === 'string'
    ? !isBrowser
      ? 0
      : () =>
          (document.querySelector(redocOptions.scrollYOffset) as HTMLElement)
            ?.clientHeight ?? 0
    : redocOptions.scrollYOffset,

• Number and function values pass through unchanged.
• Server-side rendering still receives 0 (no DOM).
• defaultOptions.scrollYOffset in redocData.ts remains 'nav.navbar' (must be JSON-serialisable plugin data).

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• redocly.github.io
  • Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node /opt/hostedtoolcache/node/24.14.0/x64/bin/node /home/REDACTED/work/redocusaurus/redocusaurus/node_modules/@docusaurus/core/bin/docusaurus.mjs build git conf�� ect\|window\|document edocusaurus/packages/redocusaurus/src/plugin.ts p/bin/bash commit.gpgsign (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 714ad5d

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.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
redocusaurus	Error		Mar 30, 2026 10:55pm