@solidrt/2d 0.0.59 → 0.0.61

package/src/camera2d.ts

@@ -2,8 +2,19 @@
 // over the layers' shared CameraUpdate - a pose (the world point at a
 // viewport pivot, zoom, rotation), the contain clamp against world
 // bounds, anchored zoom, eased glides (a wheel notch, glideTo, fit),
-// follow with damping and a dead zone, drag inertia, rotation about the
-// pivot - extracted so apps stop rebuilding the same hundred lines.
+// follow through Cinemachine's framing (a dead zone, hard limits,
+// damping per axis, lookahead), drag inertia, rotation about the pivot,
+// and the lanes (a screen offset, shakes) - extracted so apps stop
+// rebuilding the same hundred lines.
+//
+// The control runs the pipeline of okf/design/camera-controls.md: a
+// SOURCE (an input nudge, a verb, or the follow) writes the pose; the
+// FRAMING eases the followed point back into its zones; the LANES are
+// summed on top of the pose; the CONSTRAINTS (the zoom range, the
+// contain clamp) apply to pose plus the persistent offset and move the
+// pose, and clip a shake at push without touching it; and the PUSH
+// writes the final camera. pose() is the pose alone; camera() is the
+// final camera as the layers received it (what projectCamera takes).
 //
 // The control is pure (ARCHITECTURE.md: controls through an abstraction,
 // never direct event handling): it consumes three axes, `pan` (vec2),
@@ -16,14 +27,16 @@
 //
 // 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.
+// half; okf/notes/2d-camera-conventions.md): 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), at once for a direct write
+// and eased when `world.damping` says so for a motion (Godot's
+// limit_smoothed); 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.
 //
 // Input units: a `pan` delta is finger travel in viewport heights (the
 // pointer feed's unit), applied as content travel - the world follows the
@@ -33,51 +46,39 @@
 // unbracketed (a wheel notch) it retargets an eased glide, which is how
 // the control tells a finger from an impulse. A `roll` delta is turns. A
 // pan gesture's begin stops any glide (a finger landing on a gliding view
-// holds it), its end flings with the drag's velocity.
+// holds it), its end flings with the release velocity the gesture
+// measured (the pointer feed's, in viewport heights per second: one
+// estimator for every recognizer, velocity.ts in core), decaying.
 //
 // Pose is plain mutable state; a nudge or a verb pushes it at once (the
 // next paint carries the new camera, no frame loop needed for a drag),
-// and update(dt) advances glides, follow, inertia and the axis rates from
-// the app's own onFrame. `active()` is the reactive frame-loop gate (a
-// glide, fling, fit or follow in flight, or a rate driving); a resting
-// camera costs nothing. update() pushes the pose to the layers only when
-// it changed (one setCamera per driven layer: a shared-params write,
-// however many sprites exist) and reports that, so per-frame dependents
-// (labels re-projected via projectCamera) can follow the camera without
-// recomputing every frame.
+// and update(dt) advances glides, follow, inertia, the lanes and the axis
+// rates from the app's own onFrame. `active()` is the reactive frame-loop
+// gate (a glide, fling, fit, follow, shake or damped bound in flight, or
+// a rate driving); a resting camera costs nothing. update() pushes the
+// pose to the layers only when it changed (one setCamera per driven
+// layer: a shared-params write, however many sprites exist) and reports
+// that, so per-frame dependents (labels re-projected via projectCamera)
+// can follow the camera without recomputing every frame.
 
-import { createMemo, createSignal, untrack } from "@solidjs/signals"
+import { untrack } from "@solidjs/signals"
 import { createAxes } from "@solidrt/core/input"
 import type { Axes, Vec2 } from "@solidrt/core/input"
+import { checkFollowOptions, checkOffset, checkShake, createActivity, createLanes, createLookahead, easeStep, frame, GLIDE_EASE, GLIDE_EPSILON } from "@solidrt/core/camera-control"
+import type { FollowOptions } from "@solidrt/core/camera-control"
 import { projectCamera, unprojectCamera } from "./camera.ts"
-import type { CameraUpdate } from "./camera.ts"
+import type { CameraState, CameraUpdate } from "./camera.ts"
 
