@swiftbrowser/web 0.17.8 → 0.18.0

package/src/editorSelection.ts

@@ -0,0 +1,80 @@
+/**
+ * The selection a bound `texteditor` shares with the app (docs/ops-protocol.md,
+ * "Rich text editors"), the same for the rich editor (src/richEditor.ts) and
+ * the plain textarea (src/plainEditor.ts): what the editor last reported, or
+ * was last moved to, so a selection coming back from the app is not applied
+ * again and the viewer's is not echoed; and one the app set while the editor
+ * was not focused, kept for when the app focuses it.
+ */
+
+import type { TextSelectionRange } from './protocol';
+
+/** The selection each bound editor last reported, or was last moved to. */
+const reported = new WeakMap<HTMLElement, string>();
+/** A selection the app set while the editor was not focused: where its caret goes when the app focuses it. */
+const pending = new WeakMap<HTMLElement, TextSelectionRange>();
+
+const key = (range: TextSelectionRange): string => `${range.start}:${range.end}`;
+
+/** Whether the editor's `selection` is bound (the prop is in its props): only then is the viewer's reported. */
+export function markSelectionBound(el: HTMLElement, bound: boolean): void {
+  if (bound) el.dataset['sbSelection'] = '';
+  else delete el.dataset['sbSelection'];
+}
+
+export function isSelectionBound(el: HTMLElement): boolean {
+  return el.dataset['sbSelection'] !== undefined;
+}
+
+/**
+ * Whether the field or editor has `deleteBackward` in its props: Backspace
+ * with nothing selected and the caret at offset 0 then sends `deletebackward`
+ * and deletes nothing (docs/ops-protocol.md, "The delete key at the start of
+ * a field"); the same mark for a `textfield`, a plain editor and a rich one.
+ */
+export function markDeleteBackward(el: HTMLElement, wanted: boolean): void {
+  if (wanted) el.dataset['sbDeleteBackward'] = '';
+  else delete el.dataset['sbDeleteBackward'];
+}
+
+export function wantsDeleteBackward(el: HTMLElement): boolean {
+  return el.dataset['sbDeleteBackward'] !== undefined;
+}
+
+/**
+ * The app sent `range` (or no selection): the range the editor moves to now,
+ * when it is focused; otherwise null, the range kept for `takePendingSelection`
+ * when the app focuses the editor. Nothing for the selection the editor
+ * itself reported, coming back.
+ */
+export function selectionToApply(el: HTMLElement, range: TextSelectionRange | undefined): TextSelectionRange | null {
+  if (!range || reported.get(el) === key(range)) return null;
+  reported.set(el, key(range));
+  if (el.ownerDocument.activeElement === el) return range;
+  pending.set(el, range);
+  return null;
+}
+
+/** The selection the app set while the editor was not focused, taken as the app focuses it. */
+export function takePendingSelection(el: HTMLElement): TextSelectionRange | undefined {
+  const range = pending.get(el);
+  pending.delete(el);
+  return range;
+}
+
+/** The viewer's selection: whether it is new (not the one the app set or the editor last reported), and so to report. */
+export function noteViewerSelection(el: HTMLElement, range: TextSelectionRange): boolean {
+  if (reported.get(el) === key(range)) return false;
+  reported.set(el, key(range));
+  return true;
+}
+
+/** The viewer focused the editor: their caret, not one the app set before. */
+export function viewerFocused(el: HTMLElement): void {
+  pending.delete(el);
+}
+
+/** The editor lost focus: it has no caret, so the selection the app holds is one to move to again. */
+export function editorBlurred(el: HTMLElement): void {
+  reported.delete(el);
+}

package/src/files.ts

