cosmograph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corvin Burmeister
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# cosmograph
+
+Lightweight, zero-dependency canvas particle library. Composable forces, configurable everything.
+
+```
+npm install cosmograph
+```
+
+---
+
+## Quick start
+
+```js
+import { World, drift, dampen, twinkle, mouseRepel } from 'cosmograph'
+
+const world = new World({
+  canvas: document.getElementById('bg'),
+  nodeCount: 60,
+  colors: ['#ffffff', '#cce8ff'],
+  forces: [twinkle(), mouseRepel(), dampen(), drift()],
+})
+
+world.start()
+```
+
+**Forces are just functions** — compose them in any order, pass as an array. Each force runs every frame and mutates node velocities.
+
+---
+
+## Full-screen background
+
+```js
+const world = new World({
+  canvas,
+  autoResize: true,        // fits canvas to window, handles resize
+  pauseWhenHidden: true,   // pauses when tab is not visible
+  pauseWhenOffscreen: true,
+  nodeCount: 60,
+  colors: ['#ffffff', '#cce8ff', '#fff4e0'],
+  edgeMaxDist: 180,
+  forces: [twinkle(), mouseRepel(), dampen(), drift()],
+})
+world.start()
+```
+
+---
+
+## React
+
+```jsx
+import { useCosmograph } from 'cosmograph/react'
+import { drift, dampen, twinkle, mouseRepel } from 'cosmograph'
+
+export default function Background() {
+  const ref = useCosmograph({
+    nodeCount: 60,
+    colors: ['#ffffff', '#cce8ff'],
+    forces: [twinkle(), mouseRepel(), dampen(), drift()],
+  })
+
+  return <canvas ref={ref} style={{ position: 'fixed', inset: 0, width: '100%', height: '100%' }} />
+}
+```
+
+---
+
+## World options
+
+### Nodes
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `nodeCount` | `number` | `60` | Number of nodes |
+| `nodeSize` | `[min, max]` | `[0.8, 2.8]` | Radius range in px |
+| `colors` | `string[]` | `['#ffffff']` | Node colors |
+| `nodeShape` | `'circle' \| 'diamond' \| 'star' \| 'cross' \| 'ring'` | `'circle'` | Node shape |
+| `nodeRotation` | `boolean` | `false` | Nodes rotate on their axis — visible on diamond/star |
+| `nodeSizeDistribution` | `'uniform' \| 'gaussian' \| 'weighted-small'` | `'uniform'` | Size sampling distribution |
+| `nodeColorMode` | `'random' \| 'by-size' \| 'sequential' \| 'gradient' \| 'by-position'` | `'random'` | How colors are assigned |
+| `nodeSpawnRegion` | `'full' \| 'center' \| 'edges' \| fn` | `'full'` | Where nodes spawn. `fn(width, height) => {x, y}` for custom regions |
+
+### Edges
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `edgeMaxDist` | `number` | `180` | Max distance for edge to appear |
+| `edgeMaxOpacity` | `number` | `0.18` | Max edge opacity |
+| `edgeWidth` | `number` | `0.5` | Edge stroke width in px |
+| `edgeColors` | `string[]` | `null` | Edge colors — falls back to `colors` if not set |
+| `edgeStyle` | `'solid' \| 'dashed' \| 'gradient'` | `'solid'` | `gradient` interpolates between connected node colors |
+| `edgeColorMode` | `'alternate' \| 'source' \| 'target' \| fn` | `'alternate'` | `fn(a, b, i, j) => color` for custom logic |
+| `edgeCurvature` | `number` | `0` | `0` = straight, `1` = strong bezier curve |
+| `maxEdgesPerNode` | `number \| null` | `null` | Cap connections per node — prevents dense clusters |
+| `minEdgesPerNode` | `number \| null` | `null` | Guarantee minimum connections — draws faint long-range edges as fallback |
+
+### Glow
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `glowOnLargeNodes` | `boolean` | `true` | Adds radial halo to nodes above threshold |
+| `glowThreshold` | `number` | `2` | Minimum radius to trigger glow |
+| `glowScale` | `number` | `4` | Halo radius multiplier |
+| `glowOpacity` | `number` | `0.25` | Halo opacity |
+
+### Rendering
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `blendMode` | `string` | `'source-over'` | Canvas `globalCompositeOperation` — `'screen'` makes overlapping nodes glow brighter |
+| `renderOrder` | `'edges-first' \| 'nodes-first'` | `'edges-first'` | Draw order |
+| `background` | `string \| null` | `null` | Background fill color — `null` for transparent |
+| `pixelRatio` | `number \| 'auto'` | `'auto'` | HiDPI/Retina pixel ratio |
+
+### Performance
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `pauseWhenHidden` | `boolean` | `true` | Pause RAF when tab is not visible |
+| `pauseWhenOffscreen` | `boolean` | `false` | Pause RAF when canvas is scrolled out of view |
+| `autoResize` | `boolean` | `true` | Fit canvas to window on resize — set to `false` when managing canvas size yourself |
+| `maxEdgesPerFrame` | `number \| null` | `null` | Hard cap on edges drawn per frame — useful for very high node counts |
+| `spatialIndex` | `boolean` | `false` | Use a QuadTree for edge queries — O(n log n) instead of O(n²), worth enabling above ~200 nodes |
+
+### Callbacks
+
+| Option | Type | Description |
+|---|---|---|
+| `onFrame` | `(nodes, context) => void` | Called every frame after rendering |
+| `onNodeHover` | `(node) => void` | Called when cursor enters a node's hitbox |
+| `onNodeLeave` | `(node) => void` | Called when cursor leaves a node's hitbox |
+| `onNodeClick` | `(node) => void` | Called when a node is clicked |
+
+---
+
+## Forces
+
+Forces are plain functions — `(nodes, context) => void`. The `context` object provides `{ time, mouse, scrollY, width, height }`. Combine freely.
+
+### `drift({ maxSpeed })`
+Caps node velocity — prevents runaway acceleration. Use as the last force in your chain.
+
+| Param | Default | |
+|---|---|---|
+| `maxSpeed` | `0.08` | Maximum speed in px/frame |
+
+### `dampen({ factor })`
+Multiplies all velocities by `factor` each frame — simulates friction.
+
+| Param | Default | |
+|---|---|---|
+| `factor` | `0.99` | `0.95` = heavy friction, `0.999` = near frictionless |
+
+### `twinkle({ minBrightness, variance })`
+Oscillates node opacity using a per-node sine wave.
+
+| Param | Default | |
+|---|---|---|
+| `minBrightness` | `0.5` | Minimum alpha |
+| `variance` | `0.5` | Oscillation amplitude |
+
+### `mouseRepel({ mode, radius, strength, fn })`
+Cursor interaction.
+
+| Param | Default | |
+|---|---|---|
+| `mode` | `'repel'` | `'repel'` · `'attract'` · `'orbit'` · `'custom'` |
+| `radius` | `120` | Influence radius in px |
+| `strength` | `0.012` | Force multiplier |
+| `fn` | — | `fn(node, mouse, context)` when `mode: 'custom'` |
+
+### `gravity({ x, y, strength })`
+Pulls all nodes toward a fixed point. Values `0..1` are relative to canvas size.
+
+| Param | Default | |
+|---|---|---|
+| `x` | `0.5` | Target x — `0.5` = center |
+| `y` | `0.5` | Target y |
+| `strength` | `0.0002` | Force magnitude |
+
+### `attract({ x, y, radius, strength })`
+Like gravity but only affects nodes within `radius`. Has a dead zone at the center — combine with `nodeRepel` to prevent clustering.
+
+| Param | Default | |
+|---|---|---|
+| `x` | `0.5` | Target x |
+| `y` | `0.5` | Target y |
+| `radius` | `200` | Influence radius in px |
+| `strength` | `0.001` | Force magnitude |
+
+### `nodeRepel({ radius, strength })`
+Nodes push each other away — simulates charged particles. O(n²), keep `radius` small.
+
+| Param | Default | |
+|---|---|---|
+| `radius` | `60` | Repulsion radius |
+| `strength` | `0.003` | Force magnitude |
+
+### `wind({ angle, strength, gust })`
+Constant directional force with optional sinusoidal gusting.
+
+| Param | Default | |
+|---|---|---|
+| `angle` | `0` | Direction in radians |
+| `strength` | `0.001` | Base force magnitude |
+| `gust` | `0` | Gust amplitude |
+
+### `noise({ scale, strength, speed })`
+Moves nodes along a slowly shifting 2D vector field. Nearby nodes flow in the same direction — organic, non-random.
+
+| Param | Default | |
+|---|---|---|
+| `scale` | `0.004` | Field scale — small = broad sweeping currents |
+| `strength` | `0.001` | Force magnitude |
+| `speed` | `0.0003` | How fast the field shifts over time |
+
+### `scrollDrift({ mode, strength })`
+Reacts to `world.scrollY`. In `autoResize` mode this tracks `window.scrollY` automatically.
+
+| Param | Default | |
+|---|---|---|
+| `mode` | `'rotate'` | `'rotate'` · `'wave'` · `'scatter'` · `'custom'` |
+| `strength` | `1.0` | Effect multiplier |
+| `fn` | — | `fn(node, delta, context)` when `mode: 'custom'` |
+
+---
+
+## Custom forces
+
+Any function matching `(nodes, context) => void` works as a force:
+
+```js
+function pulse() {
+  return (nodes, { time }) => {
+    const scale = Math.sin(time * 0.001)
+    for (const node of nodes) {
+      node.vx += (node.x - 400) * scale * 0.0001
+      node.vy += (node.y - 300) * scale * 0.0001
+    }
+  }
+}
+
+new World({ canvas, forces: [pulse(), dampen(), drift()] })
+```
+
+---
+
+## API
+
+### `world.start()`
+Begins the render loop and registers event listeners.
+
+### `world.stop()`
+Cancels the render loop and removes all event listeners.
+
+### `world.scrollY`
+Set directly when managing scroll manually (e.g. in a bounded canvas):
+```js
+window.addEventListener('scroll', () => { world.scrollY = window.scrollY })
+```
+
+---
+
+## Shapes
+
+`circle` · `diamond` · `star` · `cross` · `ring`
+
+Custom shape function: `(ctx, x, y, r) => void`
+
+```js
+import { World } from 'cosmograph'
+
+function triangle(ctx, x, y, r) {
+  ctx.beginPath()
+  ctx.moveTo(x, y - r)
+  ctx.lineTo(x + r, y + r)
+  ctx.lineTo(x - r, y + r)
+  ctx.closePath()
+  ctx.fill()
+}
+
+new World({ canvas, nodeShape: triangle })
+```

