@warpgogol/werkstatt-shared 0.2.0

package/src/share/scripts/gsap-counter.ts

@@ -0,0 +1,168 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Initializes GSAP + ScrollTrigger animated stat counters for sections marked data-animated="true". Deferred-loaded; never imported unconditionally.</purpose>
+<non-goals>
+  <item>Do not animate sections other than those with data-animated="true".</item>
+  <item>Do not import gsap at module level — dynamic import is required for deferred loading.</item>
+  <item>Do not use this for non-counter animations (parallax, reveal, stagger of sections).</item>
+</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-0758: Extended selector to support .dynamic-status-block__stat.</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";
+
+export interface GsapCounterOptions {
+  prefersReducedMotion?: boolean;
+  locale?: string;
+}
+
+/**
+ * Finds all `.js-stat-counter` elements within sections marked `data-animated="true"`
+ * and animates them using GSAP + ScrollTrigger.
+ * Safe to call multiple times — elements are guarded with `data-gsap-ready`.
+ * No-ops when `prefersReducedMotion` is true (sets final values synchronously).
+ */
+export async function initGsapCounter(options: GsapCounterOptions = {}): Promise<void> {
+  const { prefersReducedMotion = false, locale = "de-DE" } = options;
+
+  const sections = document.querySelectorAll<HTMLElement>("[data-animated='true']");
+  if (sections.length === 0) return;
+
+  const formatNumber = (value: number, decimals = 0) =>
+    new Intl.NumberFormat(locale, {
+      minimumFractionDigits: decimals,
+      maximumFractionDigits: decimals,
+    }).format(value);
+
+  // Reduced-motion: reveal all cards and set final counter values immediately, no GSAP needed
+  if (prefersReducedMotion) {
+    sections.forEach((section) => {
+      section
+        .querySelectorAll<HTMLElement>(
+          ".impact-section__stat, .hero__stat, .section-stats__item, .dynamic-status-block__stat",
+        )
+        .forEach((statEl) => {
+          if (statEl.dataset.gsapReady === "true") return;
+          statEl.dataset.gsapReady = "true";
+          statEl.style.opacity = "1";
+          statEl.style.transform = "none";
+          const valueEl = statEl.querySelector<HTMLElement>(".js-stat-counter");
+          if (valueEl) {
+            const numeric = Number(valueEl.dataset.numeric);
+            const decimals = Number(valueEl.dataset.decimals ?? 0);
+            if (!isNaN(numeric)) valueEl.textContent = formatNumber(numeric, decimals);
+          }
+          const prefixEl = statEl.querySelector<HTMLElement>(".js-stat-prefix");
+          const suffixEl = statEl.querySelector<HTMLElement>(".js-stat-suffix");
+          if (prefixEl) {
+            prefixEl.style.opacity = "1";
+            prefixEl.style.transform = "none";
+          }
+          if (suffixEl) {
+            suffixEl.style.opacity = "1";
+            suffixEl.style.transform = "none";
+          }
+        });
+    });
+    return;
+  }
+
+  // Dynamically import GSAP so it is excluded from the orchestrator's initial bundle
+  const { gsap } = await import("gsap");
+  const { ScrollTrigger } = await import("gsap/ScrollTrigger");
+  gsap.registerPlugin(ScrollTrigger);
+
+  // Wire ScrollTrigger to Lenis for correct scroll position tracking
+  const wireLenis = (lenis: { on: (event: string, cb: (...args: unknown[]) => void) => void }) => {
+    lenis.on("scroll", () => ScrollTrigger.update());
+  };
+
+  const existingLenis = (window as unknown as Record<string, unknown>)["wgLenis"] as
+    { on: (event: string, cb: (...args: unknown[]) => void) => void } | undefined;
+
+  if (existingLenis) {
+    wireLenis(existingLenis);
+    ScrollTrigger.refresh();
+  } else {
+    window.addEventListener(
+      "lenis:ready",
+      (e) => {
+        const { lenis } = (e as CustomEvent<{ lenis: typeof existingLenis }>).detail;
+        if (lenis) {
+          wireLenis(lenis);
+          ScrollTrigger.refresh();
+        }
+      },
+      { once: true },
+    );
+  }
+
+  sections.forEach((section) => {
+    const allStats = section.querySelectorAll<HTMLElement>(
+      ".impact-section__stat, .hero__stat, .section-stats__item, .dynamic-status-block__stat",
+    );
+    allStats.forEach((statEl) => {
+      const valueEl = statEl.querySelector<HTMLElement>(".js-stat-counter");
+
+      // Guard against double-init (keyed on the stat card, not the counter span)
+      if (statEl.dataset.gsapReady === "true") return;
+      statEl.dataset.gsapReady = "true";
+
+      const tl = gsap.timeline({
+        defaults: { ease: "power3.out" },
+        scrollTrigger: {
+          trigger: statEl,
+          start: "top 82%",
+          once: true,
+          fastScrollEnd: true,
+        },
+      });
+
+      // Card reveal — runs for every stat (counter or static)
+      tl.fromTo(statEl, { opacity: 0, y: 18 }, { opacity: 1, y: 0, duration: 0.7 });
+
+      if (valueEl) {
+        const endValue = Number(valueEl.dataset.numeric ?? 0);
+        const startValue = parseNumeric(valueEl.dataset.start) ?? 0;
+        const decimals = Number(valueEl.dataset.decimals ?? 0);
+        const duration = Number(valueEl.dataset.duration ?? 1.8);
+
+        const prefixEl = statEl.querySelector<HTMLElement>(".js-stat-prefix");
+        const suffixEl = statEl.querySelector<HTMLElement>(".js-stat-suffix");
+
+        const counter = { value: startValue };
+
+        // Number count-up
+        tl.to(
+          counter,
+          {
+            value: endValue,
+            duration,
+            ease: "power2.out",
+            onUpdate: () => {
+              valueEl.textContent = formatNumber(counter.value, decimals);
+            },
+          },
+          0.08,
+        );
+
+        // Prefix reveal
+        if (prefixEl) {
+          tl.fromTo(prefixEl, { opacity: 0, y: 4 }, { opacity: 1, y: 0, duration: 0.45 }, 0.14);
+        }
+
+        // Suffix reveal
+        if (suffixEl) {
+          tl.fromTo(suffixEl, { opacity: 0, y: 4 }, { opacity: 1, y: 0, duration: 0.45 }, 0.18);
+        }
+      }
+    });
+  });
+}

