asciify-engine 1.0.39 → 1.0.41

package/README.md

@@ -4,427 +4,259 @@
   <a href="https://www.npmjs.com/package/asciify-engine"><img src="https://img.shields.io/npm/v/asciify-engine?color=d4ff00&labelColor=0a0a0a&style=flat-square" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/asciify-engine"><img src="https://img.shields.io/npm/dm/asciify-engine?color=d4ff00&labelColor=0a0a0a&style=flat-square" alt="downloads" /></a>
   <a href="https://github.com/ayangabryl/asciify-engine/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-d4ff00?labelColor=0a0a0a&style=flat-square" alt="MIT license" /></a>
-  <a href="https://www.buymeacoffee.com/asciify"><img src="https://img.shields.io/badge/buy_me_a_coffee-support-d4ff00?labelColor=0a0a0a&style=flat-square" alt="Buy Me A Coffee" /></a>
+  <a href="https://www.buymeacoffee.com/asciify"><img src="https://img.shields.io/badge/buy_me_a_coffee-%E2%98%95-d4ff00?labelColor=0a0a0a&style=flat-square" alt="Buy Me A Coffee" /></a>
 </p>
 
-> Convert images, videos, and GIFs into ASCII art on HTML canvas. 13 art styles, 4 color modes, 10 animated backgrounds, interactive hover effects — zero dependencies.
+A framework-agnostic ASCII art rendering engine for the browser. Convert images, animated GIFs, and video into character-based art rendered onto an HTML canvas — with full color support, animated backgrounds, interactive hover effects, and embed generation. Zero runtime dependencies.
 
