asciify-engine 1.0.16 → 1.0.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -66,9 +66,12 @@ declare const HOVER_PRESETS: Record<HoverPreset, {
66
66
  options: Partial<AsciiOptions>;
67
67
  }>;
68
68
 
69
+ /**
70
+ * Core frame-to-canvas renderer and source-to-frame converters.
71
+ */
72
+
69
73
  /**
70
74
  * Convert an image element or canvas to a single ASCII frame.
71
- * Now reads alpha channel for transparency support.
72
75
  */
73
76
  declare function imageToAsciiFrame(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement, options: AsciiOptions, targetWidth?: number, targetHeight?: number): {
74
77
  frame: AsciiFrame;
@@ -86,8 +89,6 @@ declare function videoToAsciiFrames(video: HTMLVideoElement, options: AsciiOptio
86
89
  }>;
87
90
  /**
88
91
  * Extract frames from an animated GIF file buffer.
89
- * Uses gifuct-js to parse and decompress GIF frames, then composites
90
- * them onto a canvas (handling disposal methods) to produce full frames.
91
92
  */
92
93
  declare function gifToAsciiFrames(buffer: ArrayBuffer, options: AsciiOptions, targetWidth: number, targetHeight: number, onProgress?: (progress: number) => void): Promise<{
93
94
  frames: AsciiFrame[];
@@ -98,22 +99,32 @@ declare function gifToAsciiFrames(buffer: ArrayBuffer, options: AsciiOptions, ta
98
99
  /**
99
100
  * Render an ASCII frame to a canvas context.
100
101
  * Supports both ASCII text mode and Dots mode.
101
- * Always renders every cell at full quality.
102
- *
103
- * Performance strategy:
104
- * - fillRect fast path for sub-6px text (30x faster than fillText)
105
- * - Auto-scaling hover radius: at high cell counts, the hover area
106
- * is proportionally smaller so fewer cells compute hover effects
107
- * - Hover bounding box early-exit skips cells outside the hover zone
108
- *
109
- * @param time - elapsed time in seconds for animation effects
110
- * @param hoverPos - optional smoothed mouse position {x, y, intensity} for hover effect
111
102
  */
112
103
  declare function renderFrameToCanvas(ctx: CanvasRenderingContext2D, frame: AsciiFrame, options: AsciiOptions, canvasWidth: number, canvasHeight: number, time?: number, hoverPos?: {
113
104
  x: number;
114
105
  y: number;
115
106
  intensity?: number;
116
107
  } | null): void;
108
+
109
+ /**
110
+ * Embed code generation — serializes ASCII frames into self-contained
111
+ * HTML snippets that replay via the CDN embed runtime.
112
+ */
113
+
114
+ /**
115
+ * Generate a static single-frame embed snippet.
116
+ */
117
+ declare function generateEmbedCode(frame: AsciiFrame, options: AsciiOptions, width: number, height: number): string;
118
+ /**
119
+ * Generate an animated multi-frame embed snippet (GIF / video).
120
+ */
121
+ declare function generateAnimatedEmbedCode(frames: AsciiFrame[], options: AsciiOptions, fps: number, width: number, height: number): string;
122
+
123
+ /**
124
+ * Simple one-call asciify API.
125
+ * Wraps imageToAsciiFrame + renderFrameToCanvas behind easy-to-use helpers.
126
+ */
127
+
117
128
  interface AsciifySimpleOptions {
118
129
  /** Character size in pixels. Default: 10 */
119
130
  fontSize?: number;
@@ -126,11 +137,7 @@ interface AsciifySimpleOptions {
126
137
  * Convert an image/video/canvas element to ASCII art and render it onto a canvas.
127
138
  *
128
139
  * @example
129
- * const img = document.querySelector('img');
130
- * const canvas = document.querySelector('canvas');
131
- * await asciify(img, canvas);
132
- *
133
- * @example with options
140
+ * await asciify(document.querySelector('img'), canvas);
134
141
  * await asciify(img, canvas, { fontSize: 8, style: 'letters' });
135
142
  */
136
143
  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
141
148
  * @example
142
149
  * const stop = await asciifyGif('animation.gif', canvas);
143
150
  * // later: stop();
144
- *
145
- * @example with style
146
- * const stop = await asciifyGif('animation.gif', canvas, { style: 'letters' });
147
151
  */
148
152
  declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
149
153
  /**
@@ -151,35 +155,11 @@ declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElem
151
155
  * Returns a `stop()` function that cancels the loop.
152
156
  *
153
157
  * @example
154
- * const video = document.querySelector('video');
155
158
  * const stop = await asciifyVideo(video, canvas);
156
159
  * // later: stop();
157
- *
158
- * @example with style
159
- * const stop = await asciifyVideo(video, canvas, { fontSize: 8, style: 'art' });
160
160
  */
161
161
  declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
162
- /**
163
- * Generate a clean embed snippet.
164
- *
165
- * Structure:
166
- * <canvas id> — the render target, short and clean
167
- * <script type=json id> — frame data lives here, clearly separated
168
- * <script src=cdn> — always the same line, cached by browsers
169
- *
170
- * Output (static):
171
- * <!-- Asciify Embed -->
172
- * <canvas id="ar-xxx" data-asciify-opts="{…}" width="…" height="…"></canvas>
173
- * <script type="application/json" id="ar-xxx-d">"BASE64"</script>
174
- * <script src="cdn/embed.js" async></script>
175
- * <!-- /Asciify Embed -->
176
- */
177
- declare function generateEmbedCode(frame: AsciiFrame, options: AsciiOptions, width: number, height: number): string;
178
- /**
179
- * Generate an animated embed snippet for multi-frame (GIF/video) ASCII art.
180
- * Uses the same CDN runtime as generateEmbedCode.
181
- */
182
- declare function generateAnimatedEmbedCode(frames: AsciiFrame[], options: AsciiOptions, fps: number, width: number, height: number): string;
162
+
183
163
  interface WaveBackgroundOptions {
184
164
  /** Font size in CSS pixels (default: 13) */
185
165
  fontSize?: number;
@@ -187,9 +167,9 @@ interface WaveBackgroundOptions {
187
167
  charAspect?: number;
188
168
  /** Line height multiplier (default: 1.4) */
189
169
  lineHeightRatio?: number;
190
- /** Character set from dark→bright (default: ' .·:;=+*#%@░▒▓') */
170
+ /** Character set from dark→bright (default: ' .:-=+*#%@') */
191
171
  chars?: string;
192
- /** Base colour for low-intensity cells — use '{a}' as alpha placeholder (default: white) */
172
+ /** Base colour — use '{a}' as alpha placeholder */
193
173
  baseColor?: string;
194
174
  /** Accent colour applied near the cursor and on wave peaks (default: '#d4ff00') */
195
175
  accentColor?: string;
@@ -197,157 +177,85 @@ interface WaveBackgroundOptions {
197
177
  accentThreshold?: number;
198
178
  /** How strongly the mouse influences local intensity (default: 0.55) */
199
179
  mouseInfluence?: number;
200
- /** Radial falloff for mouse influence — higher = tighter spotlight (default: 2.8) */
180
+ /** Radial falloff for mouse influence (default: 2.8) */
201
181
  mouseFalloff?: number;
202
182
  /** Base wave animation speed (default: 1) */
203
183
  speed?: number;
204
184
  /** Enable vortex swirl effect around cursor (default: true) */
205
185
  vortex?: boolean;
206
- /** Enable sparkle / pop flicker layered on top (default: true) */
186
+ /** Enable sparkle / pop flicker (default: true) */
207
187
  sparkles?: boolean;
208
188
  /** Enable a slow global breathe pulse (default: true) */
209
189
  breathe?: boolean;
210
190
  /** Light mode: swap fill colours to dark-on-light (default: false) */
211
191
  lightMode?: boolean;
212
192
  }
213
- /**
214
- * Render a procedural interactive wave-field of ASCII characters.
215
- *
216
- * Layers stacked per cell:
217
- * 1. Three cardinal sine waves (classic feel)
218
- * 2. Fractal Brownian Motion noise (organic structure)
219
- * 3. Diagonal drift ripple (depth / perspective)
220
- * 4. Slow global breathe pulse (heartbeat)
221
- * 5. Vortex swirl near cursor (energy field)
222
- * 6. Proximity spotlight (cursor highlight)
223
- * 7. Sparkle flickers on bright peaks (life)
224
- *
225
- * Call inside a requestAnimationFrame loop with accumulated time in seconds
226
- * and the current normalised mouse position {x, y} (0-1 range each).
227
- *
228
- * @example
229
- * ```ts
230
- * import { renderWaveBackground } from 'asciify-engine';
231
- *
232
- * const canvas = document.getElementById('bg') as HTMLCanvasElement;
233
- * const ctx = canvas.getContext('2d')!;
234
- * const mouse = { x: 0.5, y: 0.5 };
235
- * canvas.addEventListener('mousemove', e => {
236
- * const r = canvas.getBoundingClientRect();
237
- * mouse.x = (e.clientX - r.left) / r.width;
238
- * mouse.y = (e.clientY - r.top) / r.height;
239
- * });
240
- *
241
- * let t = 0;
242
- * const tick = () => {
243
- * renderWaveBackground(ctx, canvas.clientWidth, canvas.clientHeight, t, mouse);
244
- * t += 0.016;
245
- * requestAnimationFrame(tick);
246
- * };
247
- * requestAnimationFrame(tick);
248
- * ```
249
- */
250
193
  declare function renderWaveBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, mousePos?: {
251
194
  x: number;
252
195
  y: number;
253
196
  }, options?: WaveBackgroundOptions): void;
254
- /**
255
- * Renders a digital-rain ASCII background — independent columns of falling
256
- * characters each with a glowing head and fading tail. Deterministic and
257
- * stateless: derived entirely from elapsed time.
258
- *
259
- * @example
260
- * ```ts
261
- * asciiBackground('#hero', { type: 'rain' });
262
- * ```
263
- */
197
+
264
198
  interface RainBackgroundOptions {
265
199
  fontSize?: number;
266
- /** Characters drawn in columns (one picked randomly per cell per frame). */
200
+ /** Characters drawn in columns */
267
201
  chars?: string;
268
- /** Head / accent colour (default: '#d4ff00'). */
202
+ /** Head / accent colour (default: '#d4ff00') */
269
203
  accentColor?: string;
270
- /** Custom character colour (any CSS colour string). */
204
+ /** Custom character colour */
271
205
  color?: string;
272
- /** Global speed multiplier (default: 1). */
206
+ /** Global speed multiplier (default: 1) */
273
207
  speed?: number;
274
- /** Fraction of columns active at once 0-1 (default: 0.55). */
208
+ /** Fraction of columns active at once 0-1 (default: 0.55) */
275
209
  density?: number;
276
- /** Number of cells in the fading tail (default: 14). */
210
+ /** Number of cells in the fading tail (default: 14) */
277
211
  tailLength?: number;
278
- /** Light mode: dark chars on light background (default: false). */
212
+ /** Light mode (default: false) */
279
213
  lightMode?: boolean;
280
214
  }
281
215
  declare function renderRainBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: RainBackgroundOptions): void;
282
- /**
283
- * Renders a 3-D star-warp / hyperspace ASCII background — ASCII chars fly
284
- * outward from a vanishing point that gently follows the mouse cursor.
285
- * Stars scale up and brighten as they approach the screen edge.
286
- *
287
- * @example
288
- * ```ts
289
- * asciiBackground('#hero', { type: 'stars' });
290
- * ```
291
- */
216
+
292
217
  interface StarsBackgroundOptions {
293
218
  fontSize?: number;
294
- /** Characters used as stars (sparse = more authentic). */
219
+ /** Characters used as stars */
295
220
  chars?: string;
296
- /** Accent/trail colour for fast near-edge stars (default: '#d4ff00'). */
221
+ /** Accent/trail colour for fast near-edge stars (default: '#d4ff00') */
297
222
  accentColor?: string;
298
- /** Custom base colour (any CSS colour string). */
223
+ /** Custom base colour */
299
224
  color?: string;
300
- /** Global speed multiplier (default: 1). */
225
+ /** Global speed multiplier (default: 1) */
301
226
  speed?: number;
302
- /** Number of star particles (default: 180). */
227
+ /** Number of star particles (default: 180) */
303
228
  count?: number;
304
- /** Light mode (default: false). */
229
+ /** Light mode (default: false) */
305
230
  lightMode?: boolean;
306
231
  }
307
232
  declare function renderStarsBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, mousePos?: {
308
233
  x: number;
309
234
  y: number;
310
235
  }, options?: StarsBackgroundOptions): void;
311
- /**
312
- * Concentric ASCII ripples that radiate from a vanishing point following
313
- * the mouse — like a sonar / radar signal.
314
- *
315
- * @example
316
- * ```ts
317
- * asciiBackground('#hero', { type: 'pulse' });
318
- * ```
319
- */
236
+
320
237
  interface PulseBackgroundOptions {
321
- /** Font size in CSS pixels (default: 13). */
322
238
  fontSize?: number;
323
- /** Character ramp dark → bright (default: ' .:-=+*#%@'). */
239
+ /** Characters to tile (default: '. · ○ ◎ ●') */
324
240
  chars?: string;
325
- /** Accent colour on ring crests (default: '#d4ff00'). */
241
+ /** Ring peak colour (default: '#00ffcc') */
326
242
  accentColor?: string;
327
- /** Custom base character colour (any CSS colour string). */
243
+ /** Custom base colour */
328
244
  color?: string;
329
- /** Number of concentric rings (default: 6). */
245
+ /** Number of simultaneous rings (default: 5) */
330
246
  rings?: number;
331
- /** Ring travel speed (default: 1). */
247
+ /** Animation speed (default: 1) */
332
248
  speed?: number;
333
- /** Ring width sharpness higher = thinner rings (default: 4). */
249
+ /** Ring edge sharpness 1–10 (default: 4) */
334
250
  sharpness?: number;
335
- /** Light mode (default: false). */
251
+ /** Light mode (default: false) */
336
252
  lightMode?: boolean;
337
253
  }
338
254
  declare function renderPulseBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, mousePos?: {
339
255
  x: number;
340
256
  y: number;
341
257
  }, options?: PulseBackgroundOptions): void;
342
- /**
343
- * Slow-drifting organic fractal noise field. No directional pattern —
344
- * pure ambient texture. The mouse subtly warps the field around the cursor.
345
- *
346
- * @example
347
- * ```ts
348
- * asciiBackground('#hero', { type: 'noise' });
349
- * ```
350
- */
258
+
351
259
  interface NoiseBackgroundOptions {
352
260
  /** Font size in CSS pixels (default: 14). */
353
261
  fontSize?: number;
@@ -374,15 +282,7 @@ declare function renderNoiseBackground(ctx: CanvasRenderingContext2D, width: num
374
282
  x: number;
375
283
  y: number;
376
284
  }, options?: NoiseBackgroundOptions): void;
377
- /**
378
- * CRT-style horizontal scan-line sweep. Bright scan bands travel downward
379
- * continuously; the cursor creates a local disruption / glitch zone.
380
- *
381
- * @example
382
- * ```ts
383
- * asciiBackground('#hero', { type: 'grid' });
384
- * ```
385
- */
285
+
386
286
  interface GridBackgroundOptions {
387
287
  /** Font size in CSS pixels (default: 12). */
388
288
  fontSize?: number;
@@ -407,10 +307,11 @@ declare function renderGridBackground(ctx: CanvasRenderingContext2D, width: numb
407
307
  x: number;
408
308
  y: number;
409
309
  }, options?: GridBackgroundOptions): void;
310
+
410
311
  interface AuroraBackgroundOptions {
411
312
  /** Character grid density. Default 14. */
412
313
  fontSize?: number;
413
- /** Character ramp from sparse to dense. Default fine gradient ramp. */
314
+ /** Character ramp from sparse to dense. */
414
315
  chars?: string;
415
316
  /** Base character color. Default theme-aware white/black. */
416
317
  color?: string;
@@ -431,39 +332,96 @@ declare function renderAuroraBackground(ctx: CanvasRenderingContext2D, width: nu
431
332
  x: number;
432
333
  y: number;
433
334
  }, options?: AuroraBackgroundOptions): void;
335
+
336
+ interface SilkBackgroundOptions {
337
+ /** Character grid density. Default 13. */
338
+ fontSize?: number;
339
+ /** Base character color. Default theme-aware white/black. */
340
+ color?: string;
341
+ /** Accent color for intensity peaks. Default '#d4ff00'. */
342
+ accentColor?: string;
343
+ /** Animation speed multiplier. Default 0.4 (intentionally slow). */
344
+ speed?: number;
345
+ /** Number of flow-field layers. More = richer ribbons. Default 4. */
346
+ layers?: number;
347
+ /** Flow turbulence (0–2). Higher = more folded, tangled ribbons. Default 0.8. */
348
+ turbulence?: number;
349
+ /** Force light mode. Default false. */
350
+ lightMode?: boolean;
351
+ }
352
+ declare function renderSilkBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: SilkBackgroundOptions): void;
353
+
354
+ interface VoidBackgroundOptions {
355
+ /** Character grid density. Default 13. */
356
+ fontSize?: number;
357
+ /** Character ramp. Default space-to-dense. */
358
+ chars?: string;
359
+ /** Base character color. Default theme-aware. */
360
+ color?: string;
361
+ /** Accent color for the inner singularity ring. Default '#d4ff00'. */
362
+ accentColor?: string;
363
+ /** Animation speed multiplier. Default 1. */
364
+ speed?: number;
365
+ /** Gravity well radius (fraction of canvas width). Default 0.38. */
366
+ radius?: number;
367
+ /** Spiral tightness — higher = more rotation per unit distance. Default 3. */
368
+ swirl?: number;
369
+ /** Force light mode. Default false. */
370
+ lightMode?: boolean;
371
+ }
372
+ declare function renderVoidBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, mousePos?: {
373
+ x: number;
374
+ y: number;
375
+ }, options?: VoidBackgroundOptions): void;
376
+
377
+ interface MorphBackgroundOptions {
378
+ /** Character grid density. Default 14. */
379
+ fontSize?: number;
380
+ /** Character ramp. Default clean gradient. */
381
+ chars?: string;
382
+ /** Base character color. Default theme-aware. */
383
+ color?: string;
384
+ /** Accent color for intensity peaks. Default '#d4ff00'. */
385
+ accentColor?: string;
386
+ /** Animation speed multiplier. Default 0.5 (intentionally slow). */
387
+ speed?: number;
388
+ /** How many frequency harmonics per cell. More = richer shimmer. Default 3. */
389
+ harmonics?: number;
390
+ /** Force light mode. Default false. */
391
+ lightMode?: boolean;
392
+ }
393
+ declare function renderMorphBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: MorphBackgroundOptions): void;
394
+
434
395
  /**
435
- * Drop-in helper that mounts an interactive ASCII wave background onto any
436
- * element. Injects a canvas, wires DPR resize, mouse tracking, and the RAF
437
- * loop — all internally. Auto-detects light/dark mode and stays in sync if
438
- * the system theme changes.
439
- *
440
- * Returns a `destroy()` function to clean everything up.
396
+ * ASCII Background public entry point for the backgrounds sub-system.
441
397
  *
442
- * @example
443
- * ```ts
444
- * import { asciiBackground } from 'asciify-engine';
445
- *
446
- * // 1 line:
447
- * const { destroy } = asciiBackground('#hero', { opacity: 0.2 });
448
- *
449
- * // Custom color:
450
- * asciiBackground('#hero', { color: '#6b8700', accentColor: '#d4ff00' });
451
- *
452
- * // React — return destroy as cleanup:
453
- * useEffect(() => asciiBackground(ref.current).destroy, []);
454
- * ```
398
+ * Exports:
399
+ * - All 10 render functions
400
+ * - All 10 option interfaces
401
+ * - `AsciiBackgroundOptions` — combined union type + mount options
402
+ * - `asciiBackground()` the drop-in mount helper
403
+ * - `mountWaveBackground` / `MountWaveOptions` deprecated aliases
455
404
  */
