asciify-engine 1.0.34 → 1.0.36

package/dist/index.d.cts

@@ -17,24 +17,99 @@ declare const PALETTE_THEMES: Record<PaletteTheme, {
 }>;
 type SourceType = 'image' | 'video' | 'gif' | null;
 interface AsciiOptions {
+    /** Character cell size in pixels. Smaller = more detail, more cells. Default: `10` */
     fontSize: number;
+    /** Extra horizontal spacing between characters (pixels). Default: `1` */
     charSpacing: number;
+    /**
+     * Brightness adjustment applied before luminance mapping.
+     * Range −1 (black) → 0 (unchanged) → 1 (white). Default: `0`
+     */
     brightness: number;
+    /**
+     * Contrast boost applied before luminance mapping.
+     * `0` = unchanged, positive values increase contrast, negative decrease it.
+     * Default: `0`
+     */
     contrast: number;
+    /**
+     * Character density ramp — ordered from lightest to darkest.
+     * Use `CHARSETS` for pre-built ramps or supply your own string.
+     * Default: `' .:-=+*#%@'`
+     */
     charset: string;
+    /**
+     * Colour output mode.
+     * - `'grayscale'` — white-on-black monochrome
+     * - `'fullcolor'` — samples pixel colours from the source
+     * - `'matrix'` — green phosphor terminal look
+     * - `'accent'` — single accent colour with intensity-driven brightness
+     * Default: `'grayscale'`
+     */
     colorMode: ColorMode;
+    /**
+     * The accent colour used when `colorMode` is `'accent'` or `'matrix'`.
+     * Any CSS colour string. Default: `'#d4ff00'`
+     */
     accentColor: string;
+    /** Invert luminance mapping (light pixels → dense chars). Default: `false` */
     invert: boolean;
+    /**
+     * Render mode.
+     * - `'ascii'` — characters drawn as text
+     * - `'dots'` — each cell rendered as a filled circle (particle look)
+     * Default: `'ascii'`
+     */
     renderMode: RenderMode;
+    /**
+     * Per-character animation driven over time.
+     * Applies wave, glitch, rain-drop, spiral, and other effects to the rendered text.
+     * Default: `'none'`
+     */
     animationStyle: AnimationStyle;
+    /** Speed multiplier for `animationStyle` effects. Default: `1` */
     animationSpeed: number;
+    /**
+     * Size of each dot relative to the cell when `renderMode === 'dots'`.
+     * `1` fills the whole cell, `0.5` draws half-size circles. Default: `0.8`
+     */
     dotSizeRatio: number;
+    /**
+     * Floyd-Steinberg dither strength applied to the luminance map.
+     * `0` = no dithering, `1` = full dithering. Default: `0`
+     */
     ditherStrength: number;
+    /**
+     * Overall intensity of the hover / cursor interaction effect.
+     * `0` disables the effect. Default: `0`
+     */
     hoverStrength: number;
+    /**
+     * Radius of the hover interaction zone as a fraction of the canvas size.
+     * `0.1` = 10% of canvas width. Default: `0.2`
+     */
     hoverRadius: number;
+    /**
+     * Which cursor interaction style to apply when `hoverStrength > 0`.
+     * See `HoverPreset` or `HOVER_PRESETS` for ready-made configurations.
+     * Default: `'spotlight'`
+     */
     hoverEffect: HoverEffect;
+    /**
+     * Tint colour used by hover effects such as spotlight, glow, and colorShift.
+     * Any CSS colour string. Default: `'#ffffff'`
+     */
     hoverColor: string;
+    /**
+     * Art style preset applied at render time.
+     * Shorthand for a specific combination of `charset`, `renderMode`, and `colorMode`.
+     * See `ART_STYLE_PRESETS` for the full list. Default: `'classic'`
+     */
     artStyle: ArtStyle;
+    /**
+     * Custom repeating text used when `artStyle` is `'letters'` or when you set
+     * a custom charset. Leave empty to use the selected `charset`. Default: `''`
+     */
     customText: string;
 }
 interface AsciiCell {
@@ -130,8 +205,12 @@ declare function renderFrameToCanvas(ctx: CanvasRenderingContext2D, frame: Ascii
 interface AsciifySimpleOptions {
     /** Character size in pixels. Default: 10 */
     fontSize?: number;
-    /** Art style preset. Default: 'classic' */
-    style?: ArtStyle;
+    /**
+     * Art style preset — controls charset, render mode, and color mode together.
+     * Shorthand for spreading `ART_STYLE_PRESETS[artStyle]` into options.
+     * Default: `'classic'`
+     */
+    artStyle?: ArtStyle;
     /** Extra options to merge on top of the preset */
     options?: Partial<AsciiOptions>;
 }
@@ -140,9 +219,9 @@ interface AsciifySimpleOptions {
  *
  * @example
  * await asciify(document.querySelector('img'), canvas);
- * await asciify(img, canvas, { fontSize: 8, style: 'letters' });
+ * await asciify(img, canvas, { fontSize: 8, artStyle: 'letters' });
  */
-declare function asciify(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | string, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<void>;
+declare function asciify(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<void>;
 /**
  * Fetch a GIF, convert it to ASCII, and start an animation loop on a canvas.
  * Returns a `stop()` function that cancels the loop.
@@ -151,7 +230,7 @@ declare function asciify(source: HTMLImageElement | HTMLVideoElement | HTMLCanva
  * const stop = await asciifyGif('animation.gif', canvas);
  * // later: stop();
  */
-declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
+declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<() => void>;
 /**
  * Convert a video element to ASCII art and start an animation loop on a canvas.
  * Returns a `stop()` function that cancels the loop.
@@ -160,7 +239,7 @@ declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElem
  * const stop = await asciifyVideo(video, canvas);
  * // later: stop();
  */
-declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
+declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<() => void>;
 
 interface WaveBackgroundOptions {
     /** Font size in CSS pixels (default: 13) */

package/dist/index.d.ts

@@ -17,24 +17,99 @@ declare const PALETTE_THEMES: Record<PaletteTheme, {
 }>;
 type SourceType = 'image' | 'video' | 'gif' | null;
 interface AsciiOptions {
+    /** Character cell size in pixels. Smaller = more detail, more cells. Default: `10` */
     fontSize: number;
+    /** Extra horizontal spacing between characters (pixels). Default: `1` */
     charSpacing: number;
+    /**
+     * Brightness adjustment applied before luminance mapping.
+     * Range −1 (black) → 0 (unchanged) → 1 (white). Default: `0`
+     */
     brightness: number;
+    /**
+     * Contrast boost applied before luminance mapping.
+     * `0` = unchanged, positive values increase contrast, negative decrease it.
+     * Default: `0`
+     */
     contrast: number;
+    /**
+     * Character density ramp — ordered from lightest to darkest.
+     * Use `CHARSETS` for pre-built ramps or supply your own string.
+     * Default: `' .:-=+*#%@'`
+     */
     charset: string;
+    /**
+     * Colour output mode.
+     * - `'grayscale'` — white-on-black monochrome
+     * - `'fullcolor'` — samples pixel colours from the source
+     * - `'matrix'` — green phosphor terminal look
+     * - `'accent'` — single accent colour with intensity-driven brightness
+     * Default: `'grayscale'`
+     */
     colorMode: ColorMode;
+    /**
+     * The accent colour used when `colorMode` is `'accent'` or `'matrix'`.
+     * Any CSS colour string. Default: `'#d4ff00'`
+     */
     accentColor: string;
+    /** Invert luminance mapping (light pixels → dense chars). Default: `false` */
     invert: boolean;
+    /**
+     * Render mode.
+     * - `'ascii'` — characters drawn as text
+     * - `'dots'` — each cell rendered as a filled circle (particle look)
+     * Default: `'ascii'`
+     */
     renderMode: RenderMode;
+    /**
+     * Per-character animation driven over time.
+     * Applies wave, glitch, rain-drop, spiral, and other effects to the rendered text.
+     * Default: `'none'`
+     */
     animationStyle: AnimationStyle;
+    /** Speed multiplier for `animationStyle` effects. Default: `1` */
     animationSpeed: number;
+    /**
+     * Size of each dot relative to the cell when `renderMode === 'dots'`.
+     * `1` fills the whole cell, `0.5` draws half-size circles. Default: `0.8`
+     */
     dotSizeRatio: number;
+    /**
+     * Floyd-Steinberg dither strength applied to the luminance map.
+     * `0` = no dithering, `1` = full dithering. Default: `0`
+     */
     ditherStrength: number;
+    /**
+     * Overall intensity of the hover / cursor interaction effect.
+     * `0` disables the effect. Default: `0`
+     */
     hoverStrength: number;
+    /**
+     * Radius of the hover interaction zone as a fraction of the canvas size.
+     * `0.1` = 10% of canvas width. Default: `0.2`
+     */
     hoverRadius: number;
+    /**
+     * Which cursor interaction style to apply when `hoverStrength > 0`.
+     * See `HoverPreset` or `HOVER_PRESETS` for ready-made configurations.
+     * Default: `'spotlight'`
+     */
     hoverEffect: HoverEffect;
+    /**
+     * Tint colour used by hover effects such as spotlight, glow, and colorShift.
+     * Any CSS colour string. Default: `'#ffffff'`
+     */
     hoverColor: string;
+    /**
+     * Art style preset applied at render time.
+     * Shorthand for a specific combination of `charset`, `renderMode`, and `colorMode`.
+     * See `ART_STYLE_PRESETS` for the full list. Default: `'classic'`
+     */
     artStyle: ArtStyle;
+    /**
+     * Custom repeating text used when `artStyle` is `'letters'` or when you set
+     * a custom charset. Leave empty to use the selected `charset`. Default: `''`
+     */
     customText: string;
 }
 interface AsciiCell {
@@ -130,8 +205,12 @@ declare function renderFrameToCanvas(ctx: CanvasRenderingContext2D, frame: Ascii
 interface AsciifySimpleOptions {
     /** Character size in pixels. Default: 10 */
     fontSize?: number;
-    /** Art style preset. Default: 'classic' */
-    style?: ArtStyle;
+    /**
+     * Art style preset — controls charset, render mode, and color mode together.
+     * Shorthand for spreading `ART_STYLE_PRESETS[artStyle]` into options.
+     * Default: `'classic'`
+     */
+    artStyle?: ArtStyle;
     /** Extra options to merge on top of the preset */
     options?: Partial<AsciiOptions>;
 }
@@ -140,9 +219,9 @@ interface AsciifySimpleOptions {
  *
  * @example
  * await asciify(document.querySelector('img'), canvas);
- * await asciify(img, canvas, { fontSize: 8, style: 'letters' });
+ * await asciify(img, canvas, { fontSize: 8, artStyle: 'letters' });
  */
-declare function asciify(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | string, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<void>;
+declare function asciify(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<void>;
 /**
  * Fetch a GIF, convert it to ASCII, and start an animation loop on a canvas.
  * Returns a `stop()` function that cancels the loop.
@@ -151,7 +230,7 @@ declare function asciify(source: HTMLImageElement | HTMLVideoElement | HTMLCanva
  * const stop = await asciifyGif('animation.gif', canvas);
  * // later: stop();
  */
-declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
+declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<() => void>;
 /**
  * Convert a video element to ASCII art and start an animation loop on a canvas.
  * Returns a `stop()` function that cancels the loop.
@@ -160,7 +239,7 @@ declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElem
  * const stop = await asciifyVideo(video, canvas);
  * // later: stop();
  */
-declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
+declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<() => void>;
 
 interface WaveBackgroundOptions {
     /** Font size in CSS pixels (default: 13) */

package/dist/index.js

@@ -968,7 +968,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();
@@ -988,16 +988,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);
@@ -1021,20 +1021,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);