package/index.d.ts

@@ -0,0 +1,176 @@
+// cosmograph — canvas particle library
+
+export interface NodeOptions {
+  x: number
+  y: number
+  r: number
+  vx: number
+  vy: number
+  color: string
+  phase: number
+  twinkleSpeed: number
+}
+
+export declare class Node {
+  x: number
+  y: number
+  r: number
+  vx: number
+  vy: number
+  color: string
+  brightness: number
+  phase: number
+  twinkleSpeed: number
+  angle?: number
+  angularVelocity?: number
+  shape?: string | ShapeFn
+  constructor(opts: NodeOptions)
+}
+
+export type ShapeFn = (ctx: CanvasRenderingContext2D, x: number, y: number, r: number) => void
+
+export declare function resolveShape(shape: string | ShapeFn): ShapeFn
+
+export declare const circle: ShapeFn
+export declare const diamond: ShapeFn
+export declare const star: ShapeFn
+export declare const cross: ShapeFn
+export declare const ring: ShapeFn
+
+export interface ForceContext {
+  readonly time: number
+  readonly mouse: { x: number; y: number } | null
+  readonly scrollY: number
+  readonly width: number
+  readonly height: number
+}
+
+export type Force = (nodes: Node[], context: ForceContext) => void
+
+export interface WorldOptions {
+  canvas: HTMLCanvasElement
+  forces?: Force[]
+  // Nodes
+  nodeCount?: number
+  nodeSize?: number | [number, number]
+  colors?: string[]
+  nodeSizeDistribution?: 'uniform' | 'gaussian' | 'weighted-small'
+  nodeColorMode?: 'random' | 'by-size' | 'sequential' | 'gradient' | 'by-position'
+  nodeSpawnRegion?: 'full' | 'center' | 'edges' | ((width: number, height: number) => { x: number; y: number })
+  nodeRotation?: boolean
+  // Edges
+  edgeMaxDist?: number
+  edgeMaxOpacity?: number
+  edgeWidth?: number
+  edgeColors?: string[] | null
+  edgeStyle?: 'solid' | 'dashed' | 'gradient'
+  edgeColorMode?: 'alternate' | 'source' | 'target' | ((a: Node, b: Node, i: number, j: number) => string)
+  maxEdgesPerNode?: number | null
+  minEdgesPerNode?: number | null
+  edgeCurvature?: number
+  // Shape
+  nodeShape?: string | ShapeFn
+  // Glow
+  glowOnLargeNodes?: boolean
+  glowThreshold?: number
+  glowScale?: number
+  glowOpacity?: number
+  // Rendering
+  pixelRatio?: 'auto' | number
+  blendMode?: GlobalCompositeOperation
+  renderOrder?: 'edges-first' | 'nodes-first'
+  background?: string | null
+  // Callbacks
+  onFrame?: ((nodes: Node[], context: ForceContext) => void) | null
+  onNodeHover?: ((node: Node) => void) | null
+  onNodeLeave?: ((node: Node) => void) | null
+  onNodeClick?: ((node: Node) => void) | null
+  // Performance
+  pauseWhenHidden?: boolean
+  maxEdgesPerFrame?: number | null
+  spatialIndex?: boolean
+  autoResize?: boolean
+  pauseWhenOffscreen?: boolean
+}
+
+export declare class World {
+  canvas: HTMLCanvasElement
+  nodes: Node[]
+  forces: Force[]
+  options: WorldOptions
+  constructor(opts: WorldOptions)
+  start(): void
+  stop(): void
+  resize(): void
+  update(options: Partial<Omit<WorldOptions, 'canvas'>>): void
+}
+
+// Forces
+export interface DriftOptions {
+  speed?: number
+  chaos?: number
+}
+export declare function drift(opts?: DriftOptions): Force
+
+export interface DampenOptions {
+  factor?: number
+}
+export declare function dampen(opts?: DampenOptions): Force
+
+export interface TwinkleOptions {
+  minBrightness?: number
+  variance?: number
+}
+export declare function twinkle(opts?: TwinkleOptions): Force
+
+export interface MouseRepelOptions {
+  radius?: number
+  strength?: number
+  mode?: 'repel' | 'attract'
+}
+export declare function mouseRepel(opts?: MouseRepelOptions): Force
+
+export interface ScrollDriftOptions {
+  mode?: 'rotate' | 'wave' | 'scatter' | 'custom'
+  strength?: number
+  fn?: (node: Node, delta: number, context: ForceContext) => void
+}
+export declare function scrollDrift(opts?: ScrollDriftOptions): Force
+
+export interface GravityOptions {
+  x?: number | ((context: ForceContext) => number)
+  y?: number | ((context: ForceContext) => number)
+  strength?: number
+}
+export declare function gravity(opts?: GravityOptions): Force
+
+export interface WindOptions {
+  angle?: number
+  speed?: number
+  turbulence?: number
+}
+export declare function wind(opts?: WindOptions): Force
+
+export interface NodeRepelOptions {
+  radius?: number
+  strength?: number
+}
+export declare function nodeRepel(opts?: NodeRepelOptions): Force
+
+export interface NoiseOptions {
+  scale?: number
+  speed?: number
+  strength?: number
+}
+export declare function noise(opts?: NoiseOptions): Force
+
+export interface AttractOptions {
+  x?: number | ((width: number, height: number) => number)
+  y?: number | ((width: number, height: number) => number)
+  radius?: number
+  strength?: number
+}
+export declare function attract(opts?: AttractOptions): Force
+
+// React adapter
+export declare function useCosmograph(options?: Omit<WorldOptions, 'canvas'>): React.RefObject<HTMLCanvasElement>

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "cosmograph",
+  "version": "0.1.0",
+  "description": "Lightweight, zero-dependency canvas particle library. Composable forces, configurable everything.",
+  "keywords": ["canvas", "particles", "animation", "constellation", "webgl", "background", "force", "interactive"],
+  "author": "Corvin Burmeister",
+  "license": "MIT",
+  "type": "module",
+  "types": "index.d.ts",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./react": "./src/adapters/react.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "index.d.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BurmCo/cosmograph.git"
+  },
+  "homepage": "https://github.com/BurmCo/cosmograph#readme",
+  "bugs": {
+    "url": "https://github.com/BurmCo/cosmograph/issues"
+  },
+  "sideEffects": false
+}

