asciify-engine 1.0.32 → 1.0.35

package/dist/index.d.cts

@@ -17,24 +17,99 @@ declare const PALETTE_THEMES: Record<PaletteTheme, {
 }>;
 type SourceType = 'image' | 'video' | 'gif' | null;
 interface AsciiOptions {
+    /** Character cell size in pixels. Smaller = more detail, more cells. Default: `10` */
     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'`
+     */
     accentColor: string;
+    /** Invert luminance mapping (light pixels → dense chars). Default: `false` */
     invert: boolean;
+    /**
+     * 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;
+    /**
+     * Floyd-Steinberg dither strength applied to the luminance map.
+     * `0` = no dithering, `1` = full dithering. Default: `0`
+     */
     ditherStrength: number;
+    /**
+     * 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;
+    /**
+     * 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;
 }
 interface AsciiCell {
@@ -130,8 +205,12 @@ declare function renderFrameToCanvas(ctx: CanvasRenderingContext2D, frame: Ascii
 interface AsciifySimpleOptions {
     /** Character size in pixels. Default: 10 */
     fontSize?: number;
-    /** Art style preset. Default: 'classic' */
-    style?: ArtStyle;
+    /**
+     * 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>;
 }
@@ -140,9 +219,9 @@ interface AsciifySimpleOptions {
  *
  * @example
  * await asciify(document.querySelector('img'), canvas);
- * await asciify(img, canvas, { fontSize: 8, style: 'letters' });
+ * await asciify(img, canvas, { fontSize: 8, artStyle: 'letters' });
  */
-declare function asciify(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | string, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<void>;
+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.
@@ -151,7 +230,7 @@ declare function asciify(source: HTMLImageElement | HTMLVideoElement | HTMLCanva
  * const stop = await asciifyGif('animation.gif', canvas);
  * // later: stop();
  */
-declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
+declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<() => void>;
 /**
  * Convert a video element to ASCII art and start an animation loop on a canvas.
  * Returns a `stop()` function that cancels the loop.
@@ -160,7 +239,7 @@ declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElem
  * const stop = await asciifyVideo(video, canvas);
  * // later: stop();
  */
-declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
+declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<() => void>;
 
 interface WaveBackgroundOptions {
     /** Font size in CSS pixels (default: 13) */
@@ -711,66 +790,108 @@ declare function renderTextBackground(ctx: CanvasRenderingContext2D, width: numb
     intensity?: number;
 } | null): void;
 
-/**
- * record() — capture a rolling frame buffer from a running ASCII canvas
- * and export it as a downloadable animated GIF or WebP data URL.
- *
- * Usage:
- * ```ts
- * const recorder = createRecorder(canvasEl, { fps: 15, maxFrames: 120 });
- * recorder.start();
- * // ... after a few seconds ...
- * const dataUrl = await recorder.stop(); // 'data:image/gif;base64,...'
- * ```
- */
-interface RecorderOptions {
-    /** Target capture frame rate (default: 15) */
-    fps?: number;
-    /** Maximum number of frames to buffer (default: 120 → 8 s at 15 fps) */
-    maxFrames?: number;
-    /**
-     * Output format.
-     * - 'gif'  — animated GIF via gif.js worker (requires gif.worker.js in public/)
-     * - 'webp' — animated WebP via MediaRecorder API (Chrome/Edge only)
-     * - 'png-sequence' — returns a JSON array of PNG data URLs (universal)
-     * Default: 'gif'
-     */
-    format?: 'gif' | 'webp' | 'png-sequence';
-    /** GIF quality 1 (best) – 30 (smallest) — only used for format:'gif' (default: 10) */
+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 to the canvas before capture (default: 1).
-     * Use 0.5 to halve dimensions and reduce file size.
+     * Scale factor applied before capture. Default: 1.
+     * Use 2 for a high-resolution export at 2× the canvas size.
      */
     scale?: number;
 }
-interface Recorder {
-    /** Start capturing frames from the canvas. */
-    start(): void;
-    /**
-     * Stop capturing and encode.
-     * Resolves with a data URL (gif/webp) or JSON string (png-sequence).
-     */
-    stop(): Promise<string>;
-    /** True while recording. */
-    readonly isRecording: boolean;
-    /** Number of frames captured so far. */
-    readonly frameCount: number;
-}
 /**
- * Create a Recorder bound to a canvas element.
+ * Capture a single frame from a canvas as a Blob.
+ *
+ * @example
+ * ```ts
+ * const blob = await captureSnapshot(canvas);
+ * const url = URL.createObjectURL(blob);
+ * ```
  */
-declare function createRecorder(canvas: HTMLCanvasElement, options?: RecorderOptions): Recorder;
+declare function captureSnapshot(canvas: HTMLCanvasElement, { format, quality, scale }?: SnapshotOptions): Promise<Blob>;
 /**
- * Convenience: record for a fixed duration and auto-download.
+ * Capture a single frame and immediately trigger a browser download.
  *
  * @example
  * ```ts
- * await recordAndDownload(canvasEl, 3000, { fps: 15, format: 'gif' });
+ * await snapshotAndDownload(canvas);
+ * await snapshotAndDownload(canvas, { format: 'jpeg', filename: 'my-art' });
  * ```
  */
-declare function recordAndDownload(canvas: HTMLCanvasElement, durationMs: number, options?: RecorderOptions & {
+declare function snapshotAndDownload(canvas: HTMLCanvasElement, options?: SnapshotOptions & {
     filename?: string;
 }): Promise<void>;
 
-export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, type AuroraBackgroundOptions, CHARSETS, type CharsetKey, type CircuitBackgroundOptions, type ColorMode, DEFAULT_OPTIONS, type DnaBackgroundOptions, type FireBackgroundOptions, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MorphBackgroundOptions, type MountWaveOptions, type NoiseBackgroundOptions, PALETTE_THEMES, type PaletteTheme, type PulseBackgroundOptions, type RainBackgroundOptions, type Recorder, type RecorderOptions, type RenderMode, type SilkBackgroundOptions, type SourceType, type StarsBackgroundOptions, type TerrainBackgroundOptions, type TextBackgroundOptions, type VoidBackgroundOptions, type WaveBackgroundOptions, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyVideo, buildTextFrame, createRecorder, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, recordAndDownload, renderAuroraBackground, renderCircuitBackground, renderDnaBackground, renderFireBackground, renderFrameToCanvas, renderGridBackground, renderMorphBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderSilkBackground, renderStarsBackground, renderTerrainBackground, renderTextBackground, renderVoidBackground, renderWaveBackground, videoToAsciiFrames };
+/**
+ * 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>;
+
+export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, type AuroraBackgroundOptions, CHARSETS, type CharsetKey, type CircuitBackgroundOptions, type ColorMode, DEFAULT_OPTIONS, type DnaBackgroundOptions, type FireBackgroundOptions, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MorphBackgroundOptions, type MountWaveOptions, type NoiseBackgroundOptions, PALETTE_THEMES, type PaletteTheme, type PulseBackgroundOptions, type RainBackgroundOptions, type RenderMode, type SilkBackgroundOptions, type SnapshotOptions, type SourceType, type StarsBackgroundOptions, type TerrainBackgroundOptions, type TextBackgroundOptions, type VoidBackgroundOptions, type WaveBackgroundOptions, type WebcamOptions, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyVideo, asciifyWebcam, buildTextFrame, captureSnapshot, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderAuroraBackground, renderCircuitBackground, renderDnaBackground, renderFireBackground, renderFrameToCanvas, renderGridBackground, renderMorphBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderSilkBackground, renderStarsBackground, renderTerrainBackground, renderTextBackground, renderVoidBackground, renderWaveBackground, snapshotAndDownload, videoToAsciiFrames };

package/dist/index.d.ts

@@ -17,24 +17,99 @@ declare const PALETTE_THEMES: Record<PaletteTheme, {
 }>;
 type SourceType = 'image' | 'video' | 'gif' | null;
 interface AsciiOptions {
+    /** Character cell size in pixels. Smaller = more detail, more cells. Default: `10` */
     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'`
+     */
     accentColor: string;
+    /** Invert luminance mapping (light pixels → dense chars). Default: `false` */
     invert: boolean;
+    /**
+     * 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;
+    /**
+     * Floyd-Steinberg dither strength applied to the luminance map.
+     * `0` = no dithering, `1` = full dithering. Default: `0`
+     */
     ditherStrength: number;
+    /**
+     * 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;
+    /**
+     * 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;
 }
 interface AsciiCell {
@@ -130,8 +205,12 @@ declare function renderFrameToCanvas(ctx: CanvasRenderingContext2D, frame: Ascii
 interface AsciifySimpleOptions {
     /** Character size in pixels. Default: 10 */
     fontSize?: number;
-    /** Art style preset. Default: 'classic' */
-    style?: ArtStyle;
+    /**
+     * 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>;
 }
@@ -140,9 +219,9 @@ interface AsciifySimpleOptions {
  *
  * @example
  * await asciify(document.querySelector('img'), canvas);
- * await asciify(img, canvas, { fontSize: 8, style: 'letters' });
+ * await asciify(img, canvas, { fontSize: 8, artStyle: 'letters' });
  */
-declare function asciify(source: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | string, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<void>;
+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.
@@ -151,7 +230,7 @@ declare function asciify(source: HTMLImageElement | HTMLVideoElement | HTMLCanva
  * const stop = await asciifyGif('animation.gif', canvas);
  * // later: stop();
  */
-declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
+declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<() => void>;
 /**
  * Convert a video element to ASCII art and start an animation loop on a canvas.
  * Returns a `stop()` function that cancels the loop.
@@ -160,7 +239,7 @@ declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElem
  * const stop = await asciifyVideo(video, canvas);
  * // later: stop();
  */
-declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, style, options }?: AsciifySimpleOptions): Promise<() => void>;
+declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<() => void>;
 
 interface WaveBackgroundOptions {
     /** Font size in CSS pixels (default: 13) */
@@ -711,66 +790,108 @@ declare function renderTextBackground(ctx: CanvasRenderingContext2D, width: numb
     intensity?: number;
 } | null): void;
 
-/**
- * record() — capture a rolling frame buffer from a running ASCII canvas
- * and export it as a downloadable animated GIF or WebP data URL.
- *
- * Usage:
- * ```ts
- * const recorder = createRecorder(canvasEl, { fps: 15, maxFrames: 120 });
- * recorder.start();
- * // ... after a few seconds ...
- * const dataUrl = await recorder.stop(); // 'data:image/gif;base64,...'
- * ```
- */
-interface RecorderOptions {
-    /** Target capture frame rate (default: 15) */
-    fps?: number;
-    /** Maximum number of frames to buffer (default: 120 → 8 s at 15 fps) */
-    maxFrames?: number;
-    /**
-     * Output format.
-     * - 'gif'  — animated GIF via gif.js worker (requires gif.worker.js in public/)
-     * - 'webp' — animated WebP via MediaRecorder API (Chrome/Edge only)
-     * - 'png-sequence' — returns a JSON array of PNG data URLs (universal)
-     * Default: 'gif'
-     */
-    format?: 'gif' | 'webp' | 'png-sequence';
-    /** GIF quality 1 (best) – 30 (smallest) — only used for format:'gif' (default: 10) */
+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 to the canvas before capture (default: 1).
-     * Use 0.5 to halve dimensions and reduce file size.
+     * Scale factor applied before capture. Default: 1.
+     * Use 2 for a high-resolution export at 2× the canvas size.
      */
     scale?: number;
 }
-interface Recorder {
-    /** Start capturing frames from the canvas. */
-    start(): void;
-    /**
-     * Stop capturing and encode.
-     * Resolves with a data URL (gif/webp) or JSON string (png-sequence).
-     */
-    stop(): Promise<string>;
-    /** True while recording. */
-    readonly isRecording: boolean;
-    /** Number of frames captured so far. */
-    readonly frameCount: number;
-}
 /**
- * Create a Recorder bound to a canvas element.
+ * Capture a single frame from a canvas as a Blob.
+ *
+ * @example
+ * ```ts
+ * const blob = await captureSnapshot(canvas);
+ * const url = URL.createObjectURL(blob);
+ * ```
  */
-declare function createRecorder(canvas: HTMLCanvasElement, options?: RecorderOptions): Recorder;
+declare function captureSnapshot(canvas: HTMLCanvasElement, { format, quality, scale }?: SnapshotOptions): Promise<Blob>;
 /**
- * Convenience: record for a fixed duration and auto-download.
+ * Capture a single frame and immediately trigger a browser download.
  *
  * @example
  * ```ts
- * await recordAndDownload(canvasEl, 3000, { fps: 15, format: 'gif' });
+ * await snapshotAndDownload(canvas);
+ * await snapshotAndDownload(canvas, { format: 'jpeg', filename: 'my-art' });
  * ```
  */
-declare function recordAndDownload(canvas: HTMLCanvasElement, durationMs: number, options?: RecorderOptions & {
+declare function snapshotAndDownload(canvas: HTMLCanvasElement, options?: SnapshotOptions & {
     filename?: string;
 }): Promise<void>;
 
-export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, type AuroraBackgroundOptions, CHARSETS, type CharsetKey, type CircuitBackgroundOptions, type ColorMode, DEFAULT_OPTIONS, type DnaBackgroundOptions, type FireBackgroundOptions, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MorphBackgroundOptions, type MountWaveOptions, type NoiseBackgroundOptions, PALETTE_THEMES, type PaletteTheme, type PulseBackgroundOptions, type RainBackgroundOptions, type Recorder, type RecorderOptions, type RenderMode, type SilkBackgroundOptions, type SourceType, type StarsBackgroundOptions, type TerrainBackgroundOptions, type TextBackgroundOptions, type VoidBackgroundOptions, type WaveBackgroundOptions, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyVideo, buildTextFrame, createRecorder, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, recordAndDownload, renderAuroraBackground, renderCircuitBackground, renderDnaBackground, renderFireBackground, renderFrameToCanvas, renderGridBackground, renderMorphBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderSilkBackground, renderStarsBackground, renderTerrainBackground, renderTextBackground, renderVoidBackground, renderWaveBackground, videoToAsciiFrames };
+/**
+ * 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>;
+
+export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, type AuroraBackgroundOptions, CHARSETS, type CharsetKey, type CircuitBackgroundOptions, type ColorMode, DEFAULT_OPTIONS, type DnaBackgroundOptions, type FireBackgroundOptions, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MorphBackgroundOptions, type MountWaveOptions, type NoiseBackgroundOptions, PALETTE_THEMES, type PaletteTheme, type PulseBackgroundOptions, type RainBackgroundOptions, type RenderMode, type SilkBackgroundOptions, type SnapshotOptions, type SourceType, type StarsBackgroundOptions, type TerrainBackgroundOptions, type TextBackgroundOptions, type VoidBackgroundOptions, type WaveBackgroundOptions, type WebcamOptions, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyVideo, asciifyWebcam, buildTextFrame, captureSnapshot, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderAuroraBackground, renderCircuitBackground, renderDnaBackground, renderFireBackground, renderFrameToCanvas, renderGridBackground, renderMorphBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderSilkBackground, renderStarsBackground, renderTerrainBackground, renderTextBackground, renderVoidBackground, renderWaveBackground, snapshotAndDownload, videoToAsciiFrames };