@johnmorrisdotca/kyogijo-stadiums 0.59.0 → 0.60.1

package/dist/replay.follow.js

@@ -0,0 +1,279 @@
+// Following the play: where the camera looks while a replay plays, as arithmetic on numbers. `followShot` is the shot the play asks for at a moment (the skaters near the puck, padded, or the
+// puck itself, or the faceoff dot in a stoppage); `followCamera` eases toward it with a critically damped spring, a dead zone and a leash that keeps the puck in the frame; `followRunner` is
+// what a page's replay calls on each change of its clock. Nothing here reads the page or a clock: the caller says how many seconds went by, and a test does it with numbers.
+import { replayEvents } from "./replay.js";
+/** The modes, in the order the controls list them after "off". */
+export const FOLLOW_MODES = ["off", "action", "puck"];
+/** A mode from anything: `action` and `puck` are themselves, everything else is `off`. */
+export const followMode = (value) => (value === "action" || value === "puck" ? value : "off");
+/** The camera's limits by default: no closer than two and a half times, the puck followed at twice, the five nearest players, settling in about a second and a half. */
+export const FOLLOW_LIMITS = { maxZoom: 2.5, puckZoom: 2, near: 5, pad: 0.06, dead: 0.08, omega: 3.2, leash: 0.06 };
+const clamp = (value, least, most) => Math.min(most, Math.max(least, value));
+const isNum = (value) => typeof value === "number" && Number.isFinite(value);
+/** The whole surface: the shot of `off`. */
+export const wholeShot = (box) => ({ x: box.x + box.w / 2, y: box.y + box.h / 2, zoom: 1 });
+/** A shot held to the limits: its zoom from 1 to `maxZoom`, and its frame on the surface (the middle moved in until no side of the frame is off it). */
+export function clampShot(shot, box, maxZoom = FOLLOW_LIMITS.maxZoom) {
+    const zoom = clamp(isNum(shot.zoom) ? shot.zoom : 1, 1, Math.max(1, maxZoom));
+    const [hw, hh] = [box.w / zoom / 2, box.h / zoom / 2];
+    const middle = wholeShot(box);
+    return { x: clamp(isNum(shot.x) ? shot.x : middle.x, box.x + hw, box.x + box.w - hw), y: clamp(isNum(shot.y) ? shot.y : middle.y, box.y + hh, box.y + box.h - hh), zoom };
+}
+/** The frame a shot shows: the surface's size over the zoom, round the middle. */
+export const frameOf = (shot, box) => ({ x: shot.x - box.w / shot.zoom / 2, y: shot.y - box.h / shot.zoom / 2, w: box.w / shot.zoom, h: box.h / shot.zoom });
+const onSurface = (p, box) => [clamp(p[0], box.x, box.x + box.w), clamp(p[1], box.y, box.y + box.h)];
+/** The puck or the ball, on the surface, or `undefined` when there is none. */
+function puckOf(input) {
+    const puck = input.objects.find((o) => (o.team === "puck" || o.team === "ball") && isNum(o.x) && isNum(o.y));
+    return puck === undefined ? undefined : onSurface([puck.x, puck.y], input.box);
+}
+/**
+ * The shot the play asks for at a moment. `action` frames the puck (or the ball) and the `near` players nearest it, with `pad` round them, never closer than `maxZoom`: when they bunch at one end
+ * it closes in, and when they spread it pulls back. `puck` puts the puck in the middle at `puckZoom`. A stopped play (`stop`) frames the faceoff dot as closely as the limits allow. The frame is
+ * always on the surface and always holds the puck. Without a puck the action is the players' middle; with nothing at all it is the whole surface.
+ * @example
+ * ```ts
+ * import { followShot } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const box = { x: 0, y: 0, w: 200, h: 85 };
+ * const objects = [{ team: "puck" as const, x: 170, y: 40 }, { team: "home" as const, x: 165, y: 30 }, { team: "away" as const, x: 175, y: 50 }];
+ * const action = followShot("action", { objects, box });
+ * console.log(Math.round(action.x), action.y, Math.round(action.zoom * 100) / 100);
+ * console.log(followShot("puck", { objects, box }));
+ * // 148 40 1.93
+ * // { x: 150, y: 40, zoom: 2 }
+ * ```
+ */
+export function followShot(mode, input, limits = {}) {
+    const { box } = input;
+    const at = { ...FOLLOW_LIMITS, ...limits };
+    if (mode === "off" || !(box.w > 0 && box.h > 0))
+        return wholeShot(box);
+    if (input.stop !== undefined) {
+        const [x, y] = onSurface(input.stop, box);
+        return clampShot({ x, y, zoom: Math.min(at.maxZoom, mode === "puck" ? at.puckZoom : at.maxZoom) }, box, at.maxZoom);
+    }
+    const puck = puckOf(input);
+    const players = input.objects.filter((o) => (o.team === "home" || o.team === "away") && isNum(o.x) && isNum(o.y)).map((o) => onSurface([o.x, o.y], box));
+    if (mode === "puck")
+        return puck === undefined ? followShot("action", input, limits) : clampShot({ x: puck[0], y: puck[1], zoom: at.puckZoom }, box, at.maxZoom);
+    if (puck === undefined && players.length === 0)
+        return wholeShot(box);
+    const anchor = puck ?? [players.reduce((s, p) => s + p[0], 0) / players.length, players.reduce((s, p) => s + p[1], 0) / players.length];
+    const nearest = [...players].sort((a, b) => Math.hypot(a[0] - anchor[0], a[1] - anchor[1]) - Math.hypot(b[0] - anchor[0], b[1] - anchor[1])).slice(0, Math.max(0, Math.round(at.near)));
+    const held = [anchor, ...nearest];
+    const xs = held.map((p) => p[0]);
+    const ys = held.map((p) => p[1]);
+    const pad = Math.max(box.w, box.h) * at.pad;
+    const [x0, x1, y0, y1] = [Math.min(...xs) - pad, Math.max(...xs) + pad, Math.min(...ys) - pad, Math.max(...ys) + pad];
+    const zoom = Math.min(box.w / (x1 - x0), box.h / (y1 - y0), at.maxZoom);
+    return clampShot({ x: (x0 + x1) / 2, y: (y0 + y1) / 2, zoom }, box, at.maxZoom);
+}
+/**
+ * One step of a critically damped spring toward `goal`: where it is and how fast it goes after `dt` seconds. It never overshoots and never rings, and a long step lands nearer, never past.
+ * @example
+ * ```ts
+ * import { springStep } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * let [x, v] = [0, 0];
+ * for (let i = 0; i < 60; i += 1) [x, v] = springStep(x, v, 10, 1 / 60, 4);
+ * console.log(Math.round(x * 100) / 100, x < 10);
+ * // 9.08 true
+ * ```
+ */
+export function springStep(at, speed, goal, dt, omega) {
+    if (!(dt > 0))
+        return [at, speed];
+    const off = at - goal;
+    const pull = speed + omega * off;
+    const fade = Math.exp(-omega * dt);
+    return [goal + (off + pull * dt) * fade, (speed - omega * pull * dt) * fade];
+}
+/**
+ * The camera that follows the play: it eases toward `followShot` with a critically damped spring on the middle and on the zoom (the zoom eased as its logarithm, so a zoom in and a zoom out
+ * take the same time), holds still while the shot moves less than a dead zone, and is kept on the surface, never closer than the limit, with the puck inside the frame. When the play is still
+ * it comes to rest and stays exactly there.
+ * @example
+ * ```ts
+ * import { followCamera } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const camera = followCamera();
+ * const input = { box: { x: 0, y: 0, w: 200, h: 85 }, objects: [{ team: "puck" as const, x: 180, y: 40 }] };
+ * const first = camera.update("puck", input, 1 / 60);
+ * let shot = first;
+ * for (let i = 0; i < 600; i += 1) shot = camera.update("puck", input, 1 / 60);
+ * console.log(first.zoom < 1.01, shot);
+ * // true { x: 150, y: 40, zoom: 2 }
+ * ```
+ */
+export function followCamera(limits = {}) {
+    const at = { ...FOLLOW_LIMITS, ...limits };
+    let now;
+    let goal;
+    let speed = [0, 0, 0];
+    const settle = (shot) => {
+        now = shot;
+        goal = shot;
+        speed = [0, 0, 0];
+    };
+    return {
+        update(mode, input, dt) {
+            const { box } = input;
+            const asked = followShot(mode, input, at);
+            const from = now ?? wholeShot(box);
+            // The dead zone: a shot that moved little from the one the camera is going to is not a new goal.
+            if (goal === undefined || mode === "off" || dt === undefined)
+                goal = asked;
+            else {
+                const frame = frameOf(goal, box);
+                const moved = Math.abs(asked.x - goal.x) > frame.w * at.dead || Math.abs(asked.y - goal.y) > frame.h * at.dead;
+                const zoomed = Math.abs(Math.log(asked.zoom / goal.zoom)) > Math.log(1 + at.dead);
+                goal = { x: moved ? asked.x : goal.x, y: moved ? asked.y : goal.y, zoom: zoomed ? asked.zoom : goal.zoom };
+            }
+            if (dt === undefined) {
+                settle(goal);
+                return { ...goal };
+            }
+            const [x, vx] = springStep(from.x, speed[0], goal.x, dt, at.omega);
+            const [y, vy] = springStep(from.y, speed[1], goal.y, dt, at.omega);
+            const [z, vz] = springStep(Math.log(from.zoom), speed[2], Math.log(goal.zoom), dt, at.omega);
+            speed = [vx, vy, vz];
+            let next = clampShot({ x, y, zoom: Math.exp(z) }, box, at.maxZoom);
+            // The leash: a puck that runs ahead of the easing carries the frame with it, so that it never leaves it; the frame moves as the puck does, never by a jump.
+            const puck = mode === "off" ? undefined : puckOf(input);
+            if (puck !== undefined) {
+                const frame = frameOf(next, box);
+                const [mx, my] = [Math.min(frame.w * at.leash, frame.w / 2), Math.min(frame.h * at.leash, frame.h / 2)];
+                const pull = (p, middle, half, margin) => (p > middle + half - margin ? p - half + margin : p < middle - half + margin ? p + half - margin : middle);
+                next = clampShot({ x: pull(puck[0], next.x, frame.w / 2, mx), y: pull(puck[1], next.y, frame.h / 2, my), zoom: next.zoom }, box, at.maxZoom);
+            }
+            // At rest: close enough to the goal and slow enough is the goal itself, so that a still play writes nothing more.
+            const near = Math.abs(next.x - goal.x) + Math.abs(next.y - goal.y) < Math.max(box.w, box.h) * 1e-4 && Math.abs(Math.log(next.zoom / goal.zoom)) < 1e-4;
+            if (near && Math.abs(speed[0]) + Math.abs(speed[1]) < Math.max(box.w, box.h) * 1e-3 && Math.abs(speed[2]) < 1e-3)
+                settle(goal);
+            else
+                now = next;
+            return { ...now };
+        },
+        shot: () => (now === undefined ? undefined : { ...now }),
+        resting: () => now === undefined || (now.zoom === 1 && goal !== undefined && goal.zoom === 1 && now.x === goal.x && now.y === goal.y && speed.every((v) => v === 0)),
+        reset() {
+            now = undefined;
+            goal = undefined;
+            speed = [0, 0, 0];
+        },
+    };
+}
+/**
+ * How much a view magnifies for a shot's zoom, when the view at 1 shows more than the surface (`room` times it: the margin round a flat drawing, the stands round a 3D one). At a zoom of 1 the
+ * view is as it was; at `maxZoom` the frame fills it; in between the two are joined smoothly, and the view never shows less than the frame.
+ */
+export function zoomFor(zoom, room, maxZoom = FOLLOW_LIMITS.maxZoom) {
+    if (!(zoom > 1) || !(maxZoom > 1))
+        return 1;
+    return Math.pow(Math.max(1, room) * maxZoom, Math.log(Math.min(zoom, maxZoom)) / Math.log(maxZoom));
+}
+/**
+ * The part of a flat drawing to show for a shot: a rectangle in the drawing's `viewBox` units, of the viewBox's shape, round the shot's middle, inside the viewBox, and never smaller than the
+ * shot's frame. `map` takes a point of the surface's frame to the viewBox's (a surface laid tall is turned a quarter in its drawing).
+ * @example
+ * ```ts
+ * import { followWindow } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const box = { x: 0, y: 0, w: 200, h: 85 };
+ * const view = { x: -8, y: -8, w: 216, h: 101 };
+ * console.log(followWindow({ x: 100, y: 42.5, zoom: 1 }, box, view));
+ * console.log(followWindow({ x: 160, y: 42.5, zoom: 2.5 }, box, view));
+ * // { x: -8, y: -8, w: 216, h: 101 }
+ * // { x: 120, y: 23.8, w: 80, h: 37.41 }
+ * ```
+ */
+export function followWindow(shot, box, view, map = (p) => p, maxZoom = FOLLOW_LIMITS.maxZoom) {
+    const span = (points) => {
+        const xs = points.map((p) => p[0]);
+        const ys = points.map((p) => p[1]);
+        return { x: Math.min(...xs), y: Math.min(...ys), w: Math.max(...xs) - Math.min(...xs), h: Math.max(...ys) - Math.min(...ys) };
+    };
+    const corners = (b) => [[b.x, b.y], [b.x + b.w, b.y], [b.x, b.y + b.h], [b.x + b.w, b.y + b.h]].map((p) => map(p));
+    const surface = span(corners(box));
+    const by = zoomFor(shot.zoom, surface.w > 0 && surface.h > 0 ? Math.min(view.w / surface.w, view.h / surface.h) : 1, maxZoom);
+    const [w, h] = [view.w / by, view.h / by];
+    const [cx, cy] = map([shot.x, shot.y]);
+    const round = (n) => Math.round(n * 100) / 100;
+    return { x: round(clamp(cx - w / 2, view.x, view.x + view.w - w)), y: round(clamp(cy - h / 2, view.y, view.y + view.h - h)), w: round(w), h: round(h) };
+}
+/** The kinds of event that stop the play, and the one that starts it again. */
+const STOPS = ["whistle", "goal"];
+/**
+ * The faceoff dot, in the timeline's frame, while the play is stopped at `t`: from a whistle or a goal until the next `faceoff` event that has a place (`x` and `y`), the place of that faceoff.
+ * `undefined` while the play goes on, and always for a timeline with no `faceoff` events: the camera then follows the puck through the stoppage as at any other time.
+ * @example
+ * ```ts
+ * import { followStop } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const timeline = { frames: [{ t: 0, objects: [] }, { t: 30, objects: [] }], events: [{ t: 10, kind: "whistle" }, { t: 20, kind: "faceoff", x: 69, y: 22 }] };
+ * console.log(followStop(timeline, 5), followStop(timeline, 15), followStop(timeline, 25));
+ * // undefined [ 69, 22 ] undefined
+ * ```
+ */
+export function followStop(timeline, t) {
+    const events = replayEvents(timeline);
+    let stopped = false;
+    for (const e of events) {
+        if (e.t > t) {
+            if (stopped && e.kind === "faceoff" && isNum(e.x) && isNum(e.y))
+                return [e.x, e.y];
+            if (stopped && e.kind === "faceoff")
+                return undefined;
+            continue;
+        }
+        if (STOPS.includes(e.kind))
+            stopped = true;
+        else if (e.kind === "faceoff")
+            stopped = false;
+    }
+    return undefined;
+}
+/**
+ * The camera of a replay in a page: on each tick of the clock the spring moves by the seconds that went by; a seek, a step, or a change of mode while paused puts the camera where it should be at
+ * once (a reader who prefers reduced motion gets only steps); a play, a pause, a change of speed or loop moves nothing. Nothing runs between changes, and off and at rest it does nothing at all.
+ */
+export function followRunner(source) {
+    const camera = followCamera(source.limits);
+    let last;
+    let shown;
+    const show = (shot) => {
+        const same = shot === undefined ? shown === undefined : shown !== undefined && shot.x === shown.x && shot.y === shown.y && shot.zoom === shown.zoom;
+        shown = shot;
+        if (!same)
+            source.show(shot);
+    };
+    return {
+        paint({ state, reason }) {
+            const mode = state.followHeld === true ? "held" : (state.follow ?? "off");
+            const tick = reason === "tick";
+            if (!tick)
+                last = undefined;
+            if (mode === "held" || (mode === "off" && camera.resting()))
+                return;
+            if (!tick && !["seek", "step", "motion", "follow"].includes(reason))
+                return;
+            // Turned on or off, or resumed, while playing: the ticks ease it there.
+            if (reason === "follow" && state.playing)
+                return;
+            const stamp = source.now();
+            const dt = tick ? (last === undefined ? 0 : Math.min(0.1, Math.max(0, (stamp - last) / 1000))) : undefined;
+            if (tick)
+                last = stamp;
+            if (dt === 0)
+                return;
+            const input = source.at(state.t, mode === "off" ? undefined : followStop(source.timeline, state.t));
+            const shot = camera.update(mode, input, dt);
+            show(mode === "off" && camera.resting() ? undefined : shot);
+        },
+        again() {
+            if (shown !== undefined)
+                source.show(shown);
+        },
+        reset() {
+            camera.reset();
+            last = undefined;
+            shown = undefined;
+        },
+    };
+}

