chati-dev 4.2.2 → 4.3.1

package/framework/scaffold/motion-premium/lib/animations/gsap.ts.template

@@ -0,0 +1,112 @@
+/**
+ * lib/animations/gsap.ts — scaffold motion-premium v1.0.0
+ *
+ * Module-level GSAP setup: plugin registration, Lenis integration, reduced-motion
+ * detection. The non-obvious choices here are the difference between "premium"
+ * and "broken under real-world conditions" — do not remove without reading why.
+ *
+ * Non-obvious choices:
+ *
+ * - `gsap.registerPlugin(ScrollTrigger)` at MODULE level (not inside a hook or
+ *   component) — this is called exactly once per app load, regardless of HMR
+ *   reloads or strict-mode double-mounts. Registering inside a component
+ *   causes a silent warning and then silent failure as GSAP rejects the second
+ *   registration.
+ *
+ * - `gsap.ticker.lagSmoothing(0)` — SAUCE PATTERN #1. By default, when the tab
+ *   loses focus (or the browser throttles a background tab), `requestAnimationFrame`
+ *   stops firing. GSAP compensates by "smoothing" the accumulated lag the next
+ *   time RAF fires, time-scaling animations to catch up. For scroll-driven
+ *   animations this presents as a snap: the page jerks forward as GSAP races to
+ *   "catch up" scroll-linked progress values. Disabling smoothing keeps
+ *   progress tied strictly to real scroll position, no catch-up.
+ *
+ * - Single RAF loop — SAUCE PATTERN #5. Lenis has its own RAF and GSAP has its
+ *   own ticker; running both causes subtle drift (their clocks diverge over
+ *   minutes). Hooking Lenis into `gsap.ticker.add` makes GSAP the authoritative
+ *   clock, Lenis a consumer. Zero drift, one RAF, one heartbeat.
+ *
+ * - `lenis.raf(time * 1000)` — GSAP ticker passes time in SECONDS, Lenis.raf
+ *   expects MILLISECONDS. Forgetting this multiplication produces smooth-scroll
+ *   that runs 1000x slower than expected.
+ *
+ * - `window.scrollTo(0, 0)` + `lenis.scrollTo(0, immediate: true)` on init —
+ *   defends against browser's default scrollRestoration on back/forward
+ *   navigation. Combined with `history.scrollRestoration = 'manual'` in
+ *   layout.tsx (phase 3), guarantees the page opens at top.
+ *
+ * - `ScrollTrigger.refresh()` AFTER Lenis init — required because ScrollTrigger
+ *   measures scroll positions using the native scrollbar by default; once Lenis
+ *   takes over, all positions must be re-measured against the virtualized
+ *   scroll surface.
+ *
+ * - `(window as unknown as {...}).lenis = lenis` — exposes the Lenis/GSAP
+ *   instances on the global window. Used by the chati-dev visual-qa.js script
+ *   to call `window.lenis.scrollTo()` during capture runs. Also useful for
+ *   in-browser debugging. DO NOT remove — regression surface.
+ */
+
+'use client';
+
+import { gsap } from 'gsap';
+import { ScrollTrigger } from 'gsap/ScrollTrigger';
+
+// Register plugins once at module level (see header: registration reason).
+gsap.registerPlugin(ScrollTrigger);
+
+export { gsap, ScrollTrigger };
+
+/**
+ * Initialize Lenis smooth scroll and connect it to GSAP + ScrollTrigger.
+ * Call this ONCE per app lifecycle from `useSmoothScroll` (LenisProvider).
+ * Returns the lenis instance for explicit teardown on unmount.
+ */
+export async function initLenis() {
+  const { default: Lenis } = await import('lenis');
+
+  const lenis = new Lenis({
+    duration: 1.2,
+    easing: (t: number) => Math.min(1, 1.001 - Math.pow(2, -10 * t)),
+    smoothWheel: true,
+  });
+
+  if (typeof window !== 'undefined') {
+    window.scrollTo(0, 0);
+    lenis.scrollTo(0, { immediate: true });
+  }
+
+  lenis.on('scroll', ScrollTrigger.update);
+
+  // Single RAF loop — GSAP is the authoritative clock; Lenis consumes it.
+  gsap.ticker.add((time) => {
+    lenis.raf(time * 1000);
+  });
+
+  // Sauce pattern #1: eliminates tab-restore snap for scroll-driven animations.
+  gsap.ticker.lagSmoothing(0);
+
+  // Refresh ScrollTrigger AFTER Lenis is live so scroll positions are measured
+  // against the virtualized surface, not the native scrollbar.
+  ScrollTrigger.refresh();
+
+  // Expose globally for QA scripts (visual-qa.js reads window.lenis for capture).
+  if (typeof window !== 'undefined') {
+    (window as unknown as { lenis: typeof lenis }).lenis = lenis;
+    (window as unknown as { gsap: typeof gsap }).gsap = gsap;
+    (window as unknown as { ScrollTrigger: typeof ScrollTrigger }).ScrollTrigger = ScrollTrigger;
+  }
+
+  return lenis;
+}
+
+/**
+ * Check if the user has requested reduced motion.
+ * SSR-safe: returns false during server render (no `window`).
+ *
+ * Consumers: useGsapContext (early-return), every animated component that
+ * needs a reduced-motion branch.
+ */
+export function prefersReducedMotion(): boolean {
+  if (typeof window === 'undefined') return false;
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}