package/src/share/scripts/gsap-mountain-journey.ts

@@ -0,0 +1,236 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0802] GSAP mountain journey animation. Animates a marker along an SVG
+  route path to a score position and zooms the camera out simultaneously.
+  Triggered by form submission, not scroll. Respects prefers-reduced-motion.
+</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+  <item>Do not use ScrollTrigger — this animation is form-triggered, not scroll-triggered.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0802: initial implementation with MotionPathPlugin, form-triggered animation, and reduced-motion fallback.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface MountainJourneyAnimationOptions {
+  sceneSelector: string;
+  visualSelector: string;
+  routeSelector: string;
+  markerSelector: string;
+  formSelector: string;
+  errorSelector: string;
+  workerEndpoint: string;
+}
+
+const CAMERA_INITIAL_ZOOM = 3;
+const CAMERA_FINAL_ZOOM = 1.0;
+const ANIMATION_DURATION = 3;
+const DEFAULT_SCORE = 30;
+
+export async function initMountainJourneyAnimation(
+  options: MountainJourneyAnimationOptions,
+): Promise<void> {
+  const scene = document.querySelector<HTMLElement>(options.sceneSelector);
+  if (!scene) return;
+
+  const visual = document.querySelector<HTMLElement>(options.visualSelector);
+  const route = document.querySelector<SVGPathElement>(options.routeSelector);
+  const marker = document.querySelector<SVGCircleElement>(options.markerSelector);
+  const form = document.querySelector<HTMLFormElement>(options.formSelector);
+  const errorEl = document.querySelector<HTMLElement>(options.errorSelector);
+
+  if (!visual || !route || !marker || !form || !errorEl) return;
+
+  const prefersReducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+  const startPoint = route.getPointAtLength(0);
+  marker.setAttribute("cx", String(startPoint.x));
+  marker.setAttribute("cy", String(startPoint.y));
+
+  if (!prefersReducedMotion) {
+    visual.style.transform = `scale(${CAMERA_INITIAL_ZOOM})`;
+  }
+
+  let activeTl: { kill: () => void } | null = null;
+  let hasAnimated = false;
+
+  const input = form.querySelector<HTMLInputElement>('input[name="url"]');
+  if (input) {
+    input.addEventListener("input", () => {
+      if (!hasAnimated) return;
+      hasAnimated = false;
+      errorEl.hidden = true;
+
+      if (activeTl) {
+        activeTl.kill();
+        activeTl = null;
+      }
+
+      if (prefersReducedMotion) {
+        marker.setAttribute("cx", String(startPoint.x));
+        marker.setAttribute("cy", String(startPoint.y));
+        return;
+      }
+
+      void (async () => {
+        try {
+          const { gsap } = await import("gsap");
+
+          const currentCx = parseFloat(marker.getAttribute("cx") ?? String(startPoint.x));
+          const currentCy = parseFloat(marker.getAttribute("cy") ?? String(startPoint.y));
+          const pathLength = route.getTotalLength();
+          const currentLen = findNearestLength(route, currentCx, currentCy, pathLength);
+
+          const progress = { t: currentLen };
+          const targetLen = 0;
+
+          const tl = gsap.timeline();
+          activeTl = tl;
+          tl.to(
+            progress,
+            {
+              duration: ANIMATION_DURATION,
+              ease: "power2.inOut",
+              t: targetLen,
+              onUpdate: () => {
+                const pt = route.getPointAtLength(progress.t);
+                marker.setAttribute("cx", String(pt.x));
+                marker.setAttribute("cy", String(pt.y));
+              },
+            },
+            0,
+          );
+          tl.to(
+            visual,
+            {
+              duration: ANIMATION_DURATION,
+              ease: "power2.inOut",
+              scale: CAMERA_INITIAL_ZOOM,
+            },
+            0,
+          );
+        } catch (err) {
+          console.error("[mountain-journey] reset animation failed:", err);
+          marker.setAttribute("cx", String(startPoint.x));
+          marker.setAttribute("cy", String(startPoint.y));
+        }
+      })();
+    });
+  }
+
+  form.addEventListener("submit", async (event) => {
+    event.preventDefault();
+    const formData = new FormData(form);
+    const rawInput = String(formData.get("url") ?? "").trim();
+    if (!rawInput) return;
+
+    const domain = rawInput.replace(/^https?:\/\//, "").replace(/\/$/, "");
+
+    errorEl.hidden = true;
+
+    let score: number = DEFAULT_SCORE;
+    try {
+      const response = await fetch(options.workerEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ url: domain }),
+      });
+
+      if (response.ok) {
+        const data = (await response.json()) as { score: number };
+        score = Math.max(0, Math.min(100, data.score));
+      }
+    } catch {
+      // CORS or network error — use default score
+    }
+
+    if (prefersReducedMotion) {
+      placeMarkerAtScore(route, marker, score);
+      hasAnimated = true;
+      return;
+    }
+
+    try {
+      const { gsap } = await import("gsap");
+
+      if (activeTl) {
+        activeTl.kill();
+        activeTl = null;
+      }
+
+      const pathLength = route.getTotalLength();
+      const targetLength = (score / 100) * pathLength;
+      const sp = route.getPointAtLength(0);
+      marker.setAttribute("cx", String(sp.x));
+      marker.setAttribute("cy", String(sp.y));
+
+      const progress = { t: 0 };
+
+      gsap.set(visual, { scale: CAMERA_INITIAL_ZOOM });
+
+      const tl = gsap.timeline();
+      activeTl = tl;
+      tl.to(
+        progress,
+        {
+          duration: ANIMATION_DURATION,
+          ease: "power2.inOut",
+          t: 1,
+          onUpdate: () => {
+            const len = progress.t * targetLength;
+            const pt = route.getPointAtLength(len);
+            marker.setAttribute("cx", String(pt.x));
+            marker.setAttribute("cy", String(pt.y));
+          },
+        },
+        0,
+      );
+      tl.to(
+        visual,
+        {
+          duration: ANIMATION_DURATION,
+          ease: "power2.inOut",
+          scale: CAMERA_FINAL_ZOOM,
+        },
+        0,
+      );
+      hasAnimated = true;
+    } catch (err) {
+      console.error("[mountain-journey] GSAP animation failed:", err);
+      placeMarkerAtScore(route, marker, score);
+      hasAnimated = true;
+    }
+  });
+}
+
+function placeMarkerAtScore(route: SVGPathElement, marker: SVGCircleElement, score: number): void {
+  const pathLength = route.getTotalLength();
+  const targetLength = (score / 100) * pathLength;
+  const point = route.getPointAtLength(targetLength);
+  marker.setAttribute("cx", String(point.x));
+  marker.setAttribute("cy", String(point.y));
+}
+
+function findNearestLength(
+  route: SVGPathElement,
+  cx: number,
+  cy: number,
+  pathLength: number,
+): number {
+  let bestLen = 0;
+  let bestDist = Infinity;
+  const samples = 100;
+  for (let i = 0; i <= samples; i++) {
+    const len = (i / samples) * pathLength;
+    const pt = route.getPointAtLength(len);
+    const dist = (pt.x - cx) ** 2 + (pt.y - cy) ** 2;
+    if (dist < bestDist) {
+      bestDist = dist;
+      bestLen = len;
+    }
+  }
+  return bestLen;
+}

