asciify-engine 1.0.55 → 1.0.56

package/dist/index.d.cts

@@ -174,6 +174,20 @@ interface AsciiOptions {
      * Higher values remove more pixels. Default: `60`
      */
     chromaKeyTolerance: number;
+    /**
+     * Array of charset strings to cycle through over time.
+     * The engine picks `charsetFrames[Math.floor(time * charsetFps) % length]` on each
+     * render tick, re-mapping characters from stored cell luminance.
+     * Pairs beautifully with `animationStyle` and `asciiBackground`.
+     *
+     * Use `CHARSET_SEQUENCES` for curated combinations or build your own:
+     * @example
+     * options: { charsetFrames: CHARSET_SEQUENCES.cosmic }
+     * options: { charsetFrames: [CHARSETS.standard, CHARSETS.blocks, CHARSETS.circles] }
+     */
+    charsetFrames?: string[];
+    /** Cycle rate for `charsetFrames` in frames-per-second. Default: `2` */
+    charsetFps?: number;
 }
 interface AsciiCell {
     char: string;
@@ -181,6 +195,8 @@ interface AsciiCell {
     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 {
@@ -213,6 +229,33 @@ declare const CHARSETS: {
     readonly shards: " ╱╲╳◤◥◣◢△▲◆◼█";
     readonly smoke: " ·˙⁚⁖∶∷⋮⋰⋱∴∵";
 };
+/**
+ * Curated charset sequences for use with `charsetFrames`.
+ * Each sequence morphs between 2–3 complementary charsets over time,
+ * creating a living texture effect.
+ *
+ * @example
+ * asciiBackground('#hero', { charsetFrames: CHARSET_SEQUENCES.cosmic })
+ */
+declare const CHARSET_SEQUENCES: {
+    /** Stars → softcircles → orbs — dreamy space feel */
+    readonly cosmic: string[];
+    /** Katakana → braille dots → binary — hacker rain */
+    readonly rain: string[];
+    /** Box pipes → Claude glyphs → classic — terminal morph */
+    readonly terminal: string[];
+    /** Shards → blocks → squares — shattering crystal */
+    readonly crystal: string[];
+    /** Wave glyphs → smoke dots → circles — fluid / organic */
+    readonly fluid: string[];
+    /** Dense classic → art → blocks — maximum detail pulse */
+    readonly pulse: string[];
+    /** Braille → shadows → smoke — ethereal / dream-like */
+    readonly dream: string[];
+    /** Geometric shapes → shards → starfield — sci-fi angular */
+    readonly angular: string[];
+};
+type CharsetSequenceKey = keyof typeof CHARSET_SEQUENCES;
 type CharsetKey = keyof typeof CHARSETS;
 /**
  * Art Style presets — each one sets render mode, charset, color mode, etc.
@@ -1039,4 +1082,4 @@ interface WebcamOptions {
  */
 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 AsciifyLiveVideoOptions, type AsciifySimpleOptions, type AsciifyVideoOptions, type AuroraBackgroundOptions, BACKGROUND_TYPES, type BackgroundType, 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, asciifyLiveVideo, 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 };
+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, 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 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, 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

@@ -174,6 +174,20 @@ interface AsciiOptions {
      * Higher values remove more pixels. Default: `60`
      */
     chromaKeyTolerance: number;
+    /**
+     * Array of charset strings to cycle through over time.
+     * The engine picks `charsetFrames[Math.floor(time * charsetFps) % length]` on each
+     * render tick, re-mapping characters from stored cell luminance.
+     * Pairs beautifully with `animationStyle` and `asciiBackground`.
+     *
+     * Use `CHARSET_SEQUENCES` for curated combinations or build your own:
+     * @example
+     * options: { charsetFrames: CHARSET_SEQUENCES.cosmic }
+     * options: { charsetFrames: [CHARSETS.standard, CHARSETS.blocks, CHARSETS.circles] }
+     */
+    charsetFrames?: string[];
+    /** Cycle rate for `charsetFrames` in frames-per-second. Default: `2` */
+    charsetFps?: number;
 }
 interface AsciiCell {
     char: string;
@@ -181,6 +195,8 @@ interface AsciiCell {
     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 {
@@ -213,6 +229,33 @@ declare const CHARSETS: {
     readonly shards: " ╱╲╳◤◥◣◢△▲◆◼█";
     readonly smoke: " ·˙⁚⁖∶∷⋮⋰⋱∴∵";
 };
+/**
+ * Curated charset sequences for use with `charsetFrames`.
+ * Each sequence morphs between 2–3 complementary charsets over time,
+ * creating a living texture effect.
+ *
+ * @example
+ * asciiBackground('#hero', { charsetFrames: CHARSET_SEQUENCES.cosmic })
+ */
+declare const CHARSET_SEQUENCES: {
+    /** Stars → softcircles → orbs — dreamy space feel */
+    readonly cosmic: string[];
+    /** Katakana → braille dots → binary — hacker rain */
+    readonly rain: string[];
+    /** Box pipes → Claude glyphs → classic — terminal morph */
+    readonly terminal: string[];
+    /** Shards → blocks → squares — shattering crystal */
+    readonly crystal: string[];
+    /** Wave glyphs → smoke dots → circles — fluid / organic */
+    readonly fluid: string[];
+    /** Dense classic → art → blocks — maximum detail pulse */
+    readonly pulse: string[];
+    /** Braille → shadows → smoke — ethereal / dream-like */
+    readonly dream: string[];
+    /** Geometric shapes → shards → starfield — sci-fi angular */
+    readonly angular: string[];
+};
+type CharsetSequenceKey = keyof typeof CHARSET_SEQUENCES;
 type CharsetKey = keyof typeof CHARSETS;
 /**
  * Art Style presets — each one sets render mode, charset, color mode, etc.
@@ -1039,4 +1082,4 @@ interface WebcamOptions {
  */
 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 AsciifyLiveVideoOptions, type AsciifySimpleOptions, type AsciifyVideoOptions, type AuroraBackgroundOptions, BACKGROUND_TYPES, type BackgroundType, 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, asciifyLiveVideo, 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 };
+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, 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 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, 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.js

@@ -33,6 +33,24 @@ var CHARSETS = {
   shards: " \u2571\u2572\u2573\u25E4\u25E5\u25E3\u25E2\u25B3\u25B2\u25C6\u25FC\u2588",
   smoke: " \xB7\u02D9\u205A\u2056\u2236\u2237\u22EE\u22F0\u22F1\u2234\u2235"
 };
+var CHARSET_SEQUENCES = {
+  /** Stars → softcircles → orbs — dreamy space feel */
+  cosmic: [CHARSETS.starfield, CHARSETS.circles, CHARSETS.shadows],
+  /** Katakana → braille dots → binary — hacker rain */
+  rain: [CHARSETS.katakana, CHARSETS.braille, CHARSETS.binary],
+  /** Box pipes → Claude glyphs → classic — terminal morph */
+  terminal: [CHARSETS.pipes, CHARSETS.claudeCode, CHARSETS.standard],
+  /** Shards → blocks → squares — shattering crystal */
+  crystal: [CHARSETS.shards, CHARSETS.geometric, CHARSETS.blocks],
+  /** Wave glyphs → smoke dots → circles — fluid / organic */
+  fluid: [CHARSETS.waves, CHARSETS.smoke, CHARSETS.circles],
+  /** Dense classic → art → blocks — maximum detail pulse */
+  pulse: [CHARSETS.dense, CHARSETS.standard, CHARSETS.blocks],
+  /** Braille → shadows → smoke — ethereal / dream-like */
+  dream: [CHARSETS.braille, CHARSETS.shadows, CHARSETS.smoke],
+  /** Geometric shapes → shards → starfield — sci-fi angular */
+  angular: [CHARSETS.geometric, CHARSETS.shards, CHARSETS.starfield]
+};
 var ART_STYLE_PRESETS = {
   classic: {
     renderMode: "ascii",
@@ -767,7 +785,7 @@ function imageToAsciiFrame(source, options, targetWidth, targetHeight) {
       const adjustedLum = adjustLuminance(lum, options.brightness, options.contrast);
       const ditheredLum = applyDither(adjustedLum, x, y, options.ditherStrength);
       const char = options.customText ? customTextToChar(ditheredLum, options.customText, x, y, cols, invertVal) : luminanceToChar(ditheredLum, options.charset, invertVal);
-      row.push({ char, r, g, b, a });
+      row.push({ char, r, g, b, a, lum: ditheredLum });
     }
     frame.push(row);
   }
@@ -1011,9 +1029,12 @@ function renderFrameToCanvas(ctx, frame, options, canvasWidth, canvasHeight, tim
       ctx.textBaseline = "middle";
     }
     let charWeights = null;
+    const dynFrms = options.charsetFrames;
+    const hasDyn = !!dynFrms?.length;
+    const dynCharset = hasDyn ? dynFrms[Math.floor(Math.max(0, time) * (options.charsetFps ?? 2)) % dynFrms.length] : options.charset;
     if (useFastRect) {
       charWeights = {};
-      const csChars = [...options.charset];
+      const csChars = [...dynCharset];
       const csLen = csChars.length;
       for (let i = 0; i < csLen; i++) {
         charWeights[csChars[i]] = Math.max(0.1, (i + 0.3) / csLen);
@@ -1024,7 +1045,9 @@ function renderFrameToCanvas(ctx, frame, options, canvasWidth, canvasHeight, tim
       const rowData = frame[y];
       for (let x = 0; x < cols; x++) {
         const cell = rowData[x];
-        if (cell.char === " " || cell.a < 10) continue;
+        if (cell.a < 10) continue;
+        const drawChar = hasDyn && cell.lum != null ? luminanceToChar(cell.lum, dynCharset, isInverted) : cell.char;
+        if (drawChar === " ") continue;
         const animMul = noAnimation ? 1 : getAnimationMultiplier(x, y, cols, rows, time, animStyle, animSpeed);
         if (animMul < 0.05) continue;
         let hoverScale = 1;
@@ -1064,7 +1087,7 @@ function renderFrameToCanvas(ctx, frame, options, canvasWidth, canvasHeight, tim
           color = getCellColorStr(cell, colorMode, acR, acG, acB, isInverted);
         }
         if (useFastRect) {
-          const weight = charWeights[cell.char] ?? 0.5;
+          const weight = charWeights[drawChar] ?? 0.5;
           const effAlpha = Math.min(1, cell.a * 0.00392156863 * animMul * (1 + hoverGlow)) * weight;
           if (effAlpha < 0.02) continue;
           if (effAlpha !== lastAlpha) {
@@ -1091,10 +1114,10 @@ function renderFrameToCanvas(ctx, frame, options, canvasWidth, canvasHeight, tim
           if (hoverScale !== 1) {
             ctx.translate(px, py);
             ctx.scale(hoverScale, hoverScale);
-            ctx.fillText(cell.char, 0, 0);
+            ctx.fillText(drawChar, 0, 0);
             ctx.setTransform(baseTransform);
           } else {
-            ctx.fillText(cell.char, px, py);
+            ctx.fillText(drawChar, px, py);
           }
         }
       }
@@ -2685,6 +2708,6 @@ async function asciifyWebcam(canvas, {
   };
 }
 
-export { ART_STYLE_PRESETS, BACKGROUND_TYPES, CHARSETS, DEFAULT_OPTIONS, HOVER_PRESETS, PALETTE_THEMES, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyLiveVideo, 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 };
+export { ART_STYLE_PRESETS, BACKGROUND_TYPES, CHARSETS, CHARSET_SEQUENCES, DEFAULT_OPTIONS, HOVER_PRESETS, PALETTE_THEMES, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyLiveVideo, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map