-**[▶ Live Playground](https://asciify.org) · [npm](https://www.npmjs.com/package/asciify-engine) · [Support the project ☕](https://www.buymeacoffee.com/asciify)**
+**[&#9654; Live Playground](https://asciify.org) &middot; [npm](https://www.npmjs.com/package/asciify-engine)**
 
-## Features
+---
+
+## Overview
 
-- **Media → ASCII** — images, videos, and animated GIFs
-- **13 art styles** — Standard, Blocks, Circles, Braille, Katakana, Dense, and more
-- **4 color modes** — Grayscale, Full Color, Matrix, Accent
-- **14 animated backgrounds** — Wave, Rain, Stars, Pulse, Noise, Grid, Aurora, Silk, Void, Morph, Fire, DNA, Terrain, Circuit
-- **Interactive hover effects** — Spotlight, Flashlight, Magnifier, Force Field, Neon, Fire, Ice, Gravity, Shatter, Ghost
-- **Light & dark mode** — via `colorScheme: 'auto'` or explicit `light` / `dark`
-- **Embed generation** — self-contained HTML output (static or animated)
-- **Zero dependencies** — works with React, Vue, Angular, Svelte, Next.js, or vanilla JS
+asciify-engine works in two stages:
 
-## Install
+1. **Convert** — a source (image, GIF buffer, video element) is sampled and converted into an `AsciiFrame`: a 2D array of character cells, each carrying a character and RGBA color data.
+2. **Render** — the frame is drawn onto a `<canvas>` element via a 2D context, with full support for color modes, font sizes, hover effects, and time-based animations.
+
+This separation means you can pre-compute frames once and render them at any frame rate, making it efficient for both static images and smooth animations.
+
+---
+
+## Installation
 
 ```bash
 npm install asciify-engine
 ```
 
-## Quick Start
+Works with any modern bundler (Vite, webpack, esbuild, Rollup) and any framework — React, Vue, Svelte, Angular, Next.js, or vanilla JS.
 
-### Image → ASCII
+---
 
-```ts
-import { asciify } from 'asciify-engine';
-
-const canvas = document.querySelector('canvas')!;
-
-// Minimal — just a URL and a canvas, no img.onload boilerplate needed
-await asciify('https://example.com/photo.jpg', canvas);
-
-// With an art style preset
-await asciify('photo.jpg', canvas, { artStyle: 'letters' });
-
-// Full control
-await asciify('photo.jpg', canvas, {
-  fontSize: 8,
-  artStyle: 'art',
-  options: {
-    colorMode: 'fullcolor',
-    invert: true,
-    hoverEffect: 'spotlight',
-    hoverStrength: 0.5,
-  },
-});
-```
+## Converting Media to ASCII
 
-> **Canvas sizing:** Set `width` and `height` as HTML attributes on the `<canvas>` element — these control the pixel grid. CSS sizing alone (`style="width:100%"`) won't work (the canvas will be 0×0). Use `canvas.width = el.clientWidth` to fill a container.
+### Images
 
-### Webcam → ASCII
+`imageToAsciiFrame` accepts any `HTMLImageElement`, `HTMLVideoElement`, or `HTMLCanvasElement` and returns a single ASCII frame.
 
 ```ts
-import { asciifyWebcam } from 'asciify-engine';
+import { imageToAsciiFrame, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
 
-const canvas = document.querySelector('canvas')!;
+const img = new Image();
+img.crossOrigin = 'anonymous';
+img.src = 'photo.jpg';
 
-// Requests camera access, starts a live rAF loop, returns stop()
-const stop = await asciifyWebcam(canvas, {
-  artStyle: 'terminal',
-  mirror: true,           // horizontal flip (selfie mode)
-});
+img.onload = () => {
+  const canvas = document.getElementById('ascii') as HTMLCanvasElement;
+  const ctx    = canvas.getContext('2d')!;
+  const opts   = { ...DEFAULT_OPTIONS, fontSize: 10, colorMode: 'fullcolor' as const };
 
-// Release camera + cancel loop
-stop();
+  const { frame } = imageToAsciiFrame(img, opts, canvas.width, canvas.height);
+  renderFrameToCanvas(ctx, frame, opts, canvas.width, canvas.height);
+};
 ```
 
-### GIF Animation
+### Animated GIFs
+
+`gifToAsciiFrames` parses a GIF `ArrayBuffer` and returns one `AsciiFrame` per GIF frame, preserving the original frame rate.
 
 ```ts
-import { asciifyGif } from 'asciify-engine';
+import { gifToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
 
-// Fetches, converts, and starts the animation loop — returns a stop() function
-const stop = await asciifyGif('animation.gif', canvas);
+const buffer = await fetch('animation.gif').then(r => r.arrayBuffer());
+const canvas = document.getElementById('ascii') as HTMLCanvasElement;
+const opts   = { ...DEFAULT_OPTIONS, fontSize: 8 };
 
-// Clean up the animation loop when done
-stop();
+const { frames, fps } = await gifToAsciiFrames(buffer, opts, canvas.width, canvas.height);
+
+let frameIndex = 0;
+setInterval(() => {
+  renderFrameToCanvas(canvas.getContext('2d')!, frames[frameIndex], opts, canvas.width, canvas.height);
+  frameIndex = (frameIndex + 1) % frames.length;
+}, 1000 / fps);
 ```
 
 ### Video
 
-```ts
-import { asciifyVideo } from 'asciify-engine';
-
-// Accepts a URL string or an existing HTMLVideoElement
-const stop = await asciifyVideo('/my-video.mp4', canvas, { artStyle: 'terminal' });
+`videoToAsciiFrames` extracts frames from an `HTMLVideoElement` at a given frame rate and returns the full frame sequence.
 
-// Cancel when unmounting / navigating away
-stop();
-```
-
-### React
+```ts
+import { videoToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
 
-```tsx
-import { useEffect, useRef } from 'react';
-import { asciify } from 'asciify-engine';
+const video = document.createElement('video');
+video.src   = '/clip.mp4';
+video.muted = true;
+await new Promise(r => (video.onloadeddata = r));
 
-export function AsciiImage({ src }: { src: string }) {
-  const ref = useRef<HTMLCanvasElement>(null);
+const canvas = document.getElementById('ascii') as HTMLCanvasElement;
+const opts   = { ...DEFAULT_OPTIONS, fontSize: 8 };
 
-  useEffect(() => {
-    if (ref.current) asciify(src, ref.current, { artStyle: 'art' });
-  }, [src]);
+// videoToAsciiFrames(video, options, width, height, fps?, maxDurationSeconds?)
+const { frames, fps } = await videoToAsciiFrames(video, opts, canvas.width, canvas.height, 12, 10);
 
-  return <canvas ref={ref} width={800} height={600} />;
-}
+let frameIndex = 0;
+setInterval(() => {
+  renderFrameToCanvas(canvas.getContext('2d')!, frames[frameIndex], opts, canvas.width, canvas.height);
+  frameIndex = (frameIndex + 1) % frames.length;
+}, 1000 / fps);
 ```
 
-### Animated GIF or video in React
-
-```tsx
-import { useEffect, useRef } from 'react';
-import { asciifyGif } from 'asciify-engine';
-
-export function AsciiGif({ src }: { src: string }) {
-  const ref = useRef<HTMLCanvasElement>(null);
+---
 
-  useEffect(() => {
-    let stop: (() => void) | undefined;
-    asciifyGif(src, ref.current!).then(fn => { stop = fn; });
-    return () => stop?.();  // cancels the rAF loop on unmount
-  }, [src]);
+## Rendering Options
 
-  return <canvas ref={ref} width={800} height={600} />;
-}
-```
+All conversion and render functions accept an `AsciiOptions` object. Spread `DEFAULT_OPTIONS` as a base and override what you need.
 
-### Vue
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `fontSize` | `number` | `10` | Character cell size in pixels. Smaller values increase density and detail. |
+| `colorMode` | `'grayscale' \| 'fullcolor' \| 'matrix' \| 'accent'` | `'grayscale'` | Determines how pixel color is mapped to character color. |
+| `charset` | `string` | Standard ramp | Characters ordered from dense to sparse, representing brightness levels. |
+| `brightness` | `number` | `0` | Brightness adjustment from `-1` (darker) to `1` (lighter). |
+| `contrast` | `number` | `1` | Contrast multiplier applied before character mapping. |
+| `invert` | `boolean` | `false` | Inverts the luminance mapping — light areas become dense, dark areas sparse. |
+| `renderMode` | `'ascii' \| 'dots'` | `'ascii'` | Render as text characters or circular dot particles. |
+| `hoverEffect` | `string` | `'none'` | Interactive effect driven by cursor position. See hover effects below. |
+| `hoverStrength` | `number` | `0.8` | Effect intensity (0–1). |
+| `hoverRadius` | `number` | `0.3` | Effect radius relative to canvas size (0–1). |
+
+### Color Modes
+
+| Mode | Description |
+|---|---|
+| `grayscale` | Classic monochrome ASCII. Character brightness maps to source luminance. |
+| `fullcolor` | Each character inherits the original pixel color from the source. |
+| `matrix` | Monochrome green — inspired by classic terminal aesthetics. |
+| `accent` | Single accent color applied uniformly across all characters. |
 
-```vue
-<template>
-  <canvas ref="canvasRef" width="800" height="600" />
-</template>
+### Hover Effects
 
-<script setup lang="ts">
-import { useTemplateRef, onMounted } from 'vue';
-import { asciify } from 'asciify-engine';
+Interactive effects that respond to cursor movement. Pass the effect name to `hoverEffect` and supply the cursor position to `renderFrameToCanvas` at render time.
 
-const props = defineProps<{ src: string; artStyle?: string }>();
-const canvasRef = useTemplateRef<HTMLCanvasElement>('canvasRef');
+Available effects: `spotlight` · `flashlight` · `magnifier` · `force-field` · `neon` · `fire` · `ice` · `gravity` · `shatter` · `ghost`
 
-onMounted(() => asciify(props.src, canvasRef.value!, { artStyle: props.artStyle as any }));
-</script>
+```ts
+canvas.addEventListener('mousemove', (e) => {
+  const rect = canvas.getBoundingClientRect();
+  renderFrameToCanvas(ctx, frame, opts, canvas.width, canvas.height, Date.now() / 1000, {
+    x: e.clientX - rect.left,
+    y: e.clientY - rect.top,
+  });
+});
 ```
 
-### Angular
-
-```typescript
-import { Component, ElementRef, ViewChild, AfterViewInit, Input } from '@angular/core';
-import { asciify } from 'asciify-engine';
-
-@Component({
-  selector: 'app-ascii',
-  template: `<canvas #canvas width="800" height="600"></canvas>`,
-})
-export class AsciiComponent implements AfterViewInit {
-  @ViewChild('canvas') canvasRef!: ElementRef<HTMLCanvasElement>;
-  @Input() src = '';
-  @Input() artStyle = 'classic';
-
-  ngAfterViewInit() {
-    asciify(this.src, this.canvasRef.nativeElement, { artStyle: this.artStyle as any });
-  }
-}
-```
+---
 
 ## Animated Backgrounds
 
-Drop a live ASCII animation into any element with one call.
+`asciiBackground` mounts a self-animating ASCII renderer onto any DOM element — ideal for hero sections, banners, or full-page backgrounds. It manages its own canvas, animation loop, and resize handling internally.
 
 ```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' });
