interactive-bg 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bohdan Shcherbak
+
+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,203 @@
-# Temporary Holding Version
+# interactive-bg
 
-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.
+Animated backgrounds that react to the pointer, for hero sections, cards and full pages. One `<canvas>`, no dependencies, under 7 kB gzipped for the style you use.
+
+**[Live demo](https://bsh314.github.io/interactive-bg/)**
+
+| `topo` | `dots` | `plus` |
+| --- | --- | --- |
+| ![topo](https://raw.githubusercontent.com/bsh314/interactive-bg/main/docs/topo.png) | ![dots](https://raw.githubusercontent.com/bsh314/interactive-bg/main/docs/dots.png) | ![plus](https://raw.githubusercontent.com/bsh314/interactive-bg/main/docs/plus.png) |
+| Topographic contour lines that drift slowly. The terrain rises under the pointer. | A grid of dots. The pointer pushes them aside; a click sends out a wave. | A grid of "+" signs that turn to point at the pointer; a click sends out a wave. |
+
+- **Small.** Import one style with one renderer and ship only that: 4.5–6.9 kB gzipped, engine included.
+- **Cheap to run.** Idle animation renders at the lowest frame rate that still looks smooth, stops when nothing moves, and pauses off-screen and in background tabs. The grid styles idle on less CPU than an empty animated canvas.
+- **GPU first.** WebGL2, with Canvas 2D as a fallback or as a deliberate choice.
+- **Polite.** Respects `prefers-reduced-motion`, caps pixel density, never blocks clicks on your content.
+- **Typed.** Every option is typed and can be changed at runtime.
+
+## Quick start
+
+```bash
+npm install interactive-bg
+```
+
+```js
+import { createBackground } from 'interactive-bg';
+import { dots } from 'interactive-bg/dots';
+
+createBackground('#hero', dots({ spacing: 24 }));
+```
+
+The first argument is where it goes:
+
+- an element or selector: the background fills that element (it gets `position: relative` if it was static);
+- `null`: a fixed background behind the whole page;
+- your own `<canvas>`: drawn into directly.
+
+Without a bundler:
+
+```html
+<script src="https://unpkg.com/interactive-bg"></script>
+<script>
+  InteractiveBg.createBackground(null, InteractiveBg.topo());
+</script>
+```
+
+## Ship only what you use
+
+Every style comes in three builds. They have the same name and options, so switching is a one-line change.
+
+```js
+import { topo } from 'interactive-bg/topo';          // WebGL2, falls back to Canvas 2D
+import { topo } from 'interactive-bg/topo/webgl';    // WebGL2 only
+import { topo } from 'interactive-bg/topo/canvas2d'; // Canvas 2D only
+```
+
+What your app bundles, `createBackground` included (minified / gzipped):
+
+| Style  | Both renderers  | WebGL only      | Canvas 2D only  |
+| ------ | --------------- | --------------- | --------------- |
+| `topo` | 20.0 / 8.1 kB   | 16.5 / 6.9 kB   | 12.5 / 5.3 kB   |
+| `dots` | 17.9 / 7.3 kB   | 14.4 / 6.0 kB   | 10.4 / 4.5 kB   |
+| `plus` | 19.3 / 8.0 kB   | 16.2 / 6.8 kB   | 11.7 / 5.0 kB   |
+
+With a single renderer there is no fallback: if the browser can't provide it, the background stays empty, `bg.renderer` is `null`, and your page carries on.
+
+## Performance
+
+Full-screen 1920×1080 background in Chrome on an Apple M1 Pro.
+
+| Style, renderer   | Main thread, idle | Main thread, pointer moving | CPU, idle | CPU, pointer moving | Memory  |
+| ----------------- | ----------------- | --------------------------- | --------- | ------------------- | ------- |
+| `topo`, WebGL     | 1.5%              | 1.7%                        | 7%        | 12%                 | ~95 MB  |
+| `topo`, Canvas 2D | 4.5%              | 10%                         | 10%       | 21%                 | ~105 MB |
+| `dots`, WebGL     | 0.2%              | 0.4%                        | 4.4%      | 11%                 | ~90 MB  |
+| `dots`, Canvas 2D | 0.4%              | 1.7%                        | 4.3%      | 12%                 | ~70 MB  |
+| `plus`, WebGL     | 0.1%              | 0.9%                        | 3.6%      | 11%                 | ~90 MB  |
+| `plus`, Canvas 2D | 0.4%              | 2.5%                        | 3.9%      | 13%                 | ~70 MB  |
+| Empty canvas, 30 fps, for reference | — | —                    | 6.4%      | —                   | ~85 MB  |
+
+- **Main thread**: share of the page's main thread the background takes, so what's left for your app.
+- **CPU** and **Memory**: the browser's renderer and GPU processes, as % of one core and MB above a blank page. Most of the memory is the canvas itself, which the browser needs for any full-screen canvas.
+
+Reproduce with `npm run bench:memory` and `bench/realtime.html`; see [CONTRIBUTING.md](CONTRIBUTING.md#benchmarks).
+
+## API
+
+```js
+const bg = createBackground(target, style, engineOptions);
+
+bg.setOptions({ spacing: 32 });          // the style's options, any time
+bg.setEngineOptions({ idleFps: 15 });    // engine options, any time (except renderer)
+bg.pause();
+bg.resume();
+bg.destroy();                            // removes the canvas, listeners and GPU context
+
+bg.renderer;                             // 'webgl' | 'canvas2d' | null
+```
+
+In React, create it in an effect and destroy it in the cleanup:
+
+```jsx
+useEffect(() => {
+  const bg = createBackground(ref.current, dots());
+  return () => bg.destroy();
+}, []);
+```
+
+## Engine options
+
+Shared by every style.
+
+| Option                 | Default  | What it does                                                                                     |
+| ---------------------- | -------- | ------------------------------------------------------------------------------------------------ |
+| `backgroundColor`      | `null`   | Fill behind the pattern. `null` keeps the canvas transparent.                                    |
+| `fadeOutTop`, `fadeOutRight`, `fadeOutBottom`, `fadeOutLeft` | `0` | Fade the pattern out over this many px towards that edge. The background colour stays solid. |
+| `interactive`          | `true`   | React to the pointer and to clicks.                                                              |
+| `maxFps`               | `60`     | Frame-rate cap while reacting to the pointer or a click. `0` = uncapped.                         |
+| `idleFps`              | `30`     | Frame-rate cap for the ambient animation. Styles may use less.                                   |
+| `maxDpr`               | `1.5`    | Pixel-density cap. Memory grows with its square; `1.5` looks the same as `2` for thin lines.     |
+| `respectReducedMotion` | `true`   | Hold the ambient animation still for users who prefer reduced motion.                            |
+| `renderer`             | `'auto'` | `'webgl'` or `'canvas2d'` to try that one first. Fixed at creation.                              |
+
+## Style options
+
+<details>
+<summary><code>topo</code></summary>
+
+| Option            | Default      | What it does                                                        |
+| ----------------- | ------------ | ------------------------------------------------------------------- |
+| `lineColor`       | `#5b6576`    | Colour of regular lines.                                            |
+| `majorLineColor`  | `#7dd3a8`    | Colour of every `majorEvery`-th line.                               |
+| `lineOpacity`     | `0.5`        | Opacity of all lines, `0`–`1`.                                      |
+| `lineWidth`       | `1`          | Regular line width in px.                                           |
+| `majorLineWidth`  | `1.75`       | Major line width in px.                                             |
+| `majorEvery`      | `5`          | Every n-th line is a major line. `0` = none.                        |
+| `levels`          | `12`         | Number of contour levels. Higher = denser.                          |
+| `scale`           | `0.0025`     | Size of the landforms. Lower = larger and smoother.                 |
+| `octaves`         | `2`          | Detail layers. Higher = rougher terrain.                            |
+| `speed`           | `0.025`      | How fast the terrain changes. `0` = static.                         |
+| `resolution`      | `6`          | Sampling cell size in px. Lower = smoother lines, more CPU.         |
+| `seed`            | `1332056948` | Which landscape. Use `Math.random() * 2 ** 32` for a new one each load. |
+| `pointerRadius`   | `100`        | Reach of the pointer in px.                                         |
+| `pointerStrength` | `0.35`       | Height of the bump under the pointer. Negative = a crater.          |
+
+</details>
+
+<details>
+<summary><code>dots</code></summary>
+
+| Option            | Default   | What it does                                                         |
+| ----------------- | --------- | -------------------------------------------------------------------- |
+| `color`           | `#8b95a5` | Dot colour.                                                          |
+| `opacity`         | `0.6`     | Opacity, `0`–`1`.                                                    |
+| `size`            | `1.6`     | Dot radius in px.                                                    |
+| `spacing`         | `26`      | Distance between dots in px. The grid keeps half of this as padding. |
+| `jitter`          | `1.2`     | How far each dot wanders, in px. `0` = still.                        |
+| `jitterSpeed`     | `0.35`    | Wander speed in cycles per second.                                   |
+| `pointerRadius`   | `160`     | Reach of the pointer in px.                                          |
+| `pointerStrength` | `22`      | How far dots next to the pointer are pushed, in px. Negative = pulled in. |
+| `waveStrength`    | `10`      | How far a click wave pushes dots, in px. `0` = no waves.             |
+| `waveSpeed`       | `520`     | Wave speed in px per second.                                         |
+| `waveWidth`       | `60`      | Width of the wave's ring in px.                                      |
+| `waveDuration`    | `1.8`     | Seconds until a wave has faded out.                                  |
+
+</details>
+
+<details>
+<summary><code>plus</code></summary>
+
+| Option         | Default   | What it does                                                            |
+| -------------- | --------- | ----------------------------------------------------------------------- |
+| `color`        | `#8b95a5` | Sign colour.                                                            |
+| `opacity`      | `0.6`     | Opacity, `0`–`1`.                                                       |
+| `size`         | `4`       | Arm length from the centre in px.                                       |
+| `weight`       | `1.2`     | Stroke weight in px.                                                    |
+| `spacing`      | `28`      | Distance between signs in px. The grid keeps half of this as padding.   |
+| `jitter`       | `1`       | How far each sign wanders, in px. `0` = still.                          |
+| `jitterSpeed`  | `0.35`    | Wander speed in cycles per second.                                      |
+| `pointerAlign` | `1`       | How fully signs turn to point an arm at the pointer, `0`–`1`.           |
+| `turnTime`     | `0.25`    | How smoothly signs turn, in seconds. `0` = instantly.                   |
+| `waveAlign`    | `1`       | How fully signs on a click wave turn to face the click, `0`–`1`.        |
+| `waveWeight`   | `1.5`     | Extra stroke weight on the wave's crest. `1` = double.                  |
+| `waveSpeed`    | `520`     | Wave speed in px per second.                                            |
+| `waveWidth`    | `60`      | Width of the wave's ring in px.                                         |
+| `waveDuration` | `1.8`     | Seconds until a wave has faded out.                                     |
+
+</details>
+
+## Your own style
+
+The engine handles the canvas, sizing, frame loop, pointer, visibility, reduced motion, background colour and edge fades. A style only says what to draw, in WebGL2, Canvas 2D or both. See [docs/custom-styles.md](docs/custom-styles.md).
+
+## Browser support
+
+Current Chrome, Edge, Firefox and Safari (15+). WebGL2 is used where available; every built-in style also has a Canvas 2D renderer.
+
+## Contributing
+
+Development setup, project layout, benchmarks and releases: [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

package/dist/core/canvas2d-renderer.cjs

@@ -0,0 +1,119 @@
+const require_surface = require("./surface.cjs");
+// src/core/canvas2d-renderer.ts
+var SIDES = [
+	"top",
+	"right",
+	"bottom",
+	"left"
+];
+/**
+* Draw a style with Canvas 2D. The engine clears to the background colour and
+* sets the transform so the style draws in CSS pixels.
+*/
+function canvas2dRenderer(createRenderer) {
+	return {
+		name: "canvas2d",
+		create(canvas, options) {
+			const ctx = canvas.getContext("2d");
+			if (!ctx) return null;
+			const renderer = createRenderer(ctx, options);
+			const gradients = SIDES.map(() => ({
+				gradient: null,
+				size: 0,
+				length: 0
+			}));
+			/**
+			* Erase the style's drawing gradually along one side: nothing `length` px in from the edge,
+			* all of it at the edge. Erasing multiplies, so overlapping sides combine.
+			*/
+			const fadeSide = (side, length, width, height) => {
+				const size = side === 1 || side === 3 ? width : height;
+				const cache = gradients[side];
+				if (!cache.gradient || cache.size !== size || cache.length !== length) {
+					const [x0, y0, x1, y1] = [
+						[
+							0,
+							length,
+							0,
+							0
+						],
+						[
+							width - length,
+							0,
+							width,
+							0
+						],
+						[
+							0,
+							height - length,
+							0,
+							height
+						],
+						[
+							length,
+							0,
+							0,
+							0
+						]
+					][side];
+					cache.gradient = ctx.createLinearGradient(x0, y0, x1, y1);
+					cache.gradient.addColorStop(0, "rgba(0, 0, 0, 0)");
+					cache.gradient.addColorStop(1, "rgba(0, 0, 0, 1)");
+					cache.size = size;
+					cache.length = length;
+				}
+				const strip = Math.min(length, size);
+				ctx.fillStyle = cache.gradient;
+				if (side === 0) ctx.fillRect(0, 0, width, strip);
+				else if (side === 1) ctx.fillRect(width - strip, 0, strip, height);
+				else if (side === 2) ctx.fillRect(0, height - strip, width, strip);
+				else ctx.fillRect(0, 0, strip, height);
+			};
+			return {
+				name: "canvas2d",
+				update(next) {
+					renderer.update(next);
+				},
+				render(frame, backgroundColor, fade) {
+					const { width, height, dpr } = frame;
+					ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+					ctx.globalAlpha = 1;
+					ctx.globalCompositeOperation = "source-over";
+					ctx.clearRect(0, 0, width, height);
+					const fading = require_surface.fades(fade);
+					if (backgroundColor && !fading) {
+						ctx.fillStyle = backgroundColor;
+						ctx.fillRect(0, 0, width, height);
+					}
+					const busy = renderer.render(frame) === true;
+					if (fading) {
+						ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+						ctx.globalAlpha = 1;
+						ctx.globalCompositeOperation = "destination-out";
+						for (let side = 0; side < SIDES.length; side++) {
+							const length = fade[SIDES[side]];
+							if (length > 0) fadeSide(side, length, width, height);
+						}
+						if (backgroundColor) {
+							ctx.globalCompositeOperation = "destination-over";
+							ctx.fillStyle = backgroundColor;
+							ctx.fillRect(0, 0, width, height);
+						}
+						ctx.globalCompositeOperation = "source-over";
+					}
+					return busy;
+				},
+				clear() {
+					ctx.setTransform(1, 0, 0, 1, 0, 0);
+					ctx.clearRect(0, 0, canvas.width, canvas.height);
+				},
+				destroy() {
+					renderer.destroy?.();
+				}
+			};
+		}
+	};
+}
+exports.canvas2dRenderer = canvas2dRenderer;
+
+//# sourceMappingURL=canvas2d-renderer.cjs.map

package/dist/core/canvas2d-renderer.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas2d-renderer.cjs","names":["fades"],"sources":["../../src/core/canvas2d-renderer.ts"],"sourcesContent":["import type { StyleRenderer } from './style';\nimport { fades, type Fade, type Renderer } from './surface';\n\nconst SIDES: readonly (keyof Fade)[] = ['top', 'right', 'bottom', 'left'];\n\n/**\n * Draw a style with Canvas 2D. The engine clears to the background colour and\n * sets the transform so the style draws in CSS pixels.\n */\nexport function canvas2dRenderer<O>(\n  createRenderer: (ctx: CanvasRenderingContext2D, options: O) => StyleRenderer<O>,\n): Renderer<O> {\n  return {\n    name: 'canvas2d',\n    create(canvas, options) {\n      const ctx = canvas.getContext('2d');\n      if (!ctx) return null;\n      const renderer = createRenderer(ctx, options);\n\n      // One gradient per side, kept while the canvas size and fade length stay the same.\n      const gradients: { gradient: CanvasGradient | null; size: number; length: number }[] = SIDES.map(() => ({\n        gradient: null,\n        size: 0,\n        length: 0,\n      }));\n\n      /**\n       * Erase the style's drawing gradually along one side: nothing `length` px in from the edge,\n       * all of it at the edge. Erasing multiplies, so overlapping sides combine.\n       */\n      const fadeSide = (side: number, length: number, width: number, height: number): void => {\n        const horizontal = side === 1 || side === 3; // right, left\n        const size = horizontal ? width : height;\n        const cache = gradients[side];\n        if (!cache.gradient || cache.size !== size || cache.length !== length) {\n          // From the inner end of the strip to the edge.\n          const [x0, y0, x1, y1] = [\n            [0, length, 0, 0], // top\n            [width - length, 0, width, 0], // right\n            [0, height - length, 0, height], // bottom\n            [length, 0, 0, 0], // left\n          ][side];\n          cache.gradient = ctx.createLinearGradient(x0, y0, x1, y1);\n          cache.gradient.addColorStop(0, 'rgba(0, 0, 0, 0)');\n          cache.gradient.addColorStop(1, 'rgba(0, 0, 0, 1)');\n          cache.size = size;\n          cache.length = length;\n        }\n        const strip = Math.min(length, size);\n        ctx.fillStyle = cache.gradient;\n        if (side === 0) ctx.fillRect(0, 0, width, strip);\n        else if (side === 1) ctx.fillRect(width - strip, 0, strip, height);\n        else if (side === 2) ctx.fillRect(0, height - strip, width, strip);\n        else ctx.fillRect(0, 0, strip, height);\n      };\n\n      return {\n        name: 'canvas2d',\n        update(next) {\n          renderer.update(next);\n        },\n        render(frame, backgroundColor, fade) {\n          const { width, height, dpr } = frame;\n          ctx.setTransform(dpr, 0, 0, dpr, 0, 0);\n          ctx.globalAlpha = 1;\n          ctx.globalCompositeOperation = 'source-over';\n          ctx.clearRect(0, 0, width, height);\n          // With a fade, the background goes in last, behind the faded drawing, so it stays solid.\n          const fading = fades(fade);\n          if (backgroundColor && !fading) {\n            ctx.fillStyle = backgroundColor;\n            ctx.fillRect(0, 0, width, height);\n          }\n          const busy = renderer.render(frame) === true;\n          if (fading) {\n            ctx.setTransform(dpr, 0, 0, dpr, 0, 0);\n            ctx.globalAlpha = 1;\n            ctx.globalCompositeOperation = 'destination-out';\n            for (let side = 0; side < SIDES.length; side++) {\n              const length = fade[SIDES[side]];\n              if (length > 0) fadeSide(side, length, width, height);\n            }\n            if (backgroundColor) {\n              ctx.globalCompositeOperation = 'destination-over';\n              ctx.fillStyle = backgroundColor;\n              ctx.fillRect(0, 0, width, height);\n            }\n            ctx.globalCompositeOperation = 'source-over';\n          }\n          return busy;\n        },\n        clear() {\n          ctx.setTransform(1, 0, 0, 1, 0, 0);\n          ctx.clearRect(0, 0, canvas.width, canvas.height);\n        },\n        destroy() {\n          renderer.destroy?.();\n        },\n      };\n    },\n  };\n}\n"],"mappings":";;AAGA,IAAM,QAAiC;CAAC;CAAO;CAAS;CAAU;AAAM;;;;;AAMxE,SAAgB,iBACd,gBACa;CACb,OAAO;EACL,MAAM;EACN,OAAO,QAAQ,SAAS;GACtB,MAAM,MAAM,OAAO,WAAW,IAAI;GAClC,IAAI,CAAC,KAAK,OAAO;GACjB,MAAM,WAAW,eAAe,KAAK,OAAO;GAG5C,MAAM,YAAiF,MAAM,WAAW;IACtG,UAAU;IACV,MAAM;IACN,QAAQ;GACV,EAAE;;;;;GAMF,MAAM,YAAY,MAAc,QAAgB,OAAe,WAAyB;IAEtF,MAAM,OADa,SAAS,KAAK,SAAS,IAChB,QAAQ;IAClC,MAAM,QAAQ,UAAU;IACxB,IAAI,CAAC,MAAM,YAAY,MAAM,SAAS,QAAQ,MAAM,WAAW,QAAQ;KAErE,MAAM,CAAC,IAAI,IAAI,IAAI,MAAM;MACvB;OAAC;OAAG;OAAQ;OAAG;MAAC;MAChB;OAAC,QAAQ;OAAQ;OAAG;OAAO;MAAC;MAC5B;OAAC;OAAG,SAAS;OAAQ;OAAG;MAAM;MAC9B;OAAC;OAAQ;OAAG;OAAG;MAAC;KAClB,CAAC,CAAC;KACF,MAAM,WAAW,IAAI,qBAAqB,IAAI,IAAI,IAAI,EAAE;KACxD,MAAM,SAAS,aAAa,GAAG,kBAAkB;KACjD,MAAM,SAAS,aAAa,GAAG,kBAAkB;KACjD,MAAM,OAAO;KACb,MAAM,SAAS;IACjB;IACA,MAAM,QAAQ,KAAK,IAAI,QAAQ,IAAI;IACnC,IAAI,YAAY,MAAM;IACtB,IAAI,SAAS,GAAG,IAAI,SAAS,GAAG,GAAG,OAAO,KAAK;SAC1C,IAAI,SAAS,GAAG,IAAI,SAAS,QAAQ,OAAO,GAAG,OAAO,MAAM;SAC5D,IAAI,SAAS,GAAG,IAAI,SAAS,GAAG,SAAS,OAAO,OAAO,KAAK;SAC5D,IAAI,SAAS,GAAG,GAAG,OAAO,MAAM;GACvC;GAEA,OAAO;IACL,MAAM;IACN,OAAO,MAAM;KACX,SAAS,OAAO,IAAI;IACtB;IACA,OAAO,OAAO,iBAAiB,MAAM;KACnC,MAAM,EAAE,OAAO,QAAQ,QAAQ;KAC/B,IAAI,aAAa,KAAK,GAAG,GAAG,KAAK,GAAG,CAAC;KACrC,IAAI,cAAc;KAClB,IAAI,2BAA2B;KAC/B,IAAI,UAAU,GAAG,GAAG,OAAO,MAAM;KAEjC,MAAM,SAASA,gBAAAA,MAAM,IAAI;KACzB,IAAI,mBAAmB,CAAC,QAAQ;MAC9B,IAAI,YAAY;MAChB,IAAI,SAAS,GAAG,GAAG,OAAO,MAAM;KAClC;KACA,MAAM,OAAO,SAAS,OAAO,KAAK,MAAM;KACxC,IAAI,QAAQ;MACV,IAAI,aAAa,KAAK,GAAG,GAAG,KAAK,GAAG,CAAC;MACrC,IAAI,cAAc;MAClB,IAAI,2BAA2B;MAC/B,KAAK,IAAI,OAAO,GAAG,OAAO,MAAM,QAAQ,QAAQ;OAC9C,MAAM,SAAS,KAAK,MAAM;OAC1B,IAAI,SAAS,GAAG,SAAS,MAAM,QAAQ,OAAO,MAAM;MACtD;MACA,IAAI,iBAAiB;OACnB,IAAI,2BAA2B;OAC/B,IAAI,YAAY;OAChB,IAAI,SAAS,GAAG,GAAG,OAAO,MAAM;MAClC;MACA,IAAI,2BAA2B;KACjC;KACA,OAAO;IACT;IACA,QAAQ;KACN,IAAI,aAAa,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;KACjC,IAAI,UAAU,GAAG,GAAG,OAAO,OAAO,OAAO,MAAM;IACjD;IACA,UAAU;KACR,SAAS,UAAU;IACrB;GACF;EACF;CACF;AACF"}

package/dist/core/canvas2d-renderer.d.cts

@@ -0,0 +1,7 @@
+import type { StyleRenderer } from './style.cjs';
+import { type Renderer } from './surface.cjs';
+/**
+ * Draw a style with Canvas 2D. The engine clears to the background colour and
+ * sets the transform so the style draws in CSS pixels.
+ */
+export declare function canvas2dRenderer<O>(createRenderer: (ctx: CanvasRenderingContext2D, options: O) => StyleRenderer<O>): Renderer<O>;

package/dist/core/canvas2d-renderer.d.ts

@@ -0,0 +1,7 @@
+import type { StyleRenderer } from './style.js';
+import { type Renderer } from './surface.js';
+/**
+ * Draw a style with Canvas 2D. The engine clears to the background colour and
+ * sets the transform so the style draws in CSS pixels.
+ */
+export declare function canvas2dRenderer<O>(createRenderer: (ctx: CanvasRenderingContext2D, options: O) => StyleRenderer<O>): Renderer<O>;

package/dist/core/canvas2d-renderer.js

@@ -0,0 +1,119 @@
+import { fades } from "./surface.js";
+// src/core/canvas2d-renderer.ts
+var SIDES = [
+	"top",
+	"right",
+	"bottom",
+	"left"
+];
+/**
+* Draw a style with Canvas 2D. The engine clears to the background colour and
+* sets the transform so the style draws in CSS pixels.
+*/
+function canvas2dRenderer(createRenderer) {
+	return {
+		name: "canvas2d",
+		create(canvas, options) {
+			const ctx = canvas.getContext("2d");
+			if (!ctx) return null;
+			const renderer = createRenderer(ctx, options);
+			const gradients = SIDES.map(() => ({
+				gradient: null,
+				size: 0,
+				length: 0
+			}));
+			/**
+			* Erase the style's drawing gradually along one side: nothing `length` px in from the edge,
+			* all of it at the edge. Erasing multiplies, so overlapping sides combine.
+			*/
+			const fadeSide = (side, length, width, height) => {
+				const size = side === 1 || side === 3 ? width : height;
+				const cache = gradients[side];
+				if (!cache.gradient || cache.size !== size || cache.length !== length) {
+					const [x0, y0, x1, y1] = [
+						[
+							0,
+							length,
+							0,
+							0
+						],
+						[
+							width - length,
+							0,
+							width,
+							0
+						],
+						[
+							0,
+							height - length,
+							0,
+							height
+						],
+						[
+							length,
+							0,
+							0,
+							0
+						]
+					][side];
+					cache.gradient = ctx.createLinearGradient(x0, y0, x1, y1);
+					cache.gradient.addColorStop(0, "rgba(0, 0, 0, 0)");
+					cache.gradient.addColorStop(1, "rgba(0, 0, 0, 1)");
+					cache.size = size;
+					cache.length = length;
+				}
+				const strip = Math.min(length, size);
+				ctx.fillStyle = cache.gradient;
+				if (side === 0) ctx.fillRect(0, 0, width, strip);
+				else if (side === 1) ctx.fillRect(width - strip, 0, strip, height);
+				else if (side === 2) ctx.fillRect(0, height - strip, width, strip);
+				else ctx.fillRect(0, 0, strip, height);
+			};
+			return {
+				name: "canvas2d",
+				update(next) {
+					renderer.update(next);
+				},
+				render(frame, backgroundColor, fade) {
+					const { width, height, dpr } = frame;
+					ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+					ctx.globalAlpha = 1;
+					ctx.globalCompositeOperation = "source-over";
+					ctx.clearRect(0, 0, width, height);
+					const fading = fades(fade);
+					if (backgroundColor && !fading) {
+						ctx.fillStyle = backgroundColor;
+						ctx.fillRect(0, 0, width, height);
+					}
+					const busy = renderer.render(frame) === true;
+					if (fading) {
+						ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+						ctx.globalAlpha = 1;
+						ctx.globalCompositeOperation = "destination-out";
+						for (let side = 0; side < SIDES.length; side++) {
+							const length = fade[SIDES[side]];
+							if (length > 0) fadeSide(side, length, width, height);
+						}
+						if (backgroundColor) {
+							ctx.globalCompositeOperation = "destination-over";
+							ctx.fillStyle = backgroundColor;
+							ctx.fillRect(0, 0, width, height);
+						}
+						ctx.globalCompositeOperation = "source-over";
+					}
+					return busy;
+				},
+				clear() {
+					ctx.setTransform(1, 0, 0, 1, 0, 0);
+					ctx.clearRect(0, 0, canvas.width, canvas.height);
+				},
+				destroy() {
+					renderer.destroy?.();
+				}
+			};
+		}
+	};
+}
+export { canvas2dRenderer };
+
+//# sourceMappingURL=canvas2d-renderer.js.map

package/dist/core/canvas2d-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas2d-renderer.js","names":[],"sources":["../../src/core/canvas2d-renderer.ts"],"sourcesContent":["import type { StyleRenderer } from './style';\nimport { fades, type Fade, type Renderer } from './surface';\n\nconst SIDES: readonly (keyof Fade)[] = ['top', 'right', 'bottom', 'left'];\n\n/**\n * Draw a style with Canvas 2D. The engine clears to the background colour and\n * sets the transform so the style draws in CSS pixels.\n */\nexport function canvas2dRenderer<O>(\n  createRenderer: (ctx: CanvasRenderingContext2D, options: O) => StyleRenderer<O>,\n): Renderer<O> {\n  return {\n    name: 'canvas2d',\n    create(canvas, options) {\n      const ctx = canvas.getContext('2d');\n      if (!ctx) return null;\n      const renderer = createRenderer(ctx, options);\n\n      // One gradient per side, kept while the canvas size and fade length stay the same.\n      const gradients: { gradient: CanvasGradient | null; size: number; length: number }[] = SIDES.map(() => ({\n        gradient: null,\n        size: 0,\n        length: 0,\n      }));\n\n      /**\n       * Erase the style's drawing gradually along one side: nothing `length` px in from the edge,\n       * all of it at the edge. Erasing multiplies, so overlapping sides combine.\n       */\n      const fadeSide = (side: number, length: number, width: number, height: number): void => {\n        const horizontal = side === 1 || side === 3; // right, left\n        const size = horizontal ? width : height;\n        const cache = gradients[side];\n        if (!cache.gradient || cache.size !== size || cache.length !== length) {\n          // From the inner end of the strip to the edge.\n          const [x0, y0, x1, y1] = [\n            [0, length, 0, 0], // top\n            [width - length, 0, width, 0], // right\n            [0, height - length, 0, height], // bottom\n            [length, 0, 0, 0], // left\n          ][side];\n          cache.gradient = ctx.createLinearGradient(x0, y0, x1, y1);\n          cache.gradient.addColorStop(0, 'rgba(0, 0, 0, 0)');\n          cache.gradient.addColorStop(1, 'rgba(0, 0, 0, 1)');\n          cache.size = size;\n          cache.length = length;\n        }\n        const strip = Math.min(length, size);\n        ctx.fillStyle = cache.gradient;\n        if (side === 0) ctx.fillRect(0, 0, width, strip);\n        else if (side === 1) ctx.fillRect(width - strip, 0, strip, height);\n        else if (side === 2) ctx.fillRect(0, height - strip, width, strip);\n        else ctx.fillRect(0, 0, strip, height);\n      };\n\n      return {\n        name: 'canvas2d',\n        update(next) {\n          renderer.update(next);\n        },\n        render(frame, backgroundColor, fade) {\n          const { width, height, dpr } = frame;\n          ctx.setTransform(dpr, 0, 0, dpr, 0, 0);\n          ctx.globalAlpha = 1;\n          ctx.globalCompositeOperation = 'source-over';\n          ctx.clearRect(0, 0, width, height);\n          // With a fade, the background goes in last, behind the faded drawing, so it stays solid.\n          const fading = fades(fade);\n          if (backgroundColor && !fading) {\n            ctx.fillStyle = backgroundColor;\n            ctx.fillRect(0, 0, width, height);\n          }\n          const busy = renderer.render(frame) === true;\n          if (fading) {\n            ctx.setTransform(dpr, 0, 0, dpr, 0, 0);\n            ctx.globalAlpha = 1;\n            ctx.globalCompositeOperation = 'destination-out';\n            for (let side = 0; side < SIDES.length; side++) {\n              const length = fade[SIDES[side]];\n              if (length > 0) fadeSide(side, length, width, height);\n            }\n            if (backgroundColor) {\n              ctx.globalCompositeOperation = 'destination-over';\n              ctx.fillStyle = backgroundColor;\n              ctx.fillRect(0, 0, width, height);\n            }\n            ctx.globalCompositeOperation = 'source-over';\n          }\n          return busy;\n        },\n        clear() {\n          ctx.setTransform(1, 0, 0, 1, 0, 0);\n          ctx.clearRect(0, 0, canvas.width, canvas.height);\n        },\n        destroy() {\n          renderer.destroy?.();\n        },\n      };\n    },\n  };\n}\n"],"mappings":";;AAGA,IAAM,QAAiC;CAAC;CAAO;CAAS;CAAU;AAAM;;;;;AAMxE,SAAgB,iBACd,gBACa;CACb,OAAO;EACL,MAAM;EACN,OAAO,QAAQ,SAAS;GACtB,MAAM,MAAM,OAAO,WAAW,IAAI;GAClC,IAAI,CAAC,KAAK,OAAO;GACjB,MAAM,WAAW,eAAe,KAAK,OAAO;GAG5C,MAAM,YAAiF,MAAM,WAAW;IACtG,UAAU;IACV,MAAM;IACN,QAAQ;GACV,EAAE;;;;;GAMF,MAAM,YAAY,MAAc,QAAgB,OAAe,WAAyB;IAEtF,MAAM,OADa,SAAS,KAAK,SAAS,IAChB,QAAQ;IAClC,MAAM,QAAQ,UAAU;IACxB,IAAI,CAAC,MAAM,YAAY,MAAM,SAAS,QAAQ,MAAM,WAAW,QAAQ;KAErE,MAAM,CAAC,IAAI,IAAI,IAAI,MAAM;MACvB;OAAC;OAAG;OAAQ;OAAG;MAAC;MAChB;OAAC,QAAQ;OAAQ;OAAG;OAAO;MAAC;MAC5B;OAAC;OAAG,SAAS;OAAQ;OAAG;MAAM;MAC9B;OAAC;OAAQ;OAAG;OAAG;MAAC;KAClB,CAAC,CAAC;KACF,MAAM,WAAW,IAAI,qBAAqB,IAAI,IAAI,IAAI,EAAE;KACxD,MAAM,SAAS,aAAa,GAAG,kBAAkB;KACjD,MAAM,SAAS,aAAa,GAAG,kBAAkB;KACjD,MAAM,OAAO;KACb,MAAM,SAAS;IACjB;IACA,MAAM,QAAQ,KAAK,IAAI,QAAQ,IAAI;IACnC,IAAI,YAAY,MAAM;IACtB,IAAI,SAAS,GAAG,IAAI,SAAS,GAAG,GAAG,OAAO,KAAK;SAC1C,IAAI,SAAS,GAAG,IAAI,SAAS,QAAQ,OAAO,GAAG,OAAO,MAAM;SAC5D,IAAI,SAAS,GAAG,IAAI,SAAS,GAAG,SAAS,OAAO,OAAO,KAAK;SAC5D,IAAI,SAAS,GAAG,GAAG,OAAO,MAAM;GACvC;GAEA,OAAO;IACL,MAAM;IACN,OAAO,MAAM;KACX,SAAS,OAAO,IAAI;IACtB;IACA,OAAO,OAAO,iBAAiB,MAAM;KACnC,MAAM,EAAE,OAAO,QAAQ,QAAQ;KAC/B,IAAI,aAAa,KAAK,GAAG,GAAG,KAAK,GAAG,CAAC;KACrC,IAAI,cAAc;KAClB,IAAI,2BAA2B;KAC/B,IAAI,UAAU,GAAG,GAAG,OAAO,MAAM;KAEjC,MAAM,SAAS,MAAM,IAAI;KACzB,IAAI,mBAAmB,CAAC,QAAQ;MAC9B,IAAI,YAAY;MAChB,IAAI,SAAS,GAAG,GAAG,OAAO,MAAM;KAClC;KACA,MAAM,OAAO,SAAS,OAAO,KAAK,MAAM;KACxC,IAAI,QAAQ;MACV,IAAI,aAAa,KAAK,GAAG,GAAG,KAAK,GAAG,CAAC;MACrC,IAAI,cAAc;MAClB,IAAI,2BAA2B;MAC/B,KAAK,IAAI,OAAO,GAAG,OAAO,MAAM,QAAQ,QAAQ;OAC9C,MAAM,SAAS,KAAK,MAAM;OAC1B,IAAI,SAAS,GAAG,SAAS,MAAM,QAAQ,OAAO,MAAM;MACtD;MACA,IAAI,iBAAiB;OACnB,IAAI,2BAA2B;OAC/B,IAAI,YAAY;OAChB,IAAI,SAAS,GAAG,GAAG,OAAO,MAAM;MAClC;MACA,IAAI,2BAA2B;KACjC;KACA,OAAO;IACT;IACA,QAAQ;KACN,IAAI,aAAa,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;KACjC,IAAI,UAAU,GAAG,GAAG,OAAO,OAAO,OAAO,MAAM;IACjD;IACA,UAAU;KACR,SAAS,UAAU;IACrB;GACF;EACF;CACF;AACF"}

package/dist/core/color.cjs

@@ -0,0 +1,46 @@
+// src/core/color.ts
+var TRANSPARENT = [
+	0,
+	0,
+	0,
+	0
+];
+var probe = null;
+var cache = /* @__PURE__ */ new Map();
+/**
+* Resolve any CSS colour to straight (non-premultiplied) sRGB components in 0–1,
+* by letting the browser paint it into a 1×1 canvas. Results are cached.
+*/
+function parseColor(color) {
+	if (!color || color === "transparent") return TRANSPARENT;
+	const cached = cache.get(color);
+	if (cached) return cached;
+	if (!probe) {
+		const canvas = document.createElement("canvas");
+		canvas.width = canvas.height = 1;
+		probe = canvas.getContext("2d", { willReadFrequently: true });
+		if (!probe) return [
+			0,
+			0,
+			0,
+			1
+		];
+	}
+	probe.clearRect(0, 0, 1, 1);
+	probe.fillStyle = "#000";
+	probe.fillStyle = color;
+	probe.fillRect(0, 0, 1, 1);
+	const [r, g, b, a] = probe.getImageData(0, 0, 1, 1).data;
+	const rgba = [
+		r / 255,
+		g / 255,
+		b / 255,
+		a / 255
+	];
+	if (cache.size > 64) cache.clear();
+	cache.set(color, rgba);
+	return rgba;
+}
+exports.parseColor = parseColor;
+
+//# sourceMappingURL=color.cjs.map

package/dist/core/color.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.cjs","names":[],"sources":["../../src/core/color.ts"],"sourcesContent":["export type RGBA = readonly [r: number, g: number, b: number, a: number];\n\nconst TRANSPARENT: RGBA = [0, 0, 0, 0];\n\nlet probe: CanvasRenderingContext2D | null = null;\nconst cache = new Map<string, RGBA>();\n\n/**\n * Resolve any CSS colour to straight (non-premultiplied) sRGB components in 0–1,\n * by letting the browser paint it into a 1×1 canvas. Results are cached.\n */\nexport function parseColor(color: string | null): RGBA {\n  if (!color || color === 'transparent') return TRANSPARENT;\n  const cached = cache.get(color);\n  if (cached) return cached;\n\n  if (!probe) {\n    const canvas = document.createElement('canvas');\n    canvas.width = canvas.height = 1;\n    probe = canvas.getContext('2d', { willReadFrequently: true });\n    if (!probe) return [0, 0, 0, 1];\n  }\n  probe.clearRect(0, 0, 1, 1);\n  // An invalid colour leaves fillStyle unchanged, so it falls back to black.\n  probe.fillStyle = '#000';\n  probe.fillStyle = color;\n  probe.fillRect(0, 0, 1, 1);\n  const [r, g, b, a] = probe.getImageData(0, 0, 1, 1).data;\n  const rgba: RGBA = [r / 255, g / 255, b / 255, a / 255];\n  if (cache.size > 64) cache.clear();\n  cache.set(color, rgba);\n  return rgba;\n}\n"],"mappings":";AAEA,IAAM,cAAoB;CAAC;CAAG;CAAG;CAAG;AAAC;AAErC,IAAI,QAAyC;AAC7C,IAAM,wBAAQ,IAAI,IAAkB;;;;;AAMpC,SAAgB,WAAW,OAA4B;CACrD,IAAI,CAAC,SAAS,UAAU,eAAe,OAAO;CAC9C,MAAM,SAAS,MAAM,IAAI,KAAK;CAC9B,IAAI,QAAQ,OAAO;CAEnB,IAAI,CAAC,OAAO;EACV,MAAM,SAAS,SAAS,cAAc,QAAQ;EAC9C,OAAO,QAAQ,OAAO,SAAS;EAC/B,QAAQ,OAAO,WAAW,MAAM,EAAE,oBAAoB,KAAK,CAAC;EAC5D,IAAI,CAAC,OAAO,OAAO;GAAC;GAAG;GAAG;GAAG;EAAC;CAChC;CACA,MAAM,UAAU,GAAG,GAAG,GAAG,CAAC;CAE1B,MAAM,YAAY;CAClB,MAAM,YAAY;CAClB,MAAM,SAAS,GAAG,GAAG,GAAG,CAAC;CACzB,MAAM,CAAC,GAAG,GAAG,GAAG,KAAK,MAAM,aAAa,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC;CACpD,MAAM,OAAa;EAAC,IAAI;EAAK,IAAI;EAAK,IAAI;EAAK,IAAI;CAAG;CACtD,IAAI,MAAM,OAAO,IAAI,MAAM,MAAM;CACjC,MAAM,IAAI,OAAO,IAAI;CACrB,OAAO;AACT"}

package/dist/core/color.d.cts

@@ -0,0 +1,6 @@
+export type RGBA = readonly [r: number, g: number, b: number, a: number];
+/**
+ * Resolve any CSS colour to straight (non-premultiplied) sRGB components in 0–1,
+ * by letting the browser paint it into a 1×1 canvas. Results are cached.
+ */
+export declare function parseColor(color: string | null): RGBA;

package/dist/core/color.d.ts

@@ -0,0 +1,6 @@
+export type RGBA = readonly [r: number, g: number, b: number, a: number];
+/**
+ * Resolve any CSS colour to straight (non-premultiplied) sRGB components in 0–1,
+ * by letting the browser paint it into a 1×1 canvas. Results are cached.
+ */
+export declare function parseColor(color: string | null): RGBA;

package/dist/core/color.js

@@ -0,0 +1,46 @@
+// src/core/color.ts
+var TRANSPARENT = [
+	0,
+	0,
+	0,
+	0
+];
+var probe = null;
+var cache = /* @__PURE__ */ new Map();
+/**
+* Resolve any CSS colour to straight (non-premultiplied) sRGB components in 0–1,
+* by letting the browser paint it into a 1×1 canvas. Results are cached.
+*/
+function parseColor(color) {
+	if (!color || color === "transparent") return TRANSPARENT;
+	const cached = cache.get(color);
+	if (cached) return cached;
+	if (!probe) {
+		const canvas = document.createElement("canvas");
+		canvas.width = canvas.height = 1;
+		probe = canvas.getContext("2d", { willReadFrequently: true });
+		if (!probe) return [
+			0,
+			0,
+			0,
+			1
+		];
+	}
+	probe.clearRect(0, 0, 1, 1);
+	probe.fillStyle = "#000";
+	probe.fillStyle = color;
+	probe.fillRect(0, 0, 1, 1);
+	const [r, g, b, a] = probe.getImageData(0, 0, 1, 1).data;
+	const rgba = [
+		r / 255,
+		g / 255,
+		b / 255,
+		a / 255
+	];
+	if (cache.size > 64) cache.clear();
+	cache.set(color, rgba);
+	return rgba;
+}
+export { parseColor };
+
+//# sourceMappingURL=color.js.map

package/dist/core/color.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.js","names":[],"sources":["../../src/core/color.ts"],"sourcesContent":["export type RGBA = readonly [r: number, g: number, b: number, a: number];\n\nconst TRANSPARENT: RGBA = [0, 0, 0, 0];\n\nlet probe: CanvasRenderingContext2D | null = null;\nconst cache = new Map<string, RGBA>();\n\n/**\n * Resolve any CSS colour to straight (non-premultiplied) sRGB components in 0–1,\n * by letting the browser paint it into a 1×1 canvas. Results are cached.\n */\nexport function parseColor(color: string | null): RGBA {\n  if (!color || color === 'transparent') return TRANSPARENT;\n  const cached = cache.get(color);\n  if (cached) return cached;\n\n  if (!probe) {\n    const canvas = document.createElement('canvas');\n    canvas.width = canvas.height = 1;\n    probe = canvas.getContext('2d', { willReadFrequently: true });\n    if (!probe) return [0, 0, 0, 1];\n  }\n  probe.clearRect(0, 0, 1, 1);\n  // An invalid colour leaves fillStyle unchanged, so it falls back to black.\n  probe.fillStyle = '#000';\n  probe.fillStyle = color;\n  probe.fillRect(0, 0, 1, 1);\n  const [r, g, b, a] = probe.getImageData(0, 0, 1, 1).data;\n  const rgba: RGBA = [r / 255, g / 255, b / 255, a / 255];\n  if (cache.size > 64) cache.clear();\n  cache.set(color, rgba);\n  return rgba;\n}\n"],"mappings":";AAEA,IAAM,cAAoB;CAAC;CAAG;CAAG;CAAG;AAAC;AAErC,IAAI,QAAyC;AAC7C,IAAM,wBAAQ,IAAI,IAAkB;;;;;AAMpC,SAAgB,WAAW,OAA4B;CACrD,IAAI,CAAC,SAAS,UAAU,eAAe,OAAO;CAC9C,MAAM,SAAS,MAAM,IAAI,KAAK;CAC9B,IAAI,QAAQ,OAAO;CAEnB,IAAI,CAAC,OAAO;EACV,MAAM,SAAS,SAAS,cAAc,QAAQ;EAC9C,OAAO,QAAQ,OAAO,SAAS;EAC/B,QAAQ,OAAO,WAAW,MAAM,EAAE,oBAAoB,KAAK,CAAC;EAC5D,IAAI,CAAC,OAAO,OAAO;GAAC;GAAG;GAAG;GAAG;EAAC;CAChC;CACA,MAAM,UAAU,GAAG,GAAG,GAAG,CAAC;CAE1B,MAAM,YAAY;CAClB,MAAM,YAAY;CAClB,MAAM,SAAS,GAAG,GAAG,GAAG,CAAC;CACzB,MAAM,CAAC,GAAG,GAAG,GAAG,KAAK,MAAM,aAAa,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC;CACpD,MAAM,OAAa;EAAC,IAAI;EAAK,IAAI;EAAK,IAAI;EAAK,IAAI;CAAG;CACtD,IAAI,MAAM,OAAO,IAAI,MAAM,MAAM;CACjC,MAAM,IAAI,OAAO,IAAI;CACrB,OAAO;AACT"}