-// 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
-// (the 3d controls' rate, motion.ts there); `damping` scales a notch's.
-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).
+// A glide lands when the remaining travel is under this many screen
+// pixels. Also the follow's settle threshold, the damped bound's, 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.
+// are snappier. The release speed itself comes from the gesture (a
+// rested finger reads zero there), so nothing gates it here.
 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
 // Rate axes at full deflection, per second: viewport heights of pan,
 // octaves of zoom (1 = the zoom doubles each second), turns of roll.
 const PAN_RATE = 1
@@ -103,8 +104,12 @@ export type Camera2dOptions = Camera2dPose & {
    * 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 }
+   * is wider than the world centers. Absent = unbounded. `damping` eases
+   * a MOTION (a follow, a glide, a fling) into the bounds instead of
+   * cutting it at the edge, as a multiple of the built-in settle time
+   * (Godot's limit_smoothed); a direct write (a drag, set) always clamps
+   * at once. Default 0: at once. */
+  world?: { width: number; height: number; damping?: 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
@@ -115,9 +120,16 @@ export type Camera2dOptions = Camera2dPose & {
    * 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 }
+  /** How follow(x, y) chases its point (the framing stage): damping per
+   * axis, the dead zone and hard limits as fractions of the viewport
+   * centered on the pivot, lookahead. Read where it applies. */
+  follow?: FollowOptions
+  /** The offset lane: where the pose's world point is shown, in viewport
+   * HEIGHTS from the pivot (x right, y down; [0, -0.25] shows it a
+   * quarter of the height above the pivot - the look-up of a platformer).
+   * Added on top of the pose at push, never in pose(); the bounds
+   * contain pose plus offset by moving the pose. */
+  offset?: Vec2
   /** Multipliers over the built-in pan, zoom (pinch, wheel and rate) and
    * roll sensitivities. */
   panSpeed?: number
@@ -128,8 +140,6 @@ export type Camera2dOptions = Camera2dPose & {
    * built-in ease, 2 coasts twice as long, 0 applies notches at once, as
    * a pinch does. The 3d controls' knob, same meaning. */
   damping?: number
-  /** Multiplier over the built-in follow damping. */
-  followSpeed?: number
   /** Whether a drag release keeps the view gliding (default true). */
   inertia?: boolean
 }
@@ -137,54 +147,68 @@ export type Camera2dOptions = Camera2dPose & {
 export type Camera2dAxes = { pan: "vec2"; zoom: "axis"; roll: "axis" }
 
 export type Camera2d = {
-  /** The pose as the layers receive it (a fresh object per call): the
-   * argument for projectCamera/unprojectCamera. */
-  camera(): CameraUpdate
+  /** The final camera as the layers received it (a fresh object per
+   * call, every field set): the pose plus the lanes - the argument for
+   * projectCamera/unprojectCamera. */
+  camera(): CameraState
   /** Pose snapshot - the control's own four values, the shape set() takes
-   * (camera() adds the pivot the layers are told). */
+   * (the 3d controls' pose()); no lane in it. */
   pose(): Required<Camera2dPose>
   /** Merge a pose in (clamps apply) and push it. A snap: an x/y/zoom
-   * write cancels a glide or fling in flight; rotation alone leaves them
-   * running. */
+   * write drops a glide or fling in flight and ends the follow; a
+   * rotation write leaves them running. */
   set(pose: Camera2dPose): void
   /** Pan the content by a screen delta (a drag: positive dx slides the
-   * world rightward) and push. Feeds the inertia estimate; release()
-   * flings. */
+   * world right, the camera point moves left), clamped, and push. */
   panBy(dx: number, dy: number): void
-  /** End of a drag: keep gliding with the drag's velocity (inertia). */
-  release(): void
+  /** End of a drag: keep gliding from its release velocity, screen pixels
+   * per second of content travel, decaying (nothing while following, or
+   * with `inertia` off). */
+  release(velocity: Vec2): void
   /** Zoom by `factor` about a screen point - the world point under it
-   * stays under it - and push. `glide` eases there instead (a wheel
-   * notch): notches compound on the pending target, so a fast scroll is
-   * one long push. */
+   * stays under it (factor > 1 zooms in), clamped to the zoom range and
+   * the bounds, and push. `glide` eases there instead (a wheel notch),
+   * retargeting the pending glide so notches compound. */
   zoomAt(sx: number, sy: number, factor: number, opts?: { glide?: boolean }): void
-  /** Turn by radians about the pivot and push. */
+  /** Turn the world about the pivot by radians (clockwise, y-down) and push. */
   rollBy(angle: 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. */
+  /** Ease the pose to put world (x, y) at the pivot, at `zoom` (default
+   * the current, or a pending wheel or double-tap zoom's target) and
+   * `rotation` (default the current), landing exactly; a fling or a
+   * follow yields. */
+  glideTo(x: number, y: number, zoom?: number, rotation?: number): void
+  /** Frame a world rect (default the whole world): centered in the view
+   * at the zoom that fits it, clamped. A snap unless `glide`. Waits for
+   * the viewport when its size is not known yet. */
   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 (every frame for a moving one).
-   * Cancels a pose glide (glideTo, fit) and a fling; a wheel zoom keeps
-   * gliding - zoom and follow are separate axes. */
+  /** Chase a world point (the framing stage, options.follow): the pose
+   * eases toward it per axis, through the dead zone and hard limits,
+   * with lookahead. Call it every frame for a moving point; the control
+   * settles once the point rests inside the zones. A pose glide yields;
+   * an anchor glide (a wheel zoom) keeps running - zoom and follow are
+   * separate axes. */
   follow(x: number, y: number): void
   unfollow(): void
+  /** A shake on the lanes: `strength` is the peak displacement in
+   * viewport heights, `duration` seconds, an optional frequency (cycles
+   * per second) and direction (a unit [x, y], y down). Shakes sum and
+   * decay; the pose is untouched, and at a world edge the shake is
+   * clipped by the bounds (it never shows the outside). */
+  shake(strength: number, duration: number, opts?: { frequency?: number; direction?: Vec2 }): 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, inertia and the axis rates, 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 since the previous
-   * update (nudges and verbs included). */
+  /** Advance glides, follow, inertia, the lanes and the axis rates, then
+   * push the camera to the layers if it changed. Call from onFrame with
+   * the frame's dt in seconds; returns whether the camera changed since
+   * the previous update (nudges and verbs included). */
   update(dt: number): boolean
   /**
    * Reactive: whether update() still has work - a glide, fling or
-   * deferred fit in flight, a follow engaged, a write not yet pushed, or
-   * an axis rate driving. The frame-loop gate: run update(dt) on frames
+   * deferred fit in flight, a follow engaged and not settled, a shake
+   * running, a damped bound still easing, a write not yet pushed, or an
+   * axis rate driving. The frame-loop gate: run update(dt) on frames
    * while true, and nothing while false (a resting camera costs no frames).
    */
   active(): boolean
@@ -195,7 +219,7 @@ export type Camera2d = {
   axes: Axes<Camera2dAxes>
 }
 
-type Glide = { kind: "anchor"; target: number; sx: number; sy: number; wx: number; wy: number } | { kind: "pose"; x: number; y: number; zoom: number }
+type Glide = { kind: "anchor"; target: number; sx: number; sy: number; wx: number; wy: number } | { kind: "pose"; x: number; y: number; zoom: number; rotation: number }
 
 let clampNum = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v))
 
@@ -214,16 +238,15 @@ function checkPose(verb: string, pose: Camera2dPose): void {
   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 non-pose options, validated at creation and again at every set()
  * (the live-option re-clamp entry). */
 function checkOptions(options: Camera2dOptions): void {
   if (options.world) {
     positive("world.width", options.world.width)
     positive("world.height", options.world.height)
+    if (options.world.damping !== undefined && !(Number.isFinite(options.world.damping) && options.world.damping >= 0)) {
+      throw new Error(`createCamera2d: world.damping must be a non-negative number, got ${options.world.damping}`)
+    }
   }
   if (options.minZoom !== undefined) positive("minZoom", options.minZoom)
   if (options.maxZoom !== undefined) positive("maxZoom", options.maxZoom)
@@ -235,8 +258,8 @@ function checkOptions(options: Camera2dOptions): void {
   if (options.damping !== undefined && !(Number.isFinite(options.damping) && options.damping >= 0)) {
     throw new Error(`createCamera2d: damping must be a non-negative number, got ${options.damping}`)
   }
-  checkFraction("deadZone.width", options.deadZone?.width ?? 0)
-  checkFraction("deadZone.height", options.deadZone?.height ?? 0)
+  checkFollowOptions("createCamera2d", options.follow)
+  checkOffset("createCamera2d", options.offset)
 }
 
 /**
@@ -247,10 +270,10 @@ function checkOptions(options: Camera2dOptions): void {
  * applies immediately: the world fitted when `world` is given and no
  * `zoom`. The pose options are initial values; every other option is read
  * where it applies, so a caller holding the options object (or a props
- * object handing out getters) changes bounds, pivot, dead zone and rates
- * live - `set({})` re-clamps and pushes the pose under new bounds. In a
- * component tree, prefer `<Camera2d>`: it drives the nearest view through
- * context and takes an input map as a prop.
+ * object handing out getters) changes bounds, pivot, the follow's zones
+ * and rates live - `set({})` re-clamps and pushes the pose under new
+ * bounds. In a component tree, prefer `<Camera2d>`: it drives the nearest
+ * view through context and takes an input map as a prop.
  */
 export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], options: Camera2dOptions): Camera2d {
   let targets = Array.isArray(target) ? target : [target]
@@ -265,14 +288,12 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
   let maxZoom = () => options.maxZoom ?? Infinity
   let pivotFx = () => options.pivot?.x ?? 0.5
   let pivotFy = () => options.pivot?.y ?? 0.5
-  let deadW = () => options.deadZone?.width ?? 0
-  let deadH = () => options.deadZone?.height ?? 0
   let panSpeed = () => options.panSpeed ?? 1
   let zoomExponent = () => options.zoomSpeed ?? 1
   let rollSpeed = () => options.rollSpeed ?? 1
   let damping = () => options.damping ?? 1
-  let followEase = () => FOLLOW_EASE * (options.followSpeed ?? 1)
   let inertia = () => options.inertia ?? true
+  let boundsDamping = () => options.world?.damping ?? 0
 
   let w0 = world()
   let x = options.x ?? (w0 ? w0.width / 2 : 0)
@@ -302,8 +323,49 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
     return Math.min(options.minZoom ?? fit, maxZoom())
   }
 
+  // The pose as a camera (no lanes): what the framing and the anchors
+  // measure against.
+  let poseCamera = (): CameraState => ({ 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]
+  }
+  // ---- The lanes ----
+  let lanes = createLanes()
+  // The camera point for a pose point under a lane offset (viewport
+  // heights): the pose's world point is shown at the pivot plus the
+  // offset, so the point AT the pivot is the one that far back.
+  let shifted = (cx: number, cy: number, z: number, ox: number, oy: number): [number, number] => {
+    if (ox === 0 && oy === 0) return [cx, cy]
+    let c = Math.cos(rotation)
+    let s = Math.sin(rotation)
+    let dx = ox * vh
+    let dy = oy * vh
+    return [cx - (dx * c + dy * s) / z, cy - (dy * c - dx * s) / z]
+  }
+  // The persistent lane only: what the bounds contain (moving the pose)
+  // and what a zoom or glide lands against.
+  let withOffset = (cx: number, cy: number, z: number): [number, number] => shifted(cx, cy, z, options.offset?.[0] ?? 0, options.offset?.[1] ?? 0)
+  let steadyCamera = (): CameraState => {
+    let [fx, fy] = withOffset(x, y, zoom)
+    return { x: fx, y: fy, zoom, rotation, pivotX: px(), pivotY: py() }
+  }
+  // The final camera: the shakes on top, clipped by the bounds at push
+  // (a shake never enters the pose and never shows the outside).
+  let camera = (): CameraState => {
+    let [ox, oy] = lanes.total(options.offset)
+    let [fx, fy] = shifted(x, y, zoom, ox, oy)
+    if (lanes.active()) [fx, fy] = contain(fx, fy, zoom)
+    return { x: fx, y: fy, zoom, rotation, pivotX: px(), pivotY: py() }
+  }
+
   // The contain clamp on an unrotated view rect (Godot's rule: limits
-  // ignore rotation): returns the pose's x/y, moved inside the world.
+  // ignore rotation): returns the camera point, moved inside the world.
   let contain = (cx: number, cy: number, z: number): [number, number] => {
     let w = world()
     if (!w || !known()) return [cx, cy]
@@ -315,21 +377,34 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
     top = viewH >= w.height ? (w.height - viewH) / 2 : clampNum(top, 0, w.height - viewH)
     return [left + px() / z, top + py() / z]
   }
-  let clamp = () => {
+  // The constraints on pose plus offset: the zoom range, then the contain
+  // clamp of the camera point, which moves the pose by the same delta
+  // (the offset stays). At once, or eased over dt when the bounds damp a
+  // motion; leaves whether the pose is contained now in boundsSettled.
+  let boundsSettled = true
+  let clampTo = (dt: number | null) => {
     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]
+    let [fx, fy] = withOffset(x, y, zoom)
+    let [cx, cy] = contain(fx, fy, zoom)
+    let dx = cx - fx
+    let dy = cy - fy
+    if (dx === 0 && dy === 0) {
+      boundsSettled = true
+      return
+    }
+    let d = boundsDamping()
+    if (dt === null || d <= 0 || Math.hypot(dx, dy) * zoom < LAND_PX) {
+      x += dx
+      y += dy
+      boundsSettled = true
+      return
+    }
+    let k = easeStep(GLIDE_EASE / d, dt)
+    x += dx * k
+    y += dy * k
+    boundsSettled = false
   }
+  let clamp = () => clampTo(null)
   // 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) => {
@@ -340,19 +415,15 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
   }
 
   let dirty = false
-  // Whether the pose changed since the last update() (pushes included).
+  // Whether the camera changed since the last update() (pushes included).
   let changed = 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
+  let lookahead = createLookahead()
+  let predicted: number[] = [0, 0]
   // 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 && w0 ? { rect: null, glide: false } : null
@@ -361,19 +432,11 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
     dirty = true
     followSettled = false
   }
-  // A pan gesture in flight keeps the camera active: update(dt) then folds
-  // the drag's deltas into the velocity estimate every frame, so the fling
-  // at release carries the finger's speed and not the whole drag's travel
-  // over one assumed frame.
-  let dragging = false
-  let busy = () => dirty || dragging || glide !== null || fling !== null || followAt !== null || pendingFit !== null
-  // The motion's half of active(), a signal every public entry refreshes
-  // (ownedWrite: entries run from component bodies and handlers alike).
-  let [motionActive, setMotionActive] = createSignal(false, { ownedWrite: true })
-  let notify = () => {
-    let now = busy()
-    if (now !== untrack(motionActive)) setMotionActive(now)
-  }
+  let busy = () => dirty || glide !== null || fling !== null || (followAt !== null && !followSettled) || pendingFit !== null || lanes.active() || !boundsSettled
+  // The frame-loop gate (core's createActivity), built once the axes
+  // exist; notified at the end of every public entry.
+  let activity!: ReturnType<typeof createActivity>
+  let notify = () => activity.notify()
   let interrupt = () => {
     glide = null
     fling = null
@@ -393,22 +456,33 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
   }
 
   let zoomTo = (sx: number, sy: number, next: number) => {
-    let [wx, wy] = unprojectCamera(camera(), sx, sy)
+    let [wx, wy] = unprojectCamera(steadyCamera(), sx, sy)
     zoom = clampNum(next, minZoom(), maxZoom())
-    ;[x, y] = anchorPose(wx, wy, sx, sy, zoom)
+    let [nx, ny] = anchorPose(wx, wy, sx, sy, zoom)
+    // anchorPose places the camera point; the pose sits the offset back
+    // from it.
+    let [lx, ly] = withOffset(0, 0, zoom)
+    x = nx - lx
+    y = ny - ly
     clamp()
     touch()
   }
-  let glideTo = (tx: number, ty: number, tz?: number) => {
+  let glideTo = (tx: number, ty: number, tz?: number, tr?: number) => {
     finite("glideTo x", tx)
     finite("glideTo y", ty)
+    finite("glideTo rotation", tr)
     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 }
+    // A pending anchor glide (a wheel notch, a double tap's octave) hands
+    // its zoom over: the glide centres the point AND lands that zoom,
+    // instead of the later verb cancelling the earlier gesture.
+    let pending = glide !== null && glide.kind === "anchor" ? glide.target : zoom
+    let z = clampNum(tz ?? pending, minZoom(), maxZoom())
+    let [lx, ly] = withOffset(0, 0, z)
+    let [cx, cy] = contain(tx + lx, ty + ly, z)
+    glide = { kind: "pose", x: cx - lx, y: cy - ly, zoom: z, rotation: tr ?? rotation }
   }
   let fitNow = (rect: Rect2d | null, ease: boolean) => {
     let w = world()
@@ -416,13 +490,15 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
     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)
+    let [lx, ly] = withOffset(0, 0, z)
     if (ease) {
-      glideTo(nx, ny, z)
+      glideTo(nx - lx, ny - ly, z)
       return
     }
     interrupt()
-    x = nx
-    y = ny
+    followAt = null
+    x = nx - lx
+    y = ny - ly
     zoom = z
     clamp()
     touch()
@@ -432,27 +508,12 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
     interrupt()
     shift(dx, dy)
     clamp()
-    dragDx += dx
-    dragDy += dy
     touch()
   }
