npm package: @linear_non/stellar-kit
Description: Stellar frontend core for Non-Linear Studio projects.
Author: Non-Linear Studio
Latest version: 3.2.1

# 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

```bash
npm install @linear_non/stellar-kit
```

## Quick Start

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

## Imports

```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, getMarkerContainer, fixScrollerMarkers, fixTriggerMarkers } 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"

// 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, 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:

```js
engine.setup({ components, smooth })
```

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

```js
engine.setup({ components, lenis, wrapper })
```

## Local Development

```bash
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.

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

```js
// 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)
- [ ] `Application.scrollTo()` named scroll target helper
- [ ] First-class `Application.lock()` / `Application.unlock()` scroll lock API

## License

MIT

---

Made with ❤️ by [Non-Linear Studio](https://non-linear.studio)