asciify-engine 1.0.20 → 1.0.22

package/README.md

@@ -1,6 +1,6 @@
 # asciify-engine
 
-Framework-agnostic ASCII art engine. Convert images, videos, and GIFs into ASCII art rendered on HTML canvas.
+Framework-agnostic ASCII art engine. Convert images, videos, and GIFs into ASCII art rendered on HTML canvas — plus 10 animated ASCII background effects.
 
 ## Features
 
@@ -11,6 +11,8 @@ Framework-agnostic ASCII art engine. Convert images, videos, and GIFs into ASCII
 - **6 art styles** — Classic, Particles, Letters, Box Drawing, Dense Art, Terminal
 - **Color modes** — Grayscale, Full Color, Matrix, Accent
 - **Hover effects** — Spotlight, Magnify, Repel, Glow, Color Shift
+- **10 animated backgrounds** — Wave, Rain, Stars, Pulse, Noise, Grid, Aurora, Silk, Void, Morph
+- **Light & dark mode** — all backgrounds adapt via `lightMode` option or `colorScheme: 'auto'`
 - **Embed code generation** — self-contained HTML output
 - **Zero framework dependencies** — works with React, Angular, Vue, Svelte, vanilla JS
 
@@ -20,6 +22,92 @@ Framework-agnostic ASCII art engine. Convert images, videos, and GIFs into ASCII
 npm install asciify-engine
 ```
 
+## Animated Backgrounds
+
+Drop a live ASCII animation into any element with one call.
+
+```ts
+import { asciiBackground } from 'asciify-engine';
+
+// Attach to any selector — animates the element's background
+asciiBackground('#hero', { type: 'rain' });
+
+// Follows OS dark/light mode automatically
+asciiBackground('#hero', { type: 'aurora', colorScheme: 'auto' });
+
+// Force light mode (dark characters on light background)
+asciiBackground('#hero', { type: 'wave', colorScheme: 'light' });
+
+// Stop / clean up
+const stop = asciiBackground('#hero', { type: 'stars' });
+stop();
+```
+
+### Background Types
+
+| Type | Description |
+|---|---|
+| `wave` | Flowing sine-wave field with noise turbulence |
+| `rain` | Matrix-style vertical column rain with glowing head and fading tail |
+| `stars` | Parallax star field that reacts to cursor position |
+| `pulse` | Concentric ripple bursts that emanate from the cursor |
+| `noise` | Smooth value-noise field with organic flow |
+| `grid` | Geometric grid that warps and glows at cursor proximity |
+| `aurora` | Sweeping borealis-style colour bands |
+| `silk` | Silky fluid swirls following the cursor |
+| `void` | Gravitational singularity — characters spiral inward toward cursor |
+| `morph` | Characters morph between shapes driven by noise |
+
+### `asciiBackground` Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `type` | `string` | `'wave'` | Which background renderer to use |
+| `colorScheme` | `'auto' \| 'light' \| 'dark'` | `'dark'` | `'auto'` follows OS theme live; `'light'` = dark chars on light bg |
+| `fontSize` | `number` | `13` | Character size in px |
+| `accentColor` | `string` | varies | Head/highlight colour (CSS colour string) |
+| `color` | `string` | — | Override body character colour |
+| `speed` | `number` | `1` | Global animation speed multiplier |
+| `density` | `number` | `0.55` | Fraction of cells active (0–1) |
+| `lightMode` | `boolean` | `false` | Dark characters on light background |
+
+Each background type also accepts its own specific options — see the individual type exports (e.g. `RainBackgroundOptions`, `WaveBackgroundOptions`, etc.) for the full list.
+
+### Low-level background renderers
+
+All renderers are also exported individually for direct canvas use:
+
+```ts
+import {
+  renderRainBackground,
+  renderWaveBackground,
+  renderStarsBackground,
+  renderPulseBackground,
+  renderNoiseBackground,
+  renderGridBackground,
+  renderAuroraBackground,
+  renderSilkBackground,
+  renderVoidBackground,
+  renderMorphBackground,
+} from 'asciify-engine';
+
+// Example: drive the rain renderer yourself
+const canvas = document.getElementById('canvas') as HTMLCanvasElement;
+const ctx = canvas.getContext('2d')!;
+let t = 0;
+function tick() {
+  renderRainBackground(ctx, canvas.width, canvas.height, t, {
+    speed: 1.2,
+    density: 0.6,
+    accentColor: '#00ffcc',
+    lightMode: false,
+  });
+  t += 0.016;
+  requestAnimationFrame(tick);
+}
+tick();
+```
+
 ## Quick Start
 
 ### Vanilla JS
@@ -31,7 +119,6 @@ npm install asciify-engine
     imageToAsciiFrame,
     renderFrameToCanvas,
     DEFAULT_OPTIONS,
-    ART_STYLE_PRESETS,
   } from 'asciify-engine';
 
   const img = new Image();
@@ -39,10 +126,8 @@ npm install asciify-engine
   img.src = 'https://picsum.photos/600/400';
   img.onload = () => {
     const canvas = document.getElementById('ascii');
-    const options = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS.classic, fontSize: 10 };
-    const cols = Math.floor(canvas.width / options.fontSize);
-    const rows = Math.floor(canvas.height / (options.fontSize * 1.8));
-    const frame = imageToAsciiFrame(img, options, cols, rows);
+    const options = { ...DEFAULT_OPTIONS, fontSize: 10 };
+    const { frame } = imageToAsciiFrame(img, options, canvas.width, canvas.height);
     renderFrameToCanvas(canvas.getContext('2d'), frame, options, canvas.width, canvas.height);
   };
 </script>
@@ -56,11 +141,9 @@ import {
   imageToAsciiFrame,
   renderFrameToCanvas,
   DEFAULT_OPTIONS,
-  ART_STYLE_PRESETS,
-  type ArtStyle,
 } from 'asciify-engine';
 
-export function AsciiImage({ src, style = 'classic' }: { src: string; style?: ArtStyle }) {
+export function AsciiImage({ src }: { src: string }) {
   const ref = useRef<HTMLCanvasElement>(null);
 
   useEffect(() => {
@@ -69,13 +152,11 @@ export function AsciiImage({ src, style = 'classic' }: { src: string; style?: Ar
     img.src = src;
     img.onload = () => {
       const canvas = ref.current!;
-      const opts = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[style], fontSize: 10 };
-      const cols = Math.floor(canvas.width / opts.fontSize);
-      const rows = Math.floor(canvas.height / (opts.fontSize * 1.8));
-      const frame = imageToAsciiFrame(img, opts, cols, rows);
+      const opts = { ...DEFAULT_OPTIONS, fontSize: 10 };
+      const { frame } = imageToAsciiFrame(img, opts, canvas.width, canvas.height);
       renderFrameToCanvas(canvas.getContext('2d')!, frame, opts, canvas.width, canvas.height);
     };
-  }, [src, style]);
+  }, [src]);
 
   return <canvas ref={ref} width={800} height={600} />;
 }
@@ -84,12 +165,11 @@ export function AsciiImage({ src, style = 'classic' }: { src: string; style?: Ar
 ### Angular
 
 ```typescript
