asciify-engine 1.0.11 → 1.0.12

package/dist/index.d.cts

@@ -253,32 +253,55 @@ declare function renderWaveBackground(ctx: CanvasRenderingContext2D, width: numb
 }, options?: WaveBackgroundOptions): void;
 /**
  * Drop-in helper that mounts an interactive ASCII wave background onto any
- * element. Creates and injects a `<canvas>`, wires mouse tracking, DPR
- * resize, and the RAF loop — all internally.
+ * element. Injects a canvas, wires DPR resize, mouse tracking, and the RAF
+ * loop — all internally. Auto-detects light/dark mode and stays in sync if
+ * the system theme changes.
  *
  * Returns a `destroy()` function to clean everything up.
  *
  * @example
  * ```ts
- * // 1 line — that's it:
- * import { mountWaveBackground } from 'asciify-engine';
- * const { destroy } = mountWaveBackground('#hero', { opacity: 0.2 });
+ * import { asciiBackground } from 'asciify-engine';
  *
- * // React:
- * useEffect(() => mountWaveBackground(ref.current).destroy, []);
+ * // 1 line:
+ * const { destroy } = asciiBackground('#hero', { opacity: 0.2 });
+ *
+ * // Custom color:
+ * asciiBackground('#hero', { color: '#6b8700', accentColor: '#d4ff00' });
+ *
+ * // React — return destroy as cleanup:
+ * useEffect(() => asciiBackground(ref.current).destroy, []);
  * ```
  */
