@astryxdesign/core 0.7.4 → 0.7.5-canary.0418c47

package/src/gestures/__tests__/arenaContinuous.test.ts

@@ -0,0 +1,207 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file arenaContinuous.test.ts
+ * @input GestureArena with pans, long presses, taps, consumers and scroll
+ *   probes, driven by synthetic touches with explicit timestamps
+ * @output The pan's conflicts: native scrolling (failing, scroll edge,
+ *   handoff), long press vs pan, nested pans, delegate hooks, two fingers on
+ *   two views, delivery while moving, cancellation from code, the clock
+ * @position Unit tests of packages/core/src/gestures/GestureArena.ts
+ */
+
+import {describe, expect, it} from 'vitest';
+import {LongPressGestureRecognizer} from '../LongPressGestureRecognizer';
+import {PanGestureRecognizer} from '../PanGestureRecognizer';
+import {TapGestureRecognizer} from '../TapGestureRecognizer';
+import {createHarness, RecordingConsumer, scrollProbe} from './harness';
+
+describe('conflict matrix', () => {
+  it('pan vs native scroll: the browser taking the touch fails a possible pan', () => {
+    const h = createHarness();
+    const pan = new PanGestureRecognizer({name: 'pan', direction: 'vertical'});
+    h.finger(1)
+      .down(0, 100, 0, {recognizers: [pan]})
+      .move(0, 105, 16);
+    h.finger(1).takenByBrowser(24);
+    // The touch is gone from the pan, so it is ready for the next one.
+    expect(h.log).toEqual(['pan:failed@24', 'pan:possible@24']);
+    expect(h.claims).toEqual([]);
+  });
+
+  it('pan at a scroll edge (scrollEdge): begins and claims when the content cannot scroll that way', () => {
+    const atTop = createHarness();
+    const sheet = new PanGestureRecognizer({
+      name: 'sheet',
+      direction: 'down',
+      scrollEdge: true,
+    });
+    // Content at its top: a finger moving down scrolls nothing.
+    const probe = scrollProbe((_dx, dy) => dy < 0);
+    atTop.finger(1).down(0, 100, 0, {recognizers: [sheet], scroll: probe});
+    atTop.finger(1).drag(0, 30, 50, 5);
+    expect(atTop.log[0]).toBe('sheet:began@20');
+    expect(atTop.claims).toEqual([1]);
+
+    const midContent = createHarness();
+    const scrolled = new PanGestureRecognizer({
+      name: 'sheet',
+      direction: 'down',
+      scrollEdge: true,
+    });
+    const canScrollUp = scrollProbe(() => true);
+    midContent.finger(1).down(0, 100, 0, {
+      recognizers: [scrolled],
+      scroll: canScrollUp,
+    });
+    midContent.finger(1).drag(0, 30, 50, 5);
+    expect(midContent.log).toEqual(['sheet:failed@20']);
+  });
+
+  it("a drag that began as a scroll stays the browser's past the content's edge (spec:AST-094 FR14)", () => {
+    const h = createHarness();
+    const sheet = new PanGestureRecognizer({
+      name: 'sheet',
+      direction: 'down',
+      scrollEdge: true,
+    });
+    let scrollTop = 30;
+    const finger = h.finger(1).down(0, 100, 0, {
+      recognizers: [sheet],
+      scroll: scrollProbe(() => scrollTop > 0),
+    });
+    // The content scrolls toward its top: the drag is the browser's.
+    finger.move(0, 120, 16);
+    finger.takenByBrowser(20);
+    // It reaches its top mid-gesture; the finger keeps pulling.
+    scrollTop = 0;
+    finger.move(0, 160, 32);
+    finger.move(0, 200, 48);
+    finger.up(64);
+    // It failed at its first move and is reset when the browser takes the
+    // touch: it never begins, however far the finger pulls.
+    expect(h.log).toEqual(['sheet:failed@16', 'sheet:possible@20']);
+  });
+
+  it('long press vs pan: holding still wins for the long press', () => {
+    const h = createHarness();
+    const press = new LongPressGestureRecognizer({name: 'press'});
+    const pan = new PanGestureRecognizer({name: 'pan'});
+    h.finger(1).down(0, 0, 0, {recognizers: [press, pan]});
+    h.advance(500);
+    expect(h.log).toEqual(['press:began@500', 'pan:failed@500']);
+    h.finger(1).move(80, 0, 600);
+    expect(press.state).toBe('changed');
+    expect(pan.state).toBe('failed');
+    expect(h.claims).toEqual([1]);
+  });
+
+  it('long press vs pan: moving first wins for the pan', () => {
+    const h = createHarness();
+    const press = new LongPressGestureRecognizer({name: 'press'});
+    const pan = new PanGestureRecognizer({name: 'pan'});
+    h.finger(1).down(0, 0, 0, {recognizers: [press, pan]});
+    h.finger(1).move(5, 0, 100).move(12, 0, 120);
+    expect(h.log).toEqual(['press:failed@120', 'pan:began@120']);
+    h.advance(600);
+    expect(press.state).toBe('failed');
+  });
+
+  it('nested pans that both qualify on the same move: the innermost wins', () => {
+    const h = createHarness();
+    const inner = new PanGestureRecognizer({name: 'inner'});
+    const outer = new PanGestureRecognizer({name: 'outer'});
+    h.finger(1)
+      .down(0, 0, 0, {recognizers: [inner, outer]})
+      .move(20, 0, 16);
+    expect(h.log).toEqual(['inner:began@16', 'outer:failed@16']);
+  });
+
+  it('honors shouldBegin and shouldReceiveTouch', () => {
+    const h = createHarness();
+    const refused = new PanGestureRecognizer({
+      name: 'refused',
+      shouldBegin: () => false,
+    });
+    const blind = new TapGestureRecognizer({
+      name: 'blind',
+      shouldReceiveTouch: () => false,
+    });
+    h.finger(1)
+      .down(0, 0, 0, {recognizers: [refused, blind]})
+      .move(30, 0, 16);
+    expect(h.log).toEqual(['refused:failed@16']);
+    expect(blind.numberOfTouches).toBe(0);
+  });
+
+  it('two fingers on two unrelated views drive two pans at once', () => {
+    const h = createHarness();
+    const left = new PanGestureRecognizer({name: 'left'});
+    const right = new PanGestureRecognizer({name: 'right'});
+    h.finger(1).down(50, 300, 0, {recognizers: [left]});
+    h.finger(2).down(300, 300, 0, {recognizers: [right]});
+    h.finger(1).move(50, 340, 16);
+    h.finger(2).move(300, 260, 16);
+    expect(left.state).toBe('began');
+    expect(right.state).toBe('began');
+  });
+});
+
+describe('delivery to the view', () => {
+  it('delivers an unclaimed touch to the consumer and allows its click', () => {
+    const h = createHarness();
+    const consumer = new RecordingConsumer();
+    const pan = new PanGestureRecognizer({name: 'pan'});
+    const finger = h.finger(1).down(0, 0, 0, {recognizers: [pan], consumer});
+    finger.move(3, 0, 16);
+    expect(finger.up(60)).toBe('allow');
+    expect(consumer.events).toEqual(['began:1', 'moved:1', 'ended:1']);
+  });
+
+  it('cancels the view and swallows the click when a recognizer takes the touch', () => {
+    const h = createHarness();
+    const consumer = new RecordingConsumer();
+    const pan = new PanGestureRecognizer({name: 'pan'});
+    const finger = h.finger(1).down(0, 0, 0, {recognizers: [pan], consumer});
+    finger.move(30, 0, 16).move(40, 0, 32);
+    expect(consumer.events).toEqual(['began:1', 'cancelled:1']);
+    expect(finger.up(60)).toBe('suppress');
+  });
+
+  it('keeps the view and the click with cancelsTouchesInView off', () => {
+    const h = createHarness();
+    const consumer = new RecordingConsumer();
+    const pan = new PanGestureRecognizer({
+      name: 'pan',
+      cancelsTouchesInView: false,
+    });
+    const finger = h.finger(1).down(0, 0, 0, {recognizers: [pan], consumer});
+    finger.move(30, 0, 16);
+    expect(finger.up(60)).toBe('allow');
+    expect(consumer.events).toEqual(['began:1', 'moved:1', 'ended:1']);
+  });
+});
+
+describe('cancellation', () => {
+  it('stop() cancels an active recognizer from code', () => {
+    const h = createHarness();
+    const pan = new PanGestureRecognizer({name: 'pan'});
+    h.finger(1)
+      .down(0, 0, 0, {recognizers: [pan]})
+      .move(30, 0, 16);
+    pan.cancel();
+    expect(pan.state).toBe('cancelled');
+    h.finger(1).move(60, 0, 32);
+    expect(pan.state).toBe('cancelled');
+    h.finger(1).up(48);
+    expect(pan.state).toBe('possible');
+  });
+
+  it('never moves the event clock backwards', () => {
+    const h = createHarness();
+    const pan = new PanGestureRecognizer({name: 'pan'});
+    h.finger(1).down(0, 0, 100, {recognizers: [pan]});
+    h.finger(1).move(30, 0, 90);
+    expect(h.log).toEqual(['pan:began@100']);
+  });
+});