+const stop = asciiBackground('#hero', {
+  type: 'rain',
+  colorScheme: 'auto', // follows OS dark/light mode
+  speed: 1.0,
+  density: 0.55,
+  accentColor: '#d4ff00',
+});
 
-// Stop / clean up
-const { destroy } = asciiBackground('#hero', { type: 'stars' });
-destroy();
+// Stop and clean up when no longer needed
+stop();
 ```
 
-### Background Types
+### Available Background Types
 
 | Type | Description |
 |---|---|
-| `wave` | Flowing sine-wave field with noise turbulence |
-| `rain` | Matrix-style vertical column rain with glowing head and fading tail |
+| `wave` | Flowing sine-wave field with layered noise turbulence |
+| `rain` | Vertical column rain with a glowing leading character and fading trail |
 | `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 |
-| `fire` | Upward-drifting flame columns with heat-gradient character mapping |
-| `dna` | Rotating double-helix strands with base-pair characters |
-| `terrain` | Procedural heightmap landscape with parallax depth layers |
-| `circuit` | PCB trace network that pulses with traveling electric signals |
-
-### `asciiBackground` Options
+| `pulse` | Concentric ripple bursts emanating from the cursor |
+| `noise` | Smooth value-noise field with organic, fluid motion |
+| `grid` | Geometric grid that warps and brightens near the cursor |
+| `aurora` | Sweeping borealis-style color bands drifting across the field |
+| `silk` | Fluid swirl simulation following cursor movement |
+| `void` | Gravitational singularity — characters spiral inward toward the cursor |
+| `morph` | Characters morph between shapes over time, driven by noise |
+
+### Background 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 |
+| `type` | `string` | `'wave'` | Which background renderer to use. |
+| `colorScheme` | `'auto' \| 'light' \| 'dark'` | `'dark'` | `'auto'` reacts to OS theme changes in real time. |
+| `fontSize` | `number` | `13` | Character size in pixels. |
+| `speed` | `number` | `1` | Global animation speed multiplier. |
+| `density` | `number` | `0.55` | Fraction of grid cells that are active (0–1). |
+| `accentColor` | `string` | varies | Highlight or leading-character color (any CSS color string). |
+| `color` | `string` | — | Override the body character color. |
 