-interface MountWaveOptions extends WaveBackgroundOptions {
+interface AsciiBackgroundOptions extends WaveBackgroundOptions {
     /** CSS opacity applied to the canvas element (default: 0.2) */
     opacity?: number;
     /** Extra CSS class names added to the injected canvas */
     className?: string;
     /** z-index of the canvas (default: 0) */
     zIndex?: number;
+    /**
+     * Colour scheme handling (default: 'auto').
+     * - 'auto'  — follows the system prefers-color-scheme and updates live
+     * - 'dark'  — always render dark-on-dark (bright chars on dark bg)
+     * - 'light' — always render dark chars on light background
+     */
+    colorScheme?: 'auto' | 'light' | 'dark';
+    /**
+     * Custom character colour. Accepts any CSS colour string: hex, rgb(), hsl().
+     * When set, overrides the default white/black colour for the ASCII chars.
+     * The accent colour remains separate — use `accentColor` to change it.
+     * @example '#6b8700'
+     */
+    color?: string;
 }
-declare function mountWaveBackground(target: string | HTMLElement, options?: MountWaveOptions): {
+declare function asciiBackground(target: string | HTMLElement | null, options?: AsciiBackgroundOptions): {
     destroy: () => void;
 };
+/** @deprecated Use `asciiBackground` instead. */
+declare const mountWaveBackground: typeof asciiBackground;
+/** @deprecated Use `AsciiBackgroundOptions` instead. */
+type MountWaveOptions = AsciiBackgroundOptions;
 
 interface WebGLRenderer {
     render(frame: AsciiFrame, options: AsciiOptions, displayW: number, displayH: number, time: number, hoverPos?: {
@@ -297,4 +320,4 @@ interface WebGLRenderer {
  */
 declare function tryCreateWebGLRenderer(canvas: HTMLCanvasElement): WebGLRenderer | null;
 
-export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, CHARSETS, type CharsetKey, type ColorMode, DEFAULT_OPTIONS, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MountWaveOptions, type RenderMode, type SourceType, type WaveBackgroundOptions, type WebGLRenderer, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderFrameToCanvas, renderWaveBackground, tryCreateWebGLRenderer, videoToAsciiFrames };
+export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, CHARSETS, type CharsetKey, type ColorMode, DEFAULT_OPTIONS, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MountWaveOptions, type RenderMode, type SourceType, type WaveBackgroundOptions, type WebGLRenderer, asciiBackground, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderFrameToCanvas, renderWaveBackground, tryCreateWebGLRenderer, videoToAsciiFrames };

package/dist/index.d.ts

@@ -253,32 +253,55 @@ declare function renderWaveBackground(ctx: CanvasRenderingContext2D, width: numb
 }, options?: WaveBackgroundOptions): void;
 /**
  * Drop-in helper that mounts an interactive ASCII wave background onto any
- * element. Creates and injects a `<canvas>`, wires mouse tracking, DPR
- * resize, and the RAF loop — all internally.
+ * element. Injects a canvas, wires DPR resize, mouse tracking, and the RAF
+ * loop — all internally. Auto-detects light/dark mode and stays in sync if
+ * the system theme changes.
  *
  * Returns a `destroy()` function to clean everything up.
  *
  * @example
  * ```ts
- * // 1 line — that's it:
- * import { mountWaveBackground } from 'asciify-engine';
- * const { destroy } = mountWaveBackground('#hero', { opacity: 0.2 });
+ * import { asciiBackground } from 'asciify-engine';
  *
- * // React:
- * useEffect(() => mountWaveBackground(ref.current).destroy, []);
+ * // 1 line:
+ * const { destroy } = asciiBackground('#hero', { opacity: 0.2 });
+ *
+ * // Custom color:
+ * asciiBackground('#hero', { color: '#6b8700', accentColor: '#d4ff00' });
+ *
+ * // React — return destroy as cleanup:
+ * useEffect(() => asciiBackground(ref.current).destroy, []);
  * ```
  */
-interface MountWaveOptions extends WaveBackgroundOptions {
+interface AsciiBackgroundOptions extends WaveBackgroundOptions {
     /** CSS opacity applied to the canvas element (default: 0.2) */
     opacity?: number;
     /** Extra CSS class names added to the injected canvas */
     className?: string;
     /** z-index of the canvas (default: 0) */
     zIndex?: number;
+    /**
+     * Colour scheme handling (default: 'auto').
+     * - 'auto'  — follows the system prefers-color-scheme and updates live
+     * - 'dark'  — always render dark-on-dark (bright chars on dark bg)
+     * - 'light' — always render dark chars on light background
+     */
+    colorScheme?: 'auto' | 'light' | 'dark';
+    /**
+     * Custom character colour. Accepts any CSS colour string: hex, rgb(), hsl().
+     * When set, overrides the default white/black colour for the ASCII chars.
+     * The accent colour remains separate — use `accentColor` to change it.
+     * @example '#6b8700'
+     */
+    color?: string;
 }
-declare function mountWaveBackground(target: string | HTMLElement, options?: MountWaveOptions): {
+declare function asciiBackground(target: string | HTMLElement | null, options?: AsciiBackgroundOptions): {
     destroy: () => void;
 };
+/** @deprecated Use `asciiBackground` instead. */
+declare const mountWaveBackground: typeof asciiBackground;
+/** @deprecated Use `AsciiBackgroundOptions` instead. */
+type MountWaveOptions = AsciiBackgroundOptions;
 
 interface WebGLRenderer {
     render(frame: AsciiFrame, options: AsciiOptions, displayW: number, displayH: number, time: number, hoverPos?: {
@@ -297,4 +320,4 @@ interface WebGLRenderer {
  */
 declare function tryCreateWebGLRenderer(canvas: HTMLCanvasElement): WebGLRenderer | null;
 
-export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, CHARSETS, type CharsetKey, type ColorMode, DEFAULT_OPTIONS, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MountWaveOptions, type RenderMode, type SourceType, type WaveBackgroundOptions, type WebGLRenderer, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderFrameToCanvas, renderWaveBackground, tryCreateWebGLRenderer, videoToAsciiFrames };
+export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, CHARSETS, type CharsetKey, type ColorMode, DEFAULT_OPTIONS, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MountWaveOptions, type RenderMode, type SourceType, type WaveBackgroundOptions, type WebGLRenderer, asciiBackground, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderFrameToCanvas, renderWaveBackground, tryCreateWebGLRenderer, videoToAsciiFrames };

package/dist/index.js

@@ -830,7 +830,7 @@ async function asciifyVideo(source, canvas, { fontSize = 10, style = "classic",
     cancelAnimationFrame(animId);
   };
 }
-var EMBED_CDN_VERSION = "1.0.11";
+var EMBED_CDN_VERSION = "1.0.12";
 function buildEmbedOpts(options, rows, cols, width, height, fps, animated) {
   const o = {
     r: rows,
@@ -997,11 +997,28 @@ function renderWaveBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
     }
   }
 }
-function mountWaveBackground(target, options = {}) {
-  const { opacity = 0.2, className, zIndex = 0, ...renderOpts } = options;
+function _parseColor(c) {
+  const hex = c.match(/^#([0-9a-f]{3,8})$/i)?.[1];
+  if (hex) {
+    const h = hex.length <= 4 ? hex.split("").map((x) => parseInt(x + x, 16)) : [parseInt(hex.slice(0, 2), 16), parseInt(hex.slice(2, 4), 16), parseInt(hex.slice(4, 6), 16)];
+    return { r: h[0], g: h[1], b: h[2] };
+  }
+  const rgb = c.match(/rgba?\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)/i);
+  if (rgb) return { r: +rgb[1], g: +rgb[2], b: +rgb[3] };
+  return null;
+}
+function asciiBackground(target, options = {}) {
+  const {
+    opacity = 0.2,
+    className,
+    zIndex = 0,
+    colorScheme = "auto",
+    color,
+    ...renderOpts
+  } = options;
   const container = typeof target === "string" ? document.querySelector(target) : target;
   if (!container) {
-    console.warn("[asciify] mountWaveBackground: target not found", target);
+    console.warn("[asciify] asciiBackground: target not found", target);
     return { destroy: () => {
     } };
   }
@@ -1025,6 +1042,24 @@ function mountWaveBackground(target, options = {}) {
   const dpr = window.devicePixelRatio || 1;
   const mouse = { x: 0.5, y: 0.5 };
   const smoothMouse = { x: 0.5, y: 0.5 };
+  const mq = window.matchMedia("(prefers-color-scheme: light)");
+  const isLight = () => {
+    if (colorScheme === "light") return true;
+    if (colorScheme === "dark") return false;
+    return mq.matches;
+  };
+  let parsedColor = null;
+  if (color) parsedColor = _parseColor(color);
+  const buildOpts = () => ({
+    ...renderOpts,
+    lightMode: renderOpts.lightMode !== void 0 ? renderOpts.lightMode : isLight(),
+    baseColor: parsedColor ? `rgba(${parsedColor.r},${parsedColor.g},${parsedColor.b},{a})` : renderOpts.baseColor
+  });
+  const optsRef = { current: buildOpts() };
+  const onSchemeChange = () => {
+    optsRef.current = buildOpts();
+  };
+  if (colorScheme === "auto") mq.addEventListener("change", onSchemeChange);
   const resize = () => {
     const r = container.getBoundingClientRect();
     canvas.width = r.width * dpr;
@@ -1046,7 +1081,7 @@ function mountWaveBackground(target, options = {}) {
     smoothMouse.x += (mouse.x - smoothMouse.x) * 0.07;
     smoothMouse.y += (mouse.y - smoothMouse.y) * 0.07;
     const r = container.getBoundingClientRect();
-    renderWaveBackground(ctx, r.width, r.height, time, smoothMouse, renderOpts);
+    renderWaveBackground(ctx, r.width, r.height, time, smoothMouse, optsRef.current);
     time += 0.016;
     raf = requestAnimationFrame(tick);
   };
@@ -1055,12 +1090,14 @@ function mountWaveBackground(target, options = {}) {
     destroy: () => {
       cancelAnimationFrame(raf);
       ro.disconnect();
+      if (colorScheme === "auto") mq.removeEventListener("change", onSchemeChange);
       window.removeEventListener("mousemove", onMouseMove);
       canvas.remove();
       container.style.position = prevPosition;
     }
   };
 }
+var mountWaveBackground = asciiBackground;
 
 // src/webgl-engine.ts
 var VERT_SRC = (
@@ -1510,6 +1547,6 @@ function tryCreateWebGLRenderer(canvas) {
   }
 }
 
-export { ART_STYLE_PRESETS, CHARSETS, DEFAULT_OPTIONS, HOVER_PRESETS, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderFrameToCanvas, renderWaveBackground, tryCreateWebGLRenderer, videoToAsciiFrames };
+export { ART_STYLE_PRESETS, CHARSETS, DEFAULT_OPTIONS, HOVER_PRESETS, asciiBackground, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderFrameToCanvas, renderWaveBackground, tryCreateWebGLRenderer, videoToAsciiFrames };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map