package/src/gestures/__tests__/arenaTapLongPress.test.ts

@@ -0,0 +1,211 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file arenaTapLongPress.test.ts
+ * @input GestureArena with taps, long presses and consumers, driven by
+ *   synthetic touches with explicit timestamps
+ * @output The arena with real discrete and press recognizers: tap vs double
+ *   tap with and without require-to-fail, delegate requirements, delivery and
+ *   deferred clicks, cancellation before and after a long press began
+ * @position Unit tests of packages/core/src/gestures/GestureArena.ts; the
+ *   arena's own rules, with scripted recognizers, are in arena.test.ts
+ */
+
+import {describe, expect, it} from 'vitest';
+import {LongPressGestureRecognizer} from '../LongPressGestureRecognizer';
+import {TapGestureRecognizer} from '../TapGestureRecognizer';
+import {UIKIT_GESTURES} from '../../motion/uikit/gestures';
+import {createHarness, RecordingConsumer} from './harness';
+
+const INTERVAL = UIKIT_GESTURES.tap.maximumIntervalBetweenTaps.value;
+
+describe('conflict matrix', () => {
+  it('tap vs double tap, single requires double to fail: the single waits out the interval', () => {
+    const h = createHarness();
+    const single = new TapGestureRecognizer({name: 'single'});
+    const double = new TapGestureRecognizer({
+      name: 'double',
+      numberOfTapsRequired: 2,
+    });
+    single.requireToFail(double);
+    h.finger(1).down(0, 0, 0, {recognizers: [single, double]});
+    h.finger(1).up(80);
+    expect(single.state).toBe('possible');
+    expect(single.pending).toBe('ended');
+    h.advance(80 + INTERVAL);
+    expect(h.log).toEqual([
+      `double:failed@${80 + INTERVAL}`,
+      `single:ended@${80 + INTERVAL}`,
+      `single:possible@${80 + INTERVAL}`,
+      `double:possible@${80 + INTERVAL}`,
+    ]);
+  });
+
+  it('tap vs double tap, single requires double to fail: a double tap fails the single', () => {
+    const h = createHarness();
+    const single = new TapGestureRecognizer({name: 'single'});
+    const double = new TapGestureRecognizer({
+      name: 'double',
+      numberOfTapsRequired: 2,
+    });
+    single.requireToFail(double);
+    h.finger(1).down(0, 0, 0, {recognizers: [single, double]});
+    h.finger(1).up(80);
+    h.finger(2).down(2, 2, 200, {recognizers: [single, double]});
+    h.finger(2).up(260);
+    expect(h.log).toEqual([
+      'double:ended@260',
+      'single:failed@260',
+      'single:possible@260',
+      'double:possible@260',
+    ]);
+  });
+
+  it('tap vs double tap with no requirement: the single wins at once and fails the double', () => {
+    const h = createHarness();
+    const single = new TapGestureRecognizer({name: 'single'});
+    const double = new TapGestureRecognizer({
+      name: 'double',
+      numberOfTapsRequired: 2,
+    });
+    h.finger(1).down(0, 0, 0, {recognizers: [single, double]});
+    h.finger(1).up(80);
+    expect(h.log.slice(0, 2)).toEqual(['single:ended@80', 'double:failed@80']);
+  });
+
+  it('a recognizer that is not involved holds nothing up', () => {
+    const h = createHarness();
+    const idle = new TapGestureRecognizer({name: 'idle'});
+    const tap = new TapGestureRecognizer({name: 'tap'});
+    tap.requireToFail(idle);
+    h.finger(1).down(0, 0, 0, {recognizers: [tap]});
+    h.finger(1).up(50);
+    expect(h.log[0]).toBe('tap:ended@50');
+  });
+
+  it('honors delegate failure requirements', () => {
+    const h = createHarness();
+    const double = new TapGestureRecognizer({
+      name: 'double',
+      numberOfTapsRequired: 2,
+    });
+    const single = new TapGestureRecognizer({
+      name: 'single',
+      shouldRequireFailureOf: (_self, other) => other === double,
+    });
+    h.finger(1).down(0, 0, 0, {recognizers: [single, double]});
+    h.finger(1).up(50);
+    expect(single.pending).toBe('ended');
+  });
+});
+
+describe('delivery to the view', () => {
+  it('delivers an unclaimed touch to the consumer and allows its click', () => {
+    const h = createHarness();
+    const consumer = new RecordingConsumer();
+    const press = new LongPressGestureRecognizer({name: 'press'});
+    const finger = h.finger(1).down(0, 0, 0, {recognizers: [press], consumer});
+    finger.move(3, 0, 16);
+    expect(finger.up(60)).toBe('allow');
+    expect(consumer.events).toEqual(['began:1', 'moved:1', 'ended:1']);
+  });
+
+  it('cancels the view and swallows the click when a recognizer takes the touch', () => {
+    const h = createHarness();
+    const consumer = new RecordingConsumer();
+    const press = new LongPressGestureRecognizer({name: 'press'});
+    const finger = h.finger(1).down(0, 0, 0, {recognizers: [press], consumer});
+    h.advance(500);
+    expect(consumer.events).toEqual(['began:1', 'cancelled:1']);
+    expect(h.claims).toEqual([1]);
+    expect(finger.up(600)).toBe('suppress');
+  });
+
+  it('keeps the view and the click with cancelsTouchesInView off', () => {
+    const h = createHarness();
+    const consumer = new RecordingConsumer();
+    const press = new LongPressGestureRecognizer({
+      name: 'press',
+      cancelsTouchesInView: false,
+    });
+    const finger = h.finger(1).down(0, 0, 0, {recognizers: [press], consumer});
+    h.advance(500);
+    expect(finger.up(600)).toBe('allow');
+    expect(consumer.events).toEqual(['began:1', 'ended:1']);
+  });
+
+  it('defers the click of a tap a double tap may still claim, then replays it', () => {
+    const h = createHarness();
+    const consumer = new RecordingConsumer();
+    const double = new TapGestureRecognizer({
+      name: 'double',
+      numberOfTapsRequired: 2,
+    });
+    const finger = h.finger(1).down(0, 0, 0, {recognizers: [double], consumer});
+    expect(finger.up(70)).toBe('defer');
+    expect(consumer.events).toEqual(['began:1']);
+    h.advance(70 + INTERVAL);
+    expect(consumer.events).toEqual(['began:1', 'ended:1']);
+    expect(h.deferredClicks).toEqual([
+      {id: 1, allowed: true, time: 70 + INTERVAL},
+    ]);
+  });
+
+  it('drops the deferred click when the double tap is recognized', () => {
+    const h = createHarness();
+    const consumer = new RecordingConsumer();
+    const double = new TapGestureRecognizer({
+      name: 'double',
+      numberOfTapsRequired: 2,
+    });
+    h.finger(1).down(0, 0, 0, {recognizers: [double], consumer});
+    h.finger(1).up(70);
+    h.finger(2).down(1, 1, 150, {recognizers: [double], consumer});
+    expect(h.finger(2).up(210)).toBe('suppress');
+    expect(h.deferredClicks).toEqual([{id: 1, allowed: false, time: 210}]);
+    expect(consumer.events).toEqual([
+      'began:1',
+      'began:2',
+      'cancelled:1',
+      'cancelled:2',
+    ]);
+  });
+
+  it('cancels the view when the browser takes the touch', () => {
+    const h = createHarness();
+    const consumer = new RecordingConsumer();
+    const tap = new TapGestureRecognizer({name: 'tap'});
+    const finger = h.finger(1).down(0, 0, 0, {recognizers: [tap], consumer});
+    finger.takenByBrowser(30);
+    expect(consumer.events).toEqual(['began:1', 'cancelled:1']);
+    expect(h.log).toEqual(['tap:failed@30', 'tap:possible@30']);
+  });
+});
+
+describe('cancellation', () => {
+  it('a system cancel cancels an active gesture and fails a possible one', () => {
+    const h = createHarness();
+    const press = new LongPressGestureRecognizer({name: 'press'});
+    const tap = new TapGestureRecognizer({name: 'tap'});
+    h.finger(1).down(0, 0, 0, {recognizers: [press]});
+    h.advance(500);
+    h.finger(2).down(100, 0, 600, {recognizers: [tap]});
+    h.arena.cancelled([1, 2], 650);
+    expect(h.log).toEqual([
+      'press:began@500',
+      'press:cancelled@650',
+      'tap:failed@650',
+      'press:possible@650',
+      'tap:possible@650',
+    ]);
+  });
+
+  it('a long press cancelled before its duration never begins', () => {
+    const h = createHarness();
+    const press = new LongPressGestureRecognizer({name: 'press'});
+    h.finger(1).down(0, 0, 0, {recognizers: [press]});
+    h.finger(1).cancel(200);
+    h.advance(1000);
+    expect(h.log).toEqual(['press:failed@200', 'press:possible@200']);
+  });
+});

