asciify-engine 1.0.21 → 1.0.23

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

@@ -398,7 +398,7 @@ function renderWaveBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
     lineHeightRatio = 1.4,
     chars = " .:-=+*#%@",
     baseColor = null,
-    accentColor = "#d4ff00",
+    accentColor = void 0,
     accentThreshold = 0.52,
     mouseInfluence = 0.55,
     mouseFalloff = 2.8,
@@ -408,6 +408,7 @@ function renderWaveBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
     breathe = true,
     lightMode = false
   } = options;
+  const resolvedAccent = accentColor ?? (lightMode ? "#6b8700" : "#d4ff00");
   const charW = fontSize * charAspect;
   const lineH = fontSize * lineHeightRatio;
   const cols = Math.ceil(width / charW);
@@ -415,8 +416,8 @@ function renderWaveBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
   const mx = mousePos.x;
   const my = mousePos.y;
   let acR = 212, acG = 255, acB = 0;
-  if (accentColor) {
-    const hex = accentColor.replace("#", "");
+  {
+    const hex = resolvedAccent.replace("#", "");
     if (hex.length === 6) {
       acR = parseInt(hex.slice(0, 2), 16);
       acG = parseInt(hex.slice(2, 4), 16);
@@ -1026,13 +1027,14 @@ function renderRainBackground(ctx, width, height, time, options = {}) {
   const {
     fontSize = 13,
     chars = "0123456789ABCDEF@#$&*+=/<>",
-    accentColor = "#d4ff00",
+    accentColor = void 0,
     color,
     speed = 1,
     density = 0.55,
     tailLength = 14,
     lightMode = false
   } = options;
+  const resolvedAccent = accentColor ?? (lightMode ? "#6b8700" : "#d4ff00");
   const charW = fontSize * 0.62;
   const lineH = fontSize * 1.4;
   const cols = Math.ceil(width / charW);
@@ -1055,7 +1057,7 @@ function renderRainBackground(ctx, width, height, time, options = {}) {
     }
   }
   let acR = 212, acG = 255, acB = 0;
-  const ap = parseColor(accentColor);
+  const ap = parseColor(resolvedAccent);
   if (ap) {
     acR = ap.r;
     acG = ap.g;
@@ -1091,12 +1093,13 @@ function renderStarsBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
   const {
     fontSize = 14,
     chars = " . \xB7 * + \xB0 \u2605",
-    accentColor = "#d4ff00",
+    accentColor = void 0,
     color,
     speed = 1,
     count = 180,
     lightMode = false
   } = options;
+  const resolvedAccent = accentColor ?? (lightMode ? "#6b8700" : "#d4ff00");
   ctx.clearRect(0, 0, width, height);
   ctx.textBaseline = "middle";
   ctx.textAlign = "center";
@@ -1118,7 +1121,7 @@ function renderStarsBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
     }
   }
   let acR = 212, acG = 255, acB = 0;
-  const ap = parseColor(accentColor);
+  const ap = parseColor(resolvedAccent);
   if (ap) {
     acR = ap.r;
     acG = ap.g;
@@ -1151,13 +1154,14 @@ function renderPulseBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
   const {
     fontSize = 14,
     chars = ". \xB7 \u25CB \u25CE \u25CF",
-    accentColor = "#00ffcc",
+    accentColor = void 0,
     color,
     rings = 5,
     speed = 1,
     sharpness = 4,
     lightMode = false
   } = options;
+  const resolvedAccent = accentColor ?? (lightMode ? "#007a5e" : "#00ffcc");
   ctx.clearRect(0, 0, width, height);
   ctx.textBaseline = "middle";
   ctx.textAlign = "center";
@@ -1179,7 +1183,7 @@ function renderPulseBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
     }
   }
   let acR = 0, acG = 255, acB = 204;
-  const ap = parseColor(accentColor);
+  const ap = parseColor(resolvedAccent);
   if (ap) {
     acR = ap.r;
     acG = ap.g;
@@ -1224,7 +1228,7 @@ function renderNoiseBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
   const {
     fontSize = 14,
     chars = " .\xB7:;=+*#%@\u2591\u2592\u2593",
-    accentColor = "#d4ff00",
+    accentColor = void 0,
     color,
     octaves = 4,
     speed = 1,
@@ -1233,6 +1237,7 @@ function renderNoiseBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
     mouseWarp = 0.3,
     lightMode = false
   } = options;
+  const resolvedAccent = accentColor ?? (lightMode ? "#6b8700" : "#d4ff00");
   const charW = fontSize * 0.62;
   const lineH = fontSize * 1.4;
   const cols = Math.ceil(width / charW);
@@ -1255,7 +1260,7 @@ function renderNoiseBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
     }
   }
   let acR = 212, acG = 255, acB = 0;
