@linear_non/stellar-kit 3.0.8 → 3.0.11

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/classes/ImageLoader.js

@@ -24,6 +24,8 @@ export default class ImageLoader {
 
     this._results = new Map() // url -> HTMLImageElement
     this._objectURLs = [] // for revoke
+    this._worker = null // shared worker instance
+    this._workerURL = null // blob URL for cleanup
   }
 
   async load() {
@@ -61,6 +63,9 @@ export default class ImageLoader {
 
     await Promise.all(toLoad.map(url => this._loadOne(url)))
 
+    // Terminate shared worker if created
+    this._terminateWorker()
+
     // build ordered result (use cache first, then freshly loaded)
     this.images = urls.map(u => this.cache?.get(u) || this._results.get(u) || null)
     this.isLoaded = true
@@ -69,19 +74,34 @@ export default class ImageLoader {
   }
 
   _createInlineWorker() {
+    if (this._worker) return this._worker
+
     const code = `
     self.onmessage = async (e) => {
-      const { url } = e.data;
+      const { url, id } = e.data;
       try {
         const res = await fetch(url);
         const blob = await res.blob();
-        self.postMessage({ url, blob });
+        self.postMessage({ url, id, blob });
       } catch (err) {
-        self.postMessage({ url, error: String(err) });
+        self.postMessage({ url, id, error: String(err) });
       }
     };`
     const blob = new Blob([code], { type: "application/javascript" })
-    return new Worker(URL.createObjectURL(blob))
+    this._workerURL = URL.createObjectURL(blob)
+    this._worker = new Worker(this._workerURL)
+    return this._worker
+  }
+
+  _terminateWorker() {
+    if (this._worker) {
+      this._worker.terminate()
+      this._worker = null
+    }
+    if (this._workerURL) {
+      URL.revokeObjectURL(this._workerURL)
+      this._workerURL = null
+    }
   }
 
   async _loadOne(url) {
@@ -89,20 +109,25 @@ export default class ImageLoader {
     if (this.useWorker && typeof Worker !== "undefined") {
       return new Promise(resolve => {
         const w = this._createInlineWorker()
-        w.onmessage = async e => {
+        const id = url // use url as unique message id
+
+        const handler = async e => {
+          if (e.data.id !== id) return // not our message
+          w.removeEventListener("message", handler)
+
           const { blob, error } = e.data
           if (error || !blob) {
             this._bumpProgress()
-            w.terminate()
             return resolve(null)
           }
           const img = await this._blobToImage(blob)
           this._store(url, img)
           this._bumpProgress()
-          w.terminate()
           resolve(img)
         }
-        w.postMessage({ url })
+
+        w.addEventListener("message", handler)
+        w.postMessage({ url, id })
       })
     }
 
@@ -155,6 +180,7 @@ export default class ImageLoader {
   }
 
   destroy() {
+    this._terminateWorker()
     this._objectURLs.forEach(u => URL.revokeObjectURL(u))
     this._objectURLs.length = 0
     this.images = []

package/core/PageEngine.js

@@ -123,6 +123,8 @@ export default class PageEngine {
       this.smooth = smooth
     }
 
+    this.trackImages()
+
     this.manager = new Manager()
 
     if (this.manager && this.components.length) {
@@ -132,12 +134,27 @@ export default class PageEngine {
     }
 
     this.manager.initialize()
+    this.resize()
 
     this.on()
-    this.trackImages()
-    this.resize()
+  }
 
-    this.manager.animateIn?.()
+  /**
+   * Trigger entry animations on all components.
+   * Call this from the page/renderer at the appropriate moment
+   * (e.g. after loader completes or onEnterCompleted).
+   */
+  animateIn() {
+    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?.()
   }
 
   /**
@@ -167,7 +184,7 @@ export default class PageEngine {
 
     // Setup ScrollTrigger scroller proxy
     ScrollTrigger.scrollerProxy(wrapper, {
-      scrollTop: (value) => {
+      scrollTop: value => {
         if (value !== undefined) {
           this.lenis.scrollTo(value, { immediate: true })
         }
@@ -286,7 +303,6 @@ export default class PageEngine {
    */
   off() {
     this.listeners("off")
-    this.destroy()
   }
 
   /**
@@ -309,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/Emitter.js

@@ -33,7 +33,7 @@ class Emitter {
     }
     this.on(event, onceCallback, priority)
     return () => {
-      this.off(event, cb)
+      this.off(event, onceCallback)
     }
   }
 
@@ -53,6 +53,9 @@ const EVENTS = {
   APP_MOUSEMOVE: "mousemove",
   APP_MOUSEDOWN: "mousedown",
   APP_MOUSEUP: "mouseup",
+  APP_ROUTE_IN: "route:in",
+  APP_ROUTE_OUT: "route:out",
+  APP_ROUTE_END: "route:end",
   APP_SPLITTEXT_READY: "splittext:ready",
   APP_IMAGES_LOADED: "images:loaded",
   APP_IMAGES_PROGRESS: "images:progress",

package/events/Mouse.js

@@ -15,8 +15,6 @@ export default class Mouse {
       down: sniffer.isDevice ? "touchstart" : "mousedown",
       up: sniffer.isDevice ? "touchend" : "mouseup",
     }
-
-    this.on()
   }
 
   on() {
@@ -54,7 +52,7 @@ export default class Mouse {
   onUp = e => {
     const { x, target } = this.getPos(e)
     this.state.off = x
-    const isClick = Math.abs(this.state.on - this.state.off) > 10
+    const isClick = Math.abs(this.state.on - this.state.off) <= 10
     emitter.emit(EVENTS.APP_MOUSEUP, { x, target, isClick })
   }
 }

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) => {
@@ -191,6 +162,9 @@ export default class VirtualScroll {
 
   destroy = () => {
     this.unbind()
-    emitter.off(EVT_ID, () => {}) // Clear all
+    emitter.events[EVT_ID] = []
+
+    document.removeEventListener("focusin", this._onFocusIn)
+    document.removeEventListener("focusout", this._onFocusOut)
   }
 }

package/kitStore.js

@@ -40,12 +40,36 @@ export const kitStore = {
   breakpoints,
   mouse,
   flags,
-  pageContent: null,
   assets,
+
+  /** @type {HTMLElement | null} — main content container (#app) */
+  pageContent: null,
+
+  /** @type {HTMLElement | null} — current page/view element ([data-taxi-view]) */
+  currentPage: null,
+
+  /** @type {URL | string | null} — current URL (set by Application) */
+  currentURL: null,
+
+  /** @type {HTMLElement | null} — loader element (set by Application) */
+  load: null,
+
   /**
    * Scroll scroller element (wrapper for Lenis, pageContent for internal scroll).
    * Used by ScrollTrigger components to get the correct scroller.
    * @type {HTMLElement | null}
    */
   scroller: null,
+
+  /** @type {import("./events/Raf").default | null} */
+  raf: null,
+
+  /** @type {import("./events/Scroll").default | null} */
+  scroll: null,
+
+  /** @type {import("./events/Resize").default | null} */
+  resize: null,
+
+  /** @type {any | null} — Taxi router instance (if attached via Application.attachTaxi()) */
+  taxi: null,
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@linear_non/stellar-kit",
-  "version": "3.0.8",
+  "version": "3.0.11",
   "description": "Stellar frontend core for Non-Linear Studio projects.",
   "type": "module",
-  "main": "/core/index.js",
+  "main": "./core/index.js",
   "sass": "./styles/index.scss",
   "exports": {
     ".": "./kitStore.js",

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/math.js

@@ -31,7 +31,7 @@ export const clamp = (val, min, max) => Math.min(Math.max(val, min), max)
  * @param {number} [p=3] - Decimal precision
  * @returns {number}
  */
-export const round = (n, p) => {
-  const precision = p !== undefined ? Math.pow(10, p) : 1000
+export const round = (n, p = 3) => {
+  const precision = Math.pow(10, p)
   return Math.round(n * precision) / precision
 }

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,20 +54,8 @@ 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 ["Win32", "Win64", "Windows", "WinCE"].includes(window.navigator.platform)
+    return /windows/i.test(this.uA)
   },
 
   get isChrome() {
@@ -83,13 +63,12 @@ export const sniffer = {
       window.chrome !== null &&
       window.chrome !== undefined &&
       navigator.vendor.toLowerCase() === "google inc." &&
-      !this.isOpera &&
-      !this.isEdge
+      !this.isOpera
     )
   },
 
   get isMac() {
-    return navigator.platform.toLowerCase().includes("mac")
+    return /macintosh|mac os x/i.test(this.uA)
   },
 
   get isDesktop() {
@@ -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 ||
-      (window.DocumentTouch && document instanceof DocumentTouch),
-    hasTouchWin: navigator.msMaxTouchPoints && navigator.msMaxTouchPoints > 1,
-    hasPointer: !!window.navigator.msPointerEnabled,
-    hasKeyDown: "onkeydown" in document,
-    isFirefox: navigator.userAgent.indexOf("Firefox") > -1,
-  }
-}