package/src/gestures/__tests__/harness.ts

@@ -0,0 +1,204 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file harness.ts
+ * @input Nothing
+ * @output Exports the synthetic-input harness the gesture tests share: a
+ *   manual clock, an arena wired to a transition log, and fingers that land,
+ *   move and lift at explicit timestamps
+ * @position Test-only helper of packages/core/src/gestures (excluded from the
+ *   build with the rest of __tests__)
+ */
+
+import {GestureArena, type GestureClock} from '../GestureArena';
+import type {GestureRecognizer} from '../GestureRecognizer';
+import type {
+  GestureEnvironment,
+  GestureTouch,
+  NativeScrollProbe,
+  TouchConsumer,
+} from '../types';
+
+/** A clock that only moves when the test says so. */
+export class ManualClock implements GestureClock {
+  time = 0;
+  now(): number {
+    return this.time;
+  }
+  setTimeout(): number {
+    return 0;
+  }
+  clearTimeout(): void {}
+}
+
+export interface Harness {
+  arena: GestureArena;
+  clock: ManualClock;
+  /** `name:state` for every transition, in order, with its time. */
+  log: string[];
+  /** Touch ids claimed from the browser, in order. */
+  claims: number[];
+  /** Deferred clicks as they resolved. */
+  deferredClicks: {id: number; allowed: boolean; time: number}[];
+  environment: {width: number; height: number; rtl: boolean};
+  finger(id: number): Finger;
+  /** Advance the clock and run every timer due by `time`. */
+  advance(time: number): void;
+}
+
+export function createHarness(): Harness {
+  const clock = new ManualClock();
+  const log: string[] = [];
+  const claims: number[] = [];
+  const deferredClicks: Harness['deferredClicks'] = [];
+  const environment = {width: 390, height: 844, rtl: false};
+  const fingers = new Map<number, Finger>();
+  const env: GestureEnvironment = {
+    viewportSize: () => ({
+      width: environment.width,
+      height: environment.height,
+    }),
+    isRtl: () => environment.rtl,
+  };
+  const arena: GestureArena = new GestureArena({
+    clock,
+    environment: env,
+    onTransition: (recognizer, _from, to) => {
+      log.push(`${recognizer.name}:${to}@${round(arena.now())}`);
+    },
+    onClaim: ids => claims.push(...ids),
+    onDeferredClick: (touch, allowed) =>
+      deferredClicks.push({id: touch.id, allowed, time: arena.now()}),
+  });
+  const harness: Harness = {
+    arena,
+    clock,
+    log,
+    claims,
+    deferredClicks,
+    environment,
+    finger: id => {
+      let finger = fingers.get(id);
+      if (finger == null) {
+        finger = new Finger(harness, id);
+        fingers.set(id, finger);
+      }
+      return finger;
+    },
+    advance: time => {
+      clock.time = time;
+      arena.advanceTime(time);
+    },
+  };
+  return harness;
+}
+
+function round(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+export interface DownOptions {
+  recognizers: ReadonlyArray<GestureRecognizer>;
+  consumer?: TouchConsumer | null;
+  scroll?: NativeScrollProbe | null;
+  pointerType?: 'touch' | 'mouse' | 'pen';
+  target?: unknown;
+}
+
+/** One contact, driven with explicit timestamps. */
+export class Finger {
+  x = 0;
+  y = 0;
+  time = 0;
+  constructor(
+    private readonly harness: Harness,
+    readonly id: number,
+  ) {}
+
+  down(x: number, y: number, time: number, options: DownOptions): this {
+    this.x = x;
+    this.y = y;
+    this.time = time;
+    this.harness.clock.time = time;
+    this.harness.arena.began([
+      {
+        id: this.id,
+        x,
+        y,
+        time,
+        pointerType: options.pointerType ?? 'touch',
+        target: options.target ?? null,
+        scroll: options.scroll ?? null,
+        recognizers: options.recognizers,
+        consumer: options.consumer ?? null,
+      },
+    ]);
+    return this;
+  }
+
+  move(x: number, y: number, time: number): this {
+    this.x = x;
+    this.y = y;
+    this.time = time;
+    this.harness.clock.time = time;
+    this.harness.arena.moved([{id: this.id, x, y, time}]);
+    return this;
+  }
+
+  /** Move in `steps` equal steps over `duration` ms. */
+  drag(dx: number, dy: number, duration: number, steps = 8): this {
+    const x0 = this.x;
+    const y0 = this.y;
+    const t0 = this.time;
+    for (let i = 1; i <= steps; i++) {
+      const k = i / steps;
+      this.move(x0 + dx * k, y0 + dy * k, t0 + duration * k);
+    }
+    return this;
+  }
+
+  up(time: number, x = this.x, y = this.y) {
+    this.time = time;
+    this.harness.clock.time = time;
+    return this.harness.arena.ended([{id: this.id, x, y, time}]).get(this.id);
+  }
+
+  cancel(time: number): void {
+    this.harness.clock.time = time;
+    this.harness.arena.cancelled([this.id], time);
+  }
+
+  takenByBrowser(time: number): void {
+    this.harness.clock.time = time;
+    this.harness.arena.browserTookOver([this.id], time);
+  }
+}
+
+/** A consumer that records what the arena delivered to it. */
+export class RecordingConsumer implements TouchConsumer {
+  events: string[] = [];
+  veto: ((recognizer: unknown) => boolean) | null = null;
+  touchBegan(touch: GestureTouch): void {
+    this.events.push(`began:${touch.id}`);
+  }
+  touchMoved(touch: GestureTouch): void {
+    this.events.push(`moved:${touch.id}`);
+  }
+  touchEnded(touch: GestureTouch): void {
+    this.events.push(`ended:${touch.id}`);
+  }
+  touchCancelled(touch: GestureTouch): void {
+    this.events.push(`cancelled:${touch.id}`);
+  }
+  allowsAncestorRecognizer(recognizer: unknown): boolean {
+    return this.veto == null ? true : !this.veto(recognizer);
+  }
+}
+
+/** A scroll probe with a scripted answer. */
+export function scrollProbe(
+  canScroll: (dx: number, dy: number) => boolean,
+  isInsideScroller = true,
+): NativeScrollProbe {
+  return {canScroll, isInsideScroller, allowsNativePan: true};
+}

package/src/gestures/geometry.ts

@@ -0,0 +1,55 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file geometry.ts
+ * @input Touches
+ * @output Exports the small geometry helpers recognizers share: centroid,
+ *   distance, span and angle of two touches, angle unwrapping
+ * @position Pure helpers under packages/core/src/gestures
+ */
+
+import type {GestureTouch, Point} from './types';
+
+export function centroid(
+  touches: Iterable<GestureTouch>,
+  excluding?: ReadonlySet<number>,
+): Point {
+  let x = 0;
+  let y = 0;
+  let count = 0;
+  for (const touch of touches) {
+    if (excluding?.has(touch.id)) {
+      continue;
+    }
+    x += touch.x;
+    y += touch.y;
+    count += 1;
+  }
+  return count === 0 ? {x: 0, y: 0} : {x: x / count, y: y / count};
+}
+
+export function distance(a: Point, b: Point): number {
+  return Math.hypot(a.x - b.x, a.y - b.y);
+}
+
+/** How far a touch is from where it landed. */
+export function travel(touch: GestureTouch): number {
+  return Math.hypot(touch.x - touch.startX, touch.y - touch.startY);
+}
+
+/** The angle of the vector from the first touch to the second, radians. */
+export function angleBetween(a: Point, b: Point): number {
+  return Math.atan2(b.y - a.y, b.x - a.x);
+}
+
+/** `angle` shifted by whole turns to be within half a turn of `reference`. */
+export function unwrapAngle(angle: number, reference: number): number {
+  let result = angle;
+  while (result - reference > Math.PI) {
+    result -= 2 * Math.PI;
+  }
+  while (result - reference < -Math.PI) {
+    result += 2 * Math.PI;
+  }
+  return result;
+}