package/framework/scaffold/motion-premium/lib/animations/refreshCoordinator.ts.template

@@ -0,0 +1,75 @@
+/**
+ * lib/animations/refreshCoordinator.ts — scaffold motion-premium v1.0.0
+ *
+ * Debounced singleton for ScrollTrigger.refresh(). Coalesces N simultaneous
+ * refresh requests from N components mounting together into ONE refresh at
+ * the end of the debounce window.
+ *
+ * Non-obvious choices:
+ *
+ * - SAUCE PATTERN #9. Multiple components requesting refresh on mount is
+ *   common: image loaded → want refresh, font loaded → want refresh, video
+ *   ready → want refresh. Each raw `ScrollTrigger.refresh()` call iterates
+ *   all registered triggers and recomputes their start/end positions —
+ *   expensive, and visible as a layout jitter. Debouncing means the browser
+ *   sees ONE recompute for the burst instead of N.
+ *
+ * - `DEBOUNCE_MS = 200` — long enough to coalesce typical "everything mounted
+ *   this frame" bursts (which settle in under 100ms on fast hardware, up to
+ *   200ms on slow), short enough that a user will not perceive the delay
+ *   before layout correctness kicks in.
+ *
+ * - Module-level `_timer` singleton — the whole point is cross-component
+ *   coordination. A hook-level timer wouldn't coalesce across siblings.
+ *
+ * - Dynamic `import('gsap/ScrollTrigger')` inside the debounced fn —
+ *   keeps this module importable from SSR paths without pulling GSAP into
+ *   the server bundle. The debounced fn only ever runs client-side (after
+ *   the `typeof window === 'undefined'` guard in `requestRefresh`).
+ *
+ * - `cancelPendingRefresh` helper — exposed so page-transition handlers can
+ *   abort a pending refresh that would otherwise fire during an unmount
+ *   animation (the refresh rips triggers away that the exit animation is
+ *   still using). Most callers don't need this; it's a surgical tool.
+ */
+
+export const DEBOUNCE_MS = 200;
+
+let _timer: ReturnType<typeof setTimeout> | null = null;
+
+/**
+ * Request a ScrollTrigger.refresh(). Multiple calls within DEBOUNCE_MS
+ * coalesce into a single refresh at the end of the debounce window.
+ *
+ * Safe to call from SSR context: no-ops when window is undefined.
+ */
+export function requestRefresh(): void {
+  if (typeof window === 'undefined') return;
+
+  // Cancel any pending refresh
+  if (_timer !== null) {
+    clearTimeout(_timer);
+    _timer = null;
+  }
+
+  // Schedule a new refresh
+  _timer = setTimeout(async () => {
+    _timer = null;
+    const { ScrollTrigger } = await import('gsap/ScrollTrigger');
+    ScrollTrigger.refresh();
+  }, DEBOUNCE_MS);
+}
+
+/**
+ * Cancel any pending refresh. Use before a page transition / unmount that
+ * should not be perturbed by a trailing refresh.
+ *
+ * Usually not needed — the refresh is harmless after unmount. Reach for
+ * this when you see a visible jump during a page transition.
+ */
+export function cancelPendingRefresh(): void {
+  if (_timer !== null) {
+    clearTimeout(_timer);
+    _timer = null;
+  }
+}

