fix: preserve client navigation lifecycles across pages and deployments

[David Pine (IEvangelist)]

Summary

Follow-up to #1675. Keep <ClientRouter fallback="swap" /> and uninterrupted native PiP during normal browsing, while explicitly managing page-owned JavaScript and deployment changes.

Fresh production search and Twoslash work. The reported failures were reproduced by carrying the old runtime into newer HTML: the old search class remained registered, shortcuts referenced detached dialogs, and the old Twoslash workaround removed newly attached hover listeners. Fetching new HTML does not reset the running JavaScript environment.

Changes

• Use Astro's preparation loader and cancellation API to reload across deployment versions. Same-version browsing remains client-side; deployment reloads intentionally close PiP.
• Preserve the selected theme and Astro history metadata across navigation.
• Dispose pivot and install-dialog listeners/timers with their owning page. Keep floating pivot controls below the responsive table of contents.
• Remove astro-mermaid, starlight-scroll-to-top, and both proposed patches. Render diagrams through the existing mermaid dependency and a small remark transform. Use a native scroll-to-top component instead of patching plugin internals.
• Keep diagram loading lazy, serialize theme/render work, discard stale completions, and preserve visible errors. Keep scroll controls localized and usable with mouse, touch, Enter, and Space.
• Configure 1DS to exclude unload without disabling other lifecycle flushing or click capture. Remove routine analytics chatter, not error reporting.
• Add regression coverage and document lifecycle ownership using the official Astro APIs.

No new dependency patches or compatibility framework are introduced. The pre-existing Starlight and icon-cache patches are unchanged.

The Edge lazy-image notice is informational. The evaluated-script reportAllChanges/startTime exception remains unattributed; this PR does not claim to fix it.

Third-party links and affiliations

Links to Astro's official documentation as the implementation reference. No commercial or sponsored links are added.

Validation

• 55 focused unit tests passed, including Markdown/MDX output and localized component rendering.
• 12 UI browser scenarios passed on Astro dev across desktop, tablet, and mobile, covering diagram themes, repeated navigation/history, and native scroll activation.
• Scoped TypeScript, typed ESLint, and frozen-lockfile installation passed. Remaining dependency versions and resolution metadata are unchanged.
• Full production rebuild and production-browser confirmation of the patch-free revision are in progress. Earlier production results from the patched revision are not claimed as validation of this replacement.

[Copilot]

🟡 Changes recommended

Mermaid error styling and stale contributor guidance still need updates before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR makes Astro client navigation lifecycle-aware, preserves state across same-deployment navigation, and replaces plugin-owned Mermaid and scroll-to-top behavior.

Changes:

• Adds deployment-aware reloads, theme/history preservation, and lifecycle cleanup.
• Adds site-owned Mermaid, pivot, modal, and scroll implementations.
• Adds unit/E2E regression coverage and updates configuration and dependencies.

File summaries

File	Summary
src/frontend/tests/unit/site-ui-runtime.vitest.test.ts	Mermaid and scroll runtime tests
src/frontend/tests/unit/remark-mermaid.vitest.test.ts	Mermaid Markdown/MDX transform tests
src/frontend/tests/unit/pivot-selector-lifecycle.vitest.test.ts	Pivot lifecycle tests
src/frontend/tests/unit/navigation-theme.vitest.test.ts	Theme preservation tests
src/frontend/tests/unit/deployment-guard.vitest.test.ts	Deployment guard tests
src/frontend/tests/unit/custom-components.vitest.test.ts	Custom component tests
src/frontend/tests/unit/analytics-script-contracts.vitest.test.ts	Analytics contract tests
src/frontend/tests/e2e/site-ui-navigation.spec.ts	Navigation and UI regression scenarios
src/frontend/tests/e2e/pivot-selector.spec.ts	Pivot navigation and responsive scenarios
src/frontend/tests/e2e/install-modal-navigation.spec.ts	Modal lifecycle scenarios
src/frontend/tests/e2e/deployment-navigation.spec.ts	Deployment reload and PiP scenarios
src/frontend/src/styles/mermaid.css	Mermaid loading and error styling; error styling needs to move outside the reduced-motion media block
src/frontend/src/scripts/mermaid.ts	Lazy, serialized Mermaid rendering
src/frontend/src/scripts/deployment-guard.ts	Deployment-boundary navigation handling
src/frontend/src/components/starlight/Head.astro	Router, theme, history, and runtime integration
src/frontend/src/components/starlight/Footer.astro	Scroll control placement
src/frontend/src/components/ScrollToTop.astro	Native accessible scroll control
src/frontend/src/components/PivotSelector.astro	Pivot markup and responsive styling
src/frontend/src/components/pivot-selector.ts	Pivot lifecycle management
src/frontend/src/components/InstallCliModal.astro	Modal listener cleanup
src/frontend/public/scripts/analytics/track.js	Analytics logging behavior
src/frontend/public/scripts/analytics/1ds.js	Analytics lifecycle configuration
src/frontend/pnpm-lock.yaml	Dependency lockfile updates
src/frontend/package.json	Removed plugin dependencies; contributor guidance also needs updating
src/frontend/config/remark-mermaid.mjs	Mermaid fence transformation
src/frontend/config/icon-packs.mjs	Lazy icon-pack configuration
src/frontend/astro.config.mjs	Plugin and remark configuration

Review details

Files not reviewed (1)

• src/frontend/pnpm-lock.yaml: Generated file

Suppressed comments (1)

src/frontend/package.json:84

• Removing these integrations leaves .github/astro.instructions.md:76-90 claiming both starlight-scroll-to-top and astro-mermaid are configured plugins. Please update that contributor guidance in the same change so it does not describe packages this PR has removed.

    "astro-expressive-code": "^0.44.1",
    "astro-tooltips": "^0.6.2",

• Files reviewed: 26/27 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1681. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

[James Newton-King (JamesNK)]

Reviewed at a1a767962af710f40d1b34d9702e02ee84efddc5. The exact-head production build, unit suite, and desktop/tablet/mobile Playwright runs are green. Approving with two inline follow-up comments covering fresh-load initialization timing and the light-mode Mermaid palette.