@esportsplus/ui 0.56.4 → 0.57.0

package/src/components/surface-field/index.ts

@@ -1,13 +1,31 @@
 import { component, html, type Attributes } from '@esportsplus/template';
+import { effect, read as get, signal, untrack, write } from '@esportsplus/reactivity';
+import { pool } from '@esportsplus/workers';
+import { observer, type Observer } from '~/shared/resize';
+import { observeIntersection } from '~/shared/visible';
+import engine, { scheduler, type Camera, type Link as Path, type Rgb, type Settings, type Shape } from './engine';
+import surface from './surface';
+import type { Actions, Call, Field } from './worker';
 import './scss/index.scss';
 
 
-// Maps world space onto the field: screen = world * zoom + (x, y). Read every frame, so mutating the same object pans
-// and zooms the grid without a re-render.
-type Camera = { x: number, y: number, zoom: number };
+// A channel through the field between two surfaces: the dots lift into a lit vein and the lattice parts round it.
+type Link = {
+    // Surface names (`name` on a surface, or the value of `data-surface-field`) at either end.
+    from?: string;
+    // `loop` sends a crest from `from` to `to`, `bounce` sends it back and forth.
+    motion?: 'bounce' | 'loop' | 'still';
+    // The path itself, in field px (world units when a camera is set); wins over the curve between `from` and `to`.
+    points?: { x: number, y: number }[];
+    // Crest speed in px per second.
+    speed?: number;
+    to?: string;
+    // Width of the lit vein in px.
+    width?: number;
+};
 
 type Options = {
-    // Colour the lit dots and lines drift toward, blended in by `tint`.
+    // Colour the lit dots and lines drift toward, blended in by `tint`; defaults to the `--accent` custom property.
     accent?: string;
     // Resting opacity of an unlit dot.
     base?: number;
@@ -15,21 +33,25 @@ type Options = {
     breathe?: number;
     // 0 – 1: peak opacity the light lifts lines to; dots rise proportionally higher.
     brightness?: number;
-    // Anchors the grid to a pannable, zoomable world (for example a node editor's viewport) instead of centring it.
+    // Anchors the grid to a pannable, zoomable world (for example a node editor's viewport) instead of centring it. It
+    // pans with the world and scales less than it, as a floor below the content.
     camera?: Camera | null;
     // Draw grid lines between neighbouring dots where the light reaches.
     connected?: boolean;
-    // Distance between dots in px (world units when a camera is set).
+    // Distance between dots in px.
     gap?: number;
     // Radius of the pointer light's line reach in px.
     lineRadius?: number;
+    links?: Link[] | null;
     // How far dots under the pointer are nudged away, in px.
     pointerPush?: number;
     // Radius of the pointer light in px.
     radius?: number;
-    // How far a click's ripple displaces the dots it passes, in px.
+    // Each new value sends a ring out from that point, in field px.
+    ripple?: { x: number, y: number } | null;
+    // How far a ring displaces the dots it passes, in px.
     ripplePush?: number;
-    // Render a static texture: no pointer light, ripples, breathing or wandering.
+    // Render a static texture: no pointer light, rings, breathing, wandering or moving links.
     still?: boolean;
     // Widens (positive) or narrows (negative) the empty band around each surface, in px.
     surfacePadding?: number;
@@ -39,32 +61,14 @@ type Options = {
     wander?: boolean;
 };
 
-type Rect = { bottom: number, left: number, right: number, top: number };
-
-type Ripple = { born: number, x: number, y: number };
+type Style = { ellipse: boolean, radius: number, rotation: number };
 
-type Geometry = { height: number, width: number, x: number, y: number };
-
-type Surface = Attributes & {
-    // Keep the surface inside its parent. Turn off for surfaces in an unbounded world such as a pannable canvas.
-    bounded?: boolean;
-    height?: number;
-    // Names the surface in its move and resize controls' accessible labels.
-    label?: string;
-    minHeight?: number;
-    minWidth?: number;
-    // Seeds the geometry and receives every move and resize, so edges or a minimap can follow the surface.
-    state?: Geometry;
-    width?: number;
-    x?: number;
-    y?: number;
-};
 
+const ANGLE = /(-?[\d.]+)(deg|grad|rad|turn)\s*$/;
 
-const ALPHA_LEVELS = 32;
 
 const DEFAULTS: Required<Options> = {
-    accent: '#6683e8',
+    accent: '',
     base: 0.14,
     breathe: 0,
     brightness: 0.2,
@@ -72,8 +76,10 @@ const DEFAULTS: Required<Options> = {
     connected: true,
     gap: 22,
     lineRadius: 200,
+    links: null,
     pointerPush: 2,
     radius: 250,
+    ripple: null,
     ripplePush: 6,
     still: false,
     surfacePadding: 0,
@@ -81,49 +87,58 @@ const DEFAULTS: Required<Options> = {
     wander: false
 };
 
-// Pointer absence, in ms, before a wandering light takes over.
-const IDLE = 1500;
-
 const KEYS = Object.keys(DEFAULTS) as (keyof Options)[];
 
-// Share of a surface's halo added to the light around it.
-const HALO = 0.75;
-
-const RIPPLE_LIFE = 1.4;
-
-const RIPPLE_SPEED = 520;
-
-const RIPPLE_WIDTH = 36;
+// Kept in step with the engine's methods by `satisfies`; `dispose` and `flush` are the proxy's own.
+const METHODS = [
+    'camera',
+    'cancel',
+    'configure',
+    'links',
+    'pointer',
+    'press',
+    'recolor',
+    'release',
+    'resize',
+    'ripple',
+    'surfaces',
+    'visible'
+] as const satisfies (keyof Field)[];
 
 // Elements the field clears a space around and lights up.
 const SELECTOR = '.surface-field-surface, [data-surface-field]';
 
-const TAU = Math.PI * 2;
-
-const TINT_LEVELS = 5;
-
+const SETTINGS: (keyof Settings)[] = [
+    'base',
+    'breathe',
+    'brightness',
+    'connected',
+    'gap',
+    'lineRadius',
+    'pointerPush',
+    'radius',
+    'ripplePush',
+    'still',
+    'surfacePadding',
+    'tint',
+    'wander'
+];
 
-let colors = new Map<string, [number, number, number]>(),
-    probe: CanvasRenderingContext2D | null = null,
-    z = 1;
+const UNITS: Record<string, number> = { deg: 1, grad: 0.9, rad: 180 / Math.PI, turn: 360 };
 
 
-function clamp(value: number, min: number, max: number) {
-    return Math.min(max, Math.max(min, value));
-}
+let colors = new Map<string, Rgb>(),
+    probe: CanvasRenderingContext2D | null = null;
 
-function falloff(distance: number, radius: number) {
-    if (radius <= 0 || distance >= radius) {
-        return 0;
-    }
 
-    let t = distance / radius;
+function angle(value: string) {
+    let match = ANGLE.exec(value);
 
-    return (1 - t * t) * (1 - t * t);
+    return match ? parseFloat(match[1]) * UNITS[match[2]] : 0;
 }
 
 // Resolves any CSS colour (oklch, named, hex…) to rgb by painting it once.
-function rgb(color: string) {
+function rgb(color: string): Rgb {
     let cached = colors.get(color);
 
     if (cached) {
@@ -137,7 +152,7 @@ function rgb(color: string) {
     probe.fillRect(0, 0, 1, 1);
 
     let data = probe.getImageData(0, 0, 1, 1).data,
-        value: [number, number, number] = [data[0], data[1], data[2]];
+        value: Rgb = [data[0], data[1], data[2]];
 
     if (colors.size > 64) {
         colors.clear();
@@ -148,669 +163,620 @@ function rgb(color: string) {
     return value;
 }
 
+function same(a: Shape[], b: Shape[]) {
+    if (a.length !== b.length) {
+        return false;
+    }
 
-const surface = component<Surface>(
-    function(this, { bounded = true, height = 160, label = 'surface', minHeight = 72, minWidth = 120, state, width = 240, x = 0, y = 0, ...attributes }, content) {
-        let element: HTMLElement | undefined,
-            start: { h: number, pointerX: number, pointerY: number, scale: number, w: number, x: number, y: number } | null = null;
+    for (let i = 0, n = a.length; i < n; i++) {
+        let x = a[i],
+            y = b[i];
 
-        if (state) {
-            ({ height, width, x, y } = state);
+        if (
+            x.active !== y.active || x.ellipse !== y.ellipse || x.height !== y.height || x.id !== y.id
+            || x.radius !== y.radius || x.rotation !== y.rotation || x.width !== y.width || x.x !== y.x || x.y !== y.y
+        ) {
+            return false;
         }
+    }
 
-        // Written straight to the element: the field reads this geometry every frame, so a reactive binding would
-        // leave the grid a frame behind the drag.
-        function apply() {
-            if (!element) {
-                return;
-            }
-
-            let parent = element.parentElement;
+    return true;
+}
 
-            width = Math.max(minWidth, width);
-            height = Math.max(minHeight, height);
+// Corner radius and turn from the element's own styles, so the clearing matches the corners and rotation drawn.
+function style(element: Element): Style {
+    let computed = getComputedStyle(element),
+        corner = computed.borderTopLeftRadius,
+        rotation = computed.rotate && computed.rotate !== 'none' ? angle(computed.rotate) : 0,
+        transform = computed.transform;
 
-            if (bounded && parent) {
-                let pw = parent.clientWidth,
-                    ph = parent.clientHeight;
+    if (transform && transform !== 'none') {
+        let m = transform.slice(transform.indexOf('(') + 1, -1).split(',');
 
-                width = clamp(width, minWidth, Math.max(minWidth, pw));
-                height = clamp(height, minHeight, Math.max(minHeight, ph));
-                x = clamp(x, 0, Math.max(0, pw - width));
-                y = clamp(y, 0, Math.max(0, ph - height));
-            }
+        rotation += Math.atan2(parseFloat(m[1]), parseFloat(m[0])) * 180 / Math.PI;
+    }
 
-            element.style.height = `${height}px`;
-            element.style.translate = `${x}px ${y}px`;
-            element.style.width = `${width}px`;
+    if (corner.endsWith('%')) {
+        let percent = parseFloat(corner);
 
-            if (state && (state.height !== height || state.width !== width || state.x !== x || state.y !== y)) {
-                state.height = height;
-                state.width = width;
-                state.x = x;
-                state.y = y;
-            }
+        if (percent >= 50) {
+            return { ellipse: true, radius: 0, rotation };
         }
 
-        function begin(event: PointerEvent) {
-            if (event.button !== 0 || !element) {
-                return;
+        let { height, width } = element.getBoundingClientRect();
+
+        return { ellipse: false, radius: Math.min(width, height) * percent / 100, rotation };
+    }
+
+    return { ellipse: false, radius: parseFloat(corner) || 0, rotation };
+}
+
+
+export default component(
+    function(this, attributes: Attributes & Options & { state?: Options, worker?: string }, content) {
+        let given: Options = {},
+            rest: Attributes = {},
+            state = attributes.state,
+            url = attributes.worker;
+
+        for (let key in attributes) {
+            if (key === 'state' || key === 'worker') {
+                continue;
             }
 
-            (event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);
-            element.classList.add('--active');
-            element.style.zIndex = String(++z);
-            // Inside a zoomed world the pointer travels in screen px; dividing by the rendered scale keeps the surface
-            // under the cursor.
-            start = {
-                h: height,
-                pointerX: event.clientX,
-                pointerY: event.clientY,
-                scale: element.getBoundingClientRect().width / element.offsetWidth || 1,
-                w: width,
-                x,
-                y
-            };
+            if ((KEYS as string[]).includes(key)) {
+                (given as Record<string, unknown>)[key] = attributes[key];
+            }
+            else {
+                rest[key] = attributes[key];
+            }
         }
 
-        function end() {
-            element?.classList.remove('--active');
-            start = null;
+        let bounds: DOMRect | null = null,
+            canvas: HTMLCanvasElement | undefined,
+            elements: Element[] | null = null,
+            field: Field | null = null,
+            // Bumped when the worker fails, so the template renders a fresh canvas the page can draw on again.
+            generation = signal(0),
+            host: HTMLElement | undefined,
+            last = { accent: '', camera: null as Camera | null, color: '', shapes: [] as Shape[], size: '' },
+            // Ends everything a connection listens to and observes, presses still held included.
+            listening: AbortController | undefined,
+            measuring = 0,
+            relink = true,
+            resizer: Observer | undefined,
+            running = 0,
+            settle = 0,
+            shown = true,
+            styles = new WeakMap<Element, Style>();
+
+        function box() {
+            return bounds ??= host!.getBoundingClientRect();
         }
 
-        function nudge(event: KeyboardEvent, resize: boolean) {
-            let step = event.shiftKey ? 32 : 8,
-                dx = event.key === 'ArrowLeft' ? -step : event.key === 'ArrowRight' ? step : 0,
-                dy = event.key === 'ArrowUp' ? -step : event.key === 'ArrowDown' ? step : 0;
+        function collect() {
+            elements = Array.from(host!.querySelectorAll(SELECTOR));
+            resizer?.disconnect();
+            resizer?.observe(host!);
 
-            if (!dx && !dy) {
-                return;
+            for (let i = 0, n = elements.length; i < n; i++) {
+                resizer?.observe(elements[i]);
             }
 
-            event.preventDefault();
+            return elements;
+        }
+
+        function curve(a: Shape | undefined, b: Shape | undefined) {
+            let points: number[] = [];
 
-            if (resize) {
-                width += dx;
-                height += dy;
+            if (!a || !b) {
+                return points;
             }
-            else {
-                x += dx;
-                y += dy;
+
+            // Leaves and arrives along the dominant axis, the way a connector between two cards does.
+            let dx = b.x - a.x,
+                dy = b.y - a.y,
+                across = Math.abs(dx) >= Math.abs(dy),
+                c1x = across ? a.x + dx / 2 : a.x,
+                c1y = across ? a.y : a.y + dy / 2,
+                c2x = across ? b.x - dx / 2 : b.x,
+                c2y = across ? b.y : b.y - dy / 2;
+
+            for (let i = 0; i <= 32; i++) {
+                let t = i / 32,
+                    u = 1 - t;
+
+                points.push(
+                    u * u * u * a.x + 3 * u * u * t * c1x + 3 * u * t * t * c2x + t * t * t * b.x,
+                    u * u * u * a.y + 3 * u * u * t * c1y + 3 * u * t * t * c2y + t * t * t * b.y
+                );
             }
 
-            apply();
+            return points;
         }
 
-        return html`
-            <div
-                class='surface-field-surface'
-                ${this?.attributes}
-                ${attributes}
-                ${{
-                    onconnect: (el: HTMLElement) => {
-                        element = el;
-                        apply();
-                    }
-                }}
-            >
-                <button
-                    aria-label='${`Move ${label} surface with arrow keys`}'
-                    class='surface-field-surface-handle'
-                    type='button'
-                    ${{
-                        onkeydown: (event: KeyboardEvent) => nudge(event, false),
-                        onlostpointercapture: end,
-                        onpointerdown: begin,
-                        onpointermove: (event: PointerEvent) => {
-                            if (!start) {
-                                return;
-                            }
+        function measure() {
+            measuring = 0;
 
-                            x = start.x + (event.clientX - start.pointerX) / start.scale;
-                            y = start.y + (event.clientY - start.pointerY) / start.scale;
-                            apply();
-                        }
-                    }}
-                ></button>
-                <div class='surface-field-surface-content'>${content}</div>
-                <button
-                    aria-label='${`Resize ${label} surface with arrow keys; right and down make it larger`}'
-                    class='surface-field-surface-resize'
-                    type='button'
-                    ${{
-                        onkeydown: (event: KeyboardEvent) => nudge(event, true),
-                        onlostpointercapture: end,
-                        onpointerdown: begin,
-                        onpointermove: (event: PointerEvent) => {
-                            if (!start) {
-                                return;
-                            }
+            if (!host || !field) {
+                return;
+            }
 
-                            width = start.w + (event.clientX - start.pointerX) / start.scale;
-                            height = start.h + (event.clientY - start.pointerY) / start.scale;
-                            apply();
-                        }
-                    }}
-                ></button>
-            </div>
-        `;
-    }
-);
+            let changed = false,
+                height = host.clientHeight,
+                width = host.clientWidth,
+                dpr = Math.min(2, devicePixelRatio || 1),
+                size = `${width} ${height} ${dpr}`;
 
+            bounds = host.getBoundingClientRect();
 
-export default Object.assign(
-    component<Attributes & Options & { state?: Options }>(
-        function(this, attributes, content) {
-            let given: Options = {},
-                rest: Attributes = {},
-                state = attributes.state;
+            if (size !== last.size) {
+                changed = true;
+                field.resize(width, height, dpr);
+                last.size = size;
+            }
 
-            for (let key in attributes) {
-                if (key === 'state') {
-                    continue;
-                }
+            let list = elements ?? collect(),
+                shapes: Shape[] = [];
 
-                if ((KEYS as string[]).includes(key)) {
-                    (given as Record<string, unknown>)[key] = attributes[key];
-                }
-                else {
-                    rest[key] = attributes[key];
-                }
-            }
+            for (let i = 0, n = list.length; i < n; i++) {
+                let element = list[i],
+                    r = element.getBoundingClientRect();
 
-            let canvas: HTMLCanvasElement | undefined,
-                context: CanvasRenderingContext2D | null = null,
-                frame = 0,
-                host: HTMLElement | undefined,
-                key = '',
-                last = 0,
-                light = { intensity: 0, x: 0, y: 0 },
-                reduced = matchMedia('(prefers-reduced-motion: reduce)'),
-                observer: IntersectionObserver | undefined,
-                pointer = { at: -Infinity, inside: false, x: 0, y: 0 },
-                ripples: Ripple[] = [],
-                size = { dpr: 0, height: 0, width: 0 },
-                visible = false;
-
-            // Grid buffers, regrown only when the dot count rises.
-            let bucket = new Uint16Array(0),
-                dotAlpha = new Float32Array(0),
-                dotLight = new Float32Array(0),
-                lineLight = new Float32Array(0),
-                order = new Uint32Array(0),
-                px = new Float32Array(0),
-                py = new Float32Array(0),
-                segment = new Uint32Array(0),
-                segmentBucket = new Uint16Array(0),
-                segmentOrder = new Uint32Array(0),
-                seed = new Float32Array(0);
-
-            function options() {
-                let snapshot = {} as Required<Options>;
-
-                for (let i = 0, n = KEYS.length; i < n; i++) {
-                    let k = KEYS[i];
-
-                    (snapshot as Record<string, unknown>)[k] = state?.[k] ?? given[k] ?? DEFAULTS[k];
+                if (!r.width || !r.height) {
+                    continue;
                 }
 
-                // Copied so the frame works from (and compares against) the values of this moment, not a live object.
-                let camera = snapshot.camera;
+                let s = styles.get(element);
 
-                if (camera) {
-                    snapshot.camera = { x: camera.x, y: camera.y, zoom: camera.zoom };
+                if (!s) {
+                    s = style(element);
+                    styles.set(element, s);
                 }
 
-                return snapshot;
+                // Layout size is the box before any transform; the rendered box tells how far it has been scaled.
+                let turn = s.rotation * Math.PI / 180,
+                    cos = Math.abs(Math.cos(turn)),
+                    sin = Math.abs(Math.sin(turn)),
+                    w = (element as HTMLElement).offsetWidth || r.width,
+                    h = (element as HTMLElement).offsetHeight || r.height,
+                    scale = r.width / (w * cos + h * sin) || 1;
+
+                shapes.push({
+                    active: element.classList.contains('--active'),
+                    ellipse: s.ellipse,
+                    height: h * scale,
+                    id: element.getAttribute('data-surface-field') ?? '',
+                    radius: s.radius * scale,
+                    rotation: s.rotation,
+                    width: w * scale,
+                    x: r.left - bounds.left + r.width / 2,
+                    y: r.top - bounds.top + r.height / 2
+                });
             }
 
-            function grow(n: number) {
-                if (px.length >= n) {
-                    return;
-                }
-
-                bucket = new Uint16Array(n);
-                dotAlpha = new Float32Array(n);
-                dotLight = new Float32Array(n);
-                lineLight = new Float32Array(n);
-                order = new Uint32Array(n);
-                px = new Float32Array(n);
-                py = new Float32Array(n);
-                segment = new Uint32Array(n * 4);
-                segmentBucket = new Uint16Array(n * 2);
-                segmentOrder = new Uint32Array(n * 2);
-                seed = new Float32Array(n);
+            if (!same(shapes, last.shapes)) {
+                changed = relink = true;
+                field.surfaces(shapes);
+                last.shapes = shapes;
             }
 
-            function start() {
-                if (!frame && visible && host?.isConnected) {
-                    last = performance.now();
-                    frame = requestAnimationFrame(tick);
+            let camera = read('camera');
+
+            if (camera) {
+                if (!last.camera || last.camera.x !== camera.x || last.camera.y !== camera.y || last.camera.zoom !== camera.zoom) {
+                    changed = relink = true;
+                    last.camera = { x: camera.x, y: camera.y, zoom: camera.zoom };
+                    field.camera(last.camera);
                 }
             }
-
-            function stop() {
-                cancelAnimationFrame(frame);
-                frame = 0;
+            else if (last.camera) {
+                changed = relink = true;
+                last.camera = null;
+                field.camera(null);
             }
 
-            function tick(now: number) {
-                frame = requestAnimationFrame(tick);
+            if (relink) {
+                relink = false;
+                field.links(paths());
+            }
 
-                if (!host || !canvas || !context) {
-                    return;
-                }
+            field.flush();
 
-                let dt = Math.min(64, now - last) / 1000,
-                    o = options(),
-                    width = host.clientWidth,
-                    height = host.clientHeight,
-                    dpr = Math.min(2, devicePixelRatio || 1);
+            // Keeps following for a frame after the last change, and for as long as a transition or animation runs.
+            if (changed || running > 0) {
+                settle = 0;
+                schedule();
+            }
+            else if (++settle < 2) {
+                schedule();
+            }
+        }
 
-                last = now;
+        function paths() {
+            let links = read('links'),
+                camera = last.camera,
+                named: Map<string, Shape> | undefined,
+                result: Path[] = [];
 
-                if (width !== size.width || height !== size.height || dpr !== size.dpr) {
-                    canvas.height = Math.max(1, Math.round(height * dpr));
-                    canvas.width = Math.max(1, Math.round(width * dpr));
-                    size = { dpr, height, width };
-                    key = '';
-                }
+            if (!links) {
+                return result;
+            }
 
-                // Surface geometry is read fresh each frame so a drag, a resize or a layout shift is followed at once.
-                let bounds = host.getBoundingClientRect(),
-                    elements = host.querySelectorAll(SELECTOR),
-                    rects: Rect[] = [];
+            for (let i = 0, n = links.length; i < n; i++) {
+                let link = links[i],
+                    points: number[] = [];
 
-                for (let i = 0, n = elements.length; i < n; i++) {
-                    let r = elements[i].getBoundingClientRect();
+                if (link.points && link.points.length >= 2) {
+                    for (let j = 0, m = link.points.length; j < m; j++) {
+                        let p = link.points[j];
 
-                    if (r.width && r.height) {
-                        rects.push({
-                            bottom: r.bottom - bounds.top,
-                            left: r.left - bounds.left,
-                            right: r.right - bounds.left,
-                            top: r.top - bounds.top
-                        });
+                        points.push(
+                            camera ? p.x * camera.zoom + camera.x : p.x,
+                            camera ? p.y * camera.zoom + camera.y : p.y
+                        );
                     }
                 }
+                else {
+                    if (!named) {
+                        named = new Map();
 
-                let animate = !o.still && !reduced.matches,
-                    intensity = 0,
-                    target = { x: light.x, y: light.y },
-                    wandering = false;
+                        for (let j = 0, m = last.shapes.length; j < m; j++) {
+                            let shape = last.shapes[j];
 
-                if (animate && pointer.inside) {
-                    intensity = 1;
-                    target = { x: pointer.x, y: pointer.y };
-                }
-                else if (animate && o.wander && now - pointer.at > IDLE) {
-                    let t = now / 1000;
-
-                    intensity = 0.85;
-                    target = {
-                        x: width / 2 + Math.cos(t * 0.23) * width * 0.34 + Math.sin(t * 0.57) * width * 0.08,
-                        y: height / 2 + Math.sin(t * 0.31) * height * 0.3 + Math.cos(t * 0.49) * height * 0.08
-                    };
-                    wandering = true;
+                            if (shape.id && !named.has(shape.id)) {
+                                named.set(shape.id, shape);
+                            }
+                        }
+                    }
+
+                    points = curve(named.get(link.from ?? ''), named.get(link.to ?? ''));
                 }
 
-                // A light fading in from nothing starts where it is aimed rather than sweeping across from its last spot.
-                if (light.intensity < 0.01 && intensity > 0) {
-                    light.x = target.x;
-                    light.y = target.y;
+                if (points.length >= 4) {
+                    result.push({ motion: link.motion ?? 'still', points, speed: link.speed ?? 0, width: link.width ?? 0 });
                 }
+            }
 
-                let follow = 1 - Math.exp(-dt * (wandering ? 2.5 : 16)),
-                    fade = 1 - Math.exp(-dt * 6);
+            return result;
+        }
 
-                light.intensity += (intensity - light.intensity) * fade;
-                light.x += (target.x - light.x) * follow;
-                light.y += (target.y - light.y) * follow;
+        function page() {
+            shown = !document.hidden;
+            field?.visible(shown);
+        }
 
-                if (!animate) {
-                    light.intensity = 0;
-                    ripples.length = 0;
-                }
-                else if (ripples.length) {
-                    ripples = ripples.filter((ripple) => (now - ripple.born) / 1000 < RIPPLE_LIFE);
-                }
+        function read<K extends keyof Options>(key: K): Required<Options>[K] {
+            return (state?.[key] ?? given[key] ?? DEFAULTS[key]) as Required<Options>[K];
+        }
 
-                let color = getComputedStyle(canvas).color,
-                    settled = Math.abs(intensity - light.intensity) < 0.002
-                        && (light.intensity < 0.002 || (Math.abs(target.x - light.x) < 0.1 && Math.abs(target.y - light.y) < 0.1)),
-                    signature = JSON.stringify([o, color, rects, pointer.inside && animate ? [pointer.x, pointer.y] : 0]);
+        function recolor() {
+            if (!canvas || !field) {
+                return;
+            }
 
-                // Nothing moving and nothing changed: the previous frame still stands.
-                if (settled && !wandering && !ripples.length && !(animate && o.breathe > 0) && signature === key) {
-                    return;
-                }
+            let computed = getComputedStyle(canvas),
+                accent = read('accent') || computed.accentColor,
+                color = computed.color;
 
-                key = signature;
-                draw(o, rects, color, animate ? now : 0, animate);
+            if (accent === last.accent && color === last.color) {
+                return;
             }
 
-            function draw(o: Required<Options>, rects: Rect[], color: string, now: number, animate: boolean) {
-                let ctx = context!,
-                    { dpr, height, width } = size,
-                    camera = o.camera,
-                    gap = Math.max(6, o.gap) * (camera ? Math.max(0.01, camera.zoom) : 1),
-                    zoom = camera ? Math.max(0.01, camera.zoom) : 1;
+            last.accent = accent;
+            last.color = color;
+            field.recolor(rgb(color), rgb(accent));
+        }
 
-                // Zoomed far out, every other row and column drops so the dots never crowd into a grey wash.
-                while (gap < 8) {
-                    gap *= 2;
+        // Draws off the main thread: the canvas goes to a worker, and every call is queued and posted once per task.
+        function remote(element: HTMLCanvasElement, script: string): Field {
+            let calls: Call[] = [],
+                channel = new MessageChannel(),
+                queued = false,
+                workers = pool<Actions>(script, { limit: 1 }),
+                task = workers().attach(element.transferControlToOffscreen(), channel.port2),
+                proxy = {} as Record<keyof Field, unknown> as Field;
+
+            function flush() {
+                queued = false;
+
+                if (calls.length) {
+                    channel.port1.postMessage(calls);
+                    calls = [];
                 }
+            }
 
-                let cols = Math.floor(width / gap) + 2,
-                    rows = Math.floor(height / gap) + 2,
-                    n = cols * rows,
-                    // World index of the first column and row, so a dot keeps its identity (and its breathing phase)
-                    // while the camera pans.
-                    i0 = camera ? Math.floor(-camera.x / gap) : 0,
-                    j0 = camera ? Math.floor(-camera.y / gap) : 0,
-                    ox = camera ? camera.x + i0 * gap : (width - (cols - 1) * gap) / 2,
-                    oy = camera ? camera.y + j0 * gap : (height - (rows - 1) * gap) / 2,
-                    padding = o.surfacePadding * zoom,
-                    clear = Math.max(2, gap * 0.8 + padding),
-                    band = Math.max(clear + gap, gap * 3 + padding),
-                    halo = band + gap * 1.5,
-                    push = Math.min(o.radius, gap * 5),
-                    peak = Math.min(1, o.brightness * 2.5),
-                    time = now / 1000;
-
-                grow(n);
-
-                for (let j = 0; j < rows; j++) {
-                    for (let i = 0; i < cols; i++) {
-                        let k = j * cols + i,
-                            x = ox + i * gap,
-                            y = oy + j * gap,
-                            glow = 0,
-                            shown = 1;
-
-                        seed[k] = ((Math.sin((i + i0) * 12.9898 + (j + j0) * 78.233) * 43758.5453) % 1 + 1) % 1;
-
-                        // Each surface clears the dots it covers and squeezes the band around it outward, so the grid
-                        // bends around the surface's edge and rounds off at its corners.
-                        for (let r = 0, m = rects.length; r < m; r++) {
-                            let rect = rects[r],
-                                cx = clamp(x, rect.left, rect.right),
-                                cy = clamp(y, rect.top, rect.bottom),
-                                dx = x - cx,
-                                dy = y - cy,
-                                d = Math.sqrt(dx * dx + dy * dy);
-
-                            if (d === 0) {
-                                shown = 0;
-                                break;
-                            }
+            for (let i = 0, n = METHODS.length; i < n; i++) {
+                let name = METHODS[i];
 
-                            if (d < halo) {
-                                glow = Math.max(glow, 1 - d / halo);
-                            }
+                (proxy as Record<string, unknown>)[name] = (...args: unknown[]) => {
+                    calls.push([name, args]);
 
-                            if (d < band) {
-                                let scale = (clear + d * (band - clear) / band) / d;
+                    if (!queued) {
+                        queued = true;
+                        queueMicrotask(flush);
+                    }
+                };
+            }
 
-                                x = cx + dx * scale;
-                                y = cy + dy * scale;
-                            }
-                        }
+            proxy.dispose = () => {
+                flush();
+                task.dispatch('release');
+                channel.port1.close();
+                void workers.shutdown();
+            };
+            proxy.flush = flush;
 
-                        let dot = glow * glow * HALO,
-                            line = dot;
+            // A worker that fails to start or dies hands the drawing back to the page, on a fresh canvas since the
+            // old one now belongs to the worker; the fresh canvas starts the engine once it connects.
+            task.catch(() => {
+                if (field !== proxy) {
+                    return;
+                }
 
-                        if (shown && light.intensity > 0.001) {
-                            let dx = x - light.x,
-                                dy = y - light.y,
-                                d = Math.sqrt(dx * dx + dy * dy);
+                channel.port1.close();
+                void workers.shutdown();
+                field = null;
+                write(generation, generation.value + 1);
+            });
 
-                            dot += falloff(d, o.radius) * light.intensity;
-                            line += falloff(d, o.lineRadius) * light.intensity;
+            return proxy;
+        }
 
-                            if (pointer.inside && o.pointerPush && d > 0.001 && d < push) {
-                                let s = o.pointerPush * (1 - d / push) * (1 - d / push) * light.intensity / d;
+        function schedule() {
+            if (!measuring && host) {
+                measuring = requestAnimationFrame(measure);
+            }
+        }
 
-                                x += dx * s;
-                                y += dy * s;
-                            }
-                        }
+        function settings() {
+            let snapshot = {} as Settings;
 
-                        for (let r = 0, m = shown ? ripples.length : 0; r < m; r++) {
-                            let ripple = ripples[r],
-                                age = (now - ripple.born) / 1000,
-                                dx = x - ripple.x,
-                                dy = y - ripple.y,
-                                d = Math.sqrt(dx * dx + dy * dy),
-                                life = 1 - age / RIPPLE_LIFE,
-                                wave = (d - age * RIPPLE_SPEED) / RIPPLE_WIDTH,
-                                strength = Math.exp(-wave * wave) * life * life;
-
-                            if (d > 0.001) {
-                                x += dx / d * o.ripplePush * strength;
-                                y += dy / d * o.ripplePush * strength;
-                            }
+            for (let i = 0, n = SETTINGS.length; i < n; i++) {
+                let key = SETTINGS[i];
 
-                            dot += strength * 0.8;
-                            line += strength * 0.6;
-                        }
+                (snapshot as Record<string, unknown>)[key] = read(key);
+            }
 
-                        let breath = animate && o.breathe > 0
-                            ? 1 - o.breathe * 0.5 * (1 + Math.sin(time * 1.3 + seed[k] * TAU))
-                            : 1;
+            // Or held still by the CSS, under reduced motion say.
+            snapshot.still ||= !!canvas && parseFloat(getComputedStyle(canvas).getPropertyValue('--still')) > 0;
 
-                        dot = Math.min(1, dot);
-                        px[k] = x;
-                        py[k] = y;
-                        dotLight[k] = dot;
-                        dotAlpha[k] = shown * breath * (o.base + (peak - o.base) * Math.max(0, dot));
-                        lineLight[k] = shown * Math.min(1, line);
-                    }
-                }
+            return snapshot;
+        }
 
-                let accent = rgb(o.accent),
-                    base = rgb(color),
-                    buckets = ALPHA_LEVELS * TINT_LEVELS,
-                    counts = new Uint32Array(buckets + 1),
-                    fills: string[] = [],
-                    tint = clamp(o.tint, 0, 1);
-
-                for (let t = 0; t < TINT_LEVELS; t++) {
-                    let mix = tint * t / (TINT_LEVELS - 1);
-
-                    fills[t] = `rgb(${
-                        Math.round(base[0] + (accent[0] - base[0]) * mix)
-                    } ${
-                        Math.round(base[1] + (accent[1] - base[1]) * mix)
-                    } ${
-                        Math.round(base[2] + (accent[2] - base[2]) * mix)
-                    })`;
-                }
+        // Sends everything a new engine needs, from nothing.
+        function sync() {
+            if (!field) {
+                return;
+            }
 
-                ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
-                ctx.clearRect(0, 0, width, height);
+            last = { accent: '', camera: null, color: '', shapes: [], size: '' };
+            relink = true;
+            field.configure(settings());
+            field.visible(shown);
+            recolor();
+            measure();
+        }
 
-                // Lines and dots are bucketed by opacity and tint so each bucket draws as a single path.
-                if (o.connected) {
-                    let segments = 0;
+        function viewport() {
+            bounds = null;
+            schedule();
+        }
 
-                    for (let j = 0; j < rows; j++) {
-                        for (let i = 0; i < cols; i++) {
-                            let k = j * cols + i;
+        effect(() => {
+            let next = settings();
 
-                            for (let neighbour of [i + 1 < cols ? k + 1 : -1, j + 1 < rows ? k + cols : -1]) {
-                                if (neighbour < 0) {
-                                    continue;
-                                }
+            untrack(() => field?.configure(next));
+        });
 
-                                let lit = Math.min(lineLight[k], lineLight[neighbour]),
-                                    alpha = Math.round(lit * o.brightness * (ALPHA_LEVELS - 1));
+        effect(() => {
+            read('accent');
+            untrack(recolor);
+        });
 
-                                if (alpha < 1) {
-                                    continue;
-                                }
+        // Read deeply so reactive cameras and links are tracked; the next measure picks up what changed.
+        effect(() => {
+            let camera = read('camera'),
+                links = read('links');
 
-                                segment[segments * 2] = k;
-                                segment[segments * 2 + 1] = neighbour;
-                                segmentBucket[segments] = Math.round(lit * (TINT_LEVELS - 1)) * ALPHA_LEVELS + Math.min(alpha, ALPHA_LEVELS - 1);
-                                counts[segmentBucket[segments] + 1]++;
-                                segments++;
-                            }
-                        }
-                    }
-
-                    sort(counts, segmentBucket, segmentOrder, segments);
-                    ctx.lineWidth = 1;
+            if (camera) {
+                void (camera.x + camera.y + camera.zoom);
+            }
 
-                    for (let b = 0; b < buckets; b++) {
-                        let from = counts[b],
-                            to = counts[b + 1];
+            void JSON.stringify(links);
+            untrack(() => {
+                relink = true;
+                schedule();
+            });
+        });
 
-                        if (from === to) {
-                            continue;
-                        }
+        effect(() => {
+            let ripple = read('ripple');
 
-                        ctx.beginPath();
+            if (ripple) {
+                let { x, y } = ripple;
 
-                        for (let s = from; s < to; s++) {
-                            let a = segment[segmentOrder[s] * 2],
-                                c = segment[segmentOrder[s] * 2 + 1];
+                untrack(() => field?.ripple(x, y));
+            }
+        });
 
-                            ctx.moveTo(px[a], py[a]);
-                            ctx.lineTo(px[c], py[c]);
+        return html`
+            <div
+                class='surface-field'
+                ${this?.attributes}
+                ${rest}
+                ${{
+                    onconnect: (element: HTMLElement) => {
+                        if (!canvas) {
+                            return;
                         }
 
-                        ctx.globalAlpha = (b % ALPHA_LEVELS) / (ALPHA_LEVELS - 1);
-                        ctx.strokeStyle = fills[Math.floor(b / ALPHA_LEVELS)];
-                        ctx.stroke();
-                    }
-
-                    counts.fill(0);
-                }
+                        host = element;
+                        field = url && typeof Worker === 'function' && 'transferControlToOffscreen' in canvas
+                            ? remote(canvas, url)
+                            : engine(canvas, scheduler());
 
-                let dots = 0;
+                        listening = new AbortController();
 
-                for (let k = 0; k < n; k++) {
-                    let alpha = Math.round(dotAlpha[k] * (ALPHA_LEVELS - 1));
-
-                    if (alpha < 1) {
-                        bucket[k] = buckets;
-                        continue;
-                    }
-
-                    bucket[k] = Math.round(dotLight[k] * (TINT_LEVELS - 1)) * ALPHA_LEVELS + Math.min(alpha, ALPHA_LEVELS - 1);
-                    counts[bucket[k] + 1]++;
-                    dots++;
-                }
-
-                sort(counts, bucket, order, n);
-
-                for (let b = 0; b < buckets; b++) {
-                    let from = counts[b],
-                        to = counts[b + 1];
-
-                    if (from === to) {
-                        continue;
-                    }
+                        let done = (event: Event) => {
+                                if (event.type === 'transitionrun' || event.type === 'animationstart') {
+                                    running++;
+                                }
+                                else {
+                                    running = Math.max(0, running - 1);
+                                }
 
-                    let r = 0.85 + 0.45 * Math.floor(b / ALPHA_LEVELS) / (TINT_LEVELS - 1);
+                                schedule();
+                            },
+                            intersection = observeIntersection(element, (entries) => {
+                                shown = entries[entries.length - 1].isIntersecting && !document.hidden;
+                                field?.visible(shown);
+                            }),
+                            // Surfaces are followed through the writes that move them, not by polling layout.
+                            mutation = new MutationObserver((records) => {
+                                for (let i = 0, n = records.length; i < n; i++) {
+                                    let record = records[i];
+
+                                    if (record.type === 'childList' || record.attributeName === 'data-surface-field') {
+                                        elements = null;
+                                    }
+                                    else if (record.target === element) {
+                                        recolor();
+                                    }
+
+                                    styles.delete(record.target as Element);
+                                }
 
-                    ctx.beginPath();
+                                schedule();
+                            }),
+                            signal = listening.signal,
+                            theme = new MutationObserver(() => {
+                                styles = new WeakMap();
+                                recolor();
+                                schedule();
+                            });
 
-                    for (let s = from; s < to; s++) {
-                        let k = order[s];
+                        resizer = observer(() => schedule());
+                        mutation.observe(element, {
+                            attributeFilter: ['class', 'data-surface-field', 'style'],
+                            characterData: true,
+                            childList: true,
+                            subtree: true
+                        });
+                        theme.observe(document.documentElement, { attributes: true });
 
-                        ctx.moveTo(px[k] + r, py[k]);
-                        ctx.arc(px[k], py[k], r, 0, TAU);
-                    }
+                        // Hear every descendant's motion, including events with their own template handler.
+                        for (let type of ['animationcancel', 'animationend', 'animationstart', 'transitioncancel', 'transitionend', 'transitionrun']) {
+                            element.addEventListener(type, done, { signal });
+                        }
 
-                    ctx.globalAlpha = (b % ALPHA_LEVELS) / (ALPHA_LEVELS - 1);
-                    ctx.fillStyle = fills[Math.floor(b / ALPHA_LEVELS)];
-                    ctx.fill();
-                }
+                        element.addEventListener('scroll', viewport, { capture: true, passive: true, signal });
+                        matchMedia('(prefers-color-scheme: dark)').addEventListener('change', recolor, { signal });
+                        window.addEventListener('scroll', () => {
+                            bounds = null;
+                        }, { capture: true, passive: true, signal });
+                        signal.addEventListener('abort', () => {
+                            intersection();
+                            mutation.disconnect();
+                            resizer?.disconnect();
+                            theme.disconnect();
+                        }, { once: true });
+
+                        collect();
+                        sync();
+                    },
+                    ondisconnect: () => {
+                        listening?.abort();
+                        listening = undefined;
+                        cancelAnimationFrame(measuring);
+                        measuring = 0;
+                        field?.dispose();
+                        field = null;
+                        host = undefined;
+                    },
+                    ondocumentvisibilitychange: page,
+                    onpointerdown: (event: PointerEvent) => {
+                        if (!field || !host) {
+                            return;
+                        }
 
-                ctx.globalAlpha = 1;
-            }
+                        let b = box(),
+                            id = event.pointerId,
+                            x = event.clientX - b.left,
+                            y = event.clientY - b.top;
 
-            // Counting sort: `counts` holds per-bucket tallies offset by one and becomes each bucket's start index.
-            function sort(counts: Uint32Array, keys: Uint16Array, into: Uint32Array, n: number) {
-                for (let b = 1, m = counts.length; b < m; b++) {
-                    counts[b] += counts[b - 1];
-                }
+                        field.pointer(id, x, y, true);
 
-                let cursor = counts.slice();
+                        if (event.button !== 0 || (event.target as Element).closest?.(SELECTOR)) {
+                            return;
+                        }
 
-                for (let i = 0; i < n; i++) {
-                    if (keys[i] < counts.length - 1) {
-                        into[cursor[keys[i]]++] = i;
-                    }
-                }
-            }
+                        // The ring holds while pressed, so the release is heard wherever it happens.
+                        let finish = (e: PointerEvent) => {
+                            if (e.pointerId !== id) {
+                                return;
+                            }
 
-            function track(event: PointerEvent) {
-                if (!host) {
-                    return;
-                }
+                            if (e.type === 'pointercancel') {
+                                field?.cancel(id);
+                            }
+                            else {
+                                field?.release(id);
+                            }
 
-                let bounds = host.getBoundingClientRect();
+                            window.removeEventListener('pointercancel', finish);
+                            window.removeEventListener('pointerup', finish);
+                        };
+
+                        field.press(id, x, y);
+                        window.addEventListener('pointercancel', finish, { signal: listening?.signal });
+                        window.addEventListener('pointerup', finish, { signal: listening?.signal });
+                    },
+                    onpointerleave: (event: PointerEvent) => {
+                        field?.pointer(event.pointerId, 0, 0, false);
+                    },
+                    onpointermove: (event: PointerEvent) => {
+                        if (!field || !host) {
+                            return;
+                        }
 
-                pointer.at = performance.now();
-                pointer.inside = true;
-                pointer.x = event.clientX - bounds.left;
-                pointer.y = event.clientY - bounds.top;
-            }
+                        let b = box();
 
-            return html`
-                <div
-                    class='surface-field'
-                    ${this?.attributes}
-                    ${rest}
-                    ${{
-                        onconnect: (element: HTMLElement) => {
-                            host = element;
-                            canvas = element.querySelector('.surface-field-canvas') as HTMLCanvasElement;
-                            context = canvas.getContext('2d');
-                            observer = new IntersectionObserver((entries) => {
-                                visible = entries[entries.length - 1].isIntersecting;
-
-                                if (visible) {
-                                    start();
-                                }
-                                else {
-                                    stop();
+                        field.pointer(event.pointerId, event.clientX - b.left, event.clientY - b.top, true);
+                    },
+                    onwindowresize: viewport
+                }}
+            >
+                ${() => {
+                    get(generation);
+
+                    return html`
+                        <canvas
+                            aria-hidden='true'
+                            class='surface-field-canvas'
+                            ${{
+                                onconnect: (element: HTMLCanvasElement) => {
+                                    canvas = element;
+
+                                    // A replacement after the worker failed; the first canvas is started by the host.
+                                    if (host && !field) {
+                                        field = engine(element, scheduler());
+                                        sync();
+                                    }
+                                },
+                                // Its CSS transitions '--still' alone, so a change to it is heard here.
+                                ontransitionend: (e: TransitionEvent) => {
+                                    if (e.propertyName === '--still') {
+                                        field?.configure(settings());
+                                    }
                                 }
-                            });
-                            observer.observe(element);
-                        },
-                        ondisconnect: () => {
-                            observer?.disconnect();
-                            stop();
-                        },
-                        onpointerdown: (event: PointerEvent) => {
-                            track(event);
-
-                            if (event.button !== 0 || (event.target as Element).closest?.(SELECTOR)) {
-                                return;
-                            }
-
-                            ripples.push({ born: performance.now(), x: pointer.x, y: pointer.y });
-
-                            if (ripples.length > 6) {
-                                ripples.shift();
-                            }
-                        },
-                        onpointerleave: () => {
-                            pointer.at = performance.now();
-                            pointer.inside = false;
-                        },
-                        onpointermove: track
-                    }}
-                >
-                    <canvas aria-hidden='true' class='surface-field-canvas'></canvas>
-                    <div class='surface-field-content'>${content}</div>
-                </div>
-            `;
-        }
-    ),
+                            }}
+                        ></canvas>
+                    `;
+                }}
+                <div class='surface-field-content'>${content}</div>
+            </div>
+        `;
+    },
     { surface }
 );