-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 } from 'asciify-engine';
-
-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();
-```
+## React Integration
 
-## Low-level API
+```tsx
+import { useEffect, useRef } from 'react';
+import { imageToAsciiFrame, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
 
-For cases where the one-call API is too limiting — direct frame manipulation, custom render loops, progress callbacks, etc.
+export function AsciiImage({ src }: { src: string }) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
 
-### GIF (low-level)
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+
+    const img = new Image();
+    img.crossOrigin = 'anonymous';
+    img.src = src;
+    img.onload = () => {
+      const opts = { ...DEFAULT_OPTIONS, fontSize: 10, colorMode: 'fullcolor' as const };
+      const { frame } = imageToAsciiFrame(img, opts, canvas.width, canvas.height);
+      renderFrameToCanvas(canvas.getContext('2d')!, frame, opts, canvas.width, canvas.height);
+    };
+  }, [src]);
 
-```ts
-import { gifToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
+  return <canvas ref={canvasRef} width={800} height={600} />;
+}
+```
 
-const buffer = await fetch('animation.gif').then(r => r.arrayBuffer());
-const options = { ...DEFAULT_OPTIONS, fontSize: 8 };
-const { frames, fps } = await gifToAsciiFrames(buffer, options, canvas.width, canvas.height);
-
-const ctx = canvas.getContext('2d')!;
-let i = 0;
-let last = performance.now();
-const interval = 1000 / fps;
-
-let animId: number;
-const tick = (now: number) => {
-  if (now - last >= interval) {
-    renderFrameToCanvas(ctx, frames[i], options, canvas.width, canvas.height);
-    i = (i + 1) % frames.length;
-    last = now;
-  }
-  animId = requestAnimationFrame(tick);
-};
-animId = requestAnimationFrame(tick);
+---
 
-// Clean up → cancelAnimationFrame(animId);
-```
+## Embed Generation
 
-### Video (low-level)
+Generate self-contained HTML that can be hosted anywhere or dropped directly into a page — no runtime dependency required.
 
 ```ts
