ranger-compiler 3.5.1 → 3.5.2

package/dist/lib/evg/gl/evg-binary.js

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: MIT
+//
+// The display list as it crosses a thread: `EVGSceneBinary` in, the
+// painter's commands out.
+//
+// `evg-list.js` reads the list off the Ranger OBJECT, which is what a host
+// that shares a heap with the engine does. A host whose engine runs in a
+// Worker (`evg-engine.js`, PLAN_NATIVE_HOSTS.md S1) cannot: what crosses is
+// `EVGDisplayList.toBinary()` — three `Int32Array`s and a string pool,
+// transferred rather than copied — and this is the reader. It produces the
+// SAME command objects `cmdsOf` produces, key for key, so the painter does
+// not know which way the list arrived. `list-binary-check.mjs` holds the two
+// against each other on real frames.
+//
+// The record width is DERIVED from the buffer, never assumed: `cmds` is
+// allocated as exactly `count * stride`, so dividing recovers the writer's
+// number (ISSUES #4). This reader wants 36 fields; a wider record is fine and
+// a narrower one is refused with both numbers in the message. Values are
+// hundredths — `EVGDisplayList.fixed` rounds to what `toJson` writes — so the
+// division below gives back exactly the JSON's numbers.
+//
+// Slots 36 to 40 are `letter-spacing` and a stroke's cap, join and dash, and
+// they are read only when the buffer is wide
+// enough to have it. Raising FIELDS_READ instead would have refused every
+// bundle built before it existed — a hard failure for a field whose absence
+// means "the font's own spacing", which is what those bundles meant. A slot
+// that is optional in the data is optional in the reader.
+
+export const FIELDS_READ = 36;
+
+/** How many ints per command this buffer carries. */
+export function binaryStride(bin) {
+  const n = bin.count | 0;
+  const len = bin.cmds.length;
+  if (n === 0) return FIELDS_READ;
+  const stride = (len / n) | 0;
+  if (stride * n !== len) {
+    throw new Error(`scene binary: ${len} ints do not divide into ${n} commands`);
+  }
+  if (stride < FIELDS_READ) {
+    throw new Error(`scene binary: ${stride} fields per command, but this reader wants ${FIELDS_READ}`);
+  }
+  return stride;
+}
+
+const rgb = (packed) => [(packed >> 16) & 255, (packed >> 8) & 255, packed & 255];
+
+/**
+ * The camera on the envelope, or null when the list carried none.
+ *
+ * It is three numbers beside the page size rather than a field per command,
+ * which is why the record stride above is untouched by it: a reader that
+ * knows nothing about views reads this buffer exactly as it always did, and
+ * draws the scene unpanned — which is the right answer for a list whose host
+ * never asked for a camera.
+ */
+export function viewOfBinary(bin) {
+  if (!bin || !bin.hasView) return null;
+  return { x: bin.viewX || 0, y: bin.viewY || 0, scale: bin.viewScale === undefined ? 1 : bin.viewScale };
+}
+
+/** The commands, in the shape `evg-list.js`'s `cmdsOf` gives them. */
+export function cmdsOfBinary(bin) {
+  const n = bin.count | 0;
+  const stride = binaryStride(bin);
+  const r = bin.cmds, p = bin.pts, e = bin.ends, pool = bin.strings;
+  const out = new Array(n);
+  for (let i = 0; i < n; i += 1) {
+    const b = i * stride;
+    const o = { k: r[b] };
+    const layer = r[b + 30];
+    if (layer > 0) o.layer = layer;
+    o.x = r[b + 1] / 100;
+    o.y = r[b + 2] / 100;
+    o.w = r[b + 3] / 100;
+    o.h = r[b + 4] / 100;
+    const flags = r[b + 9];
+    const radius = r[b + 5] / 100;
+    if (flags & 64) o.rc = [radius, r[b + 27] / 100, r[b + 28] / 100, r[b + 29] / 100];
+    if (radius > 0) o.r = radius;
+    const t = r[b + 6] / 100;
+    if (t > 0) {
+      o.t = t;
+      if (stride > 38) {
+        if (r[b + 37] !== 0) o.cap = r[b + 37];
+        if (r[b + 38] !== 0) o.join = r[b + 38];
+      }
+      if (stride > 40) {
+        const d = r[b + 39];
+        if (d >= 0) {
+          o.dash = pool[d];
+          const off = r[b + 40] / 100;
+          if (off !== 0) o.dashoff = off;
+        }
+      }
+    }
+    o.c = [...rgb(r[b + 7]), r[b + 8] / 100];
+    if (flags & 1) {
+      o.gd = r[b + 10];
+      o.c2 = [...rgb(r[b + 11]), r[b + 12] / 100];
+    }
+    const textIdx = r[b + 15];
+    if (textIdx >= 0) {
+      o.text = pool[textIdx];
+      o.font = pool[r[b + 16]];
+      o.size = r[b + 13] / 100;
+      const w = r[b + 17];
+      if (w >= 0) o.weight = pool[w];
+      if (stride > 36) {
+        const ls = r[b + 36];
+        if (ls !== 0) o.ls = ls / 100;
+      }
+      if (flags & 2) o.italic = true;
+    }
+    const src = r[b + 18];
+    if (src >= 0) o.src = pool[src];
+    if (flags & 4) o.fx = true;
+    if (flags & 8) o.fy = true;
+    // The crop window into the source, when the picture is not shown whole.
+    // Ten-thousandths, not hundredths: a hundredth of a fraction is a whole
+    // percent of the bitmap, sixteen pixels on a wide screenshot.
+    if (stride > 44 && flags & 256) {
+      o.cu = [r[b + 41] / 10000, r[b + 42] / 10000, r[b + 43] / 10000, r[b + 44] / 10000];
+    }
+    const rot = r[b + 14] / 100;
+    if (rot !== 0) {
+      o.rot = rot;
+      if (flags & 32) {
+        o.rox = r[b + 24] / 100;
+        o.roy = r[b + 25] / 100;
+      }
+    }
+    const bb = r[b + 26] / 100;
+    if (bb > 0) o.bb = bb;
+    if (flags & 128) {
+      o.sh = {
+        x: r[b + 31] / 100, y: r[b + 32] / 100, blur: r[b + 33] / 100,
+        c: [...rgb(r[b + 34]), r[b + 35] / 100],
+      };
+    }
+    const pStart = r[b + 19], pCount = r[b + 20];
+    if (pCount > 0) {
+      const pts = new Array(pCount);
+      for (let j = 0; j < pCount; j += 1) pts[j] = p[pStart + j] / 100;
+      o.pts = pts;
+      const eStart = r[b + 21], eCount = r[b + 22];
+      const ends = new Array(eCount);
+      for (let j = 0; j < eCount; j += 1) ends[j] = e[eStart + j];
+      o.ends = ends;
+      if (flags & 16) o.eo = 1;
+    }
+    out[i] = o;
+  }
+  return out;
+}
+
+/** The typed arrays a `postMessage` may TRANSFER rather than copy. */
+export function transferablesOf(bin) {
+  return [bin.cmds.buffer, bin.pts.buffer, bin.ends.buffer];
+}

