noisefloor 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 digitalemagine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,365 @@
-# Temporary Holding Version
+# noisefloor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Analog-signal interference for UI: labels and images that break up like a weak signal, then recover. Layout never moves, screen readers and reduced-motion users are unaffected, and cross-origin images work without CORS. MIT, zero runtime dependencies, about 7.5 KB gzipped (4.5 KB for Scramble alone).
+
+**[Live demo, docs and playground](https://digitalemagine.github.io/noisefloor/)**
+
+![noisefloor demo: ambient micro-glitches, the menu and headline scrambling on hover, both images glitching](https://digitalemagine.github.io/noisefloor/media/demo.gif)
+
+- **Ambient**: Poisson-timed micro-glitches across any mix of text and image instances: a page that sometimes loses signal, without anyone touching it.
+- **Scramble**: per-character text scramble with palette colours, vertical jitter, skew, RGB split, glow, flicker, glitch lines and scanlines. Typing mode (`reveal: 'type'`) types the label character by character, each scrambling briefly before it locks, at a fitted `duration` or a fixed `speed`, with an optional block caret. Layout never moves. Works on plain text: child elements inside the target are replaced by its text. Made for labels and headings, not paragraphs: every character is its own element, restyled on each frame.
+- **Glitch**: canvas image glitch over an existing `<img>`: channel split, slice tears, block moves, colour lines, frame shake. No pixel reads, so cross-origin images work without CORS.
+
+## Install
+
+```sh
+npm i noisefloor
+```
+
+```js
+import { Scramble, Glitch, Ambient } from 'noisefloor';
+```
+
+Without a bundler, one script tag exposes the `Noisefloor` global:
+
+```html
+<script src="https://unpkg.com/noisefloor"></script>
+```
+
+## Quick start
+
+```html
+<nav>
+  <a href="#docs"><span class="label">Docs</span></a>
+  <a href="#about"><span class="label">About</span></a>
+</nav>
+<img class="glitch" src="feed.jpg" alt="Camera feed">
+
+<script type="module">
+  import { Scramble, Glitch, Ambient } from 'noisefloor';
+
+  const labels = Scramble.bind('nav a .label');
+  const images = Glitch.bind('img.glitch');
+  new Ambient([...labels, ...images], { rate: 30, amount: 0.25 });
+</script>
+```
+
+With the script tag, use `Noisefloor.Scramble`, `Noisefloor.Glitch` and `Noisefloor.Ambient`.
+
+## API
+
+Every effect is a class: `new Scramble(el, options)`, `new Glitch(img, options)`, `new Ambient(targets, options)`. `Scramble.bind()` and `Glitch.bind()` take a selector, element or list, and return the instances.
+
+- `play()`: a full scramble (characters lock in order) or a full image glitch. `play({ text })` scrambles a label to new text.
+- `burst({ amount, count, duration, intensity })`: a micro-glitch on part of the target (`count`: Scramble only); this is what `Ambient` calls. Ignored while playing.
+- `set(options)`: change options, safe while playing. `options` returns the current, validated values.
+- `finished`: a promise resolved when the current animation ends: `await label.play().finished`.
+- `finish()` jumps to rest; `destroy()` removes the effect (Scramble leaves the label as plain text); `running`, `destroyed`, and for Glitch `ready` (image loaded and measured).
+- `bind(targets, options, { trigger, host, once })`: `trigger` is an event name (default `mouseenter`, which also plays on focus) or `'visible'` (when the element scrolls into view); `once: true` plays on the first trigger only; `host: (el) => element` picks the element that listens (by default the closest link or button; otherwise the label itself for Scramble, the image wrapper for Glitch).
+- `Ambient`: `fire()`, `setTargets()`, `start()`, `stop()`, `destroy()` (targets are not destroyed). It picks an idle target each time and pauses while the tab is hidden.
+
+Typing instead of scrambling, on scroll:
+
+```js
+Scramble.bind('h2', { reveal: 'type', cursor: true }, { trigger: 'visible', once: true });
+```
+
+Cycling words: `play({ text })` changes the width once, when it starts. To keep even that from moving the layout, reserve the widest word with `min-width`:
+
+```html
+<span id="status" style="min-width: 11ch">Idle</span>
+<script type="module">
+  import { Scramble } from 'noisefloor';
+
+  const status = new Scramble(document.getElementById('status'));
+  const words = ['Idle', 'Scanning', 'Reacquiring', 'Locked'];
+  let i = 0;
+  setInterval(() => status.play({ text: words[++i % words.length] }), 2000);
+</script>
+```
+
+`ch` matches the widest word exactly only in a monospace font; with a proportional font, measure the widest word once, or round up.
+
+Options are validated: numbers out of range are clamped, invalid values fall back to the default, and development builds warn once per option.
+
+<details>
+<summary>Scramble options</summary>
+
+| Option | Default | Meaning |
+|---|---|---|
+| `duration` | `0.7` | Seconds until the last character locks. |
+| `fps` | `24` | Glyph and jitter refresh rate. Lower reads more analog. |
+| `settle` | `0.35` | Seconds for colour and position to decay after a character locks. |
+| `order` | `"ltr"` | Lock order: ltr, rtl, center or random. With typing, also the order characters appear in. |
+| `reveal` | `"all"` | 'all': every character scrambles at once. 'type': characters appear one by one in order, the width reserved from the start. |
+| `trail` | `0.15` | Typing: seconds a character scrambles between appearing and locking. |
+| `speed` | `0` | Typing: characters per second; when above 0 the run length follows the text and duration is ignored. |
+| `cursor` | `false` | Typing: block caret at the typing head. Colour: --nf-cursor. |
+| `chars` | `"01#%=$>≤<"` | Glyphs used while scrambling. |
+| `palette` | `["#ff2bd6","#00f0ff","#f5ff3b"]` | Colours for scrambling glyphs and lines; [0] and [1] drive the RGB split. |
+| `jitter` | `1.5` | Max vertical offset of a scrambling character, px. |
+| `skew` | `8` | Max skew of a scrambling character, degrees. |
+| `rgbSplit` | `1.5` | Chromatic aberration, px. |
+| `glow` | `6` | Bloom on scrambling characters, px. |
+| `flicker` | `0.12` | Chance (0-1) a scrambling character dims on a frame. |
+| `lines` | `3` | Glitch lines drawn over the label (0-8). |
+| `tear` | `2` | Horizontal sync slip of the whole label, px. |
+| `scanlines` | `true` | Rolling scanline overlay while live. |
+
+</details>
+
+<details>
+<summary>Glitch options</summary>
+
+| Option | Default | Meaning |
+|---|---|---|
+| `duration` | `0.6` | Seconds per full glitch. |
+| `fps` | `20` | Frame refresh rate. |
+| `palette` | `["#ff2bd6","#00f0ff","#f5ff3b"]` | Colours for lines and tinted bands. |
+| `rgbSplit` | `6` | Max R/B channel offset, px. |
+| `slices` | `10` | Horizontal bands displaced per frame at full amount. |
+| `tear` | `24` | Max sideways displacement of a band, px. |
+| `blocks` | `6` | Rectangles copied out of place per frame. |
+| `lines` | `4` | Palette-coloured scan lines per frame. |
+| `jitter` | `2` | Vertical shake of the whole frame, px. |
+| `flicker` | `0.1` | Chance (0-1) a frame dims. |
+| `scanlines` | `true` | Rolling scanline overlay while live. |
+
+</details>
+
+<details>
+<summary>Ambient options</summary>
+
+| Option | Default | Meaning |
+|---|---|---|
+| `rate` | `30` | Micro-glitches per minute, across all targets. |
+| `amount` | `0.2` | Share (0-1) of each target disturbed. |
+| `duration` | `0.18` | Seconds per micro-glitch. |
+| `intensity` | `0.5` | Artefact strength (0-1). |
+| `enabled` | `true` | Start scheduling immediately. |
+
+</details>
+
+Live demo, full reference and a playground that writes the configuration for you: [the project site](https://digitalemagine.github.io/noisefloor/), also built locally by `npm run build:site`.
+
+## HTML attributes
+
+For static pages and CMS content, the same effects can be declared in markup. Import `noisefloor/auto` once, or load `noisefloor.auto.iife.js` (the full library plus auto-init) instead of the plain script tag:
+
+```html
+<script src="https://unpkg.com/noisefloor/dist/noisefloor.auto.iife.js"></script>
+
+<a href="#docs"><span data-nf="scramble" data-nf-order="center">Docs</span></a>
+<span data-nf="scramble" data-nf-reveal="type" data-nf-trigger="visible" data-nf-once>Reacquiring signal</span>
+<img data-nf="glitch" data-nf-rgb-split="6" data-nf-ambient src="feed.jpg" alt="Camera feed">
+```
+
+```js
+import 'noisefloor/auto';
+```
+
+- `data-nf`: `scramble` or `glitch` (an `<img>` only).
+- `data-nf-<option>`: any effect option, in kebab case (`data-nf-rgb-split`) or as one word (`data-nf-rgbsplit`). Numbers and strings as written; booleans are true when present and false with `"false"`; `data-nf-palette` is a comma-separated list.
+- `data-nf-trigger`: as `bind()`'s `trigger` (default hover/focus of the closest link or button; `visible`; any event name), or `none` for no trigger. `data-nf-once`: unbind after the first play.
+- `data-nf-ambient`: add the element to one shared Ambient; `ambient().set({ rate: 12 })` changes its options.
+
+It scans the document when it is ready and watches it: elements added later are set up, removed ones are destroyed, and changing `data-nf` rebuilds the effect. Other attributes are read once. Elements that already have an instance are skipped. The module exports `scan(root)` (for shadow roots, which the observer does not see), `start()`, `stop()` and `ambient()`; the script-tag bundle exposes them as `Noisefloor.auto`.
+
+Not for markup a framework renders: use the recipes below, which control when instances are created and destroyed.
+
+## Frameworks
+
+React, Vue and Svelte own the nodes they render, while Scramble replaces an element's children and Glitch moves the img into a wrapper. Without care, the next render corrupts the label or throws (React: `insertBefore ... is not a child of this node`). Three rules keep them apart:
+
+- **Render the label once**, then change it with `play({ text })`: the framework never patches the text node Scramble replaced. React: the first value from `useState`; Vue: `v-once`; Svelte: `untrack`.
+- **Wrap the img in an element marked `data-nf-wrap`.** Glitch uses it instead of inserting its own wrapper, so the img stays where the framework put it.
+- **Create instances after mount and `destroy()` them on unmount.** Options are read at mount; change them later with `set()`.
+
+Checked with React 19 (StrictMode), Vue 3.5 and Svelte 5.
+
+<details>
+<summary>React</summary>
+
+```jsx
+// ScrambleText.jsx
+import { useEffect, useRef, useState } from 'react';
+import { Scramble } from 'noisefloor';
+
+export function ScrambleText({ text, options, bindOptions }) {
+  const ref = useRef(null);
+  const inst = useRef(null);
+  // Rendered once: Scramble owns the children from then on; later text goes through play().
+  const [initial] = useState(text);
+
+  useEffect(() => {
+    const [s] = Scramble.bind(ref.current, options, bindOptions);
+    inst.current = s;
+    return () => s.destroy();
+  }, []);
+
+  useEffect(() => {
+    const s = inst.current;
+    if (s && s.text !== text) s.play({ text });
+  }, [text]);
+
+  return <span ref={ref}>{initial}</span>;
+}
+```
+
+```jsx
+// GlitchImage.jsx
+import { useEffect, useRef } from 'react';
+import { Glitch } from 'noisefloor';
+
+export function GlitchImage({ options, bindOptions, ...img }) {
+  const ref = useRef(null);
+
+  useEffect(() => {
+    const [g] = Glitch.bind(ref.current, options, bindOptions);
+    return () => g.destroy();
+  }, []);
+
+  // data-nf-wrap: Glitch uses this span instead of moving the img into its own wrapper.
+  return (
+    <span data-nf-wrap="" style={{ display: 'inline-block' }}>
+      <img ref={ref} {...img} />
+    </span>
+  );
+}
+```
+
+</details>
+
+<details>
+<summary>Vue</summary>
+
+`ScrambleText.vue`:
+
+```vue
+<script setup>
+import { onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import { Scramble } from 'noisefloor';
+
+const props = defineProps({ text: { type: String, required: true }, options: Object, bindOptions: Object });
+const el = ref(null);
+let s = null;
+
+onMounted(() => { [s] = Scramble.bind(el.value, props.options, props.bindOptions); });
+watch(() => props.text, (text) => { if (s) s.play({ text }); });
+onBeforeUnmount(() => { if (s) s.destroy(); });
+</script>
+
+<template>
+  <!-- v-once: Vue renders the first text and never patches it; later text goes through play() -->
+  <span ref="el" v-once>{{ text }}</span>
+</template>
+```
+
+`GlitchImage.vue`:
+
+```vue
+<script setup>
+import { onBeforeUnmount, onMounted, ref } from 'vue';
+import { Glitch } from 'noisefloor';
+
+const props = defineProps({ src: String, alt: String, options: Object, bindOptions: Object });
+const img = ref(null);
+let g = null;
+
+onMounted(() => { [g] = Glitch.bind(img.value, props.options, props.bindOptions); });
+onBeforeUnmount(() => { if (g) g.destroy(); });
+</script>
+
+<template>
+  <!-- data-nf-wrap: Glitch uses this span instead of moving the img into its own wrapper -->
+  <span data-nf-wrap style="display: inline-block"><img ref="img" :src="src" :alt="alt"></span>
+</template>
+```
+
+</details>
+
+<details>
+<summary>Svelte</summary>
+
+`ScrambleText.svelte`:
+
+```svelte
+<script>
+  import { untrack } from 'svelte';
+  import { Scramble } from 'noisefloor';
+
+  let { text, options, bindOptions } = $props();
+  // Rendered once: Scramble owns the children from then on; later text goes through play().
+  const initial = untrack(() => text);
+
+  function scramble(node, text) {
+    const [s] = Scramble.bind(node, options, bindOptions);
+    return {
+      update(next) { s.play({ text: next }); },
+      destroy() { s.destroy(); }
+    };
+  }
+</script>
+
+<span use:scramble={text}>{initial}</span>
+```
+
+`GlitchImage.svelte`:
+
+```svelte
+<script>
+  import { Glitch } from 'noisefloor';
+
+  let { options, bindOptions, ...img } = $props();
+
+  function glitch(node) {
+    const [g] = Glitch.bind(node, options, bindOptions);
+    return { destroy() { g.destroy(); } };
+  }
+</script>
+
+<!-- data-nf-wrap: Glitch uses this span instead of moving the img into its own wrapper -->
+<span data-nf-wrap style="display: inline-block"><img use:glitch {...img} /></span>
+```
+
+</details>
+
+## Content-Security-Policy
+
+The base CSS is injected as a `<style>` element, which a policy without `'unsafe-inline'` in `style-src` blocks. Load the stylesheet yourself and turn injection off before creating instances:
+
+```js
+import 'noisefloor/style.css'; // or <link rel="stylesheet" href="https://unpkg.com/noisefloor/dist/style.css">
+import { configure } from 'noisefloor';
+
+configure({ injectCSS: false });
+```
+
+Inside a shadow root, the stylesheet must be loaded in that root.
+
+## Browser support
+
+Safari 16, Chrome and Edge 107, Firefox 104 and later (the default build target of Vite, Baseline widely available). The published files use no syntax beyond what these browsers support; a bundler targeting older browsers transpiles them. With the script tag, an older browser skips the library and the labels and images show unchanged.
+
+## Development
+
+```sh
+npm i && npx playwright install chromium
+npm run typecheck    # tsc --noEmit
+npm test             # unit tests (Vitest browser mode, headless Chromium)
+npm run build        # dist/: ESM, CJS, browser global bundle, .d.ts, style.css
+npm run check:package # publint, arethetypeswrong, tree-shaking check (needs dist/)
+npm run build:site   # site/dist/index.html (demo, docs, playground)
+npm run smoke        # build, build:site, headless smoke test of the built site
+npm run fidelity     # build, build:site, image overlay vs real image comparison
+```
+
+Design notes and decisions: `docs/DESIGN.md`. Changes: `CHANGELOG.md`.
+
+## About this project
+
+Like some of my other recent projects, noisefloor is a Claude-first experiment: the code, tests, docs and site were written with an AI assistant (Claude Code). My role was to steer it: I set the direction, reviewed plans before any code, challenged answers, iterated and reviewed the changes. The site illustrations are mine. Every change runs through the checks in this repository: unit tests in headless Chromium, a smoke test of the built site and a pixel comparison of the image overlay against the real image. It surely has rough edges I haven't found yet; feedback is welcome.
+
+## Licence
+
+MIT, Copyright (c) 2026 digitalemagine.

package/dist/auto.cjs

@@ -0,0 +1,172 @@
+/*! noisefloor v0.1.0 | MIT | (c) 2026 digitalemagine */
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_ambient = require("./core.cjs");
+//#region src/auto.ts
+/**
+* noisefloor/auto: effects declared in HTML attributes.
+*
+*   <span data-nf="scramble" data-nf-order="center">Docs</span>
+*   <img data-nf="glitch" data-nf-rgb-split="6" data-nf-ambient src="feed.jpg" alt="">
+*
+* Importing this module (or loading noisefloor.auto.iife.js) scans the
+* document when it is ready and keeps watching it: elements added later are
+* set up, removed ones are destroyed. The core `noisefloor` entry has no such
+* side effect.
+*/
+/** `data-nf-*` attributes that are not effect options. */
+const RESERVED = [
+	"wrap",
+	"trigger",
+	"once",
+	"ambient"
+];
+const live = /* @__PURE__ */ new Set();
+let observer = null;
+let shared = null;
+/** start() pending on DOMContentLoaded; cleared by stop() */
+let pending = false;
+const target = (inst) => inst instanceof require_ambient.Glitch ? inst.img : inst.el;
+/**
+* Effect options from the element's `data-nf-*` attributes, typed by the
+* defaults: numbers, booleans (present means true, "false" means false),
+* `palette` as a comma-separated list, strings as given. Names are matched
+* without dashes and case, since HTML lowercases attribute names:
+* `data-nf-rgb-split` and `data-nf-rgbsplit` both set `rgbSplit`. Unknown names
+* are passed on, so the effect warns about them in development builds.
+*/
+function options(el, defaults) {
+	const o = {}, names = Object.keys(defaults), d = defaults;
+	for (const a of Array.from(el.attributes)) {
+		if (a.name.slice(0, 8) !== "data-nf-") continue;
+		const raw = a.name.slice(8);
+		if (RESERVED.indexOf(raw) >= 0) continue;
+		const flat = raw.replace(/-/g, "");
+		const k = names.filter((n) => n.toLowerCase() === flat)[0] || raw.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+		const def = d[k], v = a.value;
+		if (typeof def === "number") o[k] = v.trim() === "" ? NaN : Number(v);
+		else if (typeof def === "boolean") o[k] = v !== "false";
+		else if (Array.isArray(def)) o[k] = v.split(/,(?![^(]*\))/).map((s) => s.trim()).filter(Boolean);
+		else o[k] = v;
+	}
+	return o;
+}
+/** Set up one `[data-nf]` element. Skips elements that already have an instance or are detached. */
+function create(el) {
+	if (require_ambient.owner(el) || !el.isConnected) return null;
+	const kind = (el.getAttribute("data-nf") || "").trim().toLowerCase();
+	const trigger = el.getAttribute("data-nf-trigger") || "mouseenter";
+	const b = {
+		trigger,
+		once: el.hasAttribute("data-nf-once")
+	};
+	let inst;
+	if (kind === "scramble") {
+		const el2 = el, o = options(el, require_ambient.Scramble.defaults);
+		inst = trigger === "none" ? new require_ambient.Scramble(el2, o) : require_ambient.Scramble.bind(el2, o, b)[0];
+	} else if (kind === "glitch" && el.tagName === "IMG") {
+		const img = el, o = options(el, require_ambient.Glitch.defaults);
+		inst = trigger === "none" ? new require_ambient.Glitch(img, o) : require_ambient.Glitch.bind(img, o, b)[0];
+	} else {
+		try {
+			if (process.env.NODE_ENV !== "production") require_ambient.warn("auto.kind." + kind + el.tagName, kind === "glitch" ? `auto: data-nf="glitch" needs an <img>, got <${el.tagName.toLowerCase()}>; ignored` : `auto: data-nf must be "scramble" or "glitch", got ${JSON.stringify(kind)}; ignored`);
+		} catch {}
+		return null;
+	}
+	live.add(inst);
+	if (el.hasAttribute("data-nf-ambient")) {
+		const a = ambient();
+		a.setTargets(a.targets.concat(inst));
+	}
+	return inst;
+}
+function drop(inst) {
+	live.delete(inst);
+	inst.destroy();
+}
+function onMutations(records) {
+	let removed = false;
+	for (const r of records) {
+		if (r.type === "attributes") {
+			const el = r.target;
+			live.forEach((inst) => {
+				if (target(inst) === el) drop(inst);
+			});
+			if (el.hasAttribute("data-nf")) create(el);
+			continue;
+		}
+		for (const n of Array.from(r.removedNodes)) if (n.nodeType === 1) removed = true;
+		for (const n of Array.from(r.addedNodes)) if (n.nodeType === 1) scan(n);
+	}
+	if (removed) live.forEach((inst) => {
+		if (!target(inst).isConnected) drop(inst);
+	});
+}
+/**
+* Set up every `[data-nf]` element in `root` (and `root` itself) that has no
+* instance yet; returns the new instances. start() does this for the
+* document; call it for content the observer does not see, such as a shadow
+* root. Instances made here are not destroyed automatically when removed.
+*/
+function scan(root = document) {
+	const els = Array.prototype.slice.call(root.querySelectorAll("[data-nf]"));
+	if (root.nodeType === 1 && root.hasAttribute("data-nf")) els.unshift(root);
+	const out = [];
+	for (const el of els) {
+		const inst = create(el);
+		if (inst) out.push(inst);
+	}
+	return out;
+}
+/**
+* Scan the document and watch it for added or removed elements and changes of
+* the `data-nf` attribute. Called on import; idempotent.
+*/
+function start() {
+	pending = false;
+	if (observer || typeof document === "undefined") return;
+	scan(document);
+	if (typeof MutationObserver !== "function") return;
+	observer = new MutationObserver(onMutations);
+	observer.observe(document.documentElement, {
+		childList: true,
+		subtree: true,
+		attributes: true,
+		attributeFilter: ["data-nf"]
+	});
+}
+/** Stop watching and destroy every instance created from attributes, and the shared Ambient. */
+function stop() {
+	pending = false;
+	if (observer) {
+		observer.disconnect();
+		observer = null;
+	}
+	live.forEach(drop);
+	if (shared) {
+		shared.destroy();
+		shared = null;
+	}
+}
+/**
+* The Ambient that drives elements marked `data-nf-ambient`, created on first
+* use with the default options; change them with `ambient().set({ rate: 12 })`.
+*/
+function ambient() {
+	if (!shared) shared = new require_ambient.Ambient([]);
+	return shared;
+}
+if (typeof document !== "undefined") {
+	if (document.readyState === "loading") {
+		pending = true;
+		document.addEventListener("DOMContentLoaded", () => {
+			if (pending) start();
+		}, { once: true });
+	} else start();
+}
+//#endregion
+exports.ambient = ambient;
+exports.scan = scan;
+exports.start = start;
+exports.stop = stop;
+
+//# sourceMappingURL=auto.cjs.map

package/dist/auto.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto.cjs","names":["Glitch","owner","Scramble","Ambient"],"sources":["../src/auto.ts"],"sourcesContent":["/**\n * noisefloor/auto: effects declared in HTML attributes.\n *\n *   <span data-nf=\"scramble\" data-nf-order=\"center\">Docs</span>\n *   <img data-nf=\"glitch\" data-nf-rgb-split=\"6\" data-nf-ambient src=\"feed.jpg\" alt=\"\">\n *\n * Importing this module (or loading noisefloor.auto.iife.js) scans the\n * document when it is ready and keeps watching it: elements added later are\n * set up, removed ones are destroyed. The core `noisefloor` entry has no such\n * side effect.\n */\nimport { Ambient } from './ambient';\nimport { Glitch } from './glitch';\nimport { Scramble } from './scramble';\nimport { owner, warn } from './shared';\nimport type { BindOptions } from './types';\n\ntype Effect = Scramble | Glitch;\n\n/** `data-nf-*` attributes that are not effect options. */\nconst RESERVED = ['wrap', 'trigger', 'once', 'ambient'];\n\nconst live = new Set<Effect>();\nlet observer: MutationObserver | null = null;\nlet shared: Ambient | null = null;\n/** start() pending on DOMContentLoaded; cleared by stop() */\nlet pending = false;\n\nconst target = (inst: Effect): Element => (inst instanceof Glitch ? inst.img : inst.el);\n\n/**\n * Effect options from the element's `data-nf-*` attributes, typed by the\n * defaults: numbers, booleans (present means true, \"false\" means false),\n * `palette` as a comma-separated list, strings as given. Names are matched\n * without dashes and case, since HTML lowercases attribute names:\n * `data-nf-rgb-split` and `data-nf-rgbsplit` both set `rgbSplit`. Unknown names\n * are passed on, so the effect warns about them in development builds.\n */\nfunction options(el: Element, defaults: object): Record<string, unknown> {\n  const o: Record<string, unknown> = {}, names = Object.keys(defaults), d = defaults as Record<string, unknown>;\n  for (const a of Array.from(el.attributes)) {\n    if (a.name.slice(0, 8) !== 'data-nf-') continue;\n    const raw = a.name.slice(8);\n    if (RESERVED.indexOf(raw) >= 0) continue;\n    const flat = raw.replace(/-/g, '');\n    const k = names.filter((n) => n.toLowerCase() === flat)[0] || raw.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());\n    const def = d[k], v = a.value;\n    if (typeof def === 'number') o[k] = v.trim() === '' ? NaN : Number(v);\n    else if (typeof def === 'boolean') o[k] = v !== 'false';\n    else if (Array.isArray(def)) o[k] = v.split(/,(?![^(]*\\))/).map((s) => s.trim()).filter(Boolean); // commas inside rgb(...) stay\n    else o[k] = v;\n  }\n  return o;\n}\n\n/** Set up one `[data-nf]` element. Skips elements that already have an instance or are detached. */\nfunction create(el: Element): Effect | null {\n  if (owner(el) || !el.isConnected) return null;\n  const kind = (el.getAttribute('data-nf') || '').trim().toLowerCase();\n  const trigger = el.getAttribute('data-nf-trigger') || 'mouseenter';\n  const b = { trigger, once: el.hasAttribute('data-nf-once') } as BindOptions<Element>;\n  let inst: Effect;\n  if (kind === 'scramble') {\n    const el2 = el as HTMLElement, o = options(el, Scramble.defaults);\n    inst = trigger === 'none' ? new Scramble(el2, o) : Scramble.bind(el2, o, b)[0] as Scramble;\n  } else if (kind === 'glitch' && el.tagName === 'IMG') {\n    const img = el as HTMLImageElement, o = options(el, Glitch.defaults);\n    inst = trigger === 'none' ? new Glitch(img, o) : Glitch.bind(img, o, b)[0] as Glitch;\n  } else {\n    if (!__NF_IIFE__) {\n      try {\n        if (process.env.NODE_ENV !== 'production') {\n          warn('auto.kind.' + kind + el.tagName, kind === 'glitch'\n            ? `auto: data-nf=\"glitch\" needs an <img>, got <${el.tagName.toLowerCase()}>; ignored`\n            : `auto: data-nf must be \"scramble\" or \"glitch\", got ${JSON.stringify(kind)}; ignored`);\n        }\n      } catch { /* no process global */ }\n    }\n    return null;\n  }\n  live.add(inst);\n  if (el.hasAttribute('data-nf-ambient')) { const a = ambient(); a.setTargets(a.targets.concat(inst)); }\n  return inst;\n}\n\nfunction drop(inst: Effect): void {\n  live.delete(inst);\n  inst.destroy();\n}\n\nfunction onMutations(records: MutationRecord[]): void {\n  let removed = false;\n  for (const r of records) {\n    if (r.type === 'attributes') {\n      const el = r.target as Element;\n      live.forEach((inst) => { if (target(inst) === el) drop(inst); });\n      if (el.hasAttribute('data-nf')) create(el);\n      continue;\n    }\n    for (const n of Array.from(r.removedNodes)) if (n.nodeType === 1) removed = true;\n    for (const n of Array.from(r.addedNodes)) if (n.nodeType === 1) scan(n as Element);\n  }\n  if (removed) live.forEach((inst) => { if (!target(inst).isConnected) drop(inst); });\n}\n\n/**\n * Set up every `[data-nf]` element in `root` (and `root` itself) that has no\n * instance yet; returns the new instances. start() does this for the\n * document; call it for content the observer does not see, such as a shadow\n * root. Instances made here are not destroyed automatically when removed.\n */\nexport function scan(root: ParentNode = document): Effect[] {\n  const els: Element[] = Array.prototype.slice.call(root.querySelectorAll('[data-nf]'));\n  if ((root as Element).nodeType === 1 && (root as Element).hasAttribute('data-nf')) els.unshift(root as Element);\n  const out: Effect[] = [];\n  for (const el of els) { const inst = create(el); if (inst) out.push(inst); }\n  return out;\n}\n\n/**\n * Scan the document and watch it for added or removed elements and changes of\n * the `data-nf` attribute. Called on import; idempotent.\n */\nexport function start(): void {\n  pending = false;\n  if (observer || typeof document === 'undefined') return;\n  scan(document);\n  if (typeof MutationObserver !== 'function') return;\n  observer = new MutationObserver(onMutations);\n  observer.observe(document.documentElement, { childList: true, subtree: true, attributes: true, attributeFilter: ['data-nf'] });\n}\n\n/** Stop watching and destroy every instance created from attributes, and the shared Ambient. */\nexport function stop(): void {\n  pending = false;\n  if (observer) { observer.disconnect(); observer = null; }\n  live.forEach(drop);\n  if (shared) { shared.destroy(); shared = null; }\n}\n\n/**\n * The Ambient that drives elements marked `data-nf-ambient`, created on first\n * use with the default options; change them with `ambient().set({ rate: 12 })`.\n */\nexport function ambient(): Ambient {\n  if (!shared) shared = new Ambient([]);\n  return shared;\n}\n\nif (typeof document !== 'undefined') {\n  if (document.readyState === 'loading') {\n    pending = true;\n    document.addEventListener('DOMContentLoaded', () => { if (pending) start(); }, { once: true });\n  } else start();\n}\n"],"mappings":"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"}

package/dist/auto.d.cts

@@ -0,0 +1,25 @@
+/*! noisefloor v0.1.0 | MIT | (c) 2026 digitalemagine */
+import { n as Glitch, r as Ambient, t as Scramble } from "./core.cjs";
+//#region src/auto.d.ts
+type Effect = Scramble | Glitch;
+/**
+ * Set up every `[data-nf]` element in `root` (and `root` itself) that has no
+ * instance yet; returns the new instances. start() does this for the
+ * document; call it for content the observer does not see, such as a shadow
+ * root. Instances made here are not destroyed automatically when removed.
+ */
+export declare function scan(root?: ParentNode): Effect[];
+/**
+ * Scan the document and watch it for added or removed elements and changes of
+ * the `data-nf` attribute. Called on import; idempotent.
+ */
+export declare function start(): void;
+/** Stop watching and destroy every instance created from attributes, and the shared Ambient. */
+export declare function stop(): void;
+/**
+ * The Ambient that drives elements marked `data-nf-ambient`, created on first
+ * use with the default options; change them with `ambient().set({ rate: 12 })`.
+ */
+export declare function ambient(): Ambient;
+//#endregion
+//# sourceMappingURL=auto.d.cts.map

package/dist/auto.d.ts

@@ -0,0 +1,25 @@
+/*! noisefloor v0.1.0 | MIT | (c) 2026 digitalemagine */
+import { n as Glitch, r as Ambient, t as Scramble } from "./core.js";
+//#region src/auto.d.ts
+type Effect = Scramble | Glitch;
+/**
+ * Set up every `[data-nf]` element in `root` (and `root` itself) that has no
+ * instance yet; returns the new instances. start() does this for the
+ * document; call it for content the observer does not see, such as a shadow
+ * root. Instances made here are not destroyed automatically when removed.
+ */
+export declare function scan(root?: ParentNode): Effect[];
+/**
+ * Scan the document and watch it for added or removed elements and changes of
+ * the `data-nf` attribute. Called on import; idempotent.
+ */
+export declare function start(): void;
+/** Stop watching and destroy every instance created from attributes, and the shared Ambient. */
+export declare function stop(): void;
+/**
+ * The Ambient that drives elements marked `data-nf-ambient`, created on first
+ * use with the default options; change them with `ambient().set({ rate: 12 })`.
+ */
+export declare function ambient(): Ambient;
+//#endregion
+//# sourceMappingURL=auto.d.ts.map