-import { videoToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
+import { generateEmbedCode, generateAnimatedEmbedCode } from 'asciify-engine';
 
-const video = document.createElement('video');
-video.crossOrigin = 'anonymous';
-video.src = '/my-video.mp4';
-// Guard against cached video where onloadeddata already fired
-if (video.readyState < 2) {
-  await new Promise<void>(r => { video.onloadeddata = () => r(); });
-}
+// Static — produces a single-file HTML with the ASCII art baked in
+const staticHtml = generateEmbedCode(frame, options);
 
-const options = { ...DEFAULT_OPTIONS, fontSize: 8 };
-const { frames, fps } = await videoToAsciiFrames(video, options, canvas.width, canvas.height, 12, 10);
-
-const ctx = canvas.getContext('2d')!;
-let i = 0;
-let last = performance.now();
-const interval = 1000 / fps;
-
-let animId: number;
-const tick = (now: number) => {
-  if (now - last >= interval) {
-    renderFrameToCanvas(ctx, frames[i], options, canvas.width, canvas.height);
-    i = (i + 1) % frames.length;
-    last = now;
-  }
-  animId = requestAnimationFrame(tick);
-};
-animId = requestAnimationFrame(tick);
-
-// Clean up → cancelAnimationFrame(animId);
+// Animated — produces a self-running HTML animation
+const animatedHtml = generateAnimatedEmbedCode(frames, options, fps);
 ```
 
-### Vanilla JS (low-level image)
-
-```html
-<canvas id="ascii" width="800" height="600"></canvas>
-<script type="module">
-  import { imageToAsciiFrame, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
-
-  const canvas = document.getElementById('ascii');
-  const ctx = canvas.getContext('2d');
-  const options = { ...DEFAULT_OPTIONS, fontSize: 10 };
-
-  const img = new Image();
-  img.crossOrigin = 'anonymous';
-  img.src = 'https://picsum.photos/600/400';
-  img.onload = () => {
-    const { frame } = imageToAsciiFrame(img, options, canvas.width, canvas.height);
-    renderFrameToCanvas(ctx, frame, options, canvas.width, canvas.height);
-  };
-</script>
-```
+---
 
 ## API Reference
 
-### Core Functions
-
-| Function | Returns | Description |
-|---|---|---|
-| `asciify(source, canvas, opts?)` | `Promise<void>` | Render a **single** ASCII frame from an image (or URL). For animated loops use `asciifyGif` / `asciifyVideo` |
-| `asciifyGif(source, canvas, opts?)` | `Promise<() => void>` | Fetch a GIF, convert, and start an animation loop — returns `stop()` |
-| `asciifyVideo(source, canvas, opts?)` | `Promise<() => void>` | Convert a video and start an animation loop — returns `stop()` |
-| `imageToAsciiFrame(source, options, w?, h?)` | `{ frame, cols, rows }` | Convert an image, video frame, or canvas to a raw ASCII frame |
-| `renderFrameToCanvas(ctx, frame, options, w, h, time?, hoverPos?)` | `void` | Render a raw ASCII frame to a 2D canvas context |
-| `gifToAsciiFrames(buffer, options, w, h, onProgress?)` | `{ frames, cols, rows, fps }` | Parse an animated GIF `ArrayBuffer` into ASCII frames |
-| `videoToAsciiFrames(video, options, w, h, fps?, maxDuration?, onProgress?)` | `{ frames, cols, rows, fps }` | Extract and convert video frames to ASCII |
-| `asciifyWebcam(canvas, opts?)` | `Promise<() => void>` | Start a live webcam → ASCII loop; returns `stop()` to cancel and release the camera |
-| `asciiBackground(target, options)` | `{ destroy: () => void }` | Mount a live animated ASCII background; call `destroy()` to stop and remove |
-| `generateEmbedCode(frame, options)` | `string` | Self-contained static HTML embed |
-| `generateAnimatedEmbedCode(frames, options, fps)` | `string` | Self-contained animated HTML embed |
-
-### Simple API Options (`AsciifySimpleOptions`)
-
-Used by `asciify()`, `asciifyGif()`, and `asciifyVideo()`:
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `fontSize` | `number` | `10` | Character cell size in px |
-| `artStyle` | `ArtStyle` | `'classic'` | Art style preset — sets charset, render mode, and color mode together |
-| `options` | `Partial<AsciiOptions>` | `{}` | Fine-grained overrides applied on top of the preset |
-
-### Key Options (`AsciiOptions`)
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `fontSize` | `number` | `10` | Character cell size in px |
-| `colorMode` | `'grayscale' \| 'fullcolor' \| 'matrix' \| 'accent'` | `'grayscale'` | Color output mode |
-| `renderMode` | `'ascii' \| 'dots'` | `'ascii'` | Render as characters or dot particles |
-| `charset` | `string` | `' .:-=+*#%@'` | Custom character density ramp (light → dark) |
-| `brightness` | `number` | `0` | Brightness adjustment (−1 → 0 → 1) |
-| `contrast` | `number` | `0` | Contrast boost (0 = unchanged, positive = more contrast) |
-| `invert` | `boolean` | `false` | Invert luminance mapping |
-| `animationStyle` | `AnimationStyle` | `'none'` | Per-character animation driven over time |
-| `hoverEffect` | `HoverEffect` | `'spotlight'` | Cursor interaction style |
-| `hoverStrength` | `number` | `0` | Effect intensity (0 = disabled) |
-| `hoverRadius` | `number` | `0.2` | Effect radius as a fraction of canvas size |
-| `artStyle` | `ArtStyle` | `'classic'` | Art style preset (see `ART_STYLE_PRESETS`) |
-| `ditherStrength` | `number` | `0` | Floyd-Steinberg dither intensity (0–1) |
-| `dotSizeRatio` | `number` | `0.8` | Dot size when `renderMode === 'dots'` (fraction of cell) |
-| `charAspect` | `number` | `0.55` | Width ÷ height of a single output character. Set to `0.5` for terminal emulators, `0.52` for browser `line-height: 1.15`, `0.55` for `line-height: 1.09`. Ensuring this matches your rendering environment keeps the output proportional to the source. |
-| `normalize` | `boolean` | `false` | Auto-stretch the luminance range of the frame before charset mapping. Maximises detail and contrast for low-contrast or muted images. |
-
-### Art Styles (`artStyle`)
-
-| Value | Color mode | Description |
+| Function | Signature | Returns |
 |---|---|---|
-| `classic` | Grayscale | Standard density ramp — clean, universally readable |
-| `art` | Full color | 70-char dense ramp for maximum tonal detail |
-| `particles` | Full color | Dot circles (`renderMode: 'dots'`) — great for photos |
-| `letters` | Full color | Alphabet characters with pixel-accurate color |
-| `terminal` | Matrix | Classic charset with green phosphor / Matrix look |
-| `claudeCode` | Accent | Box-drawing chars with accent color — technical/hacker aesthetic |
-| `braille` | Full color | 256-char braille block — ultra-dense, printed feel |
-| `katakana` | Matrix | Half-width katakana — anime / cyberpunk aesthetic |
-| `box` | Grayscale | Filled block elements `▪◾◼■█` |
-| `lines` | Grayscale | Dash/em-dash ramp — minimalist typographic look |
-| `circles` | Accent | Concentric circle chars with accent highlight |
-| `musical` | Accent | Music notation ♩♪♫♬♭♮♯ — playful, low density |
-| `emoji` | Full color | Block emoji mosaic — best at larger `fontSize` |
+| `imageToAsciiFrame` | `(source, options, w?, h?)` | `{ frame, cols, rows }` |
+| `renderFrameToCanvas` | `(ctx, frame, options, w, h, time?, hoverPos?)` | `void` |
+| `gifToAsciiFrames` | `(buffer, options, w, h, onProgress?)` | `Promise<{ frames, cols, rows, fps }>` |
+| `videoToAsciiFrames` | `(video, options, w, h, fps?, maxSec?, onProgress?)` | `Promise<{ frames, cols, rows, fps }>` |
+| `asciiBackground` | `(selector, options)` | `() => void` (cleanup) |
+| `generateEmbedCode` | `(frame, options)` | `string` |
+| `generateAnimatedEmbedCode` | `(frames, options, fps)` | `string` |
 
-### Background Options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `type` | `string` | `'wave'` | Background renderer |
-| `colorScheme` | `'auto' \| 'light' \| 'dark'` | `'dark'` | Theme; `'auto'` follows OS preference |
-| `fontSize` | `number` | `13` | Character size |
-| `speed` | `number` | `1` | Animation speed multiplier |
-| `density` | `number` | `0.55` | Fraction of cells active (0–1) |
-| `accentColor` | `string` | varies | Highlight / head colour |
+---
 
 ## License
 
 MIT © [asciify.org](https://asciify.org)
 
----
-
-<p align="left">
-  <a href="https://www.buymeacoffee.com/asciify">☕ Buy me a coffee — if this saved you time, I'd appreciate it!</a>
-</p>
+> ☕ [Buy me a coffee](https://www.buymeacoffee.com/asciify) — if this saved you time, I'd appreciate it!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciify-engine",
-  "version": "1.0.39",
+  "version": "1.0.41",
   "description": "Framework-agnostic ASCII art engine. Convert images, videos, and GIFs into ASCII art rendered on canvas.",
   "type": "module",
   "main": "./dist/index.cjs",