@solidrt/core 0.0.55 → 0.0.57

package/src/input-map.ts

@@ -0,0 +1,467 @@
+// The input map: named, typed actions between devices and consumers -
+// Godot's InputMap and Unity's action maps, in reactive form. An app
+// declares its actions once (`look: "vec2"`, `jump: "button"`), binds
+// device sources to them (a stick, a key composite, a pointer drag), and
+// consumers read the action, never the device. Anything can then drive a
+// consumer: a second pad on a second map for split screen, a debug
+// command or a network peer through the by-name injection, a replay on
+// the action stream, a settings screen over bindings().
+//
+// Each axis or vec2 action carries two channels, which is the part Godot
+// (no mouse motion in actions) and Unity (mouse delta and stick share one
+// value, consumers scale by dt themselves) each got half of:
+// - the RATE: the sum of every bound source's current value, clamped (an
+//   axis to -1..1, a vec2 to unit length), reactive, sampled per frame by
+//   the consumer and integrated over dt at its own speed;
+// - the DELTAS: immediate, device-free amounts a gesture produced (a drag
+//   in view heights, a wheel notch in octaves), delivered as they happen
+//   with begin/end brackets around a finger's gesture.
+// Values use the screen convention: x right, y down.
+//
+// A button action reads pressed while any bound button source is, and
+// may also bind to an axis action (1 while pressed). Kinds are checked at
+// bind: a vec2 source on an axis action throws.
+//
+// Reactivity: rates are memos over reactive sources, so a consumer's
+// active() gate wakes on a stick or a key. Create the map in an owned
+// scope (a component body): onPress/onRelease run effects under it.
+//
+// Consumers with the Axes contract (createAxes; the camera controls) are
+// connected by name with drive(): each axis takes the action of the same
+// name, or the name given, for both channels.
+//
+// Contexts (a menu open, a cutscene) switch actions off and on by name:
+// enable/disable. A disabled action reads neutral, drops its deltas and
+// closes the gesture it had open, while its sources keep their state, so
+// a key still held when the action comes back reads at once. A set is a
+// list of names, which a preset's action object already is
+// (`input.disable(...Object.keys(gameActions))`): Unity's per-map enable
+// and Unreal's stacked contexts, on one map, with no extra concept.
+
+import { createEffect, createRoot, createSignal, untrack } from "@solidjs/signals"
+import type { KeyEvent } from "./types"
+import { combineRates } from "./input-axes"
+import type { Axes, AxesDecl, AxisValue, Vec2 } from "./input-axes"
+
+export type ActionKind = "button" | "axis" | "vec2"
+export type ActionValue<K extends ActionKind> = K extends "button" ? boolean : K extends "axis" ? number : Vec2
+export type ActionsDecl = Record<string, ActionKind>
+
+/** Where a delta source delivers: the gesture brackets and the deltas. */
+export interface DeltaSink {
+  begin(): void
+  delta(value: number | Vec2, focal?: Vec2): void
+  end(): void
+}
+
+/**
+ * One device control as an input source. `rate` reads its current value
+ * (reactive); `deltas` subscribes a sink to the amounts a gesture
+ * produces; `key`/`blur` receive the key events a map forwards
+ * (InputMap.handlers). A source may carry any subset.
+ */
+export interface InputSource<K extends ActionKind = ActionKind> {
+  readonly kind: K
+  /** For bindings listings and settings screens: "keyboard W/A/S/D". */
+  readonly label: string
+  rate?: () => ActionValue<K>
+  deltas?: (sink: DeltaSink) => () => void
+  key?: (event: KeyEvent, down: boolean) => void
+  blur?: () => void
+}
+
+export type Binding = { action: string; source: InputSource }
+
+/**
+ * A source with its values negated - Unity's Invert processor. The one
+ * convention split every engine has: a drag moves the CONTENT under the
+ * finger, while keys and sticks move the CAMERA, so a preset binds the
+ * arrows or a stick to `pan` or `rotate` through invert() and the axis
+ * keeps one meaning.
+ */
+export function invert<K extends "axis" | "vec2">(source: InputSource<K>): InputSource<K> {
+  checkSource(source)
+  if ((source.kind as ActionKind) === "button") throw new Error(`invert: "${source.label}" is a button`)
+  let neg = (v: number | Vec2): number | Vec2 => (typeof v === "number" ? -v : [-v[0], -v[1]])
+  return {
+    kind: source.kind,
+    label: `${source.label} (inverted)`,
+    rate: source.rate ? () => neg(source.rate!() as number | Vec2) as never : undefined,
+    deltas: source.deltas
+      ? sink => source.deltas!({ begin: sink.begin, end: sink.end, delta: (value, focal) => sink.delta(neg(value), focal) })
+      : undefined,
+    key: source.key,
+    blur: source.blur,
+  }
+}
+
+/** A source scaled by `factor` (rates and deltas alike) - Unity's Scale
+ * processor: a slower stick, a finer wheel. */
+export function scale<K extends "axis" | "vec2">(source: InputSource<K>, factor: number): InputSource<K> {
+  checkSource(source)
+  if ((source.kind as ActionKind) === "button") throw new Error(`scale: "${source.label}" is a button`)
+  if (!Number.isFinite(factor)) throw new Error(`scale: factor must be a finite number, got ${factor}`)
+  let mul = (v: number | Vec2): number | Vec2 => (typeof v === "number" ? v * factor : [v[0] * factor, v[1] * factor])
+  return {
+    kind: source.kind,
+    label: `${source.label} (x${factor})`,
+    rate: source.rate ? () => mul(source.rate!() as number | Vec2) as never : undefined,
+    deltas: source.deltas
+      ? sink => source.deltas!({ begin: sink.begin, end: sink.end, delta: (value, focal) => sink.delta(mul(value), focal) })
+      : undefined,
+    key: source.key,
+    blur: source.blur,
+  }
+}
+
+export interface GestureListener<K extends "axis" | "vec2" = "axis" | "vec2"> {
+  begin?: () => void
+  delta?: (value: AxisValue<K>, focal: Vec2 | undefined) => void
+  end?: () => void
+}
+
+type AxisActions<A extends ActionsDecl> = { [N in keyof A]: A[N] extends "button" ? never : N }[keyof A] & string
+type ButtonActions<A extends ActionsDecl> = { [N in keyof A]: A[N] extends "button" ? N : never }[keyof A] & string
+
+export interface InputMap<A extends ActionsDecl> {
+  readonly actions: A
+  /** Bind sources to an action (kinds checked), or a list of bindings (a
+   * preset's return). Returns the remover for what this call bound. */
+  bind<N extends keyof A & string>(action: N, ...sources: InputSource[]): () => void
+  bind(bindings: Binding[]): () => void
+  unbind(action: keyof A & string, source: InputSource): void
+  /** Current bindings, of one action or all, in binding order. */
+  bindings(action?: keyof A & string): Binding[]
+  /** The action's rate now (reactive): pressed for a button, -1..1 for an
+   * axis, a unit-clamped [x, y] for a vec2. */
+  value<N extends keyof A & string>(action: N): ActionValue<A[N]>
+  /** Reactive: whether a button action is pressed. */
+  pressed(action: ButtonActions<A>): boolean
+  /** Edge callbacks on a button action; return the unsubscribe. */
+  onPress(action: ButtonActions<A>, callback: () => void): () => void
+  onRelease(action: ButtonActions<A>, callback: () => void): () => void
+  /** Subscribe to an axis or vec2 action's delta channel. */
+  onGesture<N extends AxisActions<A>>(action: N, listener: GestureListener<A[N] extends "axis" ? "axis" : "vec2">): () => void
+  /** Injection by name, for scripts, debug commands, peers: `set` holds
+   * a rate until set again (a value source of the map's own); `press`/
+   * `release` do the same for a button; `nudge`, `begin` and `end` feed
+   * the delta channel. */
+  set<N extends keyof A & string>(action: N, value: ActionValue<A[N]>): void
+  press(action: ButtonActions<A>): void
+  release(action: ButtonActions<A>): void
+  nudge<N extends AxisActions<A>>(action: N, delta: ActionValue<A[N]>, focal?: Vec2): void
+  begin(action: AxisActions<A>): void
+  end(action: AxisActions<A>): void
+  /** Switch actions on and off by name - a context. A disabled action
+   * reads neutral (false, 0, [0, 0]), drops its deltas and closes the
+   * gesture it had open (its listeners see the end); its sources keep
+   * their state, so a key still held when the action comes back reads at
+   * once. Edge callbacks see the switch as a release or a press. All
+   * actions start enabled. */
+  enable(...actions: (keyof A & string)[]): void
+  disable(...actions: (keyof A & string)[]): void
+  /** Reactive: whether the action is enabled. */
+  enabled(action: keyof A & string): boolean
+  /** Key events for the bound keyboard sources: spread on the window
+   * (app-global) or on the leaf that should hold focus for them. */
+  handlers: {
+    onKeyDown(event: KeyEvent): void
+    onKeyUp(event: KeyEvent): void
+    onBlur(): void
+  }
+  /**
+   * Drive a control's axes (createAxes) from this map: each axis reads
+   * the action of the same name, or the one `names` gives it (null skips
+   * an axis). Both channels: rates as a source, deltas and brackets as
+   * nudges. Returns the disconnect.
+   */
+  drive<X extends AxesDecl>(axes: Axes<X>, names?: Partial<Record<keyof X & string, keyof A & string | null>>): () => void
+}
+
+// Per action: the bound sources and the script value are plain state (a
+// write and a read in the same synchronous block must agree, which a
+// signal's deferred write does not give); `version` notifies the reactive
+// readers of a change.
+type ActionState = {
+  kind: ActionKind
+  sources: InputSource[]
+  script: boolean | number | Vec2 | null
+  enabled: boolean
+  /** Gesture brackets delivered to the listeners and not yet closed. */
+  depth: number
+  version: () => number
+  bump: () => void
+  value: () => boolean | number | Vec2
+  gesture: Set<GestureListener>
+  /** Live delta subscriptions per bound source. */
+  live: Map<InputSource, () => void>
+}
+
+let compatible = (source: ActionKind, action: ActionKind): boolean => source === action || (source === "button" && action === "axis")
+
+let neutral = (kind: ActionKind): boolean | number | Vec2 => (kind === "button" ? false : kind === "axis" ? 0 : [0, 0])
+
+function checkValue(what: string, kind: ActionKind, v: unknown): void {
+  if (kind === "button") {
+    if (typeof v !== "boolean") throw new Error(`${what}: expected a boolean, got ${String(v)}`)
+  } else if (kind === "axis") {
+    if (typeof v !== "number" || !Number.isFinite(v)) throw new Error(`${what}: expected a finite number, got ${String(v)}`)
+  } else if (!Array.isArray(v) || v.length !== 2 || !Number.isFinite(v[0]) || !Number.isFinite(v[1])) {
+    throw new Error(`${what}: expected [x, y] finite numbers, got ${JSON.stringify(v)}`)
+  }
+}
+
+function checkSource(source: unknown): InputSource {
+  let s = source as InputSource
+  if (!s || typeof s !== "object" || (s.kind !== "button" && s.kind !== "axis" && s.kind !== "vec2") || typeof s.label !== "string") {
+    throw new Error(`createInputMap: not an input source: ${String(source)}`)
+  }
+  return s
+}
+
+export function createInputMap<A extends ActionsDecl>(actions: A): InputMap<A> {
+  if (!actions || typeof actions !== "object") throw new Error("createInputMap: expected an object of action kinds")
+  let states = new Map<string, ActionState>()
+  for (let [name, kind] of Object.entries(actions)) {
+    if (kind !== "button" && kind !== "axis" && kind !== "vec2") throw new Error(`createInputMap: action "${name}" has kind "${String(kind)}", expected "button", "axis" or "vec2"`)
+    // ownedWrite: bind() and set() run from component bodies.
+    let [version, setVersion] = createSignal(0, { ownedWrite: true })
+    let state: ActionState = {
+      kind,
+      sources: [],
+      script: null,
+      enabled: true,
+      depth: 0,
+      version,
+      bump: () => setVersion(untrack(version) + 1),
+      value: (): boolean | number | Vec2 => {
+        version()
+        if (!state.enabled) return neutral(kind)
+        let s = state.script
+        if (kind === "button") {
+          if (s === true) return true
+          return state.sources.some(src => src.rate?.() === true)
+        }
+        let values: (number | Vec2)[] = []
+        if (s !== null) values.push(s as number | Vec2)
+        for (let src of state.sources) {
+          if (!src.rate) continue
+          let v = src.rate()
+          if (src.kind === "button") values.push(v ? 1 : 0)
+          else values.push(v as number | Vec2)
+        }
+        return combineRates(kind, values)
+      },
+      gesture: new Set(),
+      live: new Map(),
+    }
+    states.set(name, state)
+  }
+  let state = (name: string): ActionState => {
+    let s = states.get(name)
+    if (!s) throw new Error(`createInputMap: no action "${name}" (declared: ${[...states.keys()].join(", ")})`)
+    return s
+  }
+  let axisState = (name: string, what: string): ActionState => {
+    let s = state(name)
+    if (s.kind === "button") throw new Error(`createInputMap: ${what} needs an axis or vec2 action, "${name}" is a button`)
+    return s
+  }
+  let buttonState = (name: string, what: string): ActionState => {
+    let s = state(name)
+    if (s.kind !== "button") throw new Error(`createInputMap: ${what} needs a button action, "${name}" is a ${s.kind}`)
+    return s
+  }
+  // The delta channel fan-out for one action. Brackets are counted as
+  // delivered, so a disable can close what is open and an end whose begin
+  // was dropped (or never delivered) reaches no listener.
+  let closeGesture = (s: ActionState): void => {
+    s.depth--
+    s.gesture.forEach(g => g.end?.())
+  }
+  let sink = (s: ActionState): DeltaSink => ({
+    begin: () => {
+      if (!s.enabled) return
+      s.depth++
+      s.gesture.forEach(g => g.begin?.())
+    },
+    delta: (value, focal) => {
+      if (!s.enabled) return
+      s.gesture.forEach(g => g.delta?.(value as never, focal))
+    },
+    end: () => {
+      if (s.depth > 0) closeGesture(s)
+    },
+  })
+  let switchActions = (names: string[], on: boolean, what: string): void => {
+    if (names.length === 0) throw new Error(`createInputMap: ${what}() needs at least one action`)
+    for (let name of names) {
+      let s = state(name)
+      if (s.enabled === on) continue
+      s.enabled = on
+      while (!on && s.depth > 0) closeGesture(s)
+      s.bump()
+    }
+  }
+
+  let bindOne = (name: string, source: InputSource): void => {
+    let s = state(name)
+    checkSource(source)
+    if (!compatible(source.kind, s.kind)) throw new Error(`createInputMap: cannot bind ${source.kind} source "${source.label}" to ${s.kind} action "${name}"`)
+    if (s.sources.includes(source)) return
+    s.sources.push(source)
+    s.bump()
+    if (source.deltas && s.kind !== "button") s.live.set(source, source.deltas(sink(s)))
+  }
+  let unbindOne = (name: string, source: InputSource): void => {
+    let s = state(name)
+    let i = s.sources.indexOf(source)
+    if (i < 0) return
+    s.sources.splice(i, 1)
+    s.bump()
+    let stop = s.live.get(source)
+    if (stop) {
+      s.live.delete(source)
+      stop()
+    }
+  }
+  let edge = (name: string, want: boolean, callback: () => void): (() => void) => {
+    let s = buttonState(name, want ? "onPress" : "onRelease")
+    if (typeof callback !== "function") throw new Error(`createInputMap: ${want ? "onPress" : "onRelease"}("${name}") expects a function`)
+    return createRoot(dispose => {
+      // The callback is a side effect that may read state of its own (a
+      // focus, a pose): a snapshot, not a dependency, so untracked.
+      createEffect(
+        () => s.value() as boolean,
+        (pressed, prev) => {
+          if (pressed === want && prev !== want) untrack(callback)
+        },
+        { defer: true },
+      )
+      return dispose
+    })
+  }
+
+  let map: InputMap<A> = {
+    actions,
+    bind(actionOrList: string | Binding[], ...sources: InputSource[]) {
+      let list: Binding[] = Array.isArray(actionOrList) ? actionOrList : sources.map(source => ({ action: actionOrList, source }))
+      if (list.length === 0) throw new Error("createInputMap: bind() needs at least one source")
+      for (let b of list) bindOne(b.action, b.source)
+      return () => {
+        for (let b of list) unbindOne(b.action, b.source)
+      }
+    },
+    unbind: unbindOne,
+    bindings(action) {
+      let out: Binding[] = []
+      for (let [name, s] of states) {
+        if (action !== undefined && name !== action) continue
+        for (let source of s.sources) out.push({ action: name, source })
+      }
+      if (action !== undefined) state(action)
+      return out
+    },
+    value(action) {
+      return state(action).value() as never
+    },
+    pressed(action) {
+      return buttonState(action, "pressed").value() as boolean
+    },
+    onPress: (action, callback) => edge(action, true, callback),
+    onRelease: (action, callback) => edge(action, false, callback),
+    onGesture(action, listener) {
+      let s = axisState(action, "onGesture")
+      if (!listener || typeof listener !== "object") throw new Error(`createInputMap: onGesture("${action}") expects a listener object`)
+      s.gesture.add(listener as GestureListener)
+      return () => {
+        s.gesture.delete(listener as GestureListener)
+      }
+    },
+    set(action, value) {
+      let s = state(action)
+      checkValue(`set("${action}")`, s.kind, value)
+      s.script = value
+      s.bump()
+    },
+    press(action) {
+      let s = buttonState(action, "press")
+      s.script = true
+      s.bump()
+    },
+    release(action) {
+      let s = buttonState(action, "release")
+      s.script = false
+      s.bump()
+    },
+    nudge(action, delta, focal) {
+      let s = axisState(action, "nudge")
+      checkValue(`nudge("${action}")`, s.kind, delta)
+      if (focal !== undefined) checkValue(`nudge("${action}") focal`, "vec2", focal)
+      sink(s).delta(delta as number | Vec2, focal)
+    },
+    begin(action) {
+      sink(axisState(action, "begin")).begin()
+    },
+    end(action) {
+      sink(axisState(action, "end")).end()
+    },
+    enable: (...actions) => switchActions(actions, true, "enable"),
+    disable: (...actions) => switchActions(actions, false, "disable"),
+    enabled(action) {
+      let s = state(action)
+      s.version()
+      return s.enabled
+    },
+    handlers: {
+      onKeyDown: event => forwardKey(event, true),
+      onKeyUp: event => forwardKey(event, false),
+      onBlur: () => {
+        let seen = new Set<InputSource>()
+        for (let s of states.values()) {
+          for (let source of s.sources) {
+            if (seen.has(source)) continue
+            seen.add(source)
+            source.blur?.()
+          }
+        }
+      },
+    },
+    drive(axes, names) {
+      let stops: (() => void)[] = []
+      for (let [axis, kind] of Object.entries(axes.kinds)) {
+        let mapped = names && axis in names ? names[axis] : axis
+        if (mapped === null) continue
+        if (mapped === undefined || !states.has(mapped)) {
+          throw new Error(`createInputMap: drive() has no action for axis "${axis}" (declared: ${[...states.keys()].join(", ")}); declare it, map it with names, or skip it with null`)
+        }
+        let s = state(mapped)
+        if (s.kind !== kind) throw new Error(`createInputMap: drive() maps ${kind} axis "${axis}" to ${s.kind} action "${mapped}"`)
+        stops.push(axes.add(axis, () => s.value() as never))
+        stops.push(
+          map.onGesture(mapped as never, {
+            begin: () => axes.begin(axis),
+            delta: (value, focal) => axes.nudge(axis, value as never, focal),
+            end: () => axes.end(axis),
+          }),
+        )
+      }
+      return () => {
+        for (let stop of stops) stop()
+      }
+    },
+  }
+  // A key event reaches each bound keyboard source once, however many
+  // actions it is bound to.
+  let forwardKey = (event: KeyEvent, down: boolean): void => {
+    let seen = new Set<InputSource>()
+    for (let s of states.values()) {
+      for (let source of s.sources) {
+        if (seen.has(source) || !source.key) continue
+        seen.add(source)
+        source.key(event, down)
+      }
+    }
+  }
+  return map
+}

