asciify-engine 1.0.17 → 1.0.18

package/dist/index.d.ts

@@ -66,9 +66,12 @@ declare const HOVER_PRESETS: Record<HoverPreset, {
     options: Partial<AsciiOptions>;
 }>;
 
+/**
+ * Core frame-to-canvas renderer and source-to-frame converters.
+ */
+
 /**
  * Convert an image element or canvas to a single ASCII frame.
- * Now reads alpha channel for transparency support.
  */
 declare function imageToAsciiFrame(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement, options: AsciiOptions, targetWidth?: number, targetHeight?: number): {
     frame: AsciiFrame;
@@ -86,8 +89,6 @@ declare function videoToAsciiFrames(video: HTMLVideoElement, options: AsciiOptio
 }>;
 /**
  * Extract frames from an animated GIF file buffer.
- * Uses gifuct-js to parse and decompress GIF frames, then composites
- * them onto a canvas (handling disposal methods) to produce full frames.
  */
 declare function gifToAsciiFrames(buffer: ArrayBuffer, options: AsciiOptions, targetWidth: number, targetHeight: number, onProgress?: (progress: number) => void): Promise<{
     frames: AsciiFrame[];
@@ -98,22 +99,32 @@ declare function gifToAsciiFrames(buffer: ArrayBuffer, options: AsciiOptions, ta
 /**
  * Render an ASCII frame to a canvas context.
  * Supports both ASCII text mode and Dots mode.
- * Always renders every cell at full quality.
- *
- * Performance strategy:
- * - fillRect fast path for sub-6px text (30x faster than fillText)
- * - Auto-scaling hover radius: at high cell counts, the hover area
- *   is proportionally smaller so fewer cells compute hover effects
- * - Hover bounding box early-exit skips cells outside the hover zone
- *
- * @param time - elapsed time in seconds for animation effects
- * @param hoverPos - optional smoothed mouse position {x, y, intensity} for hover effect
  */
 declare function renderFrameToCanvas(ctx: CanvasRenderingContext2D, frame: AsciiFrame, options: AsciiOptions, canvasWidth: number, canvasHeight: number, time?: number, hoverPos?: {
     x: number;
     y: number;
     intensity?: number;
 } | null): void;
+
+/**
+ * Embed code generation — serializes ASCII frames into self-contained
+ * HTML snippets that replay via the CDN embed runtime.
+ */
+
+/**
+ * Generate a static single-frame embed snippet.
+ */
+declare function generateEmbedCode(frame: AsciiFrame, options: AsciiOptions, width: number, height: number): string;
+/**
+ * Generate an animated multi-frame embed snippet (GIF / video).
+ */
+declare function generateAnimatedEmbedCode(frames: AsciiFrame[], options: AsciiOptions, fps: number, width: number, height: number): string;
+
+/**
+ * Simple one-call asciify API.
+ * Wraps imageToAsciiFrame + renderFrameToCanvas behind easy-to-use helpers.
+ */
+
 interface AsciifySimpleOptions {
     /** Character size in pixels. Default: 10 */
     fontSize?: number;
@@ -126,11 +137,7 @@ interface AsciifySimpleOptions {
  * Convert an image/video/canvas element to ASCII art and render it onto a canvas.
  *
  * @example
- * const img = document.querySelector('img');
- * const canvas = document.querySelector('canvas');
- * await asciify(img, canvas);
- *
- * @example with options
+ * await asciify(document.querySelector('img'), canvas);
  * await asciify(img, canvas, { fontSize: 8, style: 'letters' });
  */
 declare function asciify(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | string, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<void>;
@@ -141,9 +148,6 @@ declare function asciify(source: HTMLImageElement | HTMLVideoElement | HTMLCanva
  * @example
  * const stop = await asciifyGif('animation.gif', canvas);
  * // later: stop();
- *
- * @example with style
- * const stop = await asciifyGif('animation.gif', canvas, { style: 'letters' });
  */
 declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
 /**
@@ -151,35 +155,11 @@ declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElem
  * Returns a `stop()` function that cancels the loop.
  *
  * @example
- * const video = document.querySelector('video');
  * const stop = await asciifyVideo(video, canvas);
  * // later: stop();
- *
- * @example with style
- * const stop = await asciifyVideo(video, canvas, { fontSize: 8, style: 'art' });
  */
 declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
-/**
- * Generate a clean embed snippet.
- *
- * Structure:
- *   <canvas id>            — the render target, short and clean
- *   <script type=json id>  — frame data lives here, clearly separated
- *   <script src=cdn>       — always the same line, cached by browsers
- *
- * Output (static):
- *   <!-- Asciify Embed -->
- *   <canvas id="ar-xxx" data-asciify-opts="{…}" width="…" height="…"></canvas>
- *   <script type="application/json" id="ar-xxx-d">"BASE64"</script>
- *   <script src="cdn/embed.js" async></script>
- *   <!-- /Asciify Embed -->
- */
-declare function generateEmbedCode(frame: AsciiFrame, options: AsciiOptions, width: number, height: number): string;
-/**
- * Generate an animated embed snippet for multi-frame (GIF/video) ASCII art.
- * Uses the same CDN runtime as generateEmbedCode.
- */
-declare function generateAnimatedEmbedCode(frames: AsciiFrame[], options: AsciiOptions, fps: number, width: number, height: number): string;
+
 interface WaveBackgroundOptions {
     /** Font size in CSS pixels (default: 13) */
     fontSize?: number;
@@ -187,9 +167,9 @@ interface WaveBackgroundOptions {
     charAspect?: number;
     /** Line height multiplier (default: 1.4) */
     lineHeightRatio?: number;
-    /** Character set from dark→bright (default: ' .·:;=+*#%@░▒▓') */
+    /** Character set from dark→bright (default: ' .:-=+*#%@') */
     chars?: string;
-    /** Base colour for low-intensity cells — use '{a}' as alpha placeholder (default: white) */
+    /** Base colour — use '{a}' as alpha placeholder */
     baseColor?: string;
     /** Accent colour applied near the cursor and on wave peaks (default: '#d4ff00') */
     accentColor?: string;
@@ -197,157 +177,85 @@ interface WaveBackgroundOptions {
     accentThreshold?: number;
     /** How strongly the mouse influences local intensity (default: 0.55) */
     mouseInfluence?: number;
-    /** Radial falloff for mouse influence — higher = tighter spotlight (default: 2.8) */
+    /** Radial falloff for mouse influence (default: 2.8) */
     mouseFalloff?: number;
     /** Base wave animation speed (default: 1) */
     speed?: number;
     /** Enable vortex swirl effect around cursor (default: true) */
     vortex?: boolean;
-    /** Enable sparkle / pop flicker layered on top (default: true) */
+    /** Enable sparkle / pop flicker (default: true) */
     sparkles?: boolean;
     /** Enable a slow global breathe pulse (default: true) */
     breathe?: boolean;
     /** Light mode: swap fill colours to dark-on-light (default: false) */
     lightMode?: boolean;
 }
-/**
- * Render a procedural interactive wave-field of ASCII characters.
- *
- * Layers stacked per cell:
- *  1. Three cardinal sine waves (classic feel)
- *  2. Fractal Brownian Motion noise (organic structure)
- *  3. Diagonal drift ripple (depth / perspective)
- *  4. Slow global breathe pulse (heartbeat)
- *  5. Vortex swirl near cursor (energy field)
- *  6. Proximity spotlight (cursor highlight)
- *  7. Sparkle flickers on bright peaks (life)
- *
- * Call inside a requestAnimationFrame loop with accumulated time in seconds
- * and the current normalised mouse position {x, y} (0-1 range each).
- *
- * @example
- * ```ts
- * import { renderWaveBackground } from 'asciify-engine';
- *
- * const canvas = document.getElementById('bg') as HTMLCanvasElement;
- * const ctx = canvas.getContext('2d')!;
- * const mouse = { x: 0.5, y: 0.5 };
- * canvas.addEventListener('mousemove', e => {
- *   const r = canvas.getBoundingClientRect();
- *   mouse.x = (e.clientX - r.left) / r.width;
- *   mouse.y = (e.clientY - r.top) / r.height;
- * });
- *
- * let t = 0;
- * const tick = () => {
- *   renderWaveBackground(ctx, canvas.clientWidth, canvas.clientHeight, t, mouse);
- *   t += 0.016;
- *   requestAnimationFrame(tick);
- * };
- * requestAnimationFrame(tick);
- * ```
- */
 declare function renderWaveBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, mousePos?: {
     x: number;
     y: number;
 }, options?: WaveBackgroundOptions): void;
-/**
- * Renders a digital-rain ASCII background — independent columns of falling
- * characters each with a glowing head and fading tail. Deterministic and
- * stateless: derived entirely from elapsed time.
- *
- * @example
- * ```ts
- * asciiBackground('#hero', { type: 'rain' });
- * ```
- */
+
 interface RainBackgroundOptions {
     fontSize?: number;
-    /** Characters drawn in columns (one picked randomly per cell per frame). */
+    /** Characters drawn in columns */
     chars?: string;
-    /** Head / accent colour (default: '#d4ff00'). */
+    /** Head / accent colour (default: '#d4ff00') */
     accentColor?: string;
-    /** Custom character colour (any CSS colour string). */
+    /** Custom character colour */
     color?: string;
-    /** Global speed multiplier (default: 1). */
+    /** Global speed multiplier (default: 1) */
     speed?: number;
-    /** Fraction of columns active at once 0-1 (default: 0.55). */
+    /** Fraction of columns active at once 0-1 (default: 0.55) */
     density?: number;
-    /** Number of cells in the fading tail (default: 14). */
+    /** Number of cells in the fading tail (default: 14) */
     tailLength?: number;
-    /** Light mode: dark chars on light background (default: false). */
+    /** Light mode (default: false) */
     lightMode?: boolean;
 }
 declare function renderRainBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: RainBackgroundOptions): void;
-/**
- * Renders a 3-D star-warp / hyperspace ASCII background — ASCII chars fly
- * outward from a vanishing point that gently follows the mouse cursor.
- * Stars scale up and brighten as they approach the screen edge.
- *
- * @example
- * ```ts
- * asciiBackground('#hero', { type: 'stars' });
- * ```
- */
+
 interface StarsBackgroundOptions {
     fontSize?: number;
-    /** Characters used as stars (sparse = more authentic). */
+    /** Characters used as stars */
     chars?: string;
-    /** Accent/trail colour for fast near-edge stars (default: '#d4ff00'). */
+    /** Accent/trail colour for fast near-edge stars (default: '#d4ff00') */
     accentColor?: string;
-    /** Custom base colour (any CSS colour string). */
+    /** Custom base colour */
     color?: string;
-    /** Global speed multiplier (default: 1). */
+    /** Global speed multiplier (default: 1) */
     speed?: number;
-    /** Number of star particles (default: 180). */
+    /** Number of star particles (default: 180) */
     count?: number;
-    /** Light mode (default: false). */
+    /** Light mode (default: false) */
     lightMode?: boolean;
 }
 declare function renderStarsBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, mousePos?: {
     x: number;
     y: number;
 }, options?: StarsBackgroundOptions): void;
-/**
- * Concentric ASCII ripples that radiate from a vanishing point following
- * the mouse — like a sonar / radar signal.
- *
- * @example
- * ```ts
- * asciiBackground('#hero', { type: 'pulse' });
- * ```
- */
+
 interface PulseBackgroundOptions {
-    /** Font size in CSS pixels (default: 13). */
     fontSize?: number;
-    /** Character ramp dark → bright (default: ' .:-=+*#%@'). */
+    /** Characters to tile (default: '. · ○ ◎ ●') */
     chars?: string;
-    /** Accent colour on ring crests (default: '#d4ff00'). */
+    /** Ring peak colour (default: '#00ffcc') */
     accentColor?: string;
-    /** Custom base character colour (any CSS colour string). */
+    /** Custom base colour */
     color?: string;
-    /** Number of concentric rings (default: 6). */
+    /** Number of simultaneous rings (default: 5) */
     rings?: number;
-    /** Ring travel speed (default: 1). */
+    /** Animation speed (default: 1) */
     speed?: number;
-    /** Ring width sharpness — higher = thinner rings (default: 4). */
+    /** Ring edge sharpness 1–10 (default: 4) */
     sharpness?: number;
-    /** Light mode (default: false). */
+    /** Light mode (default: false) */
     lightMode?: boolean;
 }
 declare function renderPulseBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, mousePos?: {
     x: number;
     y: number;
 }, options?: PulseBackgroundOptions): void;
-/**
- * Slow-drifting organic fractal noise field. No directional pattern —
- * pure ambient texture. The mouse subtly warps the field around the cursor.
- *
- * @example
- * ```ts
- * asciiBackground('#hero', { type: 'noise' });
- * ```
- */
+
 interface NoiseBackgroundOptions {
     /** Font size in CSS pixels (default: 14). */
     fontSize?: number;
@@ -374,15 +282,7 @@ declare function renderNoiseBackground(ctx: CanvasRenderingContext2D, width: num
     x: number;
     y: number;
 }, options?: NoiseBackgroundOptions): void;
-/**
- * CRT-style horizontal scan-line sweep. Bright scan bands travel downward
- * continuously; the cursor creates a local disruption / glitch zone.
- *
- * @example
- * ```ts
- * asciiBackground('#hero', { type: 'grid' });
- * ```
- */
+
 interface GridBackgroundOptions {
     /** Font size in CSS pixels (default: 12). */
     fontSize?: number;
@@ -407,10 +307,11 @@ declare function renderGridBackground(ctx: CanvasRenderingContext2D, width: numb
     x: number;
     y: number;
 }, options?: GridBackgroundOptions): void;
+
 interface AuroraBackgroundOptions {
     /** Character grid density. Default 14. */
     fontSize?: number;
-    /** Character ramp from sparse to dense. Default fine gradient ramp. */
+    /** Character ramp from sparse to dense. */
     chars?: string;
     /** Base character color. Default theme-aware white/black. */
     color?: string;
@@ -431,6 +332,7 @@ declare function renderAuroraBackground(ctx: CanvasRenderingContext2D, width: nu
     x: number;
     y: number;
 }, options?: AuroraBackgroundOptions): void;
+
 interface SilkBackgroundOptions {
     /** Character grid density. Default 13. */
     fontSize?: number;
@@ -448,6 +350,7 @@ interface SilkBackgroundOptions {
     lightMode?: boolean;
 }
 declare function renderSilkBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: SilkBackgroundOptions): void;
+
 interface VoidBackgroundOptions {
     /** Character grid density. Default 13. */
     fontSize?: number;
@@ -470,6 +373,7 @@ declare function renderVoidBackground(ctx: CanvasRenderingContext2D, width: numb
     x: number;
     y: number;
 }, options?: VoidBackgroundOptions): void;
+
 interface MorphBackgroundOptions {
     /** Character grid density. Default 14. */
     fontSize?: number;
@@ -487,37 +391,35 @@ interface MorphBackgroundOptions {
     lightMode?: boolean;
 }
 declare function renderMorphBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: MorphBackgroundOptions): void;
+
 /**
- * Drop-in helper that mounts an interactive ASCII wave background onto any
- * element. Injects a canvas, wires DPR resize, mouse tracking, and the RAF
- * loop — all internally. Auto-detects light/dark mode and stays in sync if
- * the system theme changes.
+ * ASCII Background — public entry point for the backgrounds sub-system.
  *
- * Returns a `destroy()` function to clean everything up.
- *
- * @example
- * ```ts
- * import { asciiBackground } from 'asciify-engine';
- *
- * // 1 line:
- * const { destroy } = asciiBackground('#hero', { opacity: 0.2 });
- *
- * // Custom color:
- * asciiBackground('#hero', { color: '#6b8700', accentColor: '#d4ff00' });
- *
- * // React — return destroy as cleanup:
- * useEffect(() => asciiBackground(ref.current).destroy, []);
- * ```
+ * Exports:
+ *  - All 10 render functions
+ *  - All 10 option interfaces
+ *  - `AsciiBackgroundOptions` — combined union type + mount options
+ *  - `asciiBackground()` — the drop-in mount helper
+ *  - `mountWaveBackground` / `MountWaveOptions` — deprecated aliases
+ */
+
+/**
+ * Combined options for `asciiBackground()`. Extends all 10 background option
+ * interfaces so every background's options can be passed through one object.
  */
 interface AsciiBackgroundOptions extends WaveBackgroundOptions, RainBackgroundOptions, StarsBackgroundOptions, PulseBackgroundOptions, NoiseBackgroundOptions, GridBackgroundOptions, AuroraBackgroundOptions, SilkBackgroundOptions, VoidBackgroundOptions, MorphBackgroundOptions {
     /**
      * Which background to render (default: 'wave').
-     * - 'wave'  — interactive ASCII field with vortex, sparkles, breathe
-     * - 'rain'  — digital column rain (Matrix-style falling characters)
-     * - 'stars' — 3D star-warp / hyperspace (chars fly toward the viewer)
-     * - 'pulse' — concentric ASCII ripples radiating from the mouse position
-     * - 'noise' — slow-drifting organic fractal noise field
-     * - 'grid'  — CRT-style horizontal scan bands with cursor glitch zone
+     * - 'wave'   — interactive ASCII field with vortex, sparkles, breathe
+     * - 'rain'   — digital column rain (Matrix-style falling characters)
+     * - 'stars'  — 3D star-warp / hyperspace chars fly toward the viewer
+     * - 'pulse'  — concentric ASCII ripples radiating from the mouse
+     * - 'noise'  — slow-drifting organic fractal noise field
+     * - 'grid'   — CRT-style horizontal scan bands with cursor glitch zone
+     * - 'aurora' — premium slow-drifting light bands
+     * - 'silk'   — smooth directional flow-field ribbons
+     * - 'void'   — gravitational singularity follows the cursor
+     * - 'morph'  — per-cell multi-frequency shimmer
      */
     type?: 'wave' | 'rain' | 'stars' | 'pulse' | 'noise' | 'grid' | 'aurora' | 'silk' | 'void' | 'morph';
     /** CSS opacity applied to the canvas element (default: 0.2) */
@@ -528,18 +430,34 @@ interface AsciiBackgroundOptions extends WaveBackgroundOptions, RainBackgroundOp
     zIndex?: number;
     /**
      * Colour scheme handling (default: 'auto').
-     * - 'auto'  — follows the system prefers-color-scheme and updates live
+     * - 'auto'  — follows system prefers-color-scheme and updates live
      * - 'dark'  — always render bright chars on dark background
      * - 'light' — always render dark chars on light background
      */
     colorScheme?: 'auto' | 'light' | 'dark';
     /**
      * Custom character colour. Accepts any CSS colour string: hex, rgb(), hsl().
-     * Overrides the default white/black for the ASCII chars.
+     * Overrides the default white/black for ASCII chars.
      * @example '#6b8700'
      */
     color?: string;
 }
+/**
+ * Drop-in helper that mounts an interactive ASCII background onto any element.
+ * Injects a canvas, wires DPR resize, mouse tracking, and the RAF loop.
+ * Auto-detects light/dark mode and stays in sync if the system theme changes.
+ *
+ * Returns a `destroy()` function to clean everything up.
+ *
+ * @example
+ * ```ts
+ * // 1 line:
+ * const { destroy } = asciiBackground('#hero', { opacity: 0.2 });
+ *
+ * // React — return destroy as cleanup:
+ * useEffect(() => asciiBackground(ref.current).destroy, []);
+ * ```
+ */
 declare function asciiBackground(target: string | HTMLElement | null, options?: AsciiBackgroundOptions): {
     destroy: () => void;
 };