@warpgogol/werkstatt-shared 0.2.0

package/src/share/scripts/inline-number-animation.ts

@@ -0,0 +1,120 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Animates .js-inline-number spans using GSAP count-up + ScrollTrigger. Deferred-loaded; never imported unconditionally.</purpose>
+<non-goals>
+  <item>Do not apply opacity, y, scale, or any spatial tween to inline number spans — causes layout reflow.</item>
+  <item>Do not load gsap at module level — dynamic import is mandatory.</item>
+  <item>Do not animate numbers inside headings — those are excluded at SSR pre-wrap time.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0041: Created as shared GSAP inline number animation module in @warpgogol/werkstatt-shared/share/scripts.</item>
+</CHANGE_SUMMARY>
+*/
+
+// @ai-invariant: RFC-0041. No spatial tweens on inline elements. Dynamic GSAP import only.
+
+export interface InlineNumberAnimationOptions {
+  prefersReducedMotion?: boolean;
+}
+
+/**
+ * Animates all `.js-inline-number` spans found in the document using GSAP count-up.
+ * Duration is read from each span's `data-duration` attribute (default 3.0 s).
+ * No spatial tweens — only the numeric value is animated to prevent CLS.
+ * Safe to call multiple times — spans are guarded with `data-gsap-ready`.
+ * No-ops when `prefersReducedMotion` is true (sets final values synchronously).
+ */
+export async function initInlineNumberAnimation(
+  options: InlineNumberAnimationOptions = {},
+): Promise<void> {
+  const { prefersReducedMotion = false } = options;
+
+  const spans = document.querySelectorAll<HTMLElement>(".js-inline-number");
+  if (spans.length === 0) return;
+
+  // Locale from document lang attribute, fallback to de-DE
+  const locale = document.documentElement.lang || "de-DE";
+
+  const formatNumber = (value: number) =>
+    new Intl.NumberFormat(locale, {
+      minimumFractionDigits: 0,
+      maximumFractionDigits: 0,
+    }).format(Math.round(value));
+
+  // Reduced-motion: set final values immediately, no GSAP
+  if (prefersReducedMotion) {
+    spans.forEach((el) => {
+      if (el.dataset.gsapReady === "true") return;
+      el.dataset.gsapReady = "true";
+      const numeric = Number(el.dataset.numeric ?? 0);
+      el.textContent = formatNumber(numeric);
+    });
+    return;
+  }
+
+  // Dynamically import GSAP — excluded from orchestrator's initial bundle
+  const { gsap } = await import("gsap");
+  const { ScrollTrigger } = await import("gsap/ScrollTrigger");
+  gsap.registerPlugin(ScrollTrigger);
+
+  // Wire ScrollTrigger to Lenis: on every Lenis scroll tick, feed the current
+  // scroll position into ScrollTrigger so it doesn't rely on native scroll events.
+  type LenisScrollEvent = { scroll: number };
+  type LenisInstance = { on: (event: string, cb: (e: LenisScrollEvent) => void) => void };
+
+  const wireLenis = (lenis: LenisInstance) => {
+    lenis.on("scroll", (e: LenisScrollEvent) => {
+      void e; // position already reflected in window.scrollY by Lenis native scroll
+      ScrollTrigger.update();
+    });
+    // Defer refresh to next rAF so layout is fully settled before positions are measured
+    requestAnimationFrame(() => ScrollTrigger.refresh());
+  };
+
+  const existingLenis = (window as unknown as Record<string, unknown>)["wgLenis"] as
+    LenisInstance | undefined;
+
+  if (existingLenis) {
+    wireLenis(existingLenis);
+  } else {
+    window.addEventListener(
+      "lenis:ready",
+      (e) => {
+        const { lenis } = (e as CustomEvent<{ lenis: LenisInstance }>).detail;
+        if (lenis) wireLenis(lenis);
+      },
+      { once: true },
+    );
+  }
+
+  spans.forEach((el) => {
+    if (el.dataset.gsapReady === "true") return;
+    el.dataset.gsapReady = "true";
+
+    const endValue = Number(el.dataset.numeric ?? 0);
+    const duration = Number(el.dataset.duration ?? 3.0);
+
+    const counter = { value: 0 };
+
+    // Only count-up tween — NO spatial tweens (y/opacity) on inline elements
+    gsap.to(counter, {
+      value: endValue,
+      duration,
+      ease: "power2.out",
+      scrollTrigger: {
+        trigger: el,
+        start: "top 85%",
+        once: true,
+        fastScrollEnd: true,
+      },
+      onUpdate: () => {
+        el.textContent = formatNumber(counter.value);
+      },
+      onComplete: () => {
+        // Ensure exact final value (avoids floating-point display artifacts)
+        el.textContent = formatNumber(endValue);
+      },
+    });
+  });
+}

