asciify-engine 1.0.23 → 1.0.24

package/dist/index.d.cts

@@ -1,9 +1,20 @@
 type ColorMode = 'grayscale' | 'fullcolor' | 'matrix' | 'accent';
 type RenderMode = 'ascii' | 'dots';
-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';
+type AnimationStyle = 'none' | 'wave' | 'pulse' | 'rain' | 'breathe' | 'sparkle' | 'glitch' | 'spiral' | 'typewriter' | 'scatter' | 'waveField' | 'ripple' | 'melt' | 'orbit' | 'cellular';
+type ArtStyle = 'classic' | 'particles' | 'letters' | 'claudeCode' | 'art' | 'terminal' | 'box' | 'lines' | 'braille' | 'katakana' | 'musical' | 'emoji';
+type HoverEffect = 'spotlight' | 'magnify' | 'repel' | 'glow' | 'colorShift' | 'attract' | 'shatter' | 'trail';
+type HoverPreset = 'none' | 'subtle' | 'flashlight' | 'magnifier' | 'forceField' | 'neon' | 'fire' | 'ice' | 'gravity' | 'shatter' | 'ghost';
+/**
+ * Named colour palette presets — pass as `colorMode` for themed rendering.
+ * Applied as a post-process colour remap over the standard grayscale output.
+ */
+type PaletteTheme = 'dracula' | 'monokai' | 'nord' | 'catppuccin' | 'solarized' | 'gruvbox';
+declare const PALETTE_THEMES: Record<PaletteTheme, {
+    name: string;
+    accent: string;
+    bg: string;
+    fg: string;
+}>;
 type SourceType = 'image' | 'video' | 'gif' | null;
 interface AsciiOptions {
     fontSize: number;
@@ -44,13 +55,17 @@ declare const CHARSETS: {
     readonly standard: " .:-=+*#%@";
     readonly blocks: " ░▒▓█";
     readonly minimal: " .:+";
-    readonly dense: " .'`^\",:;Il!i><~+_-?][}{1)(|\\/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$";
+    readonly dense: " .'`^\",:;Il!i><~+_-?][}{1)(|/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$";
     readonly binary: "01";
     readonly dots: " ⠁⠃⠇⡇⣇⣧⣷⣿";
     readonly letters: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
     readonly claudeCode: " ╔╗╚╝║═╠╣╦╩╬░▒▓█│─┌┐└┘├┤┬┴┼";
     readonly box: " ▪◾◼■█";
     readonly lines: " ˗‐–—―━";
+    readonly braille: " ⠁⠂⠃⠄⠅⠆⠇⠈⠉⠊⠋⠌⠍⠎⠏⠐⠑⠒⠓⠔⠕⠖⠗⠘⠙⠚⠛⠜⠝⠞⠟⠠⠡⠢⠣⠤⠥⠦⠧⠨⠩⠪⠫⠬⠭⠮⠯⠰⠱⠲⠳⠴⠵⠶⠷⠸⠹⠺⠻⠼⠽⠾⠿⡀⡁⡂⡃⡄⡅⡆⡇⣀⣁⣂⣃⣄⣅⣆⣇⣈⣉⣊⣋⣌⣍⣎⣏⣐⣑⣒⣓⣔⣕⣖⣗⣘⣙⣚⣛⣜⣝⣞⣟⣠⣡⣢⣣⣤⣥⣦⣧⣨⣩⣪⣫⣬⣭⣮⣯⣰⣱⣲⣳⣴⣵⣶⣷⣸⣹⣺⣻⣼⣽⣾⣿";
+    readonly katakana: " ｦｧｨｩｪｫｬｭｮｯｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾔﾕﾖﾗﾘﾙﾚﾛﾜﾝ";
+    readonly musical: " ♩♪♫♬♭♮♯";
+    readonly emoji: " ⬛🟫🟥🟧🟨🟩🟦🟪⬜";
 };
 type CharsetKey = keyof typeof CHARSETS;
 /**
@@ -392,6 +407,90 @@ interface MorphBackgroundOptions {
 }
 declare function renderMorphBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: MorphBackgroundOptions): void;
 
+interface FireBackgroundOptions {
+    /** Font size in CSS pixels (default: 13) */
+    fontSize?: number;
+    /** Characters mapped from cool→hot (default: ' .,:;i+xX#&@') */
+    chars?: string;
+    /** Base flame colour (default: '#ff4500') */
+    color?: string;
+    /** Secondary hot-tip colour (default: '#ffe066') */
+    hotColor?: string;
+    /** Flame intensity 0–1 (default: 0.85) */
+    intensity?: number;
+    /** Horizontal wind force -1..1 (default: 0) */
+    wind?: number;
+    /** Global speed multiplier (default: 1) */
+    speed?: number;
+    /** Light mode: invert text colours (default: false) */
+    lightMode?: boolean;
+}
+declare function renderFireBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: FireBackgroundOptions): void;
+
+interface DnaBackgroundOptions {
+    /** Font size in CSS pixels (default: 13) */
+    fontSize?: number;
+    /** Characters for strand nodes (default: 'ATCG') */
+    baseChars?: string;
+    /** Characters for the connectors between strands (default: '-=≡') */
+    bridgeChars?: string;
+    /** Primary strand colour (default: '#00e5ff') */
+    color?: string;
+    /** Secondary strand colour (default: '#ff4081') */
+    color2?: string;
+    /** Bridge / connector colour (default: '#88ffcc') */
+    bridgeColor?: string;
+    /** Speed multiplier (default: 1) */
+    speed?: number;
+    /** Number of helix columns (default: auto, ~1 per 80px) */
+    helixCount?: number;
+    /** Light mode (default: false) */
+    lightMode?: boolean;
+}
+declare function renderDnaBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: DnaBackgroundOptions): void;
+
+interface TerrainBackgroundOptions {
+    /** Font size in CSS pixels (default: 13) */
+    fontSize?: number;
+    /** Characters for terrain density (default: ' .,:;+*#@') */
+    chars?: string;
+    /** Foreground ground colour (default: '#4caf50') */
+    color?: string;
+    /** Sky / star colour (default: '#1a237e') */
+    skyColor?: string;
+    /** Peak / snow-cap colour (default: '#e0e0e0') */
+    peakColor?: string;
+    /** Horizontal scroll speed (default: 1) */
+    speed?: number;
+    /** Terrain roughness 0.1–1 (default: 0.55) */
+    roughness?: number;
+    /** Mountain height fraction 0–1 (default: 0.55) */
+    heightScale?: number;
+    /** Show faint background stars (default: true) */
+    stars?: boolean;
+    /** Light mode (default: false) */
+    lightMode?: boolean;
+}
+declare function renderTerrainBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: TerrainBackgroundOptions): void;
+
+interface CircuitBackgroundOptions {
+    /** Font size in CSS pixels (default: 13) */
+    fontSize?: number;
+    /** Trace characters (default: '─│┌┐└┘├┤┬┴┼') */
+    chars?: string;
+    /** Trace colour (default: '#00ff88') */
+    color?: string;
+    /** Signal pulse colour (default: '#ffffff') */
+    pulseColor?: string;
+    /** Fraction of cells that have a trace (default: 0.38) */
+    density?: number;
+    /** Signal pulse speed (default: 1) */
+    speed?: number;
+    /** Light mode (default: false) */
+    lightMode?: boolean;
+}
+declare function renderCircuitBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: CircuitBackgroundOptions): void;
+
 /**
  * ASCII Background — public entry point for the backgrounds sub-system.
  *
@@ -407,7 +506,7 @@ declare function renderMorphBackground(ctx: CanvasRenderingContext2D, width: num
  * 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 {
+interface AsciiBackgroundOptions extends WaveBackgroundOptions, RainBackgroundOptions, StarsBackgroundOptions, PulseBackgroundOptions, NoiseBackgroundOptions, GridBackgroundOptions, AuroraBackgroundOptions, SilkBackgroundOptions, VoidBackgroundOptions, MorphBackgroundOptions, FireBackgroundOptions, DnaBackgroundOptions, TerrainBackgroundOptions, CircuitBackgroundOptions {
     /**
      * Which background to render (default: 'wave').
      * - 'wave'   — interactive ASCII field with vortex, sparkles, breathe
@@ -420,8 +519,12 @@ interface AsciiBackgroundOptions extends WaveBackgroundOptions, RainBackgroundOp
      * - 'silk'   — smooth directional flow-field ribbons
      * - 'void'   — gravitational singularity follows the cursor
      * - 'morph'  — per-cell multi-frequency shimmer
+     * - 'fire'    — upward cellular-automata flame simulation
+     * - 'dna'     — double-helix strand scrolling with base-pair chars
+     * - 'terrain' — scrolling ASCII side-scroll heightmap landscape
+     * - 'circuit' — procedural PCB traces with traveling signal pulses
      */