package/src/input-pointer.ts

@@ -0,0 +1,213 @@
+// A pointer feed: one element's pointer events turned into gesture
+// sources for an input map. The pointer is the one device that is not
+// global - the tree holds UI and scene together, so a drag belongs to the
+// element it started on (a slider beside a viewport must not turn the
+// camera) - hence a feed per element: spread `feed.handlers` on the leaf
+// (a Scene, View3d, SpriteLayer or View2d takes it as its `pointer` prop
+// and spreads it on the built-in leaf) and bind its sources.
+//
+// The sources are gestures, not raw events, because a pointer only means
+// something once a gesture is recognized: a move without a press is
+// nothing, one finger dragging is `drag`, two fingers moving together is
+// `pan`, spreading is `pinch`, turning is `twist`, and the wheel is its
+// own thing. One merged recognizer (createTransform) serves all of them,
+// so they arbitrate in the app-wide gesture arena as one - a viewport
+// inside a scroller never double-handles - and they never fight each
+// other over the same fingers. `mouseDelta` is the pointer-lock path:
+// raw mouse motion while the pointer is locked, when the cursor does not
+// move and no drag can arm.
+//
+// Units are device-free (the input map's contract): drag and pan travel
+// in the element's own heights (a drag across the element is 1 whatever
+// the window size - Three's OrbitControls convention), pinch and wheel
+// in octaves (log2 of the scale change, one notch about a fifth), twist
+// in turns, mouse motion in view-height-equivalents through a fixed
+// reference. The focal point of a pinch or a wheel rides along as a
+// fraction of the element (0..1), the anchor a zoom-about-the-cursor
+// consumer maps to its own space. Screen convention: x right, y down.
+//
+// Gesture brackets: `drag` begins when the first pointer lands and ends
+// when the last lifts (or when a second lands, which begins `pan`,
+// `pinch` and `twist` until the count drops back to one); the wheel
+// sends no brackets, so a consumer can tell a notch from a finger.
+// Brackets fire on the press itself, before the recognizer's slop, so a
+// glide stops the moment a finger lands.
+//
+// The element's laid-out box normalizes the travel: read at the press
+// through getLayoutBox (the untransformed read, so a designSize fit or
+// an ancestor transform never skews it), or from `layout` when given -
+// required for a detached d-* leaf, which has no layout box (the feed
+// throws rather than treat pixels as heights), and handy for a headless
+// check with no tree. A zero-height box passes pixels through unscaled.
+//
+// Create a feed in an owned scope (a component body): the recognizer
+// registers its cleanup with the owner.
+
+import { createTransform } from "./transform"
+import { getLayoutBox } from "./core"
+import { pointerLocked } from "./window"
+import type { PointerEvent, WheelEvent } from "./types"
+import type { DeltaSink, InputSource } from "./input-map"
+import type { Vec2 } from "./input-axes"
+
+// Octaves per wheel-delta unit: the zoom exponent both cameras used
+// (0.0015 per unit) taken in log2, so a 100-unit notch zooms about a
+// fifth of an octave and a fast scroll of ten notches doubles.
+const WHEEL_OCTAVES = 0.0015 / Math.LN2
+// Mouse travel per delta unit under pointer lock, in logical pixels: one
+// unit is what a drag across the element's height means to a consumer (a
+// half turn of look in the first-person control), and 1500 px per half
+// turn is the ~0.002 rad/px of Three's PointerLockControls.
+const MOUSE_PX_PER_UNIT = 1500
+
+export interface PointerFeed {
+  /** Spread on the element whose pointer events feed the sources. */
+  handlers: {
+    onPointerDown(event: PointerEvent): void
+    onPointerMove(event: PointerEvent): void
+    onPointerUp(event: PointerEvent): void
+    onPointerLeave(event: PointerEvent): void
+    onWheel(event: WheelEvent): void
+  }
+  /** One pointer's travel, in element heights; bracketed. */
+  drag: InputSource<"vec2">
+  /** Two or more pointers' focal travel, in element heights; bracketed. */
+  pan: InputSource<"vec2">
+  /** Span change of two pointers, in octaves (spreading positive), with
+   * the focal point; bracketed. */
+  pinch: InputSource<"axis">
+  /** Rotation of the pointer pair, in turns, with the focal point; bracketed. */
+  twist: InputSource<"axis">
+  /** Wheel notches in octaves (wheel up positive), with the cursor as the
+   * focal point; unbracketed. */
+  wheel: InputSource<"axis">
+  /** Raw mouse motion while the pointer is locked, in view-height
+   * equivalents (see MOUSE_PX_PER_UNIT); unbracketed. */
+  mouseDelta: InputSource<"vec2">
+}
+
+export interface PointerFeedOptions {
+  /** The element's size, when the app knows it - required for a detached
+   * d-* leaf, which has no layout box; default reads getLayoutBox at each
+   * press. */
+  layout?: () => { width: number; height: number } | null
+}
+
+type Sinks = Set<DeltaSink>
+
+function source<K extends "axis" | "vec2">(kind: K, label: string, sinks: Sinks): InputSource<K> {
+  return {
+    kind,
+    label,
+    deltas(sink) {
+      sinks.add(sink)
+      return () => {
+        sinks.delete(sink)
+      }
+    },
+  }
+}
+
+export function createPointerFeed(options: PointerFeedOptions = {}): PointerFeed {
+  let sinks = {
+    drag: new Set<DeltaSink>(),
+    pan: new Set<DeltaSink>(),
+    pinch: new Set<DeltaSink>(),
+    twist: new Set<DeltaSink>(),
+    wheel: new Set<DeltaSink>(),
+    mouseDelta: new Set<DeltaSink>(),
+  }
+  let begin = (s: Sinks) => s.forEach(k => k.begin())
+  let end = (s: Sinks) => s.forEach(k => k.end())
+  let delta = (s: Sinks, value: number | Vec2, focal?: Vec2) => s.forEach(k => k.delta(value, focal))
+
+  // The element's box, read at each press (see the header). A detached
+  // leaf has no layout box and must bring `layout`: normalizing by
+  // nothing would turn a 100 px drag into 100 element heights, so that
+  // is a throw (the dev validation policy), while a zero-size box is a
+  // degenerate layout and passes pixels through.
+  let size = (event: { currentTarget: number }): { width: number; height: number } => {
+    let box = options.layout ? options.layout() : getLayoutBox({ id: event.currentTarget })
+    if (box === null && !options.layout) {
+      throw new Error("createPointerFeed: the element has no layout box (a detached d-* leaf, or before its first layout); create the feed with { layout: () => ({ width, height }) } for it")
+    }
+    return box && box.width > 0 && box.height > 0 ? { width: box.width, height: box.height } : { width: 0, height: 0 }
+  }
+  let box = { width: 0, height: 0 }
+  let unit = () => (box.height > 0 ? box.height : 1)
+  let focalOf = (x: number, y: number): Vec2 | undefined => (box.width > 0 && box.height > 0 ? [x / box.width, y / box.height] : undefined)
+
+  let transform = createTransform({
+    onTransformMove: t => {
+      let h = unit()
+      let travel: Vec2 = [t.dx / h, t.dy / h]
+      if (t.pointers >= 2) {
+        if (t.dx !== 0 || t.dy !== 0) delta(sinks.pan, travel)
+        let focal = focalOf(t.x, t.y)
+        if (t.scale !== 1) delta(sinks.pinch, Math.log2(t.scale), focal)
+        if (t.rotation !== 0) delta(sinks.twist, t.rotation / (2 * Math.PI), focal)
+      } else if (t.dx !== 0 || t.dy !== 0) {
+        delta(sinks.drag, travel)
+      }
+    },
+  })
+
+  // Pointers down on the element, for the gesture brackets: the first
+  // press opens drag, a second closes it and opens the two-pointer
+  // gestures, and the count coming back down reverses that.
+  let downs = new Set<number>()
+  let landed = (id: number) => {
+    if (downs.has(id)) return
+    downs.add(id)
+    if (downs.size === 1) begin(sinks.drag)
+    if (downs.size === 2) {
+      end(sinks.drag)
+      begin(sinks.pan)
+      begin(sinks.pinch)
+      begin(sinks.twist)
+    }
+  }
+  let lifted = (id: number) => {
+    if (!downs.delete(id)) return
+    if (downs.size === 1) {
+      end(sinks.pan)
+      end(sinks.pinch)
+      end(sinks.twist)
+      begin(sinks.drag)
+    }
+    if (downs.size === 0) end(sinks.drag)
+  }
+
+  return {
+    handlers: {
+      onPointerDown(e) {
+        if (e.button != null && e.button !== 0) return
+        if (downs.size === 0) box = size(e)
+        landed(e.pointerId)
+        transform.handlers.onPointerDown(e)
+      },
+      onPointerMove(e) {
+        if (pointerLocked() && e.pointerType === "mouse" && (e.movementX !== 0 || e.movementY !== 0)) {
+          delta(sinks.mouseDelta, [e.movementX / MOUSE_PX_PER_UNIT, e.movementY / MOUSE_PX_PER_UNIT])
+        }
+        transform.handlers.onPointerMove(e)
+      },
+      onPointerUp(e) {
+        transform.handlers.onPointerUp(e)
+        lifted(e.pointerId)
+      },
+      onPointerLeave() {},
+      onWheel(e) {
+        if (e.deltaY === 0) return
+        box = size(e)
+        delta(sinks.wheel, -e.deltaY * WHEEL_OCTAVES, focalOf(e.localX, e.localY))
+      },
+    },
+    drag: source("vec2", "pointer drag", sinks.drag),
+    pan: source("vec2", "pointer two-finger pan", sinks.pan),
+    pinch: source("axis", "pointer pinch", sinks.pinch),
+    twist: source("axis", "pointer twist", sinks.twist),
+    wheel: source("axis", "pointer wheel", sinks.wheel),
+    mouseDelta: source("vec2", "mouse motion (pointer locked)", sinks.mouseDelta),
+  }
+}