interactive-bg 0.0.0-stage → 0.1.0

package/dist/core/engine.cjs

@@ -0,0 +1,367 @@
+const require_surface = require("./surface.cjs");
+// src/core/engine.ts
+var engineDefaults = Object.freeze({
+	renderer: "auto",
+	backgroundColor: null,
+	fadeOutTop: 0,
+	fadeOutRight: 0,
+	fadeOutBottom: 0,
+	fadeOutLeft: 0,
+	interactive: true,
+	maxDpr: 1.5,
+	maxFps: 60,
+	idleFps: 30,
+	respectReducedMotion: true
+});
+/**
+* Mount an interactive background.
+*
+* - `target` `null`/omitted: a fixed, full-viewport canvas is placed behind the page.
+* - `target` is a `<canvas>`: it is drawn into directly and sized by your CSS.
+* - `target` is any other element (or a selector): a canvas is appended that
+*   fills it. The element gets `position: relative` if it was `static`.
+*
+* @example createBackground('#hero', topo({ levels: 14 }), { maxFps: 30 })
+*/
+function createBackground(target, style, engineOptions = {}) {
+	const host = typeof target === "string" ? document.querySelector(target) : target;
+	if (typeof target === "string" && !host) throw new Error(`interactive-bg: no element matches "${target}"`);
+	const definition = style.definition;
+	let options = { ...style.options };
+	let engine = {
+		...engineDefaults,
+		...engineOptions
+	};
+	let backgroundColor = resolveColor(engine.backgroundColor);
+	let fade = resolveFade(engine);
+	const ownsCanvas = !(host instanceof HTMLCanvasElement);
+	const hostPosition = ownsCanvas && host ? host.style.position : null;
+	let canvas = ownsCanvas ? mountCanvas(host ?? null) : host;
+	const surface = require_surface.createSurface(() => canvas, definition.renderers, options, engine.renderer, () => {
+		needsDraw = true;
+		wake();
+	}, ownsCanvas ? () => {
+		const fresh = mountCanvas(host ?? null);
+		canvas.remove();
+		canvas = fresh;
+	} : void 0) ?? blankSurface(definition);
+	let width = 0;
+	let height = 0;
+	let dpr = 1;
+	let pointerX = 0;
+	let pointerY = 0;
+	let targetX = 0;
+	let targetY = 0;
+	let influence = 0;
+	let targetInfluence = 0;
+	/** Clicks since the last rendered frame, and the array handed to the style for the current one (swapped each frame). */
+	let clicks = [];
+	let frameClicks = [];
+	const pointer = {
+		x: 0,
+		y: 0,
+		influence: 0
+	};
+	const frameState = {
+		width: 0,
+		height: 0,
+		dpr: 1,
+		dt: 0,
+		reducedMotion: false,
+		pointer,
+		clicks: frameClicks
+	};
+	/** The style reported a short-lived effect still playing in its last frame. */
+	let styleBusy = false;
+	let lastFrame = 0;
+	let rafId = 0;
+	let timerId = 0;
+	let paused = false;
+	let visible = true;
+	let intersecting = true;
+	let destroyed = false;
+	let needsDraw = true;
+	const reducedMotionQuery = window.matchMedia?.("(prefers-reduced-motion: reduce)");
+	let reducedMotion = reducedMotionQuery?.matches ?? false;
+	function holdStill() {
+		return engine.respectReducedMotion && reducedMotion;
+	}
+	/** Is the style's own ambient animation running (as opposed to only reacting to the pointer)? */
+	function animating() {
+		return surface.name !== null && definition.animates(options) && !holdStill();
+	}
+	/** Does something need the full frame rate: the pointer's effect easing, or a style effect playing? */
+	function busy() {
+		return styleBusy || clicks.length > 0 || pointerEasing();
+	}
+	/** Frame rate for the ambient animation; `0` means uncapped for the engine options. */
+	function effectiveIdleFps() {
+		const configured = engine.maxFps <= 0 ? engine.idleFps : engine.idleFps <= 0 ? engine.maxFps : Math.min(engine.maxFps, engine.idleFps);
+		const needed = definition.idleFps?.(options) ?? 0;
+		if (needed <= 0) return configured;
+		return configured <= 0 ? needed : Math.min(configured, needed);
+	}
+	function frameInterval(fps) {
+		return fps > 0 ? 1e3 / fps : 0;
+	}
+	function canRun() {
+		return !destroyed && !paused && visible;
+	}
+	/** Is the pointer's effect still catching up with the pointer? */
+	function pointerEasing() {
+		if (influence !== targetInfluence) return true;
+		return influence > 0 && (Math.abs(targetX - pointerX) > .5 || Math.abs(targetY - pointerY) > .5);
+	}
+	function resize() {
+		const rect = canvas.getBoundingClientRect();
+		const nextWidth = Math.max(1, Math.round(rect.width));
+		const nextHeight = Math.max(1, Math.round(rect.height));
+		const nextDpr = Math.min(window.devicePixelRatio || 1, Math.max(.5, engine.maxDpr));
+		if (nextWidth === width && nextHeight === height && nextDpr === dpr) return;
+		width = nextWidth;
+		height = nextHeight;
+		dpr = nextDpr;
+		canvas.width = Math.round(width * dpr);
+		canvas.height = Math.round(height * dpr);
+		needsDraw = true;
+	}
+	function frame(now) {
+		rafId = 0;
+		if (!canRun()) return;
+		const minInterval = frameInterval(busy() ? engine.maxFps : effectiveIdleFps());
+		if (lastFrame && now - lastFrame < minInterval * .85) {
+			schedule(minInterval - (now - lastFrame));
+			return;
+		}
+		const dt = lastFrame ? Math.min((now - lastFrame) / 1e3, .1) : 0;
+		lastFrame = now;
+		const wasBusy = busy();
+		const ease = 1 - Math.exp(-dt * 8);
+		pointerX += (targetX - pointerX) * ease;
+		pointerY += (targetY - pointerY) * ease;
+		influence += (targetInfluence - influence) * ease;
+		if (Math.abs(targetInfluence - influence) < .001) influence = targetInfluence;
+		const moving = animating();
+		if (moving || wasBusy || needsDraw) {
+			needsDraw = false;
+			[frameClicks, clicks] = [clicks, frameClicks];
+			clicks.length = 0;
+			pointer.x = pointerX;
+			pointer.y = pointerY;
+			pointer.influence = influence;
+			frameState.width = width;
+			frameState.height = height;
+			frameState.dpr = dpr;
+			frameState.dt = dt;
+			frameState.reducedMotion = holdStill();
+			frameState.clicks = frameClicks;
+			styleBusy = surface.render(frameState, backgroundColor, fade);
+		}
+		if (busy()) schedule();
+		else if (moving) schedule(frameInterval(effectiveIdleFps()));
+		else lastFrame = 0;
+	}
+	/** Request a frame `delay` ms from now. */
+	function schedule(delay = 0) {
+		if (rafId || timerId || !canRun()) return;
+		if (delay > 8) timerId = window.setTimeout(onTimer, delay * .8);
+		else rafId = requestAnimationFrame(frame);
+	}
+	function onTimer() {
+		timerId = 0;
+		schedule();
+	}
+	/** Render as soon as possible, cutting short any idle sleep. */
+	function wake() {
+		if (timerId) clearTimeout(timerId);
+		timerId = 0;
+		schedule();
+	}
+	function cancel() {
+		if (rafId) cancelAnimationFrame(rafId);
+		if (timerId) clearTimeout(timerId);
+		rafId = timerId = 0;
+	}
+	function onPointerMove(event) {
+		if (!engine.interactive || !canRun()) return;
+		const rect = canvas.getBoundingClientRect();
+		const x = event.clientX - rect.left;
+		const y = event.clientY - rect.top;
+		const inside = x >= 0 && y >= 0 && x <= rect.width && y <= rect.height;
+		if (inside && targetInfluence === 0) {
+			pointerX = x;
+			pointerY = y;
+		}
+		targetX = x;
+		targetY = y;
+		targetInfluence = inside ? 1 : 0;
+		if (inside || influence > 0) wake();
+	}
+	function onPointerDown(event) {
+		if (!engine.interactive || !canRun()) return;
+		const rect = canvas.getBoundingClientRect();
+		const x = event.clientX - rect.left;
+		const y = event.clientY - rect.top;
+		if (x < 0 || y < 0 || x > rect.width || y > rect.height) return;
+		clicks.push({
+			x,
+			y
+		});
+		wake();
+	}
+	function onPointerLeave() {
+		targetInfluence = 0;
+		wake();
+	}
+	function onVisibilityChange() {
+		visible = document.visibilityState === "visible" && intersecting;
+		lastFrame = 0;
+		if (visible) wake();
+		else cancel();
+	}
+	function onReducedMotionChange(event) {
+		reducedMotion = event.matches;
+		needsDraw = true;
+		wake();
+	}
+	let dprQuery = null;
+	function watchDpr() {
+		dprQuery?.removeEventListener?.("change", onDprChange);
+		dprQuery = window.matchMedia?.(`(resolution: ${window.devicePixelRatio || 1}dppx)`) ?? null;
+		dprQuery?.addEventListener?.("change", onDprChange);
+	}
+	function onDprChange() {
+		resize();
+		wake();
+		watchDpr();
+	}
+	watchDpr();
+	const resizeObserver = new ResizeObserver(() => {
+		resize();
+		wake();
+	});
+	resizeObserver.observe(canvas);
+	const intersectionObserver = typeof IntersectionObserver === "function" ? new IntersectionObserver((entries) => {
+		intersecting = entries[entries.length - 1].isIntersecting;
+		onVisibilityChange();
+	}) : null;
+	intersectionObserver?.observe(canvas);
+	window.addEventListener("pointermove", onPointerMove, { passive: true });
+	window.addEventListener("pointerdown", onPointerDown, { passive: true });
+	document.documentElement.addEventListener("pointerleave", onPointerLeave);
+	document.addEventListener("visibilitychange", onVisibilityChange);
+	reducedMotionQuery?.addEventListener?.("change", onReducedMotionChange);
+	resize();
+	schedule();
+	return {
+		canvas,
+		style: definition.name,
+		renderer: surface.name,
+		get options() {
+			return options;
+		},
+		get engineOptions() {
+			return engine;
+		},
+		setOptions(next) {
+			options = {
+				...options,
+				...next
+			};
+			surface.update(options);
+			needsDraw = true;
+			wake();
+		},
+		setEngineOptions(next) {
+			const previous = engine;
+			engine = {
+				...engine,
+				...next
+			};
+			backgroundColor = resolveColor(engine.backgroundColor);
+			fade = resolveFade(engine);
+			if (engine.maxDpr !== previous.maxDpr) resize();
+			if (!engine.interactive) {
+				influence = targetInfluence = 0;
+				clicks.length = 0;
+			}
+			needsDraw = true;
+			wake();
+		},
+		pause() {
+			paused = true;
+			cancel();
+		},
+		resume() {
+			paused = false;
+			lastFrame = 0;
+			wake();
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			cancel();
+			resizeObserver.disconnect();
+			intersectionObserver?.disconnect();
+			window.removeEventListener("pointermove", onPointerMove);
+			window.removeEventListener("pointerdown", onPointerDown);
+			document.documentElement.removeEventListener("pointerleave", onPointerLeave);
+			document.removeEventListener("visibilitychange", onVisibilityChange);
+			reducedMotionQuery?.removeEventListener?.("change", onReducedMotionChange);
+			dprQuery?.removeEventListener?.("change", onDprChange);
+			if (!ownsCanvas) surface.clear();
+			surface.destroy();
+			if (ownsCanvas) {
+				if (surface.name === "webgl") canvas.getContext("webgl2")?.getExtension("WEBGL_lose_context")?.loseContext();
+				canvas.remove();
+				if (host && hostPosition !== null) host.style.position = hostPosition;
+			}
+		}
+	};
+}
+/** Stands in when none of the style's renderers works here: draws nothing, and says so once. */
+function blankSurface(definition) {
+	const needs = definition.renderers.map((r) => r.name === "webgl" ? "WebGL2" : "Canvas 2D").join(" or ");
+	console.warn(`interactive-bg: style "${definition.name}" needs ${needs}, which this browser doesn't provide`);
+	return {
+		name: null,
+		update() {},
+		render: () => false,
+		clear() {},
+		destroy() {}
+	};
+}
+function resolveFade(engine) {
+	return {
+		top: Math.max(0, engine.fadeOutTop),
+		right: Math.max(0, engine.fadeOutRight),
+		bottom: Math.max(0, engine.fadeOutBottom),
+		left: Math.max(0, engine.fadeOutLeft)
+	};
+}
+function resolveColor(color) {
+	return color && color !== "transparent" ? color : null;
+}
+/** Create the background canvas inside `host`, or fixed behind the page when there is no host. */
+function mountCanvas(host) {
+	const canvas = document.createElement("canvas");
+	canvas.setAttribute("aria-hidden", "true");
+	Object.assign(canvas.style, {
+		position: host ? "absolute" : "fixed",
+		inset: "0",
+		width: "100%",
+		height: "100%",
+		display: "block",
+		pointerEvents: "none",
+		zIndex: host ? "0" : "-1"
+	});
+	if (host) {
+		if (getComputedStyle(host).position === "static") host.style.position = "relative";
+		host.prepend(canvas);
+	} else document.body.prepend(canvas);
+	return canvas;
+}
+exports.createBackground = createBackground;
+exports.engineDefaults = engineDefaults;
+
+//# sourceMappingURL=engine.cjs.map