package/src/Node.js

@@ -0,0 +1,13 @@
+export class Node {
+  constructor({ x, y, r, vx, vy, color, phase, twinkleSpeed }) {
+    this.x = x
+    this.y = y
+    this.r = r
+    this.vx = vx
+    this.vy = vy
+    this.color = color
+    this.phase = phase
+    this.twinkleSpeed = twinkleSpeed
+    this.brightness = 1
+  }
+}

package/src/QuadTree.js

@@ -0,0 +1,65 @@
+export class QuadTree {
+  constructor(x, y, w, h, capacity = 8) {
+    this.x = x
+    this.y = y
+    this.w = w
+    this.h = h
+    this.capacity = capacity
+    this.points = []
+    this.divided = false
+  }
+
+  insert(point) {
+    if (!this._contains(point.x, point.y)) return false
+    if (this.points.length < this.capacity && !this.divided) {
+      this.points.push(point)
+      return true
+    }
+    if (!this.divided) this._subdivide()
+    return (
+      this._ne.insert(point) ||
+      this._nw.insert(point) ||
+      this._se.insert(point) ||
+      this._sw.insert(point)
+    )
+  }
+
+  queryRadius(cx, cy, r, result = []) {
+    if (!this._intersectsCircle(cx, cy, r)) return result
+    if (this.divided) {
+      this._ne.queryRadius(cx, cy, r, result)
+      this._nw.queryRadius(cx, cy, r, result)
+      this._se.queryRadius(cx, cy, r, result)
+      this._sw.queryRadius(cx, cy, r, result)
+    } else {
+      for (const p of this.points) {
+        if (Math.hypot(p.x - cx, p.y - cy) <= r) result.push(p)
+      }
+    }
+    return result
+  }
+
+  _contains(px, py) {
+    return px >= this.x && px < this.x + this.w && py >= this.y && py < this.y + this.h
+  }
+
+  _intersectsCircle(cx, cy, r) {
+    const nearX = Math.max(this.x, Math.min(cx, this.x + this.w))
+    const nearY = Math.max(this.y, Math.min(cy, this.y + this.h))
+    return Math.hypot(cx - nearX, cy - nearY) <= r
+  }
+
+  _subdivide() {
+    const hw = this.w / 2
+    const hh = this.h / 2
+    this._ne = new QuadTree(this.x + hw, this.y, hw, hh, this.capacity)
+    this._nw = new QuadTree(this.x, this.y, hw, hh, this.capacity)
+    this._se = new QuadTree(this.x + hw, this.y + hh, hw, hh, this.capacity)
+    this._sw = new QuadTree(this.x, this.y + hh, hw, hh, this.capacity)
+    this.divided = true
+    for (const p of this.points) {
+      this._ne.insert(p) || this._nw.insert(p) || this._se.insert(p) || this._sw.insert(p)
+    }
+    this.points = []
+  }
+}