asciify-engine 4.0.0 → 4.1.0

package/dist/types-BeXEm4UY.d.cts

@@ -0,0 +1,323 @@
+type ColorMode = 'grayscale' | 'fullcolor' | 'matrix' | 'accent';
+type RenderMode = 'ascii' | 'dots';
+type AnimationStyle = 'none' | 'caustics' | 'current' | 'reform';
+/** Core media draws ASCII/dots; use StudioStyle for the 15 render styles. */
+type ArtStyle = 'classic';
+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 `CHARACTER_SETS.standard.chars` for a curated ramp 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[];
+    /**
+     * Core renderer discriminator. No legacy preset lookup is performed.
+     * Core rendering uses `classic`; select the current render styles through `/studio`.
+     */
+    artStyle: ArtStyle;
+    /** Explicit fine-dither treatment for the optional hover compositor. */
+    fineDither?: boolean;
+    /**
+     * 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`.
+     *
+     * Supply your own array of character ramps:
+     * @example
+     * options: { charsetFrames: [CHARACTER_SETS.standard.chars, CHARACTER_SETS.blocks.chars] }
+     */
+    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 DEFAULT_OPTIONS: AsciiOptions;
+/**
+ * Hover presets — one-click configurations for the hover system.
+ */
+declare const HOVER_PRESETS: Record<HoverPreset, {
+    label: string;
+    options: Partial<AsciiOptions>;
+}>;
+
+export { type AsciiFrame as A, type ColorMode as C, DEFAULT_OPTIONS as D, type HoverEffect as H, PALETTE_THEMES as P, type RenderMode as R, type SourceType as S, type AsciiOptions as a, type ArtStyle as b, type AnimationStyle as c, type AsciiCell as d, type AsciiResult as e, HOVER_PRESETS as f, type HoverPreset as g, type HoverShape as h, type PaletteTheme as i };

package/dist/types-BeXEm4UY.d.ts

@@ -0,0 +1,323 @@
+type ColorMode = 'grayscale' | 'fullcolor' | 'matrix' | 'accent';
+type RenderMode = 'ascii' | 'dots';
+type AnimationStyle = 'none' | 'caustics' | 'current' | 'reform';
+/** Core media draws ASCII/dots; use StudioStyle for the 15 render styles. */
+type ArtStyle = 'classic';
+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 `CHARACTER_SETS.standard.chars` for a curated ramp 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[];
+    /**
+     * Core renderer discriminator. No legacy preset lookup is performed.
+     * Core rendering uses `classic`; select the current render styles through `/studio`.
+     */
+    artStyle: ArtStyle;
+    /** Explicit fine-dither treatment for the optional hover compositor. */
+    fineDither?: boolean;
+    /**
+     * 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`.
+     *
+     * Supply your own array of character ramps:
+     * @example
+     * options: { charsetFrames: [CHARACTER_SETS.standard.chars, CHARACTER_SETS.blocks.chars] }
+     */
+    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 DEFAULT_OPTIONS: AsciiOptions;
+/**
+ * Hover presets — one-click configurations for the hover system.
+ */
+declare const HOVER_PRESETS: Record<HoverPreset, {
+    label: string;
+    options: Partial<AsciiOptions>;
+}>;
+
+export { type AsciiFrame as A, type ColorMode as C, DEFAULT_OPTIONS as D, type HoverEffect as H, PALETTE_THEMES as P, type RenderMode as R, type SourceType as S, type AsciiOptions as a, type ArtStyle as b, type AnimationStyle as c, type AsciiCell as d, type AsciiResult as e, HOVER_PRESETS as f, type HoverPreset as g, type HoverShape as h, type PaletteTheme as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciify-engine",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Framework-agnostic ASCII art engine. Convert images, videos, and GIFs into ASCII art rendered on canvas.",
   "type": "module",
   "main": "./dist/index.cjs",