@warpgogol/werkstatt-shared 0.14.1 → 0.16.0

package/src/checks/result-helpers.ts

@@ -22,8 +22,8 @@ import type {
   Diagnostic,
   KernelCommandResult,
   KernelNextStep,
-} from "@warpgogol/werkstatt-engine/kernel";
-import { lookupRemediation } from "../share/remediation/remediation-catalog.ts";
+} from "@warpgogol/werkstatt-shared/kernel";
+import { lookupRemediation } from "../remediation/remediation-catalog.ts";
 
 function defaultFailNextSteps(command: string): KernelNextStep[] {
   return [

package/src/checks/tests/remediation-auto-populate.test.ts

@@ -9,7 +9,7 @@
 
 import { test, expect } from "vitest";
 import { diagnosticsResult } from "../result-helpers.ts";
-import type { Diagnostic } from "@warpgogol/werkstatt-engine/kernel";
+import type { Diagnostic } from "@warpgogol/werkstatt-shared/kernel";
 
 test("diagnosticsResult: auto-populates remediation from catalog for known ruleId", () => {
   const diagnostics: Diagnostic[] = [

package/src/{share → client-scripts}/counter-utils.ts

@@ -7,8 +7,12 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Created shared counter utilities to eliminate duplication between hero and impact sections.</item>
-  <item>getStartValue now generates "1" in highest digit (e.g., "1,000" instead of "0,000") for better visual feedback during count-up.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/{share/scripts → client-scripts}/external-link-qr.ts

@@ -114,29 +114,27 @@ export function initExternalLinkQr(options?: ExternalLinkQrOptions): void {
     return !modal.hidden;
   }
 
-  function handleTriggerClick(e: Event): void {
-    const trigger = e.currentTarget as HTMLElement;
-    const anchor = trigger.closest("a");
+  function handleDelegatedClick(e: Event): void {
+    const anchor = (e.target as HTMLElement)?.closest?.("a[data-external-link]");
     if (!anchor) return;
 
     const href = anchor.getAttribute("href");
     if (!href) return;
 
     e.preventDefault();
-    e.stopPropagation();
-    openModal(href, trigger);
+    openModal(href, anchor as HTMLElement);
   }
 
-  function handleTriggerKeydown(e: KeyboardEvent): void {
+  function handleDelegatedKeydown(e: KeyboardEvent): void {
     if (e.key !== "Enter" && e.key !== " ") return;
-    e.preventDefault();
-    e.stopPropagation();
-    const trigger = e.currentTarget as HTMLElement;
-    const anchor = trigger.closest("a");
+    const anchor = (e.target as HTMLElement)?.closest?.("a[data-external-link]");
     if (!anchor) return;
+
     const href = anchor.getAttribute("href");
     if (!href) return;
-    openModal(href, trigger);
+
+    e.preventDefault();
+    openModal(href, anchor as HTMLElement);
   }
 
   function handleKeydown(e: KeyboardEvent): void {
@@ -173,11 +171,8 @@ export function initExternalLinkQr(options?: ExternalLinkQrOptions): void {
   }
 
   function attachTriggers(): void {
-    const triggers = document.querySelectorAll<HTMLElement>("[data-qr-trigger]");
-    for (const trigger of triggers) {
-      trigger.addEventListener("click", handleTriggerClick);
-      trigger.addEventListener("keydown", handleTriggerKeydown);
-    }
+    document.addEventListener("click", handleDelegatedClick);
+    document.addEventListener("keydown", handleDelegatedKeydown);
   }
 
   overlay.addEventListener("click", closeModal);

package/src/{share/scripts → client-scripts}/external-links.ts

@@ -10,8 +10,13 @@ external-link-qr entitlement is active, also injects a QR trigger span into each
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0011 Phase 2: Extracted from layout.astro inline script into src/scripts canonical pattern.</item>
-  <item>Migrated to @warpgogol/werkstatt-shared/share/scripts for platform-wide reuse.</item>
   <item>RFC-0932: accept ExternalLinkBehaviorOptions, inject QR trigger span when entitled.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -52,6 +57,12 @@ export function applyExternalLinkBehavior(options?: ExternalLinkBehaviorOptions)
     anchor.setAttribute("rel", "noopener noreferrer");
 
     if (qrEntitled && anchor.getAttribute("data-external-link-qr") !== "off") {
+      // Skip QR trigger for anchors wrapping media elements — a text arrow
+      // appended after an image/SVG/canvas looks visually wrong.
+      const hasMediaChild = anchor.querySelector("img, svg, canvas, picture");
+      if (hasMediaChild) {
+        continue;
+      }
       if (!anchor.querySelector("[data-qr-trigger]")) {
         const trigger = document.createElement("span");
         trigger.className = "external-link-qr-trigger";

package/src/{share/scripts → client-scripts}/gsap-counter.ts

@@ -8,15 +8,20 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0040: Created as shared GSAP counter initialization module in @warpgogol/werkstatt-shared/share/scripts.</item>
-  <item>Extended selector to support .hero__stat in addition to .impact-section__stat.</item>
+  <item>RFC-0040: Created as shared GSAP counter initialization module in @warpgogol/werkstatt-shared/client-scripts.</item>
   <item>RFC-0758: Extended selector to support .dynamic-status-block__stat.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 
 // @ai-invariant: RFC-0040. Do not import gsap at the top level. Always dynamic-import inside initGsapCounter.
 
-import { parseNumeric } from "../counter-utils.ts";
+import { parseNumeric } from "./counter-utils.ts";
 
 export interface GsapCounterOptions {
   prefersReducedMotion?: boolean;

package/src/client-scripts/index.ts

@@ -0,0 +1,35 @@
+/* 
+<MODULE_CONTRACT> 
+<purpose>scripts index — central export point for the script modules used in dynamic loading contexts.</purpose> 
+ 
+ 
+<non-goals> 
+<item>Do not define new modules or components.</item> 
+<item>Do not manage application state or business logic.</item> 
+</non-goals> 
+</MODULE_CONTRACT> 
+ 
+<CHANGE_SUMMARY>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — tail packages clean
+
+Sweep batch 3: rewrote ~95 purposes across werkstatt-knowledge, werkstatt-shared, godot-game, phaser-game, lifecycle-core, projektarchiv-*, portal-*, billing-*, typescript (CONTRACT-02/PURPOSE-02). Real KEY_DECISIONS on 5 godot utils, non-goals on 5 CONTRACT-03 files, headers on 4 headerless files, CS-07 history literal fix on 2 files. Policy: vitest.config.ts + test-fixtures testPatterns, worker-configuration.d.ts excludedPath. All non-site/engine packages now 0 diagnostics.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
+</CHANGE_SUMMARY> 
+*/
+
+// scheduler.ts is loaded dynamically by orchestrator.ts and lordicon.ts
+export * from "./lordicon.ts";
+export * from "./external-links.ts";
+export * from "./external-link-qr.ts";
+export * from "./lenis.ts";
+export * from "./scroll-spy.ts";
+export * from "./orchestrator.ts";
+// gsap-counter.ts (RFC-0040) is loaded dynamically by orchestrator.ts
+// inline-number-animation.ts (RFC-0041) is loaded dynamically by orchestrator.ts
+// gsap-reveal.ts / gsap-parallax.ts / gsap-stagger.ts (RFC-0106) are loaded
+// dynamically by orchestrator.ts via the reveal / parallax / stagger opt-ins.

package/src/{share/scripts → client-scripts}/inline-number-animation.ts

@@ -8,7 +8,7 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0041: Created as shared GSAP inline number animation module in @warpgogol/werkstatt-shared/share/scripts.</item>
+  <item>RFC-0041: Created as shared GSAP inline number animation module in @warpgogol/werkstatt-shared/client-scripts.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/{share/scripts → client-scripts}/lenis.ts

@@ -6,7 +6,12 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Migrated Lenis initialization to @warpgogol/werkstatt-shared/share/scripts for platform-wide reuse.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/{share/scripts → client-scripts}/lordicon.ts

@@ -11,7 +11,12 @@
 </MODULE_CONTRACT> 
  
 <CHANGE_SUMMARY>
-  <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY> ***************/
 
 async function initLordIcon(): Promise<void> {

package/src/{share/scripts → client-scripts}/orchestrator.ts

@@ -6,7 +6,12 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Created standard layout orchestrator in @warpgogol/werkstatt-shared/share/scripts to reduce code duplication in apps.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -15,6 +20,7 @@
 import { applyExternalLinkBehavior } from "./external-links.ts";
 import { initLordIconOnDemand } from "./lordicon.ts";
 import { initLenis } from "./lenis.ts";
+import { initScrollSpy } from "./scroll-spy.ts";
 
 export interface OrchestrationOptions {
   headerOffset?: number;
@@ -152,4 +158,7 @@ export async function runStandardLayoutOrchestration(
     const { initExternalLinkQr } = await import("./external-link-qr.ts");
     initExternalLinkQr();
   }
+
+  // 12. RFC-1061: scroll-spy URL hash updates (always-on, zero-dependency).
+  initScrollSpy();
 }

package/src/{share/scripts → client-scripts}/scheduler.ts

@@ -8,7 +8,12 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 ***************************************************************/
 

package/src/client-scripts/scroll-spy.ts

@@ -0,0 +1,106 @@
+/*
+<MODULE_CONTRACT>
+<purpose>scroll-spy — watches section elements via IntersectionObserver and updates the URL hash via history.replaceState as the user scrolls (RFC-1061).</purpose>
+<singleton-state>
+  <item>Module-level `activeObserver` and `activeCleanup` enforce single-instance idempotency (AC-9). Calling `initScrollSpy` twice disconnects the previous observer before creating a new one.</item>
+</singleton-state>
+<non-goals>
+  <item>Do not add navigation highlight UI — that is a separate concern.</item>
+  <item>Do not use pushState — replaceState only to avoid history pollution.</item>
+  <item>Do not modify section rendering or section id resolution.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1061: Created scroll-spy script with IntersectionObserver-based section tracking and URL hash updates.</item>
+  <item>RFC-1097: sweep — tail packages clean
+
+Sweep batch 3: rewrote ~95 purposes across werkstatt-knowledge, werkstatt-shared, godot-game, phaser-game, lifecycle-core, projektarchiv-*, portal-*, billing-*, typescript (CONTRACT-02/PURPOSE-02). Real KEY_DECISIONS on 5 godot utils, non-goals on 5 CONTRACT-03 files, headers on 4 headerless files, CS-07 history literal fix on 2 files. Policy: vitest.config.ts + test-fixtures testPatterns, worker-configuration.d.ts excludedPath. All non-site/engine packages now 0 diagnostics.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface ScrollSpyOptions {
+  /** CSS selector for elements to observe. Default: "section[id]" */
+  selector?: string;
+  /** IntersectionObserver rootMargin. Default: "-20% 0px -80% 0px" */
+  rootMargin?: string;
+  /** IntersectionObserver threshold. Default: 0 */
+  threshold?: number;
+  /** Whether to clear the hash when scrolled above the first section. Default: true */
+  clearAtTop?: boolean;
+}
+
+let activeCleanup: (() => void) | null = null;
+
+export function initScrollSpy(options?: ScrollSpyOptions): () => void {
+  const {
+    selector = "section[id]",
+    rootMargin = "-20% 0px -80% 0px",
+    threshold = 0,
+    clearAtTop = true,
+  } = options ?? {};
+
+  if (activeCleanup) {
+    activeCleanup();
+    activeCleanup = null;
+  }
+
+  if (!("IntersectionObserver" in window)) {
+    return () => {};
+  }
+
+  const sections = Array.from(document.querySelectorAll<HTMLElement>(selector)).filter(
+    (el) => !el.closest(".wl-modal"),
+  );
+
+  if (sections.length === 0) {
+    return () => {};
+  }
+
+  let currentId: string | null = null;
+
+  const updateHash = (id: string | null) => {
+    if (id === currentId) return;
+    currentId = id;
+    if (id) {
+      history.replaceState(null, "", `#${id}`);
+    } else if (clearAtTop) {
+      history.replaceState(null, "", location.pathname + location.search);
+    }
+  };
+
+  const observer = new IntersectionObserver(
+    (entries) => {
+      let topmostVisible: HTMLElement | null = null;
+      let topmostTop = Infinity;
+
+      for (const entry of entries) {
+        if (!entry.isIntersecting) continue;
+        const el = entry.target as HTMLElement;
+        const rect = el.getBoundingClientRect();
+        if (rect.top < topmostTop) {
+          topmostTop = rect.top;
+          topmostVisible = el;
+        }
+      }
+
+      if (topmostVisible) {
+        updateHash(topmostVisible.id);
+      } else if (clearAtTop) {
+        updateHash(null);
+      }
+    },
+    { rootMargin, threshold },
+  );
+
+  for (const section of sections) {
+    observer.observe(section);
+  }
+
+  const cleanup = () => {
+    observer.disconnect();
+    activeCleanup = null;
+  };
+
+  activeCleanup = cleanup;
+  return cleanup;
+}

package/src/client-scripts/tests/orchestrator.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+vi.mock("../scroll-spy.ts", () => ({
+  initScrollSpy: vi.fn(() => () => {}),
+}));
+
+import { runStandardLayoutOrchestration } from "../orchestrator.ts";
+import { initScrollSpy } from "../scroll-spy.ts";
+
+describe("runStandardLayoutOrchestration", () => {
+  beforeEach(() => {
+    class MockElement {}
+    vi.stubGlobal("Element", MockElement);
+    vi.stubGlobal("window", {
+      matchMedia: vi.fn(() => ({ matches: false })),
+      addEventListener: vi.fn(),
+    });
+    vi.stubGlobal("document", {
+      readyState: "complete",
+      querySelector: vi.fn(() => null),
+      addEventListener: vi.fn(),
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+  });
+
+  it("is an async function", () => {
+    expect(typeof runStandardLayoutOrchestration).toBe("function");
+  });
+
+  it("AC-6: calls initScrollSpy unconditionally as a new step", async () => {
+    await runStandardLayoutOrchestration();
+    expect(initScrollSpy).toHaveBeenCalled();
+  });
+
+  it("AC-6: calls initScrollSpy even when all opt-in flags are false", async () => {
+    await runStandardLayoutOrchestration({
+      counters: false,
+      reveal: false,
+      smoothScroll: false,
+    });
+    expect(initScrollSpy).toHaveBeenCalled();
+  });
+});

package/src/client-scripts/tests/scroll-spy.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { initScrollSpy } from "../scroll-spy.ts";
+
+interface MockRect {
+  top: number;
+}
+interface MockElement {
+  id: string;
+  closest: (sel: string) => object | null;
+  getBoundingClientRect: () => MockRect;
+}
+interface MockEntry {
+  target: MockElement;
+  isIntersecting: boolean;
+  boundingClientRect: MockRect;
+}
+interface MockObserverInstance {
+  observe: ReturnType<typeof vi.fn>;
+  unobserve: ReturnType<typeof vi.fn>;
+  disconnect: ReturnType<typeof vi.fn>;
+  takeRecords: ReturnType<typeof vi.fn>;
+}
+interface MockDocument {
+  body: { innerHTML: string };
+  readyState: string;
+  querySelector: ReturnType<typeof vi.fn>;
+  querySelectorAll: ReturnType<typeof vi.fn>;
+  getElementById: ReturnType<typeof vi.fn>;
+  addEventListener: ReturnType<typeof vi.fn>;
+}
+
+let observerCallbacks: Array<(entries: MockEntry[]) => void>;
+let observerInstances: MockObserverInstance[];
+let mockHistory: { replaceState: ReturnType<typeof vi.fn> };
+let mockDocument: MockDocument;
+let sectionCache: Map<string, MockElement>;
+
+function parseSections(html: string, selector: string): MockElement[] {
+  if (selector !== "section[id]") return [];
+  const sections: MockElement[] = [];
+  const sectionRegex = /<section\s+id="([^"]+)"[^>]*>([\s\S]*?)<\/section>/gi;
+  let match;
+  while ((match = sectionRegex.exec(html)) !== null) {
+    const modalBefore = html.substring(0, match.index);
+    const lastModalOpen = modalBefore.lastIndexOf('class="wl-modal"');
+    const lastModalClose = modalBefore.lastIndexOf("</div>");
+    const inModal = lastModalOpen > lastModalClose;
+    const el = {
+      id: match[1],
+      closest: (sel: string) => (sel === ".wl-modal" && inModal ? {} : null),
+      getBoundingClientRect: () => ({ top: 0 }),
+    };
+    sectionCache.set(match[1], el);
+    sections.push(el);
+  }
+  return sections;
+}
+
+describe("initScrollSpy", () => {
+  beforeEach(() => {
+    observerCallbacks = [];
+    observerInstances = [];
+    sectionCache = new Map();
+
+    class MockIntersectionObserver {
+      constructor(cb: (entries: MockEntry[]) => void) {
+        observerCallbacks.push(cb);
+        const instance = {
+          observe: vi.fn(),
+          unobserve: vi.fn(),
+          disconnect: vi.fn(),
+          takeRecords: vi.fn(() => []),
+        };
+        observerInstances.push(instance);
+        return instance;
+      }
+    }
+
+    mockHistory = { replaceState: vi.fn() };
+    mockDocument = {
+      body: { innerHTML: "" },
+      readyState: "complete",
+      querySelector: vi.fn(() => null),
+      querySelectorAll: vi.fn((selector: string) => {
+        return parseSections(mockDocument.body.innerHTML, selector);
+      }),
+      getElementById: vi.fn((id: string) => sectionCache.get(id) ?? null),
+      addEventListener: vi.fn(),
+    };
+
+    vi.stubGlobal("window", {
+      IntersectionObserver: MockIntersectionObserver,
+      addEventListener: vi.fn(),
+    });
+    vi.stubGlobal("IntersectionObserver", MockIntersectionObserver);
+    vi.stubGlobal("history", mockHistory);
+    vi.stubGlobal("location", {
+      pathname: "/page",
+      search: "",
+      hash: "",
+    });
+    vi.stubGlobal("document", mockDocument);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("AC-1: updates URL hash via history.replaceState when a section is in view", () => {
+    mockDocument.body.innerHTML = '<section id="approach">Content</section>';
+    const cleanup = initScrollSpy();
+    const section = sectionCache.get("approach")!;
+
+    observerCallbacks[0]([
+      {
+        target: section,
+        isIntersecting: true,
+        boundingClientRect: { top: 100 },
+      },
+    ]);
+
+    expect(mockHistory.replaceState).toHaveBeenCalledWith(null, "", "#approach");
+    cleanup();
+  });
+
+  it("AC-2: clears URL hash when scrolled above the first section", () => {
+    mockDocument.body.innerHTML = '<section id="hero">Hero</section>';
+    const cleanup = initScrollSpy();
+    const section = sectionCache.get("hero")!;
+
+    observerCallbacks[0]([
+      {
+        target: section,
+        isIntersecting: true,
+        boundingClientRect: { top: 100 },
+      },
+    ]);
+    expect(mockHistory.replaceState).toHaveBeenCalledWith(null, "", "#hero");
+
+    observerCallbacks[0]([
+      {
+        target: section,
+        isIntersecting: false,
+        boundingClientRect: { top: 500 },
+      },
+    ]);
+    expect(mockHistory.replaceState).toHaveBeenCalledWith(null, "", "/page");
+
+    cleanup();
+  });
+
+  it("AC-3: returns a cleanup callback that disconnects the observer", () => {
+    mockDocument.body.innerHTML = '<section id="test">Test</section>';
+    const cleanup = initScrollSpy();
+
+    expect(typeof cleanup).toBe("function");
+    cleanup();
+
+    expect(observerInstances[0].disconnect).toHaveBeenCalled();
+  });
+
+  it("AC-4: returns immediately without creating an observer when no section[id] elements exist", () => {
+    mockDocument.body.innerHTML = "<div>No sections here</div>";
+    const cleanup = initScrollSpy();
+
+    expect(observerInstances.length).toBe(0);
+    expect(typeof cleanup).toBe("function");
+    cleanup();
+  });
+
+  it("AC-5: returns silently without throwing when IntersectionObserver is not supported", () => {
+    vi.unstubAllGlobals();
+    vi.stubGlobal("window", { addEventListener: vi.fn() });
+    vi.stubGlobal("history", mockHistory);
+    vi.stubGlobal("location", { pathname: "/page", search: "", hash: "" });
+    vi.stubGlobal("document", mockDocument);
+    mockDocument.body.innerHTML = '<section id="test">Test</section>';
+    sectionCache.clear();
+
+    expect(() => initScrollSpy()).not.toThrow();
+  });
+
+  it("AC-9: is idempotent — calling twice disconnects the first observer before creating a new one", () => {
+    mockDocument.body.innerHTML = '<section id="a">A</section><section id="b">B</section>';
+    initScrollSpy();
+    expect(observerInstances.length).toBe(1);
+
+    initScrollSpy();
+    expect(observerInstances.length).toBe(2);
+    expect(observerInstances[0].disconnect).toHaveBeenCalled();
+  });
+
+  it("excludes sections inside .wl-modal elements", () => {
+    mockDocument.body.innerHTML =
+      '<div class="wl-modal"><section id="modal-section">Modal</section></div>' +
+      '<section id="page-section">Page</section>';
+
+    initScrollSpy();
+
+    expect(observerInstances.length).toBe(1);
+    expect(observerInstances[0].observe).toHaveBeenCalledTimes(1);
+    expect(observerInstances[0].observe).toHaveBeenCalledWith(sectionCache.get("page-section"));
+  });
+});