asciify-engine 1.0.118 → 1.2.0

package/dist/core.d.ts

@@ -0,0 +1,680 @@
+import { e as AsciiOptions, d as AsciiFrame, b as ArtStyle, k as HoverEffect } from './types-w2CRgyk6.js';
+export { A as ART_STYLE_PRESETS, a as AnimationStyle, c as AsciiCell, f as AsciiResult, C as CHARSETS, g as CHARSET_SEQUENCES, h as CharsetKey, i as CharsetSequenceKey, j as ColorMode, D as DEFAULT_OPTIONS, H as HOVER_PRESETS, l as HoverPreset, m as HoverShape, L as LIVING_STYLE_PRESETS, n as LivingStylePresetKey, P as PALETTE_THEMES, o as PaletteTheme, R as RenderMode, S as SourceType } from './types-w2CRgyk6.js';
+
+/**
+ * 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 { ArtStyle, AsciiFrame, AsciiOptions, type AsciiTextFrame, type AsciifyLiveVideoOptions, type AsciifySimpleOptions, type AsciifyVideoOptions, type BigTextOptions, type CanvasBleed, type CanvasObjectFit, type CanvasRenderSizeInput, HoverEffect, type SnapshotOptions, 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 };