@linear_non/stellar-kit 3.0.9 → 3.0.12

package/README.md

@@ -1,67 +1,75 @@
 # stellar-kit
 
-A modular frontend utility kit for custom websites. Built for performance, extensibility, and clean developer ergonomics — with support for smooth scrolling, events, tick updates, mouse tracking, and layout helpers.
+> `@linear_non/stellar-kit` — Front-end core framework for Non-Linear Studio projects.
 
-## ✨ Features
+A modular frontend toolkit that handles the application lifecycle, scroll management (internal smooth scroll via VirtualScroll or external via Lenis), per-frame animation ticking, component orchestration, asset loading, and responsive layout utilities.
 
-- RAF-based update loop (`Raf`)
-- Virtual scroll support (`Scroll`)
-- Viewport-based resize tracking (`Resize`)
-- Centralized event system (`Emitter`)
-- Mouse tracking (`Mouse`)
-- Utility helpers (DOM selection, bounds, clamping, etc.)
-- Designed for use with Astro, GSAP, Three.js, and modular frontend setups
-
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @linear_non/stellar-kit
-
 ```
 
-## 🧱 Folder Structure
+## Quick Start
 
-```
-stellar-kit/
-├── classes/      # Core logic: Manager, Component.
-├── events/       # Emitter system: Raf, Resize, Scroll, Mouse, etc.
-├── utils/        # Utilities: bounds, clamp, selectors, sniffer, etc.
-├── plugins/      # Helpers Grid, Observer, SplitText, etc.
-├── kitStore.js   # Central store shared across all modules
-└── index.js      # Entry point for setupKit and kitStore access
+```js
+import { Application } from "@linear_non/stellar-kit/core"
+
+await Application.initialize({
+  url: window.location,
+  page: { element: "[data-taxi-view]", container: "#app" },
+  isSmooth: true,
+  useExternalScroll: false,
+  dim: { d: 1440, m: 390 },
+})
 ```
 
-## 🧪 Local Development
+## Imports
 
-```bash
-npm install
-npm run dev
+```js
+import { kitStore } from "@linear_non/stellar-kit"
+import { Application, PageEngine } from "@linear_non/stellar-kit/core"
+import { Component, Manager, MasterLoader, ImageLoader, FontLoader } from "@linear_non/stellar-kit/classes"
+import { emitter, EVENTS, PRIORITY } from "@linear_non/stellar-kit/events"
+import { Grid, Observer, splitText, reverseSplit } from "@linear_non/stellar-kit/plugins"
+import { qs, qsa, bounds, lerp, clamp, sniffer, listener } from "@linear_non/stellar-kit/utils"
+import { gsap, ScrollTrigger, SplitText } from "@linear_non/stellar-kit/gsap"
 ```
 
-> The `dev/` folder provides a Vite playground to test modules like Smooth, Scrollbar, and events. You can import any part of the kit and prototype in isolation.
+## Architecture
 
-## 🛠️ Usage Example
+| Module    | Purpose                                                       |
+| --------- | ------------------------------------------------------------- |
+| `core`    | `Application` singleton + `PageEngine` per-page lifecycle     |
+| `classes` | `Component` base class, `Manager`, asset loaders              |
+| `events`  | `Emitter` pub/sub, `Raf`, `Resize`, `Scroll`, `Mouse`         |
+| `plugins` | `Grid` overlay, `Observer` (ScrollTrigger), `splitText`       |
+| `utils`   | DOM helpers, math, sniffer, viewport, debug                   |
+| `gsap`    | Pre-configured GSAP with ScrollTrigger, SplitText, CustomEase |
 
-```js
-// main.js or index.js of your project
-import { kitStore, setupKit } from "stellar-kit"
+## Scroll Modes
 
-setupKit() // Initializes Resize, Raf, Scroll, Mouse, etc.
+**Internal** — VirtualScroll + lerp interpolation in Raf:
 
-// Access anywhere
-kitStore.scroll
-kitStore.raf
-kitStore.mouse
+```js
+engine.setup({ components, smooth })
 ```
 
-You can also import from specific paths:
+**External (Lenis)** — Lenis manages scroll, PageEngine sets up ScrollTrigger proxy:
 
 ```js
-import { bounds, clamp, qs } from "stellar-kit/utils"
-import { Manager } from "stellar-kit/classes"
-import { Raf } from "stellar-kit/events"
+engine.setup({ components, lenis, wrapper })
+```
+
+## Local Development
+
+```bash
+npm install
+npm run dev
 ```
 
----
+The `dev/` folder provides a Vite playground for testing.
+
+## License
 