package/dist/replay.types.d.ts

@@ -117,6 +117,8 @@ export interface ReplaySettings extends ReplayLook {
     stepSeconds?: number;
     /** The time to begin at, in seconds from the first frame. 0 by default. */
     start?: number;
+    /** The camera follows the play: `action` (the players near the puck or ball), `puck` (the puck or ball), or `off` (the default). See `followShot`. */
+    follow?: "off" | "action" | "puck";
 }
 /** A tracked object at a moment, and the trail behind it. */
 export interface ReplayTrail {
@@ -154,9 +156,12 @@ export interface ReplayState {
     loop: boolean;
     /** `step` for a reader who prefers reduced motion: play moves a step, never by itself. */
     motion: "smooth" | "step";
+    /** What the camera follows, and whether the reader's own turn or zoom of a 3D view holds it until it is resumed. */
+    follow: "off" | "action" | "puck";
+    followHeld: boolean;
 }
 /** Why the controller told its listeners. */
-export type ReplayReason = "play" | "pause" | "seek" | "step" | "tick" | "speed" | "loop" | "motion";
+export type ReplayReason = "play" | "pause" | "seek" | "step" | "tick" | "speed" | "loop" | "motion" | "follow";
 /** What a listener of the controller is told. */
 export interface ReplayChange {
     state: Readonly<ReplayState>;

package/dist/strings.core.d.ts

@@ -1010,6 +1010,16 @@ export interface KyogijoWords {
         keysTurn: string;
         keysTurnStep: string;
         region: string;
+        /** The camera that follows the play: the name of its buttons, each button's word and what it does, and the button that lets it follow again after the reader turned the view. */
+        follow: string;
+        followAction: string;
+        followActionLabel: string;
+        followPuck: string;
+        followPuckLabel: string;
+        followBall: string;
+        followBallLabel: string;
+        followResume: string;
+        followResumeLabel: string;
     };
     /** The words of the 3D view: its name, the keys, the viewpoints, the controls, what is announced, and the names of what stands on the surface. */
     turn: {

package/dist/strings.en.js

@@ -447,6 +447,7 @@ export const WORDS_EN = {
         keysTurn: "Replay of the play on the 3D view. Space plays or pauses; comma and full stop step back and on by a frame, and with Shift by 5 seconds; End goes to the end. The arrow keys still turn the view. On the replay's controls the arrow keys step, and Home and End go to the ends.",
         keysTurnStep: "Replay of the play on the 3D view, in steps. Space or full stop moves on, comma goes back, and End goes to the end. The arrow keys still turn the view. On the replay's controls the right arrow key moves on and the left goes back.",
         region: "Replay",
+        follow: "Follow the play", followAction: "Action", followActionLabel: "Follow the action: close in on the puck or ball and those nearest it", followPuck: "Puck", followPuckLabel: "Follow the puck", followBall: "Ball", followBallLabel: "Follow the ball", followResume: "Resume", followResumeLabel: "Follow the action again",
     },
     turn: {
         region: "3D view", group: "Viewpoint",

package/dist/strings.ja.js

@@ -472,6 +472,7 @@ export const WORDS_JA = {
         keysTurn: "3Dビューでのプレーのリプレイです。スペースキーで再生と一時停止、カンマキーで1コマ戻り、ピリオドキーで1コマ進みます。Shiftキーを押しながらカンマキーかピリオドキーで5秒ずつ移動し、Endキーで最後に移動します。矢印キーではこれまでどおりビューを回せます。リプレイの操作ボタンにフォーカスがあるときは、左右の矢印キーで1コマずつ前後に移動し、Homeキーで最初、Endキーで最後に移動します。",
         keysTurnStep: "3Dビューでのプレーのリプレイです。コマ送りで表示しています。スペースキーまたはピリオドキーで進み、カンマキーで戻り、Endキーで最後に移動します。矢印キーではこれまでどおりビューを回せます。リプレイの操作ボタンにフォーカスがあるときは、右矢印キーで進み、左矢印キーで戻ります。",
         region: "リプレイ",
+        follow: "プレーを追う", followAction: "プレー", followActionLabel: "プレーを追う：パックやボールと、その近くの選手に寄って映す", followPuck: "パック", followPuckLabel: "パックを追う", followBall: "ボール", followBallLabel: "ボールを追う", followResume: "再び追う", followResumeLabel: "もう一度プレーを追う",
     },
     turn: {
         region: "3D表示", group: "視点",

package/dist/turn.camera.d.ts

@@ -129,9 +129,10 @@ export declare function multiply(a: Mat4, b: Mat4): number[];
 /**
  * The matrix that puts a point of the scene on the screen for a view in a placement: the scene (whose middle is the origin) is scaled, turned about the vertical,
  * tipped back, shifted to where the fit puts it, and seen with a perspective `distance` pixels deep. This is `project`'s arithmetic as one matrix, so that an
- * element can be given its whole place in one `matrix3d` and need no 3D context of the browser's: a browser that draws nested 3D layers flat still draws it right.
+ * element can be given its whole place in one `matrix3d` and need no 3D context of the browser's: a browser that draws nested 3D layers flat still draws it right. `focus`, a point of the floor
+ * in the scene's pixels from its middle, is put where the middle would be (and, by its third number from 0 to 1, that share of the way to the container's middle): the camera looks at it, and turns and tips about it.
  */
-export declare function cameraMatrix(view: TurnView, at: Placement, distance: number): number[];
+export declare function cameraMatrix(view: TurnView, at: Placement, distance: number, focus?: readonly [number, number] | readonly [number, number, number]): number[];
 /** A matrix as the CSS `transform` that applies it. */
 export declare const matrix3d: (m: Mat4) => string;
 /** How far a point is from the eye's plane after the scene is turned and tipped, in pixels towards the eye: bigger is nearer. Planes are drawn far first. */

package/dist/turn.camera.js

@@ -208,9 +208,10 @@ const translation = (x, y, z) => [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, y, z, 1
 /**
  * The matrix that puts a point of the scene on the screen for a view in a placement: the scene (whose middle is the origin) is scaled, turned about the vertical,
  * tipped back, shifted to where the fit puts it, and seen with a perspective `distance` pixels deep. This is `project`'s arithmetic as one matrix, so that an
- * element can be given its whole place in one `matrix3d` and need no 3D context of the browser's: a browser that draws nested 3D layers flat still draws it right.
+ * element can be given its whole place in one `matrix3d` and need no 3D context of the browser's: a browser that draws nested 3D layers flat still draws it right. `focus`, a point of the floor
+ * in the scene's pixels from its middle, is put where the middle would be (and, by its third number from 0 to 1, that share of the way to the container's middle): the camera looks at it, and turns and tips about it.
  */
-export function cameraMatrix(view, at, distance) {
+export function cameraMatrix(view, at, distance, focus) {
     const k = at.k * view.zoom;
     const [yaw, pitch] = [view.yaw * RAD, view.pitch * RAD];
     const [cy, sy, cp, sp] = [Math.cos(yaw), Math.sin(yaw), Math.cos(pitch), Math.sin(pitch)];
@@ -218,10 +219,14 @@ export function cameraMatrix(view, at, distance) {
     const rotateZ = [cy, sy, 0, 0, -sy, cy, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
     const rotateX = [1, 0, 0, 0, 0, cp, sp, 0, 0, -sp, cp, 0, 0, 0, 0, 1];
     const eye = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, -1 / distance, 0, 0, 0, 1];
-    let m = multiply(eye, translation(at.tx, at.ty, 0));
+    // A focus is brought toward the middle of the container by its share (the fit puts the scene's middle where its whole box is centred, which a tall scoreboard moves).
+    const centring = 1 - Math.min(1, Math.max(0, focus?.[2] ?? 0));
+    let m = multiply(eye, translation(at.tx * centring, at.ty * centring, 0));
     m = multiply(m, rotateX);
     m = multiply(m, rotateZ);
-    return multiply(m, scale);
+    m = multiply(m, scale);
+    // A point of the floor to look at (a camera following the play), in the scene's pixels from its middle: it takes the place the middle had.
+    return focus === undefined || (focus[0] === 0 && focus[1] === 0) ? m : multiply(m, translation(-focus[0], -focus[1], 0));
 }
 /**
  * A number of a matrix as CSS writes it: to ten decimals, with no exponent. The perspective terms of a camera matrix are tiny (a few ten-thousandths) and are multiplied by

package/dist/turn.dom.d.ts

@@ -81,6 +81,11 @@ export declare function turnSupported(win?: {
         supports?: (property: string, value: string) => boolean;
     } | null;
 } | undefined): boolean;
+/** Where a camera that follows the play looks: a point of the floor, in the scene's pixels from its middle, and a zoom on top of the view's own. */
+export interface Aim {
+    focus: [number, number];
+    zoom: number;
+}
 /**
  * Mount a surface as a 3D view in a container, over the static drawing it would otherwise hold: the drawing is the floor, tilted and turned by the pointer, the
  * touch, the wheel and the keys, with what stands on the surface (a net and its posts, a basket, a goal, the posts of a football field) standing on it.

package/dist/turn.dom.js

@@ -35,6 +35,13 @@ export function turnSupported(win = typeof window === "undefined" ? undefined :
     return css.supports("transform", "matrix3d(1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1)");
 }
 const KEYS = { " ": true, ArrowLeft: true, ArrowRight: true, ArrowUp: true, ArrowDown: true, "+": true, "=": true, "-": true, _: true, "0": true, Home: true, "1": true, "2": true, "3": true, "4": true };
+/** The point an aim looks at, brought toward the middle of the view as it closes in: not at all at its zoom of 1, so that turning it on does not move the view. */
+const focusOf = (aim) => (aim === undefined ? undefined : [aim.focus[0], aim.focus[1], 1 - 1 / Math.max(1, aim.zoom)]);
+/** An aim part of the way from one to another (none is the middle at a zoom of 1). */
+const aimBetween = (from, to, t) => {
+    const [a, b] = [from ?? { focus: [0, 0], zoom: 1 }, to ?? { focus: [0, 0], zoom: 1 }];
+    return { focus: [a.focus[0] + (b.focus[0] - a.focus[0]) * t, a.focus[1] + (b.focus[1] - a.focus[1]) * t], zoom: a.zoom * Math.pow(b.zoom / a.zoom, t) };
+};
 /** The view part of the way from one to another, `t` from 0 to 1, the turn taken the short way round. */
 const between = (from, to, t) => ({ yaw: from.yaw + (nearest(from.yaw, to.yaw) - from.yaw) * t, pitch: from.pitch + (to.pitch - from.pitch) * t, zoom: from.zoom * Math.pow(to.zoom / from.zoom, t) });
 /**
@@ -176,6 +183,14 @@ export function mountTurn(host, options, settings, build, replayable = false, le
     let shown = view;
     let opening = model.view;
     let flight;
+    /** What a camera that follows the play looks at (a point of the floor, and a zoom on top of the view's), where it is going in a glide, and who is told when the reader takes the view over. */
+    let aim;
+    let aimTo;
+    const users = new Set();
+    const took = (kind) => {
+        for (const user of [...users])
+            user(kind);
+    };
     let spoken;
     // The auto-turn: whether it is on, the frame that will advance it, the time of the last one, and whether it has moved the view since the page was last told.
     let playing = false;
@@ -273,7 +288,7 @@ export function mountTurn(host, options, settings, build, replayable = false, le
         model = decorate === undefined ? plain : decorate(plain);
         ceiling = ceilingFor(model, stage.clientWidth || 960, stage.clientHeight || 600, shown.zoom);
         raster = rasterFor(model);
-        const layout = layoutOf(model, shown, stage.clientWidth || 960, stage.clientHeight || 600, settings.lens, false, raster);
+        const layout = layoutOf(model, aim === undefined ? shown : { ...shown, zoom: shown.zoom * aim.zoom }, stage.clientWidth || 960, stage.clientHeight || 600, settings.lens, false, raster, focusOf(aim));
         const world = root.querySelector(".ky-turn-world");
         world.innerHTML = worldMarkup(model, layout, raster);
         // The look the floor is painted in (and the theme) are attributes of the world.
@@ -342,10 +357,11 @@ export function mountTurn(host, options, settings, build, replayable = false, le
         settling = next === ceiling ? undefined : win.setTimeout(settleRaster, next > ceiling ? 160 : 1500);
     };
     /** Put a view on the screen. */
-    const paint = (now) => {
+    const paint = (asked) => {
         const width = stage.clientWidth || 960;
         const height = stage.clientHeight || 600;
-        const layout = layoutOf(model, now, width, height, settings.lens, true, raster);
+        const now = aim === undefined ? asked : { ...asked, zoom: asked.zoom * aim.zoom };
+        const layout = layoutOf(model, now, width, height, settings.lens, true, raster, focusOf(aim));
         outside?.zoom(now.zoom);
         const culled = layout.culled;
         elements.forEach((one, i) => {
@@ -389,11 +405,16 @@ export function mountTurn(host, options, settings, build, replayable = false, le
     };
     /** Go to a view: by a glide of `ms` milliseconds, or at once. */
     const show = (to, ms) => {
+        // A camera that follows the play and is asked to let go glides back with the view (and goes on doing so when another glide takes over).
+        const aiming = aimTo !== undefined ? { from: aim, to: aimTo.to } : flight?.aim === undefined ? undefined : { from: aim, to: flight.aim.to };
+        aimTo = undefined;
         stop();
         view = to;
         label();
         if (ms <= 0 || calm() || win === null) {
             shown = to;
+            if (aiming !== undefined)
+                aim = aiming.to;
             paint(shown);
             return;
         }
@@ -404,13 +425,15 @@ export function mountTurn(host, options, settings, build, replayable = false, le
             const t = Math.min(1, (stamp - flight.start) / flight.ms);
             const eased = 1 - Math.pow(1 - t, 3);
             shown = t >= 1 ? flight.to : between(flight.from, flight.to, eased);
+            if (flight.aim !== undefined)
+                aim = t >= 1 ? flight.aim.to : aimBetween(flight.aim.from, flight.aim.to, eased);
             paint(shown);
             if (t < 1)
                 flight.frame = win.requestAnimationFrame(run);
             else
                 flight = undefined;
         };
-        flight = { from, to, start: win.performance.now(), ms, frame: 0 };
+        flight = { from, to, start: win.performance.now(), ms, frame: 0, aim: aiming };
         flight.frame = win.requestAnimationFrame(run);
     };
     const say = (text, wait = 0) => {
@@ -543,6 +566,12 @@ export function mountTurn(host, options, settings, build, replayable = false, le
         if (target === null || target === undefined || !root.contains(target))
             return;
         const name = target.dataset.preset;
+        const act = target.dataset.act ?? "";
+        if (name !== undefined || act === "reset")
+            took("preset");
+        // (The replay's own buttons are in the view too: only the view's turn it.)
+        else if (act !== "" && act !== "play" && act !== "reverse")
+            took("turn");
         if (name !== undefined)
             return toPreset(name);
         const big = event.shiftKey === true;
@@ -569,6 +598,8 @@ export function mountTurn(host, options, settings, build, replayable = false, le
         const yaw = big ? STEP.yawBig : STEP.yaw;
         const pitch = big ? STEP.pitchBig : STEP.pitch;
         event.preventDefault();
+        if (event.key !== " ")
+            took(/^[0-4]$|^Home$/.test(event.key) ? "preset" : "turn");
         switch (event.key) {
             // A key takes the surface toward its side as a drag toward that side does: the side nearest the eye goes to the right on ArrowRight, and ArrowUp tips it as a drag up does.
             case "ArrowLeft": return go(nudge(view, "left", yaw), 120);
@@ -629,9 +660,13 @@ export function mountTurn(host, options, settings, build, replayable = false, le
         }
         else {
             view = drag(view, here.x - before.x, here.y - before.y, tilts(event.pointerType));
-            if (Math.abs(here.x - before.x) + Math.abs(here.y - before.y) > 0)
+            if (Math.abs(here.x - before.x) + Math.abs(here.y - before.y) > 0 && !moved) {
                 moved = true;
+                took("turn");
+            }
         }
+        if (pinch !== undefined)
+            took("turn");
         shown = view;
         paint(shown);
     };
@@ -655,7 +690,11 @@ export function mountTurn(host, options, settings, build, replayable = false, le
     stage.addEventListener("pointermove", onMove);
     stage.addEventListener("pointerup", onUp);
     stage.addEventListener("pointercancel", onUp);
-    stage.addEventListener("dblclick", toOpening);
+    const onDouble = () => {
+        took("preset");
+        toOpening();
+    };
+    stage.addEventListener("dblclick", onDouble);
     // ---- The wheel over the view zooms it, as a map does; with the pointer anywhere else the page scrolls. Ctrl or Command and the wheel (a pinch on a trackpad) zoom too. Shift and the
     // wheel, or a sideways swipe, turn it. Tipping is a drag, the keys and the buttons. A wheel that starts while the zoom is already at its end that way goes on to scroll the page, so the page is
     // never trapped; one that reaches the end part-way through stops there rather than flinging the page. ----
@@ -667,6 +706,7 @@ export function mountTurn(host, options, settings, build, replayable = false, le
         if (!pinch && (event.shiftKey || Math.abs(event.deltaX) > Math.abs(event.deltaY))) {
             event.preventDefault();
             wheelTaken = now;
+            took("turn");
             grab();
             view = clampView({ ...view, yaw: view.yaw + (event.deltaX || event.deltaY) * 0.25 });
         }
@@ -680,6 +720,7 @@ export function mountTurn(host, options, settings, build, replayable = false, le
             wheelTaken = now;
             if (next.zoom === view.zoom)
                 return;
+            took("turn");
             grab();
             view = next;
         }
@@ -721,6 +762,21 @@ export function mountTurn(host, options, settings, build, replayable = false, le
             if (alive)
                 paint(shown);
         },
+        aim(next, glide = false) {
+            if (!alive)
+                return;
+            if (glide) {
+                aimTo = { to: next };
+                // (A glide of the view that is about to start carries it; otherwise it glides alone.)
+                show(view, 560);
+                return;
+            }
+            aim = next;
+        },
+        onUser(listener) {
+            users.add(listener);
+            return () => void users.delete(listener);
+        },
         requestFrame,
         cancelFrame,
     });
@@ -864,6 +920,7 @@ export function mountTurn(host, options, settings, build, replayable = false, le
             probe?.stop();
             frames.clear();
             seen?.disconnect();
+            users.clear();
             doc.removeEventListener("visibilitychange", onVisible);
             clearTimeout(spoken);
             observer?.disconnect();

package/dist/turn.follow.d.ts

@@ -0,0 +1,22 @@
+import type { ReplayController } from "./replay.control.ts";
+import { type FollowShot } from "./replay.follow.ts";
+import type { ReplayChange, ReplayLook, ReplayTimeline } from "./replay.types.ts";
+import type { Aim } from "./turn.dom.ts";
+import type { TurnModel } from "./turn.model.ts";
+import type { TurnInternals } from "./turn.replay.dom.ts";
+import type { ScoreOptions, SurfaceOptions } from "./types.ts";
+/**
+ * What a 3D view looks at for a shot: the shot's middle as a point of the floor in the scene's pixels from its middle, and the zoom on top of the view's. The scene at a zoom of 1 holds more
+ * than the surface (the boards, the stands): the zoom is worked out against how much more, so that the closest shot frames the same share of the surface as a flat drawing's.
+ */
+export declare function aimOf(shot: FollowShot, model: Pick<TurnModel, "scale" | "centre" | "box">, surface: {
+    w: number;
+    h: number;
+}): Aim;
+/** What `turnFollow` gives back: the paint the replay calls on each change of its clock, and `destroy`. */
+export interface TurnFollow {
+    paint(change: ReplayChange): void;
+    destroy(): void;
+}
+/** The camera of a replay on a 3D view. `floor` is the options the floor is drawn with (the replay's), or `undefined` before it is laid. */
+export declare function turnFollow(view: TurnInternals, controller: () => ReplayController, timeline: ReplayTimeline, look: ReplayLook, floor: () => SurfaceOptions | ScoreOptions | undefined): TurnFollow;