asciify-engine 1.0.79 → 1.0.81

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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';
+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';
@@ -255,6 +255,18 @@ declare const CHARSETS: {
     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`.
@@ -281,6 +293,12 @@ declare const CHARSET_SEQUENCES: {
     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;
@@ -288,6 +306,179 @@ 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 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 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 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 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;
+    };
+};
+type LivingStylePresetKey = keyof typeof LIVING_STYLE_PRESETS;
 declare const DEFAULT_OPTIONS: AsciiOptions;
 /**
  * Hover presets — one-click configurations for the hover system.
@@ -354,6 +545,49 @@ interface AsciifySimpleOptions {
     /** 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;
+    /** 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;
+}
 interface AsciifyVideoOptions extends AsciifySimpleOptions {
     /**
      * Fit the canvas to a container element, maintaining the video's aspect ratio.
@@ -376,6 +610,18 @@ interface AsciifyVideoOptions extends AsciifySimpleOptions {
      * ⚠️ Memory-intensive. Capped at 10 s / 300 frames.
      */
     preExtract?: boolean;
+    /**
+     * Target FPS for pre-extracted video frames. Lower values use less memory and
+     * make scroll scrubbing cheaper. Defaults to `18` for pre-extracted scroll
+     * scrub and the engine default for normal pre-extracted playback.
+     */
+    fps?: number;
+    /**
+     * Maximum long-edge render dimension for video frame extraction.
+     * Lower this for large full-width heroes where the canvas is CSS-scaled.
+     * Default: `2048`.
+     */
+    maxRenderDimension?: number;
     /**
      * Trim the video to a specific time range (in seconds).
      * - `start` — seek to this time before playback begins. Default: `0`
@@ -390,6 +636,25 @@ interface AsciifyVideoOptions extends AsciifySimpleOptions {
         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.
@@ -400,6 +665,13 @@ interface AsciifyVideoOptions extends AsciifySimpleOptions {
 }
 /** @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;
 /**
  * Convert an image/video/canvas element to ASCII art and render it onto a canvas.
  *
@@ -454,7 +726,7 @@ declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElem
  * // 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, preExtract, trim, onReady, onFrame }?: AsciifyVideoOptions): Promise<() => void>;
+declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options, fitTo, preExtract, fps, maxRenderDimension, trim, scroll, 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`.
@@ -1180,4 +1452,4 @@ declare function asciifyText(text: string, options?: BigTextOptions): string;
  */
 declare function renderTextToCanvas(canvas: HTMLCanvasElement, text: string, options?: BigTextOptions): void;
 
-export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifyLiveVideoOptions, type AsciifySimpleOptions, type AsciifyVideoOptions, type AuroraBackgroundOptions, BACKGROUND_TYPES, type BackgroundType, type BigTextOptions, CHARSETS, CHARSET_SEQUENCES, type CharsetKey, type CharsetSequenceKey, type CircuitBackgroundOptions, type ColorMode, DEFAULT_OPTIONS, type DnaBackgroundOptions, type FireBackgroundOptions, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type HoverShape, 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, asciifyLiveVideo, asciifyText, asciifyVideo, asciifyWebcam, buildTextFrame, captureSnapshot, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderAuroraBackground, renderCircuitBackground, renderDnaBackground, renderFireBackground, renderFrameToCanvas, renderGridBackground, renderMorphBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderSilkBackground, renderStarsBackground, renderTerrainBackground, renderTextBackground, renderTextToCanvas, renderVoidBackground, renderWaveBackground, snapshotAndDownload, videoToAsciiFrames };
+export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifyLiveVideoOptions, type AsciifySimpleOptions, type AsciifyVideoOptions, type AuroraBackgroundOptions, BACKGROUND_TYPES, type BackgroundType, type BigTextOptions, CHARSETS, CHARSET_SEQUENCES, type CharsetKey, type CharsetSequenceKey, type CircuitBackgroundOptions, type ColorMode, DEFAULT_OPTIONS, type DnaBackgroundOptions, type FireBackgroundOptions, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type HoverShape, LIVING_STYLE_PRESETS, type LivingStylePresetKey, 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 VideoScrollScrubOptions, type VoidBackgroundOptions, type WaveBackgroundOptions, type WebcamOptions, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyLiveVideo, asciifyText, asciifyVideo, asciifyWebcam, buildTextFrame, captureSnapshot, createVideoScrollScrub, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderAuroraBackground, renderCircuitBackground, renderDnaBackground, renderFireBackground, renderFrameToCanvas, renderGridBackground, renderMorphBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderSilkBackground, renderStarsBackground, renderTerrainBackground, renderTextBackground, renderTextToCanvas, renderVoidBackground, renderWaveBackground, snapshotAndDownload, videoToAsciiFrames };