package/framework/scaffold/motion-premium/lib/animations/tokens.ts.template

@@ -0,0 +1,119 @@
+/**
+ * lib/animations/tokens.ts — scaffold motion-premium v1.0.0
+ *
+ * Animation constants: easings, durations, staggers, ScrollTrigger defaults.
+ * Mirrors the CSS custom properties declared in app/globals.css.
+ *
+ * Why this file exists separately from globals.css:
+ *   - GSAP accepts easing as a `cubic-bezier(...)` string OR a function;
+ *     Framer Motion expects a 4-number array. Having both shapes here prevents
+ *     every component from re-deriving the same curve math.
+ *   - GSAP uses seconds for duration; CSS uses milliseconds. Converting at
+ *     the token boundary is cleaner than at every call site.
+ *   - Staggers have no CSS equivalent — they live purely in the JS animation
+ *     API, so the TS file is their canonical home.
+ *
+ * Override classification: `partial` — adjust values (e.g. change `cinematic`
+ * from 1.4s to 1.2s), but keep the exported object shape so downstream
+ * templates (useGsapContext consumers, providers) remain compatible.
+ */
+
+// -----------------------------------------------------------------------
+// EASINGS — string form for GSAP + CSS
+// Mirror of --ease-* custom properties declared in app/globals.css.
+// When values change in globals.css, mirror here to avoid drift.
+// -----------------------------------------------------------------------
+export const EASINGS = {
+  /** --ease-default: cubic-bezier(0.25, 0.1, 0.25, 1) */
+  default:   "cubic-bezier(0.25, 0.1, 0.25, 1)",
+  /** --ease-in: cubic-bezier(0.42, 0, 1, 1) */
+  in:        "cubic-bezier(0.42, 0, 1, 1)",
+  /** --ease-out: cubic-bezier(0, 0, 0.58, 1) */
+  out:       "cubic-bezier(0, 0, 0.58, 1)",
+  /** --ease-in-out: cubic-bezier(0.42, 0, 0.58, 1) */
+  inOut:     "cubic-bezier(0.42, 0, 0.58, 1)",
+  /** --ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275) */
+  spring:    "cubic-bezier(0.175, 0.885, 0.32, 1.275)",
+  /** --ease-cinematic: cubic-bezier(0.16, 1, 0.3, 1) */
+  cinematic: "cubic-bezier(0.16, 1, 0.3, 1)",
+  /** --ease-gentle: cubic-bezier(0.4, 0, 0.2, 1) */
+  gentle:    "cubic-bezier(0.4, 0, 0.2, 1)",
+} as const;
+
+export type EasingKey = keyof typeof EASINGS;
+
+// -----------------------------------------------------------------------
+// EASING_CURVES — array form for Framer Motion
+// Same curves as EASINGS but expressed as 4-number tuples. Framer Motion's
+// `ease` prop rejects `cubic-bezier(...)` strings, so this parallel shape
+// is required — do not try to collapse into EASINGS.
+// -----------------------------------------------------------------------
+export const EASING_CURVES: Record<EasingKey, [number, number, number, number]> = {
+  default:   [0.25, 0.1, 0.25, 1],
+  in:        [0.42, 0, 1, 1],
+  out:       [0, 0, 0.58, 1],
+  inOut:     [0.42, 0, 0.58, 1],
+  spring:    [0.175, 0.885, 0.32, 1.275],
+  cinematic: [0.16, 1, 0.3, 1],
+  gentle:    [0.4, 0, 0.2, 1],
+};
+
+// -----------------------------------------------------------------------
+// DURATIONS — seconds (GSAP convention)
+// The CSS side is in milliseconds; the values here are the same intervals
+// converted at the token boundary. Reference mapping in doc comments.
+// -----------------------------------------------------------------------
+export const DURATIONS = {
+  /** --duration-instant: 0ms -> 0s (no-op / CSS-only transitions) */
+  instant:   0,
+  /** --duration-fast: 150ms -> 0.15s (hover states, microinteractions) */
+  fast:      0.15,
+  /** --duration-normal: 300ms -> 0.3s (default UI transitions) */
+  normal:    0.3,
+  /** --duration-slow: 500ms -> 0.5s (panel reveals, accordion) */
+  slow:      0.5,
+  /** --duration-dramatic: 900ms -> 0.9s (hero entrance, section reveals) */
+  dramatic:  0.9,
+  /** --duration-cinematic: 1400ms -> 1.4s (long pin scrubs, crossfades) */
+  cinematic: 1.4,
+} as const;
+
+export type DurationKey = keyof typeof DURATIONS;
+
+// -----------------------------------------------------------------------
+// STAGGERS — inter-element delays (seconds)
+// No CSS equivalent — staggers are an animation-API concept. These are the
+// TypeScript source of truth; there is no globals.css mirror.
+// -----------------------------------------------------------------------
+export const STAGGERS = {
+  /** Fine-grained character or item stagger (split-text reveals) */
+  tight:   0.03,
+  /** Default stagger for lists, cards, grids */
+  default: 0.05,
+  /** Relaxed stagger for section-level reveals */
+  relaxed: 0.1,
+  /** Dramatic entrance stagger for hero copy */
+  hero:    0.15,
+} as const;
+
+export type StaggerKey = keyof typeof STAGGERS;
+
+// -----------------------------------------------------------------------
+// SCROLL_TRIGGER_DEFAULTS — common trigger start/end strings
+// The GSAP "top 80%" syntax means: "fire when element's top is at 80% down
+// the viewport". Defaults here encode the weight/timing recommendations
+// from the reference implementation (reference-website) — they produce the
+// signature feel of the premium pattern set.
+// -----------------------------------------------------------------------
+export const SCROLL_TRIGGER_DEFAULTS = {
+  /** Element enters viewport at 80% from top — standard reveal threshold */
+  standardReveal: "top 80%",
+  /** Element enters viewport at 90% from top — early reveal for large blocks */
+  earlyReveal:    "top 90%",
+  /** Element enters viewport at 70% from top — late reveal for emphasis */
+  lateReveal:     "top 70%",
+  /** Scrub scene start position (pinned panels) */
+  sceneStart:     "top top",
+  /** Scrub scene end (500% viewport height travel — typical pin duration) */
+  sceneEnd:       "+=500%",
+} as const;