package/src/share/scripts/lenis.ts

@@ -0,0 +1,109 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/scripts/lenis.ts as an authored share script module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not manage app-specific UI states (e.g. scroll-to-top button visibility).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Migrated Lenis initialization to @warpgogol/werkstatt-shared/share/scripts for platform-wide reuse.</item>
+</CHANGE_SUMMARY>
+*/
+
+// @ai-invariant: This is a high-risk module. Preserve its core logic and minimize external side effects during modification.
+
+export type LenisInstance = import("lenis").default;
+
+export type InitLenisOptions = {
+  prefersReducedMotion?: boolean;
+  headerOffset?: number;
+  duration?: number;
+  onScroll?: (lenis: LenisInstance) => void;
+};
+
+let lenisInstance: LenisInstance | null = null;
+
+export async function initLenis(
+  options: InitLenisOptions = {},
+): Promise<LenisInstance | undefined> {
+  const { prefersReducedMotion = false, headerOffset = 0, duration = 1.2, onScroll } = options;
+
+  if (prefersReducedMotion) {
+    (window as Window & { wgLenis?: LenisInstance }).wgLenis = undefined;
+    return;
+  }
+
+  const Lenis = await import("lenis");
+
+  lenisInstance = new Lenis.default({
+    duration,
+    easing: (t: number) => Math.min(1, 1.001 - 2 ** (-10 * t)),
+    orientation: "vertical",
+    gestureOrientation: "vertical",
+    smoothWheel: true,
+    wheelMultiplier: 1,
+    touchMultiplier: 2,
+  });
+
+  (window as Window & { wgLenis?: LenisInstance }).wgLenis = lenisInstance;
+
+  if (onScroll) {
+    lenisInstance.on("scroll", () => onScroll(lenisInstance!));
+  }
+
+  window.dispatchEvent(
+    new CustomEvent("lenis:ready", {
+      detail: { lenis: lenisInstance },
+    }),
+  );
+
+  const activeLenis = lenisInstance;
+
+  // Handle anchor links for smooth scrolling
+  document.addEventListener("click", (e) => {
+    const target = e.target as HTMLElement;
+    const link = target.closest('a[href^="#"]');
+
+    if (link) {
+      const href = link.getAttribute("href");
+      if (href && href !== "#") {
+        const targetElement = document.querySelector(href);
+        if (targetElement) {
+          // Skip if it's a modal or something that should handle itself
+          if (targetElement.classList.contains("wl-modal")) {
+            return;
+          }
+
+          e.preventDefault();
+          activeLenis.scrollTo(targetElement as HTMLElement, {
+            offset: -headerOffset,
+            immediate: prefersReducedMotion,
+          });
+        }
+      }
+    }
+  });
+
+  // Scroll to hash target on page load (cross-page anchor navigation)
+  if (window.location.hash) {
+    const hashTarget = document.querySelector(window.location.hash);
+    if (hashTarget && !hashTarget.classList.contains("wl-modal")) {
+      // Defer until after the browser's initial scroll attempt
+      requestAnimationFrame(() => {
+        activeLenis.scrollTo(hashTarget as HTMLElement, {
+          offset: -headerOffset,
+          immediate: prefersReducedMotion,
+        });
+      });
+    }
+  }
+
+  function raf(time: number) {
+    activeLenis.raf(time);
+    requestAnimationFrame(raf);
+  }
+
+  requestAnimationFrame(raf);
+
+  return activeLenis;
+}

package/src/share/scripts/live-photos.ts

