@solidrt/2d 0.0.55 → 0.0.56

package/src/camera-motion.ts

@@ -0,0 +1,532 @@
+// The 2d camera's motion, pure: a pose (the world point at a viewport
+// pivot, zoom, rotation), the contain clamp against world bounds, anchored
+// zoom, the eased glides (wheel notch, glideTo, fit), follow with damping
+// and a dead zone, and drag inertia. Everything createCamera2d does except
+// the input glue, which lives in camera2d.ts: this module imports no GUI
+// or core module, so checks/camera2d-check.ts runs it headless on flux.
+//
+// Conventions, decided against Godot's Camera2D, Unity's Cinemachine and
+// Three's MapControls (plus the map/whiteboard libraries for the canvas
+// half): the pose is "world point at the pivot" with the pivot defaulting
+// to the viewport center (Godot's drag-center anchor, Cinemachine's screen
+// position, a map's center); bounds CONTAIN the view and center an axis
+// whose view is wider than the world (Cinemachine's confiner skeleton,
+// tldraw's contain origin - Godot's left-wins is the worse behavior);
+// limits ignore rotation, clamping the unrotated view rect (Godot's rule);
+// every ease is exponential and frame-rate independent, zoom eased in log
+// space so a long glide reads evenly.
+
+import { projectCamera, unprojectCamera } from "./camera.ts"
+import type { CameraUpdate } from "./camera.ts"
+
+// Zoom exponent per wheel-delta unit (wheel up zooms in); the same rate as
+// @solidrt/3d's orbit camera, so the two feel alike.
+const WHEEL_ZOOM = 0.0015
+// Glide rate toward a pending zoom or pose, e-foldings per second: high
+// enough that a wheel notch reads as one push, low enough to look smooth.
+const GLIDE_EASE = 9
+// A glide lands when the remaining zoom gap is under this (relative) ...
+const GLIDE_EPSILON = 0.002
+// ... and the remaining travel is under this many screen pixels. Also the
+// follow's settle threshold and, times the fling decay, the speed a fling
+// stops at (the distance it would still travel).
+const LAND_PX = 0.5
+// Follow damping, e-foldings per second (Godot's default
+// position_smoothing_speed).
+const FOLLOW_EASE = 5
+// Inertia after a drag release: velocity decay in e-foldings per second. A
+// 1500 px/s flick travels 500 px; iOS scrolling decelerates at ~2, maps
+// are snappier.
+const FLING_DECAY = 3
+// Release speeds under this (px/s) do not fling: a finger that stopped
+// before lifting leaves the view where it is.
+const FLING_MIN_SPEED = 50
+// Per-update EMA weight of the drag velocity estimate: heavy on the newest
+// frame so a direction change registers within a frame or two.
+const VELOCITY_SMOOTH = 0.5
+// Frame time assumed for the drag delta still pending at a release when the
+// release arrives in the same frame as the last move.
+const FALLBACK_DT = 1 / 60
+
+/** What a 2d camera drives: anything with the layers' `setCamera`. */
+export type Camera2dTarget = { setCamera(update: CameraUpdate): void }
+
+export type Camera2dPose = {
+  x?: number
+  y?: number
+  zoom?: number
+  rotation?: number
+}
+
+export type Rect2d = { x: number; y: number; width: number; height: number }
+
+export type Camera2dMotionOptions = Camera2dPose & {
+  /** Viewport size in layer pixels, read whenever the camera needs it (a
+   * resize re-clamps at the next update). Return zeros while unknown -
+   * clamping and fitting wait for a real size. */
+  viewport: () => { width: number; height: number }
+  /** World bounds (origin 0,0) the view is kept inside: an axis whose view
+   * is wider than the world centers. Absent = unbounded. */
+  world?: { width: number; height: number }
+  /** Zoom range. minZoom defaults to the fit zoom (whole world visible)
+   * when `world` is given, else to no lower bound; maxZoom to no upper
+   * bound. An explicit maxZoom below the fit zoom wins, the world then
+   * floats centered. */
+  minZoom?: number
+  maxZoom?: number
+  /** Where in the viewport the camera's world point sits, as fractions of
+   * its size; default the center. glideTo and follow land their point
+   * here and rotation turns about it. */
+  pivot?: { x: number; y: number }
+  /** Follow dead zone as fractions of the viewport, centered on the pivot:
+   * the target roams inside it without moving the camera. Default 0,0. */
+  deadZone?: { width: number; height: number }
+  /** Multiplier over the built-in wheel and pinch sensitivity. */
+  zoomSpeed?: number
+  /** Multiplier over the built-in follow damping. */
+  followSpeed?: number
+  /** Whether a drag release keeps the view gliding (default true). */
+  inertia?: boolean
+}
+
+export type Camera2dMotion = {
+  /** The pose as the layers receive it (a fresh object per call): the
+   * argument for projectCamera/unprojectCamera. */
+  camera(): CameraUpdate
+  /** Merge a pose in (clamps apply) and reach the layers at the next
+   * update(). A snap: an x/y/zoom write cancels a glide or fling in
+   * flight; rotation alone leaves them running. */
+  set(pose: Camera2dPose): void
+  /** Pan the content by a screen delta (a drag: positive dx slides the
+   * world rightward). Feeds the inertia estimate; release() flings. */
+  panBy(dx: number, dy: number): void
+  /** End of a drag: keep gliding with the drag's velocity (inertia). */
+  release(): void
+  /** Zoom by `factor` about a screen point - the world point under it
+   * stays under it. */
+  zoomAt(sx: number, sy: number, factor: number): void
+  /** A wheel notch at a screen point: retargets an eased, anchored zoom. */
+  wheel(sx: number, sy: number, deltaY: number): void
+  /** Ease the pose until world (x, y) sits at the pivot, at `zoom` (default
+   * the current zoom). Cancels a follow. */
+  glideTo(x: number, y: number, zoom?: number): void
+  /** Show a world rect (default the world) whole, centered in the
+   * viewport, snapping or gliding. Waits for the viewport if unknown. */
+  fit(rect?: Rect2d, opts?: { glide?: boolean }): void
+  /** Keep world (x, y) at the pivot through the dead zone and damping;
+   * call again whenever the target moves. Cancels a glide. */
+  follow(x: number, y: number): void
+  unfollow(): void
+  /** Stop a glide or fling in flight (a press landing). */
+  interrupt(): void
+  /** The world-space bounding box of what the viewport shows. */
+  viewRect(): Rect2d
+  /** Advance glides, follow and inertia, then push the pose to the
+   * layers if it changed. Call from onFrame with the frame's dt in
+   * seconds; returns whether the pose changed. */
+  update(dt: number): boolean
+  /**
+   * Whether update() still has work: a glide, fling or deferred fit in
+   * flight, a follow engaged, or a write not yet pushed. The frame-loop
+   * gate - run update(dt) on frames while true, and nothing while false
+   * (a resting camera costs no frames).
+   */
+  active(): boolean
+}
+
+type Glide = { kind: "anchor"; target: number; sx: number; sy: number; wx: number; wy: number } | { kind: "pose"; x: number; y: number; zoom: number }
+
+let clampNum = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v))
+
+function positive(what: string, v: number): void {
+  if (!(Number.isFinite(v) && v > 0)) throw new Error(`createCamera2d: ${what} must be a positive number, got ${v}`)
+}
+
+function finite(what: string, v: number | undefined): void {
+  if (v !== undefined && !Number.isFinite(v)) throw new Error(`createCamera2d: ${what} must be a finite number, got ${v}`)
+}
+
+function checkPose(verb: string, pose: Camera2dPose): void {
+  finite(`${verb} x`, pose.x)
+  finite(`${verb} y`, pose.y)
+  finite(`${verb} rotation`, pose.rotation)
+  if (pose.zoom !== undefined) positive(`${verb} zoom`, pose.zoom)
+}
+
+function checkFraction(what: string, v: number): void {
+  if (!(Number.isFinite(v) && v >= 0 && v <= 1)) throw new Error(`createCamera2d: ${what} must be within 0..1, got ${v}`)
+}
+
+/**
+ * The pure motion behind createCamera2d. `onActive` reports each flip of
+ * active() as it happens (the reactive face in camera2d.ts feeds a signal
+ * from it); pure callers poll active() instead.
+ */
+export function createCameraMotion(target: Camera2dTarget | Camera2dTarget[], options: Camera2dMotionOptions, onActive?: (active: boolean) => void): Camera2dMotion {
+  let targets = Array.isArray(target) ? target : [target]
+  if (typeof options.viewport !== "function") throw new Error("createCamera2d: viewport must be a function returning { width, height }")
+  let world = options.world ?? null
+  if (world) {
+    positive("world.width", world.width)
+    positive("world.height", world.height)
+  }
+  if (options.minZoom !== undefined) positive("minZoom", options.minZoom)
+  if (options.maxZoom !== undefined) positive("maxZoom", options.maxZoom)
+  if (options.minZoom !== undefined && options.maxZoom !== undefined && options.minZoom > options.maxZoom) {
+    throw new Error(`createCamera2d: minZoom ${options.minZoom} exceeds maxZoom ${options.maxZoom}`)
+  }
+  checkPose("", options)
+  let pivotFx = options.pivot?.x ?? 0.5
+  let pivotFy = options.pivot?.y ?? 0.5
+  finite("pivot.x", pivotFx)
+  finite("pivot.y", pivotFy)
+  let deadW = options.deadZone?.width ?? 0
+  let deadH = options.deadZone?.height ?? 0
+  checkFraction("deadZone.width", deadW)
+  checkFraction("deadZone.height", deadH)
+  let wheelZoom = WHEEL_ZOOM * (options.zoomSpeed ?? 1)
+  let zoomExponent = options.zoomSpeed ?? 1
+  let followEase = FOLLOW_EASE * (options.followSpeed ?? 1)
+  let inertia = options.inertia ?? true
+  let maxZoom = options.maxZoom ?? Infinity
+
+  let x = options.x ?? (world ? world.width / 2 : 0)
+  let y = options.y ?? (world ? world.height / 2 : 0)
+  let zoom = options.zoom ?? 1
+  let rotation = options.rotation ?? 0
+
+  // The viewport as last read; zeros mean unknown (nothing clamps or fits
+  // until a real size arrives).
+  let vw = 0
+  let vh = 0
+  let known = () => vw > 0 && vh > 0
+  let readViewport = () => {
+    let v = options.viewport()
+    if (!(Number.isFinite(v.width) && Number.isFinite(v.height) && v.width >= 0 && v.height >= 0)) {
+      throw new Error(`createCamera2d: viewport() must return non-negative finite width/height, got ${v.width}x${v.height}`)
+    }
+    vw = v.width
+    vh = v.height
+  }
+  let px = () => vw * pivotFx
+  let py = () => vh * pivotFy
+
+  let minZoom = () => {
+    let fit = world && known() ? Math.min(vw / world.width, vh / world.height) : 0
+    return Math.min(options.minZoom ?? fit, maxZoom)
+  }
+
+  // The contain clamp on an unrotated view rect (Godot's rule: limits
+  // ignore rotation): returns the pose's x/y, moved inside the world.
+  let contain = (cx: number, cy: number, z: number): [number, number] => {
+    if (!world || !known()) return [cx, cy]
+    let viewW = vw / z
+    let viewH = vh / z
+    let left = cx - px() / z
+    let top = cy - py() / z
+    left = viewW >= world.width ? (world.width - viewW) / 2 : clampNum(left, 0, world.width - viewW)
+    top = viewH >= world.height ? (world.height - viewH) / 2 : clampNum(top, 0, world.height - viewH)
+    return [left + px() / z, top + py() / z]
+  }
+  let clamp = () => {
+    zoom = clampNum(zoom, minZoom(), maxZoom)
+    ;[x, y] = contain(x, y, zoom)
+  }
+
+  let camera = (): CameraUpdate => ({ x, y, zoom, rotation, pivotX: px(), pivotY: py() })
+  // Pose x/y that put world (wx, wy) under screen (sx, sy) at zoom z:
+  // the inverse of projectCamera solved for the camera point.
+  let anchorPose = (wx: number, wy: number, sx: number, sy: number, z: number): [number, number] => {
+    let c = Math.cos(rotation)
+    let s = Math.sin(rotation)
+    let dx = sx - px()
+    let dy = sy - py()
+    return [wx - (dx * c + dy * s) / z, wy - (dy * c - dx * s) / z]
+  }
+  // Slide the content by a screen delta: the camera point moves the
+  // opposite way, the delta un-rotated into world axes.
+  let shift = (dx: number, dy: number) => {
+    let c = Math.cos(rotation)
+    let s = Math.sin(rotation)
+    x -= (dx * c + dy * s) / zoom
+    y -= (dy * c - dx * s) / zoom
+  }
+
+  let dirty = false
+  let glide: Glide | null = null
+  let fling: { vx: number; vy: number } | null = null
+  let followAt: { x: number; y: number } | null = null
+  // A follow that reached its target stops writing until something moves.
+  let followSettled = false
+  // Drag deltas since the last update, and the smoothed velocity (px/s).
+  let dragDx = 0
+  let dragDy = 0
+  let vx = 0
+  let vy = 0
+  let lastDt = FALLBACK_DT
+  // A fit that waits for the viewport (the default pose when a world is
+  // given, or an explicit fit() before the size is known).
+  let pendingFit: { rect: Rect2d | null; glide: boolean } | null = options.zoom === undefined && world ? { rect: null, glide: false } : null
+
+  let touch = () => {
+    dirty = true
+    followSettled = false
+  }
+  let active = () => dirty || glide !== null || fling !== null || followAt !== null || pendingFit !== null
+  // Report flips of active() to the hook; every public entry ends here.
+  let wasActive = false
+  let notify = () => {
+    let now = active()
+    if (now === wasActive) return
+    wasActive = now
+    onActive?.(now)
+  }
+  let interrupt = () => {
+    glide = null
+    fling = null
+    notify()
+  }
+  let apply = () => {
+    let update = camera()
+    for (let t of targets) t.setCamera(update)
+  }
+
+  let zoomTo = (sx: number, sy: number, next: number) => {
+    let [wx, wy] = unprojectCamera(camera(), sx, sy)
+    zoom = clampNum(next, minZoom(), maxZoom)
+    ;[x, y] = anchorPose(wx, wy, sx, sy, zoom)
+    clamp()
+    touch()
+  }
+  let glideTo = (tx: number, ty: number, tz?: number) => {
+    finite("glideTo x", tx)
+    finite("glideTo y", ty)
+    if (tz !== undefined) positive("glideTo zoom", tz)
+    readViewport()
+    fling = null
+    followAt = null
+    let z = clampNum(tz ?? zoom, minZoom(), maxZoom)
+    let [cx, cy] = contain(tx, ty, z)
+    glide = { kind: "pose", x: cx, y: cy, zoom: z }
+  }
+  let fitNow = (rect: Rect2d | null, ease: boolean) => {
+    let r = rect ?? (world ? { x: 0, y: 0, width: world.width, height: world.height } : null)
+    if (!r) throw new Error("createCamera2d: fit() needs a rect when the camera has no world")
+    let z = clampNum(Math.min(vw / r.width, vh / r.height), minZoom(), maxZoom)
+    let [nx, ny] = anchorPose(r.x + r.width / 2, r.y + r.height / 2, vw / 2, vh / 2, z)
+    if (ease) {
+      glideTo(nx, ny, z)
+      return
+    }
+    interrupt()
+    x = nx
+    y = ny
+    zoom = z
+    clamp()
+    touch()
+  }
+
+  readViewport()
+  clamp()
+  if (pendingFit && known()) {
+    fitNow(pendingFit.rect, pendingFit.glide)
+    pendingFit = null
+  }
+  dirty = false
+  apply()
+  notify()
+
+  return {
+    camera,
+    active,
+    set(pose) {
+      checkPose("set", pose)
+      readViewport()
+      if (pose.x !== undefined || pose.y !== undefined || pose.zoom !== undefined) interrupt()
+      if (pose.x !== undefined) x = pose.x
+      if (pose.y !== undefined) y = pose.y
+      if (pose.zoom !== undefined) zoom = pose.zoom
+      if (pose.rotation !== undefined) rotation = pose.rotation
+      clamp()
+      touch()
+      notify()
+    },
+    panBy(dx, dy) {
+      readViewport()
+      interrupt()
+      shift(dx, dy)
+      clamp()
+      dragDx += dx
+      dragDy += dy
+      touch()
+      notify()
+    },
+    release() {
+      // Fold the delta still pending from the release's own frame in with
+      // the last frame time, then start from rest either way.
+      let rvx = vx + (dragDx / lastDt - vx) * VELOCITY_SMOOTH
+      let rvy = vy + (dragDy / lastDt - vy) * VELOCITY_SMOOTH
+      dragDx = 0
+      dragDy = 0
+      vx = 0
+      vy = 0
+      if (!inertia || followAt !== null) return
+      if (Math.hypot(rvx, rvy) < FLING_MIN_SPEED) return
+      fling = { vx: rvx, vy: rvy }
+      notify()
+    },
+    zoomAt(sx, sy, factor) {
+      positive("zoomAt factor", factor)
+      readViewport()
+      interrupt()
+      zoomTo(sx, sy, zoom * Math.pow(factor, zoomExponent))
+      notify()
+    },
+    wheel(sx, sy, deltaY) {
+      readViewport()
+      fling = null
+      if (glide !== null && glide.kind === "pose") glide = null
+      // Notches compound on the pending target, so a fast scroll is one
+      // long push; the anchor is the world point under the pointer now.
+      let from = glide !== null ? glide.target : zoom
+      let target = clampNum(from * Math.exp(-deltaY * wheelZoom), minZoom(), maxZoom)
+      let [wx, wy] = unprojectCamera(camera(), sx, sy)
+      glide = { kind: "anchor", target, sx, sy, wx, wy }
+      notify()
+    },
+    glideTo(tx, ty, tz) {
+      glideTo(tx, ty, tz)
+      notify()
+    },
+    fit(rect, opts) {
+      readViewport()
+      if (!known()) {
+        pendingFit = { rect: rect ?? null, glide: opts?.glide ?? false }
+        notify()
+        return
+      }
+      fitNow(rect ?? null, opts?.glide ?? false)
+      notify()
+    },
+    follow(tx, ty) {
+      finite("follow x", tx)
+      finite("follow y", ty)
+      glide = null
+      fling = null
+      if (followAt === null) followAt = { x: tx, y: ty }
+      else {
+        followAt.x = tx
+        followAt.y = ty
+      }
+      followSettled = false
+      notify()
+    },
+    unfollow() {
+      followAt = null
+      notify()
+    },
+    interrupt,
+    viewRect() {
+      readViewport()
+      let cam = camera()
+      let corners = [unprojectCamera(cam, 0, 0), unprojectCamera(cam, vw, 0), unprojectCamera(cam, 0, vh), unprojectCamera(cam, vw, vh)]
+      let minX = Infinity
+      let minY = Infinity
+      let maxX = -Infinity
+      let maxY = -Infinity
+      for (let [cx, cy] of corners) {
+        minX = Math.min(minX, cx)
+        minY = Math.min(minY, cy)
+        maxX = Math.max(maxX, cx)
+        maxY = Math.max(maxY, cy)
+      }
+      return { x: minX, y: minY, width: maxX - minX, height: maxY - minY }
+    },
+    update(dt) {
+      let pw = vw
+      let ph = vh
+      readViewport()
+      if (vw !== pw || vh !== ph) {
+        // The pivot moved with the viewport; the world point stays under
+        // it. A resize can also change the fit zoom, hence the re-clamp.
+        if (pendingFit !== null && known()) {
+          fitNow(pendingFit.rect, pendingFit.glide)
+          pendingFit = null
+        }
+        clamp()
+        touch()
+      }
+      if (dt > 0) {
+        vx += (dragDx / dt - vx) * VELOCITY_SMOOTH
+        vy += (dragDy / dt - vy) * VELOCITY_SMOOTH
+        dragDx = 0
+        dragDy = 0
+        lastDt = dt
+      }
+      if (fling !== null && dt > 0) {
+        shift(fling.vx * dt, fling.vy * dt)
+        let decay = Math.exp(-FLING_DECAY * dt)
+        fling.vx *= decay
+        fling.vy *= decay
+        if (Math.hypot(fling.vx, fling.vy) < LAND_PX * FLING_DECAY) fling = null
+        clamp()
+        touch()
+      }
+      if (glide !== null && dt > 0) {
+        let k = 1 - Math.exp(-GLIDE_EASE * dt)
+        if (glide.kind === "anchor") {
+          let gap = Math.log(glide.target / zoom)
+          zoom = Math.abs(gap) < GLIDE_EPSILON ? glide.target : zoom * Math.exp(gap * k)
+          ;[x, y] = anchorPose(glide.wx, glide.wy, glide.sx, glide.sy, zoom)
+          if (zoom === glide.target) glide = null
+        } else {
+          let gap = Math.log(glide.zoom / zoom)
+          let landed = Math.abs(gap) < GLIDE_EPSILON && Math.hypot(glide.x - x, glide.y - y) * zoom < LAND_PX
+          if (landed) {
+            x = glide.x
+            y = glide.y
+            zoom = glide.zoom
+            glide = null
+          } else {
+            zoom *= Math.exp(gap * k)
+            x += (glide.x - x) * k
+            y += (glide.y - y) * k
+          }
+        }
+        clamp()
+        touch()
+      }
+      if (followAt !== null && !followSettled && dt > 0 && known()) {
+        // How far the target sits outside the dead zone, in screen pixels;
+        // the camera eases by that overshoot so the target rides the zone
+        // edge, or snaps the last sub-pixel and settles.
+        let [sx, sy] = projectCamera(camera(), followAt.x, followAt.y)
+        let hw = (deadW * vw) / 2
+        let hh = (deadH * vh) / 2
+        let ox = sx < px() - hw ? sx - (px() - hw) : sx > px() + hw ? sx - (px() + hw) : 0
+        let oy = sy < py() - hh ? sy - (py() - hh) : sy > py() + hh ? sy - (py() + hh) : 0
+        if (Math.hypot(ox, oy) < LAND_PX) {
+          if (ox !== 0 || oy !== 0) {
+            shift(-ox, -oy)
+            clamp()
+            dirty = true
+          }
+          followSettled = true
+        } else {
+          let k = 1 - Math.exp(-followEase * dt)
+          shift(-ox * k, -oy * k)
+          clamp()
+          dirty = true
+        }
+      }
+      if (!dirty) {
+        notify()
+        return false
+      }
+      dirty = false
+      apply()
+      notify()
+      return true
+    },
+  }
+}