-  let release = () => {
-    // Fold the delta still pending from the release's own frame in with
-    // the last frame time, then start from rest either way. The fling
-    // gates on the SMOOTHED velocity too: a finger that stopped before
-    // lifting has let it decay over the still frames, and the stray delta
-    // the release frame may still carry (the resampler's last correction)
-    // must not fling the view on its own.
-    let smoothed = Math.hypot(vx, vy)
-    let rvx = vx + (dragDx / lastDt - vx) * VELOCITY_SMOOTH
-    let rvy = vy + (dragDy / lastDt - vy) * VELOCITY_SMOOTH
-    dragDx = 0
-    dragDy = 0
-    vx = 0
-    vy = 0
+  let release = (velocity: Vec2) => {
     if (!inertia() || followAt !== null) return
-    if (smoothed < FLING_MIN_SPEED || Math.hypot(rvx, rvy) < FLING_MIN_SPEED) return
-    fling = { vx: rvx, vy: rvy }
+    if (velocity[0] === 0 && velocity[1] === 0) return
+    fling = { vx: velocity[0], vy: velocity[1] }
   }
   let zoomAt = (sx: number, sy: number, factor: number, ease: boolean) => {
     positive("zoomAt factor", factor)
@@ -468,7 +529,7 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
     // long push; the anchor is the world point under the pointer now.
     let from = glide !== null ? glide.target : zoom
     let target = clampNum(from * factor, minZoom(), maxZoom())
-    let [wx, wy] = unprojectCamera(camera(), sx, sy)
+    let [wx, wy] = unprojectCamera(steadyCamera(), sx, sy)
     glide = { kind: "anchor", target, sx, sy, wx, wy }
   }
   let rollBy = (angle: number) => {
@@ -481,18 +542,36 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
   // gesture has none.
   let focalPx = (focal: Vec2 | undefined): [number, number] => (focal ? [focal[0] * vw, focal[1] * vh] : [px(), py()])
 
+  // ---- The follow: the framing stage ----
+  let stepFollow = (dt: number): boolean => {
+    let point = lookahead.predict([followAt!.x, followAt!.y], options.follow?.lookahead, dt, predicted)
+    // The point's offset from the pivot in viewport fractions, measured
+    // against the POSE camera: the lanes shift the picture afterwards.
+    let [sx, sy] = projectCamera(poseCamera(), point[0]!, point[1]!)
+    let framed = frame([(sx - px()) / vw, (sy - py()) / vh], options.follow, dt, LAND_PX / vh)
+    let moved = framed.x !== 0 || framed.y !== 0
+    if (moved) {
+      shift(-framed.x * vw, -framed.y * vh)
+      clampTo(dt)
+      dirty = true
+    }
+    followSettled = framed.settled
+    return moved
+  }
+
   let axes = createAxes<Camera2dAxes>(
     { pan: "vec2", zoom: "axis", roll: "axis" },
     {
       onBegin: name => {
         if (name !== "pan") return
-        dragging = true
         interrupt()
       },
-      onEnd: name => {
+      onEnd: (name, velocity) => {
         if (name !== "pan") return
-        dragging = false
-        release()
+        // Viewport heights per second of finger travel to screen pixels
+        // per second of content travel, the pan delta's own mapping.
+        let v = (velocity as Vec2 | undefined) ?? [0, 0]
+        release([v[0] * vh * panSpeed(), v[1] * vh * panSpeed()])
         notify()
       },
       onNudge: (name, delta, focal) => {
@@ -511,7 +590,8 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
       },
     },
   )
-  let active = createMemo(() => motionActive() || axes.active())
+  activity = createActivity(busy, () => axes.active())
+  let active = activity.active
 
   readViewport()
   clamp()
@@ -535,7 +615,10 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
       // change), so the options are validated here as at creation.
       checkOptions(options)
       readViewport()
-      if (pose.x !== undefined || pose.y !== undefined || pose.zoom !== undefined) interrupt()
+      if (pose.x !== undefined || pose.y !== undefined || pose.zoom !== undefined) {
+        interrupt()
+        followAt = null
+      }
       if (pose.x !== undefined) x = pose.x
       if (pose.y !== undefined) y = pose.y
       if (pose.zoom !== undefined) zoom = pose.zoom
@@ -550,8 +633,11 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
       panBy(dx, dy)
       flush()
     },
-    release() {
-      release()
+    release(velocity) {
+      if (!Array.isArray(velocity) || velocity.length !== 2) throw new Error(`createCamera2d: release() takes [vx, vy], got ${JSON.stringify(velocity)}`)
+      finite("release vx", velocity[0])
+      finite("release vy", velocity[1])
+      release(velocity)
       notify()
     },
     zoomAt(sx, sy, factor, opts) {
@@ -565,8 +651,8 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
       rollBy(angle)
       flush()
     },
-    glideTo(tx, ty, tz) {
-      glideTo(tx, ty, tz)
+    glideTo(tx, ty, tz, tr) {
+      glideTo(tx, ty, tz, tr)
       notify()
     },
     fit(rect, opts) {
@@ -588,8 +674,10 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
       // a moving target must not cancel the zoom under it.
       if (glide !== null && glide.kind === "pose") glide = null
       fling = null
-      if (followAt === null) followAt = { x: tx, y: ty }
-      else {
+      if (followAt === null) {
+        followAt = { x: tx, y: ty }
+        lookahead.reset()
+      } else {
         followAt.x = tx
         followAt.y = ty
       }
@@ -600,6 +688,11 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
       followAt = null
       notify()
     },
+    shake(strength, duration, opts) {
+      checkShake("createCamera2d", strength, duration, opts)
+      lanes.shake(strength, duration, opts)
+      notify()
+    },
     interrupt,
     viewRect() {
       readViewport()
@@ -653,11 +746,6 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
           clamp()
           touch()
         }
-        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)
@@ -665,57 +753,53 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
         fling.vx *= decay
         fling.vy *= decay
         if (Math.hypot(fling.vx, fling.vy) < LAND_PX * FLING_DECAY) fling = null
-        clamp()
+        clampTo(dt)
         touch()
       }
       if (glide !== null && dt > 0) {
         // A wheel notch's glide coasts as `damping` says; a commanded
         // glide (glideTo, fit) at the built-in rate.
-        let k = 1 - Math.exp(-(glide.kind === "anchor" ? GLIDE_EASE / damping() : GLIDE_EASE) * dt)
+        let k = easeStep(glide.kind === "anchor" ? GLIDE_EASE / damping() : 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)
+          let [nx, ny] = anchorPose(glide.wx, glide.wy, glide.sx, glide.sy, zoom)
+          let [lx, ly] = withOffset(0, 0, zoom)
+          x = nx - lx
+          y = ny - ly
           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
+          let turn = glide.rotation - rotation
+          let landed = Math.abs(gap) < GLIDE_EPSILON && Math.hypot(glide.x - x, glide.y - y) * zoom < LAND_PX && Math.abs(turn) * Math.hypot(vw, vh) < LAND_PX
           if (landed) {
             x = glide.x
             y = glide.y
             zoom = glide.zoom
+            rotation = glide.rotation
             glide = null
           } else {
             zoom *= Math.exp(gap * k)
             x += (glide.x - x) * k
             y += (glide.y - y) * k
+            rotation += turn * k
           }
         }
-        clamp()
+        clampTo(dt)
         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
-        }
+        stepFollow(dt)
+      }
+      if (lanes.active() && dt > 0) {
+        lanes.step(dt)
+        dirty = true
+      }
+      if (!boundsSettled && dt > 0 && glide === null && fling === null && (followAt === null || followSettled)) {
+        // A damped bound still easing after the motion that crossed it
+        // has landed: finish the way in.
+        clampTo(dt)
+        dirty = true
       }
       if (dirty) {
         dirty = false