@warpgogol/werkstatt-shared 0.14.0 → 0.15.0

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/external-link-qr.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { initExternalLinkQr } from "../external-link-qr.ts";
+
+describe("initExternalLinkQr", () => {
+  it("is a function", () => {
+    expect(typeof initExternalLinkQr).toBe("function");
+  });
+});

package/src/client-scripts/tests/external-links.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { applyExternalLinkBehavior } from "../external-links.ts";
+
+describe("applyExternalLinkBehavior", () => {
+  beforeEach(() => {
+    vi.stubGlobal("document", {
+      querySelectorAll: vi.fn(() => []),
+    });
+    vi.stubGlobal("window", {
+      location: { href: "https://example.com/", origin: "https://example.com" },
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("is a function", () => {
+    expect(typeof applyExternalLinkBehavior).toBe("function");
+  });
+
+  it("does not throw when no anchors exist", () => {
+    expect(() => applyExternalLinkBehavior()).not.toThrow();
+  });
+});

package/src/client-scripts/tests/gsap-counter.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { initGsapCounter } from "../gsap-counter.ts";
+
+describe("initGsapCounter", () => {
+  it("is an async function", () => {
+    expect(typeof initGsapCounter).toBe("function");
+  });
+});

package/src/client-scripts/tests/gsap-mountain-journey.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { initMountainJourneyAnimation } from "../gsap-mountain-journey.ts";
+
+describe("initMountainJourneyAnimation", () => {
+  it("is an async function", () => {
+    expect(typeof initMountainJourneyAnimation).toBe("function");
+  });
+});

package/src/client-scripts/tests/gsap-parallax.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { initGsapParallax } from "../gsap-parallax.ts";
+
+describe("initGsapParallax", () => {
+  it("is an async function", () => {
+    expect(typeof initGsapParallax).toBe("function");
+  });
+});

package/src/client-scripts/tests/gsap-reveal.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { initGsapReveal } from "../gsap-reveal.ts";
+
+describe("initGsapReveal", () => {
+  it("is an async function", () => {
+    expect(typeof initGsapReveal).toBe("function");
+  });
+});

package/src/client-scripts/tests/gsap-stagger.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { initGsapStagger } from "../gsap-stagger.ts";
+
+describe("initGsapStagger", () => {
+  it("is an async function", () => {
+    expect(typeof initGsapStagger).toBe("function");
+  });
+});

package/src/client-scripts/tests/inline-number-animation.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { initInlineNumberAnimation } from "../inline-number-animation.ts";
+
+describe("initInlineNumberAnimation", () => {
+  it("is an async function", () => {
+    expect(typeof initInlineNumberAnimation).toBe("function");
+  });
+});

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

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { initLenis } from "../lenis.ts";
+
+describe("initLenis", () => {
+  it("is an async function", () => {
+    expect(typeof initLenis).toBe("function");
+  });
+});

package/src/client-scripts/tests/live-photos.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { initLivePhotos } from "../live-photos.ts";
+
+describe("initLivePhotos", () => {
+  it("is an async function", () => {
+    expect(typeof initLivePhotos).toBe("function");
+  });
+});

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

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+import { initLordIconOnDemand } from "../lordicon.ts";
+
+describe("initLordIconOnDemand", () => {
+  it("is a function", () => {
+    expect(typeof initLordIconOnDemand).toBe("function");
+  });
+});

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/scheduler.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { scheduleTask } from "../scheduler.ts";
+
+describe("scheduleTask", () => {
+  beforeEach(() => {
+    vi.stubGlobal("window", {
+      requestIdleCallback: vi.fn(),
+      setTimeout: vi.fn(),
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("is a function", () => {
+    expect(typeof scheduleTask).toBe("function");
+  });
+
+  it("does not throw when scheduling a task", () => {
+    expect(() => scheduleTask(() => undefined)).not.toThrow();
+  });
+});

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"));
+  });
+});