asciify-engine 1.0.10 → 1.0.12

package/dist/index.d.cts

@@ -251,6 +251,57 @@ declare function renderWaveBackground(ctx: CanvasRenderingContext2D, width: numb
     x: number;
     y: number;
 }, options?: WaveBackgroundOptions): void;
+/**
+ * Drop-in helper that mounts an interactive ASCII wave background onto any
+ * 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
+ * import { asciiBackground } from 'asciify-engine';
+ *
+ * // 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 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 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?: {
@@ -269,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 RenderMode, type SourceType, type WaveBackgroundOptions, type WebGLRenderer, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, 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

@@ -251,6 +251,57 @@ declare function renderWaveBackground(ctx: CanvasRenderingContext2D, width: numb
     x: number;
     y: number;
 }, options?: WaveBackgroundOptions): void;
+/**
+ * Drop-in helper that mounts an interactive ASCII wave background onto any
+ * 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
+ * import { asciiBackground } from 'asciify-engine';
+ *
+ * // 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 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 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?: {
@@ -269,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 RenderMode, type SourceType, type WaveBackgroundOptions, type WebGLRenderer, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, 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.10";
+var EMBED_CDN_VERSION = "1.0.12";
 function buildEmbedOpts(options, rows, cols, width, height, fps, animated) {
   const o = {
     r: rows,
@@ -997,6 +997,107 @@ function renderWaveBackground(ctx, width, height, time, mousePos = { x: 0.5, y:
     }
   }
 }
+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] asciiBackground: target not found", target);
+    return { destroy: () => {
+    } };
+  }
+  const prevPosition = container.style.position;
+  if (getComputedStyle(container).position === "static") {
+    container.style.position = "relative";
+  }
+  const canvas = document.createElement("canvas");
+  canvas.style.cssText = [
+    "position:absolute",
+    "inset:0",
+    "width:100%",
+    "height:100%",
+    `opacity:${opacity}`,
+    "pointer-events:none",
+    `z-index:${zIndex}`
+  ].join(";");
+  if (className) canvas.className = className;
+  container.prepend(canvas);
+  const ctx = canvas.getContext("2d");
+  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;
+    canvas.height = r.height * dpr;
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  };
+  resize();
+  const onMouseMove = (e) => {
+    const r = container.getBoundingClientRect();
+    mouse.x = (e.clientX - r.left) / r.width;
+    mouse.y = (e.clientY - r.top) / r.height;
+  };
+  const ro = new ResizeObserver(resize);
+  ro.observe(container);
+  window.addEventListener("mousemove", onMouseMove);
+  let time = 0;
+  let raf = 0;
+  const tick = () => {
+    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, optsRef.current);
+    time += 0.016;
+    raf = requestAnimationFrame(tick);
+  };
+  raf = requestAnimationFrame(tick);
+  return {
+    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 = (
@@ -1446,6 +1547,6 @@ function tryCreateWebGLRenderer(canvas) {
   }
 }
 
-export { ART_STYLE_PRESETS, CHARSETS, DEFAULT_OPTIONS, HOVER_PRESETS, asciify, asciifyGif, asciifyVideo, generateAnimatedEmbedCode, generateEmbedCode, gifToAsciiFrames, imageToAsciiFrame, 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