package/dist/lib/evg/gl/evg-engine.js

@@ -0,0 +1,296 @@
+// SPDX-License-Identifier: MIT
+//
+// The engine off the main thread.
+//
+// PLAN_NATIVE_HOSTS.md S1, the web half. An EVG app — the tree, the cascade,
+// the layout, the display list, the hit test — is pure Ranger and needs no
+// DOM, so it can run in a Worker, and then a layout that takes twelve
+// milliseconds on a chart-heavy page blocks neither the pointer nor the
+// compositor. What crosses back is the display list as `toBinary()` gives
+// it: three `Int32Array`s and a string pool, TRANSFERRED rather than copied,
+// read on the main thread by `evg-binary.js` into the same commands the
+// painter has always been fed. Input crosses the other way, as the calls the
+// host already made — `press`, `scrollDrag`, `setHover` — and the hit test
+// happens where the tree is.
+//
+// One file, two halves:
+//
+//   serveEngine(opts)      the worker's side — owns the app and answers
+//   connectEngine(worker)  the page's side — a proxy the host talks to
+//
+// THE PROTOCOL, and why it is shaped like this.
+//
+//   post(name, ...args)    a call with no answer, QUEUED — a pointer move, a
+//                          key, a press. Nothing is sent yet.
+//   call(name, ...args)    a call with an answer, as a promise: `hitId` for
+//                          the cursor, `fieldStateJson` for the text bridge.
+//                          Sent at once, with everything queued before it,
+//                          so order is what the host wrote.
+//   frame(dt)              the frame: every queued post, then `tick(dt)`,
+//                          then the display list — ONE message each way per
+//                          frame, however many events the browser delivered.
+//
+// The reply to `frame` is one of three things, and the host's painter
+// already knows what to do with each — it is exactly the distinction
+// `gallery/realtrainer/web/main.js` draws with `buildSeq` and `frameSeq`:
+//
+//   { t: "frame", doc, shifts }   a new build: buffers to upload
+//   { t: "shift", shifts }        the kept list moved — a scroll — draw the
+//                                 frame on the card with new offsets
+//   { t: "idle" }                 nothing moved; do not draw
+//
+// Every reply carries `state`: a small object the app-side bootstrap
+// composes from what the host reads on every frame — the scene's name, the
+// focused field, the scroll velocity — so the host is not making a round
+// trip for a string. What a host cannot do is READ synchronously; that is
+// the whole change, and `main-worker.js` beside the RealTrainer page shows
+// what a host looks like written that way.
+
+import { cmdsOfBinary, transferablesOf } from "./evg-binary.js";
+
+// ---------------------------------------------------------------------------
+// The worker's side
+// ---------------------------------------------------------------------------
+
+/**
+ * Serve an app from inside a Worker.
+ *
+ * @param {object} opts
+ * @param {(init: any) => object} opts.make    build the app from the `init`
+ *        message's payload — install the measurer FIRST (`evg-measure.js`
+ *        works here through `OffscreenCanvas`), because the app keeps a
+ *        layout from the moment it exists
+ * @param {(app: object) => object} opts.display  the display list for the
+ *        frame: `app.display()` for a host that keeps its list
+ * @param {(app: object, dt: number) => boolean} [opts.tick]  the clock;
+ *        default `app.tick(dt)`
+ * @param {(app: object) => object} [opts.state]  what every reply carries
+ * @param {(app: object) => object|undefined} [opts.effect]  the surface
+ *        effect, in the JSON's shape — `effectOf` from evg-list.js
+ * @param {(app: object) => number[][]} opts.shifts  the layers' shifts —
+ *        `shiftsOf` from evg-list.js
+ * @param {(app: object, dl: object) => object} [opts.onBuild]  what a NEW
+ *        BUILD carries beside the picture — the accessibility tree, say,
+ *        which changes when the tree changes and at no other time — merged
+ *        into the "frame" reply as `built`
+ * @param {object} [opts.hooks]  functions the host may post or call by
+ *        `@name` — host logic that belongs beside the tree, such as "hit
+ *        test this point and hover what is there", written once here rather
+ *        than as three round trips
+ * @param {object} [opts.scope]  `self` by default
+ */
+export function serveEngine(opts) {
+  const scope = opts.scope || self;
+  let app = null;
+  let lastList = null;
+  let lastSeq = -1;
+  let lastShifts = "";
+  const tick = opts.tick || ((a, dt) => a.tick(dt));
+  const state = opts.state || (() => ({}));
+
+  const reply = (msg, transfer) => scope.postMessage(msg, transfer || []);
+
+  const run = (name, args) => {
+    if (name.charCodeAt(0) === 64) {
+      const h = opts.hooks && opts.hooks[name.slice(1)];
+      if (typeof h !== "function") throw new Error(`engine: no hook ${name}`);
+      return h(app, ...args);
+    }
+    const f = app[name];
+    if (typeof f !== "function") throw new Error(`engine: the app has no method ${name}`);
+    return f.apply(app, args);
+  };
+
+  const frameReply = (dt, dirty) => {
+    let ticked = false;
+    if (dt !== undefined && dt !== null) ticked = !!tick(app, dt);
+    const dl = opts.display(app);
+    const seq = dl.buildSeq * 100000 + dl.frameSeq;
+    const shifts = opts.shifts(app, dl);
+    const st = state(app, dl);
+    if (dl !== lastList || seq !== lastSeq) {
+      lastList = dl;
+      lastSeq = seq;
+      lastShifts = JSON.stringify(shifts);
+      const bin = dl.toBinary();
+      const doc = {
+        width: bin.width, height: bin.height, seq,
+        bin: { count: bin.count, cmds: bin.cmds, pts: bin.pts, ends: bin.ends, strings: bin.strings },
+      };
+      const effect = opts.effect ? opts.effect(app, dl) : undefined;
+      if (effect) doc.effect = effect;
+      const built = opts.onBuild ? opts.onBuild(app, dl) : undefined;
+      reply({ t: "frame", doc, shifts, state: st, ticked, built }, transferablesOf(bin));
+      return;
+    }
+    const sh = JSON.stringify(shifts);
+    if (sh !== lastShifts || ticked || dirty) {
+      lastShifts = sh;
+      reply({ t: "shift", shifts, state: st, ticked });
+      return;
+    }
+    reply({ t: "idle", state: st, ticked });
+  };
+
+  scope.onmessage = (ev) => {
+    const m = ev.data;
+    try {
+      switch (m.t) {
+        case "init":
+          app = opts.make(m.init);
+          reply({ t: "ready", state: state(app, null) });
+          break;
+        case "post":
+          run(m.name, m.args);
+          break;
+        case "call": {
+          const value = run(m.name, m.args);
+          reply({ t: "ret", id: m.id, value: value === undefined ? null : value });
+          break;
+        }
+        case "batch": {
+          let dirty = false;
+          for (const [name, args] of m.posts) {
+            const r = run(name, args);
+            if (r === true) dirty = true;
+          }
+          for (const c of m.calls) {
+            const value = run(c.name, c.args);
+            reply({ t: "ret", id: c.id, value: value === undefined ? null : value });
+          }
+          if (m.frame) frameReply(m.dt, dirty || m.dirty);
+          break;
+        }
+        case "close":
+          scope.close();
+          break;
+        default:
+          throw new Error(`engine: unknown message ${m.t}`);
+      }
+    } catch (e) {
+      reply({ t: "error", id: m.id, message: String((e && e.stack) || e), during: m.t + ":" + (m.name || "") });
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The page's side
+// ---------------------------------------------------------------------------
+
+/**
+ * Talk to an app served by `serveEngine`.
+ *
+ * @param {Worker} worker
+ * @param {any} init  what the worker's `make` is handed
+ * @returns {{
+ *   ready: Promise<object>,
+ *   post: (name: string, ...args: any[]) => void,
+ *   call: (name: string, ...args: any[]) => Promise<any>,
+ *   frame: (dt?: number, dirty?: boolean) => Promise<object>,
+ *   flush: () => void,
+ *   state: () => object,
+ *   onError: (fn: (e: {message: string, during: string}) => void) => void,
+ *   close: () => void,
+ * }}
+ */
+export function connectEngine(worker, init) {
+  let nextId = 1;
+  const waiting = new Map();
+  let posts = [];
+  let last = {};
+  let errorFn = (e) => console.error("engine:", e.during, e.message);
+  let readyResolve;
+  const ready = new Promise((r) => { readyResolve = r; });
+  // At most one frame in flight: a host that asks for the next frame before
+  // the last one came back is asking the worker to fall behind, and a
+  // second request is answered by the reply already coming.
+  let frameWaiting = null;
+
+  worker.onmessage = (ev) => {
+    const m = ev.data;
+    switch (m.t) {
+      case "ready":
+        last = m.state || {};
+        readyResolve(last);
+        break;
+      case "ret": {
+        const w = waiting.get(m.id);
+        if (w) { waiting.delete(m.id); w.resolve(m.value); }
+        break;
+      }
+      case "frame": {
+        // The buffers arrive owned by this thread; the commands are made once.
+        m.doc.list = { seq: m.doc.seq, shifts: m.shifts, cmds: cmdsOfBinary(m.doc.bin) };
+        if (m.doc.effect) m.doc.list.effect = m.doc.effect;
+        delete m.doc.bin;
+        // falls through
+      }
+      case "shift":
+      case "idle": {
+        last = m.state || last;
+        const w = frameWaiting;
+        frameWaiting = null;
+        if (w) w.resolve(m);
+        break;
+      }
+      case "error": {
+        if (m.id !== undefined && waiting.has(m.id)) {
+          const w = waiting.get(m.id);
+          waiting.delete(m.id);
+          w.reject(new Error(m.message));
+        } else if (frameWaiting && m.during.startsWith("batch")) {
+          const w = frameWaiting;
+          frameWaiting = null;
+          w.reject(new Error(m.message));
+        }
+        errorFn(m);
+        break;
+      }
+      default:
+        break;
+    }
+  };
+
+  worker.postMessage({ t: "init", init });
+
+  const send = (calls, frame, dt, dirty) => {
+    const batch = { t: "batch", posts, calls, frame, dt, dirty };
+    posts = [];
+    worker.postMessage(batch);
+  };
+
+  return {
+    ready,
+    post(name, ...args) {
+      posts.push([name, args]);
+    },
+    call(name, ...args) {
+      const id = nextId++;
+      return new Promise((resolve, reject) => {
+        waiting.set(id, { resolve, reject });
+        send([{ id, name, args }], false);
+      });
+    },
+    frame(dt, dirty) {
+      if (frameWaiting) return frameWaiting.promise;
+      let resolve, reject;
+      const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
+      frameWaiting = { promise, resolve, reject };
+      send([], true, dt, !!dirty);
+      return promise;
+    },
+    /** Send what is queued without asking for a frame. */
+    flush() {
+      if (posts.length) send([], false);
+    },
+    state() {
+      return last;
+    },
+    onError(fn) {
+      errorFn = fn;
+    },
+    close() {
+      worker.postMessage({ t: "close" });
+    },
+  };
+}

package/dist/lib/evg/gl/evg-fx.js

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: MIT
+//
+// The effect driver: what turns a pointer into the events a surface effect
+// reads, from what the DOCUMENT said rather than from what the page's code
+// remembered to do.
+//
+// BEFORE THIS, the ripple was driven like this, in the demo's own main.js:
+//
+//   canvas.addEventListener("pointerdown", (ev) => {
+//     app.ripple(ev.offsetX, ev.offsetY);   // every press, anywhere
+//   });
+//
+// and the application kept the drops, aged them on every tick, retired them,
+// and stamped them onto the root at paint time. Three arrays of state and four
+// methods on a dashboard, for an effect the dashboard has no opinion about.
+// Nothing in that chain could answer "which element ripples" — the answer was
+// "the page", because the effect was the page's.
+//
+// Now the document answers it:
+//
+//   .card    { evg-surface-effect: ripple;    evg-effect-on: press drag }
+//   .hero-sky { evg-surface-effect: starfield; evg-effect-on: always }
+//
+// and this file is the whole of the wiring:
+//
+//   const fx = createEffectDriver();
+//   attachEffectPointer(canvas, fx, () => schedule());   // optional
+//   // per frame:
+//   fx.tick(dtMs, list);      // ages the events, stamps the clock on
+//   renderDisplayList(gl, { width, height, list }, { dpr });
+//
+// WHAT IT OWNS is the events: where a press landed, in PAGE pixels, and how
+// long ago. What it does not own is anything about how they look — that is the
+// plugin's, in `evg-webgl.js` — or which element they belong to, which is the
+// display list's, because that came from the stylesheet.
+//
+// WHY IT IS NOT IN THE ENGINE. The engine has no pointer. A press is a browser
+// event on the web, a MotionEvent on Android and a UITouch on iOS, and the one
+// thing all three have in common is that the box they landed in is already in
+// the display list. So the driver is per host and small, and the part that is
+// the same everywhere — which box, what trigger, how the event ages — is here
+// rather than written again in each one.
+
+/** How far a drag travels before it drops another event, in page pixels.
+ *  Closer and the rings pile into one bright blob; further and a wake reads
+ *  as a row of separate taps. */
+const DRAG_STEP = 26;
+
+/** The most events one instance carries. Eight is what a dragged finger fills
+ *  in a third of a second, and it is what the shaders' `MAX_EVENTS` is. */
+const MAX_EVENTS = 8;
+
+/** How long an event lives, in seconds. The ripple's own decay has taken it
+ *  under a 250th by three seconds, so this is the renderer's number and not a
+ *  guess. */
+const LIFE = 3;
+
+/** Does this instance's trigger list mention `what`? A trigger is a list of
+ *  words — `press drag` — because a card can want both and CSS has no better
+ *  shape for "one or more of these".
+ *
+ *  An instance the host has switched off (`inst.off`) answers no to everything,
+ *  so a press on it lands on whatever is under it rather than being swallowed
+ *  by an effect that is not running. The painter skips the same flag, and
+ *  between them "off" means off rather than "invisible but still listening". */
+export function triggerHas(inst, what) {
+  if (!inst || inst.off) return false;
+  const on = inst.on || "";
+  return on.length > 0 && on.split(/[\s,]+/).indexOf(what) >= 0;
+}
+
+/** Is the point inside the instance's box? Corners are not tested: an effect
+ *  is triggered by a press on the element, and the element's rounded corner is
+ *  a question about painting rather than about who was pressed. */
+function inBox(inst, x, y) {
+  const b = inst.box;
+  return !!b && x >= b[0] && y >= b[1] && x <= b[0] + b[2] && y <= b[1] + b[3];
+}
+
+export function createEffectDriver(opts = {}) {
+  // Per instance id: the events in flight and where the last drag event was
+  // dropped. Keyed by ID and not by object, because the display list is
+  // rebuilt — a reflow makes new instance objects for the same elements, and
+  // a ripple must not die because the window was resized.
+  const state = new Map();
+  // Seconds since the driver was made. What `always` effects run on, and the
+  // reason a starfield needs no events at all.
+  let clock = 0;
+  const life = opts.life === undefined ? LIFE : opts.life;
+  const step = opts.dragStep === undefined ? DRAG_STEP : opts.dragStep;
+
+  const stateFor = (id) => {
+    let st = state.get(id);
+    if (!st) { st = { events: [], lastX: -1, lastY: -1 }; state.set(id, st); }
+    return st;
+  };
+
+  // The instances of the list last synced, newest first — the reverse of paint
+  // order, so the TOPMOST element that wants the event gets it. Two effects
+  // that overlap are a stack, and a press belongs to the one on top.
+  let instances = [];
+
+  const fire = (x, y, what) => {
+    let hit = null;
+    for (let i = instances.length - 1; i >= 0; i -= 1) {
+      const inst = instances[i];
+      if (!triggerHas(inst, what)) continue;
+      if (!inBox(inst, x, y)) continue;
+      hit = inst;
+      break;
+    }
+    if (!hit) return null;
+    const st = stateFor(hit.id);
+    st.events.push([x, y, 0]);
+    if (st.events.length > MAX_EVENTS) st.events.shift();
+    st.lastX = x;
+    st.lastY = y;
+    return hit;
+  };
+
+  return {
+    /** The instances this driver is watching, for a host that wants to look. */
+    instances: () => instances,
+
+    /** Seconds since the driver was made. */
+    time: () => clock,
+
+    /** Take the list of the frame about to be drawn, advance every event by
+     *  `dtMs`, and stamp what the painter reads onto each instance.
+     *
+     *  IT MUTATES THE LIST, and that is deliberate: the instances are the
+     *  painter's own objects, so a host that keeps a built frame across many
+     *  draws sees the events move without rebuilding anything. Nothing in the
+     *  tree changes — the clock is not in the document, which is what keeps a
+     *  running effect off the layout's critical path entirely. */
+    tick(dtMs, list) {
+      const dt = (dtMs || 0) / 1000;
+      clock += dt;
+      for (const st of state.values()) {
+        if (!st.events.length) continue;
+        const kept = [];
+        for (const e of st.events) {
+          e[2] += dt;
+          if (e[2] < life) kept.push(e);
+        }
+        st.events = kept;
+      }
+      instances = (list && list.effects) || [];
+      for (const inst of instances) {
+        const st = state.get(inst.id);
+        inst.events = st ? st.events : [];
+        inst.time = clock;
+      }
+      return this.busy();
+    },
+
+    /** Is anything still moving? A page whose effects are all idle can stop
+     *  asking for frames, which is the difference between an effect and a
+     *  background process. */
+    busy() {
+      for (const inst of instances) {
+        if (inst.off) continue;
+        if (triggerHas(inst, "always")) return true;
+        const st = state.get(inst.id);
+        if (st && st.events.length) return true;
+      }
+      return false;
+    },
+
+    /** A press at a point in PAGE pixels. Returns the instance it went to, or
+     *  null when it landed on nothing that wanted it — which is the ordinary
+     *  case, and the whole difference from a page that ripples everywhere. */
+    press(x, y) { return fire(x, y, "press"); },
+
+    /** The pointer moving with the button down. One event per step rather than
+     *  one that follows the pointer: a wake is a row of sources, and a single
+     *  source that moves has no history. */
+    drag(x, y) {
+      for (let i = instances.length - 1; i >= 0; i -= 1) {
+        const inst = instances[i];
+        if (!triggerHas(inst, "drag")) continue;
+        if (!inBox(inst, x, y)) continue;
+        const st = stateFor(inst.id);
+        if (st.lastX < 0) { st.lastX = x; st.lastY = y; return null; }
+        const dx = x - st.lastX, dy = y - st.lastY;
+        if (dx * dx + dy * dy < step * step) return null;
+        return fire(x, y, "drag");
+      }
+      return null;
+    },
+
+    /** The pointer moving with no button down. */
+    hover(x, y) { return fire(x, y, "hover"); },
+
+    /** The button came up: the next drag starts a fresh trail rather than
+     *  joining the last one. */
+    release() {
+      for (const st of state.values()) { st.lastX = -1; st.lastY = -1; }
+    },
+
+    /** Everything in flight, gone. For a host that navigated away from the
+     *  page the events belonged to. */
+    clear() { state.clear(); },
+  };
+}
+
+/**
+ * The web host's three lines of it. `onChange` is called whenever something
+ * happened that the page has to draw — a host that is already drawing every
+ * frame can leave it out.
+ *
+ * The coordinates are `offsetX`/`offsetY`, which are CSS pixels relative to the
+ * canvas, which is the page space the display list is in. A canvas with a
+ * camera on it has to unproject them first, and then this is the wrong helper —
+ * pass the driver the page point yourself.
+ */
+export function attachEffectPointer(canvas, driver, onChange) {
+  const poke = () => { if (onChange) onChange(); };
+  const down = (ev) => { if (driver.press(ev.offsetX, ev.offsetY)) poke(); };
+  const move = (ev) => {
+    const hit = ev.buttons ? driver.drag(ev.offsetX, ev.offsetY) : driver.hover(ev.offsetX, ev.offsetY);
+    if (hit) poke();
+  };
+  const up = () => driver.release();
+  canvas.addEventListener("pointerdown", down);
+  canvas.addEventListener("pointermove", move);
+  canvas.addEventListener("pointerup", up);
+  canvas.addEventListener("pointercancel", up);
+  canvas.addEventListener("pointerleave", up);
+  return () => {
+    canvas.removeEventListener("pointerdown", down);
+    canvas.removeEventListener("pointermove", move);
+    canvas.removeEventListener("pointerup", up);
+    canvas.removeEventListener("pointercancel", up);
+    canvas.removeEventListener("pointerleave", up);
+  };
+}