fix(docs): re-run home scroll-reveal after View Transitions navigation

[IEvangelist]

Summary

The home page scroll‑reveal sections (the "Why Squad?" features grid and everything below the hero) disappear and never come back after you navigate away from the home page and return to it via Astro View Transitions.

Reproduction (on the live site, https://bradygaster.github.io/squad/):

1. Land on the home page.
2. Open search (Ctrl/Cmd+K), type a query, and click a result.
3. Click the Squad logo to return home.
4. Scroll down — the reveal sections under the hero stay blank.

Root cause

BaseLayout.astro enables <ViewTransitions /> (the Astro client router), so in‑site navigation swaps the DOM instead of doing a full page reload.

The reveal effect works like this:

• .reveal elements start at opacity: 0; transform: translateY(24px) (docs/src/styles/global.css).
• An IntersectionObserver adds the .visible class when they scroll into view, which animates them to opacity: 1.

That observer was created in a module <script> in docs/src/pages/index.astro. Module scripts are evaluated only once per session. When you navigate back to the home page via a View Transition, fresh .reveal nodes are swapped in, but the script never re‑runs — so nothing observes the new elements and they remain at opacity: 0.

Notably, the rest of the codebase already handles this correctly: Search.astro and BaseLayout.astro re‑initialize their DOM‑dependent logic on the astro:page-load event (which fires on initial load and after every View Transition). The home page script was the one place that didn't follow that convention.

Fix

Wrap the home page script in an initHomePage() function registered on astro:page-load, mirroring the existing convention:

• The IntersectionObserver is disconnect()‑ed before being recreated, so re‑runs don't leak observers.
• The copy‑install button handler is assigned via onclick (idempotent) instead of addEventListener, so it can't accumulate duplicate listeners.

function initHomePage() {
  const copyBtn = document.getElementById('copy-install');
  if (copyBtn) { copyBtn.onclick = async () => { /* copy install command */ }; }

  revealObserver?.disconnect();
  revealObserver = new IntersectionObserver(/* …adds .visible… */, { threshold: 0.1, rootMargin: '0px 0px -40px 0px' });
  document.querySelectorAll('.reveal').forEach(el => revealObserver.observe(el));
}

// Fires on initial load AND after every View Transition navigation.
document.addEventListener('astro:page-load', initHomePage);

Testing

Added docs/tests/hero-reveal.spec.mjs (Playwright) with three cases:

1. Reveal sections animate in on initial load.
2. Reveal sections still animate in after navigating away and back (the regression).
3. Reveal sections animate in when reaching home for the first time via a View Transition (script loaded mid‑transition).

Running 3 tests using 1 worker
  ✓ home reveal sections animate in on initial load
  ✓ home reveal sections still animate in after navigating away and back
  ✓ home reveal sections animate in when reaching home via View Transition
  3 passed

Test 2 fails on dev and passes with this change. Verified on a production build (astro build + astro preview) by running the exact repro flow:

State	First .reveal section after returning home	Result
Before (this branch's parent)	class="… reveal", opacity = 0	Section blank/invisible
After (this branch)	class="… reveal visible", opacity = 1	Section fully visible

The rest of the existing docs suite is unaffected by this change. (The api-reference.spec.mjs cases fail locally only because the generated API‑reference pages aren't produced outside CI; they're unrelated to this change.)

Scope / follow‑up

This PR is intentionally scoped to the reported hero‑reveal regression. While investigating I noticed Header.astro binds its mobile‑nav / sidebar toggle in a top‑level script without astro:page-load, which is the same latent pattern and likely affects the mobile menu after a View Transition. That's a separate concern (different feature) and is left for a follow‑up.

Files changed

• docs/src/pages/index.astro — re‑run reveal/copy logic on astro:page-load.
• docs/tests/hero-reveal.spec.mjs — regression coverage (new).

[github-actions]

🟢 Impact Analysis — PR #1215

Risk tier: 🟢 LOW

📊 Summary

Metric	Count
Files changed	2
Files added	1
Files modified	1
Files deleted	0
Modules touched	1

🎯 Risk Factors

• 2 files changed (≤5 → LOW)
• 1 module(s) touched (≤1 → LOW)

📦 Modules Affected

docs (2 files)

• docs/src/pages/index.astro
• docs/tests/hero-reveal.spec.mjs

---

This report is generated automatically for every PR. See #733 for details.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 02b8736

PR Scope: 🔧 Infrastructure

⚠️ 1 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	No source files changed — changeset not required
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	No Copilot review threads
✅	CI passing	All checks passing

Files Changed (2 files, +104 −17)

File	+/−
docs/src/pages/index.astro	+31 −17
docs/tests/hero-reveal.spec.mjs	+73 −0

Total: +104 −17

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[Copilot]

Pull request overview

Fixes a docs-site regression where home-page “scroll reveal” sections remain invisible after navigating away and back via Astro View Transitions by re-initializing the home page’s DOM-dependent logic on astro:page-load. Adds Playwright coverage to prevent regressions across initial load, away-and-back navigation, and first-time arrival to home via a View Transition.

Changes:

• Reworks the home page script to run reveal/copy setup in an initHomePage() handler on astro:page-load, with observer teardown to avoid leaks.
• Ensures the install-copy handler is idempotent across repeated inits.
• Adds Playwright regression tests that reproduce the View Transitions navigation path and assert reveal sections become visible.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
docs/src/pages/index.astro	Re-initializes the reveal IntersectionObserver (and copy button handler) on astro:page-load so newly swapped DOM is observed after View Transitions.
docs/tests/hero-reveal.spec.mjs	Adds regression Playwright tests covering initial load and View Transitions navigation scenarios for home-page reveal behavior.