asciify-engine 1.0.34 → 1.0.36

package/README.md

@@ -28,6 +28,133 @@
 npm install asciify-engine
 ```
 
+## Quick Start
+
+### 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,
+  },
+});
+```
+
+### GIF Animation
+
+```ts
+import { asciifyGif } from 'asciify-engine';
+
+// Fetches, converts, and starts the animation loop — returns a stop() function
+const stop = await asciifyGif('animation.gif', canvas);
+
+// Clean up the animation loop when done
+stop();
+```
+
+### 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' });
+
+// Cancel when unmounting / navigating away
+stop();
+```
+
+### React
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { asciify } from 'asciify-engine';
+
+export function AsciiImage({ src }: { src: string }) {
+  const ref = useRef<HTMLCanvasElement>(null);
+
+  useEffect(() => {
+    if (ref.current) asciify(src, ref.current, { artStyle: 'art' });
+  }, [src]);
+
+  return <canvas ref={ref} width={800} height={600} />;
+}
+```
+
+### 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]);
+
+  return <canvas ref={ref} width={800} height={600} />;
+}
+```
+
+### Vue
+
+```vue
+<template>
+  <canvas ref="canvasRef" width="800" height="600" />
+</template>
+
+<script setup lang="ts">
+import { useTemplateRef, onMounted } from 'vue';
+import { asciify } from 'asciify-engine';
+
+const props = defineProps<{ src: string; artStyle?: string }>();
+const canvasRef = useTemplateRef<HTMLCanvasElement>('canvasRef');
+
+onMounted(() => asciify(props.src, canvasRef.value!, { artStyle: props.artStyle as any }));
+</script>
+```
+
+### 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.
@@ -84,23 +211,12 @@ Each background type also accepts its own specific options — see the individua
 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
+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,
@@ -114,113 +230,39 @@ function tick() {
 tick();
 ```
 
-## Quick Start
-
-### Vanilla JS
-
-```html
-<canvas id="ascii" width="800" height="600"></canvas>
-<script type="module">
-  import {
-    imageToAsciiFrame,
-    renderFrameToCanvas,
-    DEFAULT_OPTIONS,
-  } from 'asciify-engine';
-
-  const img = new Image();
-  img.crossOrigin = 'anonymous';
-  img.src = 'https://picsum.photos/600/400';
-  img.onload = () => {
-    const canvas = document.getElementById('ascii');
-    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>
-```
-
-### React
-
-```tsx
-import { useEffect, useRef } from 'react';
-import {
-  imageToAsciiFrame,
-  renderFrameToCanvas,
-  DEFAULT_OPTIONS,
-} from 'asciify-engine';
-
-export function AsciiImage({ src }: { src: string }) {
-  const ref = useRef<HTMLCanvasElement>(null);
-
-  useEffect(() => {
-    const img = new Image();
-    img.crossOrigin = 'anonymous';
-    img.src = src;
-    img.onload = () => {
-      const canvas = ref.current!;
-      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]);
-
-  return <canvas ref={ref} width={800} height={600} />;
-}
-```
-
-### Angular
-
-```typescript
-import { Component, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
-import {
-  imageToAsciiFrame,
-  renderFrameToCanvas,
-  DEFAULT_OPTIONS,
-} 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>;
+## Low-level API
 
-  ngAfterViewInit() {
-    const img = new Image();
-    img.crossOrigin = 'anonymous';
-    img.src = 'https://picsum.photos/600/400';
-    img.onload = () => {
-      const canvas = this.canvasRef.nativeElement;
-      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);
-    };
-  }
-}
-```
+For cases where the one-call API is too limiting — direct frame manipulation, custom render loops, progress callbacks, etc.
 
-### GIF Animation
+### GIF (low-level)
 
 ```ts
 import { gifToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
 
-const response = await fetch('https://media.giphy.com/media/ENagATV1Gr9eg/giphy.gif');
-const buffer = await response.arrayBuffer();
-
-const canvas = document.getElementById('ascii') as HTMLCanvasElement;
-const ctx = canvas.getContext('2d')!;
+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;
-setInterval(() => {
-  renderFrameToCanvas(ctx, frames[i], options, canvas.width, canvas.height);
-  i = (i + 1) % frames.length;
-}, 1000 / fps);
+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);
 ```
 
