@johnmorrisdotca/kyogijo-stadiums 0.51.0 → 0.52.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.52.0] - 2026-11-03
+
+### Added
+
+- **A replay plays on the 3D view (KYOGIJO-STADIUMS-23)** ([the replay in 3D](./docs/replay.md#in-3d)): `view.replay(timeline, settings?)` on the handle of `mountKyogijoTurn` gives the same controller as `mount.replay`, and the rink can be turned, tipped and zoomed while the game plays. The players and officials stand up as discs that face the eye (the flat replay's circles, squares, triangles and numbers, turned up), and the ball or the puck, its trail, the passes, the shots and the goals stay on the floor. `stand: false` keeps the players flat. On the view, Space plays and pauses, comma and full stop step, and the arrow keys still turn it; on the replay's controls the arrows step. Nothing runs while it is paused, hidden or out of sight, the auto-turn and the replay share one animation frame, only what moves is written, and destroy leaves nothing; browser tests hold each of these. `replayTurnModel` is the pure model of a frame, and `<kyogijo-field turn>` with a `timeline` plays it on its 3D view.
+- **An example game (KYOGIJO-STADIUMS-25)** ([example games](./docs/example-games.md)): `examples/games/canada-japan.json`, a whole made-up game of Canada and Japan, three periods, shaped from a public NHL play-by-play with every team, player, place, time and the result changed. It is in the repository and on the demo's site, not in the npm package.
+- The demo: a section, "A game on the ice, in 3D", plays the example game in 3D or flat, with a button for each period, the score on the board as it goes, and the code with a Copy button; the arena at the top of the page has **Play a game**, which loads the game when it is first pressed and plays it on the arena's ice in front of its crowd.
+
+### Changed
+
+- The flat replay's page side is a painter and a driver that the 3D replay shares (`replay.dom.ts`); the flat replay behaves as before.
+
 ## [0.51.0] - 2026-11-03
 
 ### Added

package/README.md

@@ -36,7 +36,7 @@ Kyogijo Stadiums draws the places a game is played on, with the score of the gam
 
 ## The showcase
 
-Real buildings drawn in the outline OpenStreetMap maps for them, each with a plausible bowl of the seats, tiers and roof its sources give. In the first three rows the picture in the middle turns, slowly, and the others stand still; the last row is still.
+Real buildings drawn in the outline OpenStreetMap maps for them, each with a plausible bowl of the seats, tiers and roof its sources give. In the rows of arenas, of halls and of districts the picture in the middle turns, slowly, and the others stand still; the other rows are still.
 
 **Arenas and stadiums** ([real arenas](./docs/venues.md), [real stadiums](./docs/stadiums.md))
 
@@ -143,6 +143,34 @@ Real buildings drawn in the outline OpenStreetMap maps for them, each with a pla
 </tr>
 </table>
 
+**A game on the ice** ([the replay in 3D](./docs/replay.md#in-3d), [the example game](./docs/example-games.md))
+
+<table align="center">
+<tr>
+<td align="center" valign="top">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kyogijo-stadiums/main/docs/images/replay-game-3d-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kyogijo-stadiums/main/docs/images/replay-game-3d-desk-light.webp" alt="A made-up game of Canada and Japan replayed on the rink in 3D from the main camera: the players standing up as discs with their numbers, red circles and blue squares, the score hung over centre ice, and a shot's arrow and a whistle's cross on the ice." width="250">
+</picture>
+<br><em>A made-up game, replayed in 3D</em>
+</td>
+<td align="center" valign="top">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kyogijo-stadiums/main/docs/images/hero-game-3d-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kyogijo-stadiums/main/docs/images/hero-game-3d-desk-light.webp" alt="The same game on the ice of a real arena, in front of its crowd: the players standing as discs on the rink inside two tiers of seats." width="250">
+</picture>
+<br><em>The same game in an arena, in front of the crowd</em>
+</td>
+<td align="center" valign="top">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kyogijo-stadiums/main/docs/images/replay-game-flat-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kyogijo-stadiums/main/docs/images/replay-game-flat-desk-light.webp" alt="The same moment of the game flat: each side's flag and name at the end it defends, the score panel at centre ice, the players as circles and squares with their numbers, a goal's star at the net." width="250">
+</picture>
+<br><em>The same moment, flat</em>
+</td>
+</tr>
+</table>
+
 **Surfaces** ([the surfaces](./docs/surfaces.md), [score and layout](./docs/score.md))
 
 <table align="center">
@@ -217,7 +245,7 @@ console.log(svg.startsWith("<svg"), svg.includes("USA 3, Canada 2"));
 - **A 3D view** of any surface or venue that turns by mouse, touch or keys, with the roof and the walls to switch and a quality level for every device. [The 3D view](./docs/turn.md), [quality](./docs/quality.md).
 - **Circuits**: a famous race track as OpenStreetMap maps it, the Las Vegas Strip Circuit first, with its turns numbered and its pit building standing in 3D. [Circuits](./docs/circuits.md).
 - **Tournaments**: several surfaces on one floor, who judges where, boards laid over a surface. [Layouts](./docs/multi.md), [judging](./docs/judging.md), [boards](./docs/boards.md).
-- **Data on a surface**: points, heat maps, shot and pass charts, team shapes and a replay, in 48 providers' coordinate frames. [Layers](./docs/layers.md), [frames](./docs/frames.md), [replay](./docs/replay.md).
+- **Data on a surface**: points, heat maps, shot and pass charts, team shapes and a replay, flat or in 3D with the players standing on the ice, in 48 providers' coordinate frames. [Layers](./docs/layers.md), [frames](./docs/frames.md), [replay](./docs/replay.md), [an example game](./docs/example-games.md).
 - **Looks and flags**: eight named looks, a flag or crest on each half, trophies and crests from Dougu Sports, flags from Hata, light and dark. [Theming](./docs/theming.md), [the pageant](./docs/pageant.md).
 - **Four ways in**: a function that returns SVG text, a helper that draws into a container, a custom element, a frame for pages with no script; renderers for a canvas, d3, Observable Plot, GeoJSON and PNG. [Entry points](./docs/entry-points.md), [renderers](./docs/renderers.md).
 - **Accessible and small**: each drawing is an `img` with a title and a description, in English or Japanese; no dependencies, no network requests, nothing stored.

package/catalogue.json

@@ -3,7 +3,7 @@
  "generatedAt": "2026-11-03",
  "package": {
   "name": "@johnmorrisdotca/kyogijo-stadiums",
-  "version": "0.51.0"
+  "version": "0.52.0"
  },
  "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.51.0"
+        "version": "0.52.0"
     },
     "address": "https://johnmorrisdotca.github.io/kyogijo-stadiums/catalogue.json",
     "site": "https://johnmorrisdotca.github.io/kyogijo-stadiums/",

package/dist/element.d.ts

@@ -1,5 +1,6 @@
 import { type KyogijoReplay } from "./mount.ts";
 import { type KyogijoTurn } from "./turn.dom.ts";
+import "./turn.replay.dom.ts";
 import type { TurnSettings } from "./turn.model.ts";
 import type { ReplaySettings, ReplayTimeline } from "./replay.types.ts";
 import type { ScoreOptions, SurfaceOptions } from "./types.ts";

package/dist/element.js

@@ -9,13 +9,15 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
-var _KyogijoField_instances, _KyogijoField_mount, _KyogijoField_host, _KyogijoField_options, _KyogijoField_theme, _KyogijoField_timeline, _KyogijoField_replaySettings, _KyogijoField_replay, _KyogijoField_replayOf, _KyogijoField_turn, _KyogijoField_turnSettings, _KyogijoField_attach, _KyogijoField_draw;
+var _KyogijoField_instances, _KyogijoField_mount, _KyogijoField_host, _KyogijoField_options, _KyogijoField_theme, _KyogijoField_timeline, _KyogijoField_replaySettings, _KyogijoField_replay, _KyogijoField_replayOf, _KyogijoField_turn, _KyogijoField_turnSettings, _KyogijoField_attach, _KyogijoField_draw, _KyogijoField_follow;
 import { SPORTS } from "./draw.js";
 import { leagueIds } from "./leagues.js";
 import { parseRange } from "./ranges.names.js";
 import { mountKyogijo } from "./mount.js";
 import { TURN_PRESET_NAMES } from "./turn.camera.js";
 import { mountKyogijoTurn } from "./turn.dom.js";
+// A timeline on the element's 3D view plays with the replay's code for the view.
+import "./turn.replay.dom.js";
 /** The tag of the element. */
 export const KYOGIJO_TAG = "kyogijo-field";
 /** The attributes the element reads. */
@@ -355,7 +357,8 @@ export class KyogijoField extends Base {
     }
 }
 _KyogijoField_mount = new WeakMap(), _KyogijoField_host = new WeakMap(), _KyogijoField_options = new WeakMap(), _KyogijoField_theme = new WeakMap(), _KyogijoField_timeline = new WeakMap(), _KyogijoField_replaySettings = new WeakMap(), _KyogijoField_replay = new WeakMap(), _KyogijoField_replayOf = new WeakMap(), _KyogijoField_turn = new WeakMap(), _KyogijoField_turnSettings = new WeakMap(), _KyogijoField_instances = new WeakSet(), _KyogijoField_attach = function _KyogijoField_attach(again) {
-    if (__classPrivateFieldGet(this, _KyogijoField_mount, "f") === undefined || __classPrivateFieldGet(this, _KyogijoField_timeline, "f") === undefined)
+    const on = __classPrivateFieldGet(this, _KyogijoField_turn, "f") ?? __classPrivateFieldGet(this, _KyogijoField_mount, "f");
+    if (on === undefined || __classPrivateFieldGet(this, _KyogijoField_timeline, "f") === undefined)
         return;
     const settings = replaySettingsFromAttributes((name) => this.getAttribute(name), __classPrivateFieldGet(this, _KyogijoField_replaySettings, "f"));
     if (__classPrivateFieldGet(this, _KyogijoField_replay, "f") !== undefined && __classPrivateFieldGet(this, _KyogijoField_replayOf, "f") === __classPrivateFieldGet(this, _KyogijoField_timeline, "f") && !again) {
@@ -368,7 +371,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, __classPrivateFieldGet(this, _KyogijoField_mount, "f").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 }), "f");
 }, _KyogijoField_draw = function _KyogijoField_draw() {
     if (__classPrivateFieldGet(this, _KyogijoField_host, "f") === undefined || !this.isConnected)
         return;
@@ -377,7 +380,7 @@ _KyogijoField_mount = new WeakMap(), _KyogijoField_host = new WeakMap(), _Kyogij
     if (options.theme === undefined && (page === "light" || page === "dark"))
         options.theme = page;
     if (turnWanted((name) => this.getAttribute(name))) {
-        // The 3D view takes the container over from the flat drawing; a replay does not play on it.
+        // The 3D view takes the container over from the flat drawing; a replay plays on it, the players standing up.
         if (__classPrivateFieldGet(this, _KyogijoField_mount, "f") !== undefined) {
             __classPrivateFieldGet(this, _KyogijoField_mount, "f").destroy();
             __classPrivateFieldSet(this, _KyogijoField_mount, undefined, "f");
@@ -385,20 +388,28 @@ _KyogijoField_mount = new WeakMap(), _KyogijoField_host = new WeakMap(), _Kyogij
             __classPrivateFieldSet(this, _KyogijoField_replayOf, undefined, "f");
         }
         const settings = turnSettingsFromAttributes((name) => this.getAttribute(name), __classPrivateFieldGet(this, _KyogijoField_turnSettings, "f"));
-        if (__classPrivateFieldGet(this, _KyogijoField_turn, "f") === undefined)
+        if (__classPrivateFieldGet(this, _KyogijoField_turn, "f") === undefined) {
             __classPrivateFieldSet(this, _KyogijoField_turn, mountKyogijoTurn(__classPrivateFieldGet(this, _KyogijoField_host, "f"), options, settings), "f");
+            __classPrivateFieldSet(this, _KyogijoField_replay, undefined, "f");
+            __classPrivateFieldSet(this, _KyogijoField_replayOf, undefined, "f");
+        }
         else
             __classPrivateFieldGet(this, _KyogijoField_turn, "f").update(options);
+        __classPrivateFieldGet(this, _KyogijoField_instances, "m", _KyogijoField_follow).call(this);
         return;
     }
     if (__classPrivateFieldGet(this, _KyogijoField_turn, "f") !== undefined) {
         __classPrivateFieldGet(this, _KyogijoField_turn, "f").destroy();
         __classPrivateFieldSet(this, _KyogijoField_turn, undefined, "f");
+        __classPrivateFieldSet(this, _KyogijoField_replay, undefined, "f");
+        __classPrivateFieldSet(this, _KyogijoField_replayOf, undefined, "f");
     }
     if (__classPrivateFieldGet(this, _KyogijoField_mount, "f") === undefined)
         __classPrivateFieldSet(this, _KyogijoField_mount, mountKyogijo(__classPrivateFieldGet(this, _KyogijoField_host, "f"), options), "f");
     else
         __classPrivateFieldGet(this, _KyogijoField_mount, "f").update(options);
+    __classPrivateFieldGet(this, _KyogijoField_instances, "m", _KyogijoField_follow).call(this);
+}, _KyogijoField_follow = function _KyogijoField_follow() {
     if (__classPrivateFieldGet(this, _KyogijoField_timeline, "f") === undefined) {
         __classPrivateFieldGet(this, _KyogijoField_replay, "f")?.destroy();
         __classPrivateFieldSet(this, _KyogijoField_replay, undefined, "f");

package/dist/judging.mount.js

@@ -62,6 +62,7 @@ export function mountJudgingBroadcast(host, options, settings = {}) {
         direction: () => turn.direction(),
         setDirection: (direction) => turn.setDirection(direction),
         togglePlay: () => turn.togglePlay(),
+        replay: (timeline, replaySettings) => turn.replay(timeline, replaySettings),
         get quality() {
             return turn.quality;
         },

package/dist/replay.d.ts

@@ -17,6 +17,8 @@ export declare function replayInfo(timeline: ReplayTimeline): {
     events: number;
     step: number;
 };
+/** Everything a timeline tracks, each as it first appears (its id, team, number and label), in that order. */
+export declare function replayCast(timeline: ReplayTimeline): readonly ReplayObject[];
 /** The times of the frames, and of the events, in order: the moments a step can land on. */
 export declare function replayTimes(timeline: ReplayTimeline): readonly number[];
 /** The events of a timeline, in time order. */
@@ -151,6 +153,8 @@ export declare function replayPlacer(options: SurfaceOptions | ScoreOptions, tim
  * ```
  */
 export declare function drawFrame(options: SurfaceOptions | ScoreOptions, timeline: ReplayTimeline, t: number, look?: ReplayLook): string;
+/** `drawFrame` with only the groups `keep` says yes to: a 3D view keeps the players off its floor, where they stand up instead. */
+export declare function drawFrameOf(options: SurfaceOptions | ScoreOptions, timeline: ReplayTimeline, t: number, look?: ReplayLook, keep?: (group: ReplayGroup) => boolean): string;
 /** The prefix of the ids in a replay's drawing when the options give none: a hash of the options and of the timeline's size, not of the time. */
 export declare const replayId: (options: SurfaceOptions | ScoreOptions, timeline: ReplayTimeline) => string;
 /**

package/dist/replay.dom.d.ts

@@ -1,6 +1,7 @@
 import { type ReplayController } from "./replay.control.ts";
-import type { ReplaySettings, ReplayTimeline } from "./replay.types.ts";
-import type { ScoreOptions, SurfaceOptions } from "./types.ts";
+import { type ReplayGroup } from "./replay.ts";
+import type { ReplayLook, ReplaySettings, ReplayTimeline } from "./replay.types.ts";
+import type { Language, ScoreOptions, SurfaceOptions } from "./types.ts";
 /** The controls' stylesheet: written once beside the controls, scoped to them, in the page's own colours. */
 export declare const REPLAY_STYLE: string;
 /** A replay attached to a container: the controller, the stage the drawing goes in, and how to draw it again. */
@@ -13,6 +14,70 @@ export interface ReplayView {
     /** Stop the clock and the listeners, and empty the container. */
     destroy(): void;
 }
+/** What a painter is given: where the drawing is, what it was drawn from, and how to draw it whole again. */
+export interface PainterSource {
+    doc: Document;
+    timeline: ReplayTimeline;
+    look: ReplayLook;
+    /** The drawing the replay's groups are in (`svg.kyogijo`), or `null` before it is written. */
+    svg(): SVGSVGElement | null;
+    /** The options it was drawn with, its `id` among them. */
+    options(): SurfaceOptions | ScoreOptions;
+    language(): Language;
+    /** Which groups of the replay are in this drawing: all when missing (a 3D view stands the players up and leaves the rest on the floor). */
+    keep?: (group: ReplayGroup) => boolean;
+    /** Write the drawing whole again at a time; the painter binds itself to it afterwards. */
+    redraw(t: number): void;
+}
+/** The painter of a replay's drawing: `paint` moves the marks to a time; `bind` matches the elements of a drawing just written at `t`. */
+export interface ReplayPainter {
+    paint(t: number): void;
+    bind(t: number): void;
+}
+/**
+ * The painter of a replay: it moves the marks that move and nothing else. A mark that comes or goes (an object that enters, an event that begins) draws the replay's own group
+ * again, never the surface; a group whose marks cannot be matched to elements one for one is drawn again each time.
+ */
+export declare function replayPainter(source: PainterSource): ReplayPainter;
+/** What a driver is given: how to paint a time, where its keys are heard, and what it labels. */
+export interface DriverSource {
+    /** Move the drawing to a time. Called on every change of the clock. */
+    paint(t: number): void;
+    language: Language;
+    /** The element whose keys play, step and seek (its descendants too): the stage and the bar in a flat replay, the bar alone over a 3D view. */
+    keysOn: HTMLElement;
+    /** The element that says what the replay is doing (`data-state`, `data-motion`). */
+    holder: HTMLElement;
+    /** The element that names the replay and points at its key help (the flat drawing's stage), if any. */
+    labelled?: HTMLElement;
+    /** The element whose being in sight lets the clock run: no frame is asked for while it is scrolled out of sight. */
+    seen?: Element;
+    /** The key help: `keys` and `keysStep` by default, `keysTurn` and `keysTurnStep` over a 3D view. */
+    help?: "flat" | "turn";
+    /** Where frames are asked for: the page's `requestAnimationFrame` by default; a 3D view lends its own, so that a turning view and its replay share one frame. */
+    frames?: {
+        request(callback: FrameRequestCallback): number;
+        cancel(id: number): void;
+    };
+}
+/** The page's side of a replay without its drawing: the clock on animation frames, the controls, the keys, the live region, a hidden page and reduced motion. */
+export interface ReplayDriver {
+    controller: ReplayController;
+    /** The style, the key help, the bar and the live region, in that order, for the caller to put in the page. */
+    parts: {
+        style: HTMLStyleElement;
+        hint: HTMLElement;
+        bar: HTMLElement;
+        live: HTMLElement;
+    };
+    /** The words changed: the controls are made again. */
+    setLanguage(language: Language): void;
+    /** The play, pause or step the keys of a 3D view's stage ask for, by the names of the keys: the same moves as the bar's keys. */
+    key(event: KeyboardEvent, scope: "stage" | "bar"): boolean;
+    destroy(): void;
+}
+/** Make the clock, the controls and the keys of a replay. Nothing runs until the reader (or `autoplay`) plays it, and nothing runs while it is paused, hidden or out of sight. */
+export declare function replayDriver(doc: Document, timeline: ReplayTimeline, settings: ReplaySettings, source: DriverSource): ReplayDriver;
 /**
  * Attach a replay to a container: the stage with the drawing, the controls under it, the keyboard and the live region. The drawing is written once
  * and then only the marks that move are moved, on `requestAnimationFrame`; a mark that comes or goes (an object that enters, an event that