-import { Component, ElementRef, Input, ViewChild, AfterViewInit } from '@angular/core';
+import { Component, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
 import {
   imageToAsciiFrame,
   renderFrameToCanvas,
   DEFAULT_OPTIONS,
-  ART_STYLE_PRESETS,
 } from 'asciify-engine';
 
 @Component({
@@ -98,19 +178,15 @@ import {
 })
 export class AsciiComponent implements AfterViewInit {
   @ViewChild('canvas') canvasRef!: ElementRef<HTMLCanvasElement>;
-  @Input() src!: string;
-  @Input() artStyle = 'classic';
 
   ngAfterViewInit() {
     const img = new Image();
     img.crossOrigin = 'anonymous';
-    img.src = this.src;
+    img.src = 'https://picsum.photos/600/400';
     img.onload = () => {
       const canvas = this.canvasRef.nativeElement;
-      const opts = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[this.artStyle], fontSize: 10 };
-      const cols = Math.floor(canvas.width / opts.fontSize);
-      const rows = Math.floor(canvas.height / (opts.fontSize * 1.8));
-      const frame = imageToAsciiFrame(img, opts, cols, rows);
+      const opts = { ...DEFAULT_OPTIONS, fontSize: 10 };
+      const { frame } = imageToAsciiFrame(img, opts, canvas.width, canvas.height);
       renderFrameToCanvas(canvas.getContext('2d')!, frame, opts, canvas.width, canvas.height);
     };
   }
@@ -128,10 +204,8 @@ const buffer = await response.arrayBuffer();
 const canvas = document.getElementById('ascii') as HTMLCanvasElement;
 const ctx = canvas.getContext('2d')!;
 const options = { ...DEFAULT_OPTIONS, fontSize: 8 };
-const cols = Math.floor(canvas.width / options.fontSize);
-const rows = Math.floor(canvas.height / (options.fontSize * 1.8));
 
-const { frames, fps } = await gifToAsciiFrames(buffer, options, cols, rows);
+const { frames, fps } = await gifToAsciiFrames(buffer, options, canvas.width, canvas.height);
 
 let i = 0;
 setInterval(() => {
@@ -150,31 +224,31 @@ video.crossOrigin = 'anonymous';
 video.src = '/my-video.mp4';
 await new Promise((r) => (video.onloadeddata = r));
 
+const canvas = document.getElementById('ascii') as HTMLCanvasElement;
 const options = { ...DEFAULT_OPTIONS, fontSize: 8 };
-const cols = 120;
-const rows = 50;
-const { frames, fps } = await videoToAsciiFrames(video, options, cols, rows, 10, 6);
+
+const { frames, fps } = await videoToAsciiFrames(video, options, canvas.width, canvas.height, 12, 10);
 
 let i = 0;
 setInterval(() => {
-  const ctx = document.getElementById('ascii').getContext('2d');
-  renderFrameToCanvas(ctx, frames[i], options, 800, 600);
+  renderFrameToCanvas(canvas.getContext('2d')!, frames[i], options, canvas.width, canvas.height);
   i = (i + 1) % frames.length;
 }, 1000 / fps);
 ```
 
 ## API
 
-### Functions
+### Core Functions
 
 | Function | Description |
 |---|---|
-| `imageToAsciiFrame(img, options, cols, rows)` | Convert an image element to a single ASCII frame |
-| `renderFrameToCanvas(ctx, frame, options, width, height)` | Render an ASCII frame onto a canvas context |
-| `gifToAsciiFrames(buffer, options, cols, rows, onProgress?)` | Convert a GIF `ArrayBuffer` to animated frames |
-| `videoToAsciiFrames(video, options, cols, rows, fps, maxDuration, onProgress?)` | Convert a `<video>` to animated frames |
+| `imageToAsciiFrame(source, options, targetWidth?, targetHeight?)` | Convert an image/video/canvas to a single ASCII frame; returns `{ frame, cols, rows }` |
+| `renderFrameToCanvas(ctx, frame, options, width, height, time?, hoverPos?)` | Render an ASCII frame onto a canvas context |
+| `gifToAsciiFrames(buffer, options, targetWidth, targetHeight, onProgress?)` | Convert a GIF `ArrayBuffer` to animated frames; returns `{ frames, cols, rows, fps }` |
+| `videoToAsciiFrames(video, options, targetWidth, targetHeight, fps?, maxDuration?, onProgress?)` | Convert a `<video>` to animated frames; returns `{ frames, cols, rows, fps }` |
 | `generateEmbedCode(frame, options)` | Generate self-contained HTML embed string |
 | `generateAnimatedEmbedCode(frames, options, fps)` | Generate animated HTML embed string |
+| `asciiBackground(selector, options)` | Mount an animated ASCII background on an element; returns a cleanup function |
 
 ### Art Styles
 

package/dist/index.cjs

@@ -374,7 +374,7 @@ function lerp(a, b, t) {
 function hash2(ix, iy) {
   let n = ix * 127 + iy * 311;
   n = n >> 13 ^ n;
-  return (n * (n * n * 15731 + 789221) + 1376312589 & 2147483647) / 1073741823 - 1;
+  return (n * (n * n * 15731 + 789221) + 1376312589 & 2147483647) / 2147483647;
 }
 function vnoise(x, y) {
   const ix = Math.floor(x), iy = Math.floor(y);