refactor(nav): unify section-id vocabulary + make off-route detection explicit

[yigitdot]

Follow-up from the PR #159 review (fix #157). Two related, non-blocking improvements deferred out of that bugfix's scope.

1. Unify the section-id vocabulary

"intro" and the section-id set are currently declared in three unrelated places with no compile-time link:

• lib/scroll.ts — HOME_SECTION_ID = "intro"
• components/site/Chrome.tsx — SECTION_IDS = ["intro", "compare", "method", "faq", "contact"]
• components/site/MobileMenu.tsx — type SectionId = "intro" | "compare" | ...

Renaming the hero section id today means editing three files in lockstep with no type error to catch a miss.

Proposal: export a single SectionId union + SECTION_IDS tuple from lib/ (e.g. lib/scroll.ts or a sibling), import it in both components, and define HOME_SECTION_ID as a member of it. HomeNavTarget's section.id could then narrow to Exclude<SectionId, typeof HOME_SECTION_ID>. Touches the active-section observer typing in Chrome.tsx, so it's a deliberate refactor rather than a one-liner.

2. Make the off-route discriminator explicit

Both nav codepaths decide "am I off-route?" by element absence:

• components/site/Chrome.tsx:70 — if (document.getElementById(HOME_SECTION_ID) === null) return;
• components/site/MobileMenu.tsx cleanup — if (anchor && !targetEl) window.location.assign(...)

Correct today because every nav target is a synchronously-rendered home section and the Hero always mounts on /. But the check can't distinguish "wrong route" from "right route, target not mounted": a future lazy/Suspense-mounted target tapped on the home page would be misread as off-route and silently hard-reload (and the desktop return path could become a no-op dead-click if the Hero ever failed to mount).

Proposal: key the off-route branch on actual route mismatch (e.g. via usePathname(), already used in Chrome.tsx) rather than element absence, and/or extract a small testable isOnHomeRoute() / resolveLocalTarget() helper so the off-route-vs-missing distinction is explicit and unit-testable.

Both surfaced by the multi-agent review on #159; neither is a live bug.

[github-actions]

🎯 Agentic Issue Triage

Two related code-quality improvements deferred from PR #159 (fix #157). Neither is a live bug — both reduce future maintenance risk and improve TypeScript safety in the nav subsystem.

Item 1 centralises the section-id vocabulary into a single lib/ source of truth to prevent silent mismatches on future renames. Item 2 decouples off-route detection from DOM element presence to prevent a misclassification if any section ever becomes lazy/Suspense-mounted.

📐 Implementation sketch

Item 1 — Unify section-id vocabulary

Create (or expand) a lib/nav.ts (or add to lib/scroll.ts) exporting:

// lib/nav.ts
export const SECTION_IDS = [
  "intro",
  "compare",
  "method",
  "faq",
  "contact",
] as const;

export type SectionId = (typeof SECTION_IDS)[number];
export const HOME_SECTION_ID = "intro" satisfies SectionId;

Then update consumers:

• lib/scroll.ts — remove or re-export HOME_SECTION_ID from the shared module.
• components/site/Chrome.tsx — replace the local SECTION_IDS as const array with the imported one; the (typeof SECTION_IDS)[number] usages then resolve automatically. The NAV array's item ids can optionally narrow to Exclude<SectionId, typeof HOME_SECTION_ID>.
• components/site/MobileMenu.tsx — replace the local type SectionId = ... union with the import; SECTIONS array stays as-is.

Unit-testability: SECTION_IDS and HOME_SECTION_ID are pure constants — no new tests strictly needed, but a quick expect(SECTION_IDS).toContain(HOME_SECTION_ID) would self-document the invariant.

Item 2 — Explicit off-route discriminator

Chrome.tsx already has const pathname = usePathname() (line 41). The off-route check at line 63 can be tightened:

// Before
const el = document.getElementById(id);
if (el === null) {
  window.location.assign(`/#${id}`);
  return;
}

// After
const isHome = pathname === "/";
if (!isHome) {
  window.location.assign(`/#${id}`);
  return;
}
const el = document.getElementById(id);
if (el === null) {
  // Right route but target isn't mounted yet — fallback
  window.scrollTo({ top: 0 });
  return;
}

For MobileMenu.tsx, extract a helper that Chrome.tsx can also share:

// lib/nav.ts
export function isHomeRoute(pathname: string): boolean {
  return pathname === "/";
}

This makes the two distinct failure modes (wrong route vs. missing element) explicit and independently testable.

🧪 Testing checklist

• SECTION_IDS constant still matches all Frame id attributes in components/site/ (grep: id="compare" etc.)
• HOME_SECTION_ID is a member of SECTION_IDS (invariant assertion)
• Chrome.tsx active-section state type resolves correctly after the import swap (TypeScript build passes)
• MobileMenu.tsx activeSection prop type still satisfies SectionId
• Off-route nav (from /blog/*) still triggers window.location.assign rather than attempting a DOM scroll — extend chrome-active.test.ts or add to lib/scroll.test.ts
• pnpm build passes (static export, no TS errors)
• pnpm test passes

📂 Files to touch

File	Change
lib/nav.ts (new)	Export SectionId, SECTION_IDS, HOME_SECTION_ID, isHomeRoute()
lib/scroll.ts	Remove or re-export HOME_SECTION_ID; keep existing scroll helpers
components/site/Chrome.tsx	Import from lib/nav; update off-route check
components/site/MobileMenu.tsx	Import SectionId from lib/nav; keep existing logic
lib/scroll.test.ts (or new lib/nav.test.ts)	Add invariant + off-route helper tests

🔗 Related context

• Deferred from: fix(chrome): land home at top without a sticky #intro fragment #159 (PR) / fixing chrome: home/logo nav leaves a sticky #intro fragment in the URL #157
• Related prior refactor: Rename section components to match their domain identity (Close → Contact, …) #128 (rename Close → Contact — similar single-source-of-truth concern, now closed ✓)
• Related future concern: chrome: navbar home-route check assumes single locale, no basePath #115 (navbar home-route check assumes pathname === "/" — isHomeRoute() helper proposed here would be the right fix for that too)

Generated by Agentic Triage for issue #160 · ● 2.8M · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/issue-triage.md@c7d030cd6d4607b90d9ac3ffc8b24aff4f251632