456
- interface AsciiBackgroundOptions extends WaveBackgroundOptions, RainBackgroundOptions, StarsBackgroundOptions, PulseBackgroundOptions, NoiseBackgroundOptions, GridBackgroundOptions, AuroraBackgroundOptions {
405
+
406
+ /**
407
+ * Combined options for `asciiBackground()`. Extends all 10 background option
408
+ * interfaces so every background's options can be passed through one object.
409
+ */
410
+ interface AsciiBackgroundOptions extends WaveBackgroundOptions, RainBackgroundOptions, StarsBackgroundOptions, PulseBackgroundOptions, NoiseBackgroundOptions, GridBackgroundOptions, AuroraBackgroundOptions, SilkBackgroundOptions, VoidBackgroundOptions, MorphBackgroundOptions {
457
411
  /**
458
412
  * Which background to render (default: 'wave').
459
- * - 'wave' — interactive ASCII field with vortex, sparkles, breathe
460
- * - 'rain' — digital column rain (Matrix-style falling characters)
461
- * - 'stars' — 3D star-warp / hyperspace (chars fly toward the viewer)
462
- * - 'pulse' — concentric ASCII ripples radiating from the mouse position
463
- * - 'noise' — slow-drifting organic fractal noise field
464
- * - 'grid' — CRT-style horizontal scan bands with cursor glitch zone
413
+ * - 'wave' — interactive ASCII field with vortex, sparkles, breathe
414
+ * - 'rain' — digital column rain (Matrix-style falling characters)
415
+ * - 'stars' — 3D star-warp / hyperspace chars fly toward the viewer
416
+ * - 'pulse' — concentric ASCII ripples radiating from the mouse
417
+ * - 'noise' — slow-drifting organic fractal noise field
418
+ * - 'grid' — CRT-style horizontal scan bands with cursor glitch zone
419
+ * - 'aurora' — premium slow-drifting light bands
420
+ * - 'silk' — smooth directional flow-field ribbons
421
+ * - 'void' — gravitational singularity follows the cursor
422
+ * - 'morph' — per-cell multi-frequency shimmer
465
423
  */
466
- type?: 'wave' | 'rain' | 'stars' | 'pulse' | 'noise' | 'grid' | 'aurora';
424
+ type?: 'wave' | 'rain' | 'stars' | 'pulse' | 'noise' | 'grid' | 'aurora' | 'silk' | 'void' | 'morph';
467
425
  /** CSS opacity applied to the canvas element (default: 0.2) */
468
426
  opacity?: number;
469
427
  /** Extra CSS class names added to the injected canvas */
@@ -472,18 +430,34 @@ interface AsciiBackgroundOptions extends WaveBackgroundOptions, RainBackgroundOp
472
430
  zIndex?: number;
473
431
  /**
474
432
  * Colour scheme handling (default: 'auto').
475
- * - 'auto' — follows the system prefers-color-scheme and updates live
433
+ * - 'auto' — follows system prefers-color-scheme and updates live
476
434
  * - 'dark' — always render bright chars on dark background
477
435
  * - 'light' — always render dark chars on light background
478
436
  */
479
437
  colorScheme?: 'auto' | 'light' | 'dark';
480
438
  /**
481
439
  * Custom character colour. Accepts any CSS colour string: hex, rgb(), hsl().
482
- * Overrides the default white/black for the ASCII chars.
440
+ * Overrides the default white/black for ASCII chars.
483
441
  * @example '#6b8700'
484
442
  */
485
443
  color?: string;
486
444
  }
445
+ /**
446
+ * Drop-in helper that mounts an interactive ASCII background onto any element.
447
+ * Injects a canvas, wires DPR resize, mouse tracking, and the RAF loop.
448
+ * Auto-detects light/dark mode and stays in sync if the system theme changes.
449
+ *
450
+ * Returns a `destroy()` function to clean everything up.
451
+ *
452
+ * @example
453
+ * ```ts
454
+ * // 1 line:
455
+ * const { destroy } = asciiBackground('#hero', { opacity: 0.2 });
456
+ *
457
+ * // React — return destroy as cleanup:
458
+ * useEffect(() => asciiBackground(ref.current).destroy, []);
459
+ * ```
460
+ */
487
461
  declare function asciiBackground(target: string | HTMLElement | null, options?: AsciiBackgroundOptions): {
488
462
  destroy: () => void;
489
463
  };
@@ -509,4 +483,4 @@ interface WebGLRenderer {
509
483
  */
510
484
  declare function tryCreateWebGLRenderer(canvas: HTMLCanvasElement): WebGLRenderer | null;
511
485
 
512
- export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, type AuroraBackgroundOptions, CHARSETS, type CharsetKey, type ColorMode, DEFAULT_OPTIONS, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MountWaveOptions, type NoiseBackgroundOptions, type PulseBackgroundOptions, type RainBackgroundOptions, type RenderMode, type SourceType, type StarsBackgroundOptions, type WaveBackgroundOptions, type WebGLRenderer, asciiBackground, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderAuroraBackground, renderFrameToCanvas, renderGridBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderStarsBackground, renderWaveBackground, tryCreateWebGLRenderer, videoToAsciiFrames };
486
+ export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, type AuroraBackgroundOptions, CHARSETS, type CharsetKey, type ColorMode, DEFAULT_OPTIONS, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MorphBackgroundOptions, type MountWaveOptions, type NoiseBackgroundOptions, type PulseBackgroundOptions, type RainBackgroundOptions, type RenderMode, type SilkBackgroundOptions, type SourceType, type StarsBackgroundOptions, type VoidBackgroundOptions, type WaveBackgroundOptions, type WebGLRenderer, asciiBackground, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderAuroraBackground, renderFrameToCanvas, renderGridBackground, renderMorphBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderSilkBackground, renderStarsBackground, renderVoidBackground, renderWaveBackground, tryCreateWebGLRenderer, videoToAsciiFrames };