stellar-kit

@linear_non/stellar-kit — Front-end core framework for Non-Linear Studio projects.

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.

Installation

npm install @linear_non/stellar-kit

Quick Start

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 },
})

Imports

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, getMarkerContainer, fixScrollerMarkers, fixTriggerMarkers } from "@linear_non/stellar-kit/plugins"
import { qs, qsa, bounds, lerp, damp, clamp, sniffer, listener } from "@linear_non/stellar-kit/utils"
import { gsap, ScrollTrigger, SplitText } from "@linear_non/stellar-kit/gsap"

// Tailwind preset (layout-only utilities)
import stellarPreset from "@linear_non/stellar-kit/styles/preset"

Architecture

| 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 (lerp, damp), sniffer, viewport, debug | | gsap | Pre-configured GSAP with ScrollTrigger, SplitText, CustomEase | | styles | SCSS reset + helpers; Tailwind preset for layout utilities |

Scroll Modes

Internal — VirtualScroll + lerp interpolation in Raf:

await engine.setup({ components, smooth })

External (Lenis) — Lenis manages scroll, PageEngine sets up ScrollTrigger proxy:

await engine.setup({ components, lenis, wrapper })

Lazy components

Components can use dynamic imports — only fetched when their DOM nodes exist:

this.components.push(
  { name: "header", instance: Header },                              // eager
  { name: "gallery", loader: () => import("./Gallery.js") },         // lazy
)

engine.setup() resolves all pending loaders in parallel before initializing. Fully backwards compatible — eager instance entries work exactly as before.

Scroll to target — works in both modes:

Application.scrollTo('#about')
Application.scrollTo('.section', { offset: -100, duration: 2 })
Application.scrollTo('top', { immediate: true })

Local Development

npm install
npm run dev

The dev/ folder provides a Vite playground for testing.

Tailwind (v4)

Layout-only Tailwind utilities. Typography and component styles stay in SCSS.

/* src/styles/tailwind.css */
@import "tailwindcss" layer(utilities);
@import "@linear_non/stellar-kit/styles/theme.css";

// astro.config.mjs (or vite.config.js)
import tailwindcss from "@tailwindcss/vite"
// add tailwindcss() to vite plugins

No tailwind.config.js, no postcss.config.mjs needed.

Spacing — pixel-named: p-24 = 2.4rem = 24px. Fine range 1-20 (every pixel), then 8px grid multiples up to 1440. Columns — w-col-9 = 36rem = 360px (36 cols × 4rem default) Breakpoints — m-up:flex (desktop), max-m-up:hidden (mobile only) Viewport — h-vh = var(--vh, 100vh) Negative margins — -m-16 = -1.6rem Colors — bg-black, text-white, bg-[#ccc], bg-black/10

SCSS import still works alongside: @import "@linear_non/stellar-kit/styles"

Roadmap

• [ ] TypeScript definitions (.d.ts for all 7 public exports)
• [ ] Unit test suite (Emitter, Manager, sniffer, math utils)
• [ ] Debug overlay panel for mobile (?debug live kitStore inspector)
• [x] Application.scrollTo() unified scroll-to (internal + Lenis)
• [x] Tab key support in smooth scroll (focus-driven scroll via Raf.scrollTo)
• [x] Manager lazy component loading (loader dynamic imports)
• [ ] First-class Application.lock() / Application.unlock() scroll lock API

License

MIT

Made with ❤️ by Non-Linear Studio