@linear_non/stellar-kit 3.0.5 → 3.0.6

package/core/PageEngine.js

@@ -2,6 +2,7 @@ import { Manager } from "../classes/index.js"
 import { emitter, EVENTS } from "../events/index.js"
 import { Debug, qsa } from "../utils/index.js"
 import { kitStore } from "../kitStore.js"
+import { ScrollTrigger } from "../libraries/gsap/index.js"
 
 /**
  * @typedef {Object} EngineOwner
@@ -23,9 +24,16 @@ import { kitStore } from "../kitStore.js"
 /**
  * @typedef {Object} EngineSetupConfig
  * @property {Array<any>} components - Array of component constructors/definitions.
- * @property {any} smooth - Smooth instance for scroll control.
+ * @property {Object} [lenis] - Lenis instance. If provided, uses Lenis mode.
+ * @property {HTMLElement} [wrapper] - Scroll wrapper element (required if lenis is provided).
+ * @property {any} [smooth] - Legacy: Smooth instance for internal scroll mode.
  */
 
+/**
+ * Unified page engine that handles both internal scroll and Lenis modes.
+ * - Pass `lenis` + `wrapper` in setup() → Lenis mode (auto-configures ticker + ScrollTrigger)
+ * - Don't pass lenis → Internal scroll mode (uses APP_TICK from Raf.js)
+ */
 export default class PageEngine {
   /**
    * @param {{ owner: EngineOwner }} param0
@@ -52,11 +60,23 @@ export default class PageEngine {
     this.manager = null
 
     /**
-     * Smooth instance passed in by project Page
+     * Smooth/Lenis instance
      * @type {any | null}
      */
     this.smooth = null
 
+    /**
+     * Lenis instance (if using Lenis mode)
+     * @type {any | null}
+     */
+    this.lenis = null
+
+    /**
+     * Wrapper element for ScrollTrigger proxy
+     * @type {HTMLElement | null}
+     */
+    this.wrapper = null
+
     /**
      * @type {EngineScrollState}
      */
@@ -81,16 +101,23 @@ export default class PageEngine {
   }
 
   /**
-   * Called by Page.initCore().
-   * Recreates Manager and binds a new Smooth instance.
+   * Setup the engine with components and optional scroll instance.
+   * Auto-detects Lenis mode if `lenis` is provided.
    *
    * @param {EngineSetupConfig} param0
    */
-  setup({ components, smooth }) {
-    Debug.log("ENGINE", "Setup", { components, smooth })
+  setup({ components, lenis, wrapper, smooth }) {
+    Debug.log("ENGINE", "Setup", { components, lenis, wrapper, smooth })
 
     this.components = components || []
-    this.smooth = smooth || null
+
+    if (lenis && wrapper) {
+      // Lenis mode: auto-configure ticker and ScrollTrigger
+      this._setupLenis(lenis, wrapper)
+    } else if (smooth) {
+      // Legacy: smooth instance passed directly
+      this.smooth = smooth
+    }
 
     this.manager = new Manager()
 
@@ -108,6 +135,54 @@ export default class PageEngine {
     this.resize()
   }
 
+  /**
+   * Setup Lenis: register with global Raf and configure ScrollTrigger.
+   * Raf.js handles the lenis.raf() call on each tick.
+   * @param {Object} lenis - Lenis instance
+   * @param {HTMLElement} wrapper - Scroll wrapper element
+   * @private
+   */
+  _setupLenis(lenis, wrapper) {
+    Debug.log("ENGINE", "Setting up Lenis mode")
+
+    this.lenis = lenis
+    this.wrapper = wrapper
+    this.smooth = lenis
+
+    // Store scroller globally so components can access it
+    kitStore.scroller = wrapper
+
+    // Register Lenis with global Raf - it will call lenis.raf() on each tick
+    if (kitStore.raf) {
+      kitStore.raf.setLenis(lenis)
+    }
+
+    // Wire Lenis scroll events to ScrollTrigger
+    this.lenis.on("scroll", ScrollTrigger.update)
+
+    // Setup ScrollTrigger scroller proxy
+    ScrollTrigger.scrollerProxy(wrapper, {
+      scrollTop: (value) => {
+        if (value !== undefined) {
+          this.lenis.scrollTo(value, { immediate: true })
+        }
+        return this.lenis.scroll
+      },
+      getBoundingClientRect: () => ({
+        top: 0,
+        left: 0,
+        width: window.innerWidth,
+        height: window.innerHeight,
+      }),
+      pinType: wrapper.style.transform ? "transform" : "fixed",
+    })
+
+    // Set default scroller for all ScrollTrigger instances
+    ScrollTrigger.defaults({ scroller: wrapper })
+
+    Debug.log("ENGINE", "Lenis setup complete", { wrapper, scrollerSet: true })
+  }
+
   /**
    * Adds `.loaded` class to images when loaded.
    * Looks for `.lazy` images.
@@ -134,42 +209,22 @@ export default class PageEngine {
 
   /**
    * Receives data from global Raf (APP_TICK).
-   * In internal mode, uses {current, diff} from Scroll.js.
-   * In external mode (Lenis), calls smooth.raf() and derives scroll.
+   * Raf already handles Lenis.raf() call and provides correct scroll values.
    *
    * @param {{ current: number, diff: number, mouse: EngineMouseState }} param0
    */
   tick = ({ current, diff, mouse }) => {
-    const { isResizing, isLocked, useExternalScroll } = kitStore.flags
+    const { isResizing, isLocked } = kitStore.flags
 
     if (isResizing || isLocked) return
     if (!this.manager) return
 
-    let nextScroll = current
-    let delta = diff
-
-    if (useExternalScroll && this.smooth?.raf) {
-      const t = performance.now()
-      this.smooth.raf(t)
-
-      if (typeof this.smooth.scroll === "number") {
-        nextScroll = this.smooth.scroll
-      } else if (typeof this.smooth.targetScroll === "number") {
-        nextScroll = this.smooth.targetScroll
-      } else {
-        nextScroll = window.scrollY || window.pageYOffset || 0
-      }
-
-      delta = nextScroll - this.scroll.current
-    }
+    this.scroll.current = current
+    this.scroll.direction = diff > 0 ? "down" : "up"
 
-    this.scroll.current = nextScroll
-    this.scroll.direction = delta > 0 ? "down" : "up"
-    
     this.mouse.x = mouse.x
     this.mouse.y = mouse.y
-    
-    // Debug.log("ENGINE", "Tick scroll:", this.scroll)
+
     this.manager.tick?.({
       mouse: this.mouse,
       scroll: this.scroll,
@@ -178,15 +233,15 @@ export default class PageEngine {
 
   /**
    * Called during APP_RESIZE.
-   * Updates Smooth then calls Manager.resize().
+   * Updates Smooth/Lenis then calls Manager.resize().
    */
   resize = () => {
     Debug.log("ENGINE", "Resize")
 
+    // Lenis
+    this.lenis?.resize?.()
     // Internal Smooth
     this.smooth?.update?.()
-    // Lenis
-    this.smooth?.resize?.()
 
     this.manager?.resize?.()
   }
@@ -229,6 +284,25 @@ export default class PageEngine {
     this.destroy()
   }
 
+  /**
+   * Cleanup Lenis if in Lenis mode.
+   * @private
+   */
+  _destroyLenis() {
+    // Unregister Lenis from global Raf
+    if (kitStore.raf) {
+      kitStore.raf.setLenis(null)
+    }
+
+    if (this.lenis) {
+      this.lenis.destroy()
+      this.lenis = null
+    }
+
+    this.wrapper = null
+    kitStore.scroller = null
+  }
+
   /**
    * Cleanup Smooth + Manager.
    * Called by Page.onLeaveCompleted().
@@ -237,9 +311,13 @@ export default class PageEngine {
     this.manager?.destroy?.()
     this.manager = null
 
-    if (this.smooth) {
-      this.smooth.destroy?.()
-      this.smooth = null
+    // Cleanup Lenis if in Lenis mode
+    this._destroyLenis()
+
+    // Cleanup internal smooth
+    if (this.smooth?.destroy) {
+      this.smooth.destroy()
     }
+    this.smooth = null
   }
-}
+}

package/events/Raf.js

@@ -3,8 +3,54 @@ import emitter, { EVENTS } from "./Emitter"
 import { Debug, lerp } from "../utils"
 import { gsap, ScrollTrigger } from "../libraries/gsap"
 
+/**
+ * @typedef {Object} RafScrollState
+ * @property {number} target - Target scroll position (used in internal scroll mode).
+ * @property {number} current - Current interpolated scroll position.
+ * @property {number} rounded - Rounded scroll position for rendering.
+ * @property {number} ease - Lerp easing factor for smooth interpolation.
+ */
+
+/**
+ * @typedef {Object} RafMouseState
+ * @property {number} x - Current mouse X position.
+ * @property {number} y - Current mouse Y position.
+ * @property {EventTarget|null} target - Current mouse event target element.
+ */
+
+/**
+ * @typedef {Object} RafTickPayload
+ * @property {number} target - Target scroll position.
+ * @property {number} current - Current scroll position.
+ * @property {RafMouseState} mouse - Current mouse state.
+ * @property {number} diff - Scroll delta/difference.
+ */
+
+/**
+ * Global RAF (Request Animation Frame) manager.
+ *
+ * Handles the main animation loop and scroll state for the application.
+ * Supports two scroll modes:
+ *
+ * **Internal Scroll Mode** (`useExternalScroll: false`):
+ * - Receives scroll delta from VirtualScroll via APP_SCROLL events
+ * - Interpolates scroll position using lerp for smooth scrolling
+ * - Sets up ScrollTrigger scroller proxy on pageContent
+ *
+ * **Lenis Mode** (`useExternalScroll: true`):
+ * - Lenis instance is registered via `setLenis()`
+ * - Calls `lenis.raf()` on each tick
+ * - Reads scroll position directly from Lenis
+ * - PageEngine handles ScrollTrigger proxy setup
+ *
+ * Emits `APP_TICK` event on each frame with scroll and mouse data.
+ */
 export default class Raf {
   constructor() {
+    /**
+     * Scroll state for internal scroll mode.
+     * @type {RafScrollState}
+     */
     this.scroll = {
       target: 0,
       current: 0,
@@ -12,14 +58,28 @@ export default class Raf {
       ease: 0.115,
     }
 
+    /**
+     * Current mouse position state.
+     * @type {RafMouseState}
+     */
     this.mouse = {
       x: 0,
       y: 0,
       target: null,
     }
 
+    /**
+     * Scroll delta between frames.
+     * @type {number}
+     */
     this.diff = 0
 
+    /**
+     * Lenis instance when using external scroll mode.
+     * @type {Object|null}
+     */
+    this.lenis = null
+
     this.tick = this.tick.bind(this)
     this.onScroll = this.onScroll.bind(this)
     this.onMouseMove = this.onMouseMove.bind(this)
@@ -29,10 +89,29 @@ export default class Raf {
     this.onPageShow = this.resume.bind(this)
   }
 
+  /**
+   * Register Lenis instance for external scroll mode.
+   * When set, tick() will call lenis.raf() and read scroll position from Lenis.
+   * @param {Object|null} lenis - Lenis instance, or null to unregister.
+   */
+  setLenis(lenis) {
+    this.lenis = lenis
+    if (lenis) {
+      gsap.ticker.lagSmoothing(0)
+    }
+  }
+
+  /**
+   * Initialize the RAF system.
+   * Sets up ScrollTrigger scroller proxy for internal scroll mode.
+   */
   init() {
     this.setScrollTrigger()
   }
 
+  /**
+   * Activate all event listeners and start the animation loop.
+   */
   on() {
     gsap.ticker.add(this.tick)
 
@@ -44,6 +123,9 @@ export default class Raf {
     window.addEventListener("pageshow", this.onPageShow)
   }
 
+  /**
+   * Deactivate all event listeners and stop the animation loop.
+   */
   off() {
     gsap.ticker.remove(this.tick)
 
@@ -55,10 +137,18 @@ export default class Raf {
     window.removeEventListener("pageshow", this.onPageShow)
   }
 
+  /**
+   * Cleanup and destroy the RAF system.
+   */
   destroy() {
     this.off()
   }
 
+  /**
+   * Handle smooth resize events.
+   * Clamps scroll values to valid range and updates ScrollTrigger.
+   * @private
+   */
   onAppResize() {
     const { fh } = kitStore.sizes
 
@@ -69,17 +159,39 @@ export default class Raf {
     ScrollTrigger.update()
   }
 
-  tick() {
+  /**
+   * Main animation loop tick.
+   * Called on each frame via GSAP ticker.
+   *
+   * - In Lenis mode: calls lenis.raf() and reads scroll from Lenis
+   * - In internal mode: interpolates scroll using lerp
+   *
+   * Emits APP_TICK event with current scroll and mouse state.
+   *
+   * @param {number} time - Current time from GSAP ticker (in seconds).
+   */
+  tick(time) {
     if (kitStore.flags.isResizing) return
 
-    const { target, current, ease } = this.scroll
+    // Lenis mode: update Lenis first, then read scroll from it
+    if (this.lenis) {
+      this.lenis.raf(time * 1000)
+
+      const lenisScroll = this.lenis.scroll ?? 0
+      this.diff = lenisScroll - this.scroll.current
+      this.scroll.current = lenisScroll
+      this.scroll.rounded = lenisScroll
+    } else {
+      // Internal scroll mode
+      const { target, current, ease } = this.scroll
 
-    this.scroll.current = lerp(current, target, ease)
-    this.scroll.rounded = Math.round(this.scroll.current * 100) / 100
-    this.diff = (target - this.scroll.current) * 0.005
+      this.scroll.current = lerp(current, target, ease)
+      this.scroll.rounded = Math.round(this.scroll.current * 100) / 100
+      this.diff = (target - this.scroll.current) * 0.005
+    }
 
     emitter.emit(EVENTS.APP_TICK, {
-      target,
+      target: this.lenis ? this.scroll.current : this.scroll.target,
       current: this.getScroll(),
       mouse: this.mouse,
       diff: this.diff,
@@ -88,29 +200,61 @@ export default class Raf {
     ScrollTrigger.update()
   }
 
+  /**
+   * Get the current scroll position.
+   * - In Lenis mode: returns the rounded Lenis scroll value.
+   * - In internal smooth mode: returns the interpolated scroll value.
+   * - In native mode: returns the container's scrollTop.
+   * @returns {number} Current scroll position.
+   */
   getScroll() {
+    // Lenis mode: return Lenis scroll position
+    if (this.lenis) {
+      return this.scroll.rounded
+    }
+
+    // Internal mode
     const { pageContent, flags } = kitStore
     const container = pageContent ? pageContent.parentNode : document.body
     return flags.isSmooth ? this.scroll.rounded : container.scrollTop
   }
 
+  /**
+   * Clamp scroll target to valid range (0 to full height).
+   * @private
+   */
   clamp() {
     const { fh } = kitStore.sizes
     this.scroll.target = Math.min(Math.max(this.scroll.target, 0), fh)
   }
 
+  /**
+   * Handle scroll events from VirtualScroll (internal scroll mode).
+   * Adds delta to target and clamps to valid range.
+   * @param {{ y: number }} param0 - Scroll delta.
+   * @private
+   */
   onScroll({ y }) {
     if (kitStore.flags.isLocked) return
     this.scroll.target += y
     this.clamp()
   }
 
+  /**
+   * Handle mouse move events.
+   * @param {{ x: number, y: number, target: EventTarget }} param0 - Mouse position and target.
+   * @private
+   */
   onMouseMove({ x, y, target }) {
     this.mouse.x = x
     this.mouse.y = y
     this.mouse.target = target
   }
 
+  /**
+   * Smoothly scroll to a target offset.
+   * @param {number} offset - Target scroll position in pixels.
+   */
   scrollTo(offset) {
     if (kitStore.flags.isSmooth) {
       gsap.to(this.scroll, {
@@ -123,6 +267,10 @@ export default class Raf {
     }
   }
 
+  /**
+   * Immediately set scroll position (no animation).
+   * @param {number} offset - Target scroll position in pixels.
+   */
   setScroll(offset) {
     if (kitStore.flags.isSmooth) {
       gsap.set(this.scroll, {
@@ -135,10 +283,25 @@ export default class Raf {
     }
   }
 
+  /**
+   * Configure ScrollTrigger for internal scroll mode.
+   * Sets up scroller proxy and defaults.
+   * Skipped when useExternalScroll is true (PageEngine handles it).
+   * @private
+   */
   setScrollTrigger() {
+    // Skip if useExternalScroll flag is set - PageEngine will handle ScrollTrigger setup
+    if (kitStore.flags.useExternalScroll) {
+      Debug.log("RAF", "Skipping ScrollTrigger setup (external scroll mode)")
+      return
+    }
+
     const { pageContent } = kitStore
     const scroller = pageContent || document.body
 
+    // Store scroller globally so components can access it
+    kitStore.scroller = scroller
+
     Debug.log(
       "RAF",
       "Setting ScrollTrigger scroller to:",
@@ -159,10 +322,17 @@ export default class Raf {
     })
   }
 
+  /**
+   * Pause the animation loop (e.g., when page is hidden).
+   */
   stop() {
     gsap.ticker.remove(this.tick)
   }
 
+  /**
+   * Resume the animation loop (e.g., when page becomes visible).
+   * Syncs current scroll to target to prevent jumps.
+   */
   resume() {
     this.scroll.current = this.scroll.target
     this.scroll.rounded = this.scroll.target

package/kitStore.js

@@ -42,4 +42,10 @@ export const kitStore = {
   flags,
   pageContent: null,
   assets,
+  /**
+   * Scroll scroller element (wrapper for Lenis, pageContent for internal scroll).
+   * Used by ScrollTrigger components to get the correct scroller.
+   * @type {HTMLElement | null}
+   */
+  scroller: null,
 }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@linear_non/stellar-kit",
-  "version": "3.0.5",
+  "version": "3.0.6",
   "description": "Stellar frontend core for Non-Linear Studio projects.",
   "type": "module",
   "main": "/core/index.js",
   "sass": "./styles/index.scss",
   "exports": {
     ".": "./kitStore.js",
+    "./kitStore": "./kitStore.js",
     "./utils": "./utils/index.js",
     "./core": "./core/index.js",
     "./classes": "./classes/index.js",

package/plugins/Observer.js

@@ -1,5 +1,6 @@
 import { Emitter } from "../events"
 import { ScrollTrigger } from "../libraries/gsap"
+import { kitStore } from "../kitStore"
 
 const DEFAULTS = {
   trigger: null,
@@ -33,6 +34,7 @@ export default class Observer extends Emitter {
       scrub,
       once,
       markers,
+      scroller: kitStore.scroller || undefined,
       onEnter: forward("enter"),
       onLeave: forward("leave"),
       onEnterBack: forward("enterBack"),