@@ -0,0 +1,250 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0202] Living-photos runtime. Wires the `in-viewport` (IntersectionObserver) and `tap`
+  (button) playback triggers for [data-live-photo] elements emitted by <LivePhoto>. No GSAP, no
+  framework — a few KB of vanilla DOM. The `autoplay` trigger is native and is never touched
+  here (those elements carry no data-trigger). Respects prefers-reduced-motion: non-interactive
+  playback is suppressed (static poster wins); a user tap always wins.
+</purpose>
+<non-goals>
+  <item>Do not handle the autoplay (native) path — those elements have no data-trigger.</item>
+  <item>Do not resolve clips or own presentation — that is @warpgogol/werkstatt-site/ui.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0202: introduced the living-photos runtime.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface LivePhotosOptions {
+  prefersReducedMotion?: boolean;
+}
+
+const PLAYING = "live-photo--playing";
+const USER_PLAYING = "live-photo--user-playing";
+const READY = "live-photo--ready";
+const UNSUPPORTED = "live-photo--unsupported";
+
+/** Cached WebM support check — true if browser claims VP8/VP9 support. */
+let webmSupportCache: boolean | undefined;
+
+function isIOSLike(): boolean {
+  return (
+    /iPad|iPhone|iPod/.test(navigator.userAgent) ||
+    (navigator.platform === "MacIntel" && "ontouchend" in document)
+  );
+}
+
+/** Detect WebM support via canPlayType. Now more optimistic since we have MP4 fallbacks. */
+function detectWebMSupport(): boolean {
+  if (webmSupportCache !== undefined) return webmSupportCache;
+
+  const video = document.createElement("video");
+  const canPlay =
+    video.canPlayType('video/webm; codecs="vp8, vorbis"') !== "" ||
+    video.canPlayType('video/webm; codecs="vp9"') !== "" ||
+    video.canPlayType("video/webm") !== "";
+
+  // Check if MP4 is supported as fallback (almost universal)
+  const canPlayMP4 =
+    video.canPlayType('video/mp4; codecs="avc1.42E01E"') !== "" ||
+    video.canPlayType("video/mp4") !== "";
+
+  // If we have MP4 support, we can be less strict about WebM
+  // iOS will get MP4 fallback, so we don't need to mark as unsupported
+  webmSupportCache = canPlay || canPlayMP4;
+  return webmSupportCache;
+}
+
+/** Mark a living photo as unsupported — hide video, keep poster visible. */
+function markUnsupported(root: HTMLElement, video: HTMLVideoElement): void {
+  root.classList.add(UNSUPPORTED);
+  root.classList.remove(PLAYING, USER_PLAYING, READY);
+  video.style.display = "none";
+  // Hide the toggle button on unsupported devices
+  const toggle = root.querySelector<HTMLButtonElement>(".live-photo__toggle");
+  if (toggle) toggle.style.display = "none";
+}
+
+function setReady(root: HTMLElement, ready: boolean): void {
+  if (ready) {
+    root.classList.add(READY);
+  } else {
+    root.classList.remove(READY);
+  }
+}
+
+function ensureVideoSources(video: HTMLVideoElement): void {
+  let changed = false;
+  for (const source of Array.from(video.querySelectorAll<HTMLSourceElement>("source[data-src]"))) {
+    const src = source.dataset.src;
+    if (!src || source.getAttribute("src") === src) continue;
+    source.setAttribute("src", src);
+    changed = true;
+  }
+  if (changed) video.load();
+}
+
+function attemptPlay(root: HTMLElement, video: HTMLVideoElement, _byUser: boolean): void {
+  ensureVideoSources(video);
+  const canPlay = video.readyState >= 3; // HAVE_FUTURE_DATA
+
+  if (!canPlay) {
+    // Wait for video to be ready before playing (prevents iOS black flash)
+    video.addEventListener(
+      "canplaythrough",
+      () => {
+        setReady(root, true);
+        void video.play().catch(() => handlePlayFailure(root));
+      },
+      { once: true },
+    );
+    // Also listen for error — if video can't load, revert to poster
+    video.addEventListener(
+      "error",
+      () => {
+        handlePlayFailure(root);
+      },
+      { once: true },
+    );
+    return;
+  }
+
+  setReady(root, true);
+  void video.play().catch(() => handlePlayFailure(root));
+}
+
+function handlePlayFailure(root: HTMLElement): void {
+  // Play policy rejected (e.g., iOS without user gesture) or video error — restore poster
+  root.classList.remove(PLAYING, USER_PLAYING, READY);
+  const toggle = root.querySelector<HTMLButtonElement>(".live-photo__toggle");
+  if (toggle) toggle.setAttribute("aria-pressed", "false");
+}
+
+function setPlaying(
+  root: HTMLElement,
+  video: HTMLVideoElement,
+  on: boolean,
+  byUser: boolean,
+): void {
+  if (on) {
+    root.classList.add(PLAYING);
+    if (byUser) root.classList.add(USER_PLAYING);
+    attemptPlay(root, video, byUser);
+  } else {
+    root.classList.remove(PLAYING, USER_PLAYING, READY);
+    video.pause();
+  }
+  const toggle = root.querySelector<HTMLButtonElement>(".live-photo__toggle");
+  if (toggle) toggle.setAttribute("aria-pressed", String(root.classList.contains(PLAYING)));
+}
+
+export async function initLivePhotos(options: LivePhotosOptions = {}): Promise<void> {
+  const prefersReducedMotion =
+    options.prefersReducedMotion ?? window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+  const roots = document.querySelectorAll<HTMLElement>("[data-live-photo][data-trigger]");
+  if (roots.length === 0) return;
+
+  // One shared observer for all in-viewport clips.
+  const observed = new Map<Element, HTMLVideoElement>();
+  const observer =
+    "IntersectionObserver" in window
+      ? new IntersectionObserver(
+          (entries) => {
+            for (const entry of entries) {
+              const video = observed.get(entry.target);
+              if (!video) continue;
+              const isIntersecting = entry.isIntersecting;
+              // iOS Safari respects autoplay attribute more than programmatic play()
+              if (isIntersecting) {
+                video.setAttribute("autoplay", "");
+              } else {
+                video.removeAttribute("autoplay");
+              }
+              setPlaying(entry.target as HTMLElement, video, isIntersecting, false);
+            }
+          },
+          { threshold: 0.25 },
+        )
+      : null;
+
+  for (const root of Array.from(roots)) {
+    if (root.dataset.livePhotoReady === "true") continue;
+    root.dataset.livePhotoReady = "true";
+
+    const video = root.querySelector<HTMLVideoElement>(".live-photo__video");
+    if (!video) continue;
+
+    // Check WebM support early — if unsupported, hide video and keep poster
+    if (!detectWebMSupport()) {
+      markUnsupported(root, video);
+      continue;
+    }
+
+    const mp4Src = root.dataset.mp4Src;
+
+    // iOS Safari decodes VP8/VP9 WebM but ignores its alpha channel: a transparent
+    // living photo plays with a dirty opaque background instead of the cut-out subject.
+    // (Other browsers honour VP9 alpha and render it correctly.) These decorative
+    // portraits ship WebM-only — there is no iOS-playable alpha source — so the only
+    // correct iOS behaviour is to keep the transparent static poster. When an explicit
+    // MP4 fallback is authored (opaque clips), we still let iOS play it below.
+    if (isIOSLike() && !mp4Src) {
+      markUnsupported(root, video);
+      continue;
+    }
+
+    if (mp4Src && isIOSLike()) {
+      const firstSource = video.querySelector<HTMLSourceElement>("source");
+      if (firstSource) {
+        firstSource.dataset.src = mp4Src;
+        firstSource.setAttribute("type", "video/mp4");
+      }
+    }
+
+    const trigger = root.dataset.trigger;
+    const tapBehavior = root.dataset.tapBehavior ?? "toggle";
+    const toggle = root.querySelector<HTMLButtonElement>(".live-photo__toggle");
+
+    // Control: user-initiated, always permitted (even under reduced motion).
+    if (toggle) {
+      toggle.addEventListener("click", () => {
+        const playing = root.classList.contains(PLAYING);
+        if (playing && tapBehavior === "toggle") {
+          setPlaying(root, video, false, false);
+        } else {
+          // For iOS: ensure autoplay attribute is set before user-triggered play
+          video.setAttribute("autoplay", "");
+          setPlaying(root, video, true, true);
+        }
+      });
+    }
+
+    // Video load error handling — iOS may fail to decode WebM
+    video.addEventListener("error", () => {
+      // Video failed to load/decode — ensure poster remains visible
+      root.classList.remove(PLAYING, USER_PLAYING, READY);
+      if (!mp4Src) video.style.display = "none";
+    });
+
+    // Metadata loaded — we know dimensions but may not be ready to play yet
+    video.addEventListener("loadedmetadata", () => {
+      // Video metadata available, but we wait for canplaythrough before marking ready
+    });
+
+    // in-viewport auto playback — suppressed under reduced motion (poster stays).
+    if (trigger === "in-viewport" && !prefersReducedMotion && observer) {
+      observed.set(root, video);
+      observer.observe(root);
+    }
+
+    // Pause when tab is hidden (mobile UX + power saving)
+    document.addEventListener("visibilitychange", () => {
+      if (document.hidden && root.classList.contains(PLAYING)) {
+        setPlaying(root, video, false, false);
+      }
+    });
+  }
+}