package/dist/core/engine.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.cjs","names":["createSurface"],"sources":["../../src/core/engine.ts"],"sourcesContent":["import type { Frame, Point, RendererName, Style, StyleDefinition } from './style';\nimport { createSurface, type Fade, type Surface } from './surface';\n\n/** Options shared by every style: how and when the background is rendered. */\nexport interface EngineOptions {\n  /**\n   * Rendering backend, chosen when the background is created (changing it later has no effect).\n   * `'auto'` uses the style's renderers in their own order (WebGL2 first for the built-in styles)\n   * and falls back to the next when the browser lacks one. Naming one tries it first.\n   */\n  renderer: 'auto' | RendererName;\n  /** Fill colour painted behind the style. `null` or `'transparent'` keeps the canvas transparent. */\n  backgroundColor: string | null;\n  /**\n   * Fade the pattern out towards the top edge over this many CSS pixels: from its own opacity\n   * this far in from the edge to fully transparent at the edge. The background colour isn't\n   * faded. `0` = no fade. Fades on several sides multiply where they overlap.\n   */\n  fadeOutTop: number;\n  /** Like `fadeOutTop`, towards the right edge. */\n  fadeOutRight: number;\n  /** Like `fadeOutTop`, towards the bottom edge. */\n  fadeOutBottom: number;\n  /** Like `fadeOutTop`, towards the left edge. */\n  fadeOutLeft: number;\n  /** React to the pointer and to clicks / taps. */\n  interactive: boolean;\n  /**\n   * Upper limit for the canvas pixel density. Canvas memory grows with its square:\n   * a 1920×1080 canvas takes 8 MB at 1, 18 MB at 1.5 and 32 MB at 2.\n   */\n  maxDpr: number;\n  /** Frame-rate cap while the pointer is moving the background. `0` = uncapped. */\n  maxFps: number;\n  /** Frame-rate cap while only the style's own animation runs. Lower saves CPU and battery. `0` = same as `maxFps`. */\n  idleFps: number;\n  /** Hold the style's own animation still when the user prefers reduced motion. */\n  respectReducedMotion: boolean;\n}\n\nexport const engineDefaults: Readonly<EngineOptions> = Object.freeze({\n  renderer: 'auto',\n  backgroundColor: null,\n  fadeOutTop: 0,\n  fadeOutRight: 0,\n  fadeOutBottom: 0,\n  fadeOutLeft: 0,\n  interactive: true,\n  maxDpr: 1.5,\n  maxFps: 60,\n  idleFps: 30,\n  respectReducedMotion: true,\n});\n\nexport interface Background<O extends object> {\n  readonly canvas: HTMLCanvasElement;\n  /** Name of the style, e.g. `'topo'`. */\n  readonly style: string;\n  /**\n   * The rendering backend actually in use, or `null` when none of the style's renderers works in\n   * this browser (e.g. a WebGL-only style without WebGL2): the background then stays blank.\n   */\n  readonly renderer: RendererName | null;\n  readonly options: Readonly<O>;\n  readonly engineOptions: Readonly<EngineOptions>;\n  /** Update any of the style's options on the fly. */\n  setOptions(options: Partial<O>): void;\n  /** Update any engine options on the fly (except `renderer`). */\n  setEngineOptions(options: Partial<EngineOptions>): void;\n  pause(): void;\n  resume(): void;\n  /** Stop rendering, remove listeners and (if it was created by us) the canvas. */\n  destroy(): void;\n}\n\n/**\n * Mount an interactive background.\n *\n * - `target` `null`/omitted: a fixed, full-viewport canvas is placed behind the page.\n * - `target` is a `<canvas>`: it is drawn into directly and sized by your CSS.\n * - `target` is any other element (or a selector): a canvas is appended that\n *   fills it. The element gets `position: relative` if it was `static`.\n *\n * @example createBackground('#hero', topo({ levels: 14 }), { maxFps: 30 })\n */\nexport function createBackground<O extends object>(\n  target: HTMLElement | string | null | undefined,\n  style: Style<O>,\n  engineOptions: Partial<EngineOptions> = {},\n): Background<O> {\n  const host = typeof target === 'string' ? document.querySelector<HTMLElement>(target) : target;\n  if (typeof target === 'string' && !host) {\n    throw new Error(`interactive-bg: no element matches \"${target}\"`);\n  }\n\n  const definition = style.definition;\n  let options: O = { ...style.options };\n  let engine: EngineOptions = { ...engineDefaults, ...engineOptions };\n  let backgroundColor = resolveColor(engine.backgroundColor);\n  let fade = resolveFade(engine);\n\n  const ownsCanvas = !(host instanceof HTMLCanvasElement);\n  // We may switch the host to `position: relative`; remember what to restore on destroy().\n  const hostPosition = ownsCanvas && host ? host.style.position : null;\n  let canvas = ownsCanvas ? mountCanvas(host ?? null) : (host as HTMLCanvasElement);\n  const surface =\n    createSurface(\n      () => canvas,\n      definition.renderers,\n      options,\n      engine.renderer,\n      () => {\n        needsDraw = true;\n        wake();\n      },\n      // A renderer that failed may have claimed the canvas's context; the next one needs a fresh canvas.\n      ownsCanvas\n        ? () => {\n            const fresh = mountCanvas(host ?? null);\n            canvas.remove();\n            canvas = fresh;\n          }\n        : undefined,\n    ) ?? blankSurface(definition);\n\n  // Canvas size in CSS pixels, and the pixel density it is rendered at.\n  let width = 0;\n  let height = 0;\n  let dpr = 1;\n\n  // Pointer state: `target*` is where the pointer is, the rest eases toward it.\n  let pointerX = 0;\n  let pointerY = 0;\n  let targetX = 0;\n  let targetY = 0;\n  let influence = 0;\n  let targetInfluence = 0;\n  /** Clicks since the last rendered frame, and the array handed to the style for the current one (swapped each frame). */\n  let clicks: Point[] = [];\n  let frameClicks: Point[] = [];\n  // Reused for every frame: styles only read them during render().\n  const pointer = { x: 0, y: 0, influence: 0 };\n  const frameState: Frame = { width: 0, height: 0, dpr: 1, dt: 0, reducedMotion: false, pointer, clicks: frameClicks };\n  /** The style reported a short-lived effect still playing in its last frame. */\n  let styleBusy = false;\n\n  let lastFrame = 0;\n  let rafId = 0;\n  let timerId = 0;\n  let paused = false;\n  let visible = true;\n  let intersecting = true;\n  let destroyed = false;\n  let needsDraw = true;\n\n  const reducedMotionQuery = window.matchMedia?.('(prefers-reduced-motion: reduce)');\n  let reducedMotion = reducedMotionQuery?.matches ?? false;\n\n  function holdStill(): boolean {\n    return engine.respectReducedMotion && reducedMotion;\n  }\n\n  /** Is the style's own ambient animation running (as opposed to only reacting to the pointer)? */\n  function animating(): boolean {\n    return surface.name !== null && definition.animates(options) && !holdStill();\n  }\n\n  /** Does something need the full frame rate: the pointer's effect easing, or a style effect playing? */\n  function busy(): boolean {\n    return styleBusy || clicks.length > 0 || pointerEasing();\n  }\n\n  /** Frame rate for the ambient animation; `0` means uncapped for the engine options. */\n  function effectiveIdleFps(): number {\n    const configured =\n      engine.maxFps <= 0\n        ? engine.idleFps\n        : engine.idleFps <= 0\n          ? engine.maxFps\n          : Math.min(engine.maxFps, engine.idleFps);\n    const needed = definition.idleFps?.(options) ?? 0;\n    if (needed <= 0) return configured;\n    return configured <= 0 ? needed : Math.min(configured, needed);\n  }\n\n  function frameInterval(fps: number): number {\n    return fps > 0 ? 1000 / fps : 0;\n  }\n\n  function canRun(): boolean {\n    return !destroyed && !paused && visible;\n  }\n\n  /** Is the pointer's effect still catching up with the pointer? */\n  function pointerEasing(): boolean {\n    if (influence !== targetInfluence) return true;\n    return influence > 0 && (Math.abs(targetX - pointerX) > 0.5 || Math.abs(targetY - pointerY) > 0.5);\n  }\n\n  function resize(): void {\n    const rect = canvas.getBoundingClientRect();\n    const nextWidth = Math.max(1, Math.round(rect.width));\n    const nextHeight = Math.max(1, Math.round(rect.height));\n    const nextDpr = Math.min(window.devicePixelRatio || 1, Math.max(0.5, engine.maxDpr));\n    if (nextWidth === width && nextHeight === height && nextDpr === dpr) return;\n    width = nextWidth;\n    height = nextHeight;\n    dpr = nextDpr;\n    canvas.width = Math.round(width * dpr);\n    canvas.height = Math.round(height * dpr);\n    needsDraw = true;\n  }\n\n  function frame(now: number): void {\n    rafId = 0;\n    if (!canRun()) return;\n\n    // Full frame rate only while reacting to the pointer or playing an effect.\n    const minInterval = frameInterval(busy() ? engine.maxFps : effectiveIdleFps());\n    // 15% tolerance so a 60 fps cap doesn't drop frames on 60 Hz displays.\n    if (lastFrame && now - lastFrame < minInterval * 0.85) {\n      schedule(minInterval - (now - lastFrame));\n      return;\n    }\n    const dt = lastFrame ? Math.min((now - lastFrame) / 1000, 0.1) : 0;\n    lastFrame = now;\n\n    const wasBusy = busy();\n    // Frame-rate independent easing.\n    const ease = 1 - Math.exp(-dt * 8);\n    pointerX += (targetX - pointerX) * ease;\n    pointerY += (targetY - pointerY) * ease;\n    influence += (targetInfluence - influence) * ease;\n    if (Math.abs(targetInfluence - influence) < 0.001) influence = targetInfluence;\n\n    const moving = animating();\n    if (moving || wasBusy || needsDraw) {\n      needsDraw = false;\n      [frameClicks, clicks] = [clicks, frameClicks];\n      clicks.length = 0;\n      pointer.x = pointerX;\n      pointer.y = pointerY;\n      pointer.influence = influence;\n      frameState.width = width;\n      frameState.height = height;\n      frameState.dpr = dpr;\n      frameState.dt = dt;\n      frameState.reducedMotion = holdStill();\n      frameState.clicks = frameClicks;\n      styleBusy = surface.render(frameState, backgroundColor, fade);\n    }\n\n    // Nothing left to animate: stop until a pointer move, click, resize or option change wakes us.\n    if (busy()) schedule();\n    else if (moving) schedule(frameInterval(effectiveIdleFps()));\n    else lastFrame = 0;\n  }\n\n  /** Request a frame `delay` ms from now. */\n  function schedule(delay = 0): void {\n    if (rafId || timerId || !canRun()) return;\n    // requestAnimationFrame alone wakes up on every display refresh (up to 120–165 Hz),\n    // so sleep through longer gaps with a timer and only then wait for the next frame.\n    // The timer wakes slightly early so the next frame lands within frame()'s tolerance.\n    if (delay > 8) {\n      timerId = window.setTimeout(onTimer, delay * 0.8);\n    } else {\n      rafId = requestAnimationFrame(frame);\n    }\n  }\n\n  function onTimer(): void {\n    timerId = 0;\n    schedule();\n  }\n\n  /** Render as soon as possible, cutting short any idle sleep. */\n  function wake(): void {\n    if (timerId) clearTimeout(timerId);\n    timerId = 0;\n    schedule();\n  }\n\n  function cancel(): void {\n    if (rafId) cancelAnimationFrame(rafId);\n    if (timerId) clearTimeout(timerId);\n    rafId = timerId = 0;\n  }\n\n  function onPointerMove(event: PointerEvent): void {\n    if (!engine.interactive || !canRun()) return;\n    const rect = canvas.getBoundingClientRect();\n    const x = event.clientX - rect.left;\n    const y = event.clientY - rect.top;\n    const inside = x >= 0 && y >= 0 && x <= rect.width && y <= rect.height;\n    if (inside && targetInfluence === 0) {\n      // Entering: start where the pointer is instead of sliding in.\n      pointerX = x;\n      pointerY = y;\n    }\n    targetX = x;\n    targetY = y;\n    targetInfluence = inside ? 1 : 0;\n    if (inside || influence > 0) wake();\n  }\n\n  function onPointerDown(event: PointerEvent): void {\n    if (!engine.interactive || !canRun()) return;\n    const rect = canvas.getBoundingClientRect();\n    const x = event.clientX - rect.left;\n    const y = event.clientY - rect.top;\n    if (x < 0 || y < 0 || x > rect.width || y > rect.height) return;\n    clicks.push({ x, y });\n    wake();\n  }\n\n  function onPointerLeave(): void {\n    targetInfluence = 0;\n    wake();\n  }\n\n  function onVisibilityChange(): void {\n    visible = document.visibilityState === 'visible' && intersecting;\n    lastFrame = 0;\n    if (visible) wake();\n    else cancel();\n  }\n\n  function onReducedMotionChange(event: MediaQueryListEvent): void {\n    reducedMotion = event.matches;\n    needsDraw = true;\n    wake();\n  }\n\n  // ResizeObserver doesn't fire when only the pixel density changes (e.g. the window moves to\n  // another screen), so watch the current density with a media query, re-armed after each change.\n  let dprQuery: MediaQueryList | null = null;\n  function watchDpr(): void {\n    dprQuery?.removeEventListener?.('change', onDprChange);\n    dprQuery = window.matchMedia?.(`(resolution: ${window.devicePixelRatio || 1}dppx)`) ?? null;\n    dprQuery?.addEventListener?.('change', onDprChange);\n  }\n  function onDprChange(): void {\n    resize();\n    wake();\n    watchDpr();\n  }\n  watchDpr();\n\n  const resizeObserver = new ResizeObserver(() => {\n    resize();\n    wake();\n  });\n  resizeObserver.observe(canvas);\n\n  const intersectionObserver =\n    typeof IntersectionObserver === 'function'\n      ? new IntersectionObserver((entries) => {\n          intersecting = entries[entries.length - 1].isIntersecting;\n          onVisibilityChange();\n        })\n      : null;\n  intersectionObserver?.observe(canvas);\n\n  window.addEventListener('pointermove', onPointerMove, { passive: true });\n  window.addEventListener('pointerdown', onPointerDown, { passive: true });\n  document.documentElement.addEventListener('pointerleave', onPointerLeave);\n  document.addEventListener('visibilitychange', onVisibilityChange);\n  reducedMotionQuery?.addEventListener?.('change', onReducedMotionChange);\n\n  resize();\n  schedule();\n\n  return {\n    canvas,\n    style: definition.name,\n    renderer: surface.name,\n    get options() {\n      return options;\n    },\n    get engineOptions() {\n      return engine;\n    },\n    setOptions(next) {\n      options = { ...options, ...next };\n      surface.update(options);\n      needsDraw = true;\n      wake();\n    },\n    setEngineOptions(next) {\n      const previous = engine;\n      engine = { ...engine, ...next };\n      backgroundColor = resolveColor(engine.backgroundColor);\n      fade = resolveFade(engine);\n      if (engine.maxDpr !== previous.maxDpr) resize();\n      if (!engine.interactive) {\n        influence = targetInfluence = 0;\n        clicks.length = 0;\n      }\n      needsDraw = true;\n      wake();\n    },\n    pause() {\n      paused = true;\n      cancel();\n    },\n    resume() {\n      paused = false;\n      lastFrame = 0;\n      wake();\n    },\n    destroy() {\n      if (destroyed) return;\n      destroyed = true;\n      cancel();\n      resizeObserver.disconnect();\n      intersectionObserver?.disconnect();\n      window.removeEventListener('pointermove', onPointerMove);\n      window.removeEventListener('pointerdown', onPointerDown);\n      document.documentElement.removeEventListener('pointerleave', onPointerLeave);\n      document.removeEventListener('visibilitychange', onVisibilityChange);\n      reducedMotionQuery?.removeEventListener?.('change', onReducedMotionChange);\n      dprQuery?.removeEventListener?.('change', onDprChange);\n      if (!ownsCanvas) surface.clear();\n      surface.destroy();\n      if (ownsCanvas) {\n        // Free the GPU context now rather than at garbage collection: browsers cap live WebGL contexts.\n        if (surface.name === 'webgl') canvas.getContext('webgl2')?.getExtension('WEBGL_lose_context')?.loseContext();\n        canvas.remove();\n        if (host && hostPosition !== null) host.style.position = hostPosition;\n      }\n    },\n  };\n}\n\n/** Stands in when none of the style's renderers works here: draws nothing, and says so once. */\nfunction blankSurface<O extends object>(definition: StyleDefinition<O>): Omit<Surface<O>, 'name'> & { name: null } {\n  const needs = definition.renderers.map((r) => (r.name === 'webgl' ? 'WebGL2' : 'Canvas 2D')).join(' or ');\n  console.warn(`interactive-bg: style \"${definition.name}\" needs ${needs}, which this browser doesn't provide`);\n  return { name: null, update() {}, render: () => false, clear() {}, destroy() {} };\n}\n\nfunction resolveFade(engine: EngineOptions): Fade {\n  return {\n    top: Math.max(0, engine.fadeOutTop),\n    right: Math.max(0, engine.fadeOutRight),\n    bottom: Math.max(0, engine.fadeOutBottom),\n    left: Math.max(0, engine.fadeOutLeft),\n  };\n}\n\nfunction resolveColor(color: string | null): string | null {\n  return color && color !== 'transparent' ? color : null;\n}\n\n/** Create the background canvas inside `host`, or fixed behind the page when there is no host. */\nfunction mountCanvas(host: HTMLElement | null): HTMLCanvasElement {\n  const canvas = document.createElement('canvas');\n  canvas.setAttribute('aria-hidden', 'true');\n  Object.assign(canvas.style, {\n    position: host ? 'absolute' : 'fixed',\n    inset: '0',\n    width: '100%',\n    height: '100%',\n    display: 'block',\n    pointerEvents: 'none',\n    zIndex: host ? '0' : '-1',\n  });\n  if (host) {\n    if (getComputedStyle(host).position === 'static') host.style.position = 'relative';\n    host.prepend(canvas);\n  } else {\n    document.body.prepend(canvas);\n  }\n  return canvas;\n}\n"],"mappings":"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"}

package/dist/core/engine.d.cts

@@ -0,0 +1,69 @@
+import type { RendererName, Style } from './style.cjs';
+/** Options shared by every style: how and when the background is rendered. */
+export interface EngineOptions {
+    /**
+     * Rendering backend, chosen when the background is created (changing it later has no effect).
+     * `'auto'` uses the style's renderers in their own order (WebGL2 first for the built-in styles)
+     * and falls back to the next when the browser lacks one. Naming one tries it first.
+     */
+    renderer: 'auto' | RendererName;
+    /** Fill colour painted behind the style. `null` or `'transparent'` keeps the canvas transparent. */
+    backgroundColor: string | null;
+    /**
+     * Fade the pattern out towards the top edge over this many CSS pixels: from its own opacity
+     * this far in from the edge to fully transparent at the edge. The background colour isn't
+     * faded. `0` = no fade. Fades on several sides multiply where they overlap.
+     */
+    fadeOutTop: number;
+    /** Like `fadeOutTop`, towards the right edge. */
+    fadeOutRight: number;
+    /** Like `fadeOutTop`, towards the bottom edge. */
+    fadeOutBottom: number;
+    /** Like `fadeOutTop`, towards the left edge. */
+    fadeOutLeft: number;
+    /** React to the pointer and to clicks / taps. */
+    interactive: boolean;
+    /**
+     * Upper limit for the canvas pixel density. Canvas memory grows with its square:
+     * a 1920×1080 canvas takes 8 MB at 1, 18 MB at 1.5 and 32 MB at 2.
+     */
+    maxDpr: number;
+    /** Frame-rate cap while the pointer is moving the background. `0` = uncapped. */
+    maxFps: number;
+    /** Frame-rate cap while only the style's own animation runs. Lower saves CPU and battery. `0` = same as `maxFps`. */
+    idleFps: number;
+    /** Hold the style's own animation still when the user prefers reduced motion. */
+    respectReducedMotion: boolean;
+}
+export declare const engineDefaults: Readonly<EngineOptions>;
+export interface Background<O extends object> {
+    readonly canvas: HTMLCanvasElement;
+    /** Name of the style, e.g. `'topo'`. */
+    readonly style: string;
+    /**
+     * The rendering backend actually in use, or `null` when none of the style's renderers works in
+     * this browser (e.g. a WebGL-only style without WebGL2): the background then stays blank.
+     */
+    readonly renderer: RendererName | null;
+    readonly options: Readonly<O>;
+    readonly engineOptions: Readonly<EngineOptions>;
+    /** Update any of the style's options on the fly. */
+    setOptions(options: Partial<O>): void;
+    /** Update any engine options on the fly (except `renderer`). */
+    setEngineOptions(options: Partial<EngineOptions>): void;
+    pause(): void;
+    resume(): void;
+    /** Stop rendering, remove listeners and (if it was created by us) the canvas. */
+    destroy(): void;
+}
+/**
+ * Mount an interactive background.
+ *
+ * - `target` `null`/omitted: a fixed, full-viewport canvas is placed behind the page.
+ * - `target` is a `<canvas>`: it is drawn into directly and sized by your CSS.
+ * - `target` is any other element (or a selector): a canvas is appended that
+ *   fills it. The element gets `position: relative` if it was `static`.
+ *
+ * @example createBackground('#hero', topo({ levels: 14 }), { maxFps: 30 })
+ */
+export declare function createBackground<O extends object>(target: HTMLElement | string | null | undefined, style: Style<O>, engineOptions?: Partial<EngineOptions>): Background<O>;

package/dist/core/engine.d.ts

@@ -0,0 +1,69 @@
+import type { RendererName, Style } from './style.js';
+/** Options shared by every style: how and when the background is rendered. */
+export interface EngineOptions {
+    /**
+     * Rendering backend, chosen when the background is created (changing it later has no effect).
+     * `'auto'` uses the style's renderers in their own order (WebGL2 first for the built-in styles)
+     * and falls back to the next when the browser lacks one. Naming one tries it first.
+     */
+    renderer: 'auto' | RendererName;
+    /** Fill colour painted behind the style. `null` or `'transparent'` keeps the canvas transparent. */
+    backgroundColor: string | null;
+    /**
+     * Fade the pattern out towards the top edge over this many CSS pixels: from its own opacity
+     * this far in from the edge to fully transparent at the edge. The background colour isn't
+     * faded. `0` = no fade. Fades on several sides multiply where they overlap.
+     */
+    fadeOutTop: number;
+    /** Like `fadeOutTop`, towards the right edge. */
+    fadeOutRight: number;
+    /** Like `fadeOutTop`, towards the bottom edge. */
+    fadeOutBottom: number;
+    /** Like `fadeOutTop`, towards the left edge. */
+    fadeOutLeft: number;
+    /** React to the pointer and to clicks / taps. */
+    interactive: boolean;
+    /**
+     * Upper limit for the canvas pixel density. Canvas memory grows with its square:
+     * a 1920×1080 canvas takes 8 MB at 1, 18 MB at 1.5 and 32 MB at 2.
+     */
+    maxDpr: number;
+    /** Frame-rate cap while the pointer is moving the background. `0` = uncapped. */
+    maxFps: number;
+    /** Frame-rate cap while only the style's own animation runs. Lower saves CPU and battery. `0` = same as `maxFps`. */
+    idleFps: number;
+    /** Hold the style's own animation still when the user prefers reduced motion. */
+    respectReducedMotion: boolean;
+}
+export declare const engineDefaults: Readonly<EngineOptions>;
+export interface Background<O extends object> {
+    readonly canvas: HTMLCanvasElement;
+    /** Name of the style, e.g. `'topo'`. */
+    readonly style: string;
+    /**
+     * The rendering backend actually in use, or `null` when none of the style's renderers works in
+     * this browser (e.g. a WebGL-only style without WebGL2): the background then stays blank.
+     */
+    readonly renderer: RendererName | null;
+    readonly options: Readonly<O>;
+    readonly engineOptions: Readonly<EngineOptions>;
+    /** Update any of the style's options on the fly. */
+    setOptions(options: Partial<O>): void;
+    /** Update any engine options on the fly (except `renderer`). */
+    setEngineOptions(options: Partial<EngineOptions>): void;
+    pause(): void;
+    resume(): void;
+    /** Stop rendering, remove listeners and (if it was created by us) the canvas. */
+    destroy(): void;
+}
+/**
+ * Mount an interactive background.
+ *
+ * - `target` `null`/omitted: a fixed, full-viewport canvas is placed behind the page.
+ * - `target` is a `<canvas>`: it is drawn into directly and sized by your CSS.
+ * - `target` is any other element (or a selector): a canvas is appended that
+ *   fills it. The element gets `position: relative` if it was `static`.
+ *
+ * @example createBackground('#hero', topo({ levels: 14 }), { maxFps: 30 })
+ */
+export declare function createBackground<O extends object>(target: HTMLElement | string | null | undefined, style: Style<O>, engineOptions?: Partial<EngineOptions>): Background<O>;