asciify-engine 1.0.5 → 1.0.7

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 type ColorMode = 'grayscale' | 'fullcolor' | 'matrix' | 'accent';
 type RenderMode = 'ascii' | 'dots';
-type AnimationStyle = 'none' | 'wave' | 'pulse' | 'rain' | 'breathe' | 'sparkle' | 'glitch' | 'spiral' | 'typewriter' | 'scatter';
+type AnimationStyle = 'none' | 'wave' | 'pulse' | 'rain' | 'breathe' | 'sparkle' | 'glitch' | 'spiral' | 'typewriter' | 'scatter' | 'waveField';
 type ArtStyle = 'classic' | 'particles' | 'letters' | 'claudeCode' | 'art' | 'terminal' | 'box' | 'lines';
 type HoverEffect = 'spotlight' | 'magnify' | 'repel' | 'glow' | 'colorShift';
 type HoverPreset = 'none' | 'subtle' | 'flashlight' | 'magnifier' | 'forceField' | 'neon' | 'fire' | 'ice';
@@ -160,15 +160,87 @@ declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElem
  */
 declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
 /**
- * Generate a self-contained HTML embed snippet for an ASCII image.
- * Features: canvas rendering, animation loop, hover effects.
+ * Generate a professional 3-line embed snippet.
+ * The render runtime is loaded from jsDelivr CDN (free, served from npm).
+ * Only the base64-encoded frame data is inlined.
  */
 declare function generateEmbedCode(frame: AsciiFrame, options: AsciiOptions, width: number, height: number): string;
 /**
- * Generate animated embed code for multi-frame (video) ASCII art.
- * Canvas-based with frame cycling, animation effects, and hover.
+ * 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;
+    /** Character aspect ratio width/height (default: 0.62) */
+    charAspect?: number;
+    /** Line height multiplier (default: 1.4) */
+    lineHeightRatio?: number;
+    /** Character set from dark→bright (default: ' .·:;=+*#%@░▒▓') */
+    chars?: string;
+    /** Base colour for low-intensity cells — use '{a}' as alpha placeholder (default: white) */
+    baseColor?: string;
+    /** Accent colour applied near the cursor and on wave peaks (default: '#d4ff00') */
+    accentColor?: string;
+    /** Accent threshold: normalised intensity above which accent kicks in (default: 0.52) */
+    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) */
+    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) */
+    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;
 
 interface WebGLRenderer {
     render(frame: AsciiFrame, options: AsciiOptions, displayW: number, displayH: number, time: number, hoverPos?: {
@@ -187,4 +259,4 @@ interface WebGLRenderer {
  */
 declare function tryCreateWebGLRenderer(canvas: HTMLCanvasElement): WebGLRenderer | null;
 
-export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, CHARSETS, type CharsetKey, type ColorMode, DEFAULT_OPTIONS, HOVER_PRESETS, type HoverEffect, type HoverPreset, type RenderMode, type SourceType, type WebGLRenderer, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, renderFrameToCanvas, tryCreateWebGLRenderer, videoToAsciiFrames };
+export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, CHARSETS, type CharsetKey, type ColorMode, DEFAULT_OPTIONS, HOVER_PRESETS, type HoverEffect, type HoverPreset, type RenderMode, type SourceType, type WaveBackgroundOptions, type WebGLRenderer, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, renderFrameToCanvas, renderWaveBackground, tryCreateWebGLRenderer, videoToAsciiFrames };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 type ColorMode = 'grayscale' | 'fullcolor' | 'matrix' | 'accent';
 type RenderMode = 'ascii' | 'dots';
-type AnimationStyle = 'none' | 'wave' | 'pulse' | 'rain' | 'breathe' | 'sparkle' | 'glitch' | 'spiral' | 'typewriter' | 'scatter';
+type AnimationStyle = 'none' | 'wave' | 'pulse' | 'rain' | 'breathe' | 'sparkle' | 'glitch' | 'spiral' | 'typewriter' | 'scatter' | 'waveField';
 type ArtStyle = 'classic' | 'particles' | 'letters' | 'claudeCode' | 'art' | 'terminal' | 'box' | 'lines';
 type HoverEffect = 'spotlight' | 'magnify' | 'repel' | 'glow' | 'colorShift';
 type HoverPreset = 'none' | 'subtle' | 'flashlight' | 'magnifier' | 'forceField' | 'neon' | 'fire' | 'ice';
@@ -160,15 +160,87 @@ declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElem
  */
 declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
 /**
- * Generate a self-contained HTML embed snippet for an ASCII image.
- * Features: canvas rendering, animation loop, hover effects.
+ * Generate a professional 3-line embed snippet.
+ * The render runtime is loaded from jsDelivr CDN (free, served from npm).
+ * Only the base64-encoded frame data is inlined.
  */
 declare function generateEmbedCode(frame: AsciiFrame, options: AsciiOptions, width: number, height: number): string;
 /**
- * Generate animated embed code for multi-frame (video) ASCII art.
- * Canvas-based with frame cycling, animation effects, and hover.
+ * 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;
+    /** Character aspect ratio width/height (default: 0.62) */
+    charAspect?: number;
+    /** Line height multiplier (default: 1.4) */
+    lineHeightRatio?: number;
+    /** Character set from dark→bright (default: ' .·:;=+*#%@░▒▓') */
+    chars?: string;
+    /** Base colour for low-intensity cells — use '{a}' as alpha placeholder (default: white) */
+    baseColor?: string;
+    /** Accent colour applied near the cursor and on wave peaks (default: '#d4ff00') */
+    accentColor?: string;
+    /** Accent threshold: normalised intensity above which accent kicks in (default: 0.52) */
+    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) */
+    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) */
+    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;
 
 interface WebGLRenderer {
     render(frame: AsciiFrame, options: AsciiOptions, displayW: number, displayH: number, time: number, hoverPos?: {
@@ -187,4 +259,4 @@ interface WebGLRenderer {
  */
 declare function tryCreateWebGLRenderer(canvas: HTMLCanvasElement): WebGLRenderer | null;
 
-export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, CHARSETS, type CharsetKey, type ColorMode, DEFAULT_OPTIONS, HOVER_PRESETS, type HoverEffect, type HoverPreset, type RenderMode, type SourceType, type WebGLRenderer, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, renderFrameToCanvas, tryCreateWebGLRenderer, videoToAsciiFrames };
+export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, CHARSETS, type CharsetKey, type ColorMode, DEFAULT_OPTIONS, HOVER_PRESETS, type HoverEffect, type HoverPreset, type RenderMode, type SourceType, type WaveBackgroundOptions, type WebGLRenderer, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, renderFrameToCanvas, renderWaveBackground, tryCreateWebGLRenderer, videoToAsciiFrames };