package/src/share/scripts/gsap-parallax.ts

@@ -0,0 +1,50 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0106] GSAP parallax for [data-parallax-speed] elements (emitted by
+  <SectionImage parallax> and <SiteBackground kind: image>).
+</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface GsapParallaxOptions {
+  prefersReducedMotion?: boolean;
+}
+
+export async function initGsapParallax(options: GsapParallaxOptions = {}): Promise<void> {
+  const prefersReducedMotion =
+    options.prefersReducedMotion ?? window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  if (prefersReducedMotion) return;
+
+  const targets = document.querySelectorAll<HTMLElement>("[data-parallax-speed]");
+  if (targets.length === 0) return;
+
+  const { gsap } = await import("gsap");
+  const { ScrollTrigger } = await import("gsap/ScrollTrigger");
+  gsap.registerPlugin(ScrollTrigger);
+
+  for (const el of Array.from(targets)) {
+    if (el.dataset.parallaxReady === "true") continue;
+    el.dataset.parallaxReady = "true";
+
+    const speed = Number.parseFloat(el.dataset.parallaxSpeed ?? "0.4");
+    const parent = el.parentElement ?? el;
+
+    gsap.to(el, {
+      yPercent: speed * -50,
+      ease: "none",
+      scrollTrigger: {
+        trigger: parent,
+        start: "top bottom",
+        end: "bottom top",
+        scrub: true,
+      },
+    });
+  }
+}