-### Video
+### Video (low-level)
 
 ```ts
 import { videoToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
@@ -228,18 +270,52 @@ import { videoToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciif
 const video = document.createElement('video');
 video.crossOrigin = 'anonymous';
 video.src = '/my-video.mp4';
-await new Promise((r) => (video.onloadeddata = r));
+// Guard against cached video where onloadeddata already fired
+if (video.readyState < 2) {
+  await new Promise<void>(r => { video.onloadeddata = () => r(); });
+}
 
-const canvas = document.getElementById('ascii') as HTMLCanvasElement;
 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;
-setInterval(() => {
-  renderFrameToCanvas(canvas.getContext('2d')!, frames[i], options, canvas.width, canvas.height);
-  i = (i + 1) % frames.length;
-}, 1000 / fps);
+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);
+```
+
+### 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
@@ -248,14 +324,27 @@ setInterval(() => {
 
 | Function | Returns | Description |
 |---|---|---|
-| `imageToAsciiFrame(source, options, w?, h?)` | `{ frame, cols, rows }` | Convert an image, video frame, or canvas to ASCII |
-| `renderFrameToCanvas(ctx, frame, options, w, h, time?, hoverPos?)` | `void` | Render an ASCII frame to a 2D canvas context |
+| `asciify(source, canvas, opts?)` | `Promise<void>` | Convert an image/video/canvas (or URL) to ASCII and render — handles loading automatically |
+| `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 |
 | `asciiBackground(selector, options)` | `() => void` | Mount a live animated ASCII background; returns a cleanup function |
 | `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 |
@@ -263,13 +352,17 @@ setInterval(() => {
 | `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` | standard ramp | Custom character density ramp |
-| `brightness` | `number` | `0` | Brightness adjustment (-1 → 1) |
-| `contrast` | `number` | `1` | Contrast multiplier |
+| `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 |
-| `hoverEffect` | `string` | `'none'` | Interactive effect name |
-| `hoverStrength` | `number` | `0.8` | Effect intensity |
-| `hoverRadius` | `number` | `0.3` | Effect radius (0–1 relative to canvas) |
+| `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) |
 
 ### Background Options
 

package/dist/index.cjs

@@ -970,7 +970,7 @@ function renderFrameToCanvas(ctx, frame, options, canvasWidth, canvasHeight, tim
 }
 
 // src/core/simple-api.ts
-async function asciify(source, canvas, { fontSize = 10, style = "classic", options = {} } = {}) {
+async function asciify(source, canvas, { fontSize = 10, artStyle = "classic", options = {} } = {}) {
   let el;
   if (typeof source === "string") {
     const img = new Image();
@@ -990,16 +990,16 @@ async function asciify(source, canvas, { fontSize = 10, style = "classic", optio
   } else {
     el = source;
   }
-  const preset = ART_STYLE_PRESETS[style];
+  const preset = ART_STYLE_PRESETS[artStyle];
   const merged = { ...DEFAULT_OPTIONS, ...preset, ...options, fontSize };
   const ctx = canvas.getContext("2d");
   if (!ctx) throw new Error("Could not get 2d context from canvas");
   const { frame } = imageToAsciiFrame(el, merged, canvas.width, canvas.height);
   renderFrameToCanvas(ctx, frame, merged, canvas.width, canvas.height);
 }
-async function asciifyGif(source, canvas, { fontSize = 10, style = "classic", options = {} } = {}) {
+async function asciifyGif(source, canvas, { fontSize = 10, artStyle = "classic", options = {} } = {}) {
   const buffer = typeof source === "string" ? await fetch(source).then((r) => r.arrayBuffer()) : source;
-  const merged = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[style], ...options, fontSize };
+  const merged = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[artStyle], ...options, fontSize };
   const ctx = canvas.getContext("2d");
   if (!ctx) throw new Error("Could not get 2d context from canvas");
   const { frames, fps } = await gifToAsciiFrames(buffer, merged, canvas.width, canvas.height);
@@ -1023,20 +1023,22 @@ async function asciifyGif(source, canvas, { fontSize = 10, style = "classic", op
     cancelAnimationFrame(animId);
   };
 }
-async function asciifyVideo(source, canvas, { fontSize = 10, style = "classic", options = {} } = {}) {
+async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic", options = {} } = {}) {
   let video;
   if (typeof source === "string") {
     video = document.createElement("video");
     video.crossOrigin = "anonymous";
     video.src = source;
-    await new Promise((resolve, reject) => {
-      video.onloadeddata = () => resolve();
-      video.onerror = () => reject(new Error(`Failed to load video: ${source}`));
-    });
+    if (video.readyState < 2) {
+      await new Promise((resolve, reject) => {
+        video.onloadeddata = () => resolve();
+        video.onerror = () => reject(new Error(`Failed to load video: ${source}`));
+      });
+    }
   } else {
     video = source;
   }
-  const merged = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[style], ...options, fontSize };
+  const merged = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[artStyle], ...options, fontSize };
   const ctx = canvas.getContext("2d");
   if (!ctx) throw new Error("Could not get 2d context from canvas");
   const { frames, fps } = await videoToAsciiFrames(video, merged, canvas.width, canvas.height);