-    type?: 'wave' | 'rain' | 'stars' | 'pulse' | 'noise' | 'grid' | 'aurora' | 'silk' | 'void' | 'morph';
+    type?: 'wave' | 'rain' | 'stars' | 'pulse' | 'noise' | 'grid' | 'aurora' | 'silk' | 'void' | 'morph' | 'fire' | 'dna' | 'terrain' | 'circuit';
     /** CSS opacity applied to the canvas element (default: 0.2) */
     opacity?: number;
     /** Extra CSS class names added to the injected canvas */
@@ -466,6 +569,105 @@ declare const mountWaveBackground: typeof asciiBackground;
 /** @deprecated Use `AsciiBackgroundOptions` instead. */
 type MountWaveOptions = AsciiBackgroundOptions;
 
+/**
+ * asciiText — pure string output (no canvas required).
+ * Converts an image/video/canvas element to a plain-text ASCII string
+ * suitable for server-side rendering, clipboard export, or terminal output.
+ */
+
+/**
+ * Convert any image/video/canvas source to a plain multi-line string of ASCII.
+ *
+ * @example
+ * ```ts
+ * const text = asciiText(imgEl, { fontSize: 8, colorMode: 'grayscale' });
+ * console.log(text);
+ * ```
+ *
+ * @example SSR (Node/JSDOM)
+ * ```ts
+ * const { createCanvas, loadImage } = require('@napi-rs/canvas');
+ * const img = await loadImage('./photo.jpg');
+ * const canvas = createCanvas(img.width, img.height);
+ * const ctx = canvas.getContext('2d');
+ * ctx.drawImage(img, 0, 0);
+ * const text = asciiText(canvas as unknown as HTMLCanvasElement, { fontSize: 10 });
+ * ```
+ */
+declare function asciiText(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement, options?: Partial<AsciiOptions>, targetWidth?: number, targetHeight?: number): string;
+/**
+ * Convert any source to an ASCII string with ANSI 256-colour escape codes.
+ * Works in any terminal that supports ANSI colours.
+ *
+ * @example
+ * ```ts
+ * process.stdout.write(asciiTextAnsi(imgEl, { fontSize: 8 }));
+ * ```
+ */
+declare function asciiTextAnsi(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement, options?: Partial<AsciiOptions>, targetWidth?: number, targetHeight?: number): string;
+
+/**
+ * record() — capture a rolling frame buffer from a running ASCII canvas
+ * and export it as a downloadable animated GIF or WebP data URL.
+ *
+ * Usage:
+ * ```ts
+ * const recorder = createRecorder(canvasEl, { fps: 15, maxFrames: 120 });
+ * recorder.start();
+ * // ... after a few seconds ...
+ * const dataUrl = await recorder.stop(); // 'data:image/gif;base64,...'
+ * ```
+ */
+interface RecorderOptions {
+    /** Target capture frame rate (default: 15) */
+    fps?: number;
+    /** Maximum number of frames to buffer (default: 120 → 8 s at 15 fps) */
+    maxFrames?: number;
+    /**
+     * Output format.
+     * - 'gif'  — animated GIF via gif.js worker (requires gif.worker.js in public/)
+     * - 'webp' — animated WebP via MediaRecorder API (Chrome/Edge only)
+     * - 'png-sequence' — returns a JSON array of PNG data URLs (universal)
+     * Default: 'gif'
+     */
+    format?: 'gif' | 'webp' | 'png-sequence';
+    /** GIF quality 1 (best) – 30 (smallest) — only used for format:'gif' (default: 10) */
+    quality?: number;
+    /**
+     * Scale factor applied to the canvas before capture (default: 1).
+     * Use 0.5 to halve dimensions and reduce file size.
+     */
+    scale?: number;
+}
+interface Recorder {
+    /** Start capturing frames from the canvas. */
+    start(): void;
+    /**
+     * Stop capturing and encode.
+     * Resolves with a data URL (gif/webp) or JSON string (png-sequence).
+     */
+    stop(): Promise<string>;
+    /** True while recording. */
+    readonly isRecording: boolean;
+    /** Number of frames captured so far. */
+    readonly frameCount: number;
+}
+/**
+ * Create a Recorder bound to a canvas element.
+ */
+declare function createRecorder(canvas: HTMLCanvasElement, options?: RecorderOptions): Recorder;
+/**
+ * Convenience: record for a fixed duration and auto-download.
+ *
+ * @example
+ * ```ts
+ * await recordAndDownload(canvasEl, 3000, { fps: 15, format: 'gif' });
+ * ```
+ */
+declare function recordAndDownload(canvas: HTMLCanvasElement, durationMs: number, options?: RecorderOptions & {
+    filename?: string;
+}): Promise<void>;
+
 interface WebGLRenderer {
     render(frame: AsciiFrame, options: AsciiOptions, displayW: number, displayH: number, time: number, hoverPos?: {
         x: number;
@@ -483,4 +685,4 @@ interface WebGLRenderer {
  */
 declare function tryCreateWebGLRenderer(canvas: HTMLCanvasElement): WebGLRenderer | null;
 
-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 };
+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 CircuitBackgroundOptions, type ColorMode, DEFAULT_OPTIONS, type DnaBackgroundOptions, type FireBackgroundOptions, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MorphBackgroundOptions, type MountWaveOptions, type NoiseBackgroundOptions, PALETTE_THEMES, type PaletteTheme, type PulseBackgroundOptions, type RainBackgroundOptions, type Recorder, type RecorderOptions, type RenderMode, type SilkBackgroundOptions, type SourceType, type StarsBackgroundOptions, type TerrainBackgroundOptions, type VoidBackgroundOptions, type WaveBackgroundOptions, type WebGLRenderer, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyVideo, createRecorder, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, recordAndDownload, renderAuroraBackground, renderCircuitBackground, renderDnaBackground, renderFireBackground, renderFrameToCanvas, renderGridBackground, renderMorphBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderSilkBackground, renderStarsBackground, renderTerrainBackground, renderVoidBackground, renderWaveBackground, tryCreateWebGLRenderer, videoToAsciiFrames };

package/dist/index.d.ts

@@ -1,9 +1,20 @@
 type ColorMode = 'grayscale' | 'fullcolor' | 'matrix' | 'accent';
 type RenderMode = 'ascii' | 'dots';
-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';
+type AnimationStyle = 'none' | 'wave' | 'pulse' | 'rain' | 'breathe' | 'sparkle' | 'glitch' | 'spiral' | 'typewriter' | 'scatter' | 'waveField' | 'ripple' | 'melt' | 'orbit' | 'cellular';
+type ArtStyle = 'classic' | 'particles' | 'letters' | 'claudeCode' | 'art' | 'terminal' | 'box' | 'lines' | 'braille' | 'katakana' | 'musical' | 'emoji';
+type HoverEffect = 'spotlight' | 'magnify' | 'repel' | 'glow' | 'colorShift' | 'attract' | 'shatter' | 'trail';
+type HoverPreset = 'none' | 'subtle' | 'flashlight' | 'magnifier' | 'forceField' | 'neon' | 'fire' | 'ice' | 'gravity' | 'shatter' | 'ghost';
+/**
+ * Named colour palette presets — pass as `colorMode` for themed rendering.
+ * Applied as a post-process colour remap over the standard grayscale output.
+ */
+type PaletteTheme = 'dracula' | 'monokai' | 'nord' | 'catppuccin' | 'solarized' | 'gruvbox';
+declare const PALETTE_THEMES: Record<PaletteTheme, {
+    name: string;
+    accent: string;
+    bg: string;
+    fg: string;
+}>;
 type SourceType = 'image' | 'video' | 'gif' | null;
 interface AsciiOptions {
     fontSize: number;
@@ -44,13 +55,17 @@ declare const CHARSETS: {
     readonly standard: " .:-=+*#%@";
     readonly blocks: " ░▒▓█";
     readonly minimal: " .:+";
-    readonly dense: " .'`^\",:;Il!i><~+_-?][}{1)(|\\/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$";
+    readonly dense: " .'`^\",:;Il!i><~+_-?][}{1)(|/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$";
     readonly binary: "01";
     readonly dots: " ⠁⠃⠇⡇⣇⣧⣷⣿";
     readonly letters: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
     readonly claudeCode: " ╔╗╚╝║═╠╣╦╩╬░▒▓█│─┌┐└┘├┤┬┴┼";
     readonly box: " ▪◾◼■█";
     readonly lines: " ˗‐–—―━";
+    readonly braille: " ⠁⠂⠃⠄⠅⠆⠇⠈⠉⠊⠋⠌⠍⠎⠏⠐⠑⠒⠓⠔⠕⠖⠗⠘⠙⠚⠛⠜⠝⠞⠟⠠⠡⠢⠣⠤⠥⠦⠧⠨⠩⠪⠫⠬⠭⠮⠯⠰⠱⠲⠳⠴⠵⠶⠷⠸⠹⠺⠻⠼⠽⠾⠿⡀⡁⡂⡃⡄⡅⡆⡇⣀⣁⣂⣃⣄⣅⣆⣇⣈⣉⣊⣋⣌⣍⣎⣏⣐⣑⣒⣓⣔⣕⣖⣗⣘⣙⣚⣛⣜⣝⣞⣟⣠⣡⣢⣣⣤⣥⣦⣧⣨⣩⣪⣫⣬⣭⣮⣯⣰⣱⣲⣳⣴⣵⣶⣷⣸⣹⣺⣻⣼⣽⣾⣿";
+    readonly katakana: " ｦｧｨｩｪｫｬｭｮｯｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾔﾕﾖﾗﾘﾙﾚﾛﾜﾝ";
+    readonly musical: " ♩♪♫♬♭♮♯";
+    readonly emoji: " ⬛🟫🟥🟧🟨🟩🟦🟪⬜";
 };
 type CharsetKey = keyof typeof CHARSETS;
 /**
@@ -392,6 +407,90 @@ interface MorphBackgroundOptions {
 }
 declare function renderMorphBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: MorphBackgroundOptions): void;
 
+interface FireBackgroundOptions {
+    /** Font size in CSS pixels (default: 13) */
+    fontSize?: number;
+    /** Characters mapped from cool→hot (default: ' .,:;i+xX#&@') */
+    chars?: string;
+    /** Base flame colour (default: '#ff4500') */
+    color?: string;
+    /** Secondary hot-tip colour (default: '#ffe066') */
+    hotColor?: string;
+    /** Flame intensity 0–1 (default: 0.85) */
+    intensity?: number;
+    /** Horizontal wind force -1..1 (default: 0) */
+    wind?: number;
+    /** Global speed multiplier (default: 1) */
+    speed?: number;
+    /** Light mode: invert text colours (default: false) */
+    lightMode?: boolean;
+}
+declare function renderFireBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: FireBackgroundOptions): void;
+
+interface DnaBackgroundOptions {
+    /** Font size in CSS pixels (default: 13) */
+    fontSize?: number;
+    /** Characters for strand nodes (default: 'ATCG') */
+    baseChars?: string;
+    /** Characters for the connectors between strands (default: '-=≡') */
+    bridgeChars?: string;
+    /** Primary strand colour (default: '#00e5ff') */
+    color?: string;
+    /** Secondary strand colour (default: '#ff4081') */
+    color2?: string;
+    /** Bridge / connector colour (default: '#88ffcc') */
+    bridgeColor?: string;
+    /** Speed multiplier (default: 1) */
+    speed?: number;
+    /** Number of helix columns (default: auto, ~1 per 80px) */
+    helixCount?: number;
+    /** Light mode (default: false) */
+    lightMode?: boolean;
+}
+declare function renderDnaBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: DnaBackgroundOptions): void;
+
+interface TerrainBackgroundOptions {
+    /** Font size in CSS pixels (default: 13) */
+    fontSize?: number;
+    /** Characters for terrain density (default: ' .,:;+*#@') */
+    chars?: string;
+    /** Foreground ground colour (default: '#4caf50') */
+    color?: string;
+    /** Sky / star colour (default: '#1a237e') */
+    skyColor?: string;
+    /** Peak / snow-cap colour (default: '#e0e0e0') */
+    peakColor?: string;
+    /** Horizontal scroll speed (default: 1) */
+    speed?: number;
+    /** Terrain roughness 0.1–1 (default: 0.55) */
+    roughness?: number;
+    /** Mountain height fraction 0–1 (default: 0.55) */
+    heightScale?: number;
+    /** Show faint background stars (default: true) */
+    stars?: boolean;
+    /** Light mode (default: false) */
+    lightMode?: boolean;
+}
+declare function renderTerrainBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: TerrainBackgroundOptions): void;
+
+interface CircuitBackgroundOptions {
+    /** Font size in CSS pixels (default: 13) */
+    fontSize?: number;
+    /** Trace characters (default: '─│┌┐└┘├┤┬┴┼') */
+    chars?: string;
+    /** Trace colour (default: '#00ff88') */
+    color?: string;
+    /** Signal pulse colour (default: '#ffffff') */
+    pulseColor?: string;
+    /** Fraction of cells that have a trace (default: 0.38) */
+    density?: number;
+    /** Signal pulse speed (default: 1) */
+    speed?: number;
+    /** Light mode (default: false) */
+    lightMode?: boolean;
+}
+declare function renderCircuitBackground(ctx: CanvasRenderingContext2D, width: number, height: number, time: number, options?: CircuitBackgroundOptions): void;
+
 /**
  * ASCII Background — public entry point for the backgrounds sub-system.
  *
@@ -407,7 +506,7 @@ declare function renderMorphBackground(ctx: CanvasRenderingContext2D, width: num
  * 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 {
+interface AsciiBackgroundOptions extends WaveBackgroundOptions, RainBackgroundOptions, StarsBackgroundOptions, PulseBackgroundOptions, NoiseBackgroundOptions, GridBackgroundOptions, AuroraBackgroundOptions, SilkBackgroundOptions, VoidBackgroundOptions, MorphBackgroundOptions, FireBackgroundOptions, DnaBackgroundOptions, TerrainBackgroundOptions, CircuitBackgroundOptions {
     /**
      * Which background to render (default: 'wave').
      * - 'wave'   — interactive ASCII field with vortex, sparkles, breathe
@@ -420,8 +519,12 @@ interface AsciiBackgroundOptions extends WaveBackgroundOptions, RainBackgroundOp
      * - 'silk'   — smooth directional flow-field ribbons
      * - 'void'   — gravitational singularity follows the cursor
      * - 'morph'  — per-cell multi-frequency shimmer
+     * - 'fire'    — upward cellular-automata flame simulation
+     * - 'dna'     — double-helix strand scrolling with base-pair chars
+     * - 'terrain' — scrolling ASCII side-scroll heightmap landscape
+     * - 'circuit' — procedural PCB traces with traveling signal pulses
      */