package/src/camera.ts

@@ -0,0 +1,86 @@
+// The 2d camera vocabulary, pure: the one camera type both layers share
+// and its world <-> screen mapping as plain functions - no GPU or GUI
+// imports, so the checks rig (checks/camera-check.ts) exercises this
+// module headless on the flux binary. Three consumers implement or undo
+// exactly this mapping and must agree with it: the vertex stages
+// (shaders.ts, uCamera + uCameraRot), the tile layer's composite
+// transform (the <view> props in components.tsx) and the pointer inverse
+// (spriteDispatch in layer.ts, which calls unprojectCamera directly). The
+// check keeps the spellings from drifting.
+
+/**
+ * A camera over a 2d world - the sprite layer's `setCamera`/`camera` prop
+ * and the tile layer's `TileCamera` alike. The world point (`x`, `y`) is
+ * shown at the viewport point (`pivotX`, `pivotY`), the world scaled by
+ * `zoom` and rotated by `rotation` ABOUT that pivot. Rotation turns the
+ * world clockwise (y-down) about the pivot; to render a heading `h`
+ * upward use `rotation = -h - Math.PI / 2`. The pivot defaults to (0, 0),
+ * which makes `{ x, y, zoom }` mean "world x/y at the viewport top-left" -
+ * the plain scrolling camera.
+ *
+ * As a `setCamera` update, absent keys keep their values (the params
+ * rule); as an argument to projectCamera/unprojectCamera, absent keys
+ * read as the defaults (x/y/rotation 0, zoom 1, pivot (0, 0)).
+ */
+export type CameraUpdate = {
+  /** World pixel shown at the pivot (the viewport top-left by default). */
+  x?: number
+  y?: number
+  /** World-to-screen scale; 1 is pixel-for-pixel. */
+  zoom?: number
+  /** Rotation, radians, clockwise (y-down), about the pivot. */
+  rotation?: number
+  /** Viewport point the camera's world point pins to; default (0, 0). */
+  pivotX?: number
+  pivotY?: number
+}
+
+/** A camera snapshot (a layer's `camera()`): CameraUpdate's fields, all
+ * present - the argument for projectCamera/unprojectCamera. */
+export type CameraState = Required<CameraUpdate>
+
+const CAMERA_FIELDS = ["x", "y", "zoom", "rotation", "pivotX", "pivotY"] as const
+
+/**
+ * Validate a setCamera update (throws - the dev validation policy): every
+ * present field must be finite, zoom additionally positive. A NaN rotation
+ * or pivot would otherwise poison the uniforms and blank the layer with no
+ * error. Internal - both layer kinds call it at the top of setCamera.
+ */
+export function checkCamera(update: CameraUpdate): void {
+  for (let key of CAMERA_FIELDS) {
+    let value = update[key]
+    if (value !== undefined && !Number.isFinite(value)) {
+      throw new Error(`setCamera: ${key} must be a finite number, got ${value}`)
+    }
+  }
+  if (update.zoom !== undefined && update.zoom <= 0) {
+    throw new Error(`setCamera: zoom must be positive, got ${update.zoom}`)
+  }
+}
+
+/**
+ * World -> screen under a camera:
+ * `pivot + R(rotation) * zoom * (world - cam)`. Screen means the layer's
+ * viewport pixels (the sprite layer's output, the tile world's container).
+ */
+export function projectCamera(camera: CameraUpdate, worldX: number, worldY: number): [number, number] {
+  let zoom = camera.zoom ?? 1
+  let rotation = camera.rotation ?? 0
+  let c = Math.cos(rotation)
+  let s = Math.sin(rotation)
+  let dx = (worldX - (camera.x ?? 0)) * zoom
+  let dy = (worldY - (camera.y ?? 0)) * zoom
+  return [(camera.pivotX ?? 0) + dx * c - dy * s, (camera.pivotY ?? 0) + dx * s + dy * c]
+}
+
+/** Screen -> world: the exact inverse of projectCamera. */
+export function unprojectCamera(camera: CameraUpdate, screenX: number, screenY: number): [number, number] {
+  let zoom = camera.zoom ?? 1
+  let rotation = camera.rotation ?? 0
+  let c = Math.cos(rotation)
+  let s = Math.sin(rotation)
+  let dx = screenX - (camera.pivotX ?? 0)
+  let dy = screenY - (camera.pivotY ?? 0)
+  return [(camera.x ?? 0) + (dx * c + dy * s) / zoom, (camera.y ?? 0) + (dy * c - dx * s) / zoom]
+}