-  const ap = parseColor(accentColor);
+  const ap = parseColor(resolvedAccent);
   if (ap) {
     acR = ap.r;
     acG = ap.g;
@@ -1303,7 +1308,7 @@ function renderGridBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
   const {
     fontSize = 12,
     chars = "\xB7-=+|/",
-    accentColor = "#d4ff00",
+    accentColor = void 0,
     color,
     bands = 3,
     speed = 1,
@@ -1311,6 +1316,7 @@ function renderGridBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
     glitch = true,
     lightMode = false
   } = options;
+  const resolvedAccent = accentColor ?? (lightMode ? "#6b8700" : "#d4ff00");
   const charW = fontSize * 0.62;
   const lineH = fontSize * 1.4;
   const cols = Math.ceil(width / charW);
@@ -1333,7 +1339,7 @@ function renderGridBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
     }
   }
   let acR = 212, acG = 255, acB = 0;
-  const ap = parseColor(accentColor);
+  const ap = parseColor(resolvedAccent);
   if (ap) {
     acR = ap.r;
     acG = ap.g;
@@ -1375,13 +1381,14 @@ function renderAuroraBackground(ctx, width, height, time, mousePos = { x: 0.5, y
     fontSize = 14,
     chars = " \xB7\u2219\u2022:;+=\u2261\u2263#@",
     color,
-    accentColor = "#d4ff00",
+    accentColor = void 0,
     speed = 1,
     layers = 5,
     softness = 1.2,
     mouseRipple = 0.2,
     lightMode = false
   } = options;
+  const resolvedAccent = accentColor ?? (lightMode ? "#6b8700" : "#d4ff00");
   const charW = fontSize * 0.62;
   const lineH = fontSize * 1.4;
   const cols = Math.ceil(width / charW);
@@ -1404,7 +1411,7 @@ function renderAuroraBackground(ctx, width, height, time, mousePos = { x: 0.5, y
     }
   }
   let acR = 212, acG = 255, acB = 0;
-  const ap = parseColor(accentColor);
+  const ap = parseColor(resolvedAccent);
   if (ap) {
     acR = ap.r;
     acG = ap.g;
@@ -1460,12 +1467,13 @@ function renderSilkBackground(ctx, width, height, time, options = {}) {
   const {
     fontSize = 13,
     color,
-    accentColor = "#d4ff00",
+    accentColor = void 0,
     speed = 0.4,
     layers = 4,
     turbulence = 0.8,
     lightMode = false
   } = options;
+  const resolvedAccent = accentColor ?? (lightMode ? "#6b8700" : "#d4ff00");
   const charW = fontSize * 0.62;
   const lineH = fontSize * 1.4;
   const cols = Math.ceil(width / charW);
@@ -1488,7 +1496,7 @@ function renderSilkBackground(ctx, width, height, time, options = {}) {
     }
   }
   let acR = 212, acG = 255, acB = 0;
-  const ap = parseColor(accentColor);
+  const ap = parseColor(resolvedAccent);
   if (ap) {
     acR = ap.r;
     acG = ap.g;
@@ -1535,12 +1543,13 @@ function renderVoidBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
     fontSize = 13,
     chars = " \xB7:;=+*#%@",
     color,
-    accentColor = "#d4ff00",
+    accentColor = void 0,
     speed = 1,
     radius = 0.38,
     swirl = 3,
     lightMode = false
   } = options;
+  const resolvedAccent = accentColor ?? (lightMode ? "#6b8700" : "#d4ff00");
   const charW = fontSize * 0.62;
   const lineH = fontSize * 1.4;
   const cols = Math.ceil(width / charW);
@@ -1564,7 +1573,7 @@ function renderVoidBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
     }
   }
   let acR = 212, acG = 255, acB = 0;
-  const ap = parseColor(accentColor);
+  const ap = parseColor(resolvedAccent);
   if (ap) {
     acR = ap.r;
     acG = ap.g;
@@ -1608,11 +1617,12 @@ function renderMorphBackground(ctx, width, height, time, options = {}) {
     fontSize = 14,
     chars = " \xB7\u2219\u2022:-=+*#",
     color,
-    accentColor = "#d4ff00",
+    accentColor = void 0,
     speed = 0.5,
     harmonics = 3,
     lightMode = false
   } = options;
+  const resolvedAccent = accentColor ?? (lightMode ? "#6b8700" : "#d4ff00");
   const charW = fontSize * 0.62;
   const lineH = fontSize * 1.4;
   const cols = Math.ceil(width / charW);
@@ -1635,7 +1645,7 @@ function renderMorphBackground(ctx, width, height, time, options = {}) {
     }
   }
   let acR = 212, acG = 255, acB = 0;
-  const ap = parseColor(accentColor);
+  const ap = parseColor(resolvedAccent);
   if (ap) {
     acR = ap.r;
     acG = ap.g;