@@ -0,0 +1,442 @@
+/**
+ * The app's files from JavaScript: `FileManager` in @swiftbrowser/react
+ * (packages/react/src/fileManager.ts) over the `files` field of the host
+ * request environment, a `FilesHost`. On a page the host is this module: the
+ * same iOS-like home a Swift app has (appFiles.ts, "Phase 19"), `/data` with
+ * `Documents`, `Library/Application Support` and `Library/Caches`, kept in
+ * the app's IndexedDB database (`sb-files:<App>`, the `entries` store, one
+ * row per file or directory), and `/tmp`, kept in memory for the session.
+ * Natively the host is the app's sandbox (packages/native/src/hostRequests.ts,
+ * Host/FilesBridge.swift). Paths are `file:` URLs on both sides, and
+ * `loadURL` turns one into a URL a media element or an image can load (an
+ * object URL of the bytes here, the URL itself natively), which the renderer
+ * does for a `file:` URL in a `video` or `image` element.
+ */
+
+import { ENTRIES, HOME, HOME_DIRECTORIES, TMP, done, openFilesDatabase, request, type EntryRow } from './appFiles';
+
+/** What `attributes` answers for a file or directory that exists. */
+export interface FileAttributes {
+  /** The file's bytes; 0 for a directory. */
+  size: number;
+  /** When it was last written, in milliseconds since the epoch, where the host knows. */
+  modified: number | null;
+  directory: boolean;
+}
+
+/** The app's standard directories, as `file:` URLs. */
+export interface FileDirectories {
+  documents: string;
+  applicationSupport: string;
+  caches: string;
+  temporary: string;
+}
+
+/**
+ * The host of the app's files. Every URL is a `file:` URL in the app's home;
+ * one outside it fails `unsupported: …`. Failures are errors whose message
+ * starts with a word and a colon: `notFound: …` (no such file or directory,
+ * or the destination's directory), `exists: …` (a destination, or a file
+ * where a directory is made), `isDirectory: …` (a directory read as a file),
+ * `notDirectory: …` (a file listed as a directory).
+ */
+export interface FilesHost {
+  readonly directories: FileDirectories;
+  /** The file's bytes. */
+  read(url: string): Promise<Uint8Array>;
+  /** Writes the bytes as the file, replacing one there; its directory must exist. */
+  write(url: string, data: Uint8Array): Promise<void>;
+  /** Removes a file, or a directory and everything in it. */
+  remove(url: string): Promise<void>;
+  /** Makes the directory and the directories above it; one already there is fine. */
+  createDirectory(url: string): Promise<void>;
+  /** The URLs of what the directory holds, by name. */
+  list(url: string): Promise<string[]>;
+  /** The attributes of what is at the URL, or null when nothing is. */
+  attributes(url: string): Promise<FileAttributes | null>;
+  /** Moves a file or directory to a URL nothing is at, in a directory that exists. */
+  move(from: string, to: string): Promise<void>;
+  /** Copies a file or directory to a URL nothing is at, in a directory that exists. */
+  copy(from: string, to: string): Promise<void>;
+  /** A URL the page can load the file at: an object URL of its bytes on a page, the URL itself natively. */
+  loadURL(url: string): Promise<string>;
+}
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+/** The home on a page, as the wasm module sees it, and the session's temporary directory. */
+export const HOME_URL = `file://${HOME}`;
+export const TMP_URL = `file://${TMP}`;
+
+export const BROWSER_DIRECTORIES: FileDirectories = {
+  documents: `${HOME_URL}/Documents`,
+  applicationSupport: `${HOME_URL}/Library/Application Support`,
+  caches: `${HOME_URL}/Library/Caches`,
+  temporary: TMP_URL,
+};
+
+/** The segments of a `file:` URL's path, `.` and `..` resolved; null for another scheme. */
+export function fileSegments(url: string): string[] | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== 'file:') return null;
+  const out: string[] = [];
+  for (const raw of parsed.pathname.split('/')) {
+    let part = raw;
+    try {
+      part = decodeURIComponent(raw);
+    } catch {
+      // Not percent-encoded: as written.
+    }
+    if (part === '' || part === '.') continue;
+    if (part === '..') out.pop();
+    else out.push(part);
+  }
+  return out;
+}
+
+/** A `file:` URL of `root` (a `file:` URL) and the path below it. */
+export function fileURL(root: string, path: string): string {
+  const encoded = path
+    .split('/')
+    .filter((part) => part !== '')
+    .map((part) => encodeURIComponent(part))
+    .join('/');
+  return encoded === '' ? root : `${root.replace(/\/+$/, '')}/${encoded}`;
+}
+
+/** `path`'s directory ('' at the top). */
+function parentOf(path: string): string {
+  const at = path.lastIndexOf('/');
+  return at < 0 ? '' : path.slice(0, at);
+}
+
+// ---------------------------------------------------------------------------
+// Rows: a home's files by path, in IndexedDB or memory
+// ---------------------------------------------------------------------------
+
+/** A file's bytes, or null for a directory, and when it was written. */
+export interface FileRow {
+  data: Uint8Array | null;
+  modified: number | null;
+}
+
+/** The rows of one home, by path relative to it (`Documents/notes.txt`). */
+export interface FileRows {
+  get(path: string): Promise<FileRow | undefined>;
+  put(path: string, row: FileRow): Promise<void>;
+  remove(paths: readonly string[]): Promise<void>;
+  /** Every path that has a row. */
+  keys(): Promise<string[]>;
+}
+
+/** Rows in a Map: `/tmp`, a page without IndexedDB, and tests. */
+export function memoryRows(): FileRows {
+  const rows = new Map<string, FileRow>();
+  return {
+    get: async (path) => rows.get(path),
+    put: async (path, row) => void rows.set(path, { data: row.data === null ? null : row.data.slice(), modified: row.modified }),
+    remove: async (paths) => paths.forEach((path) => rows.delete(path)),
+    keys: async () => [...rows.keys()],
+  };
+}
+
+/** The app's rows in its IndexedDB database (the `entries` store the wasm loader reads). */
+export function indexedDBRows(app: string, factory: IDBFactory = indexedDB): FileRows {
+  let opened: Promise<IDBDatabase> | null = null;
+  const database = (): Promise<IDBDatabase> => (opened ??= openFilesDatabase(app, factory));
+  const store = async (mode: IDBTransactionMode): Promise<IDBObjectStore> => (await database()).transaction(ENTRIES, mode).objectStore(ENTRIES);
+  return {
+    async get(path) {
+      const row = (await request((await store('readonly')).get(path))) as EntryRow | undefined;
+      if (!row) return undefined;
+      return { data: row.directory ? null : new Uint8Array(row.data ?? new Uint8Array()), modified: typeof row.modified === 'number' ? row.modified : null };
+    },
+    async put(path, row) {
+      const entries = await store('readwrite');
+      const stored: EntryRow = row.data === null ? { path, directory: true } : { path, data: row.data.slice() };
+      if (row.modified !== null) stored.modified = row.modified;
+      entries.put(stored);
+      await done(entries.transaction);
+    },
+    async remove(paths) {
+      if (paths.length === 0) return;
+      const entries = await store('readwrite');
+      for (const path of paths) entries.delete(path);
+      await done(entries.transaction);
+    },
+    async keys() {
+      return (await request((await store('readonly')).getAllKeys())).map(String);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The host
+// ---------------------------------------------------------------------------
+
+export class FilesFailure extends Error {
+  constructor(kind: 'unsupported' | 'notFound' | 'exists' | 'isDirectory' | 'notDirectory', detail: string) {
+    super(`${kind}: ${detail}`);
+    this.name = 'FilesFailure';
+  }
+}
+
+/** A mounted root: its URL, where its rows are, and the directories it always has. */
+interface Mount {
+  url: string;
+  prefix: string[];
+  rows: () => FileRows;
+  standard: readonly string[];
+}
+
+const MEDIA_TYPES: Record<string, string> = {
+  m4a: 'audio/mp4', mp4: 'video/mp4', mov: 'video/quicktime', m4v: 'video/mp4', webm: 'video/webm', wav: 'audio/wav', mp3: 'audio/mpeg',
+  aac: 'audio/aac', ogg: 'audio/ogg', oga: 'audio/ogg', flac: 'audio/flac', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif',
+  webp: 'image/webp', svg: 'image/svg+xml', heic: 'image/heic', avif: 'image/avif', pdf: 'application/pdf', json: 'application/json', txt: 'text/plain',
+};
+
+/** The media type a file's extension says, for the blob a media element loads. */
+export function mediaType(path: string): string {
+  const dot = path.lastIndexOf('.');
+  return (dot >= 0 && MEDIA_TYPES[path.slice(dot + 1).toLowerCase()]) || 'application/octet-stream';
+}
+
+export interface BrowserFilesOptions {
+  /** The home's rows (the app's IndexedDB database by default). */
+  home?: FileRows;
+  /** `/tmp`'s rows (memory by default). */
+  temporary?: FileRows;
+  /** `URL.createObjectURL` and `URL.revokeObjectURL`, or null for `data:` URLs. */
+  objectURLs?: { create(blob: Blob): string; revoke(url: string): void } | null;
+  now?: () => number;
+}
+
+/**
+ * The page's files host over rows (see the module comment). `app` names the
+ * database the home's rows are in, read when the home is first touched after
+ * `setApp` (mount's `app` option); `app` by default.
+ */
+export class BrowserFiles implements FilesHost {
+  readonly directories = BROWSER_DIRECTORIES;
+  private app = 'app';
+  private homeRows: FileRows | null;
+  private readonly temporaryRows: FileRows;
+  private readonly objectURLs: { create(blob: Blob): string; revoke(url: string): void } | null;
+  private readonly now: () => number;
+  /** Object URLs handed out, by mount URL and path, revoked when the file changes. */
+  private readonly loaded = new Map<string, string>();
+
+  /** Whether the home's rows are the database named by `app` (not rows an option gave). */
+  private readonly defaultRows: boolean;
+
+  constructor(options: BrowserFilesOptions = {}) {
+    this.homeRows = options.home ?? null;
+    this.defaultRows = options.home === undefined;
+    this.temporaryRows = options.temporary ?? memoryRows();
+    this.objectURLs =
+      options.objectURLs !== undefined
+        ? options.objectURLs
+        : typeof URL !== 'undefined' && typeof URL.createObjectURL === 'function'
+          ? { create: (blob) => URL.createObjectURL(blob), revoke: (url) => URL.revokeObjectURL(url) }
+          : null;
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  /**
+   * Names the app whose database holds the home (`mount`'s `app` option),
+   * for what the app does with its files from here on; name it before the
+   * app touches them, since what was written before stays in the database
+   * named then.
+   */
+  setApp(app: string): void {
+    if (app === this.app) return;
+    this.app = app;
+    if (this.defaultRows) this.homeRows = null;
+  }
+
+  private readonly mounts: Mount[] = [
+    {
+      url: HOME_URL,
+      prefix: HOME.split('/').filter(Boolean),
+      rows: () => (this.homeRows ??= typeof indexedDB === 'undefined' ? memoryRows() : indexedDBRows(this.app)),
+      standard: HOME_DIRECTORIES,
+    },
+    { url: TMP_URL, prefix: TMP.split('/').filter(Boolean), rows: () => this.temporaryRows, standard: [] },
+  ];
+
+  /** The mount a URL falls in and its path there, or a failure for a URL outside the app's files. */
+  private locate(url: string): { mount: Mount; path: string } {
+    const segments = fileSegments(url);
+    if (segments) {
+      for (const mount of this.mounts) {
+        if (segments.length >= mount.prefix.length && mount.prefix.every((part, i) => segments[i] === part)) {
+          return { mount, path: segments.slice(mount.prefix.length).join('/') };
+        }
+      }
+    }
+    throw new FilesFailure('unsupported', `${url} is not a file in the app's home (${HOME_URL}) or its temporary directory (${TMP_URL})`);
+  }
+
+  /** Whether `path` is a directory the mount always has, or an ancestor of a row (a directory the rows imply). */
+  private async impliedDirectory(mount: Mount, path: string): Promise<boolean> {
+    if (path === '' || mount.standard.includes(path)) return true;
+    const prefix = `${path}/`;
+    return (await mount.rows().keys()).some((key) => key.startsWith(prefix));
+  }
+
+  /** The row at the path, a directory row for an implied directory, or undefined. */
+  private async rowAt(mount: Mount, path: string): Promise<FileRow | undefined> {
+    const row = await mount.rows().get(path);
+    if (row) return row;
+    return (await this.impliedDirectory(mount, path)) ? { data: null, modified: null } : undefined;
+  }
+
+  private async requireDirectory(mount: Mount, path: string, url: string): Promise<void> {
+    const row = await this.rowAt(mount, path);
+    if (!row) throw new FilesFailure('notFound', `no directory at ${fileURL(mount.url, path)} (for ${url})`);
+    if (row.data !== null) throw new FilesFailure('notDirectory', `${fileURL(mount.url, path)} is a file`);
+  }
+
+  private forget(mount: Mount, path: string): void {
+    const key = `${mount.url}/${path}`;
+    const url = this.loaded.get(key);
+    if (url === undefined) return;
+    this.loaded.delete(key);
+    this.objectURLs?.revoke(url);
+  }
+
+  async read(url: string): Promise<Uint8Array> {
+    const { mount, path } = this.locate(url);
+    const row = await this.rowAt(mount, path);
+    if (!row) throw new FilesFailure('notFound', `no file at ${url}`);
+    if (row.data === null) throw new FilesFailure('isDirectory', `${url} is a directory`);
+    return row.data;
+  }
+
+  async write(url: string, data: Uint8Array): Promise<void> {
+    const { mount, path } = this.locate(url);
+    if (path === '') throw new FilesFailure('isDirectory', `${url} is a directory`);
+    await this.requireDirectory(mount, parentOf(path), url);
+    const existing = await this.rowAt(mount, path);
+    if (existing && existing.data === null) throw new FilesFailure('isDirectory', `${url} is a directory`);
+    await mount.rows().put(path, { data, modified: this.now() });
+    this.forget(mount, path);
+  }
+
+  async remove(url: string): Promise<void> {
+    const { mount, path } = this.locate(url);
+    if (path === '') throw new FilesFailure('unsupported', `${url} is the home itself`);
+    const row = await this.rowAt(mount, path);
+    if (!row) throw new FilesFailure('notFound', `nothing at ${url}`);
+    const prefix = `${path}/`;
+    const below = (await mount.rows().keys()).filter((key) => key === path || key.startsWith(prefix));
+    await mount.rows().remove(below);
+    for (const key of below) this.forget(mount, key);
+  }
+
+  async createDirectory(url: string): Promise<void> {
+    const { mount, path } = this.locate(url);
+    const parts = path.split('/').filter(Boolean);
+    for (let depth = 1; depth <= parts.length; depth += 1) {
+      const at = parts.slice(0, depth).join('/');
+      const row = await mount.rows().get(at);
+      if (row?.data) throw new FilesFailure('exists', `${fileURL(mount.url, at)} is a file`);
+      if (!row && !mount.standard.includes(at)) await mount.rows().put(at, { data: null, modified: this.now() });
+    }
+  }
+
+  async list(url: string): Promise<string[]> {
+    const { mount, path } = this.locate(url);
+    await this.requireDirectory(mount, path, url);
+    const prefix = path === '' ? '' : `${path}/`;
+    const names = new Set<string>();
+    for (const key of [...(await mount.rows().keys()), ...mount.standard]) {
+      if (!key.startsWith(prefix) || key === path) continue;
+      const rest = key.slice(prefix.length);
+      const slash = rest.indexOf('/');
+      names.add(slash < 0 ? rest : rest.slice(0, slash));
+    }
+    return [...names].sort((a, b) => a.localeCompare(b)).map((name) => fileURL(mount.url, prefix + name));
+  }
+
+  async attributes(url: string): Promise<FileAttributes | null> {
+    const { mount, path } = this.locate(url);
+    const row = await this.rowAt(mount, path);
+    if (!row) return null;
+    return { size: row.data?.byteLength ?? 0, modified: row.modified, directory: row.data === null };
+  }
+
+  /** Every row at or below `path`, by path. */
+  private async subtree(mount: Mount, path: string): Promise<Map<string, FileRow>> {
+    const out = new Map<string, FileRow>();
+    const own = await this.rowAt(mount, path);
+    if (own) out.set(path, own);
+    const prefix = `${path}/`;
+    for (const key of await mount.rows().keys()) {
+      if (!key.startsWith(prefix)) continue;
+      const row = await mount.rows().get(key);
+      if (row) out.set(key, row);
+    }
+    return out;
+  }
+
+  private async transfer(from: string, to: string, removeSource: boolean): Promise<void> {
+    const source = this.locate(from);
+    const target = this.locate(to);
+    if (source.path === '' || target.path === '') throw new FilesFailure('unsupported', `the home itself cannot be ${removeSource ? 'moved' : 'copied'}`);
+    const rows = await this.subtree(source.mount, source.path);
+    if (rows.size === 0) throw new FilesFailure('notFound', `nothing at ${from}`);
+    if (await this.rowAt(target.mount, target.path)) throw new FilesFailure('exists', `something is at ${to} already`);
+    await this.requireDirectory(target.mount, parentOf(target.path), to);
+    if (target.path.startsWith(`${source.path}/`) && target.mount === source.mount) throw new FilesFailure('unsupported', `${to} is inside ${from}`);
+    const now = this.now();
+    for (const [path, row] of rows) {
+      const moved = target.path + path.slice(source.path.length);
+      await target.mount.rows().put(moved, { data: row.data, modified: removeSource ? row.modified : now });
+    }
+    if (removeSource) {
+      await source.mount.rows().remove([...rows.keys()].filter((key) => key !== source.path || !source.mount.standard.includes(key)));
+      for (const key of rows.keys()) this.forget(source.mount, key);
+    }
+  }
+
+  move(from: string, to: string): Promise<void> {
+    return this.transfer(from, to, true);
+  }
+
+  copy(from: string, to: string): Promise<void> {
+    return this.transfer(from, to, false);
+  }
+
+  async loadURL(url: string): Promise<string> {
+    const { mount, path } = this.locate(url);
+    const key = `${mount.url}/${path}`;
+    const known = this.loaded.get(key);
+    if (known !== undefined) return known;
+    const data = await this.read(url);
+    const type = mediaType(path);
+    if (!this.objectURLs) return `data:${type};base64,${base64Of(data)}`;
+    const made = this.objectURLs.create(new Blob([data.slice()], { type }));
+    this.loaded.set(key, made);
+    return made;
+  }
+}
+
+function base64Of(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i += 0x8000) binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  return btoa(binary);
+}
+
+/** The page's files host, where the page keeps files (IndexedDB) or can at least hold them for the session. */
+export function browserFiles(): BrowserFiles | undefined {
+  if (typeof indexedDB === 'undefined' && typeof document === 'undefined') return undefined;
+  return new BrowserFiles();
+}

package/src/gestureComposition.ts

@@ -0,0 +1,92 @@
+/**
+ * How gestures compose (docs/ops-protocol.md, "Gesture spaces and
+ * composition"): the order the wrappers on a pointer's way to the root are
+ * asked in, and the taps a `tapgesture` with `count` collects. Pure, so the
+ * rules are tested in Node; src/interaction.ts and src/renderer.ts apply them.
+ */
+
+import type { GestureMode } from './protocol';
+
+/** A behaviour that could own a pointer: a `gesture` element's carries its mode. */
+export interface Wrapper {
+  kind: string;
+  mode?: GestureMode;
+}
+
+/** The double-tap interval: a single tap beside a double tap waits this long. */
+export const DOUBLE_TAP_MS = 300;
+
+/**
+ * Puts a wrapper found on the way up into `out`, which lists the wrappers
+ * found so far innermost first, from `wrapperStart` (what comes before them
+ * is the system's: a row's grip, the back swipe). A `highPriority` gesture
+ * goes in front of the wrappers inside it, as `.highPriorityGesture` wins
+ * over the gestures of the views it wraps; an outer one found later goes in
+ * front of it in turn. Everything else goes at the end, innermost first.
+ */
+export function placeWrapper<T extends Wrapper>(out: T[], candidate: T, wrapperStart: number): void {
+  if (candidate.kind === 'gesture' && candidate.mode === 'highPriority') out.splice(wrapperStart, 0, candidate);
+  else out.push(candidate);
+}
+
+/** `.simultaneousGesture`: runs beside the pointer's owner, never claiming. */
+export function isSimultaneous(candidate: Wrapper): boolean {
+  return candidate.kind === 'gesture' && candidate.mode === 'simultaneous';
+}
+
+/**
+ * The taps a click lands: `multi` is the innermost `tapgesture` with a
+ * `count` above one on the click's way up (null when none), `single` the
+ * innermost of one tap; `detail` is what the firing needs of the click (its
+ * point), the last click's when several make a tap. A click with no `multi`
+ * fires `single` at once. With one, the clicks are counted: the `count`th
+ * within the interval fires `multi`; should the interval pass first, `single`
+ * fires instead (as iOS waits for a double tap before a single tap lands). A
+ * click elsewhere ends the count, firing the pending single.
+ */
+export class TapCounter<T, D = void> {
+  private pending: { multi: T; single: T | null; detail: D; taps: number; timer: unknown } | null = null;
+
+  constructor(
+    private readonly fire: (target: T, detail: D) => void,
+    private readonly schedule: (run: () => void, ms: number) => unknown = (run, ms) => setTimeout(run, ms),
+    private readonly cancel: (timer: unknown) => void = (timer) => clearTimeout(timer as number),
+  ) {}
+
+  click(multi: T | null, count: number, single: T | null, detail: D): void {
+    if (this.pending && this.pending.multi !== multi) this.flush();
+    if (!multi) {
+      if (single) this.fire(single, detail);
+      return;
+    }
+    if (this.pending) {
+      this.pending.taps += 1;
+      this.pending.detail = detail;
+      if (this.pending.taps < count) return;
+      this.cancel(this.pending.timer);
+      this.pending = null;
+      this.fire(multi, detail);
+      return;
+    }
+    if (count <= 1) {
+      this.fire(multi, detail);
+      return;
+    }
+    const pending = { multi, single, detail, taps: 1, timer: null as unknown };
+    pending.timer = this.schedule(() => {
+      if (this.pending !== pending) return;
+      this.pending = null;
+      if (single) this.fire(single, pending.detail);
+    }, DOUBLE_TAP_MS);
+    this.pending = pending;
+  }
+
+  /** Ends a count early: the single tap it was holding fires (nothing when there was none). */
+  flush(): void {
+    const pending = this.pending;
+    if (!pending) return;
+    this.cancel(pending.timer);
+    this.pending = null;
+    if (pending.single) this.fire(pending.single, pending.detail);
+  }
+}