package/src/share/scripts/gsap-reveal.ts

@@ -0,0 +1,65 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0106] GSAP scroll-triggered reveal animation. Hooks every
+  [data-motion-reveal] element with fade / fade-up / fade-up-stagger variants.
+  Respects prefers-reduced-motion.
+</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface GsapRevealOptions {
+  prefersReducedMotion?: boolean;
+}
+
+export async function initGsapReveal(options: GsapRevealOptions = {}): Promise<void> {
+  const prefersReducedMotion =
+    options.prefersReducedMotion ?? window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  if (prefersReducedMotion) return;
+
+  const targets = document.querySelectorAll<HTMLElement>("[data-motion-reveal]");
+  if (targets.length === 0) return;
+
+  const { gsap } = await import("gsap");
+  const { ScrollTrigger } = await import("gsap/ScrollTrigger");
+  gsap.registerPlugin(ScrollTrigger);
+
+  for (const el of Array.from(targets)) {
+    if (el.dataset.motionRevealReady === "true") continue;
+    el.dataset.motionRevealReady = "true";
+
+    const variant = el.dataset.motionRevealVariant ?? "fade-up";
+    const threshold = Number.parseFloat(el.dataset.motionRevealThreshold ?? "0.15");
+    const once = el.dataset.motionRevealOnce !== "false";
+
+    const fromVars: gsap.TweenVars = { opacity: 0 };
+    if (variant === "fade-up" || variant === "fade-up-stagger") {
+      fromVars.y = 16;
+    }
+
+    const toVars: gsap.TweenVars = {
+      opacity: 1,
+      y: 0,
+      duration: 0.6,
+      ease: "power2.out",
+      scrollTrigger: {
+        trigger: el,
+        start: `top ${100 - threshold * 100}%`,
+        toggleActions: once ? "play none none none" : "play none none reverse",
+      },
+    };
+
+    if (variant === "fade-up-stagger") {
+      const children = el.querySelectorAll<HTMLElement>(":scope > *");
+      gsap.from(Array.from(children), { ...fromVars, ...toVars, stagger: 0.1 });
+    } else {
+      gsap.from(el, { ...fromVars, ...toVars });
+    }
+  }
+}

