@diabolic/borealis 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Borealis Contributors
+
+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,520 @@
+# Borealis
+
+An interactive, animated canvas background with noise-based patterns and visual effects.
+
+[![npm version](https://badge.fury.io/js/@diabolic%2Fborealis.svg)](https://www.npmjs.com/package/@diabolic/borealis)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+https://github.com/user-attachments/assets/897d9ca9-2ac9-4b55-adaa-158a704aa220
+
+> 🎬 [Live Demo](https://bugrakaan.github.io/borealis/)
+
+## Features
+
+- 🌟 **Noise-based patterns** - Beautiful river-like patterns using Simplex noise with domain warping
+- 🔵 **Solid dot pattern** - Clean grid of uniform dots (alternative to noise)
+- ✨ **Wave effect** - Diagonal sparkling wave that sweeps across the screen
+- 💫 **Twinkle effect** - Grouped star twinkling with customizable dead zone
+- 🌈 **Aurora colors** - Optional cyan-green to violet color gradient
+- 🎯 **Radial collapse/expand** - Smooth show/hide animations from center
+- 🎬 **WebM Recording** - Export animations as high-quality video (VP9 codec)
+- 🎭 **Alpha Mask Export** - Generate separate luma matte video for compositing
+- 💾 **URL State Persistence** - Share configurations via URL parameters
+- 📋 **Copy Code Button** - Generate initialization code from current settings
+- ⚡ **Highly customizable** - 40+ configurable options
+- 📱 **Responsive** - Automatically adapts to window size
+- 🪶 **Lightweight** - No dependencies, pure JavaScript
+- 📦 **TypeScript support** - Full type definitions included
+
+## Installation
+
+### npm
+
+```bash
+npm install @diabolic/borealis
+```
+
+### yarn
+
+```bash
+yarn add @diabolic/borealis
+```
+
+### pnpm
+
+```bash
+pnpm add @diabolic/borealis
+```
+
+### CDN
+
+```html
+<!-- UMD (Global variable) -->
+<script src="https://unpkg.com/@diabolic/borealis/dist/borealis.min.js"></script>
+
+<!-- Or from jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/@diabolic/borealis/dist/borealis.min.js"></script>
+```
+
+### Direct Script Include
+
+```html
+<script src="borealis.js"></script>
+```
+
+## Quick Start
+
+### ES Module
+
+```javascript
+import Borealis from '@diabolic/borealis';
+
+// Create with default options (fullscreen)
+const borealis = new Borealis();
+
+// Create with custom options
+const borealis = new Borealis({
+    effect: {
+        type: 'twinkle',
+        aurora: true
+    },
+    patternAurora: true,
+    density: 70
+});
+```
+
+### Target a Specific Container
+
+```javascript
+// Render inside a specific element
+const borealis = new Borealis({
+    container: document.getElementById('my-container'),
+    fullscreen: false  // Use container dimensions instead of viewport
+});
+
+// With explicit dimensions
+const borealis = new Borealis({
+    container: document.getElementById('hero-section'),
+    fullscreen: false,
+    width: 800,
+    height: 400
+});
+```
+
+### CommonJS
+
+```javascript
+const Borealis = require('@diabolic/borealis');
+
+const borealis = new Borealis();
+```
+
+### Browser (UMD)
+
+```html
+<script src="https://unpkg.com/@diabolic/borealis/dist/borealis.min.js"></script>
+<script>
+    const borealis = new Borealis({
+        effect: { type: 'wave' }
+    });
+</script>
+```
+
+## API Reference
+
+### Constructor
+
+```javascript
+new Borealis(options)
+```
+
+Creates a new Borealis instance with the specified options.
+
+### Methods
+
+#### `start()`
+Start the animation loop.
+
+```javascript
+borealis.start();
+```
+
+#### `stop()`
+Stop the animation loop.
+
+```javascript
+borealis.stop();
+```
+
+#### `resize([width], [height])`
+Manually trigger a resize. Useful when container size changes.
+
+```javascript
+// Resize to specific dimensions
+borealis.resize(800, 600);
+
+// Resize using current container dimensions
+borealis.resize();
+```
+
+#### `redraw()`
+Force a single frame redraw. Useful when animation is stopped but you want to update the display.
+
+```javascript
+borealis.stop();
+borealis.setOption('patternAurora', true);
+borealis.redraw(); // Update display without starting animation
+```
+
+#### `show([callback])`
+Expand the pattern from center (reverse collapse).
+
+```javascript
+borealis.show(() => {
+    console.log('Pattern is now visible');
+});
+```
+
+#### `hide([callback])`
+Collapse the pattern to center.
+
+```javascript
+borealis.hide(() => {
+    console.log('Pattern is now hidden');
+});
+```
+
+
+#### `toggle([callback])`
+Toggle between show and hide states.
+
+```javascript
+borealis.toggle();
+```
+
+#### `isVisible()`
+Returns `true` if the pattern is fully visible (not collapsed).
+
+```javascript
+if (borealis.isVisible()) {
+    console.log('Pattern is visible');
+}
+```
+
+#### `isHidden()`
+Returns `true` if the pattern is fully hidden (collapsed).
+
+```javascript
+if (borealis.isHidden()) {
+    console.log('Pattern is hidden');
+}
+```
+
+#### `setOption(key, value)`
+Set a single option value.
+
+```javascript
+borealis.setOption('effect', 'twinkle');
+borealis.setOption('density', 80);
+```
+
+#### `setOptions(options)`
+Set multiple options at once.
+
+```javascript
+borealis.setOptions({
+    effect: 'twinkle',
+    patternAurora: true,
+    twinkleSpeed: 70
+});
+```
+
+#### `getOption(key)`
+Get a specific option value.
+
+```javascript
+const currentEffect = borealis.getOption('effect');
+```
+
+#### `getOptions()`
+Get all current options.
+
+```javascript
+const options = borealis.getOptions();
+```
+
+#### `destroy()`
+Clean up and remove the canvas from DOM.
+
+```javascript
+borealis.destroy();
+```
+
+## Options Reference
+
+### Container Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `container` | `HTMLElement` | `document.body` | Parent element for the canvas |
+
+### Grid Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `density` | `number` | `50` | Grid density (10-100). Higher = more dots |
+| `densityMinCell` | `number` | `2` | Minimum cell size at max density |
+| `densityMaxCell` | `number` | `8` | Maximum cell size at min density |
+| `dotSize` | `number` | `0` | Fixed dot size (0-10). 0 = noise-based size |
+| `solidPattern` | `boolean` | `false` | Use uniform solid dots instead of noise pattern |
+| `densityMinGap` | `number` | `1` | Minimum gap at max density |
+| `densityMaxGap` | `number` | `4` | Maximum gap at min density |
+
+### Pattern Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `patternScale` | `number` | `0.001` | Noise scale (smaller = larger patterns) |
+| `patternAurora` | `boolean` | `false` | Use aurora colors for base pattern |
+| `warpScale` | `number` | `0.5` | Domain warp frequency multiplier |
+| `warpAmount` | `number` | `20` | Domain warp intensity |
+| `animationSpeed` | `number` | `0.00002` | Base animation speed |
+| `ridgePower` | `number` | `2` | Ridge sharpness (higher = sharper lines) |
+| `minOpacity` | `number` | `0` | Minimum dot opacity (0-1) |
+| `maxOpacity` | `number` | `1` | Maximum dot opacity (0-1) |
+| `waveFrequency` | `number` | `3` | Wave oscillation frequency |
+| `waveAmplitude` | `number` | `0.5` | Wave intensity (0-1) |
+
+### Effect Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `effect` | `string` | `'wave'` | Effect type: `'none'`, `'wave'`, or `'twinkle'` |
+| `effectAurora` | `boolean` | `false` | Use aurora colors for effect |
+| `deadzone` | `number` | `0` | Effect dead zone around cursor (0-100) |
+
+### Wave Effect Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `waveSpeed` | `number` | `0.0008` | Diagonal wave speed |
+| `waveWidth` | `number` | `120` | Width of the wave band |
+| `waveChance` | `number` | `0.08` | Chance of a cell sparkling (0-1) |
+| `waveIntensity` | `number` | `1` | Maximum wave brightness |
+| `waveDelayMin` | `number` | `1000` | Minimum delay between waves (ms) |
+| `waveDelayMax` | `number` | `3000` | Maximum delay between waves (ms) |
+| `waveCombineSparkle` | `boolean` | `false` | Combine wave with sparkle effect |
+| `waveSparkleBaseOpacity` | `number` | `0.3` | Base opacity for combined sparkle (0-1) |
+
+### Twinkle Effect Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `twinkleSpeed` | `number` | `50` | Animation speed (10-100) |
+| `twinkleSize` | `number` | `50` | Pattern size (10-100, higher = larger groups) |
+| `twinkleDensity` | `number` | `50` | Star density (0-100, higher = more stars) |
+| `twinkleDeadzone` | `number` | `20` | Center dead zone size (0-50) |
+| `twinkleIntensity` | `number` | `1` | Maximum twinkle brightness |
+| `twinkleMode` | `string` | `'sparkle'` | Twinkle style: `'sparkle'` or `'wave'` |
+| `twinkleCombined` | `boolean` | `false` | Combine with base pattern |
+| `twinkleBaseOpacity` | `number` | `0.3` | Base opacity when combined (0-1) |
+
+### Aurora Color Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `auroraColor1` | `array` | `[0, 255, 128]` | First aurora color (RGB) - Cyan-green |
+| `auroraColor2` | `array` | `[148, 0, 211]` | Second aurora color (RGB) - Violet |
+| `colorScale` | `number` | `0.003` | Color variation scale |
+
+### Collapse Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `collapseSpeed` | `number` | `0.1` | Collapse/expand animation speed |
+| `collapseWaveWidth` | `number` | `0.4` | Width of the collapse transition |
+
+### Animation Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `animateOnHover` | `boolean` | `true` | Only animate when mouse is over document |
+| `autoStart` | `boolean` | `true` | Start animation automatically |
+
+### Callback Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `onShow` | `function` | `null` | Called when show animation completes |
+| `onHide` | `function` | `null` | Called when hide animation completes |
+
+## Examples
+
+### Basic Usage
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <style>
+        body {
+            margin: 0;
+            min-height: 100vh;
+            background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+        }
+    </style>
+</head>
+<body>
+    <script src="borealis.js"></script>
+    <script>
+        const borealis = new Borealis();
+    </script>
+</body>
+</html>
+```
+
+### Twinkle Effect with Aurora Colors
+
+```javascript
+const borealis = new Borealis({
+    effect: 'twinkle',
+    patternAurora: true,
+    effectAurora: true,
+    twinkleSpeed: 70,
+    twinkleDensity: 60,
+    twinkleDeadzone: 25
+});
+```
+
+### Show/Hide on Button Click
+
+```javascript
+const borealis = new Borealis();
+
+document.getElementById('toggleBtn').addEventListener('click', () => {
+    borealis.toggle(() => {
+        console.log('Animation complete');
+    });
+});
+```
+
+### Custom Aurora Colors
+
+```javascript
+const borealis = new Borealis({
+    patternAurora: true,
+    auroraColor1: [255, 100, 100],  // Pink
+    auroraColor2: [100, 100, 255],  // Blue
+});
+```
+
+### Programmatic Control
+
+```javascript
+const borealis = new Borealis({ autoStart: false });
+
+// Start when ready
+setTimeout(() => {
+    borealis.start();
+}, 1000);
+
+// Change effect dynamically
+borealis.setOption('effect', 'twinkle');
+
+// Hide and perform action
+borealis.hide(() => {
+    // Navigate or perform other action
+    window.location.href = '/next-page';
+});
+```
+
+### Inside a Specific Container
+
+```javascript
+const container = document.getElementById('hero-section');
+
+const borealis = new Borealis({
+    container: container,
+    density: 60,
+    effect: 'wave'
+});
+```
+
+## Browser Support
+
+- Chrome 60+
+- Firefox 55+
+- Safari 12+
+- Edge 79+
+
+## Demo Page Features
+
+The included `index.html` demo page provides a comprehensive interface for testing and configuring Borealis:
+
+### Settings Panel
+
+- **Two-column layout** - Organized controls for all options
+- **Live preview** - Changes apply instantly
+- **URL state persistence** - Settings are saved to URL parameters for easy sharing
+- **Copy Code button** - Generate JavaScript initialization code from current settings
+
+### Recording Features
+
+The demo page includes WebM video recording capabilities:
+
+| Feature | Description |
+|---------|-------------|
+| **Format** | WebM with VP9 codec |
+| **Framerate** | 30 fps |
+| **Main Video Bitrate** | 5 Mbps |
+| **Alpha Mask Bitrate** | 3 Mbps |
+| **Resolutions** | 640×360, 854×480, 1280×720, 1440×900, 1920×1080, 2560×1440 |
+| **Durations** | 5s, 10s, 15s, 30s, 60s, 120s |
+
+#### Alpha Mask Export
+
+When "Include Alpha Mask" is enabled, a separate grayscale WebM video is generated alongside the main recording:
+
+- **Purpose**: Luma matte for video compositing
+- **Format**: Grayscale video where white = opaque, black = transparent
+- **Usage**: Import into video editors (After Effects, Premiere, DaVinci Resolve) as a track matte
+- **Filename**: `borealis-alpha-{timestamp}.webm`
+
+Both files share the same timestamp for easy pairing.
+
+### URL State Persistence
+
+All settings are automatically saved to URL parameters. You can:
+
+1. Configure settings using the panel
+2. Copy the URL to share your exact configuration
+3. Open the URL to restore all settings
+
+Example URL:
+```
+index.html?effect=twinkle&patternAurora=true&density=70&twinkleSpeed=60
+```
+
+## Performance Tips
+
+1. **Lower density on mobile** - Use lower density values (30-50) on mobile devices
+2. **Disable on low-power mode** - Consider detecting battery status
+3. **Use `stop()` when hidden** - Stop animation when tab is not visible
+
+```javascript
+document.addEventListener('visibilitychange', () => {
+    if (document.hidden) {
+        borealis.stop();
+    } else {
+        borealis.start();
+    }
+});
+```
+
+## License
+
+MIT License - feel free to use in personal and commercial projects.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.