package/framework/scaffold/motion-premium/lib/animations/useGsapContext.ts.template

@@ -0,0 +1,92 @@
+/**
+ * lib/animations/useGsapContext.ts — scaffold motion-premium v1.0.0
+ *
+ * Scoped GSAP animations with automatic cleanup and reduced-motion safety.
+ * This is the primary hook every animated component should use.
+ *
+ * Non-obvious choices:
+ *
+ * - `gsap.context(fn, containerRef)` — SAUCE PATTERN #3. The second argument
+ *   SCOPES all selector strings inside `fn` to descendants of containerRef.
+ *   Calling `gsap.fromTo('.title', ...)` inside the context ONLY matches
+ *   `.title` elements within this component, not globally. Without scope, a
+ *   second mount of the same component (or any sibling with .title) would
+ *   double-animate. Forget this and the bug appears as "animations sometimes
+ *   jitter or fire twice on some pages" — hell to debug.
+ *
+ * - `ctx.revert()` on unmount — kills every tween, timeline, and ScrollTrigger
+ *   created inside the context. Without this, ScrollTriggers leak: they stay
+ *   registered against the scroll position, firing on pages that don't contain
+ *   the originating component. Memory cost grows with navigation; worse, the
+ *   leaked triggers intercept wheel events and break Lenis.
+ *
+ * - Reduced-motion early-return with `clearProps` — SAUCE PATTERN #11 tie-in.
+ *   When prefers-reduced-motion is on, we DO NOT run the setup fn (would
+ *   leave initial state like `opacity: 0` stuck). Instead we forcibly show
+ *   all [data-gsap-target] descendants at their final state. `clearProps:
+ *   'transform,opacity'` strips any prior GSAP overrides so CSS defaults take
+ *   effect. Components must tag their animated elements with
+ *   `data-gsap-target` for this fallback to find them.
+ *
+ * - `deps` param — passed to useEffect. Default empty array = run once,
+ *   consistent with how most component animations want it. Pass a non-empty
+ *   array only if the animation genuinely depends on state that can change.
+ *
+ * - `RefObject<HTMLElement | null>` — the `| null` matches React 19's
+ *   stricter ref typing where `useRef<HTMLDivElement>(null)` returns a
+ *   nullable ref. Removing `| null` forces every caller to cast.
+ */
+
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { gsap, prefersReducedMotion } from './gsap';
+
+/**
+ * Run a GSAP setup inside a scoped context tied to a container ref.
+ * Automatically calls `ctx.revert()` on unmount for leak-free teardown.
+ *
+ * Usage:
+ *   const containerRef = useRef<HTMLDivElement>(null);
+ *   useGsapContext(containerRef, (ctx) => {
+ *     gsap.fromTo('.title', { opacity: 0 }, { opacity: 1 });
+ *     // Register ScrollTriggers, timelines, etc. They are all scoped.
+ *   });
+ *
+ * If reduced-motion is active, `setupFn` is NOT called. Instead, all
+ * `[data-gsap-target]` descendants are set to the visible final state.
+ * Mark every animated element with `data-gsap-target` so this fallback
+ * can find it.
+ */
+export function useGsapContext(
+  containerRef: React.RefObject<HTMLElement | null>,
+  setupFn: (context: gsap.Context) => void,
+  deps: React.DependencyList = []
+) {
+  const ctxRef = useRef<gsap.Context | null>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    // Reduced-motion safeguard: skip animations, show targets at final state.
+    if (prefersReducedMotion()) {
+      const targets = containerRef.current.querySelectorAll('[data-gsap-target]');
+      if (targets.length > 0) {
+        gsap.set(targets, { opacity: 1, y: 0, clearProps: 'transform,opacity' });
+      }
+      return;
+    }
+
+    // Scoped context — all selectors inside setupFn match only this subtree.
+    ctxRef.current = gsap.context((ctx) => {
+      setupFn(ctx);
+    }, containerRef);
+
+    // Cleanup: kill every tween / timeline / ScrollTrigger created above.
+    return () => {
+      ctxRef.current?.revert();
+      ctxRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+}

package/framework/scaffold/motion-premium/lib/animations/useScrollSnapStepper.ts.template

@@ -0,0 +1,265 @@
+/**
+ * lib/animations/useScrollSnapStepper.ts — scaffold motion-premium v1.0.0
+ *
+ * Step-snap navigation for horizontally-pinned ScrollTrigger sequences.
+ * One wheel tick = one panel advance. Used by multi-stage pins (method
+ * sections, editorial lists) where free scrub would miss panels entirely.
+ *
+ * The function is named `setupScrollSnapStepper` (not a hook) so callers
+ * can invoke it from inside `useGsapContext` setup fns without nested hooks.
+ *
+ * Non-obvious choices:
+ *
+ * - `normalizeWheelDelta` — WheelEvent.deltaY values differ by deltaMode:
+ *   0 = pixels (trackpad, default), 1 = lines (mouse wheel, multiply by 16),
+ *   2 = pages (rare, multiply by 800). Without normalization, a mouse wheel
+ *   tick (deltaY=1 in mode 1) looks smaller than a trackpad flick (deltaY=50
+ *   in mode 0) and the threshold logic misbehaves.
+ *
+ * - `wheelAccumulator` with 500ms reset — SAUCE PATTERN #13. A trackpad
+ *   momentum scroll fires dozens of small deltaY events. Each alone is
+ *   sub-threshold, but their sum represents clear intent. The accumulator
+ *   sums deltas; the 500ms reset clears stale totals so a slow continuous
+ *   scroll doesn't eventually cross the threshold by itself.
+ *
+ * - `WHEEL_THRESHOLD = 50` — chosen empirically. Low enough that a single
+ *   deliberate swipe crosses it; high enough that drift/noise doesn't.
+ *
+ * - `entryCooldownUntil` — SAUCE PATTERN #12. 600ms cooldown after the pin
+ *   section scrolls INTO view. Without it, the momentum of the entry scroll
+ *   triggers an immediate first-panel snap — user perceives "I just got here,
+ *   why is it already moving?" Cooldown owner (caller) sets this via
+ *   stepState.entryCooldownUntil = performance.now() + 600 on pin start.
+ *
+ * - `lenis.stop()` / `lenis.start()` around programmatic scroll — Lenis's
+ *   smoothWheel listener fights user-initiated scrolls that are actually
+ *   our own programmatic scrollTo. Stopping Lenis prevents the fight; the
+ *   150ms post-complete delay before `start()` absorbs any residual input.
+ *
+ * - `lock: true` on lenis.scrollTo — forbids other scroll inputs until our
+ *   programmatic motion completes. Without it, a rapid second wheel tick
+ *   during a snap causes a compound motion that overshoots by 2 panels.
+ *
+ * - `capture: true` listeners — React's synthetic event system sits downstream
+ *   of native capture-phase listeners. By listening in capture we intercept
+ *   wheel/touch BEFORE React handlers (which may preventDefault on us or
+ *   trigger layout scroll that makes Lenis fight).
+ *
+ * - `passive: false` on wheel + touchmove — required for preventDefault to
+ *   work. Chrome warns (correctly) that passive listeners are faster, but we
+ *   need the ability to cancel the scroll during isBlocked() windows.
+ */
+
+'use client';
+
+import { ScrollTrigger } from './gsap';
+
+/**
+ * Minimal Lenis surface we depend on. Kept narrow so the stepper can work
+ * with any Lenis-like scroll driver (or a shim in tests).
+ */
+export interface LenisLike {
+  stop:  () => void;
+  start: () => void;
+  scrollTo: (
+    v: number,
+    o?: {
+      duration?:   number;
+      easing?:     (t: number) => number;
+      force?:      boolean;
+      onComplete?: () => void;
+      lock?:       boolean;
+    },
+  ) => void;
+}
+
+/**
+ * Retrieve the globally-exposed Lenis instance (see gsap.ts initLenis).
+ * Returns undefined during SSR or before LenisProvider has mounted.
+ */
+export function getLenis(): LenisLike | undefined {
+  if (typeof window === 'undefined') return undefined;
+  const w = window as unknown as { lenis?: LenisLike };
+  return w.lenis;
+}
+
+/**
+ * Mutable state the stepper threads between invocations. Owners typically
+ * allocate one per pinned ScrollTrigger instance.
+ */
+export interface StepState {
+  isSnapping:         boolean;
+  lastScrollTs:       number;
+  entryCooldownUntil: number;
+}
+
+export interface StepByStepConfig {
+  /** ScrollTrigger id that this stepper should advance. */
+  triggerId:  string;
+  /** Number of discrete stages (panels) within the scrubbed range. */
+  stageCount: number;
+  /** Mutable step state (snap in progress, cooldowns, last wheel ts). */
+  stepState:  StepState;
+}
+
+/**
+ * Attach wheel + touch listeners that advance a scrubbed ScrollTrigger one
+ * panel at a time. Returns a cleanup function that removes the listeners;
+ * always pair with useEffect or gsap.context cleanup.
+ *
+ * Typical call site:
+ *   useGsapContext(sectionRef, () => {
+ *     const stepState = { isSnapping: false, lastScrollTs: 0, entryCooldownUntil: 0 };
+ *     ScrollTrigger.create({ id: 'method', trigger: ..., pin: true, ... });
+ *     const cleanup = setupScrollSnapStepper({
+ *       triggerId: 'method', stageCount: 5, stepState,
+ *     });
+ *     return cleanup; // gsap.context.revert() calls this for free if returned
+ *   });
+ */
+export function setupScrollSnapStepper({
+  triggerId,
+  stageCount,
+  stepState,
+}: StepByStepConfig): () => void {
+  const stageStep = 1 / (stageCount - 1);
+  let touchStartY = 0;
+
+  const advance = (direction: number): boolean => {
+    if (stepState.isSnapping) return true;
+    const st = ScrollTrigger.getById(triggerId);
+    if (!st || !st.isActive) return false;
+
+    const currentStep = Math.round(st.progress / stageStep);
+    const nextStep = currentStep + direction;
+
+    if (nextStep < 0 || nextStep > stageCount - 1) return false;
+
+    stepState.isSnapping = true;
+    const lenis = getLenis();
+    if (lenis) lenis.stop();
+
+    const targetProgress = nextStep * stageStep;
+    const targetScroll = st.start + (st.end - st.start) * targetProgress;
+
+    const finish = () => {
+      window.setTimeout(() => {
+        stepState.isSnapping = false;
+        stepState.lastScrollTs = performance.now();
+        if (lenis) lenis.start();
+      }, 150);
+    };
+
+    if (lenis) {
+      lenis.scrollTo(targetScroll, {
+        duration: 0.9,
+        easing: (t: number) => 1 - Math.pow(1 - t, 3),
+        force: true,
+        lock: true,
+        onComplete: finish,
+      });
+      window.setTimeout(finish, 1100);
+    } else {
+      window.scrollTo({ top: targetScroll, behavior: 'smooth' });
+      window.setTimeout(finish, 900);
+    }
+    return true;
+  };
+
+  const isBlocked = () => {
+    const now = performance.now();
+    return (
+      stepState.isSnapping ||
+      now < stepState.entryCooldownUntil ||
+      now - stepState.lastScrollTs < 200
+    );
+  };
+
+  // Normalize WheelEvent deltaY across deltaMode values:
+  // 0 = pixels (pass-through), 1 = lines (*16), 2 = pages (*800).
+  const normalizeWheelDelta = (e: WheelEvent): number => {
+    if (e.deltaMode === 1) return e.deltaY * 16;
+    if (e.deltaMode === 2) return e.deltaY * 800;
+    return e.deltaY;
+  };
+
+  let wheelAccumulator = 0;
+  let wheelResetTimer: ReturnType<typeof setTimeout> | null = null;
+  const WHEEL_THRESHOLD = 50;
+
+  const onWheel = (e: WheelEvent) => {
+    const st = ScrollTrigger.getById(triggerId);
+    if (!st || !st.isActive) return;
+
+    const normalized = normalizeWheelDelta(e);
+    if (Math.abs(normalized) < 1) return;
+
+    if (isBlocked()) {
+      e.preventDefault();
+      e.stopPropagation();
+      return;
+    }
+
+    // Accumulate normalized delta; reset after 500ms of no events.
+    wheelAccumulator += normalized;
+    if (wheelResetTimer !== null) clearTimeout(wheelResetTimer);
+    wheelResetTimer = setTimeout(() => {
+      wheelAccumulator = 0;
+      wheelResetTimer = null;
+    }, 500);
+
+    if (Math.abs(wheelAccumulator) < WHEEL_THRESHOLD) {
+      e.preventDefault();
+      e.stopPropagation();
+      return;
+    }
+
+    // Threshold exceeded: fire step-snap and reset accumulator.
+    const direction = wheelAccumulator > 0 ? 1 : -1;
+    wheelAccumulator = 0;
+    if (wheelResetTimer !== null) {
+      clearTimeout(wheelResetTimer);
+      wheelResetTimer = null;
+    }
+
+    const handled = advance(direction);
+    if (handled) {
+      e.preventDefault();
+      e.stopPropagation();
+    }
+  };
+
+  const onTouchStart = (e: TouchEvent) => {
+    touchStartY = e.touches[0].clientY;
+  };
+
+  const onTouchMove = (e: TouchEvent) => {
+    const st = ScrollTrigger.getById(triggerId);
+    if (!st || !st.isActive) return;
+    if (isBlocked()) {
+      e.preventDefault();
+      e.stopPropagation();
+      return;
+    }
+    // Screen-origin inverted: finger moves DOWN (deltaY > 0 here) = forward scroll.
+    const deltaY = touchStartY - e.touches[0].clientY;
+    if (Math.abs(deltaY) < 25) return;
+    const direction = deltaY > 0 ? 1 : -1;
+    const handled = advance(direction);
+    if (handled) {
+      e.preventDefault();
+      e.stopPropagation();
+      touchStartY = e.touches[0].clientY;
+    }
+  };
+
+  window.addEventListener('wheel',      onWheel,      { passive: false, capture: true });
+  window.addEventListener('touchstart', onTouchStart, { passive: true,  capture: true });
+  window.addEventListener('touchmove',  onTouchMove,  { passive: false, capture: true });
+
+  return () => {
+    window.removeEventListener('wheel',      onWheel,      { capture: true } as EventListenerOptions);
+    window.removeEventListener('touchstart', onTouchStart, { capture: true } as EventListenerOptions);
+    window.removeEventListener('touchmove',  onTouchMove,  { capture: true } as EventListenerOptions);
+  };
+}