@johnmorrisdotca/kyogijo-stadiums 0.59.0 → 0.60.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.60.1] - 2026-11-03
+
+### Fixed
+
+- **The home-screen icon loads under a strict content policy (MODULES-256)**: the demo pages' `apple-touch-icon` link is now relative to the page, so a page that allows images from its own site only (`img-src 'self'`) loads it, and a copy of the site served under another address finds it. The sharing pictures (`og:image`, `twitter:image`) stay absolute. The family's thumbnail file is version 2026-11-03.2.
+
+## [0.60.0] - 2026-11-03
+
+### Added
+
+- **The camera follows the play (KYOGIJO-STADIUMS-46)** ([following the play](./docs/replay.md#following-the-play)): a replay can be watched with a camera that closes in where the action is and pulls back as the players spread, or moves with the puck. Off by default; the replay's bar has **Action** and **Puck** (**Ball** for a ball game) toggles, the setting `follow` (`"action"`, `"puck"`, `"off"`), the controller's `setFollow` and `holdFollow`, and the element's `follow` attribute. Action frames the puck and the five players nearest it, padded, never closer than 2.5 times the surface; Puck centres the puck at twice; from a whistle or a goal to the next `faceoff` event with a place, it goes to that faceoff dot. It eases with a critically damped spring, holds still for small moves (a dead zone), never leaves the surface, always holds the puck, and at rest writes nothing. Flat, it writes the drawing's `viewBox`; in 3D it looks at a point of the floor with a zoom over the view's, so the auto-turn and every viewpoint go on while it follows; the reader's drag, zoom, arrows or a viewpoint hold it until **Resume**. Reduced motion steps. It moves inside the replay's own animation frame, asks for none of its own, and runs nothing while paused, hidden or out of sight. The pure parts are in `/replay`: `followShot`, `followCamera`, `followStop`, `followWindow`, `clampShot`, `frameOf`, `springStep`, `zoomFor`, `FOLLOW_LIMITS`. The demo keeps the choice in its address (`follow=action`, `follow=puck`) for the hero's game, the Try it surface, the game section and the arenas page. `docs/replay.ja.md` is new: the camera in Japanese.
+
 ## [0.59.0] - 2026-11-03
 
 ### Fixed

package/README.md

@@ -180,6 +180,8 @@ Real buildings drawn in the outline OpenStreetMap maps for them, each with a pla
 </tr>
 </table>
 
+A camera can follow the play, flat or in 3D: it closes in where the action is and pulls back as the players spread, or moves with the puck, while the view goes on turning ([following the play](./docs/replay.md#following-the-play)).
+
 The scoreboard hung over an arena's ice follows the replay: its score, period and game clock come from the same timeline and clock as the controls ([the scoreboard over the arena](./docs/replay.md#the-scoreboard-over-the-arena-follows-the-game)).
 
 **Surfaces** ([the surfaces](./docs/surfaces.md), [score and layout](./docs/score.md))

package/catalogue.json

@@ -3,7 +3,7 @@
  "generatedAt": "2026-11-03",
  "package": {
   "name": "@johnmorrisdotca/kyogijo-stadiums",
-  "version": "0.59.0"
+  "version": "0.60.1"
  },
  "address": "https://johnmorrisdotca.github.io/kyogijo-stadiums/catalogue.json",
  "site": "https://johnmorrisdotca.github.io/kyogijo-stadiums/",

package/dist/catalogue.data.js

@@ -3,7 +3,7 @@ export const CATALOGUE_DATA = {
     "generatedAt": "2026-11-03",
     "package": {
         "name": "@johnmorrisdotca/kyogijo-stadiums",
-        "version": "0.59.0"
+        "version": "0.60.1"
     },
     "address": "https://johnmorrisdotca.github.io/kyogijo-stadiums/catalogue.json",
     "site": "https://johnmorrisdotca.github.io/kyogijo-stadiums/",

package/dist/element.d.ts

@@ -7,12 +7,12 @@ import type { ScoreOptions, SurfaceOptions } from "./types.ts";
 /** The tag of the element. */
 export declare const KYOGIJO_TAG = "kyogijo-field";
 /** The attributes the element reads. */
-export declare const KYOGIJO_ATTRIBUTES: readonly ["sport", "league", "size", "theme", "language", "orientation", "park", "ground", "arena", "year", "detail", "margin", "stripes", "exact-lines", "uppercase", "pitch", "pitch-type", "half", "range", "range-end", "goals", "stripe-pattern", "corner-flags", "look", "line-width", "line-dash", "line-opacity", "landmarks", "walls", "quirks", "home", "away", "home-abbr", "away-abbr", "home-score", "away-score", "home-penalties", "away-penalties", "score", "home-logo", "away-logo", "home-flag", "away-flag", "home-color", "away-color", "status", "competition", "date", "label", "winner", "home-side", "pageant", "description", "options", "loop", "speed", "autoplay", "controls", "trail", "turn", "turn-view", "turn-controls", "turn-uprights", "turn-score", "turn-touch", "turn-venue", "turn-roof", "turn-autoplay", "turn-speed", "turn-direction"];
+export declare const KYOGIJO_ATTRIBUTES: readonly ["sport", "league", "size", "theme", "language", "orientation", "park", "ground", "arena", "year", "detail", "margin", "stripes", "exact-lines", "uppercase", "pitch", "pitch-type", "half", "range", "range-end", "goals", "stripe-pattern", "corner-flags", "look", "line-width", "line-dash", "line-opacity", "landmarks", "walls", "quirks", "home", "away", "home-abbr", "away-abbr", "home-score", "away-score", "home-penalties", "away-penalties", "score", "home-logo", "away-logo", "home-flag", "away-flag", "home-color", "away-color", "status", "competition", "date", "label", "winner", "home-side", "pageant", "description", "options", "loop", "speed", "autoplay", "controls", "trail", "follow", "turn", "turn-view", "turn-controls", "turn-uprights", "turn-score", "turn-touch", "turn-venue", "turn-roof", "turn-autoplay", "turn-speed", "turn-direction"];
 /** The settings of a 3D view an element's attributes make: `turn-view` names the viewpoint it opens on, `turn-controls="false"` and `turn-uprights="false"` leave the buttons and what stands on the surface out, `turn-score="floor"` leaves the score panel on the floor, `turn-touch="turn"` keeps every touch for the view, `turn-venue="false"` leaves out the stands and the room (they are raised for a drawing with a crowd and for a dojo), `turn-roof` puts a roof or canopy over the stands, `turn-autoplay` starts the auto-turn (`force` even for a reader who prefers reduced motion) and `turn-speed` is its degrees a second. */
 export declare function turnSettingsFromAttributes(read: (name: string) => string | null, base?: TurnSettings): TurnSettings;
 /** Whether an element's `turn` attribute asks for the 3D view: present, and not `false`. */
 export declare const turnWanted: (read: (name: string) => string | null) => boolean;
-/** The settings of a replay an element's attributes make: `loop`, `autoplay` and `controls="false"` are switches, `speed` and `trail` numbers. */
+/** The settings of a replay an element's attributes make: `loop`, `autoplay` and `controls="false"` are switches, `speed` and `trail` numbers, `follow` what the camera follows (`action`, `puck` or `off`). */
 export declare function replaySettingsFromAttributes(read: (name: string) => string | null, base?: ReplaySettings): ReplaySettings;
 /** The options an element's attributes (and its `options` attribute and property) make. */
 export declare function optionsFromAttributes(read: (name: string) => string | null, base?: Partial<ScoreOptions>): SurfaceOptions | ScoreOptions;
@@ -25,7 +25,7 @@ export declare function optionsFromAttributes(read: (name: string) => string | n
 declare const Base: typeof HTMLElement;
 export declare class KyogijoField extends Base {
     #private;
-    static observedAttributes: readonly ["sport", "league", "size", "theme", "language", "orientation", "park", "ground", "arena", "year", "detail", "margin", "stripes", "exact-lines", "uppercase", "pitch", "pitch-type", "half", "range", "range-end", "goals", "stripe-pattern", "corner-flags", "look", "line-width", "line-dash", "line-opacity", "landmarks", "walls", "quirks", "home", "away", "home-abbr", "away-abbr", "home-score", "away-score", "home-penalties", "away-penalties", "score", "home-logo", "away-logo", "home-flag", "away-flag", "home-color", "away-color", "status", "competition", "date", "label", "winner", "home-side", "pageant", "description", "options", "loop", "speed", "autoplay", "controls", "trail", "turn", "turn-view", "turn-controls", "turn-uprights", "turn-score", "turn-touch", "turn-venue", "turn-roof", "turn-autoplay", "turn-speed", "turn-direction"];
+    static observedAttributes: readonly ["sport", "league", "size", "theme", "language", "orientation", "park", "ground", "arena", "year", "detail", "margin", "stripes", "exact-lines", "uppercase", "pitch", "pitch-type", "half", "range", "range-end", "goals", "stripe-pattern", "corner-flags", "look", "line-width", "line-dash", "line-opacity", "landmarks", "walls", "quirks", "home", "away", "home-abbr", "away-abbr", "home-score", "away-score", "home-penalties", "away-penalties", "score", "home-logo", "away-logo", "home-flag", "away-flag", "home-color", "away-color", "status", "competition", "date", "label", "winner", "home-side", "pageant", "description", "options", "loop", "speed", "autoplay", "controls", "trail", "follow", "turn", "turn-view", "turn-controls", "turn-uprights", "turn-score", "turn-touch", "turn-venue", "turn-roof", "turn-autoplay", "turn-speed", "turn-direction"];
     /** The options given as a property: an object, laid under the attributes. */
     get options(): Partial<ScoreOptions> | undefined;
     set options(value: Partial<ScoreOptions> | undefined);

package/dist/element.js

@@ -26,11 +26,11 @@ export const KYOGIJO_ATTRIBUTES = [
     "pitch", "pitch-type", "half", "range", "range-end", "goals", "stripe-pattern", "corner-flags", "look", "line-width", "line-dash", "line-opacity", "landmarks", "walls", "quirks",
     "home", "away", "home-abbr", "away-abbr", "home-score", "away-score", "home-penalties", "away-penalties", "score", "home-logo", "away-logo", "home-flag", "away-flag", "home-color", "away-color",
     "status", "competition", "date", "label", "winner", "home-side", "pageant", "description", "options",
-    "loop", "speed", "autoplay", "controls", "trail",
+    "loop", "speed", "autoplay", "controls", "trail", "follow",
     "turn", "turn-view", "turn-controls", "turn-uprights", "turn-score", "turn-touch", "turn-venue", "turn-roof", "turn-autoplay", "turn-speed", "turn-direction",
 ];
 /** The attributes that are about a replay and not about the drawing. */
-const REPLAY_ATTRIBUTES = ["loop", "speed", "autoplay", "controls", "trail"];
+const REPLAY_ATTRIBUTES = ["loop", "speed", "autoplay", "controls", "trail", "follow"];
 /** The settings of a 3D view an element's attributes make: `turn-view` names the viewpoint it opens on, `turn-controls="false"` and `turn-uprights="false"` leave the buttons and what stands on the surface out, `turn-score="floor"` leaves the score panel on the floor, `turn-touch="turn"` keeps every touch for the view, `turn-venue="false"` leaves out the stands and the room (they are raised for a drawing with a crowd and for a dojo), `turn-roof` puts a roof or canopy over the stands, `turn-autoplay` starts the auto-turn (`force` even for a reader who prefers reduced motion) and `turn-speed` is its degrees a second. */
 export function turnSettingsFromAttributes(read, base = {}) {
     const out = { ...base };
@@ -66,7 +66,7 @@ export function turnSettingsFromAttributes(read, base = {}) {
 }
 /** Whether an element's `turn` attribute asks for the 3D view: present, and not `false`. */
 export const turnWanted = (read) => read("turn") !== null && read("turn") !== "false";
-/** The settings of a replay an element's attributes make: `loop`, `autoplay` and `controls="false"` are switches, `speed` and `trail` numbers. */
+/** The settings of a replay an element's attributes make: `loop`, `autoplay` and `controls="false"` are switches, `speed` and `trail` numbers, `follow` what the camera follows (`action`, `puck` or `off`). */
 export function replaySettingsFromAttributes(read, base = {}) {
     const out = { ...base };
     const on = (name) => (read(name) === null ? undefined : read(name) !== "false");
@@ -89,6 +89,9 @@ export function replaySettingsFromAttributes(read, base = {}) {
     const trail = number("trail");
     if (trail !== undefined)
         out.trail = trail;
+    const follow = read("follow");
+    if (follow !== null)
+        out.follow = follow === "action" || follow === "puck" ? follow : "off";
     return out;
 }
 /** `3-2`, `3–2` or `3:2` as home and away. */
@@ -350,7 +353,9 @@ export class KyogijoField extends Base {
                 __classPrivateFieldGet(this, _KyogijoField_turn, "f").preset(view);
             return;
         }
-        if (REPLAY_ATTRIBUTES.includes(name) && __classPrivateFieldGet(this, _KyogijoField_replay, "f") !== undefined)
+        if (name === "follow" && __classPrivateFieldGet(this, _KyogijoField_replay, "f") !== undefined)
+            __classPrivateFieldGet(this, _KyogijoField_replay, "f").setFollow(replaySettingsFromAttributes((key) => this.getAttribute(key)).follow ?? "off");
+        else if (REPLAY_ATTRIBUTES.includes(name) && __classPrivateFieldGet(this, _KyogijoField_replay, "f") !== undefined)
             __classPrivateFieldGet(this, _KyogijoField_instances, "m", _KyogijoField_attach).call(this, name !== "speed" && name !== "loop");
         else
             __classPrivateFieldGet(this, _KyogijoField_instances, "m", _KyogijoField_draw).call(this);
@@ -371,7 +376,7 @@ _KyogijoField_mount = new WeakMap(), _KyogijoField_host = new WeakMap(), _Kyogij
     const from = __classPrivateFieldGet(this, _KyogijoField_replay, "f") === undefined || __classPrivateFieldGet(this, _KyogijoField_replayOf, "f") !== __classPrivateFieldGet(this, _KyogijoField_timeline, "f") ? undefined : __classPrivateFieldGet(this, _KyogijoField_replay, "f").state();
     __classPrivateFieldGet(this, _KyogijoField_replay, "f")?.destroy();
     __classPrivateFieldSet(this, _KyogijoField_replayOf, __classPrivateFieldGet(this, _KyogijoField_timeline, "f"), "f");
-    __classPrivateFieldSet(this, _KyogijoField_replay, on.replay(__classPrivateFieldGet(this, _KyogijoField_timeline, "f"), from === undefined ? settings : { ...settings, start: from.t - from.start }), "f");
+    __classPrivateFieldSet(this, _KyogijoField_replay, on.replay(__classPrivateFieldGet(this, _KyogijoField_timeline, "f"), from === undefined ? settings : { ...settings, start: from.t - from.start, follow: from.follow }), "f");
 }, _KyogijoField_draw = function _KyogijoField_draw() {
     if (__classPrivateFieldGet(this, _KyogijoField_host, "f") === undefined || !this.isConnected)
         return;

package/dist/replay-entry.d.ts

@@ -8,5 +8,7 @@ export { alongPool, distanceAt, progressOf, raceTimeline } from "./pool.replay.t
 export type { Progress, RaceReplayOptions } from "./pool.replay.ts";
 export { formatTime, parseTime } from "./pool.race.ts";
 export { REPLAY_SPEEDS, REPLAY_SPEED_RANGE, createReplay } from "./replay.control.ts";
+export { FOLLOW_LIMITS, FOLLOW_MODES, clampShot, followCamera, followMode, followShot, followStop, followWindow, frameOf, springStep, zoomFor } from "./replay.follow.ts";
+export type { FollowBox, FollowCamera, FollowInput, FollowLimits, FollowMode, FollowShot } from "./replay.follow.ts";
 export type { ReplayController } from "./replay.control.ts";
 export type { ActiveEvent, Possession, ReplayChange, ReplayEvent, ReplayEventKind, ReplayFrame, ReplayLook, ReplayObject, ReplayPeriod, ReplayReason, ReplaySettings, ReplayState, ReplayTeam, ReplayTimeline, ReplayTrail, } from "./replay.types.ts";

package/dist/replay-entry.js

@@ -8,3 +8,4 @@ export { boardClock, replayBoard, replayPeriods } from "./replay.board.js";
 export { alongPool, distanceAt, progressOf, raceTimeline } from "./pool.replay.js";
 export { formatTime, parseTime } from "./pool.race.js";
 export { REPLAY_SPEEDS, REPLAY_SPEED_RANGE, createReplay } from "./replay.control.js";
+export { FOLLOW_LIMITS, FOLLOW_MODES, clampShot, followCamera, followMode, followShot, followStop, followWindow, frameOf, springStep, zoomFor } from "./replay.follow.js";

package/dist/replay.control.d.ts

@@ -22,6 +22,10 @@ export interface ReplayController {
     setLoop(loop: boolean): void;
     /** `step` for a reader who prefers reduced motion: playing stops, and play steps. */
     setMotion(motion: "smooth" | "step"): void;
+    /** What the camera follows (`off`, `action`, `puck`); a change lets go of a hold. */
+    setFollow(mode: "off" | "action" | "puck"): void;
+    /** Hold the camera where it is (the reader turned or zoomed the view), or let it follow again (`false`). */
+    holdFollow(held: boolean): void;
     /** Tell the clock that seconds went by: while playing, the time moves by that many seconds times the speed. */
     advance(seconds: number): void;
     /** Be told of every change. Returns a function that stops it. */

package/dist/replay.control.js

@@ -39,6 +39,8 @@ export function createReplay(timeline, settings = {}) {
         speed: isNum(settings.speed) ? clamp(settings.speed, REPLAY_SPEED_RANGE[0], REPLAY_SPEED_RANGE[1]) : 1,
         loop: settings.loop === true,
         motion: settings.motion === "step" ? "step" : "smooth",
+        follow: settings.follow === "action" || settings.follow === "puck" ? settings.follow : "off",
+        followHeld: false,
     };
     const listeners = new Set();
     const tell = (reason, crossed = []) => {
@@ -148,6 +150,20 @@ export function createReplay(timeline, settings = {}) {
             state.playing = false;
             tell("motion");
         },
+        setFollow(mode) {
+            const next = mode === "action" || mode === "puck" ? mode : "off";
+            if (next === state.follow && !state.followHeld)
+                return;
+            state.follow = next;
+            state.followHeld = false;
+            tell("follow");
+        },
+        holdFollow(held) {
+            if (state.followHeld === held || (held && state.follow === "off"))
+                return;
+            state.followHeld = held;
+            tell("follow");
+        },
         advance(seconds) {
             if (!state.playing || state.motion === "step" || !isNum(seconds) || seconds <= 0)
                 return;

package/dist/replay.dom.js

@@ -4,6 +4,7 @@
 import { num } from "./format.js";
 import { renderLayers } from "./layers.js";
 import { REPLAY_SPEEDS, createReplay } from "./replay.control.js";
+import { FOLLOW_STYLE, flatFollow, followControls } from "./replay.follow.dom.js";
 import { describeEvent, drawFrame, replayClock, replayGroups, replaySpoken, replayInfo, replayPlacer, replaySnapshot } from "./replay.js";
 import { KYOGIJO_STRINGS, fill } from "./strings.core.js";
 const SVG_NS = "http://www.w3.org/2000/svg";
@@ -175,7 +176,7 @@ export function replayDriver(doc, timeline, settings, source) {
     let language = source.language;
     const words = () => KYOGIJO_STRINGS[language].replay;
     const style = doc.createElement("style");
-    style.textContent = REPLAY_STYLE;
+    style.textContent = REPLAY_STYLE + FOLLOW_STYLE;
     const hint = doc.createElement("p");
     hint.className = "ky-hint";
     hint.id = `${id}-keys`;
@@ -236,7 +237,8 @@ export function replayDriver(doc, timeline, settings, source) {
         play.hidden = stepMode;
         speed.hidden = stepMode;
         loop.hidden = stepMode;
-        bar.append(back, play, forward, speed, loop, range, clock);
+        const follow = followControls(doc, w, controller, timeline);
+        bar.append(back, play, forward, speed, loop, range, clock, ...follow.parts);
         hint.textContent = source.help === "turn" ? (stepMode ? w.keysTurnStep : w.keysTurn) : stepMode ? w.keysStep : w.keys;
         if (source.labelled !== undefined) {
             source.labelled.setAttribute("aria-label", w.region);
@@ -267,6 +269,7 @@ export function replayDriver(doc, timeline, settings, source) {
             loop.setAttribute("aria-pressed", String(s.loop));
             source.holder.dataset.state = s.ended ? "ended" : s.playing ? "playing" : "paused";
             source.holder.dataset.motion = s.motion;
+            follow.sync(s);
         };
         sync(undefined);
     };
@@ -432,13 +435,27 @@ export function createReplayView(host, timeline, settings, initial) {
     function drawStage(t) {
         stage.innerHTML = drawFrame(options, timeline, t, settings);
         svg = stage.querySelector("svg.kyogijo");
+        // (A drawing written again is shown at the camera's shot.)
+        camera.again();
     }
-    const driver = replayDriver(doc, timeline, settings, { paint: (t) => painter.paint(t), language, keysOn: root, holder: root, labelled: stage });
+    const camera = flatFollow({ svg: () => svg, options: () => options, timeline, look: settings, now: () => performance.now() });
+    const driver = replayDriver(doc, timeline, settings, {
+        paint: (t, change) => {
+            painter.paint(t);
+            if (change !== undefined)
+                camera.paint(change);
+        },
+        language,
+        keysOn: root,
+        holder: root,
+        labelled: stage,
+    });
     const { style, hint, bar, live } = driver.parts;
     root.append(style, stage, hint, bar, live);
     host.replaceChildren(root);
     drawStage(driver.controller.state().t);
     painter.bind(driver.controller.state().t);
+    camera.paint({ state: driver.controller.state(), reason: "follow", crossed: [] });
     if (settings.autoplay === true && driver.controller.state().motion === "smooth" && doc.visibilityState !== "hidden")
         driver.controller.play();
     return {

package/dist/replay.follow.d.ts

@@ -0,0 +1,164 @@
+import type { ReplayChange, ReplayObject, ReplayTimeline } from "./replay.types.ts";
+/** What the camera follows: nothing (the whole surface), the action (the players near the puck or ball, and it), or the puck or ball alone. */
+export type FollowMode = "off" | "action" | "puck";
+/** The modes, in the order the controls list them after "off". */
+export declare const FOLLOW_MODES: readonly FollowMode[];
+/** A mode from anything: `action` and `puck` are themselves, everything else is `off`. */
+export declare const followMode: (value: unknown) => FollowMode;
+/** A rectangle in the drawing's own feet. */
+export interface FollowBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Where the camera looks: the middle of the frame, in the drawing's feet, and how much it magnifies the surface (1 is the whole of it: the frame is the surface's size over `zoom`). */
+export interface FollowShot {
+    x: number;
+    y: number;
+    zoom: number;
+}
+/** How the camera frames and moves. Shares are of the surface's length (its longer side). */
+export interface FollowLimits {
+    /** The closest the camera comes: the frame is never smaller than the surface over this. */
+    maxZoom: number;
+    /** The zoom of `puck`. */
+    puckZoom: number;
+    /** How many of the players nearest the puck the action is framed round. */
+    near: number;
+    /** The room left round the action, a share of the surface's length on each side. */
+    pad: number;
+    /** A move of the shot smaller than this share of the frame does not move the camera, and a zoom that changes by less than this share does not zoom it. */
+    dead: number;
+    /** How quickly the spring follows, in radians a second: about 4.7 over this many seconds settles it. */
+    omega: number;
+    /** The room kept between the puck and the edge of the frame, a share of the frame. */
+    leash: number;
+}
+/** 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 declare const FOLLOW_LIMITS: Readonly<FollowLimits>;
+/** What the shot is worked out from at a moment: the objects in the drawing's feet, the surface, and the faceoff dot when the play is stopped. */
+export interface FollowInput {
+    objects: readonly Pick<ReplayObject, "team" | "x" | "y">[];
+    box: FollowBox;
+    /** The faceoff dot while the play is stopped (see `followStop`): the camera goes there. */
+    stop?: readonly [number, number];
+}
+/** The whole surface: the shot of `off`. */
+export declare const wholeShot: (box: FollowBox) => FollowShot;
+/** 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 declare function clampShot(shot: FollowShot, box: FollowBox, maxZoom?: number): FollowShot;
+/** The frame a shot shows: the surface's size over the zoom, round the middle. */
+export declare const frameOf: (shot: FollowShot, box: FollowBox) => FollowBox;
+/**
+ * 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 declare function followShot(mode: FollowMode, input: FollowInput, limits?: Partial<FollowLimits>): FollowShot;
+/**
+ * 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 declare function springStep(at: number, speed: number, goal: number, dt: number, omega: number): [number, number];
+/** What `followCamera` gives back. */
+export interface FollowCamera {
+    /** Move toward the shot the play asks for: by `dt` seconds of the spring, or at once (`dt` undefined). Gives where it is now. */
+    update(mode: FollowMode, input: FollowInput, dt?: number): FollowShot;
+    /** Where it is now. */
+    shot(): FollowShot | undefined;
+    /** Whether it is at rest on the whole surface: `off`, and nothing left to ease back. */
+    resting(): boolean;
+    /** Forget where it was: the next update starts from the whole surface. */
+    reset(): void;
+}
+/**
+ * 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 declare function followCamera(limits?: Partial<FollowLimits>): FollowCamera;
+/**
+ * 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 declare function zoomFor(zoom: number, room: number, maxZoom?: number): number;
+/**
+ * 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 declare function followWindow(shot: FollowShot, box: FollowBox, view: FollowBox, map?: (p: [number, number]) => [number, number], maxZoom?: number): FollowBox;
+/**
+ * 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 declare function followStop(timeline: ReplayTimeline, t: number): [number, number] | undefined;
+/** What a runner is given: the timeline, where its objects are in the drawing at a time, the surface, a clock in milliseconds, and how to show a shot (`undefined` gives back the whole drawing). */
+export interface FollowSource {
+    timeline: ReplayTimeline;
+    /** The objects at a time and the faceoff dot of a stoppage, in the drawing's feet. */
+    at(t: number, stop: readonly [number, number] | undefined): FollowInput;
+    now(): number;
+    show(shot: FollowShot | undefined): void;
+    limits?: Partial<FollowLimits>;
+}
+/** What `followRunner` gives back. */
+export interface FollowRunner {
+    /** The replay's clock changed: move the camera for it. */
+    paint(change: ReplayChange): void;
+    /** Show the shot again (the drawing was written again). */
+    again(): void;
+    /** Forget the shot: the camera starts from the whole surface. */
+    reset(): void;
+}
+/**
+ * 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 declare function followRunner(source: FollowSource): FollowRunner;

package/dist/replay.follow.dom.d.ts

@@ -0,0 +1,30 @@
+import type { ReplayController } from "./replay.control.ts";
+import { type FollowRunner } from "./replay.follow.ts";
+import type { ReplayLook, ReplayState, ReplayTimeline } from "./replay.types.ts";
+import type { KyogijoWords } from "./strings.core.ts";
+import type { ScoreOptions, SurfaceOptions } from "./types.ts";
+/** The buttons' own rules, added to the replay's stylesheet: a word beside each icon. */
+export declare const FOLLOW_STYLE: string;
+/** The buttons of the follow camera, for the replay's bar, and how to make them say the state. */
+export interface FollowControls {
+    parts: HTMLElement[];
+    sync(state: Readonly<ReplayState>): void;
+}
+/**
+ * The buttons: Action and Puck (Ball for a game with a ball) press in and out, one at a time, and pressing the one that is in turns the camera off (held or not); Resume shows only while the
+ * reader's own turn or zoom holds the camera.
+ */
+export declare function followControls(doc: Document, words: KyogijoWords["replay"], controller: ReplayController, timeline: ReplayTimeline): FollowControls;
+/** What the flat camera is given: the drawing now, what it was drawn from, the timeline and how its frames are drawn. */
+export interface FlatFollowSource {
+    svg(): SVGSVGElement | null;
+    options(): SurfaceOptions | ScoreOptions;
+    timeline: ReplayTimeline;
+    look: ReplayLook;
+    now(): number;
+}
+/**
+ * The camera of a flat replay: it shows the part of the drawing the shot frames by writing the drawing's `viewBox`, one attribute, and puts the whole drawing back when it is off. A drawing
+ * written again (a theme, a score) is shown at the same shot by `again`.
+ */
+export declare function flatFollow(source: FlatFollowSource): FollowRunner;

package/dist/replay.follow.dom.js

@@ -0,0 +1,118 @@
+// Following the play in a page: the buttons in the replay's bar (Action, Puck or Ball, and Resume), and the camera of a flat replay, which shows part of the drawing by its `viewBox`. The
+// arithmetic is replay.follow.ts's; the 3D view's camera is turn.follow.ts's.
+import { outlineOf } from "./outline.js";
+import { FOLLOW_LIMITS, followRunner, followWindow } from "./replay.follow.js";
+import { replayPlacer, replaySnapshot } from "./replay.js";
+/** The buttons' own rules, added to the replay's stylesheet: a word beside each icon. */
+export const FOLLOW_STYLE = `
+.ky-replay .ky-follow{display:inline-flex;flex-wrap:wrap;gap:.5rem}
+.ky-replay .ky-follow button{gap:.35rem}
+.ky-replay .ky-follow svg{fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round}
+`.trim();
+const SHAPES = {
+    action: "M3 8V3h5M16 3h5v5M21 16v5h-5M8 21H3v-5M9 12h6M12 9v6",
+    puck: "M12 3v3M12 18v3M3 12h3M18 12h3M12 8a4 4 0 1 0 0.01 0",
+    resume: "M4 12a8 8 0 1 0 2.3-5.7M4 4v5h5",
+};
+/** What the timeline follows: a puck, a ball, or neither (then there is no Puck button). */
+const followed = (timeline) => {
+    for (const frame of timeline.frames)
+        for (const o of frame.objects)
+            if (o.team === "puck" || o.team === "ball")
+                return o.team;
+    return undefined;
+};
+/**
+ * The buttons: Action and Puck (Ball for a game with a ball) press in and out, one at a time, and pressing the one that is in turns the camera off (held or not); Resume shows only while the
+ * reader's own turn or zoom holds the camera.
+ */
+export function followControls(doc, words, controller, timeline) {
+    const group = doc.createElement("span");
+    group.className = "ky-follow";
+    group.setAttribute("role", "group");
+    group.setAttribute("aria-label", words.follow);
+    const button = (name, word, label, onClick) => {
+        const b = doc.createElement("button");
+        b.type = "button";
+        b.className = `ky-follow-${name}`;
+        b.setAttribute("aria-label", label);
+        b.title = label;
+        b.innerHTML = `<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="${SHAPES[name]}"/></svg><span>${word}</span>`;
+        b.addEventListener("click", onClick);
+        return b;
+    };
+    const press = (mode) => () => controller.setFollow(controller.state().follow === mode ? "off" : mode);
+    const ball = followed(timeline);
+    const action = button("action", words.followAction, words.followActionLabel, press("action"));
+    const puck = button("puck", ball === "ball" ? words.followBall : words.followPuck, ball === "ball" ? words.followBallLabel : words.followPuckLabel, press("puck"));
+    puck.hidden = ball === undefined;
+    const resume = button("resume", words.followResume, words.followResumeLabel, () => controller.holdFollow(false));
+    group.append(action, puck, resume);
+    return {
+        parts: [group],
+        sync(state) {
+            action.setAttribute("aria-pressed", String(state.follow === "action"));
+            puck.setAttribute("aria-pressed", String(state.follow === "puck"));
+            resume.hidden = !state.followHeld;
+            group.dataset.follow = state.followHeld ? "held" : state.follow;
+        },
+    };
+}
+/** The matrix that takes the replay's layers to the drawing's own units: a surface laid tall is turned a quarter inside its drawing. */
+function layersToDrawing(svg) {
+    const layers = svg.querySelector("g.ky-layers");
+    let m = { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
+    for (let el = layers?.parentElement ?? null; el !== null && el !== svg; el = el.parentElement) {
+        const t = el.transform?.baseVal?.consolidate?.()?.matrix;
+        if (t === undefined || t === null)
+            continue;
+        // The outer transform after the inner: t times m.
+        m = { a: t.a * m.a + t.c * m.b, b: t.b * m.a + t.d * m.b, c: t.a * m.c + t.c * m.d, d: t.b * m.c + t.d * m.d, e: t.a * m.e + t.c * m.f + t.e, f: t.b * m.e + t.d * m.f + t.f };
+    }
+    return ([x, y]) => [m.a * x + m.c * y + m.e, m.b * x + m.d * y + m.f];
+}
+/**
+ * The camera of a flat replay: it shows the part of the drawing the shot frames by writing the drawing's `viewBox`, one attribute, and puts the whole drawing back when it is off. A drawing
+ * written again (a theme, a score) is shown at the same shot by `again`.
+ */
+export function flatFollow(source) {
+    const whole = new WeakMap();
+    const own = (svg) => {
+        let known = whole.get(svg);
+        if (known === undefined) {
+            const text = svg.getAttribute("viewBox");
+            const [x, y, w, h] = (text ?? "").split(/[\s,]+/).map(Number);
+            known = { view: [x, y, w, h].every(Number.isFinite) ? { x, y, w, h } : { x: 0, y: 0, w: 0, h: 0 }, text, map: layersToDrawing(svg) };
+            whole.set(svg, known);
+        }
+        return known;
+    };
+    const box = () => outlineOf(source.options()).box;
+    return followRunner({
+        timeline: source.timeline,
+        now: source.now,
+        at(t, stop) {
+            const place = replayPlacer(source.options(), source.timeline);
+            const objects = replaySnapshot(source.timeline, t, source.look).objects;
+            const placed = place(objects.map((o) => [o.x, o.y]));
+            return { box: box(), objects: objects.map((o, i) => ({ team: o.team, x: placed[i][0], y: placed[i][1] })), stop: stop === undefined ? undefined : place([[stop[0], stop[1]]])[0] };
+        },
+        show(shot) {
+            const svg = source.svg();
+            if (svg === null)
+                return;
+            const known = own(svg);
+            if (shot === undefined || !(known.view.w > 0)) {
+                if (known.text === null)
+                    svg.removeAttribute("viewBox");
+                else
+                    svg.setAttribute("viewBox", known.text);
+                return;
+            }
+            const w = followWindow(shot, box(), known.view, known.map, FOLLOW_LIMITS.maxZoom);
+            const text = `${w.x} ${w.y} ${w.w} ${w.h}`;
+            if (svg.getAttribute("viewBox") !== text)
+                svg.setAttribute("viewBox", text);
+        },
+    });
+}