@warpgogol/werkstatt-shared 0.14.1 → 0.15.0

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

package/src/{share/scripts → client-scripts/tests}/video-player.test.ts

@@ -6,7 +6,36 @@
 <CHANGE_SUMMARY><item>RFC-0950: initial video-player tests.</item></CHANGE_SUMMARY>
 */
 
-import { test, expect, vi, beforeEach, afterEach } from "vitest";
+import { test, expect, vi, beforeEach, afterEach, type Mock } from "vitest";
+
+// ── Mock types ──────────────────────────────────────────────────────────────
+
+interface MockVideo {
+  dataset: Record<string, string>;
+  canPlayType: ReturnType<typeof vi.fn>;
+  play: ReturnType<typeof vi.fn>;
+  pause: ReturnType<typeof vi.fn>;
+  load: ReturnType<typeof vi.fn>;
+  insertBefore: ReturnType<typeof vi.fn>;
+  firstChild: null;
+}
+interface MockHlsInstance {
+  loadSource: ReturnType<typeof vi.fn>;
+  attachMedia: ReturnType<typeof vi.fn>;
+  destroy: ReturnType<typeof vi.fn>;
+  on: Mock<(event: string, cb: () => void) => void>;
+}
+interface MockEntry {
+  isIntersecting: boolean;
+  target: MockVideo;
+}
+interface MockObserver {
+  unobserve: () => void;
+}
+interface MockDocument {
+  querySelectorAll: ReturnType<typeof vi.fn>;
+  createElement: ReturnType<typeof vi.fn>;
+}
 
 // ── Mocks ───────────────────────────────────────────────────────────────────
 
@@ -15,7 +44,7 @@ vi.mock("plyr", () => ({
 }));
 
 vi.mock("hls.js/light", () => {
-  const hlsRef = { current: null as any };
+  const hlsRef = { current: null as MockHlsInstance | null };
   const fn = vi.fn(function Hls() {
     return hlsRef.current;
   });
@@ -28,8 +57,8 @@ vi.mock("hls.js/light", () => {
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
-function createMockVideo(attrs: Record<string, string | undefined> = {}): any {
-  const video: any = {
+function createMockVideo(attrs: Record<string, string | undefined> = {}): MockVideo {
+  const video: MockVideo = {
     dataset: {},
     canPlayType: vi.fn(() => ""),
     play: vi.fn(() => Promise.resolve()),
@@ -44,23 +73,15 @@ function createMockVideo(attrs: Record<string, string | undefined> = {}): any {
   return video;
 }
 
-let observerCallbacks: ((
-  entries: { isIntersecting: boolean; target: any }[],
-  obs: { unobserve: () => void },
-) => void)[] = [];
+let observerCallbacks: ((entries: MockEntry[], obs: MockObserver) => void)[] = [];
 let observerOptions: { threshold?: number; rootMargin?: string }[] = [];
+let mockDocument: MockDocument;
 
 class MockIntersectionObserver {
-  callback: (
-    entries: { isIntersecting: boolean; target: any }[],
-    obs: { unobserve: () => void },
-  ) => void;
+  callback: (entries: MockEntry[], obs: MockObserver) => void;
   options: { threshold?: number; rootMargin?: string };
   constructor(
-    cb: (
-      entries: { isIntersecting: boolean; target: any }[],
-      obs: { unobserve: () => void },
-    ) => void,
+    cb: (entries: MockEntry[], obs: MockObserver) => void,
     opts: { threshold?: number; rootMargin?: string },
   ) {
     this.callback = cb;
@@ -79,24 +100,23 @@ beforeEach(() => {
   vi.clearAllMocks();
   observerCallbacks = [];
   observerOptions = [];
-  (globalThis as any).IntersectionObserver = MockIntersectionObserver;
-  (globalThis as any).window = globalThis;
-  (globalThis as any).document = {
+  mockDocument = {
     querySelectorAll: vi.fn(() => []),
     createElement: vi.fn((tag: string) => ({ tagName: tag.toUpperCase() })),
   };
+  vi.stubGlobal("IntersectionObserver", MockIntersectionObserver);
+  vi.stubGlobal("window", globalThis);
+  vi.stubGlobal("document", mockDocument);
 });
 
 afterEach(() => {
-  delete (globalThis as any).IntersectionObserver;
-  delete (globalThis as any).window;
-  delete (globalThis as any).document;
+  vi.unstubAllGlobals();
   vi.restoreAllMocks();
 });
 
-async function triggerUpgrade(video: any): Promise<void> {
-  const { initVideoPlayers } = await import("../scripts/video-player.ts");
-  vi.spyOn(globalThis.document as any, "querySelectorAll").mockReturnValue([video]);
+async function triggerUpgrade(video: MockVideo): Promise<void> {
+  const { initVideoPlayers } = await import("../video-player.ts");
+  mockDocument.querySelectorAll.mockReturnValue([video]);
   await initVideoPlayers();
 
   expect(observerCallbacks.length).toBeGreaterThanOrEqual(1);
@@ -107,12 +127,10 @@ async function triggerUpgrade(video: any): Promise<void> {
 // ── Tests ───────────────────────────────────────────────────────────────────
 
 test("initVideoPlayers: returns early when no [data-video-player] elements", async () => {
-  const querySelectorAll = vi.spyOn(globalThis.document as any, "querySelectorAll");
-  querySelectorAll.mockReturnValue([]);
-  const { initVideoPlayers } = await import("../scripts/video-player.ts");
+  mockDocument.querySelectorAll.mockReturnValue([]);
+  const { initVideoPlayers } = await import("../video-player.ts");
   await initVideoPlayers();
   expect(observerCallbacks.length).toBe(0);
-  querySelectorAll.mockRestore();
 });
 
 test("upgrade: data-controls='false' configures Plyr with only ['mute']", async () => {
@@ -165,7 +183,9 @@ test("upgrade: data-autoplay='true' with HLS waits for MEDIA_ATTACHED before pla
     destroy: vi.fn(),
     on: vi.fn(),
   };
-  const Hls = (await import("hls.js/light")).default as any;
+  const Hls = (await import("hls.js/light")).default as unknown as {
+    _hlsRef: { current: MockHlsInstance | null };
+  };
   Hls._hlsRef.current = hlsInstance;
 
   await triggerUpgrade(video);
@@ -173,7 +193,7 @@ test("upgrade: data-autoplay='true' with HLS waits for MEDIA_ATTACHED before pla
   expect(Hls).toHaveBeenCalled();
   expect(hlsInstance.attachMedia).toHaveBeenCalledWith(video);
 
-  const attachedCall = hlsInstance.on.mock.calls.find((c: any[]) => c[0] === "hls.MEDIA_ATTACHED");
+  const attachedCall = hlsInstance.on.mock.calls.find((c) => c[0] === "hls.MEDIA_ATTACHED");
   expect(attachedCall, "Hls must register a MEDIA_ATTACHED listener before play()").toBeDefined();
   attachedCall![1]();