package/src/share/scripts/gsap-stagger.ts

@@ -0,0 +1,54 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0106] GSAP stagger for [data-motion-stagger] parents — animates child
+  elements in sequence on scroll-in.
+</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface GsapStaggerOptions {
+  prefersReducedMotion?: boolean;
+}
+
+export async function initGsapStagger(options: GsapStaggerOptions = {}): Promise<void> {
+  const prefersReducedMotion =
+    options.prefersReducedMotion ?? window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  if (prefersReducedMotion) return;
+
+  const targets = document.querySelectorAll<HTMLElement>("[data-motion-stagger]");
+  if (targets.length === 0) return;
+
+  const { gsap } = await import("gsap");
+  const { ScrollTrigger } = await import("gsap/ScrollTrigger");
+  gsap.registerPlugin(ScrollTrigger);
+
+  for (const parent of Array.from(targets)) {
+    if (parent.dataset.motionStaggerReady === "true") continue;
+    parent.dataset.motionStaggerReady = "true";
+
+    const childSelector = parent.dataset.motionStaggerChild ?? "[data-motion-child]";
+    const delay = Number.parseFloat(parent.dataset.motionStaggerDelay ?? "0.1");
+    const children = parent.querySelectorAll<HTMLElement>(childSelector);
+    if (children.length === 0) continue;
+
+    gsap.from(Array.from(children), {
+      opacity: 0,
+      y: 12,
+      duration: 0.5,
+      ease: "power2.out",
+      stagger: delay,
+      scrollTrigger: {
+        trigger: parent,
+        start: "top 85%",
+        toggleActions: "play none none none",
+      },
+    });
+  }
+}

package/src/share/scripts/index.ts

@@ -0,0 +1,25 @@
+/* 
+<MODULE_CONTRACT> 
+<purpose>Serves as a central export point for various script modules utilized 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>Added Compass scaffolding to clarify module roles and prevent scope creep.</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 "./lenis.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.