asciify-engine 1.0.117 → 1.1.0

package/dist/core.d.cts

@@ -0,0 +1,1265 @@
+type ColorMode = 'grayscale' | 'fullcolor' | 'matrix' | 'accent';
+type RenderMode = 'ascii' | 'dots';
+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' | 'circles' | 'shadows' | 'starfield' | 'geometric' | 'pipes' | 'waves' | 'shards' | 'smoke' | 'ascii' | 'interface' | 'prompt' | 'data' | 'humanist' | 'mesh';
+type HoverEffect = 'spotlight' | 'magnify' | 'repel' | 'glow' | 'colorShift' | 'attract' | 'shatter' | 'trail' | 'glitchText';
+type HoverShape = 'circle' | 'box';
+type HoverPreset = 'none' | 'subtle' | 'flashlight' | 'magnifier' | 'forceField' | 'neon' | 'fire' | 'ice' | 'gravity' | 'shatter' | 'ghost' | 'glitchReveal';
+type SourceCropUnit = 'percent' | 'pixel';
+type SourceCropAnchor = 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+interface SourceCrop {
+    /** Legacy crop origin on the source media. Percent values use 0–1. Default: centered when cropped */
+    x?: number;
+    /** Legacy crop origin on the source media. Percent values use 0–1. Default: centered when cropped */
+    y?: number;
+    /** Legacy crop width on the source media. Percent values use 0–1. Default: mirrors `height` to preserve proportions */
+    width?: number;
+    /** Legacy crop height on the source media. Percent values use 0–1. Default: mirrors `width` to preserve proportions */
+    height?: number;
+    /** CSS-like crop inset from the top edge. Percent values use 0–1. */
+    top?: number;
+    /** CSS-like crop inset from the right edge. Percent values use 0–1. */
+    right?: number;
+    /** CSS-like crop inset from the bottom edge. Percent values use 0–1. */
+    bottom?: number;
+    /** CSS-like crop inset from the left edge. Percent values use 0–1. */
+    left?: number;
+    /**
+     * Keep the source aspect ratio when deriving a crop from a single `width` or
+     * `height`. CSS-like side insets (`top`, `right`, `bottom`, `left`) already
+     * define an exact source view box, and `asciifyVideo` sizes from that crop
+     * aspect so the output does not stretch. Default: `true`.
+     */
+    preserveAspect?: boolean;
+    /** Bias auto-centered crops toward an edge or corner. Default: `'center'` */
+    anchor?: SourceCropAnchor;
+    /** Interpret values as normalized percentages or source pixels. Default: `'percent'` */
+    unit?: SourceCropUnit;
+}
+/**
+ * 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 {
+    /** Character cell width in pixels. Smaller = more detail, more cells. Default: `7` */
+    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'`
+     */
+    /**
+     * Hex color string used when `colorMode` is `'accent'`.
+     * Set to `'auto'` to let the engine pick contrasting ink automatically:
+     * dark ink (`#0d0d0d`) in light mode, light ink (`#faf9f7`) in dark mode.
+     */
+    accentColor: string;
+    /**
+     * Invert luminance mapping (light pixels → dense chars). Default: `false`
+     *
+     * Set to `'auto'` to let the engine detect the OS color scheme:
+     * - Light mode → inverts (bright pixel = dark char = visible on white background)
+     * - Dark mode  → normal  (bright pixel = bright char = visible on dark background)
+     */
+    invert: boolean | 'auto';
+    /**
+     * 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;
+    /**
+     * Ordered Bayer (4×4) dither strength applied to the luminance map.
+     * `0` = no dithering, `1` = full dithering. Default: `0`
+     */
+    ditherStrength: number;
+    /**
+     * Assumed aspect ratio (width ÷ height) of a single output character.
+     * Controls how many rows vs columns are generated — must match your rendering
+     * environment to preserve the source image's proportions.
+     * - `0.55` — browser monospace at `line-height: 1.09` (default)
+     * - `0.52` — browser monospace at `line-height: 1.15`
+     * - `0.5`  — most terminal emulators
+     * Default: `0.55`
+     */
+    charAspect: number;
+    /**
+     * Auto-stretch the luminance range before charset mapping.
+     * When `true`, the darkest pixel in the frame maps to the first charset character
+     * and the brightest to the last, maximising perceived detail and contrast.
+     * Particularly useful for images with low inherent contrast or muted tones.
+     * Default: `false`
+     */
+    normalize: boolean;
+    /**
+     * 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;
+    /**
+     * Shape of the hover interaction zone.
+     * - `'circle'` — radial falloff (default)
+     * - `'box'` — rectangular zone, text fills a block around the cursor
+     * Default: `'circle'`
+     */
+    hoverShape: HoverShape;
+    /**
+     * Text string revealed by the `'glitchText'` hover effect.
+     * Characters around the cursor scramble and resolve into this text.
+     * Supports `\n` for multi-line reveals.
+     *
+     * Pass an **array** of strings to cycle through different words based on
+     * the cursor's grid region — the engine picks one via a spatial hash so
+     * each area of the canvas shows a different word.
+     *
+     * Default: `'ASCIIFY'`
+     *
+     * @example
+     * // Single word:
+     * options: { hoverEffect: 'glitchText', hoverText: 'HELLO' }
+     *
+     * // Word pool — different text at different cursor positions:
+     * options: { hoverEffect: 'glitchText', hoverText: ['DEPLOY', 'SCALE', 'SHIP', 'BUILD'] }
+     */
+    hoverText: string | 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;
+    /**
+     * Chroma-key colour to remove from the source (green screen / blue screen).
+     * Pixels whose RGB distance from this colour is within `chromaKeyTolerance`
+     * are keyed out: their character becomes a space and alpha is set to 0,
+     * letting the canvas background show through.
+     *
+     * - `true` — **smart green screen**: heuristic detection (`g > r*1.4 && g > b*1.4`)
+     *   catches every shade of green screen (lime, broadcast, chroma green) with no
+     *   config. Works on virtually all studio/streaming footage.
+     * - `'blue-screen'` — **smart blue screen**: same heuristic for blue.
+     * - `{ r, g, b }` or CSS colour string — custom key colour + `chromaKeyTolerance`
+     * - `null` / `false` — disabled (default)
+     *
+     * @example
+     * // Standard green screen — zero config:
+     * options: { chromaKey: true }
+     *
+     * // Blue screen — zero config:
+     * options: { chromaKey: 'blue-screen' }
+     *
+     * // Custom CSS colour:
+     * options: { chromaKey: '#00b140', chromaKeyTolerance: 70 }
+     */
+    chromaKey: {
+        r: number;
+        g: number;
+        b: number;
+    } | string | boolean | null;
+    /**
+     * Euclidean RGB tolerance radius for chroma-key detection.
+     * `0` = exact match only, `441` ≈ key out everything.
+     * Higher values remove more pixels. Default: `60`
+     */
+    chromaKeyTolerance: number;
+    /**
+     * Extra normalized padding kept around the detected chroma-key foreground when
+     * `asciifyVideo` auto-trims keyed video content inside `sourceCrop`.
+     * `0` hugs the visible foreground. `0.01` keeps 1% safety padding.
+     * Default: `0.002`
+     */
+    chromaKeyTrimPadding: number;
+    /**
+     * Minimum source-pixel luminance for chroma-key foreground auto-trim.
+     * Raise this when faint edge noise is counted as content and prevents a
+     * keyed subject from filling a preserved-ratio layout. Range `0–255`.
+     * Default: `0`
+     */
+    chromaKeyTrimLuminanceThreshold: number;
+    /**
+     * How keyed video foreground trimming is applied when `chromaKey` and
+     * `sourceCrop` are enabled.
+     *
+     * - `'range'` samples the video/scroll range once and keeps a stable union
+     *   crop. Best default for consistent framing.
+     * - `'frame'` remeasures each rendered frame and expands the crop to the
+     *   render aspect. Best for scroll-scrubbed hero footage where foreground
+     *   position changes and pure contain leaves empty edges.
+     * - `'off'` disables automatic keyed foreground trimming.
+     *
+     * Default: `'range'`
+     */
+    chromaKeyTrimMode: 'range' | 'frame' | 'off';
+    /**
+     * Optional source crop applied before ASCII sampling.
+     *
+     * Use this when the media has empty edges or a subject that should be framed
+     * tighter without changing the destination canvas size.
+     *
+     * @example
+     * // Remove 15% from the top and 15% from the bottom, preserving proportions:
+     * options: { sourceCrop: { top: 0.15, bottom: 0.15 } }
+     *
+     * @example
+     * // Keep 70% of the source, preserve proportions, and center it:
+     * options: { sourceCrop: { height: 0.7 } }
+     *
+     * @example
+     * // Use an exact source window when manual framing should override proportions:
+     * options: { sourceCrop: { x: 0.05, y: 0.08, width: 0.9, height: 0.9, preserveAspect: false } }
+     */
+    sourceCrop?: SourceCrop | null;
+    /**
+     * Array of charset strings to cycle through over time.
+     * The engine picks `charsetFrames[Math.floor(time * charsetFps) % length]` on each
+     * render tick, re-mapping characters from stored cell luminance.
+     * Pairs beautifully with `animationStyle` and `asciiBackground`.
+     *
+     * Use `CHARSET_SEQUENCES` for curated combinations or build your own:
+     * @example
+     * options: { charsetFrames: CHARSET_SEQUENCES.cosmic }
+     * options: { charsetFrames: [CHARSETS.standard, CHARSETS.blocks, CHARSETS.circles] }
+     */
+    charsetFrames?: string[];
+    /** Cycle rate for `charsetFrames` in frames-per-second. Default: `2` */
+    charsetFps?: number;
+}
+interface AsciiCell {
+    char: string;
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+    /** Stored dithered luminance (0–255). Present when the frame was generated by the engine. Used for dynamic charset re-selection at render time via `charsetFrames`. */
+    lum?: number;
+}
+type AsciiFrame = AsciiCell[][];
+interface AsciiResult {
+    frames: AsciiFrame[];
+    cols: number;
+    rows: number;
+    fps: number;
+}
+declare const CHARSETS: {
+    readonly standard: " .:-=+*#%@";
+    readonly blocks: " ░▒▓█";
+    readonly minimal: " .:+";
+    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: " ⬛🟫🟥🟧🟨🟩🟦🟪⬜";
+    readonly circles: " .·:∘○◦°•∙";
+    readonly shadows: " ·∘◦○◎⊙●◉";
+    readonly starfield: " ˙·∘∗✦✧★◆●";
+    readonly geometric: " ·△▷◇◈◆▣■█";
+    readonly pipes: " ╶─┐└├┤┬┴┼╬▒▓█";
+    readonly waves: " ˜∼≈〰≋∿∾∭∫";
+    readonly shards: " ╱╲╳◤◥◣◢△▲◆◼█";
+    readonly smoke: " ·˙⁚⁖∶∷⋮⋰⋱∴∵";
+    /** All printable ASCII characters ordered from airy punctuation to dense symbols. */
+    readonly ascii: " .'`^\",:;~-_+<>i!lI?/\\|()[]{}1tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$";
+    /** Clean product UI glyphs inspired by command palettes, panes, controls, and focus rings. */
+    readonly interface: " ·•-–—+=:;<>[]{}()⌘⌥⇧⌃↵↗↘◇◆◈□■";
+    /** Prompt, shell, and assistant transcript glyphs for modern AI/dev surfaces. */
+    readonly prompt: " .:;>_`/\\|{}[]()=+*#@$";
+    /** Analytical/data-viz glyphs: sparse dots into nodes, diamonds, and dense blocks. */
+    readonly data: " ·∙•◦○●◇◆◈▱▰▣█";
+    /** Warm editorial/math symbols for quieter Claude-like and research-oriented pages. */
+    readonly humanist: " ·˙,:;∴∵∷∶⁚⋮⋯∼≈≋∞";
+    /** Dense network/mesh characters for agent maps, model graphs, and infrastructure visuals. */
+    readonly mesh: " ·╶╴╷╵─│┌┐└┘├┤┬┴┼╬░▒▓█";
+};
+/**
+ * Curated charset sequences for use with `charsetFrames`.
+ * Each sequence morphs between 2–3 complementary charsets over time,
+ * creating a living texture effect.
+ *
+ * @example
+ * asciiBackground('#hero', { charsetFrames: CHARSET_SEQUENCES.cosmic })
+ */
+declare const CHARSET_SEQUENCES: {
+    /** Stars → softcircles → orbs — dreamy space feel */
+    readonly cosmic: string[];
+    /** Katakana → braille dots → binary — hacker rain */
+    readonly rain: string[];
+    /** Box pipes → Claude glyphs → classic — terminal morph */
+    readonly terminal: string[];
+    /** Shards → blocks → squares — shattering crystal */
+    readonly crystal: string[];
+    /** Wave glyphs → smoke dots → circles — fluid / organic */
+    readonly fluid: string[];
+    /** Dense classic → art → blocks — maximum detail pulse */
+    readonly pulse: string[];
+    /** Braille → shadows → smoke — ethereal / dream-like */
+    readonly dream: string[];
+    /** Geometric shapes → shards → starfield — sci-fi angular */
+    readonly angular: string[];
+    /** Interface controls → prompts → data nodes — clean assistant/product motion */
+    readonly assistant: string[];
+    /** Mesh → data → ASCII — alive network signal with readable texture */
+    readonly signal: string[];
+    /** Humanist symbols → waves → smoke — soft research/editorial motion */
+    readonly editorial: string[];
+};
+type CharsetSequenceKey = keyof typeof CHARSET_SEQUENCES;
+type CharsetKey = keyof typeof CHARSETS;
+/**
+ * Art Style presets — each one sets render mode, charset, color mode, etc.
+ */
+declare const ART_STYLE_PRESETS: Record<ArtStyle, Partial<AsciiOptions>>;
+/**
+ * Higher-level living presets for output that should feel active immediately.
+ * They intentionally compose existing primitives so renderers and integrations
+ * can consume them as a normal `Partial<AsciiOptions>`.
+ */
+declare const LIVING_STYLE_PRESETS: {
+    readonly agentField: {
+        readonly charsetFrames: string[];
+        readonly charsetFps: 1.6;
+        readonly animationStyle: "breathe";
+        readonly animationSpeed: 0.75;
+        readonly ditherStrength: 0.12;
+        readonly hoverEffect: "glow";
+        readonly hoverStrength: 0.42;
+        readonly hoverRadius: 0.18;
+        readonly hoverColor: "#f4f1ea";
+        readonly normalize: true;
+        readonly fontSize?: number | undefined;
+        readonly charSpacing?: number | undefined;
+        readonly brightness?: number | undefined;
+        readonly contrast?: number | undefined;
+        readonly charset?: string | undefined;
+        readonly colorMode?: ColorMode | undefined;
+        readonly accentColor?: string | undefined;
+        readonly invert?: boolean | "auto" | undefined;
+        readonly renderMode?: RenderMode | undefined;
+        readonly dotSizeRatio?: number | undefined;
+        readonly charAspect?: number | undefined;
+        readonly hoverShape?: HoverShape | undefined;
+        readonly hoverText?: string | string[] | undefined;
+        readonly artStyle?: ArtStyle | undefined;
+        readonly customText?: string | undefined;
+        readonly chromaKey?: string | boolean | {
+            r: number;
+            g: number;
+            b: number;
+        } | null | undefined;
+        readonly chromaKeyTolerance?: number | undefined;
+        readonly chromaKeyTrimPadding?: number | undefined;
+        readonly chromaKeyTrimLuminanceThreshold?: number | undefined;
+        readonly chromaKeyTrimMode?: "range" | "frame" | "off" | undefined;
+        readonly sourceCrop?: SourceCrop | null;
+    };
+    readonly liquidSignal: {
+        readonly charsetFrames: string[];
+        readonly charsetFps: 2.4;
+        readonly animationStyle: "melt";
+        readonly animationSpeed: 0.65;
+        readonly ditherStrength: 0.45;
+        readonly hoverEffect: "repel";
+        readonly hoverStrength: 0.55;
+        readonly hoverRadius: 0.22;
+        readonly hoverColor: "#8fd3ff";
+        readonly normalize: true;
+        readonly fontSize?: number | undefined;
+        readonly charSpacing?: number | undefined;
+        readonly brightness?: number | undefined;
+        readonly contrast?: number | undefined;
+        readonly charset?: string | undefined;
+        readonly colorMode?: ColorMode | undefined;
+        readonly accentColor?: string | undefined;
+        readonly invert?: boolean | "auto" | undefined;
+        readonly renderMode?: RenderMode | undefined;
+        readonly dotSizeRatio?: number | undefined;
+        readonly charAspect?: number | undefined;
+        readonly hoverShape?: HoverShape | undefined;
+        readonly hoverText?: string | string[] | undefined;
+        readonly artStyle?: ArtStyle | undefined;
+        readonly customText?: string | undefined;
+        readonly chromaKey?: string | boolean | {
+            r: number;
+            g: number;
+            b: number;
+        } | null | undefined;
+        readonly chromaKeyTolerance?: number | undefined;
+        readonly chromaKeyTrimPadding?: number | undefined;
+        readonly chromaKeyTrimLuminanceThreshold?: number | undefined;
+        readonly chromaKeyTrimMode?: "range" | "frame" | "off" | undefined;
+        readonly sourceCrop?: SourceCrop | null;
+    };
+    readonly cursorGravity: {
+        readonly charsetFrames: string[];
+        readonly charsetFps: 1.2;
+        readonly animationStyle: "orbit";
+        readonly animationSpeed: 0.9;
+        readonly ditherStrength: 0.2;
+        readonly hoverEffect: "attract";
+        readonly hoverStrength: 0.82;
+        readonly hoverRadius: 0.24;
+        readonly hoverColor: "#ffffff";
+        readonly normalize: true;
+        readonly fontSize?: number | undefined;
+        readonly charSpacing?: number | undefined;
+        readonly brightness?: number | undefined;
+        readonly contrast?: number | undefined;
+        readonly charset?: string | undefined;
+        readonly colorMode?: ColorMode | undefined;
+        readonly accentColor?: string | undefined;
+        readonly invert?: boolean | "auto" | undefined;
+        readonly renderMode?: RenderMode | undefined;
+        readonly dotSizeRatio?: number | undefined;
+        readonly charAspect?: number | undefined;
+        readonly hoverShape?: HoverShape | undefined;
+        readonly hoverText?: string | string[] | undefined;
+        readonly artStyle?: ArtStyle | undefined;
+        readonly customText?: string | undefined;
+        readonly chromaKey?: string | boolean | {
+            r: number;
+            g: number;
+            b: number;
+        } | null | undefined;
+        readonly chromaKeyTolerance?: number | undefined;
+        readonly chromaKeyTrimPadding?: number | undefined;
+        readonly chromaKeyTrimLuminanceThreshold?: number | undefined;
+        readonly chromaKeyTrimMode?: "range" | "frame" | "off" | undefined;
+        readonly sourceCrop?: SourceCrop | null;
+    };
+    readonly editorialPulse: {
+        readonly charsetFrames: string[];
+        readonly charsetFps: 0.9;
+        readonly animationStyle: "ripple";
+        readonly animationSpeed: 0.55;
+        readonly ditherStrength: 0.18;
+        readonly hoverEffect: "spotlight";
+        readonly hoverStrength: 0.35;
+        readonly hoverRadius: 0.2;
+        readonly hoverColor: "#fff8ea";
+        readonly normalize: true;
+        readonly fontSize?: number | undefined;
+        readonly charSpacing?: number | undefined;
+        readonly brightness?: number | undefined;
+        readonly contrast?: number | undefined;
+        readonly charset?: string | undefined;
+        readonly colorMode?: ColorMode | undefined;
+        readonly accentColor?: string | undefined;
+        readonly invert?: boolean | "auto" | undefined;
+        readonly renderMode?: RenderMode | undefined;
+        readonly dotSizeRatio?: number | undefined;
+        readonly charAspect?: number | undefined;
+        readonly hoverShape?: HoverShape | undefined;
+        readonly hoverText?: string | string[] | undefined;
+        readonly artStyle?: ArtStyle | undefined;
+        readonly customText?: string | undefined;
+        readonly chromaKey?: string | boolean | {
+            r: number;
+            g: number;
+            b: number;
+        } | null | undefined;
+        readonly chromaKeyTolerance?: number | undefined;
+        readonly chromaKeyTrimPadding?: number | undefined;
+        readonly chromaKeyTrimLuminanceThreshold?: number | undefined;
+        readonly chromaKeyTrimMode?: "range" | "frame" | "off" | undefined;
+        readonly sourceCrop?: SourceCrop | null;
+    };
+    readonly terminalFlow: {
+        readonly charsetFrames: string[];
+        readonly charsetFps: 3;
+        readonly animationStyle: "rain";
+        readonly animationSpeed: 1.1;
+        readonly ditherStrength: 0.22;
+        readonly hoverEffect: "glitchText";
+        readonly hoverStrength: 0.65;
+        readonly hoverRadius: 0.16;
+        readonly hoverColor: "#d4ff00";
+        readonly hoverText: ["BUILD", "SHIP", "RUN", "ASK", "MODEL"];
+        readonly normalize: true;
+        readonly fontSize?: number | undefined;
+        readonly charSpacing?: number | undefined;
+        readonly brightness?: number | undefined;
+        readonly contrast?: number | undefined;
+        readonly charset?: string | undefined;
+        readonly colorMode?: ColorMode | undefined;
+        readonly accentColor?: string | undefined;
+        readonly invert?: boolean | "auto" | undefined;
+        readonly renderMode?: RenderMode | undefined;
+        readonly dotSizeRatio?: number | undefined;
+        readonly charAspect?: number | undefined;
+        readonly hoverShape?: HoverShape | undefined;
+        readonly artStyle?: ArtStyle | undefined;
+        readonly customText?: string | undefined;
+        readonly chromaKey?: string | boolean | {
+            r: number;
+            g: number;
+            b: number;
+        } | null | undefined;
+        readonly chromaKeyTolerance?: number | undefined;
+        readonly chromaKeyTrimPadding?: number | undefined;
+        readonly chromaKeyTrimLuminanceThreshold?: number | undefined;
+        readonly chromaKeyTrimMode?: "range" | "frame" | "off" | undefined;
+        readonly sourceCrop?: SourceCrop | null;
+    };
+};
+type LivingStylePresetKey = keyof typeof LIVING_STYLE_PRESETS;
+declare const DEFAULT_OPTIONS: AsciiOptions;
+/**
+ * Hover presets — one-click configurations for the hover system.
+ */
+declare const HOVER_PRESETS: Record<HoverPreset, {
+    label: string;
+    options: Partial<AsciiOptions>;
+}>;
+
+/**
+ * Core frame-to-canvas renderer and source-to-frame converters.
+ */
+
+interface AsciiTextFrame {
+    rows: string[];
+    cols: number;
+    rowCount: number;
+    colors?: Uint8ClampedArray;
+}
+/** Clear shared renderer caches. Useful for long-lived editors that cycle many fonts/charsets. */
+declare function clearAsciifyCaches(): void;
+/**
+ * Convert an image element or canvas to a single ASCII frame.
+ */
+declare function imageToAsciiFrame(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement, options: AsciiOptions, targetWidth?: number, targetHeight?: number): {
+    frame: AsciiFrame;
+    cols: number;
+    rows: number;
+};
+/**
+ * Convert a source into pre-shaped text rows for fast monochrome/accent ASCII.
+ *
+ * This is the high-performance path for dense video scrubbers. It keeps the
+ * expensive pixel sampling work, but avoids allocating one object per cell and
+ * lets the renderer draw one string per row instead of one `fillText` per cell.
+ */
+declare function imageToAsciiTextFrame(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement, options: AsciiOptions, targetWidth?: number, targetHeight?: number): AsciiTextFrame;
+declare function renderTextFrameToCanvas(ctx: CanvasRenderingContext2D, textFrame: AsciiTextFrame, options: AsciiOptions, canvasWidth: number, canvasHeight: number): void;
+/**
+ * Extract frames from a video element for ASCII animation.
+ */
+declare function videoToAsciiFrames(video: HTMLVideoElement, options: AsciiOptions, targetWidth: number, targetHeight: number, targetFps?: number, maxDuration?: number, onProgress?: (progress: number) => void, startTime?: number): Promise<{
+    frames: AsciiFrame[];
+    cols: number;
+    rows: number;
+    fps: number;
+}>;
+/**
+ * Extract video frames into compact text rows for high-density monochrome/accent
+ * animations. This mirrors videoToAsciiFrames but avoids object-per-cell frames.
+ */
+declare function videoToAsciiTextFrames(video: HTMLVideoElement, options: AsciiOptions, targetWidth: number, targetHeight: number, targetFps?: number, maxDuration?: number, onProgress?: (progress: number) => void, startTime?: number): Promise<{
+    frames: AsciiTextFrame[];
+    cols: number;
+    rows: number;
+    fps: number;
+}>;
+/**
+ * Extract frames from an animated GIF file buffer.
+ */
+declare function gifToAsciiFrames(buffer: ArrayBuffer, options: AsciiOptions, targetWidth: number, targetHeight: number, onProgress?: (progress: number) => void): Promise<{
+    frames: AsciiFrame[];
+    cols: number;
+    rows: number;
+    fps: number;
+}>;
+/**
+ * Extract animated GIF frames into compact text rows for high-density
+ * monochrome/accent playback. Keeps the legacy object-frame extractor intact
+ * for full-color and interactive modes.
+ */
+declare function gifToAsciiTextFrames(buffer: ArrayBuffer, options: AsciiOptions, targetWidth: number, targetHeight: number, onProgress?: (progress: number) => void): Promise<{
+    frames: AsciiTextFrame[];
+    cols: number;
+    rows: number;
+    fps: number;
+}>;
+/** Frames are immutable: replace a frame after editing cells to invalidate its cached drawing. */
+declare function renderFrameToCanvas(ctx: CanvasRenderingContext2D, frame: AsciiFrame, options: AsciiOptions, width: number, height: number, time?: number, pointer?: {
+    x: number;
+    y: number;
+    intensity?: number;
+} | null): void;
+
+/**
+ * Simple one-call asciify API.
+ * Wraps imageToAsciiFrame + renderFrameToCanvas behind easy-to-use helpers.
+ */
+
+interface AsciifySimpleOptions {
+    /** Character size in pixels. Default: 10 */
+    fontSize?: number;
+    /**
+     * 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>;
+}
+type ScrollTriggerInstance = {
+    kill?: () => void;
+};
+type ScrollTriggerLike = {
+    create: (vars: Record<string, unknown>) => ScrollTriggerInstance;
+};
+type GsapLike = {
+    registerPlugin?: (...plugins: unknown[]) => void;
+    ScrollTrigger?: ScrollTriggerLike;
+};
+interface VideoScrollScrubOptions {
+    /**
+     * Element that controls scroll progress. Accepts an HTMLElement or selector.
+     * When used through `asciifyVideo`, defaults to `fitTo` or the canvas.
+     */
+    trigger?: HTMLElement | string | null;
+    /**
+     * GSAP instance. Pass this with ScrollTrigger for native GSAP scrub support.
+     *
+     * @example
+     * asciifyVideo('/hero.mp4', canvas, {
+     *   fitTo: '#hero',
+     *   scroll: { gsap, ScrollTrigger }
+     * });
+     */
+    gsap?: GsapLike;
+    /** GSAP ScrollTrigger plugin. Optional when available as `gsap.ScrollTrigger`. */
+    ScrollTrigger?: ScrollTriggerLike;
+    /** GSAP start value. Native fallback ignores this and uses viewport progress. */
+    start?: string;
+    /** GSAP end value. Native fallback ignores this and uses viewport progress. */
+    end?: string;
+    /** GSAP scrub value. Default: `true`. Native fallback always scrubs. */
+    scrub?: boolean | number;
+    /**
+     * Multiply scroll progress before mapping it to video time.
+     * `2` reaches the end of the clip in half the scroll distance, `0.5` makes it
+     * take twice as much scroll. Default: `1`.
+     */
+    speed?: number;
+    /** Video time to map from. Defaults to trim start or `0`. */
+    from?: number;
+    /** Video time to map to. Defaults to trim end or video duration. */
+    to?: number;
+    /** Optional progress transform before mapping to video time. */
+    ease?: (progress: number) => number;
+    /** Called whenever scroll progress updates. */
+    onUpdate?: (progress: number, video: HTMLVideoElement) => void;
+}
+type CanvasObjectFit = 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+type CanvasBleed = number | string | {
+    x?: number | string;
+    y?: number | string;
+};
+interface AsciifyVideoOptions extends AsciifySimpleOptions {
+    /**
+     * Fit the canvas to a container element, maintaining the video's aspect ratio.
+     * Accepts an HTMLElement or a CSS selector string. The canvas is resized on
+     * load and again whenever the container resizes (via ResizeObserver).
+     * `stop()` automatically disconnects the observer.
+     *
+     * @example
+     * // Fill the hero div, re-size on window resize automatically:
+     * asciifyVideo('/clip.mp4', canvas, { fitTo: '#hero' });
+     */
+    fitTo?: HTMLElement | string | null;
+    /**
+     * CSS object-fit behavior for the visible canvas when `fitTo` or explicit
+     * `width`/`height` is used. This controls visual framing only; ASCII sampling
+     * resolution remains independent. When `options.sourceCrop` is present, the
+     * engine sizes from the resolved crop aspect to avoid stretch.
+     *
+     * Use `'cover'` for full-bleed heroes and `'contain'` for previews.
+     * Default: `'contain'`.
+     */
+    objectFit?: CanvasObjectFit;
+    /**
+     * CSS object-position for the visible canvas, e.g. `'center bottom'` or
+     * `'50% 62%'`. Useful with `objectFit: 'cover'`.
+     */
+    objectPosition?: string;
+    /**
+     * Visual scale applied with the CSS individual `scale` property. This is a
+     * layout-safe way to overfill a container without changing source proportions
+     * or overriding an app's `transform` styles.
+     */
+    scale?: number;
+    /**
+     * Visible CSS width for the canvas. Numbers are pixels; strings are used as
+     * provided (`'100%'`, `'100vw'`, `min(100vw, 1200px)`, etc.).
+     */
+    width?: number | string;
+    /**
+     * Visible CSS height for the canvas. Numbers are pixels; strings are used as
+     * provided.
+     */
+    height?: number | string;
+    /**
+     * Extra visible overfill added around the fitted canvas box before
+     * object-fit sizing. Useful for full-bleed ASCII heroes where glyph side
+     * bearings or character-cell quantization can leave a small edge gap even
+     * when the source media and canvas are full width.
+     *
+     * Numbers are pixels. Strings support `%`, `px`, `vw`, and `vh`. Pass an
+     * object to control axes independently, e.g. `{ x: '2vw', y: 0 }`.
+     */
+    bleed?: CanvasBleed;
+    /**
+     * Pre-extract all video frames into memory before starting playback.
+     * Useful for short clips where you need frame-perfect control.
+     *
+     * Default: `false` — streams live directly from the playing video (instant
+     * start, constant memory, unlimited duration).
+     *
+     * ⚠️ Memory-intensive. Capped at 10 s / 300 frames.
+     */
+    preExtract?: boolean;
+    /**
+     * Target render FPS.
+     * - In pre-extracted mode, this controls how many frames are decoded into memory.
+     * - In live mode, this throttles expensive ASCII frame rendering while the
+     *   backing video continues decoding normally.
+     *
+     * Lower values use less CPU/memory and make scroll scrubbing cheaper.
+     * Defaults to `18` for pre-extracted scroll scrub and unthrottled rendering
+     * for normal live playback.
+     */
+    fps?: number;
+    /**
+     * Maximum long-edge render dimension for video frame extraction.
+     * Raise this for full-width or 4K heroes so the canvas is not upscaled by CSS.
+     * Default: `2048`.
+     */
+    maxRenderDimension?: number;
+    /**
+     * Trim the video to a specific time range (in seconds).
+     * - `start` — seek to this time before playback begins. Default: `0`
+     * - `end` — loop back to `start` when this time is reached.
+     *   In `preExtract` mode, only frames up to `end` are extracted.
+     *
+     * @example
+     * // Play only seconds 2–8, looping:
+     * asciifyVideo('/clip.mp4', canvas, { trim: { start: 2, end: 8 } });
+     */
+    trim?: {
+        start?: number;
+        end?: number;
+    };
+    /**
+     * Sync video time to scroll progress.
+     *
+     * - `true` uses native scroll scrubbing with `fitTo`/canvas as the trigger.
+     * - Passing `gsap` + `ScrollTrigger` uses GSAP ScrollTrigger.
+     *
+     * @example
+     * await asciifyVideo('/hero.mp4', canvas, {
+     *   fitTo: '#hero',
+     *   scroll: true
+     * });
+     *
+     * @example
+     * await asciifyVideo('/hero.mp4', canvas, {
+     *   fitTo: '#hero',
+     *   scroll: { gsap, ScrollTrigger, start: 'top bottom', end: 'bottom top', scrub: 1 }
+     * });
+     */
+    scroll?: boolean | VideoScrollScrubOptions;
+    /**
+     * Called once when the video metadata is loaded and playback has started.
+     * Receives the backing video element.
+     */
+    onReady?: (video: HTMLVideoElement) => void;
+    /**
+     * Maximum number of decoded text frames kept in memory for live scroll scrub.
+     * The cache is nearest-frame and bounded; lower values reduce memory for long
+     * clips while preserving smooth scrubbing around the current scroll position.
+     * Default: `90`.
+     */
+    maxCachedFrames?: number;
+    /** Called after every rendered frame. */
+    onFrame?: () => void;
+}
+/** @deprecated Use {@link AsciifyVideoOptions} */
+type AsciifyLiveVideoOptions = AsciifyVideoOptions;
+/**
+ * Sync an HTMLVideoElement's currentTime to scroll progress.
+ *
+ * If `gsap` and `ScrollTrigger` are supplied, the helper uses GSAP. Otherwise
+ * it falls back to a tiny native scroll listener. Returns a cleanup function.
+ */
+declare function createVideoScrollScrub(video: HTMLVideoElement, opts?: VideoScrollScrubOptions): () => void;
+interface CanvasRenderSizeInput {
+    sourceWidth: number;
+    sourceHeight: number;
+    cssWidth?: number;
+    cssHeight?: number;
+    /** Accepted for callers that pass complete display context; DPR is applied separately by the canvas backing buffer. */
+    dpr?: number;
+    maxRenderDimension?: number;
+}
+declare function computeCanvasRenderSize({ sourceWidth, sourceHeight, cssWidth, cssHeight, maxRenderDimension, }: CanvasRenderSizeInput): {
+    renderW: number;
+    renderH: number;
+};
+/**
+ * Convert an image/video/canvas element to ASCII art and render it onto a canvas.
+ *
+ * When hover options are active (`hoverStrength > 0` in `options`), the engine
+ * automatically sets up mouse tracking and a `requestAnimationFrame` loop so
+ * the hover effect works out of the box. In that case, a `stop()` function is
+ * returned to tear down the loop and listeners.
+ *
+ * @example
+ * // Static (no hover):
+ * await asciify('/photo.jpg', canvas);
+ *
+ * // With hover — returns a cleanup handle:
+ * const stop = await asciify('/photo.jpg', canvas, {
+ *   options: { hoverEffect: 'glitchText', hoverStrength: 0.8, hoverText: 'HI' }
+ * });
+ * // later: stop?.();
+ */
+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.
+ *
+ * @example
+ * const stop = await asciifyGif('animation.gif', canvas);
+ * // later: stop();
+ */
+declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<() => void>;
+/**
+ * Render a video as ASCII art on a canvas. Defaults to live streaming —
+ * instant start, constant memory, unlimited duration.
+ *
+ * Pass `{ preExtract: true }` to pre-decode all frames before playback starts
+ * (useful for short clips that need frame-perfect looping).
+ *
+ * Pass `{ fitTo: '#container' }` to automatically size and re-size the canvas
+ * to fill a container element, maintaining the video's aspect ratio.
+ *
+ * Returns a `stop()` function that cancels the loop and cleans up.
+ *
+ * ⚠️ Never set the backing `<video>` to `display: none` — browsers skip GPU
+ * frame decoding for hidden elements. When given a URL string, this function
+ * handles that automatically.
+ *
+ * @example
+ * // Minimal
+ * const stop = await asciifyVideo('/clip.mp4', canvas);
+ *
+ * // Fit to container, re-size on window resize:
+ * const stop = await asciifyVideo('/clip.mp4', canvas, { fitTo: '#hero' });
+ *
+ * // Pre-extract frames (old behavior):
+ * const stop = await asciifyVideo('/clip.mp4', canvas, { preExtract: true });
+ */
+declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options, fitTo, objectFit, objectPosition, scale, width, height, bleed, preExtract, fps, maxRenderDimension, trim, scroll, maxCachedFrames, onReady, onFrame, }?: AsciifyVideoOptions): Promise<() => void>;
+/**
+ * @deprecated Use {@link asciifyVideo} instead — it now defaults to live streaming
+ * and accepts the same options including `fitTo` and `preExtract`.
+ */
+declare function asciifyLiveVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, opts?: AsciifyVideoOptions): Promise<() => void>;
+
+/**
+ * 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;
+
+/**
+ * text-frame.ts — Build and render ASCII frames from tiling text patterns.
+ *
+ * Enables interactive text backgrounds with the full hover-effect system
+ * (spotlight, magnify, repel, glow, colorShift, …) without needing an image
+ * source.
+ *
+ * @example — basic usage
+ * ```ts
+ * import { renderTextBackground } from 'asciify-engine';
+ *
+ * function tick(ctx, w, h, mousePos) {
+ *   renderTextBackground(ctx, w, h, 'asciify·engine·v1·', {
+ *     hoverEffect: 'spotlight',
+ *     hoverColor: '#d4ff00',
+ *   }, mousePos);
+ *   requestAnimationFrame(() => tick(ctx, w, h, mousePos));
+ * }
+ * ```
+ *
+ * @example — build the frame yourself and pass it to renderFrameToCanvas
+ * ```ts
+ * import { buildTextFrame, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
+ *
+ * const frame = buildTextFrame('hello world · ', 80, 24);
+ * renderFrameToCanvas(ctx, frame, {
+ *   ...DEFAULT_OPTIONS,
+ *   hoverEffect: 'repel',
+ *   hoverStrength: 0.9,
+ *   hoverColor: '#a0e8ff',
+ * }, width, height, 0, mousePos);
+ * ```
+ */
+
+interface TextBackgroundOptions {
+    /**
+     * Character size in pixels.
+     * Controls the grid density: smaller → more cells, finer text.
+     * @default 10
+     */
+    fontSize?: number;
+    /**
+     * Line-height multiplier applied on top of `fontSize` to derive row height.
+     * Matches the default monospace aspect ratio used by the renderer.
+     * @default 1.6
+     */
+    lineHeight?: number;
+    /**
+     * Base colour for the text cells (inactive state).
+     * Accepts any CSS hex or rgb string.
+     * @default '#505050'
+     */
+    color?: string;
+    /**
+     * Base alpha for the text cells, 0–255.
+     * @default 100
+     */
+    opacity?: number;
+    /**
+     * Which hover effect to activate when `hoverPos` is supplied.
+     * @default 'spotlight'
+     */
+    hoverEffect?: HoverEffect;
+    /**
+     * Intensity of the hover distortion / glow, 0–1.
+     * @default 0.85
+     */
+    hoverStrength?: number;
+    /**
+     * Normalised radius of the hover influence zone, 0–1.
+     * @default 0.18
+     */
+    hoverRadius?: number;
+    /**
+     * Accent colour applied by the hover effect.
+     * @default '#d4ff00'
+     */
+    hoverColor?: string;
+}
+/**
+ * Build an `AsciiFrame` filled with a tiling text pattern.
+ *
+ * The `text` string is repeated (wrapping at column boundaries) across every
+ * cell of the `cols × rows` grid.  Each cell carries the supplied base colour
+ * and opacity as `{r, g, b, a}` values.
+ *
+ * The returned frame can be passed directly to `renderFrameToCanvas` with any
+ * `AsciiOptions` including hover effects.
+ *
+ * @param text    - Pattern string to tile across the grid (e.g. `'hello · '`)
+ * @param cols    - Number of character columns
+ * @param rows    - Number of character rows
+ * @param color   - Base RGB colour string for the cells (default: `'#505050'`)
+ * @param opacity - Base alpha 0–255 (default: `100`)
+ */
+declare function buildTextFrame(text: string, cols: number, rows: number, color?: string, opacity?: number): AsciiFrame;
+/**
+ * All-in-one: build a tiling text grid and render it to a canvas with the
+ * full hover-effect system (spotlight, magnify, repel, glow, colorShift, …).
+ *
+ * Call this inside a `requestAnimationFrame` loop, passing updated `hoverPos`
+ * each frame to get smooth interactive effects.
+ *
+ * @param ctx       - 2D rendering context of the target canvas
+ * @param width     - Canvas logical width in pixels
+ * @param height    - Canvas logical height in pixels
+ * @param text      - Pattern string to tile (e.g. `'asciify·engine·v1·'`)
+ * @param options   - {@link TextBackgroundOptions}
+ * @param hoverPos  - Normalised mouse position `{x, y}` in 0–1 range,
+ *                    optionally with an `intensity` multiplier (0–1).
+ *                    Pass `null` or omit to render without hover.
+ */
+declare function renderTextBackground(ctx: CanvasRenderingContext2D, width: number, height: number, text: string, options?: TextBackgroundOptions, hoverPos?: {
+    x: number;
+    y: number;
+    intensity?: number;
+} | null): void;
+
+interface SnapshotOptions {
+    /**
+     * Image format.
+     * - 'png'  — lossless (default)
+     * - 'jpeg' — smaller, no transparency
+     * - 'webp' — best compression with transparency
+     */
+    format?: 'png' | 'jpeg' | 'webp';
+    /** 0–1 quality for jpeg/webp. Default: 0.92 */
+    quality?: number;
+    /**
+     * Scale factor applied before capture. Default: 1.
+     * Use 2 for a high-resolution export at 2× the canvas size.
+     */
+    scale?: number;
+}
+/**
+ * Capture a single frame from a canvas as a Blob.
+ *
+ * @example
+ * ```ts
+ * const blob = await captureSnapshot(canvas);
+ * const url = URL.createObjectURL(blob);
+ * ```
+ */
+declare function captureSnapshot(canvas: HTMLCanvasElement, { format, quality, scale }?: SnapshotOptions): Promise<Blob>;
+/**
+ * Capture a single frame and immediately trigger a browser download.
+ *
+ * @example
+ * ```ts
+ * await snapshotAndDownload(canvas);
+ * await snapshotAndDownload(canvas, { format: 'jpeg', filename: 'my-art' });
+ * ```
+ */
+declare function snapshotAndDownload(canvas: HTMLCanvasElement, options?: SnapshotOptions & {
+    filename?: string;
+}): Promise<void>;
+
+/**
+ * asciifyWebcam — live webcam → ASCII art on canvas.
+ *
+ * Requests camera access, attaches the stream to a hidden video element, and
+ * runs a rAF loop that converts each frame to ASCII and renders it onto a
+ * supplied canvas.
+ *
+ * @example
+ * const stop = await asciifyWebcam(canvas);
+ * // later: stop();
+ *
+ * @example
+ * const stop = await asciifyWebcam(canvas, {
+ *   fontSize: 8,
+ *   style: 'terminal',
+ *   mirror: true,                   // horizontal flip (selfie mode)
+ *   constraints: { facingMode: 'user' },
+ * });
+ */
+
+interface WebcamOptions {
+    /** Character size in pixels. Default: 10 */
+    fontSize?: number;
+    /** Art style preset. Default: 'classic' */
+    style?: ArtStyle;
+    /** Extra AsciiOptions merged on top of the preset */
+    options?: Partial<AsciiOptions>;
+    /**
+     * Called every frame to get the latest options. Takes priority over `options`.
+     * Use this to keep the rendering in sync with live UI controls without
+     * restarting the camera.
+     *
+     * @example
+     * const optionsRef = useRef(currentOptions);
+     * optionsRef.current = currentOptions;
+     * asciifyWebcam(canvas, { liveOptions: () => optionsRef.current });
+     */
+    liveOptions?: () => Partial<AsciiOptions>;
+    /**
+     * Flip the output horizontally so it reads like a mirror / selfie camera.
+     * Default: true
+     */
+    mirror?: boolean;
+    /**
+     * Passed directly to `getUserMedia({ video: constraints })`.
+     * Defaults to `{ facingMode: 'user' }`.
+     */
+    constraints?: MediaTrackConstraints;
+    /**
+     * Device pixel ratio used to compute logical render dimensions from the
+     * canvas's physical pixel size. Defaults to `window.devicePixelRatio ?? 1`.
+     * Set this when you size the canvas at physical resolution (e.g. width × dpr)
+     * so that ASCII column/row counts are based on CSS pixels, not physical ones.
+     */
+    dpr?: number;
+}
+/**
+ * Start a live webcam ASCII-art loop and render it onto `canvas`.
+ * Returns a `stop()` function that cancels the loop and releases the camera.
+ *
+ * Throws if the browser doesn't support `getUserMedia` or the user denies
+ * camera permission.
+ */
+declare function asciifyWebcam(canvas: HTMLCanvasElement, { fontSize, style, options, liveOptions, mirror, constraints, dpr: dprOverride, }?: WebcamOptions): Promise<() => void>;
+
+/**
+ * big-text.ts — ASCII text rendering via an embedded 7×7 bitmap font.
+ *
+ * Each character is defined as 7 rows × 7 pixels stored as compact bit-patterns.
+ * No canvas, no font files, no pixel-sampling — output is always crisp and readable.
+ *
+ * @example
+ * ```ts
+ * import { asciifyText } from 'asciify-engine';
+ * console.log(asciifyText('Hello!'));
+ * console.log(asciifyText('v2', { scale: 2, char: '#' }));
+ * ```
+ */
+interface BigTextOptions {
+    /**
+     * Character used for ink pixels. Any single grapheme — emoji work too.
+     * @default '█'
+     */
+    char?: string;
+    /**
+     * Pixel scale factor.
+     * `1` = each font pixel → 1 char (output is 7 rows tall).
+     * `2` = each pixel → 2×2 chars (14 rows tall), etc.
+     * @default 1
+     */
+    scale?: number;
+    /** Foreground colour (canvas output only). @default '#d4ff00' */
+    color?: string;
+    /** Background colour (canvas output only). @default transparent */
+    bgColor?: string;
+    /** Physical character cell size in px (canvas output only). @default 10 */
+    fontSize?: number;
+}
+/**
+ * Convert a string to multi-line ASCII text art.
+ *
+ * Uses an embedded 7×7 pixel bitmap font — no font files, no install step,
+ * works in every JS environment (browser, Node, Deno, Bun).
+ *
+ * @example
+ * ```ts
+ * import { asciifyText } from 'asciify-engine';
+ * console.log(asciifyText('Hello!'));
+ * console.log(asciifyText('v2.0', { char: '#' }));
+ * console.log(asciifyText('WOW',  { scale: 2, char: '▓' }));
+ * ```
+ */
+declare function asciifyText(text: string, options?: BigTextOptions): string;
+/**
+ * Render ASCII text directly onto an HTMLCanvasElement.
+ * The canvas is automatically resized to fit the output.
+ *
+ * @example
+ * ```ts
+ * import { renderTextToCanvas } from 'asciify-engine';
+ * renderTextToCanvas(canvas, 'Hello!', { color: '#d4ff00', scale: 2 });
+ * ```
+ */
+declare function renderTextToCanvas(canvas: HTMLCanvasElement, text: string, options?: BigTextOptions): void;
+
+export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciiTextFrame, type AsciifyLiveVideoOptions, type AsciifySimpleOptions, type AsciifyVideoOptions, type BigTextOptions, CHARSETS, CHARSET_SEQUENCES, type CanvasBleed, type CanvasObjectFit, type CanvasRenderSizeInput, type CharsetKey, type CharsetSequenceKey, type ColorMode, DEFAULT_OPTIONS, HOVER_PRESETS, type HoverEffect, type HoverPreset, type HoverShape, LIVING_STYLE_PRESETS, type LivingStylePresetKey, PALETTE_THEMES, type PaletteTheme, type RenderMode, type SnapshotOptions, type SourceType, type TextBackgroundOptions, type VideoScrollScrubOptions, type WebcamOptions, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyLiveVideo, asciifyText, asciifyVideo, asciifyWebcam, buildTextFrame, captureSnapshot, clearAsciifyCaches, computeCanvasRenderSize, createVideoScrollScrub, gifToAsciiFrames, gifToAsciiTextFrames, imageToAsciiFrame, imageToAsciiTextFrame, renderFrameToCanvas, renderTextBackground, renderTextFrameToCanvas, renderTextToCanvas, snapshotAndDownload, videoToAsciiFrames, videoToAsciiTextFrames };