package/src/share/scripts/lordicon.ts

@@ -0,0 +1,94 @@
+// @ai-invariant: This is a high-risk module. Preserve its core logic and minimize external side effects during modification.
+/*************** <MODULE_CONTRACT> 
+<purpose>Facilitates the dynamic loading and hydration of Lordicon elements based on viewport visibility.</purpose> 
+ 
+ 
+<non-goals> 
+<item>Do not handle raw content parsing for icons.</item> 
+<item>Do not manage global application state or configuration.</item> 
+<item>Do not perform network requests outside of JSON prefetching.</item> 
+</non-goals> 
+</MODULE_CONTRACT> 
+ 
+<CHANGE_SUMMARY>
+  <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</item>
+</CHANGE_SUMMARY> ***************/
+
+async function initLordIcon(): Promise<void> {
+  const { defineElement } = await import("@lordicon/element");
+  defineElement();
+}
+
+let lordIconLoaderPromise: Promise<void> | null = null;
+
+const jsonPrefetchCache = new Map<string, Promise<void>>();
+
+const ensureLordIconLoaded = () => {
+  if (!lordIconLoaderPromise) {
+    lordIconLoaderPromise = new Promise((resolve) => {
+      void (async () => {
+        const { scheduleTask } = await import("./scheduler.ts");
+        scheduleTask(async () => {
+          await initLordIcon();
+          resolve();
+        });
+      })();
+    });
+  }
+  return lordIconLoaderPromise;
+};
+
+const prefetchJsonOnce = (url: string) => {
+  const existing = jsonPrefetchCache.get(url);
+  if (existing) return existing;
+
+  const p = fetch(url, { cache: "force-cache" })
+    .then(() => {})
+    .catch(() => {});
+  jsonPrefetchCache.set(url, p);
+  return p;
+};
+
+export function initLordIconOnDemand(): void {
+  const icons = Array.from(document.querySelectorAll("lord-icon"));
+  if (!icons.length) return;
+
+  const hydrateIcon = async (icon: HTMLElement) => {
+    // 1. Ensure library is loaded/loading
+    ensureLordIconLoaded();
+
+    // 2. Swap src if needed
+    const src = icon.getAttribute("data-src");
+    if (src && !icon.getAttribute("src")) {
+      void prefetchJsonOnce(src);
+      icon.setAttribute("src", src);
+    }
+  };
+
+  if (typeof IntersectionObserver !== "function") {
+    // Fallback: load everything immediately
+    ensureLordIconLoaded();
+    icons.forEach((icon) => {
+      const src = icon.getAttribute("data-src");
+      if (src) icon.setAttribute("src", src);
+    });
+    return;
+  }
+
+  const observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          const icon = entry.target as HTMLElement;
+          hydrateIcon(icon);
+          observer.unobserve(icon);
+        }
+      }
+    },
+    { rootMargin: "100px" }, // Smaller margin to defer loading of far-off icons
+  );
+
+  for (const icon of icons) {
+    observer.observe(icon);
+  }
+}