@johnmorrisdotca/kyogijo-stadiums 0.60.1 → 0.62.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.62.0] - 2026-11-03
+
+### Added
+
+- **Penalties, power plays and the penalty box (KYOGIJO-STADIUMS-48)** ([penalties](./docs/replay.md#penalties-and-the-power-play)): a penalty in a replay is a stoppage with the face-off in the offending side's end; the penalized player skates to his side's penalty box, across the ice from the benches, and sits there for the penalty's time on the game clock while his side plays a skater short (two for overlapping penalties, never below three skaters), then comes back into the play. A timeline has `penalties` now; the board over the arena shows each side's strength and each penalty's clock (the time left in the short side's block of colour, PP in the other's), and `replayBoard` gives `strength` and `penalties`. One rule set, in `/replay`: `hockeyPenaltyEnds` (a minor 2 minutes, a double minor 4, a major 5, a misconduct 10 with a substitute; a power-play goal ends a minor but not a major; coincidental penalties keep the strength even; a third penalty waits), `hockeyPenaltyKind` (the NHL play-by-play's kinds), `hockeyPenaltyBox` (a stand-in for the rink's own boxes), `penaltiesAt` and `replayGameTime`. The example game has its seven penalties (`examples/games/canada-japan.json`, 1.1 MB). Players on the bench are not drawn.
+
+### Fixed
+
+- **Stoppages play like hockey (KYOGIJO-STADIUMS-45)** ([stoppages](./docs/replay.md#stoppages-the-clock-stops-the-players-line-up)): after a goal the example game no longer moves the puck from the net to centre ice as if it were passed. A timeline has `stoppages` now: in each the game clock stands still (the board over the arena shows the same time from the goal to the drop) while the replay's own clock moves on, the puck is dead (it stays where play stopped, in the net after a goal, then is out of sight until the drop), and the players glide to the face-off's line-up at the spot the rules give, a line going off by its bench; the clock runs again at the drop. One rule set for hockey, in `/replay`: `hockeyFaceoffDot` (centre after a goal and at a period's start, the end-zone spot after a save or a frozen puck, the offending side's end after icing or a penalty, the neutral-zone spot after offside, the nearest spot in the zone otherwise), `hockeyFormation` (the line-up of Rule 76), `HOCKEY_DEAD_TIME` and `HOCKEY_RULES` (the speeds and seconds), `hockeyStopOf` (the NHL play-by-play's words), and, for any sport, `addDeadTime`, `replayGameClock`, `replayStoppages`, `stoppageAt` and `restartsBetween`. A `faceoff` event is said at each drop and draws no mark. A trail begins again after a frame its object is not in. `examples/games/canada-japan.json` is made again with the rules: 66 stoppages, about fifteen minutes, 1.1 MB (was 1.3 MB). The other sports' dead time is planned in the docs, not built.
+
+## [0.61.0] - 2026-11-03
+
+### Added
+
+- **Sound: the crowd of each kind of venue, at a level (KYOGIJO-STADIUMS-36)** ([sound](./docs/sound.md)): `@johnmorrisdotca/kyogijo-stadiums/sound` has `createKyogijoSound`, a surface's crowd made in the browser with Web Audio (the building's air, people talking, applause and the crowd's voice, and the pool's water), at five levels from quiet to a roar, heard in the room its venue makes (its roof and its seats: an arena rings, an open stadium does not), as large as the crowd in it and drier from above in 2D. An index of sound sets (`SOUND_BEDS`, `SOUND_SETS`, `SOUND_OF_SPORT`) gives every surface a bed for its kind of venue (arena, open stadium, ballpark, court hall, pool, dojo, ring, track) and the levels it offers (a kyudo hall only two); a surface with none has no sound. Off until turned on: nothing is fetched, made or decoded before, one audio context serves the page, and nothing plays or decodes while it is off, muted, hidden or out of sight. `soundRoom`, `soundMix` and `levelFor` are the rules, pure.
+- The demo: a Sound button, a volume slider and the crowd's levels as buttons, kept in the address (`sound=on`, `volume`, `level`), on the real arenas (venues.html), under the surface in Try it (the levels of each surface's venue, none with the crowd off) and over the arena at the top of the page. Its recordings (`demo/sounds/`) are CC0 or in the public domain, each listed with its source, author and licence in [sound credits](./docs/sound-credits.md), made by `pnpm sounds:fetch` and `pnpm sounds` (loudness matched, seamless loops, Opus with AAC); the most a sport loads is under 110 kB. They are not in the npm package.
+- **Sound: a game's cues from its replay (KYOGIJO-STADIUMS-36)** ([game cues](./docs/sound.md#game-cues)): `sound.follow(controller, { periods, scoreAt })` plays each sport's cues as the replay goes by them (hockey's goal horn and the crowd's swell, a whistle at a stoppage, the buzzer at a period's end, a ring's bell, a starting gun, an "ooh" at a near miss), none on a seek or while paused, and under `level: "auto"` the crowd follows the game (`excitementAt`: loud late in a close game, a roar after a goal). `cueKindOf` reads a timeline's own words (`touchdown`, `try`, `ippon`, `foul`...); `cuesOf` and `cuesOfChange` are the rules, pure. The demo's game section and every Play a game (the arena at the top of the page, Try it and the real arenas) have the sound, with Follow the game among the levels; `play-game.js` tells a page of the replay it puts on the view (`onReplay`).
+- **Sound: live events (KYOGIJO-STADIUMS-36)** ([live events](./docs/sound.md#live-events)): `sound.cue({ kind, team })` plays an event's cues as it happens, and `sound.game(moment)` gives the game's state to the level under `auto`; a goal lifts it to a roar for six seconds. The demo's live score has the sound, and pushes each goal and the game's end as they come.
+
 ## [0.60.1] - 2026-11-03
 
 ### Fixed

package/README.md

@@ -159,7 +159,7 @@ Real buildings drawn in the outline OpenStreetMap maps for them, each with a pla
 <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">
+<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 goal's arrow into the net." width="250">
 </picture>
 <br><em>A made-up game, replayed in 3D</em>
 </td>
@@ -182,7 +182,7 @@ Real buildings drawn in the outline OpenStreetMap maps for them, each with a pla
 
 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)).
+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)). In a stoppage its clock stands still while the players glide to the face-off's line-up and the dead puck is out of sight, and it runs again at the drop ([stoppages](./docs/replay.md#stoppages-the-clock-stops-the-players-line-up)). A penalized player sits in his box for his time while his side plays short, and the board shows the power play and each penalty's clock ([penalties](./docs/replay.md#penalties-and-the-power-play)).
 
 **Surfaces** ([the surfaces](./docs/surfaces.md), [score and layout](./docs/score.md))
 
@@ -260,6 +260,7 @@ console.log(svg.startsWith("<svg"), svg.includes("USA 3, Canada 2"));
 - **Bring your own race feed**: a race plays from a feed you choose, read by your own browser from an address, pasted or from a file, and followed while it is live: kyogijo's open race timeline or OpenF1-style lap rows, with our made-up sample feed first. [The race feed](./docs/race-feed.md), [Where to find a feed](./docs/where-to-find-a-feed.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, 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).
+- **Sound**: the crowd of each kind of venue at a level from quiet to a roar, heard in the room its venue makes, and its game's sounds (the goal horn, the whistle, the buzzer, the bell) from a replay or live events; made in the browser, off until turned on. [Sound](./docs/sound.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.
@@ -275,6 +276,7 @@ console.log(svg.startsWith("<svg"), svg.includes("USA 3, Canada 2"));
 | `./circuits` | Race tracks as OpenStreetMap maps them, in 2D and 3D, and a simulated race on them with its clock and timing board ([demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/circuits.html?race=1)). |
 | `./multi`, `./judging`, `./layouts` | Several surfaces for one event ([demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/halls.html)); who judges where; small multiples and backgrounds. |
 | `./layers`, `./charts`, `./frames`, `./zones`, `./pointer`, `./replay` | Data layers, charts, the providers' frames, zones by the rules, a click as a place, tracking data played on a surface. |
+| `./sound` | A surface's crowd and its game's sounds, made in the browser with Web Audio ([demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/venues.html?sound=on)). |
 | `./athletics`, `./budo`, `./skating` | The athletics stadium, the budō (areas, dohyō, the dojo builder) and the skating rinks. |
 | `./scene`, `./canvas`, `./d3`, `./plot`, `./geojson`, `./png` | The drawing as data, on a canvas, in d3, as an Observable Plot mark, as GeoJSON, as a PNG. |
 | `./mount`, `./react`, `./element`, `./element/define` | Draw into a container; React props; the `<kyogijo-field>` element and its registration. |

package/catalogue.json

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

package/dist/replay-entry.d.ts

@@ -2,8 +2,12 @@ import "./full.ts";
 import "./venues.all.ts";
 export { activeEvents, describeEvent, drawFrame, eventsBetween, interpolate, possession, replayClock, replayEvents, replayInfo, replayLayers, replaySnapshot, replaySummary, replayTable, replayTimes, trails } from "./replay.ts";
 export type { ReplaySnapshot } from "./replay.ts";
-export { boardClock, replayBoard, replayPeriods } from "./replay.board.ts";
-export type { ReplayBoardState } from "./replay.board.ts";
+export { boardClock, penaltiesAt, replayBoard, replayGameClock, replayGameTime, replayPenalties, replayPeriods } from "./replay.board.ts";
+export type { ReplayBoardState, ReplayGameClock, ServedPenalty } from "./replay.board.ts";
+export { addDeadTime, deadSeconds, replayStoppages, restartsBetween, stoppageAt } from "./replay.deadtime.ts";
+export type { DeadStop, DeadTimeRules } from "./replay.deadtime.ts";
+export { HOCKEY_BLUE_LINE, HOCKEY_DEAD_TIME, HOCKEY_DOTS, HOCKEY_PENALTY_MINUTES, HOCKEY_RULES, hockeyFaceoffDot, hockeyFormation, hockeyPenaltyBox, hockeyPenaltyEnds, hockeyPenaltyKind, hockeyStopOf, isHockeyDot, } from "./replay.hockey.ts";
+export type { HockeyCall, HockeyPenaltyKind, HockeyRole, HockeyServed, HockeyStop, HockeyStopAt } from "./replay.hockey.ts";
 export { alongPool, distanceAt, progressOf, raceTimeline } from "./pool.replay.ts";
 export type { Progress, RaceReplayOptions } from "./pool.replay.ts";
 export { formatTime, parseTime } from "./pool.race.ts";
@@ -11,4 +15,4 @@ export { REPLAY_SPEEDS, REPLAY_SPEED_RANGE, createReplay } from "./replay.contro
 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";
+export type { ActiveEvent, Possession, ReplayChange, ReplayEvent, ReplayEventKind, ReplayFrame, ReplayLook, ReplayObject, ReplayPenalty, ReplayPeriod, ReplayReason, ReplaySettings, ReplayState, ReplayStoppage, ReplayTeam, ReplayTimeline, ReplayTrail, } from "./replay.types.ts";

package/dist/replay-entry.js

@@ -4,7 +4,9 @@ import "./full.js";
 // The real venues of the NHL's arenas, as this entry has always had them (the lean district reads the ones it shows).
 import "./venues.all.js";
 export { activeEvents, describeEvent, drawFrame, eventsBetween, interpolate, possession, replayClock, replayEvents, replayInfo, replayLayers, replaySnapshot, replaySummary, replayTable, replayTimes, trails } from "./replay.js";
-export { boardClock, replayBoard, replayPeriods } from "./replay.board.js";
+export { boardClock, penaltiesAt, replayBoard, replayGameClock, replayGameTime, replayPenalties, replayPeriods } from "./replay.board.js";
+export { addDeadTime, deadSeconds, replayStoppages, restartsBetween, stoppageAt } from "./replay.deadtime.js";
+export { HOCKEY_BLUE_LINE, HOCKEY_DEAD_TIME, HOCKEY_DOTS, HOCKEY_PENALTY_MINUTES, HOCKEY_RULES, hockeyFaceoffDot, hockeyFormation, hockeyPenaltyBox, hockeyPenaltyEnds, hockeyPenaltyKind, hockeyStopOf, isHockeyDot, } from "./replay.hockey.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";

package/dist/replay.board.d.ts

@@ -1,4 +1,4 @@
-import type { ReplayPeriod, ReplayTimeline } from "./replay.types.ts";
+import type { ReplayPenalty, ReplayPeriod, ReplayStoppage, ReplayTimeline } from "./replay.types.ts";
 /** The board at a time. */
 export interface ReplayBoardState {
     /** The goals so far: the events of kind `goal` at or before the time, by `team`. */
@@ -7,6 +7,14 @@ export interface ReplayBoardState {
     period?: number;
     /** The game clock as it is written, `19:20`: the time left in the period, or the time gone when the timeline counts `up`. Whole seconds, so it changes once a second of game time at most. */
     clock: string;
+    /** Only when the timeline has penalties: the skaters each side has on the ice (`[5, 4]` is a power play for the home side). */
+    strength?: [number, number];
+    /** Only when the timeline has penalties: each penalty being served at the time, by its side, with its time left as the board writes it (`1:42`), those that make the side play short first. */
+    penalties?: {
+        team: "home" | "away";
+        left: string;
+        short: boolean;
+    }[];
 }
 /** Seconds on a board's clock, `19:20`. A board has two digits of minutes, so more than 99:59 is shown as 99:59. */
 export declare function boardClock(seconds: number): string;
@@ -14,10 +22,73 @@ export declare function boardClock(seconds: number): string;
 export declare function replayPeriods(timeline: ReplayTimeline): readonly (ReplayPeriod & {
     number?: number;
 })[];
+/** The game clock at a time on the replay's clock. */
+export interface ReplayGameClock {
+    /** The period's number, or `undefined` when the timeline has no periods. */
+    period?: number;
+    /** Seconds of the period played on the game clock, and seconds left of it. */
+    played: number;
+    left: number;
+    /** `false` in a stoppage (and before a period has begun or after it has ended): the game clock is standing still. */
+    running: boolean;
+    /** The stoppage the time is in, when it is in one. */
+    stoppage?: ReplayStoppage;
+}
+/**
+ * The game clock at a time `t` on the replay's clock: the period it is in (the last that has begun; the first, before any has) and how much of it has been played. The game clock runs only while play is
+ * on: it stands still in each of the timeline's `stoppages`, while the replay's clock moves on through it. A period's `length` is spread over the seconds of it that are not in a stoppage, so a game
+ * re-timed to minutes reads like the real one. Pure.
+ * @example
+ * ```ts
+ * import { replayGameClock } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const timeline = {
+ *   frames: [{ t: 0, objects: [] }, { t: 70, objects: [] }],
+ *   periods: [{ start: 0, end: 70, length: 1200 }],
+ *   stoppages: [{ start: 30, end: 40, reason: "goal" }],
+ * };
+ * const at = (t: number) => { const c = replayGameClock(timeline, t); return `${c.played} ${c.running}`; };
+ * console.log(at(15), at(30), at(35), at(40), at(55));
+ * // 300 true 600 false 600 false 600 true 900 true
+ * ```
+ */
+export declare function replayGameClock(timeline: ReplayTimeline, t: number): ReplayGameClock;
+/**
+ * The game time at `t` on the replay's clock: the seconds of game clock played since the first period began (the lengths of the periods before, and what has been played of this one). It stands still in a
+ * stoppage, as the game clock does: a penalty's two minutes are two minutes of it.
+ */
+export declare function replayGameTime(timeline: ReplayTimeline, t: number): number;
+export declare function replayPenalties(timeline: ReplayTimeline): readonly ReplayPenalty[];
+/** A penalty being served at a time, and its game seconds left. */
+export interface ServedPenalty {
+    penalty: ReplayPenalty;
+    left: number;
+}
+/**
+ * The penalties being served at `t` (the player is in the box: from the call to his `end`) with the game seconds left of each, and each side's skaters on the ice: five, less one for each penalty that
+ * makes it play short, never fewer than three. A penalty's time left is the game clock from now to its `end` (it runs only while the game clock does), or, with no end or one a power-play goal
+ * brought early (`endedBy: "goal"`), its minutes from the drop after the call. Pure.
+ * @example
+ * ```ts
+ * import { penaltiesAt } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const timeline = {
+ *   frames: [{ t: 0, objects: [] }, { t: 60, objects: [] }],
+ *   periods: [{ start: 0, end: 60, length: 1200 }],
+ *   penalties: [{ team: "away" as const, by: "a4", start: 10, end: 16, minutes: 2 }],
+ * };
+ * const at = penaltiesAt(timeline, 12);
+ * console.log(at.strength, at.served.map((s) => `${s.penalty.by} ${s.left}`), penaltiesAt(timeline, 16).strength);
+ * // [ 5, 4 ] [ 'a4 80' ] [ 5, 5 ]
+ * ```
+ */
+export declare function penaltiesAt(timeline: ReplayTimeline, t: number): {
+    served: ServedPenalty[];
+    strength: [number, number];
+};
 /**
- * The scoreboard of a replay at a time `t`, in seconds on the timeline's clock. The score is the goals at or before it; the period is the last one that has begun (the first, before any has);
- * the clock runs through the period from its full length to nothing, or from nothing up when the timeline counts `up`. A period with a `length` of its own runs its clock through that many
- * seconds however long it lasts on the timeline, so a game re-timed to minutes can read like the real one.
+ * The scoreboard of a replay at a time `t`, in seconds on the timeline's clock. The score is the goals at or before it; the period and the clock are the game clock's (`replayGameClock`): the clock runs
+ * through the period from its full length to nothing, or from nothing up when the timeline counts `up`, and stands still in a stoppage. A period with a `length` of its own runs its clock through that many
+ * seconds however long it lasts on the timeline, so a game re-timed to minutes can read like the real one. A timeline with `penalties` adds each side's `strength` and the penalties being served,
+ * with their time left (`penaltiesAt`).
  * @example
  * ```ts
  * import { replayBoard } from "@johnmorrisdotca/kyogijo-stadiums/replay";

package/dist/replay.board.js

@@ -1,6 +1,7 @@
 // What a scoreboard shows of a replayed game at a time: the score, the period and the game clock, worked out from the same timeline the replay plays (its goals and its periods). Pure: a timeline and a time
 // give the same board every time, so a seek, a step and a period's button all land on the right figures at once, and a replay that goes back finds the score as it was. The 3D view draws it on the scoreboard
 // hung over the surface (`turn.replay.ts`); a page that draws its own board reads it the same way.
+import { deadSeconds, stoppageAt } from "./replay.deadtime.js";
 import { replayEvents, replayInfo } from "./replay.js";
 const isNum = (value) => typeof value === "number" && Number.isFinite(value);
 const two = (n) => String(n).padStart(2, "0");
@@ -19,9 +20,106 @@ export function replayPeriods(timeline) {
     return [...given].sort((a, b) => a.start - b.start).map((p, i) => ({ ...p, number: isNum(p.number) ? p.number : i + 1 }));
 }
 /**
- * The scoreboard of a replay at a time `t`, in seconds on the timeline's clock. The score is the goals at or before it; the period is the last one that has begun (the first, before any has);
- * the clock runs through the period from its full length to nothing, or from nothing up when the timeline counts `up`. A period with a `length` of its own runs its clock through that many
- * seconds however long it lasts on the timeline, so a game re-timed to minutes can read like the real one.
+ * The game clock at a time `t` on the replay's clock: the period it is in (the last that has begun; the first, before any has) and how much of it has been played. The game clock runs only while play is
+ * on: it stands still in each of the timeline's `stoppages`, while the replay's clock moves on through it. A period's `length` is spread over the seconds of it that are not in a stoppage, so a game
+ * re-timed to minutes reads like the real one. Pure.
+ * @example
+ * ```ts
+ * import { replayGameClock } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const timeline = {
+ *   frames: [{ t: 0, objects: [] }, { t: 70, objects: [] }],
+ *   periods: [{ start: 0, end: 70, length: 1200 }],
+ *   stoppages: [{ start: 30, end: 40, reason: "goal" }],
+ * };
+ * const at = (t: number) => { const c = replayGameClock(timeline, t); return `${c.played} ${c.running}`; };
+ * console.log(at(15), at(30), at(35), at(40), at(55));
+ * // 300 true 600 false 600 false 600 true 900 true
+ * ```
+ */
+export function replayGameClock(timeline, t) {
+    const periods = replayPeriods(timeline);
+    let at = periods[0];
+    for (const p of periods)
+        if (p.start <= t)
+            at = p;
+    const live = at.end - at.start - deadSeconds(timeline, at.start, at.end);
+    const into = Math.min(at.end, Math.max(at.start, t));
+    const gone = into - at.start - deadSeconds(timeline, at.start, into);
+    const share = live > 0 ? Math.min(1, Math.max(0, gone / live)) : 0;
+    const length = isNum(at.length) && at.length > 0 ? at.length : live;
+    const stoppage = stoppageAt(timeline, t);
+    const played = share * length;
+    const running = stoppage === undefined && t >= at.start && t < at.end;
+    return { ...(at.number === undefined ? {} : { period: at.number }), played, left: length - played, running, ...(stoppage === undefined ? {} : { stoppage }) };
+}
+/**
+ * The game time at `t` on the replay's clock: the seconds of game clock played since the first period began (the lengths of the periods before, and what has been played of this one). It stands still in a
+ * stoppage, as the game clock does: a penalty's two minutes are two minutes of it.
+ */
+export function replayGameTime(timeline, t) {
+    const periods = replayPeriods(timeline);
+    let before = 0;
+    for (const p of periods) {
+        if (p.end > t)
+            break;
+        const next = periods[periods.indexOf(p) + 1];
+        if (next === undefined || next.start > t)
+            break;
+        before += isNum(p.length) && p.length > 0 ? p.length : p.end - p.start - deadSeconds(timeline, p.start, p.end);
+    }
+    return before + replayGameClock(timeline, t).played;
+}
+/** The penalties of a timeline, each checked: a side, a start and minutes that are numbers. Kept for the next call. */
+const PENALTIES = new WeakMap();
+export function replayPenalties(timeline) {
+    const hit = PENALTIES.get(timeline);
+    if (hit !== undefined)
+        return hit;
+    const given = Array.isArray(timeline.penalties) ? timeline.penalties : [];
+    const out = given.filter((p) => typeof p === "object" && p !== null && (p.team === "home" || p.team === "away") && isNum(p.start) && isNum(p.minutes) && p.minutes > 0 && (p.end === undefined || (isNum(p.end) && p.end >= p.start))).map((p) => ({ ...p }));
+    PENALTIES.set(timeline, out);
+    return out;
+}
+/**
+ * The penalties being served at `t` (the player is in the box: from the call to his `end`) with the game seconds left of each, and each side's skaters on the ice: five, less one for each penalty that
+ * makes it play short, never fewer than three. A penalty's time left is the game clock from now to its `end` (it runs only while the game clock does), or, with no end or one a power-play goal
+ * brought early (`endedBy: "goal"`), its minutes from the drop after the call. Pure.
+ * @example
+ * ```ts
+ * import { penaltiesAt } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const timeline = {
+ *   frames: [{ t: 0, objects: [] }, { t: 60, objects: [] }],
+ *   periods: [{ start: 0, end: 60, length: 1200 }],
+ *   penalties: [{ team: "away" as const, by: "a4", start: 10, end: 16, minutes: 2 }],
+ * };
+ * const at = penaltiesAt(timeline, 12);
+ * console.log(at.strength, at.served.map((s) => `${s.penalty.by} ${s.left}`), penaltiesAt(timeline, 16).strength);
+ * // [ 5, 4 ] [ 'a4 80' ] [ 5, 5 ]
+ * ```
+ */
+export function penaltiesAt(timeline, t) {
+    const served = [];
+    const short = { home: 0, away: 0 };
+    const now = replayGameTime(timeline, t);
+    for (const p of replayPenalties(timeline)) {
+        if (p.start > t || (p.end !== undefined && p.end <= t))
+            continue;
+        const full = p.minutes * 60;
+        // Its time left: to its end on the game clock (a penalty that waited for a side two short begins its count later), or, with no end or one a power-play goal brought early, its minutes from the call.
+        const left = p.end !== undefined && p.endedBy !== "goal" ? Math.min(full, replayGameTime(timeline, p.end) - now) : full - (now - replayGameTime(timeline, p.start));
+        if (left <= 0 && p.end === undefined)
+            continue;
+        served.push({ penalty: p, left: Math.max(0, left) });
+        if (p.short !== false)
+            short[p.team] += 1;
+    }
+    return { served, strength: [Math.max(3, 5 - short.home), Math.max(3, 5 - short.away)] };
+}
+/**
+ * The scoreboard of a replay at a time `t`, in seconds on the timeline's clock. The score is the goals at or before it; the period and the clock are the game clock's (`replayGameClock`): the clock runs
+ * through the period from its full length to nothing, or from nothing up when the timeline counts `up`, and stands still in a stoppage. A period with a `length` of its own runs its clock through that many
+ * seconds however long it lasts on the timeline, so a game re-timed to minutes can read like the real one. A timeline with `penalties` adds each side's `strength` and the penalties being served,
+ * with their time left (`penaltiesAt`).
  * @example
  * ```ts
  * import { replayBoard } from "@johnmorrisdotca/kyogijo-stadiums/replay";
@@ -48,15 +146,17 @@ export function replayBoard(timeline, t) {
         if (e.kind === "goal" && (e.team === "home" || e.team === "away"))
             score[e.team === "home" ? 0 : 1] += 1;
     }
-    const periods = replayPeriods(timeline);
-    let at = periods[0];
-    for (const p of periods)
-        if (p.start <= t)
-            at = p;
-    const span = at.end - at.start;
-    const share = span > 0 ? Math.min(1, Math.max(0, (t - at.start) / span)) : 0;
-    const length = isNum(at.length) && at.length > 0 ? at.length : span;
+    const game = replayGameClock(timeline, t);
     // Down: the time left, rounded up, so that the full length shows until the period has moved and nothing shows only at its end. Up: the whole seconds gone.
-    const clock = timeline.clock === "up" ? boardClock(share * length) : boardClock(Math.ceil((1 - share) * length - 1e-9));
-    return at.number === undefined ? { score, clock } : { score, period: at.number, clock };
+    const clock = timeline.clock === "up" ? boardClock(game.played) : boardClock(Math.ceil(game.left - 1e-9));
+    const board = game.period === undefined ? { score, clock } : { score, period: game.period, clock };
+    if (replayPenalties(timeline).length > 0) {
+        const { served, strength } = penaltiesAt(timeline, t);
+        board.strength = strength;
+        board.penalties = served
+            .map((s) => ({ team: s.penalty.team, left: boardClock(Math.ceil(s.left - 1e-9)), short: s.penalty.short !== false, seconds: s.left }))
+            .sort((a, b) => Number(b.short) - Number(a.short) || a.seconds - b.seconds)
+            .map(({ team, left, short }) => ({ team, left, short }));
+    }
+    return board;
 }

package/dist/replay.d.ts

@@ -44,7 +44,7 @@ export declare function interpolate(timeline: ReplayTimeline, t: number, options
 }): ReplayObject[];
 /**
  * The path each object took over the last `seconds` before `t`, oldest place first and ending at its place at `t`: the frames in between, and the places at the two ends.
- * Only objects that are there at `t` have a trail. `teams` and `ids` choose whose; all by default.
+ * Only objects that are there at `t` have a trail, and it begins after the last frame the object was not in (a dead puck out of sight). `teams` and `ids` choose whose; all by default.
  * @example
  * ```ts
  * import { trails } from "@johnmorrisdotca/kyogijo-stadiums/replay";

package/dist/replay.deadtime.d.ts

@@ -0,0 +1,58 @@
+import type { ReplayObject, ReplayStoppage, ReplayTimeline } from "./replay.types.ts";
+type P = readonly [number, number];
+/**
+ * The stoppages of a timeline, in order, each checked: a `start` and an `end` that are numbers, the end not before the start. Ones that overlap are joined. Read once and kept.
+ * @example
+ * ```ts
+ * import { replayStoppages } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const frames = [{ t: 0, objects: [] }];
+ * console.log(replayStoppages({ frames, stoppages: [{ start: 9, end: 12 }, { start: 2, end: 5, reason: "goal" }, { start: 4, end: 6 }, { start: 8, end: 7 }] }));
+ * // [ { start: 2, end: 6, reason: 'goal' }, { start: 9, end: 12 } ]
+ * ```
+ */
+export declare function replayStoppages(timeline: ReplayTimeline): readonly ReplayStoppage[];
+/** The stoppage a time is in (from its start, up to but not at its end, when play starts again), or `undefined` while play is on. */
+export declare function stoppageAt(timeline: ReplayTimeline, t: number): ReplayStoppage | undefined;
+/** The seconds of a span of the timeline's clock that were dead: the parts of it in stoppages. */
+export declare function deadSeconds(timeline: ReplayTimeline, from: number, to: number): number;
+/**
+ * The restarts that went by while the clock moved from `from` to `to` (`(from, to]`): the stoppages whose end, the drop of the puck, is in it. What a page plays the drop's sound on, as it plays the
+ * horn on a goal of `eventsBetween`.
+ */
+export declare function restartsBetween(timeline: ReplayTimeline, from: number, to: number): readonly ReplayStoppage[];
+/** How a sport's dead time goes: the speed the players go at and how long each part lasts, by the reason for the stoppage. */
+export interface DeadTimeRules {
+    /** The fastest a player goes to his place, in the timeline's units a second. */
+    speed: number;
+    /** Seconds after play stops before anyone heads for the restart: a goal is celebrated, a whistle is a moment. */
+    pause(reason: string): number;
+    /** Seconds after play stops that the dead ball or puck is still seen where it stopped; then it is out of sight until the restart. */
+    shown(reason: string): number;
+    /** The shortest time the players take to get to their places, and how long they stand in them before the restart. */
+    least: number;
+    hold: number;
+    /** Where a player who comes off goes, and one who comes on comes from (the bench's gate), or `undefined` for none: then they only go and come at the restart. */
+    bench?(object: ReplayObject): P | undefined;
+    /** Is it the ball or the puck: dead in the stoppage, out of sight until the restart. */
+    dead(object: ReplayObject): boolean;
+}
+/** A stoppage to write into a timeline: play stops at `t`; the timeline's frames from `until` on (the players in their places, the puck on the dot) are the restart. */
+export interface DeadStop {
+    t: number;
+    /** The time on the timeline given of the restart's frame: `t` and `until` are moved apart by the dead time, what was between them is left out, and the instant between them becomes part of the stoppage. 0.04 seconds after `t` by default. */
+    until?: number;
+    reason: string;
+    /** Where play starts again. */
+    x?: number;
+    y?: number;
+    team?: "home" | "away";
+}
+/**
+ * Write stoppages into a timeline. The timeline given has each stoppage as an instant: the play up to `t`, then at `until` the restart (the players in their places, the puck on the dot). Each is
+ * opened into the dead time the rules give: the puck stays where it stopped for a moment and is then out of sight, the players stand a moment (a goal is celebrated) and then go to their places at the
+ * rules' speed or slower (all getting there together, the farthest at the rules' speed), a player going off goes to the bench and the one coming on comes from it, and they stand in their places a
+ * moment before the restart. Everything after is moved on by the dead time; the periods with it (each keeps its length on the game clock), the events, the stoppages already there and the
+ * penalties. Pure.
+ */
+export declare function addDeadTime(timeline: ReplayTimeline, stops: readonly DeadStop[], rules: DeadTimeRules): ReplayTimeline;
+export {};

package/dist/replay.deadtime.js

@@ -0,0 +1,169 @@
+// Dead time: the stoppages of a replay. A stoppage stops the game clock (the board's) while the replay's own clock moves on; in it the ball or the puck is dead (it stays where play stopped,
+// then is out of sight until the restart) and the players go to their places for the restart at a speed a player would. The functions here are pure and know no sport: a sport's rule set
+// (`replay.hockey.ts` for the rink) says where play starts again, how long each part of the dead time lasts and how fast the players go, and `addDeadTime` writes the stoppages into a timeline.
+import { interpolate } from "./replay.js";
+const isNum = (value) => typeof value === "number" && Number.isFinite(value);
+const CLEAN = new WeakMap();
+/**
+ * The stoppages of a timeline, in order, each checked: a `start` and an `end` that are numbers, the end not before the start. Ones that overlap are joined. Read once and kept.
+ * @example
+ * ```ts
+ * import { replayStoppages } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const frames = [{ t: 0, objects: [] }];
+ * console.log(replayStoppages({ frames, stoppages: [{ start: 9, end: 12 }, { start: 2, end: 5, reason: "goal" }, { start: 4, end: 6 }, { start: 8, end: 7 }] }));
+ * // [ { start: 2, end: 6, reason: 'goal' }, { start: 9, end: 12 } ]
+ * ```
+ */
+export function replayStoppages(timeline) {
+    const hit = CLEAN.get(timeline);
+    if (hit !== undefined)
+        return hit;
+    const given = Array.isArray(timeline.stoppages) ? timeline.stoppages : [];
+    const sorted = given
+        .filter((s) => typeof s === "object" && s !== null && isNum(s.start) && isNum(s.end) && s.end >= s.start)
+        .map((s) => ({ ...s }))
+        .sort((a, b) => a.start - b.start);
+    const out = [];
+    for (const s of sorted) {
+        const last = out[out.length - 1];
+        if (last !== undefined && s.start <= last.end)
+            last.end = Math.max(last.end, s.end);
+        else
+            out.push(s);
+    }
+    CLEAN.set(timeline, out);
+    return out;
+}
+/** The stoppage a time is in (from its start, up to but not at its end, when play starts again), or `undefined` while play is on. */
+export function stoppageAt(timeline, t) {
+    for (const s of replayStoppages(timeline)) {
+        if (s.start > t)
+            return undefined;
+        if (t < s.end)
+            return s;
+    }
+    return undefined;
+}
+/** The seconds of a span of the timeline's clock that were dead: the parts of it in stoppages. */
+export function deadSeconds(timeline, from, to) {
+    let dead = 0;
+    for (const s of replayStoppages(timeline)) {
+        if (s.start >= to)
+            break;
+        dead += Math.max(0, Math.min(to, s.end) - Math.max(from, s.start));
+    }
+    return dead;
+}
+/**
+ * The restarts that went by while the clock moved from `from` to `to` (`(from, to]`): the stoppages whose end, the drop of the puck, is in it. What a page plays the drop's sound on, as it plays the
+ * horn on a goal of `eventsBetween`.
+ */
+export function restartsBetween(timeline, from, to) {
+    return replayStoppages(timeline).filter((s) => s.end > from && s.end <= to);
+}
+const round2 = (n) => Math.round(n * 100) / 100;
+const round1 = (n) => Math.round(n * 10) / 10;
+const ceil2 = (n) => Math.ceil(n * 100 - 1e-6) / 100;
+const dist = (a, b) => Math.hypot(b[0] - a[0], b[1] - a[1]);
+const placeOn = (path, t) => {
+    if (t < path.from || t >= path.until)
+        return undefined;
+    let at = path.legs[0].a;
+    for (const leg of path.legs) {
+        if (t < leg.t0)
+            break;
+        if (t >= leg.t1)
+            at = leg.b;
+        else {
+            const f = leg.t1 > leg.t0 ? (t - leg.t0) / (leg.t1 - leg.t0) : 1;
+            return [leg.a[0] + (leg.b[0] - leg.a[0]) * f, leg.a[1] + (leg.b[1] - leg.a[1]) * f];
+        }
+    }
+    return at;
+};
+/**
+ * Write stoppages into a timeline. The timeline given has each stoppage as an instant: the play up to `t`, then at `until` the restart (the players in their places, the puck on the dot). Each is
+ * opened into the dead time the rules give: the puck stays where it stopped for a moment and is then out of sight, the players stand a moment (a goal is celebrated) and then go to their places at the
+ * rules' speed or slower (all getting there together, the farthest at the rules' speed), a player going off goes to the bench and the one coming on comes from it, and they stand in their places a
+ * moment before the restart. Everything after is moved on by the dead time; the periods with it (each keeps its length on the game clock), the events, the stoppages already there and the
+ * penalties. Pure.
+ */
+export function addDeadTime(timeline, stops, rules) {
+    // Each period's length on the game clock, before the dead time stretches it: a period that had none keeps the live seconds it had.
+    const periods = timeline.periods?.map((p) => ({ ...p, length: isNum(p.length) ? p.length : p.end - p.start - deadSeconds(timeline, p.start, p.end) }));
+    let frames = [...timeline.frames];
+    let events = [...(timeline.events ?? [])];
+    let stoppages = [...replayStoppages(timeline)];
+    // The last first, so that a stoppage does not move the ones before it.
+    const order = [...stops].filter((s) => isNum(s.t)).sort((a, b) => b.t - a.t);
+    let pers = periods;
+    let penalties = timeline.penalties?.map((p) => ({ ...p }));
+    for (const stop of order) {
+        const t0 = stop.t;
+        const u = isNum(stop.until) && stop.until > t0 ? stop.until : t0 + 0.04;
+        const view = { ...timeline, frames, events: [] };
+        const at = new Map(interpolate(view, t0).map((o) => [o.id, o]));
+        const next = new Map(interpolate(view, u).map((o) => [o.id, o]));
+        const pause = round2(Math.max(0, rules.pause(stop.reason)));
+        const shown = round2(Math.max(0, rules.shown(stop.reason)));
+        // The players: who stays on, who goes off and who comes on, and how far each goes.
+        const stay = [];
+        const off = [];
+        const on = [];
+        for (const [id, o] of at) {
+            if (rules.dead(o))
+                continue;
+            const b = next.get(id);
+            if (b !== undefined)
+                stay.push([o, [o.x, o.y], [b.x, b.y]]);
+            else
+                off.push([o, [o.x, o.y], rules.bench?.(o)]);
+        }
+        for (const [id, o] of next)
+            if (!rules.dead(o) && !at.has(id))
+                on.push([o, rules.bench?.(o), [o.x, o.y]]);
+        const leave = Math.max(0, ...off.map(([, a, b]) => (b === undefined ? 0 : dist(a, b) / rules.speed)));
+        const swap = off.length > 0 || on.length > 0 ? ceil2(pause + leave) : pause;
+        const come = Math.max(0, ...on.map(([, a, b]) => (a === undefined ? 0 : dist(a, b) / rules.speed)));
+        const skate = Math.max(...stay.map(([, a, b]) => dist(a, b) / rules.speed), 0);
+        const arrive = ceil2(Math.max(pause + Math.max(rules.least, skate), on.length > 0 ? round2(swap + 0.04) + come : 0));
+        const total = round2(Math.max(arrive + rules.hold, shown + 1));
+        // The paths.
+        const paths = [];
+        for (const [object, a, b] of stay)
+            paths.push({ object, from: 0, until: Infinity, legs: [{ t0: 0, t1: pause, a, b: a }, { t0: pause, t1: arrive, a, b }] });
+        for (const [object, a, b] of off)
+            paths.push({ object, from: 0, until: b === undefined ? swap : round2(swap + 0.04), legs: [{ t0: 0, t1: pause, a, b: a }, { t0: pause, t1: swap, a, b: b ?? a }] });
+        for (const [object, a, b] of on)
+            paths.push({ object, from: a === undefined ? arrive : round2(swap + 0.04), until: Infinity, legs: [{ t0: round2(swap + 0.04), t1: arrive, a: a ?? b, b }] });
+        const deadOnes = [...at.values()].filter((o) => rules.dead(o));
+        const changes = off.length > 0 || on.length > 0 ? [swap, round2(swap + 0.04)] : [];
+        const moments = [...new Set([0, pause, shown, ...changes, arrive].map(round2))].filter((m) => m >= 0 && m < total).sort((a, b) => a - b);
+        const inserted = moments.map((m) => {
+            const objects = [];
+            for (const path of paths) {
+                const p = placeOn(path, m);
+                if (p !== undefined)
+                    objects.push({ ...path.object, x: round1(p[0]), y: round1(p[1]) });
+            }
+            // The dead puck: where it stopped, and out of sight from `shown` on.
+            if (m < shown)
+                for (const o of deadOnes)
+                    objects.push({ ...o });
+            return { t: round2(t0 + m), objects };
+        });
+        // The restart: the frame given at `until`, and everything after it, moved on.
+        const shift = round2(t0 + total - u);
+        const move = (t) => (t >= u ? round2(t + shift) : t > t0 ? t0 : t);
+        const restart = { t: round2(t0 + total), objects: [...next.values()] };
+        frames = [...frames.filter((f) => f.t < t0), ...inserted, restart, ...frames.filter((f) => f.t > u).map((f) => ({ ...f, t: move(f.t) }))];
+        events = events.map((e) => ({ ...e, t: move(e.t), ...(isNum(e.until) ? { until: move(e.until) } : {}) }));
+        stoppages = [
+            ...stoppages.map((s) => ({ ...s, start: move(s.start), end: move(s.end) })),
+            { start: t0, end: round2(t0 + total), reason: stop.reason, ...(isNum(stop.x) && isNum(stop.y) ? { x: stop.x, y: stop.y } : {}), ...(stop.team === undefined ? {} : { team: stop.team }) },
+        ].sort((a, b) => a.start - b.start);
+        pers = pers?.map((p) => ({ ...p, start: move(p.start), end: move(p.end) }));
+        penalties = penalties?.map((p) => ({ ...p, start: move(p.start), ...(isNum(p.end) ? { end: move(p.end) } : {}) }));
+    }
+    return { ...timeline, frames, events: events.sort((a, b) => a.t - b.t), stoppages, ...(pers === undefined ? {} : { periods: pers }), ...(penalties === undefined ? {} : { penalties }) };
+}