ispyx 0.0.0-stage → 1.0.0

package/src/effects/scan.js

@@ -0,0 +1,850 @@
+// Screenshot animation: after a capture an eye opens at the top of the captured region, looks down and follows
+// a glowing green scan line that sweeps the region from top to bottom. Two click-through, per-pixel-alpha windows;
+// pixels are drawn in software into DIB sections, so nothing here depends on GDI+.
+import platform from '../platform/index.js';
+
+const clamp = (v, lo = 0, hi = 1) => Math.min(hi, Math.max(lo, v));
+const mix = (a, b, t) => a + (b - a) * t;
+const smooth = (t) => t * t * (3 - 2 * t);
+
+/** The scan line: a bright green edge at the bottom with a glow trailing above it. */
+export function renderBand(px, width, height, stride = width) {
+  const edgeFade = Math.max(8, width * 0.06);
+  for (let y = 0; y < height; y++) {
+    const d = height - 1 - y; // distance above the leading edge
+    const k = d < 3 ? 1 : 0.6 * Math.exp(-d / 16);
+    for (let x = 0; x < width; x++) {
+      const e = smooth(clamp(Math.min(x, width - 1 - x) / edgeFade));
+      const hit = Math.exp(-(((x - width / 2) / (width * 0.035)) ** 2)) * Math.exp(-d / 6); // where the laser lands
+      const a = clamp(k * e + 0.9 * hit);
+      const core = clamp((d < 3 ? 0.75 : 0) + hit);
+      let r = mix(40, 255, core), g = mix(230, 255, core), b = mix(110, 255, core);
+      if (d < 1.2) { r = 14; g = 70; b = 40; } // dark leading edge, so the line also shows on white
+      const i = (y * stride + x) * 4;
+      px[i] = b * a; px[i + 1] = g * a; px[i + 2] = r * a; px[i + 3] = a * 255;
+    }
+  }
+}
+
+/**
+ * The eye: white eyeball, green iris, dark pupil, a soft highlight. `open` 0..1 is the lid (0 = closed),
+ * (gx, gy) in -1..1 is where it looks.
+ */
+/** Where the pupil centre is inside the eye sprite (sprite pixels). */
+const eyeR = (size) => size / 2 - 7; // the rest of the sprite holds the outline ring and its glow
+export function pupilPos(size, gx, gy) {
+  const R = eyeR(size);
+  return { x: size / 2 + gx * 0.36 * R + gx * 0.07 * R, y: size / 2 + gy * 0.40 * R + gy * 0.09 * R };
+}
+
+export function renderEye(px, size, open, gx, gy, glow = 0) {
+  const c = size / 2;
+  const R = eyeR(size);
+  const lid = Math.max(open, 0.02);
+  const ix = c + gx * 0.36 * R, iy = c + gy * 0.40 * R;
+  const rxI = 0.46 * R * (1 - 0.2 * Math.abs(gx)), ryI = 0.46 * R * (1 - 0.2 * Math.abs(gy));
+  const px0 = ix + gx * 0.07 * R, py0 = iy + gy * 0.09 * R;
+  const rxP = rxI * 0.56, ryP = ryI * 0.56;
+  const hx = ix + 0.5 * rxI, hy = iy - 0.38 * ryI, hr = 0.55 * rxI;
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      const dx = x + 0.5 - c, dy = y + 0.5 - c;
+      const sd = Math.hypot(dx, dy / lid) - R;
+      const a = clamp(0.5 - sd);
+      const i = (y * size + x) * 4;
+      // outline ring (dark, so the white eyeball shows on a white screen) with a soft green glow outside it
+      const darkA = clamp(2.5 + 0.5 - sd) * 0.92;
+      const glowA = 0.7 * Math.exp(-(((sd - 3.5) / 1.6) ** 2));
+      if (a <= 0) {
+        if (sd > 7 || (darkA <= 0 && glowA < 0.01)) { px[i] = px[i + 1] = px[i + 2] = px[i + 3] = 0; continue; }
+        // glow under dark, both over transparent (premultiplied)
+        const ga = glowA * (1 - darkA);
+        px[i] = (110 * ga + 22 * darkA); px[i + 1] = (255 * ga + 70 * darkA); px[i + 2] = (60 * ga + 40 * darkA); px[i + 3] = (ga + darkA) * 255;
+        continue;
+      }
+      const n = Math.hypot(dx, dy) / R;
+      const low = smooth(clamp((dy / R - 0.1) / 0.7));
+      let r = 254 - 30 * n ** 3 - 22 * low, g = 255 - 24 * n ** 3 - 4 * low, b = 254 - 30 * n ** 3 - 20 * low;
+      const di = Math.hypot((x + 0.5 - ix) / rxI, (y + 0.5 - iy) / ryI);
+      const ai = clamp((1 - di) * rxI);
+      if (ai > 0) {
+        const light = 0.22 * (((x + 0.5 - ix) / rxI) * 0.6 - ((y + 0.5 - iy) / ryI) * 0.6);
+        const t = clamp(1 - di + light);
+        r = mix(r, mix(8, 120, t), ai); g = mix(g, mix(120, 245, t), ai); b = mix(b, mix(30, 110, t), ai);
+        const dp = Math.hypot((x + 0.5 - px0) / rxP, (y + 0.5 - py0) / ryP);
+        const ap = clamp((1 - dp) * rxP);
+        if (ap > 0) {
+          const t2 = clamp(dp);
+          r = mix(r, mix(2, 10, t2), ap); g = mix(g, mix(18, 60, t2), ap); b = mix(b, mix(6, 24, t2), ap);
+          if (glow > 0) { // the laser charges in the pupil
+            const h = glow * (1 - t2) ** 1.5 * ap;
+            r = mix(r, 150, h); g = mix(g, 255, h); b = mix(b, 190, h);
+          }
+        }
+      }
+      const ah = clamp((1 - Math.hypot(x + 0.5 - hx, y + 0.5 - hy) / hr) * hr * 0.5) * 0.42;
+      if (ah > 0) { r = mix(r, 255, ah); g = mix(g, 255, ah); b = mix(b, 255, ah); }
+      // eye over its dark outline: at the rim (a < 1) the ring shows through
+      const ra = a + darkA * (1 - a);
+      px[i] = b * a + 40 * darkA * (1 - a); px[i + 1] = g * a + 70 * darkA * (1 - a); px[i + 2] = r * a + 22 * darkA * (1 - a); px[i + 3] = ra * 255;
+    }
+  }
+}
+
+/**
+ * The scanner light: a triangle from the pupil (ax, ay) to the scan line, which runs from x1 to x2 at height ey
+ * (all in buffer pixels). Brighter towards the line, bright rims along the two edges, faint horizontal striations.
+ * The buffer is cleared first.
+ */
+export function drawWedge(px, width, height, ax, ay, x1, x2, ey) {
+  px.fill(0, 0, width * height * 4);
+  const span = ey - ay;
+  if (Math.abs(span) < 2) return;
+  const y0 = Math.max(0, Math.ceil(Math.min(ay, ey))), y1 = Math.min(height - 1, Math.floor(Math.max(ay, ey)));
+  for (let y = y0; y <= y1; y++) {
+    const sn = (y + 0.5 - ay) / span; // 0 at the pupil, 1 at the line
+    if (sn <= 0) continue;
+    const xl = ax + (x1 - ax) * sn, xr = ax + (x2 - ax) * sn;
+    const wd = xr - xl;
+    if (wd < 1) continue;
+    const stripe = 0.86 + 0.14 * Math.sin(y * 0.7);
+    const gain = 0.08 + 0.2 * sn;
+    const xs = Math.max(0, Math.floor(xl - 1)), xe = Math.min(width - 1, Math.ceil(xr + 1));
+    for (let x = xs; x <= xe; x++) {
+      const e = Math.min(x + 0.5 - xl, xr - (x + 0.5)); // distance to the nearest rim
+      const inside = clamp(e + 0.5);
+      if (inside <= 0) continue;
+      const rim = 0.55 * Math.exp(-((e / 2.2) ** 2)) * (0.4 + 0.6 * sn);
+      const a = clamp((gain * stripe + rim) * inside);
+      const i = (y * width + x) * 4;
+      px[i] = 60 * a; px[i + 1] = 255 * a; px[i + 2] = 110 * a; px[i + 3] = a * 255;
+    }
+  }
+}
+
+/** A green frame on the rectangle's edges: dark outer line (shows on white), bright core, glow inward, thick corner brackets. */
+export function renderFrame(px, width, height) {
+  const reach = 34, arm = Math.min(60, Math.floor(Math.min(width, height) / 3));
+  px.fill(0, 0, width * height * 4);
+  for (let y = 0; y < height; y++) {
+    const dy = Math.min(y, height - 1 - y);
+    const full = dy < reach;
+    for (let x = 0; x < width; x++) {
+      const dx = Math.min(x, width - 1 - x);
+      if (!full && dx >= reach && width - reach - 1 > x) { x = width - reach - 1; continue; } // skip the empty middle
+      const d = Math.min(dx, dy);
+      const nearCorner = (dx < arm && dy < reach) || (dy < arm && dx < reach);
+      const thick = nearCorner ? 9 : 5; // corner brackets are thicker
+      let r, g, bl, a;
+      if (d < 2.5) { r = 14; g = 50; bl = 28; a = 0.95; } // dark outline
+      else if (d < 2.5 + thick) { const t = (d - 2.5) / thick; r = mix(150, 60, t); g = 255; bl = mix(190, 110, t); a = 1; } // bright core
+      else { const k = Math.exp(-(d - 2.5 - thick) / 10); r = 60; g = 255; bl = 110; a = 0.5 * k; }
+      if (a < 0.01) continue;
+      const i = (y * width + x) * 4;
+      px[i] = bl * a; px[i + 1] = g * a; px[i + 2] = r * a; px[i + 3] = a * 255;
+    }
+  }
+}
+
+const RIPPLE_COLORS = { left: [60, 255, 110], right: [40, 200, 255], middle: [255, 190, 40] }; // RGB
+export const RIPPLE_MS = 430, RIPPLE_GAP_MS = 120;
+const RIPPLE_SIZE = 132;
+
+/** Expanding rings (one per click of a multi-click) with a dark outline, plus a dot where the button went down. */
+export function renderRipple(px, size, t, rings, rgb) {
+  px.fill(0, 0, size * size * 4);
+  const c = size / 2;
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      const r = Math.hypot(x + 0.5 - c, y + 0.5 - c);
+      let pr = 0, pg = 0, pb = 0, pa = 0; // premultiplied accumulator
+      const add = (cr, cg, cb, a) => { if (a <= 0) return; pr = cr * a + pr * (1 - a); pg = cg * a + pg * (1 - a); pb = cb * a + pb * (1 - a); pa = a + pa * (1 - a); };
+      for (let k = 0; k < rings; k++) {
+        const u = (t - k * RIPPLE_GAP_MS) / RIPPLE_MS;
+        if (u <= 0 || u >= 1) continue;
+        const radius = 6 + 52 * (1 - (1 - u) ** 3);
+        const fade = (1 - u) ** 1.2;
+        const d = Math.abs(r - radius);
+        add(14, 50, 28, clamp(2.6 - Math.abs(d - 2.6)) * 0.7 * fade); // dark outline hugging the ring
+        add(rgb[0], rgb[1], rgb[2], clamp(2.2 - d) * fade); // bright ring
+        add(rgb[0], rgb[1], rgb[2], 0.18 * clamp(radius - r) * fade * 0.07); // faint fill
+      }
+      const u0 = t / 260;
+      if (u0 < 1) { // the press point
+        add(14, 50, 28, clamp(5.5 - r) * 0.8 * (1 - u0));
+        add(255, 255, 255, clamp(3.6 - r) * (1 - u0));
+      }
+      if (pa <= 0) continue;
+      const i = (y * size + x) * 4;
+      px[i] = pb; px[i + 1] = pg; px[i + 2] = pr; px[i + 3] = pa * 255;
+    }
+  }
+}
+
+/** A rectangle outline (dark line outside, bright line inside) with alpha `a`; coordinates are inclusive pixel edges. */
+function drawBorder(px, W, H, x0, y0, x1, y1, rgb, a, thick) {
+  const set = (x, y, r, g, b, al) => {
+    if (x < 0 || y < 0 || x >= W || y >= H || al <= 0) return;
+    const i = (y * W + x) * 4;
+    if (al * 255 <= px[i + 3]) return;
+    px[i] = b * al; px[i + 1] = g * al; px[i + 2] = r * al; px[i + 3] = al * 255;
+  };
+  const ring = (inset, width, c, al) => {
+    const a0 = x0 + inset, b0 = y0 + inset, a1 = x1 - inset, b1 = y1 - inset;
+    for (let k = 0; k < width; k++) {
+      for (let x = a0 + k; x <= a1 - k; x++) { set(x, b0 + k, c[0], c[1], c[2], al); set(x, b1 - k, c[0], c[1], c[2], al); }
+      for (let y = b0 + k; y <= b1 - k; y++) { set(a0 + k, y, c[0], c[1], c[2], al); set(a1 - k, y, c[0], c[1], c[2], al); }
+    }
+  };
+  ring(0, 2, [14, 50, 28], 0.85 * a);
+  ring(2, thick, rgb, a);
+}
+
+const easeOut = (t) => 1 - (1 - t) ** 1.5;
+
+/**
+ * A sonar ring of radius `r` around (cx, cy): bright thin front with a dark outer edge (so it shows on white) and a
+ * glow trailing `trail` px inward. Only the annulus is visited. `k` scales the strength (0..1).
+ */
+function drawRing(px, W, H, cx, cy, r, trail, k) {
+  if (k <= 0.01) return;
+  const rout = r + 3.5, rin = Math.max(0, r - trail);
+  const y0 = Math.max(0, Math.floor(cy - rout)), y1 = Math.min(H - 1, Math.ceil(cy + rout));
+  for (let y = y0; y <= y1; y++) {
+    const dy = y + 0.5 - cy;
+    if (Math.abs(dy) > rout) continue;
+    const xo = Math.sqrt(rout * rout - dy * dy);
+    const xi = Math.abs(dy) < rin ? Math.sqrt(rin * rin - dy * dy) : 0;
+    for (const [xa, xb] of [[cx + xi, cx + xo], [cx - xo, cx - xi]]) {
+      for (let x = Math.max(0, Math.floor(xa)); x <= Math.min(W - 1, Math.ceil(xb)); x++) {
+        const d = r - Math.hypot(x + 0.5 - cx, dy); // > 0 behind the front
+        let al, red, grn, blu;
+        if (d < -3.2) continue;
+        if (d < 0) { al = 0.7 * clamp(1.6 - Math.abs(d + 1.7)) * k; red = 14; grn = 50; blu = 28; } // dark outer edge
+        else {
+          const core = clamp(2.2 - d);
+          al = Math.max(core, 0.5 * Math.exp(-d / 20)) * k;
+          red = mix(60, 255, core); grn = 255; blu = mix(110, 255, core);
+        }
+        if (al <= 0.01) continue;
+        const i = (y * W + x) * 4;
+        if (al * 255 <= px[i + 3]) continue;
+        px[i] = blu * al; px[i + 1] = grn * al; px[i + 2] = red * al; px[i + 3] = al * 255;
+      }
+    }
+  }
+}
+
+const KEY_LABELS = { ctrl: 'Ctrl', control: 'Ctrl', shift: 'Shift', alt: 'Alt', win: 'Win', windows: 'Win', meta: 'Win', cmd: 'Win', super: 'Win', enter: 'Enter', return: 'Enter', esc: 'Esc', escape: 'Esc', tab: 'Tab', space: 'Space', backspace: 'Backspace', delete: 'Del', del: 'Del', insert: 'Ins', ins: 'Ins', home: 'Home', end: 'End', pageup: 'PgUp', pgup: 'PgUp', pagedown: 'PgDn', pgdn: 'PgDn', left: '\u2190', up: '\u2191', right: '\u2192', down: '\u2193' };
+/** "ctrl+a ctrl+c" -> [['Ctrl', 'A'], ['Ctrl', 'C']] */
+export const keyLabels = (keys) => keys.trim().split(/\s+/).filter(Boolean).map((chord) => chord.split('+').filter(Boolean).map((k) => KEY_LABELS[k.toLowerCase()] ?? (k.length === 1 ? k.toUpperCase() : k[0].toUpperCase() + k.slice(1))));
+
+const TRAIL_LIFE_MS = 750, TRAIL_FADE_MS = 320;
+
+/** Draws a thick soft line segment into a premultiplied buffer, keeping the stronger alpha where strokes overlap. */
+function stroke(px, width, height, x0, y0, x1, y1, radius, rgb, alpha) {
+  const n = Math.max(1, Math.ceil(Math.hypot(x1 - x0, y1 - y0)));
+  const R = Math.ceil(radius + 1);
+  for (let s = 0; s <= n; s++) {
+    const cx = x0 + ((x1 - x0) * s) / n, cy = y0 + ((y1 - y0) * s) / n;
+    const xa = Math.max(0, Math.floor(cx - R)), xb = Math.min(width - 1, Math.ceil(cx + R));
+    const ya = Math.max(0, Math.floor(cy - R)), yb = Math.min(height - 1, Math.ceil(cy + R));
+    for (let y = ya; y <= yb; y++) {
+      for (let x = xa; x <= xb; x++) {
+        const a = clamp(radius + 0.5 - Math.hypot(x + 0.5 - cx, y + 0.5 - cy)) * alpha;
+        const i = (y * width + x) * 4;
+        if (a * 255 <= px[i + 3]) continue;
+        px[i] = rgb[2] * a; px[i + 1] = rgb[1] * a; px[i + 2] = rgb[0] * a; px[i + 3] = a * 255;
+      }
+    }
+  }
+}
+
+/**
+ * Point at u (0..1) between p1 and p2 on a centripetal Catmull-Rom spline through p0..p3. The trail samples the
+ * pointer once a frame, so a fast glide leaves a few points far apart; this draws the curve between them. The
+ * centripetal form never loops or overshoots, also where the pointer turns back.
+ */
+export function catmullRom(p0, p1, p2, p3, u) {
+  const d = (a, b) => Math.max(1e-3, Math.sqrt(Math.hypot(b.x - a.x, b.y - a.y)));
+  const t1 = d(p0, p1), t2 = t1 + d(p1, p2), t3 = t2 + d(p2, p3);
+  const t = t1 + (t2 - t1) * u;
+  const lerp = (a, b, ta, tb) => ({ x: (a.x * (tb - t) + b.x * (t - ta)) / (tb - ta), y: (a.y * (tb - t) + b.y * (t - ta)) / (tb - ta) });
+  const a1 = lerp(p0, p1, 0, t1), a2 = lerp(p1, p2, t1, t2), a3 = lerp(p2, p3, t2, t3);
+  const b1 = lerp(a1, a2, 0, t2), b2 = lerp(a2, a3, t1, t3);
+  return lerp(b1, b2, t1, t2);
+}
+
+/** The start marker of a drag: dark ring, bright ring and a dot. */
+function marker(px, width, height, cx, cy, rgb) {
+  for (let y = Math.max(0, Math.floor(cy - 16)); y <= Math.min(height - 1, Math.ceil(cy + 16)); y++) {
+    for (let x = Math.max(0, Math.floor(cx - 16)); x <= Math.min(width - 1, Math.ceil(cx + 16)); x++) {
+      const r = Math.hypot(x + 0.5 - cx, y + 0.5 - cy);
+      const dark = clamp(2.2 - Math.abs(r - 12.5)) * 0.85, bright = clamp(1.6 - Math.abs(r - 11)), dot = clamp(4 - r);
+      const a = Math.max(dark, bright, dot);
+      if (a <= 0) continue;
+      const k = bright >= dark * 0.9 || dot > 0.5 ? 1 : 0;
+      const i = (y * width + x) * 4;
+      const c = k ? rgb : [14, 50, 28];
+      px[i] = c[2] * a; px[i + 1] = c[1] * a; px[i + 2] = c[0] * a; px[i + 3] = a * 255;
+    }
+  }
+}
+
+const ease = (t) => t * t * (3 - 2 * t);
+const T_OPEN = 280, T_SCAN = 1100, T_CLOSE = 320;
+export const SCAN_TOTAL_MS = T_OPEN + T_SCAN + T_CLOSE;
+
+let flip = false; // alternates the side of the eye between screenshots
+
+export const FLASH_TOTAL_MS = 760;
+
+
+export class ScanAnimation {
+  constructor({ enabled = true } = {}) {
+    this.enabled = enabled;
+  }
+
+  /**
+   * drag: a ring where the button went down and a glowing trail that follows the pointer (sampled every frame),
+   * fading with age. When `stopped` resolves (button released) the trail fades out and rings mark the end.
+   * `bounds` {left, top, right, bottom}: where the drag can go. Never throws.
+   */
+  async trail(start, bounds, stopped, cancelled = () => false, button = 'left', { marker: showMarker = true, life = TRAIL_LIFE_MS, ring = true } = {}) {
+    if (!this.enabled) return;
+    let layer = null;
+    let ended = false;
+    stopped.then(() => { ended = true; });
+    try {
+      platform.ensurePump();
+      const v = platform.virtualScreen();
+      const pad = 330;
+      const left = Math.max(v.x, Math.floor(Math.min(bounds.left, start.x) - pad)), top = Math.max(v.y, Math.floor(Math.min(bounds.top, start.y) - pad));
+      const right = Math.min(v.x + v.width, Math.ceil(Math.max(bounds.right, start.x) + pad)), bottom = Math.min(v.y + v.height, Math.ceil(Math.max(bounds.bottom, start.y) + pad));
+      layer = new platform.Layer(Math.max(40, right - left), Math.max(40, bottom - top));
+      const rgb = RIPPLE_COLORS[button] ?? RIPPLE_COLORS.left;
+      const pts = [{ x: start.x, y: start.y, t: 0 }];
+      const t0 = performance.now();
+      let endAt = 0, endPoint = null;
+      for (;;) {
+        const tf = performance.now(), t = tf - t0;
+        if (cancelled()) break;
+        if (ended && !endAt) { endAt = t; const c = platform.cursorPos(); endPoint = { x: c.x, y: c.y }; pts.push({ ...endPoint, t }); }
+        if (endAt && t - endAt > TRAIL_FADE_MS) break;
+        if (!endAt) {
+          const c = platform.cursorPos();
+          const last = pts[pts.length - 1];
+          if (Math.hypot(c.x - last.x, c.y - last.y) >= 1) pts.push({ x: c.x, y: c.y, t });
+        }
+        layer.px.fill(0);
+        const fade = endAt ? 1 - clamp((t - endAt) / TRAIL_FADE_MS) : 1;
+        for (let pass = 0; pass < 2; pass++) {
+          for (let k = 1; k < pts.length; k++) {
+            const age = (endAt ? Math.min(t, endAt) : t) - pts[k].t;
+            const a = clamp(1 - age / life) * fade;
+            if (a <= 0.02) continue;
+            // the curve through the samples, in pieces of about 12 px
+            const P0 = pts[Math.max(0, k - 2)], P1 = pts[k - 1], P2 = pts[k], P3 = pts[Math.min(pts.length - 1, k + 1)];
+            const pieces = Math.min(24, Math.max(1, Math.ceil(Math.hypot(P2.x - P1.x, P2.y - P1.y) / 12)));
+            let A = P1;
+            for (let s = 1; s <= pieces; s++) {
+              const B = s === pieces ? P2 : catmullRom(P0, P1, P2, P3, s / pieces);
+              if (pass === 0) stroke(layer.px, layer.width, layer.height, A.x - left, A.y - top, B.x - left, B.y - top, 5.2, [14, 50, 28], a * 0.75);
+              else stroke(layer.px, layer.width, layer.height, A.x - left, A.y - top, B.x - left, B.y - top, 3, k % 6 < 5 ? rgb : [255, 255, 255], a);
+              A = B;
+            }
+          }
+        }
+        if (showMarker) marker(layer.px, layer.width, layer.height, start.x - left, start.y - top, rgb);
+        layer.present(left, top, 255 * fade);
+        await new Promise((r) => setTimeout(r, Math.max(1, 16 - (performance.now() - tf))));
+      }
+      layer.destroy();
+      layer = null;
+      if (endPoint && ring && !cancelled()) await this.ripple(endPoint, button, 1, cancelled);
+    } catch (e) {
+      process.stderr.write(`ispyx: drag effect failed (${e.message})
+`);
+    } finally {
+      layer?.destroy();
+    }
+  }
+
+  /**
+   * scroll: chevrons beside the pointer travel in the scroll direction while the wheel turns (until `stopped`
+   * resolves, at least 380 ms, then a short fade). dirV: +1 up / -1 down / 0, dirH: +1 right / -1 left / 0. Never throws.
+   */
+  async wheelCue(point, dirV, dirH, speed, stopped, cancelled = () => false) {
+    if (!this.enabled || (!dirV && !dirH)) return;
+    let layer = null;
+    let ended = false;
+    stopped.then(() => { ended = true; });
+    try {
+      platform.ensurePump();
+      const S = 180, c = S / 2;
+      layer = new platform.Layer(S, S);
+      const SP = 24, L = SP * 3, arm = 13;
+      const t0 = performance.now();
+      let endAt = 0;
+      for (;;) {
+        const tf = performance.now(), t = tf - t0;
+        if (cancelled()) break;
+        if (ended && t >= 380 && !endAt) endAt = t;
+        if (endAt && t - endAt > 220) break;
+        const fade = endAt ? 1 - clamp((t - endAt) / 220) : clamp(t / 90);
+        layer.px.fill(0);
+        const phase = (t * 0.09 * clamp(speed, 0.6, 3)) % SP;
+        for (let pass = 0; pass < 2; pass++) {
+          for (let k = 0; k < 4; k++) {
+            const pos = k * SP + phase; // 0..L+SP along the travel direction
+            const a = Math.sin(Math.PI * clamp(pos / L)) * fade;
+            if (a < 0.03) continue;
+            for (const [dir, horiz] of [[dirV, false], [dirH, true]]) {
+              if (!dir) continue;
+              const along = (pos - L / 2) * dir, anchor = horiz ? { x: c + along, y: c + 40 } : { x: c + 40, y: c - along };
+              // chevron: tip leads in the travel direction
+              const tip = horiz ? { x: anchor.x + 6 * dir, y: anchor.y } : { x: anchor.x, y: anchor.y - 6 * dir };
+              const e1 = horiz ? { x: anchor.x - 6 * dir, y: anchor.y - arm } : { x: anchor.x - arm, y: anchor.y + 6 * dir };
+              const e2 = horiz ? { x: anchor.x - 6 * dir, y: anchor.y + arm } : { x: anchor.x + arm, y: anchor.y + 6 * dir };
+              if (pass === 0) {
+                stroke(layer.px, S, S, e1.x, e1.y, tip.x, tip.y, 4.6, [14, 50, 28], a * 0.8);
+                stroke(layer.px, S, S, tip.x, tip.y, e2.x, e2.y, 4.6, [14, 50, 28], a * 0.8);
+              } else {
+                stroke(layer.px, S, S, e1.x, e1.y, tip.x, tip.y, 2.6, [60, 255, 110], a);
+                stroke(layer.px, S, S, tip.x, tip.y, e2.x, e2.y, 2.6, [60, 255, 110], a);
+              }
+            }
+          }
+        }
+        layer.present(point.x - c, point.y - c, 255);
+        await new Promise((r) => setTimeout(r, Math.max(1, 16 - (performance.now() - tf))));
+      }
+    } catch (e) {
+      process.stderr.write(`ispyx: scroll effect failed (${e.message})
+`);
+    } finally {
+      layer?.destroy();
+    }
+  }
+
+  /**
+   * press_keys: key caps ("Ctrl" + "C") appear near the bottom of the screen the keys go to, hold, fade.
+   * `area` is the rectangle (desktop pixels) to centre them in. Never throws.
+   */
+  async keycaps(chords, area, cancelled = () => false) {
+    if (!this.enabled || !chords.length) return;
+    let layer = null;
+    try {
+      platform.ensurePump();
+      const pad = 16, capH = 46, gapPlus = 26, gapChord = 38;
+      const items = chords.map((chord) => chord.map((label) => ({ label, t: platform.textMask(label, 22, 600) })));
+      const plus = platform.textMask('+', 22, 600);
+      const capW = (it) => Math.max(capH, it.t.width + 30);
+      const widths = items.map((chord) => chord.reduce((sum, it) => sum + capW(it), 0) + gapPlus * (chord.length - 1));
+      const total = widths.reduce((a, b) => a + b, 0) + gapChord * (items.length - 1);
+      const W = Math.min(Math.round(total + pad * 2), Math.max(200, area.width - 20)), H = capH + pad * 2;
+      layer = new platform.Layer(W, H);
+      const px = layer.px;
+      const put = (x, y, r, g, b, a) => { // premultiplied "over"
+        if (a <= 0 || x < 0 || y < 0 || x >= W || y >= H) return;
+        const i = (y * W + x) * 4, k = 1 - a;
+        px[i] = b * a + px[i] * k; px[i + 1] = g * a + px[i + 1] * k; px[i + 2] = r * a + px[i + 2] * k; px[i + 3] = a * 255 + px[i + 3] * k;
+      };
+      const drawMask = (m, x0, y0, rgb, alpha = 1) => { for (let y = 0; y < m.height; y++) for (let x = 0; x < m.width; x++) put(x0 + x, y0 + y, rgb[0], rgb[1], rgb[2], (m.mask[y * m.width + x] / 255) * alpha); };
+      let x = Math.round((W - total) / 2);
+      const y0 = pad;
+      items.forEach((chord, ci) => {
+        chord.forEach((it, ki) => {
+          const cw = capW(it);
+          for (let yy = 0; yy < capH; yy++) {
+            for (let xx = 0; xx < cw; xx++) {
+              const dx = Math.min(xx, cw - 1 - xx), dy = Math.min(yy, capH - 1 - yy);
+              const rr = 10, cx = Math.max(0, rr - dx), cy = Math.max(0, rr - dy);
+              const dist = Math.hypot(cx, cy) - rr; // < 0 inside the rounded rectangle
+              const inside = clamp(0.5 - dist);
+              const edge = clamp(0.5 - (Math.abs(dist + 1.2) - 1.2));
+              const top = clamp(1 - yy / capH);
+              put(x + xx, y0 + yy, mix(26, 52, top * 0.5), mix(30, 56, top * 0.5), mix(36, 62, top * 0.5), inside * 0.94);
+              put(x + xx, y0 + yy, 60, 255, 110, edge * inside);
+            }
+          }
+          drawMask(it.t, x + Math.round((cw - it.t.width) / 2), y0 + Math.round((capH - it.t.height) / 2), [245, 250, 247]);
+          x += cw;
+          if (ki < chord.length - 1) { drawMask(plus, x + Math.round((gapPlus - plus.width) / 2), y0 + Math.round((capH - plus.height) / 2), [150, 255, 180]); x += gapPlus; }
+        });
+        if (ci < items.length - 1) x += gapChord;
+      });
+      const left = Math.round(area.left + (area.width - W) / 2), top = Math.round(area.top + area.height - H - 90);
+      const hold = 420 + 140 * chords.length;
+      const t0 = performance.now();
+      for (;;) {
+        const tf = performance.now(), t = tf - t0;
+        if (t >= hold + 260 || cancelled()) break;
+        const a = t < 110 ? ease(t / 110) : t < hold ? 1 : 1 - ease((t - hold) / 260);
+        layer.present(left, top + (1 - Math.min(1, t / 110)) * 14, 255 * a);
+        await new Promise((r) => setTimeout(r, Math.max(1, 16 - (performance.now() - tf))));
+      }
+    } catch (e) {
+      process.stderr.write(`ispyx: key effect failed (${e.message})\n`);
+    } finally {
+      layer?.destroy();
+    }
+  }
+
+  /**
+   * type_text: a small pill near the bottom of the screen with a keyboard icon, a progress bar and "37 / 120".
+   * It never shows the text. `progress.n` is the characters sent so far; the pill ends when `stopped` resolves.
+   */
+  async typing(total, progress, area, stopped, cancelled = () => false) {
+    if (!this.enabled || total < 1) return;
+    let layer = null;
+    let ended = false;
+    stopped.then(() => { ended = true; });
+    try {
+      platform.ensurePump();
+      const W = 300, H = 64;
+      layer = new platform.Layer(W, H);
+      const px = layer.px;
+      const glyphs = {};
+      for (const g of '0123456789/') glyphs[g] = platform.textMask(g, 17, 600);
+      const adv = Math.max(...'0123456789'.split('').map((g) => glyphs[g].width)) + 1;
+      const put = (x, y, r, g, b, a) => {
+        if (a <= 0 || x < 0 || y < 0 || x >= W || y >= H) return;
+        const i = (y * W + x) * 4, k = 1 - a;
+        px[i] = b * a + px[i] * k; px[i + 1] = g * a + px[i + 1] * k; px[i + 2] = r * a + px[i + 2] * k; px[i + 3] = a * 255 + px[i + 3] * k;
+      };
+      const roundRect = (x0, y0, w0, h0, rad, fill, alpha, border) => {
+        for (let y = 0; y < h0; y++) for (let x = 0; x < w0; x++) {
+          const dx = Math.min(x, w0 - 1 - x), dy = Math.min(y, h0 - 1 - y);
+          const dist = Math.hypot(Math.max(0, rad - dx), Math.max(0, rad - dy)) - rad;
+          const inside = clamp(0.5 - dist);
+          if (fill) put(x0 + x, y0 + y, fill[0], fill[1], fill[2], inside * alpha);
+          if (border) put(x0 + x, y0 + y, border[0], border[1], border[2], clamp(0.5 - (Math.abs(dist + 1.2) - 1.2)) * inside);
+        }
+      };
+      const draw = (n) => {
+        px.fill(0);
+        roundRect(0, 0, W, H, 14, [26, 30, 36], 0.94, [60, 255, 110]);
+        // keyboard icon
+        roundRect(16, 20, 32, 24, 5, null, 0, [60, 255, 110]);
+        for (let r = 0; r < 2; r++) for (let c = 0; c < 4; c++) roundRect(21 + c * 6, 25 + r * 6, 4, 4, 1, [150, 255, 180], 1, null);
+        roundRect(24, 37, 16, 3, 1, [150, 255, 180], 1, null);
+        // counter "37 / 120" (glyph by glyph; fixed advance for digits)
+        let x = 66;
+        for (const ch of String(n) + ' / ' + String(total)) {
+          if (ch === ' ') { x += 5; continue; }
+          const g = glyphs[ch]; if (!g) continue;
+          const dx = ch === '/' ? 0 : Math.round((adv - g.width) / 2);
+          for (let yy = 0; yy < g.height; yy++) for (let xx = 0; xx < g.width; xx++) put(x + dx + xx, 10 + yy, 245, 250, 247, g.mask[yy * g.width + xx] / 255);
+          x += ch === '/' ? g.width : adv;
+        }
+        // progress bar
+        const bx = 66, bw = W - 66 - 18, by = 40;
+        roundRect(bx, by, bw, 8, 4, [58, 64, 72], 1, null);
+        const fw = Math.max(0, Math.round(bw * clamp(n / total)));
+        if (fw >= 2) roundRect(bx, by, fw, 8, 4, [60, 255, 110], 1, null);
+      };
+      const left = Math.round(area.left + (area.width - W) / 2), top = Math.round(area.top + area.height - H - 90);
+      const t0 = performance.now();
+      let endAt = 0;
+      for (;;) {
+        const t = performance.now() - t0;
+        if (cancelled()) break;
+        if (ended && t >= 500 && !endAt) endAt = t;
+        if (endAt && t - endAt > 260) break;
+        draw(Math.min(progress.n, total));
+        const a = endAt ? 1 - ease(clamp((t - endAt) / 260)) : ease(clamp(t / 110));
+        layer.present(left, top + (1 - Math.min(1, t / 110)) * 14, 255 * a);
+        await new Promise((r) => setTimeout(r, 33));
+      }
+    } catch (e) {
+      process.stderr.write(`ispyx: typing effect failed (${e.message})\n`);
+    } finally {
+      layer?.destroy();
+    }
+  }
+
+  /**
+   * list_windows: an eye opens in the middle of the monitor and sends out one sonar ping: a ring that expands to
+   * the corners. A window's frame lights when the ring reaches its nearest edge (so the nearest windows light
+   * first), then everything fades. Green = usable, red = on the denylist, amber = elevated (cannot be controlled).
+   * `wins`: [{ rect, allowed, elevated }] in desktop pixels.
+   */
+  async radar(wins, area, cancelled = () => false, opts = {}) {
+    if (!this.enabled) return;
+    let frames = null, eye = null;
+    try {
+      const W = area.width, H = area.height;
+      // `opts.origin` (desktop pixels) puts the eye elsewhere than the middle of `area`: with several monitors one
+      // eye sits on one of them and the ring carries on across the others (`opts.reach`, `opts.t0` keep them in step)
+      const cx = opts.origin ? opts.origin.x - area.left : W / 2, cy = opts.origin ? opts.origin.y - area.top : H / 2;
+      const hasEye = cx >= 0 && cx < W && cy >= 0 && cy < H;
+      const list = wins
+        .map((x) => {
+          const l = Math.max(area.left, x.rect.left), t = Math.max(area.top, x.rect.top);
+          const r = Math.min(area.left + W, x.rect.left + x.rect.width), bt = Math.min(area.top + H, x.rect.top + x.rect.height);
+          const q = { x0: l - area.left, y0: t - area.top, x1: r - area.left - 1, y1: bt - area.top - 1, rgb: x.allowed === false ? [255, 80, 80] : x.elevated ? [255, 190, 40] : [60, 255, 110] };
+          q.dist = Math.hypot(Math.max(q.x0 - cx, 0, cx - q.x1), Math.max(q.y0 - cy, 0, cy - q.y1)); // eye to the nearest edge
+          return q;
+        })
+        .filter((q) => q.x1 - q.x0 >= 60 && q.y1 - q.y0 >= 40)
+        .slice(0, 14);
+      if (!list.length && !opts.origin) return;
+      platform.ensurePump();
+      const esize = Math.round(clamp(Math.min(W, H) * 0.11, 72, 124));
+      const reach = opts.reach ?? Math.hypot(cx, cy) + 60; // the rings run past the farthest corner
+      frames = new platform.Layer(W, H);
+      if (hasEye) eye = new platform.Layer(esize, esize);
+      const OPEN = 300, PING = 1300, FADE = 450;
+      const END = OPEN + PING;
+      const front = (t) => (t < OPEN ? -1 : easeOut(clamp((t - OPEN) / PING)) * reach); // ring radius, -1 = not yet
+      const t0 = opts.t0 ?? performance.now();
+      const stats = (this.stats = { frames: 0, drawMs: 0, presentMs: 0 }); // frame cost, for tuning
+      for (;;) {
+        const t = performance.now() - t0;
+        if (t >= END + FADE || cancelled()) break;
+        const tf = performance.now();
+        const out = t > END ? 1 - ease(clamp((t - END) / FADE)) : 1;
+        const r1 = front(t);
+        frames.px.fill(0);
+        if (r1 > 2 && r1 < reach) drawRing(frames.px, W, H, cx, cy, r1, 70, out * (1 - 0.5 * (r1 / reach)));
+        for (const q of list) {
+          if (r1 < q.dist) continue; // the first ring has not got there
+          const since = (r1 - q.dist) / reach * PING; // roughly how long ago the ring passed
+          drawBorder(frames.px, W, H, q.x0, q.y0, q.x1, q.y1, q.rgb, out, since < 170 ? 5 : 3);
+        }
+        const td = performance.now();
+        frames.present(area.left, area.top, 255);
+        stats.presentMs += performance.now() - td; stats.drawMs += td - tf; stats.frames++;
+        if (eye) {
+          const open = t < OPEN ? ease(t / OPEN) : t > END ? 1 - ease(clamp((t - END) / FADE)) : 1;
+          const pulse = Math.max(0, 1 - Math.abs(t - OPEN - 80) / 260); // the pupil flares as the ping leaves
+          renderEye(eye.px, esize, open, 0, 0.15, pulse);
+          eye.present(area.left + cx - esize / 2, area.top + cy - esize / 2, 255 * Math.min(ease(clamp(t / OPEN)), out));
+        }
+        await new Promise((r) => setTimeout(r, Math.max(1, 16 - (performance.now() - tf))));
+      }
+    } catch (e) {
+      process.stderr.write(`ispyx: window scan effect failed (${e.message})\n`);
+    } finally {
+      eye?.destroy();
+      frames?.destroy();
+    }
+  }
+
+  /**
+   * The radar over all monitors (`areas`): one eye in the middle of `home`, one ping that runs on across the others.
+   * This is the one entry point; `radar` alone draws a single monitor.
+   */
+  radarAll(wins, areas, home, cancelled = () => false) {
+    const origin = { x: home.left + home.width / 2, y: home.top + home.height / 2 };
+    const reach = Math.max(...areas.flatMap((a) => [a.left, a.left + a.width].flatMap((x) => [a.top, a.top + a.height].map((y) => Math.hypot(x - origin.x, y - origin.y))))) + 60;
+    const opts = { origin, reach, t0: performance.now() };
+    return Promise.all(areas.map((a) => this.radar(wins, a, cancelled, opts)));
+  }
+
+  /**
+   * wait: a small pill near the bottom of the screen with an hourglass, the time left ("4.2 s") and a bar that
+   * runs down. Lasts `ms`, then fades. Never throws.
+   */
+  async countdown(ms, area, cancelled = () => false) {
+    if (!this.enabled || ms < 1) return;
+    let layer = null;
+    try {
+      platform.ensurePump();
+      const W = 220, H = 64;
+      layer = new platform.Layer(W, H);
+      const px = layer.px;
+      const glyphs = {};
+      for (const g of '0123456789.s') glyphs[g] = platform.textMask(g, 17, 600);
+      const adv = Math.max(...'0123456789'.split('').map((g) => glyphs[g].width)) + 1;
+      const put = (x, y, r, g, b, a) => {
+        if (a <= 0 || x < 0 || y < 0 || x >= W || y >= H) return;
+        const i = (y * W + x) * 4, k = 1 - a;
+        px[i] = b * a + px[i] * k; px[i + 1] = g * a + px[i + 1] * k; px[i + 2] = r * a + px[i + 2] * k; px[i + 3] = a * 255 + px[i + 3] * k;
+      };
+      const roundRect = (x0, y0, w0, h0, rad, fill, alpha, border) => {
+        for (let y = 0; y < h0; y++) for (let x = 0; x < w0; x++) {
+          const dx = Math.min(x, w0 - 1 - x), dy = Math.min(y, h0 - 1 - y);
+          const dist = Math.hypot(Math.max(0, rad - dx), Math.max(0, rad - dy)) - rad;
+          const inside = clamp(0.5 - dist);
+          if (fill) put(x0 + x, y0 + y, fill[0], fill[1], fill[2], inside * alpha);
+          if (border) put(x0 + x, y0 + y, border[0], border[1], border[2], clamp(0.5 - (Math.abs(dist + 1.2) - 1.2)) * inside);
+        }
+      };
+      // hourglass: two triangles; the top one empties as the sand moves to the bottom one
+      const hourglass = (cx, cy, k) => {
+        const hw = 10, hh = 12;
+        for (let y = -hh; y <= hh; y++) {
+          const w0 = Math.abs(y) / hh * hw; // half width of the glass at this row
+          for (let x = -hw; x <= hw; x++) {
+            const edge = Math.abs(Math.abs(x) - w0);
+            const inside = Math.abs(x) <= w0;
+            if (edge < 1.1) put(cx + x, cy + y, 150, 255, 180, 1 - edge / 1.6);
+            else if (inside) {
+              const top = y < 0, depth = top ? -y / hh : y / hh; // 0 at the neck, 1 at the end
+              const filled = top ? depth > k * 0.9 : depth > 1 - k * 0.9; // top drains from the neck up, bottom fills from the end
+              if (filled) put(cx + x, cy + y, 60, 255, 110, 0.85);
+            }
+          }
+        }
+      };
+      const draw = (left, frac) => {
+        px.fill(0);
+        roundRect(0, 0, W, H, 14, [26, 30, 36], 0.94, [60, 255, 110]);
+        hourglass(30, 32, 1 - frac);
+        let x = 62;
+        const s = (left / 1000).toFixed(1);
+        for (const ch of s + ' s') {
+          if (ch === ' ') { x += 5; continue; }
+          const g = glyphs[ch]; if (!g) continue;
+          const dx = ch === '.' ? 0 : ch === 's' ? 0 : Math.round((adv - g.width) / 2);
+          for (let yy = 0; yy < g.height; yy++) for (let xx = 0; xx < g.width; xx++) put(x + dx + xx, 10 + yy, 245, 250, 247, g.mask[yy * g.width + xx] / 255);
+          x += ch === '.' || ch === 's' ? g.width + 1 : adv;
+        }
+        const bx = 62, bw = W - 62 - 18, by = 40;
+        roundRect(bx, by, bw, 8, 4, [58, 64, 72], 1, null);
+        const fw = Math.round(bw * clamp(frac));
+        if (fw >= 2) roundRect(bx, by, fw, 8, 4, [60, 255, 110], 1, null);
+      };
+      const left0 = Math.round(area.left + (area.width - W) / 2), top0 = Math.round(area.top + area.height - H - 90);
+      const t0 = performance.now(), FADE = 260;
+      for (;;) {
+        const tf = performance.now(), t = tf - t0;
+        if (t >= ms + FADE || cancelled()) break;
+        const remaining = Math.max(0, ms - t);
+        draw(remaining, remaining / ms);
+        const a = t > ms ? 1 - ease(clamp((t - ms) / FADE)) : ease(clamp(t / 160));
+        layer.present(left0, top0 + (1 - Math.min(1, t / 160)) * 14, 255 * a);
+        await new Promise((r) => setTimeout(r, Math.max(1, 33 - (performance.now() - tf))));
+      }
+    } catch (e) {
+      process.stderr.write(`ispyx: wait effect failed (${e.message})\n`);
+    } finally {
+      layer?.destroy();
+    }
+  }
+
+  /** click: expanding rings at the pressed point (colour by button, one ring per click). Never throws. */
+  async ripple(point, button = 'left', rings = 1, cancelled = () => false) {
+    if (!this.enabled) return;
+    let layer = null;
+    try {
+      platform.ensurePump();
+      layer = new platform.Layer(RIPPLE_SIZE, RIPPLE_SIZE);
+      const rgb = RIPPLE_COLORS[button] ?? RIPPLE_COLORS.left;
+      const total = RIPPLE_MS + (rings - 1) * RIPPLE_GAP_MS;
+      const t0 = performance.now();
+      for (;;) {
+        const tf = performance.now(), t = tf - t0;
+        if (t >= total || cancelled()) break;
+        renderRipple(layer.px, RIPPLE_SIZE, t, rings, rgb);
+        layer.present(point.x - RIPPLE_SIZE / 2, point.y - RIPPLE_SIZE / 2, 255);
+        await new Promise((r) => setTimeout(r, Math.max(1, 16 - (performance.now() - tf))));
+      }
+    } catch (e) {
+      process.stderr.write(`ispyx: click effect failed (${e.message})
+`);
+    } finally {
+      layer?.destroy();
+    }
+  }
+
+  /** focus_window: a green frame lights up around the window (clipped to the desktop) and fades. Never throws. */
+  async flash(rect, cancelled = () => false) {
+    if (!this.enabled) return;
+    let layer = null;
+    try {
+      const v = platform.virtualScreen();
+      const left = Math.max(rect.left, v.x), top = Math.max(rect.top, v.y);
+      const right = Math.min(rect.left + rect.width, v.x + v.width), bottom = Math.min(rect.top + rect.height, v.y + v.height);
+      if (right - left < 20 || bottom - top < 20) return;
+      platform.ensurePump();
+      layer = new platform.Layer(right - left, bottom - top);
+      renderFrame(layer.px, layer.width, layer.height);
+      const t0 = performance.now();
+      for (;;) {
+        const tf = performance.now(), t = tf - t0;
+        if (t >= FLASH_TOTAL_MS || cancelled()) break;
+        // on, a short dip, on again (a double blink catches the eye), then fade
+        const a = t < 80 ? t / 80 : t < 280 ? 1 : t < 380 ? 1 - 0.65 * Math.sin(((t - 280) / 100) * Math.PI) : t < 480 ? 1 : 1 - ease((t - 480) / (FLASH_TOTAL_MS - 480));
+        layer.present(left, top, 255 * a);
+        await new Promise((r) => setTimeout(r, Math.max(1, 16 - (performance.now() - tf))));
+      }
+    } catch (e) {
+      process.stderr.write(`ispyx: focus effect failed (${e.message})
+`);
+    } finally {
+      layer?.destroy();
+    }
+  }
+
+  /**
+   * Plays the animation over `rect` (desktop pixels) and resolves when it is over. `cancelled()` is polled each
+   * frame; the windows are always removed. Never throws: a failed animation must not break a screenshot.
+   */
+  async play(rect, cancelled = () => false) {
+    if (!this.enabled) return;
+    let wedge = null, band = null, eye = null;
+    try {
+      platform.ensurePump();
+      const size = Math.round(clamp(Math.min(rect.width, rect.height) * 0.3, 56, 150));
+      const bandH = 56;
+      // the eye floats beside the region (alternating sides; the side with more room if only one fits) and looks at it
+      // (room is measured on the monitor holding the region's centre; with no room, as for a full-screen scan,
+      // the eye sits inside the region, inset from its left or right edge)
+      const cxr = rect.left + rect.width / 2, cyr = rect.top + rect.height / 2;
+      const mon = platform.listMonitors().find((m) => cxr >= m.left && cxr < m.left + m.width && cyr >= m.top && cyr < m.top + m.height) ?? platform.virtualScreen();
+      const m = { x: mon.left ?? mon.x, y: mon.top ?? mon.y, width: mon.width, height: mon.height };
+      const gap = 18;
+      const roomL = rect.left - m.x, roomR = m.x + m.width - (rect.left + rect.width);
+      const fitsL = roomL >= size + gap, fitsR = roomR >= size + gap;
+      const left = fitsL && fitsR ? (flip = !flip) : fitsL ? true : fitsR ? false : (flip = !flip);
+      const ex = fitsL || fitsR
+        ? (left ? rect.left - size - gap : rect.left + rect.width + gap)
+        : (left ? Math.max(rect.left, m.x) + gap * 2 : Math.min(rect.left + rect.width, m.x + m.width) - size - gap * 2); // inside the region (on the monitor holding its centre)
+      const ey = clamp(rect.top + (rect.height - size) / 2, m.y, m.y + m.height - size);
+      const gx = left ? 0.95 : -0.95; // pupil towards the region
+      const pad = 4;
+      const lx = Math.floor(Math.min(ex, rect.left) - pad), rx = Math.ceil(Math.max(ex + size, rect.left + rect.width) + pad);
+      const ty = Math.floor(Math.min(ey, rect.top) - pad), by = Math.ceil(Math.max(ey + size, rect.top + rect.height) + pad);
+      wedge = new platform.Layer(rx - lx, by - ty);
+      band = new platform.Layer(Math.max(40, rect.width), bandH);
+      renderBand(band.px, band.width, bandH);
+      eye = new platform.Layer(size, size);
+      const midY = rect.top + rect.height / 2;
+      const t0 = performance.now();
+      for (;;) {
+        const tf = performance.now(), t = tf - t0;
+        if (t >= SCAN_TOTAL_MS || cancelled()) break;
+        let open, fade, p = 0;
+        if (t < T_OPEN) { open = ease(t / T_OPEN); fade = open; }
+        else if (t < T_OPEN + T_SCAN) { open = 1; fade = 1; p = ease((t - T_OPEN) / T_SCAN); }
+        else { const k = (t - T_OPEN - T_SCAN) / T_CLOSE; open = 1 - ease(k); fade = 1 - k; p = 1; }
+        const edge = rect.top + p * rect.height; // the scan line (its leading edge is the bottom)
+        // the pupil goes from upper right to lower right (mirrored when the eye is on the right) with the line
+        const gy = (p > 0 ? clamp((edge - midY) / (rect.height / 2), -1, 1) : -1) * 0.85;
+        const charge = p > 0 ? 1 : clamp((t - T_OPEN * 0.6) / (T_OPEN * 0.4)); // pupil glows just before the scan
+        renderEye(eye.px, size, open, gx, gy, charge);
+        const live = Math.min(1, p * 10, (1 - p) * 6);
+        if (p > 0 && p < 1) {
+          const pupil = pupilPos(size, gx, gy);
+          drawWedge(wedge.px, wedge.width, wedge.height, ex + pupil.x - lx, ey + pupil.y - ty, rect.left - lx, rect.left + rect.width - lx, edge - ty);
+          wedge.present(lx, ty, 255 * live);
+          band.present(rect.left + (rect.width - band.width) / 2, edge - bandH, 255 * live);
+        } else if (wedge.shown) {
+          wedge.present(lx, ty, 0, 1);
+          band.present(rect.left, rect.top, 0, 1);
+        }
+        eye.present(ex, ey, 255 * fade);
+        await new Promise((r) => setTimeout(r, Math.max(1, 16 - (performance.now() - tf))));
+      }
+    } catch (e) {
+      process.stderr.write(`ispyx: scan animation failed (${e.message})\n`);
+    } finally {
+      wedge?.destroy();
+      band?.destroy();
+      eye?.destroy();
+    }
+  }
+}