-Made with ❤️ by [Non-Linear Studio](https://non-linear.studio)
+MIT — [Non-Linear Studio](https://non-linear.studio)

package/classes/Component.js

@@ -31,8 +31,6 @@ export default class Component {
     this.off()
   }
 
-  setWebgl() {}
-
   render() {
     this.setup()
     this.on()

package/core/Application.js

@@ -213,6 +213,10 @@ export class ApplicationManager {
     }
 
     await this._waitDOM()
+
+    // Auto-enable debug mode from ?debug URL param
+    Debug.init()
+
     Debug.log(
       "APP",
       "DOM ready with",
@@ -310,4 +314,4 @@ export class ApplicationManager {
     if (document.readyState !== "loading") return Promise.resolve()
     return new Promise(res => document.addEventListener("DOMContentLoaded", res, { once: true }))
   }
-}
+}

package/core/PageEngine.js

@@ -148,6 +148,15 @@ export default class PageEngine {
     this.manager?.animateIn?.()
   }
 
+  /**
+   * Trigger exit animations on all components.
+   * Call this from the page/renderer before leaving
+   * (e.g. during onLeave or transition out).
+   */
+  animateOut() {
+    this.manager?.animateOut?.()
+  }
+
   /**
    * Setup Lenis: register with global Raf and configure ScrollTrigger.
    * Raf.js handles the lenis.raf() call on each tick.
@@ -294,7 +303,6 @@ export default class PageEngine {
    */
   off() {
     this.listeners("off")
-    this.destroy()
   }
 
   /**
@@ -317,10 +325,12 @@ export default class PageEngine {
   }
 
   /**
-   * Cleanup Smooth + Manager.
+   * Cleanup listeners, Smooth + Manager.
    * Called by Page.onLeaveCompleted().
    */
   destroy() {
+    this.off()
+
     this.manager?.destroy?.()
     this.manager = null
 

package/events/Raf.js

@@ -313,12 +313,18 @@ export default class Raf {
     })
 
     ScrollTrigger.scrollerProxy(scroller, {
-      scrollTop: () => {
+      scrollTop: value => {
+        if (value !== undefined) {
+          this.scroll.target = value
+          this.scroll.current = value
+          this.scroll.rounded = value
+        }
         return this.getScroll()
       },
       getBoundingClientRect() {
         return { top: 0, left: 0, width: window.innerWidth, height: window.innerHeight }
       },
+      pinType: "transform",
     })
   }
 

package/events/VirtualScroll.js

@@ -1,7 +1,7 @@
 // VirtualScroll.js
 import { kitStore } from "../kitStore"
 import emitter from "./Emitter"
-import { supportMouseTouch } from "../utils"
+import { sniffer } from "../utils"
 import Lethargy from "lethargy"
 
 const EVT_ID = "virtualscroll"
@@ -25,7 +25,6 @@ export default class VirtualScroll {
     this.event = { x: 0, y: 0, deltaX: 0, deltaY: 0 }
     this.touchStartX = null
     this.touchStartY = null
-    this.bodyTouchAction = null
     this.focusingInput = false
 
     if (this.options.limitInertia) this.lethargy = new Lethargy()
@@ -34,8 +33,11 @@ export default class VirtualScroll {
       this.listenerOptions = { passive: this.options.passive }
     }
 
-    document.addEventListener("focusin", () => (this.focusingInput = true))
-    document.addEventListener("focusout", () => (this.focusingInput = false))
+    this._onFocusIn = () => (this.focusingInput = true)
+    this._onFocusOut = () => (this.focusingInput = false)
+
+    document.addEventListener("focusin", this._onFocusIn)
+    document.addEventListener("focusout", this._onFocusOut)
   }
 
   notify(e) {
@@ -56,10 +58,10 @@ export default class VirtualScroll {
     if (this.lethargy && !this.lethargy.check(e)) return
 
     const evt = this.event
-    evt.deltaX = e.wheelDeltaX || e.deltaX * -1
-    evt.deltaY = e.wheelDeltaY || e.deltaY * -1
+    evt.deltaX = e.deltaX * -1
+    evt.deltaY = e.deltaY * -1
 
-    if (supportMouseTouch().isFirefox && e.deltaMode === 1) {
+    if (sniffer.isFirefox && e.deltaMode === 1) {
       evt.deltaX *= this.options.firefoxMultiplier
       evt.deltaY *= this.options.firefoxMultiplier
     }
@@ -70,16 +72,6 @@ export default class VirtualScroll {
     this.notify(e)
   }
 
-  onMouseWheel = e => {
-    if (this.options.limitInertia && !this.lethargy.check(e)) return
-
-    const evt = this.event
-    evt.deltaX = e.wheelDeltaX || 0
-    evt.deltaY = e.wheelDeltaY || e.wheelDelta
-
-    this.notify(e)
-  }
-
   onTouchStart = e => {
     const t = e.targetTouches ? e.targetTouches[0] : e
     this.touchStartX = t.pageX
@@ -132,44 +124,23 @@ export default class VirtualScroll {
   }
 
   bind = () => {
-    const support = supportMouseTouch()
+    this.el.addEventListener("wheel", this.onWheel, this.listenerOptions)
 
-    if (support.hasWheelEvent) this.el.addEventListener("wheel", this.onWheel, this.listenerOptions)
-
-    if (support.hasMouseWheelEvent)
-      this.el.addEventListener("mousewheel", this.onMouseWheel, this.listenerOptions)
-
-    if (support.hasTouch && this.options.useTouch) {
+    if (sniffer.isTouch && this.options.useTouch) {
       this.el.addEventListener("touchstart", this.onTouchStart, this.listenerOptions)
       this.el.addEventListener("touchmove", this.onTouchMove, this.listenerOptions)
     }
 
-    if (support.hasPointer && support.hasTouchWin) {
-      this.bodyTouchAction = document.body.style.msTouchAction
-      document.body.style.msTouchAction = "none"
-      this.el.addEventListener("MSPointerDown", this.onTouchStart, true)
-      this.el.addEventListener("MSPointerMove", this.onTouchMove, true)
-    }
-
-    if (support.hasKeyDown && this.options.useKeyboard) document.addEventListener("keydown", this.onKeyDown)
+    if (this.options.useKeyboard) document.addEventListener("keydown", this.onKeyDown)
   }
 
   unbind = () => {
-    const support = supportMouseTouch()
-
-    if (support.hasWheelEvent) this.el.removeEventListener("wheel", this.onWheel)
-    if (support.hasMouseWheelEvent) this.el.removeEventListener("mousewheel", this.onMouseWheel)
-    if (support.hasTouch) {
+    this.el.removeEventListener("wheel", this.onWheel)
+    if (sniffer.isTouch) {
       this.el.removeEventListener("touchstart", this.onTouchStart)
       this.el.removeEventListener("touchmove", this.onTouchMove)
     }
-    if (support.hasPointer && support.hasTouchWin) {
-      document.body.style.msTouchAction = this.bodyTouchAction
-      this.el.removeEventListener("MSPointerDown", this.onTouchStart, true)
-      this.el.removeEventListener("MSPointerMove", this.onTouchMove, true)
-    }
-    if (support.hasKeyDown && this.options.useKeyboard)
-      document.removeEventListener("keydown", this.onKeyDown)
+    if (this.options.useKeyboard) document.removeEventListener("keydown", this.onKeyDown)
   }
 
   on = (cb, priority = 0) => {
@@ -192,5 +163,8 @@ export default class VirtualScroll {
   destroy = () => {
     this.unbind()
     emitter.events[EVT_ID] = []
+
+    document.removeEventListener("focusin", this._onFocusIn)
+    document.removeEventListener("focusout", this._onFocusOut)
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linear_non/stellar-kit",
-  "version": "3.0.9",
+  "version": "3.0.12",
   "description": "Stellar frontend core for Non-Linear Studio projects.",
   "type": "module",
   "main": "./core/index.js",

package/plugins/Observer.js

@@ -33,7 +33,7 @@ export default class Observer extends Emitter {
       end,
       scrub,
       once,
-      markers,
+      markers: markers || kitStore.flags.isDebug,
       scroller: kitStore.scroller || undefined,
       onEnter: forward("enter"),
       onLeave: forward("leave"),

package/utils/debug.js

@@ -18,9 +18,21 @@ function fmt(scope) {
  *
  * - Controlled via kitStore.flags.isDebug
  * - No-op when debug is off
+ * - Call Debug.init() to auto-enable via ?debug URL param
  */
 
 export const Debug = {
+  /**
+   * Auto-enable debug mode if the URL contains a `?debug` query parameter.
+   * e.g. `https://example.com/?debug=1` or `?debug`
+   * Call this early (e.g. in Application.initialize).
+   */
+  init() {
+    const params = new URLSearchParams(window.location.search)
+    if (params.has("debug")) {
+      this.enable()
+    }
+  },
   enable() {
     kitStore.flags.isDebug = true
   },

package/utils/index.js

@@ -5,6 +5,6 @@ export { offset } from "./offset"
 export { getViewport, getWindowSizes, setViewportHeight } from "./window"
 export { sniffer } from "./sniffer"
 export { lerp, clamp, norm, round } from "./math"
-export { supportWebp, supportMouseTouch } from "./support"
+export { supportWebp } from "./support"
 export { listener } from "./listener"
 export { raf2 } from "./timing"

package/utils/sniffer.js

@@ -2,20 +2,12 @@
 export const sniffer = {
   uA: navigator.userAgent.toLowerCase(),
 
-  get isWindowsMobile() {
-    return /windows phone|iemobile|wpdesktop/.test(this.uA)
-  },
-
-  get isMobileOpera() {
-    return /opera mini/i.test(this.uA)
-  },
-
   get isIOS() {
     return /iphone|ipad|ipod/i.test(this.uA)
   },
 
   get isIpad() {
-    return !this.isWindowsMobile && /ipad/i.test(this.uA) && this.isIOS
+    return /ipad/i.test(this.uA) && this.isIOS
   },
 
   get isLatestIpad() {
@@ -23,15 +15,15 @@ export const sniffer = {
   },
 
   get isIphone() {
-    return !this.isWindowsMobile && /iphone/i.test(this.uA) && this.isIOS
+    return /iphone/i.test(this.uA) && this.isIOS
   },
 
   get isMobileAndroid() {
-    return !this.isWindowsMobile && /android.*mobile/.test(this.uA)
+    return /android.*mobile/.test(this.uA)
   },
 
   get isTabletAndroid() {
-    return !this.isWindowsMobile && !this.isMobileAndroid && /android/i.test(this.uA)
+    return !this.isMobileAndroid && /android/i.test(this.uA)
   },
 
   get isAndroid() {
@@ -39,7 +31,7 @@ export const sniffer = {
   },
 
   get isPhone() {
-    return this.isMobileAndroid || (this.isIOS && !this.isIpad) || this.isWindowsMobile
+    return this.isMobileAndroid || (this.isIOS && !this.isIpad)
   },
 
   get isTablet() {
@@ -62,18 +54,6 @@ export const sniffer = {
     return this.uA.includes("opr")
   },
 
-  get isIE11() {
-    return !window.ActiveXObject && "ActiveXObject" in window
-  },
-
-  get isIE() {
-    return this.uA.includes("msie") || this.isIE11 || this.uA.includes("edge")
-  },
-
-  get isEdge() {
-    return this.uA.includes("edge")
-  },
-
   get isWindows() {
     return /windows/i.test(this.uA)
   },
@@ -83,8 +63,7 @@ export const sniffer = {
       window.chrome !== null &&
       window.chrome !== undefined &&
       navigator.vendor.toLowerCase() === "google inc." &&
-      !this.isOpera &&
-      !this.isEdge
+      !this.isOpera
     )
   },
 
@@ -97,13 +76,15 @@ export const sniffer = {
   },
 
   get isTouch() {
-    return "ontouchstart" in window
+    return (
+      "ontouchstart" in window ||
+      !!window.TouchEvent ||
+      (navigator.maxTouchPoints && navigator.maxTouchPoints > 0)
+    )
   },
 
   get sniff() {
     return {
-      isWindowsMobile: this.isWindowsMobile,
-      isMobileOpera: this.isMobileOpera,
       isIOS: this.isIOS,
       isIpad: this.isIpad,
       isIphone: this.isIphone,
@@ -113,9 +94,6 @@ export const sniffer = {
       isFirefox: this.isFirefox,
       isSafari: this.isSafari,
       isOpera: this.isOpera,
-      isIE11: this.isIE11,
-      isIE: this.isIE,
-      isEdge: this.isEdge,
       isChrome: this.isChrome,
       isMac: this.isMac,
       isPhone: this.isPhone,

package/utils/support.js

@@ -6,18 +6,3 @@ export const supportWebp = () => {
   }
   return false
 }
-
-export const supportMouseTouch = () => {
-  return {
-    hasWheelEvent: "onwheel" in document,
-    hasMouseWheelEvent: "onmousewheel" in document,
-    hasTouch:
-      "ontouchstart" in window ||
-      window.TouchEvent ||
-      (navigator.maxTouchPoints && navigator.maxTouchPoints > 0),
-    hasTouchWin: navigator.msMaxTouchPoints && navigator.msMaxTouchPoints > 1,
-    hasPointer: !!window.navigator.msPointerEnabled,
-    hasKeyDown: "onkeydown" in document,
-    isFirefox: navigator.userAgent.indexOf("Firefox") > -1,
-  }
-}