@linear_non/stellar-kit 2.1.21 → 3.0.1

package/classes/Manager.js

@@ -1,26 +1,63 @@
-// Manager.js
 import { qsa } from "../utils"
 
+/**
+ * @typedef {import("./Component").default} BaseComponent
+ */
+
+/**
+ * Component life cycle manager.
+ *
+ * @typedef {Object} ComponentDefinition
+ * @property {string} name
+ * @property {new (options: any) => BaseComponent} instance
+ * @property {any} [data]
+ */
 export default class Manager {
+  /**
+   * @param {{ data?: any }} [options]
+   */
   constructor({ data = {} } = {}) {
+    /** @type {{ name: string; component: BaseComponent }[]} */
     this.components = [] // { name, component }
+
+    /** @type {any} */
     this.data = data
   }
 
+  /**
+   * Get all components by name.
+   *
+   * @param {string} name
+   * @returns {BaseComponent[]}
+   */
   getComponents(name) {
     return this.components.filter(c => c.name === name).map(c => c.component)
   }
 
+  /**
+   * Get a single component by name and index.
+   *
+   * @param {string} name
+   * @param {number} [index=0]
+   * @returns {BaseComponent|null}
+   */
   getComponent(name, index = 0) {
     return this.getComponents(name)[index] || null
   }
 
+  /**
+   * Add components based on definition.
+   *
+   * @param {ComponentDefinition} def
+   * @param {any} [renderer=null]
+   * @returns {void}
+   */
   addComponent(def, renderer = null) {
     if (!def || !def.instance || !def.name) return
 
     const { name, instance, data = null } = def
 
-    // resolve selector from name
+    /** @type {string} */
     let selector
     if (name.startsWith(".") || name.startsWith("[")) {
       selector = name
@@ -49,7 +86,14 @@ export default class Manager {
     })
   }
 
-  // INTERNAL CALLER
+  /**
+   * Call a method on all components.
+   *
+   * @param {keyof BaseComponent} method
+   * @param {...any} args
+   * @returns {void}
+   * @private
+   */
   _call(method, ...args) {
     this.components.forEach(entry => {
       const c = entry.component
@@ -70,6 +114,9 @@ export default class Manager {
     this._call("animateOut")
   }
 
+  /**
+   * @param {any} obj
+   */
   tick(obj) {
     this._call("tick", obj)
   }

package/core/Application.js

@@ -0,0 +1,299 @@
+// Application.js
+import { kitStore } from "../kitStore.js"
+
+// Events
+import { emitter, EVENTS, Scroll } from "../events/index.js"
+import Resize from "../events/Resize.js"
+import Mouse from "../events/Mouse.js"
+import Raf from "../events/Raf.js"
+
+// Libraries
+import { ScrollTrigger } from "../libraries/gsap/index.js"
+
+// Utils
+import { sniffer } from "../utils/sniffer.js"
+import { qs } from "../utils/selector.js"
+import { Debug } from "../utils/debug.js"
+
+/**
+ * Core lifecycle manager for all global systems:
+ * - Resize
+ * - Mouse
+ * - Scroll
+ * - Raf (ticker)
+ *
+ * Responsible for:
+ * - Store initialization
+ * - System initialization and activation
+ * - Router integration
+ * - View transitions
+ * - DOM readiness handling
+ */
+export class ApplicationManager {
+  constructor() {
+    /**
+     * Whether the application completed initialization.
+     * @type {boolean}
+     */
+    this.initialized = false
+
+    /**
+     * Debug mode state.
+     * @type {boolean}
+     */
+    this.isDebug = false
+
+    /**
+     * Global system instances (initialized in _initSystems).
+     * @type {{
+     *   resize: Resize|null,
+     *   mouse: Mouse|null,
+     *   scroll: Scroll|null,
+     *   raf: Raf|null
+     * }}
+     */
+    this.systems = {
+      resize: null,
+      mouse: null,
+      scroll: null,
+      raf: null,
+    }
+  }
+
+  /**
+   * Enable or disable debug logging.
+   * @param {boolean} [state=true]
+   * @returns {ApplicationManager}
+   */
+  debug(state = true) {
+    Debug[state ? "enable" : "disable"]()
+    return this
+  }
+
+  /**
+   * Initialize internal state store and environment flags.
+   * @param {{
+   *   url: URL|string,
+   *   page?: { element?: string, container?: string },
+   *   load?: string,
+   *   dim?: { d?: number, m?: number }
+   * }} config
+   * @private
+   */
+  _initStore({ url, page, load, dim }) {
+    const { element, container } = page || {}
+    const isHomePage = url.pathname === "/" || url === "/"
+
+    kitStore.pageContent = container ? qs(container) : null
+    kitStore.currentPage = element ? qs(element) : null
+
+    kitStore.load = load ? qs(load) : null
+    kitStore.currentURL = url ?? null
+    kitStore.flags.isHomePage = Boolean(isHomePage)
+
+    if (dim) {
+      kitStore.sizes.d = dim.d ?? kitStore.sizes.d
+      kitStore.sizes.m = dim.m ?? kitStore.sizes.m
+    }
+
+    this._setSizes(kitStore.sizes.d, kitStore.sizes.m)
+
+    kitStore.flags.isLocked = true
+
+    Debug.log("APP", "Store initialized", {
+      url: kitStore.currentURL,
+      pageContent: kitStore.pageContent,
+      currentPage: kitStore.currentPage,
+      sizes: kitStore.sizes,
+    })
+  }
+
+  /**
+   * Initialize and activate all global systems.
+   * @param {{ isSmooth: boolean }} options
+   * @private
+   */
+  _initSystems({ isSmooth }) {
+    const resize = new Resize()
+    const mouse = new Mouse()
+    const scroll = new Scroll({ isSmooth: isSmooth })
+    const raf = new Raf()
+
+    this.systems = { resize, mouse, scroll, raf }
+
+    kitStore.resize = resize
+    kitStore.mouse = mouse
+    kitStore.scroll = scroll
+    kitStore.raf = raf
+
+    kitStore.flags.isSmooth = isSmooth
+
+    // Phase 1: init
+    Object.values(this.systems).forEach(sys => {
+      if (sys && typeof sys.init === "function") sys.init()
+    })
+
+    // Phase 2: activate listeners/tickers
+    this.on()
+
+    Debug.log("APP", "Systems initialized", this.systems)
+  }
+
+  /**
+   * Activate all system listeners (Resize, Mouse, Scroll, Raf).
+   */
+  on() {
+    Object.values(this.systems).forEach(sys => {
+      if (sys && typeof sys.on === "function") sys.on()
+    })
+  }
+
+  /**
+   * Deactivate all system listeners.
+   */
+  stop() {
+    Object.values(this.systems).forEach(sys => {
+      if (sys && typeof sys.off === "function") sys.off()
+    })
+  }
+
+  /**
+   * Fully destroy all systems and reset the application state.
+   */
+  destroy() {
+    this.stop()
+    Object.values(this.systems).forEach(sys => {
+      if (sys && typeof sys.destroy === "function") sys.destroy()
+    })
+    this.initialized = false
+  }
+
+  /**
+   * Initialize the full application lifecycle.
+   * Ensures DOMReady + store + systems + flags.
+   *
+   * @param {{
+   *   url: URL|string,
+   *   page: { element?: string, container?: string },
+   *   load?: string,
+   *   isSmooth?: boolean,
+   *   dim?: { d?: number, m?: number }
+   * }} config
+   * @returns {Promise<typeof kitStore>}
+   */
+  async initialize(config) {
+    if (this.initialized) return kitStore
+    if (!sniffer.isDesktop) {
+      config.isSmooth = false
+    } else if (!config.isSmooth && sniffer.isDesktop) {
+      config.isSmooth = true
+    }
+
+    await this._waitDOM()
+    Debug.log("APP", "DOM ready with", config.isSmooth ? "smooth " : "native " + "scroll.")
+
+    this._initStore(config)
+    this._initSystems({ isSmooth: config.isSmooth })
+
+    this.initialized = true
+    Debug.log("APP", "Application ready.", kitStore)
+
+    return kitStore
+  }
+
+  /**
+   * Attach Taxi router events into the global lifecycle.
+   * @param {import("@unseenco/taxi").Core|null} router
+   */
+  attachTaxi(router) {
+    if (!router) return
+    kitStore.taxi = router
+
+    router.on("NAVIGATE_IN", () => {
+      const { currentLocation } = router
+      kitStore.currentURL = currentLocation
+
+      if (kitStore.raf?.setScroll) kitStore.raf.setScroll(0)
+
+      Debug.log("ROUTE", "NAVIGATE_IN")
+      emitter.emit(EVENTS.APP_ROUTE_IN, { url: currentLocation })
+    })
+
+    router.on("NAVIGATE_END", () => {
+      this._updatePageRefs()
+      this._afterViewChange()
+
+      Debug.log("ROUTE", "NAVIGATE_END")
+      emitter.emit(EVENTS.APP_ROUTE_END, { url: kitStore.currentURL })
+    })
+
+    router.on("NAVIGATE_OUT", () => {
+      Debug.log("ROUTE", "NAVIGATE_OUT")
+      emitter.emit(EVENTS.APP_ROUTE_OUT, { url: kitStore.currentURL })
+    })
+  }
+
+  /**
+   * Update references to current page and container after a Taxi view swap.
+   * @private
+   */
+  _updatePageRefs() {
+    const currentPage = qs("[data-taxi-view]")
+    const pageContent = kitStore.pageContent ? kitStore.pageContent : qs("#app")
+
+    kitStore.currentPage = currentPage || null
+    kitStore.pageContent = pageContent || null
+  }
+
+  /**
+   * Run post-navigation updates:
+   * - Reset Scroll bounds
+   * - Reset GSAP scroll proxy
+   * - Soft resize
+   * @private
+   */
+  _afterViewChange() {
+    if (this.systems.scroll?.setScrollBounds) {
+      this.systems.scroll.setScrollBounds()
+    }
+
+    if (this.systems.raf?.setScrollTrigger) {
+      this.systems.raf.setScrollTrigger()
+    }
+
+    this._softResize()
+  }
+
+  /**
+   * Set CSS variables for responsive layout.
+   * @param {number} d
+   * @param {number} m
+   * @private
+   */
+  _setSizes(d, m) {
+    document.documentElement.style.setProperty("--desktop", d)
+    document.documentElement.style.setProperty("--mobile", m)
+  }
+
+  /**
+   * Trigger a "soft resize":
+   * - Emit resize event
+   * - Refresh ScrollTrigger
+   * @private
+   */
+  _softResize() {
+    Debug.log("APP", "Soft resize triggered.")
+    emitter.emit(EVENTS.APP_SMOOTH_RESIZE)
+    ScrollTrigger.refresh()
+  }
+
+  /**
+   * Wait for DOM ready before execution.
+   * @returns {Promise<void>}
+   * @private
+   */
+  _waitDOM() {
+    if (document.readyState !== "loading") return Promise.resolve()
+    return new Promise(res => document.addEventListener("DOMContentLoaded", res, { once: true }))
+  }
+}

package/core/PageEngine.js

@@ -0,0 +1,221 @@
+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"
+
+/**
+ * @typedef {Object} EngineOwner
+ * The page instance passed from project-level Page (extends Renderer).
+ */
+
+/**
+ * @typedef {Object} EngineScrollState
+ * @property {number} current - Current scroll value coming from Raf.
+ * @property {"up"|"down"} direction - Derived scroll direction.
+ */
+
+/**
+ * @typedef {Object} EngineMouseState
+ * @property {number} x - Current mouse X.
+ * @property {number} y - Current mouse Y.
+ */
+
+/**
+ * @typedef {Object} EngineSetupConfig
+ * @property {Array<any>} components - Array of component constructors/definitions.
+ * @property {any} smooth - Smooth instance for scroll control.
+ */
+
+export default class PageEngine {
+  /**
+   * @param {{ owner: EngineOwner }} param0
+   */
+  constructor({ owner }) {
+    /**
+     * @type {EngineOwner}
+     */
+    this.owner = owner
+
+    /**
+     * @type {Array<any>}
+     */
+    this.components = []
+
+    /**
+     * @type {number}
+     */
+    this.componentsLength = 0
+
+    /**
+     * @type {Manager | null}
+     */
+    this.manager = null
+
+    /**
+     * Smooth instance passed in by project Page
+     * @type {any | null}
+     */
+    this.smooth = null
+
+    /**
+     * @type {EngineScrollState}
+     */
+    this.scroll = { current: 0, direction: "down" }
+
+    /**
+     * @type {EngineMouseState}
+     */
+    this.mouse = { x: 0, y: 0 }
+  }
+
+  /**
+   * Store component definitions.
+   * Page calls this during setComponents().
+   *
+   * @param {Array<any>} components
+   */
+  setComponents(components) {
+    Debug.log("ENGINE", "Set Components", { components })
+
+    this.components = components || []
+  }
+
+  /**
+   * Called by Page.initCore().
+   * Recreates Manager and binds a new Smooth instance.
+   *
+   * @param {EngineSetupConfig} param0
+   */
+  setup({ components, smooth }) {
+    Debug.log("ENGINE", "Setup", { components, smooth })
+
+    this.components = components || []
+    this.smooth = smooth || null
+
+    this.manager = new Manager()
+
+    if (this.manager && this.components.length) {
+      this.components.forEach(obj => {
+        this.manager.addComponent(obj, this.owner)
+      })
+    }
+
+    this.manager.initialize()
+    this.manager.animateIn?.()
+
+    this.on()
+    this.trackImages()
+    this.resize()
+  }
+
+  /**
+   * Adds `.loaded` class to images when loaded.
+   * Looks for `.lazy` images.
+   */
+  trackImages() {
+    const imgs = qsa(".lazy")
+    if (!imgs || !imgs.length) return
+
+    imgs.forEach(img => {
+      if (img.complete) {
+        img.classList.add("loaded")
+        return
+      }
+
+      img.addEventListener(
+        "load",
+        () => {
+          img.classList.add("loaded")
+        },
+        { once: true }
+      )
+    })
+  }
+
+  /**
+   * Receives scroll and mouse data from Raf (APP_TICK).
+   * Packages them and forwards to Manager.tick().
+   *
+   * @param {{ current: number, diff: number, mouse: EngineMouseState }} param0
+   */
+  tick = ({ current, diff, mouse }) => {
+    const { isResizing, isLocked } = kitStore.flags
+
+    if (isResizing || isLocked) return
+    if (!this.manager) return
+
+    this.scroll.current = current
+    this.scroll.direction = diff > 0 ? "down" : "up"
+
+    this.mouse.x = mouse.x
+    this.mouse.y = mouse.y
+
+    this.manager.tick?.({
+      mouse: this.mouse,
+      scroll: this.scroll,
+    })
+  }
+
+  /**
+   * Called during APP_RESIZE.
+   * Updates Smooth then calls Manager.resize().
+   */
+  resize = () => {
+    Debug.log("ENGINE", "Resize")
+
+    this.smooth?.update?.()
+    this.manager?.resize?.()
+  }
+
+  /**
+   * Called during APP_SMOOTH_RESIZE.
+   * Delegates to Manager.smoothResize().
+   */
+  smoothResize = () => {
+    Debug.log("ENGINE", "Smooth Resize")
+
+    this.manager?.smoothResize?.()
+  }
+
+  /**
+   * Internal listener binder/unbinder.
+   *
+   * @param {"on" | "off"} action
+   */
+  listeners(action) {
+    Debug.log("ENGINE", `Listeners`, action.toUpperCase())
+
+    emitter[action](EVENTS.APP_TICK, this.tick)
+    emitter[action](EVENTS.APP_RESIZE, this.resize)
+    emitter[action](EVENTS.APP_SMOOTH_RESIZE, this.smoothResize)
+  }
+
+  /**
+   * Register RAF listeners.
+   */
+  on() {
+    this.listeners("on")
+  }
+
+  /**
+   * Unregister RAF listeners.
+   */
+  off() {
+    this.listeners("off")
+    this.destroy()
+  }
+
+  /**
+   * Cleanup Smooth + Manager.
+   * Called by Page.onLeaveCompleted().
+   */
+  destroy() {
+    this.manager?.destroy?.()
+    this.manager = null
+
+    if (this.smooth) {
+      this.smooth.destroy?.()
+      this.smooth = null
+    }
+  }
+}

package/core/index.js

@@ -0,0 +1,8 @@
+import { ApplicationManager } from "./Application"
+import PageEngine from "./PageEngine"
+
+/**
+ * @type {ApplicationManager}
+ */
+export const Application = new ApplicationManager()
+export { PageEngine }

package/events/Emitter.js

@@ -6,6 +6,7 @@ class Emitter {
 
   emit(event, ...args) {
     const callbacks = this.events[event] || []
+
     for (let i = 0, { length } = callbacks; i < length; i++) {
       callbacks[i].cb(...args)
     }
@@ -15,6 +16,7 @@ class Emitter {
     const data = { cb, priority }
     this.events[event]?.push(data) || (this.events[event] = [data])
     this.events[event].sort((a, b) => a.priority - b.priority)
+
     return () => {
       this.events[event] = this.events[event]?.filter(v => cb !== v.cb)
     }
@@ -29,9 +31,7 @@ class Emitter {
       cb(...args)
       this.off(event, onceCallback)
     }
-
     this.on(event, onceCallback, priority)
-
     return () => {
       this.off(event, cb)
     }
@@ -45,6 +45,7 @@ class Emitter {
 const emitter = new Emitter()
 
 const EVENTS = {
+  APP_UNLOCKED: "app:unlocked",
   APP_TICK: "tick",
   APP_RESIZE: "resize",
   APP_SMOOTH_RESIZE: "smooth:resize",

package/events/Raf.js

@@ -1,5 +1,4 @@
-// Raf.js
-import kitStore from "../kitStore"
+import { kitStore } from "../kitStore"
 import emitter, { EVENTS } from "./Emitter"
 import { lerp } from "../utils"
 import { gsap, ScrollTrigger } from "../libraries/gsap"
@@ -19,14 +18,50 @@ export default class Raf {
       target: null,
     }
 
+    this.diff = 0
+
+    this.tick = this.tick.bind(this)
+    this.onScroll = this.onScroll.bind(this)
+    this.onMouseMove = this.onMouseMove.bind(this)
+    this.onAppResize = this.onAppResize.bind(this)
+
+    this.onPageHide = this.stop.bind(this)
+    this.onPageShow = this.resume.bind(this)
+  }
+
+  init() {
     this.setScrollTrigger()
-    this.on()
   }
 
-  onAppResize = () => {
+  on() {
+    gsap.ticker.add(this.tick)
+
+    emitter.on(EVENTS.APP_SCROLL, this.onScroll)
+    emitter.on(EVENTS.APP_MOUSEMOVE, this.onMouseMove)
+    emitter.on(EVENTS.APP_SMOOTH_RESIZE, this.onAppResize)
+
+    window.addEventListener("pagehide", this.onPageHide)
+    window.addEventListener("pageshow", this.onPageShow)
+  }
+
+  off() {
+    gsap.ticker.remove(this.tick)
+
+    emitter.off(EVENTS.APP_SCROLL, this.onScroll)
+    emitter.off(EVENTS.APP_MOUSEMOVE, this.onMouseMove)
+    emitter.off(EVENTS.APP_SMOOTH_RESIZE, this.onAppResize)
+
+    window.removeEventListener("pagehide", this.onPageHide)
+    window.removeEventListener("pageshow", this.onPageShow)
+  }
+
+  destroy() {
+    this.off()
+  }
+
+  onAppResize() {
     const { fh } = kitStore.sizes
 
-    // clamp our smooth state
     this.scroll.target = Math.min(Math.max(this.scroll.target, 0), fh)
     this.scroll.current = Math.min(Math.max(this.scroll.current, 0), fh)
     this.scroll.rounded = Math.min(Math.max(this.scroll.rounded, 0), fh)
@@ -34,8 +69,9 @@ export default class Raf {
     ScrollTrigger.update()
   }
 
-  tick = () => {
+  tick() {
     if (kitStore.flags.isResizing) return
+
     const { target, current, ease } = this.scroll
 
     this.scroll.current = lerp(current, target, ease)
@@ -55,7 +91,6 @@ export default class Raf {
   getScroll() {
     const { pageContent, flags } = kitStore
     const container = pageContent ? pageContent.parentNode : document.body
-
     return flags.isSmooth ? this.scroll.rounded : container.scrollTop
   }
 
@@ -64,13 +99,13 @@ export default class Raf {
     this.scroll.target = Math.min(Math.max(this.scroll.target, 0), fh)
   }
 
-  onScroll = ({ y }) => {
+  onScroll({ y }) {
     if (kitStore.flags.isLocked) return
     this.scroll.target += y
     this.clamp()
   }
 
-  onMouseMove = ({ x, y, target }) => {
+  onMouseMove({ x, y, target }) {
     this.mouse.x = x
     this.mouse.y = y
     this.mouse.target = target
@@ -102,52 +137,30 @@ export default class Raf {
 
   setScrollTrigger() {
     const { pageContent } = kitStore
+    const scroller = pageContent || document.body
 
     ScrollTrigger.defaults({
-      scroller: pageContent,
+      scroller,
     })
 
-    ScrollTrigger.scrollerProxy(pageContent, {
+    ScrollTrigger.scrollerProxy(scroller, {
       scrollTop: () => {
         return this.getScroll()
       },
       getBoundingClientRect() {
-        // Important that width and height are dynamic
         return { top: 0, left: 0, width: window.innerWidth, height: window.innerHeight }
       },
     })
   }
 
-  stop = () => {
+  stop() {
     gsap.ticker.remove(this.tick)
   }
 
-  resume = () => {
+  resume() {
     this.scroll.current = this.scroll.target
     this.scroll.rounded = this.scroll.target
     gsap.ticker.add(this.tick)
     ScrollTrigger.update()
   }
-
-  on() {
-    gsap.ticker.add(this.tick)
-    emitter.on(EVENTS.APP_SCROLL, this.onScroll)
-    emitter.on(EVENTS.APP_MOUSEMOVE, this.onMouseMove)
-    emitter.on(EVENTS.APP_SMOOTH_RESIZE, this.onAppResize)
-    window.addEventListener("pagehide", () => this.stop)
-    window.addEventListener("pageshow", () => this.resume)
-  }
-
-  off() {
-    gsap.ticker.remove(this.tick)
-    emitter.off(EVENTS.APP_SCROLL, this.onScroll)
-    emitter.off(EVENTS.APP_MOUSEMOVE, this.onMouseMove)
-    emitter.off(EVENTS.APP_SMOOTH_RESIZE, this.onAppResize)
-    window.removeEventListener("pagehide", () => this.stop)
-    window.removeEventListener("pageshow", () => this.resume)
-  }
-
-  destroy() {
-    this.off()
-  }
 }

package/events/Resize.js

@@ -1,4 +1,3 @@
-// Resize.js
 import { sizes, flags, breakpoints } from "../kitStore"
 import emitter, { EVENTS } from "./Emitter"
 import debounce from "lodash.debounce"
@@ -8,7 +7,27 @@ import { ScrollTrigger } from "../libraries/gsap"
 export default class Resize {
   constructor() {
     this.wasDesktop = sniffer.isDesktop
-    this.init()
+
+    this.handleResize = debounce(this.onResize.bind(this), 200)
+    this.handleLoadOnce = this.onLoadOnce.bind(this)
+  }
+
+  init() {
+    this.onResize()
+  }
+
+  on() {
+    window.addEventListener("resize", this.handleResize, { passive: true })
+    window.addEventListener("load", this.handleLoadOnce, { once: true })
+  }
+
+  off() {
+    window.removeEventListener("resize", this.handleResize)
+    window.removeEventListener("load", this.handleLoadOnce)
+  }
+
+  destroy() {
+    this.off()
   }
 
   onResize = () => {
@@ -16,7 +35,7 @@ export default class Resize {
 
     const { width, height } = getViewport()
     const bp = getWindowSizes()
-    sniffer.update() // Update sniffer after viewport read
+    sniffer.update()
 
     Object.assign(sizes, {
       vw: width,
@@ -69,14 +88,4 @@ export default class Resize {
     document.body.classList.toggle("is-desktop", isDesktop)
     document.body.classList.toggle("is-device", !isDesktop)
   }
-
-  on() {
-    window.addEventListener("resize", debounce(this.onResize, 200), { passive: true })
-    window.addEventListener("load", this.onLoadOnce, { once: true })
-  }
-
-  init() {
-    this.on()
-    this.onResize() // Run once on init
-  }
 }

package/events/Scroll.js

@@ -1,4 +1,3 @@
-// Scroll.js
 import { sizes } from "../kitStore"
 import emitter, { EVENTS } from "./Emitter"
 import VirtualScroll from "./VirtualScroll"
@@ -7,24 +6,52 @@ import { bounds, sniffer } from "../utils"
 export default class Scroll {
   constructor({ isSmooth = false } = {}) {
     this.isSmooth = isSmooth
+    this.virtualScroll = null
 
+    this.onVirtualScroll = this.onVirtualScroll.bind(this)
+    this.onScroll = this.onScroll.bind(this)
+  }
+
+  init() {
+    this.setScrollBounds()
+  }
+
+  on() {
     if (this.isSmooth) {
       document.body.classList.add("is-smooth")
 
-      this.virtualScroll = new VirtualScroll({
-        mouseMultiplier: sniffer.isWindows ? 1.1 : 0.45,
-        touchMultiplier: 3.5,
-        firefoxMultiplier: sniffer.isWindows ? 40 : 90,
+      if (!this.virtualScroll) {
+        this.virtualScroll = new VirtualScroll({
+          mouseMultiplier: sniffer.isWindows ? 1.1 : 0.45,
+          touchMultiplier: 3.5,
+          firefoxMultiplier: sniffer.isWindows ? 40 : 90,
+          passive: true,
+        })
+      }
+
+      this.virtualScroll.on(this.onVirtualScroll)
+    } else {
+      document.addEventListener("scroll", this.onScroll, {
         passive: true,
+        capture: true,
       })
+    }
+  }
 
-      this.virtualScroll.on(this.onVirtualScroll)
+  off() {
+    if (this.virtualScroll) {
+      this.virtualScroll.off(this.onVirtualScroll)
     } else {
-      this.onScroll = this.onScroll.bind(this)
-      document.addEventListener("scroll", this.onScroll, true)
+      document.removeEventListener("scroll", this.onScroll, true)
     }
+  }
 
-    this.setScrollBounds()
+  destroy() {
+    this.off()
+    if (this.virtualScroll) {
+      this.virtualScroll.destroy()
+      this.virtualScroll = null
+    }
   }
 
   setScrollBounds() {
@@ -33,19 +60,11 @@ export default class Scroll {
     sizes.fh = height > sizes.vh ? height - sizes.vh : 0
   }
 
-  onVirtualScroll = e => {
+  onVirtualScroll(e) {
     emitter.emit(EVENTS.APP_SCROLL, { y: e.deltaY * -1 })
   }
 
-  onScroll(e) {
+  onScroll() {
     emitter.emit(EVENTS.APP_SCROLL, { y: window.scrollY })
   }
-
-  destroy() {
-    if (this.virtualScroll) {
-      this.virtualScroll.destroy()
-    } else {
-      document.removeEventListener("scroll", this.onScroll, true)
-    }
-  }
 }

package/events/VirtualScroll.js

@@ -1,5 +1,5 @@
 // VirtualScroll.js
-import kitStore from "../kitStore"
+import { kitStore } from "../kitStore"
 import emitter from "./Emitter"
 import { supportMouseTouch } from "../utils"
 import Lethargy from "lethargy"

package/index.js

@@ -1,4 +1,8 @@
-// stellar-kit/index.js
+/**
+ * Legacy setup functions for Stellar Kit.
+ * These were previously part of Application.js but have been moved out
+ */
+
 import { Mouse, Resize, Raf, Scroll } from "./events"
 import kitStore from "./kitStore"
 import { sniffer } from "./utils"

package/kitStore.js

@@ -1,13 +1,13 @@
-//kitStore.js
+// kitStore.js
+
 export const sizes = {
   vw: 0,
   vh: 0,
   fh: 0,
-  d: 1440, // design width
-  m: 390, // mobile width
+  d: 1440,
+  m: 390,
 }
 
-// in case you want to "cache" your assets
 export const assets = {}
 
 export const flags = {
@@ -32,11 +32,14 @@ export const mouse = {
   y: 0,
 }
 
-export default {
+/**
+ * Single canonical store object.
+ */
+export const kitStore = {
   sizes,
   breakpoints,
   mouse,
   flags,
-  pageContent: null, // This should be set to the main content element
+  pageContent: null,
   assets,
 }

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@linear_non/stellar-kit",
-  "version": "2.1.21",
+  "version": "3.0.1",
   "description": "Stellar frontend core for Non-Linear Studio projects.",
-  "main": "index.js",
+  "main": "/core/index.js",
   "exports": {
-    ".": "./index.js",
+    ".": "./kitStore.js",
     "./utils": "./utils/index.js",
+    "./core": "./core/index.js",
     "./classes": "./classes/index.js",
     "./events": "./events/index.js",
     "./plugins": "./plugins/index.js",
@@ -14,10 +15,12 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
+    "build": "vite build",
     "format": "prettier --write .",
     "check": "vite build --emptyOutDir --watch"
   },
   "files": [
+    "core/",
     "classes/",
     "events/",
     "plugins/",

package/plugins/Grid.js

@@ -1,4 +1,4 @@
-import kitStore from "../kitStore"
+import { kitStore } from "../kitStore"
 import { getWindowSizes } from "../utils/window"
 import { emitter, EVENTS } from "../events"
 import { gsap } from "../libraries/gsap"

package/utils/debug.js

@@ -0,0 +1,64 @@
+import { kitStore } from "../kitStore.js"
+
+const COLORS = {
+  APP: "#03A9F4",
+  ENGINE: "#4CAF50",
+  PAGE: "#FF9800",
+  MANAGER: "#E91E63",
+  ROUTE: "#9C27B0",
+}
+
+function fmt(scope) {
+  const color = COLORS[scope] || "#999"
+  return [`%c[${scope}]`, `color:${color};font-weight:bold`]
+}
+
+/**
+ * Lightweight global debug helper.
+ *
+ * - Controlled via kitStore.flags.isDebug
+ * - No-op when debug is off
+ */
+
+export const Debug = {
+  enable() {
+    kitStore.flags.isDebug = true
+  },
+
+  disable() {
+    kitStore.flags.isDebug = false
+  },
+
+  isEnabled() {
+    return Boolean(kitStore.flags.isDebug)
+  },
+
+  log(scope, ...args) {
+    if (!kitStore.flags.isDebug) return
+    const [tag, style] = fmt(scope)
+    console.log(tag, style, ...args)
+  },
+
+  warn(scope, ...args) {
+    if (!kitStore.flags.isDebug) return
+    const [tag, style] = fmt(scope)
+    console.warn(tag, style, ...args)
+  },
+
+  error(scope, ...args) {
+    if (!kitStore.flags.isDebug) return
+    const [tag, style] = fmt(scope)
+    console.error(tag, style, ...args)
+  },
+
+  group(scope, fn) {
+    if (!kitStore.flags.isDebug) return
+    const [tag, style] = fmt(scope)
+    console.group(tag, style)
+    try {
+      fn()
+    } finally {
+      console.groupEnd()
+    }
+  },
+}

package/utils/index.js

@@ -1,3 +1,4 @@
+export { Debug } from "./debug"
 export { qs, qsa, getid, gettag } from "./selector"
 export { bounds } from "./bounds"
 export { offset } from "./offset"

package/utils/listener.js

@@ -1,12 +1,28 @@
-// listener.js
+/**
+ * @typedef {EventTarget | EventTarget[] | NodeListOf<EventTarget> | HTMLCollectionOf<EventTarget>} ListenerTarget
+ */
+/**
+ * @typedef {"add" | "remove"} ListenerAction
+ */
+
+/**
+ * Cross-browser helper to add/remove event listeners on a single element or a collection.
+ *
+ * @param {ListenerTarget} el - Element or collection of elements.
+ * @param {ListenerAction} action - `"add"` to add, `"remove"` to remove.
+ * @param {string} type - Event type, e.g. `"click"`, `"scroll"`.
+ * @param {(event: Event) => void} cb - Event handler callback.
+ * @param {boolean} [p] - If `true`, listener is registered as passive.
+ * @returns {void}
+ */
 export const listener = (el, action, type, cb, p) => {
   const passive = p === true ? { passive: true } : false
 
-  if (el.length) {
+  if (el && "length" in el && typeof el !== "string") {
     for (let i = 0; i < el.length; i++) {
       el[i][action + "EventListener"](type, cb, passive)
     }
-  } else {
+  } else if (el) {
     el[action + "EventListener"](type, cb, passive)
   }
 }

package/utils/math.js

@@ -1,16 +1,36 @@
-// math.js
-export const lerp = (a, b, n) => {
-  return a * (1 - n) + b * n
-}
+/**
+ * Linearly interpolates between two numbers.
+ * @param {number} a
+ * @param {number} b
+ * @param {number} n - Normalized factor [0–1]
+ * @returns {number}
+ */
+export const lerp = (a, b, n) => a * (1 - n) + b * n
 
-export const norm = (val, min, max) => {
-  return (val - min) / (max - min)
-}
+/**
+ * Normalizes a value into a 0–1 range.
+ * @param {number} val
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+export const norm = (val, min, max) => (val - min) / (max - min)
 
-export const clamp = (val, min, max) => {
-  return Math.min(Math.max(val, min), max)
-}
+/**
+ * Clamps a number between a minimum and maximum.
+ * @param {number} val
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+export const clamp = (val, min, max) => Math.min(Math.max(val, min), max)
 
+/**
+ * Rounds a number to a given precision.
+ * @param {number} n
+ * @param {number} [p=3] - Decimal precision
+ * @returns {number}
+ */
 export const round = (n, p) => {
   const precision = p !== undefined ? Math.pow(10, p) : 1000
   return Math.round(n * precision) / precision

package/utils/offset.js

@@ -1,14 +1,27 @@
-// offset.js
-// Helpfull to use instead of
-// bounds when using smooth scroll
+/**
+ * Computes the cumulative offset of an element relative to the document.
+ * Use this instead of `bounds()` when smooth-scroll systems shift the viewport.
+ *
+ * @param {HTMLElement} el
+ * @returns {{left: number, top: number, bottom: number}}
+ */
 export const offset = el => {
-  let left = 0,
-    top = 0
-  const node = el
+  if (!el) return { left: 0, top: 0, bottom: 0 }
+
+  let left = 0
+  let top = 0
+  const base = el
+
+  /** Walk up the offset parent chain */
   while (el) {
-    left += el.offsetLeft
-    top += el.offsetTop
+    left += el.offsetLeft || 0
+    top += el.offsetTop || 0
     el = el.offsetParent
   }
-  return { left, top, bottom: top + node.offsetHeight }
+
+  return {
+    left,
+    top,
+    bottom: top + base.offsetHeight,
+  }
 }

package/utils/selector.js

@@ -1,5 +1,35 @@
-// selector.js
-export const qs = (s, o = document) => o.querySelector(s)
-export const qsa = (s, o = document) => Array.from(o.querySelectorAll(s))
-export const getid = (s, o = document) => o.getElementById(s)
-export const gettag = (s, o = document) => o.getElementsByTagName(s)
+/**
+ * Query a single DOM element.
+ *
+ * @param {string} selector - CSS selector
+ * @param {ParentNode} [scope=document] - Scope to search within
+ * @returns {Element|null}
+ */
+export const qs = (selector, scope = document) => scope.querySelector(selector)
+
+/**
+ * Query multiple DOM elements.
+ *
+ * @param {string} selector - CSS selector
+ * @param {ParentNode} [scope=document] - Scope to search within
+ * @returns {Element[]} - Array of matched elements
+ */
+export const qsa = (selector, scope = document) => Array.from(scope.querySelectorAll(selector))
+
+/**
+ * Get an element by ID.
+ *
+ * @param {string} id - Element ID
+ * @param {Document|HTMLElement} [scope=document] - Scope to search within
+ * @returns {HTMLElement|null}
+ */
+export const getid = (id, scope = document) => scope.getElementById(id)
+
+/**
+ * Get elements by tag name.
+ *
+ * @param {string} tag - Tag name
+ * @param {Document|HTMLElement} [scope=document] - Scope to search within
+ * @returns {HTMLCollectionOf<Element>}
+ */
+export const gettag = (tag, scope = document) => scope.getElementsByTagName(tag)