-    type?: 'wave' | 'rain' | 'stars' | 'pulse' | 'noise' | 'grid' | 'aurora' | 'silk' | 'void' | 'morph';
+    type?: 'wave' | 'rain' | 'stars' | 'pulse' | 'noise' | 'grid' | 'aurora' | 'silk' | 'void' | 'morph' | 'fire' | 'dna' | 'terrain' | 'circuit';
     /** CSS opacity applied to the canvas element (default: 0.2) */
     opacity?: number;
     /** Extra CSS class names added to the injected canvas */
@@ -466,6 +569,105 @@ declare const mountWaveBackground: typeof asciiBackground;
 /** @deprecated Use `AsciiBackgroundOptions` instead. */
 type MountWaveOptions = AsciiBackgroundOptions;
 
+/**
+ * asciiText — pure string output (no canvas required).
+ * Converts an image/video/canvas element to a plain-text ASCII string
+ * suitable for server-side rendering, clipboard export, or terminal output.
+ */
+
+/**
+ * Convert any image/video/canvas source to a plain multi-line string of ASCII.
+ *
+ * @example
+ * ```ts
+ * const text = asciiText(imgEl, { fontSize: 8, colorMode: 'grayscale' });
+ * console.log(text);
+ * ```
+ *
+ * @example SSR (Node/JSDOM)
+ * ```ts
+ * const { createCanvas, loadImage } = require('@napi-rs/canvas');
+ * const img = await loadImage('./photo.jpg');
+ * const canvas = createCanvas(img.width, img.height);
+ * const ctx = canvas.getContext('2d');
+ * ctx.drawImage(img, 0, 0);
+ * const text = asciiText(canvas as unknown as HTMLCanvasElement, { fontSize: 10 });
+ * ```
+ */
+declare function asciiText(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement, options?: Partial<AsciiOptions>, targetWidth?: number, targetHeight?: number): string;
+/**
+ * Convert any source to an ASCII string with ANSI 256-colour escape codes.
+ * Works in any terminal that supports ANSI colours.
+ *
+ * @example
+ * ```ts
+ * process.stdout.write(asciiTextAnsi(imgEl, { fontSize: 8 }));
+ * ```
+ */
+declare function asciiTextAnsi(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement, options?: Partial<AsciiOptions>, targetWidth?: number, targetHeight?: number): string;
+
+/**
+ * record() — capture a rolling frame buffer from a running ASCII canvas
+ * and export it as a downloadable animated GIF or WebP data URL.
+ *
+ * Usage:
+ * ```ts
+ * const recorder = createRecorder(canvasEl, { fps: 15, maxFrames: 120 });
+ * recorder.start();
+ * // ... after a few seconds ...
+ * const dataUrl = await recorder.stop(); // 'data:image/gif;base64,...'
+ * ```
+ */
+interface RecorderOptions {
+    /** Target capture frame rate (default: 15) */
+    fps?: number;
+    /** Maximum number of frames to buffer (default: 120 → 8 s at 15 fps) */
+    maxFrames?: number;
+    /**
+     * Output format.
+     * - 'gif'  — animated GIF via gif.js worker (requires gif.worker.js in public/)
+     * - 'webp' — animated WebP via MediaRecorder API (Chrome/Edge only)
+     * - 'png-sequence' — returns a JSON array of PNG data URLs (universal)
+     * Default: 'gif'
+     */
+    format?: 'gif' | 'webp' | 'png-sequence';
+    /** GIF quality 1 (best) – 30 (smallest) — only used for format:'gif' (default: 10) */
+    quality?: number;
+    /**
+     * Scale factor applied to the canvas before capture (default: 1).
+     * Use 0.5 to halve dimensions and reduce file size.
+     */
+    scale?: number;
+}
+interface Recorder {
+    /** Start capturing frames from the canvas. */
+    start(): void;
+    /**
+     * Stop capturing and encode.
+     * Resolves with a data URL (gif/webp) or JSON string (png-sequence).
+     */
+    stop(): Promise<string>;
+    /** True while recording. */
+    readonly isRecording: boolean;
+    /** Number of frames captured so far. */
+    readonly frameCount: number;
+}
+/**
+ * Create a Recorder bound to a canvas element.
+ */
+declare function createRecorder(canvas: HTMLCanvasElement, options?: RecorderOptions): Recorder;
+/**
+ * Convenience: record for a fixed duration and auto-download.
+ *
+ * @example
+ * ```ts
+ * await recordAndDownload(canvasEl, 3000, { fps: 15, format: 'gif' });
+ * ```
+ */
+declare function recordAndDownload(canvas: HTMLCanvasElement, durationMs: number, options?: RecorderOptions & {
+    filename?: string;
+}): Promise<void>;
+
 interface WebGLRenderer {
     render(frame: AsciiFrame, options: AsciiOptions, displayW: number, displayH: number, time: number, hoverPos?: {
         x: number;
@@ -483,4 +685,4 @@ interface WebGLRenderer {
  */
 declare function tryCreateWebGLRenderer(canvas: HTMLCanvasElement): WebGLRenderer | null;
 
-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 };
+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 CircuitBackgroundOptions, type ColorMode, DEFAULT_OPTIONS, type DnaBackgroundOptions, type FireBackgroundOptions, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MorphBackgroundOptions, type MountWaveOptions, type NoiseBackgroundOptions, PALETTE_THEMES, type PaletteTheme, type PulseBackgroundOptions, type RainBackgroundOptions, type Recorder, type RecorderOptions, type RenderMode, type SilkBackgroundOptions, type SourceType, type StarsBackgroundOptions, type TerrainBackgroundOptions, type VoidBackgroundOptions, type WaveBackgroundOptions, type WebGLRenderer, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyVideo, createRecorder, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, recordAndDownload, renderAuroraBackground, renderCircuitBackground, renderDnaBackground, renderFireBackground, renderFrameToCanvas, renderGridBackground, renderMorphBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderSilkBackground, renderStarsBackground, renderTerrainBackground, renderVoidBackground, renderWaveBackground, tryCreateWebGLRenderer, videoToAsciiFrames };