@johnmorrisdotca/kyogijo-stadiums 0.53.0 → 0.55.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.55.0] - 2026-11-03
+
+### Added
+
+- **A simulated race on a circuit (KYOGIJO-STADIUMS-32)** ([a race](./docs/circuits.md#a-race)): twenty made-up cars as dots from the grid to the chequered flag over a full race distance (50 laps of Las Vegas, about an hour and twenty-two minutes), with gaps, passes, trains, one or two pit stops each and now and then a retirement, all from a seed. `simulateRace` works it out (the lap's speeds from the bends, `paceProfile`), `raceAt` gives any moment (the order, the gaps to the leader and the car in front, the last and best laps, the stops), `drawRace` and `raceBoard` draw it, and `mountCircuitRace` plays it in a page, flat or in 3D (the cars standing as discs), with a race clock, play, 1×, 10× and 60×, a slider over the whole race and the timing board, in English and Japanese. It is labelled a simulation: every team, driver, code and colour is invented, and no real race is in it; the model's figures were guided by public timing data read once and kept outside the package. Nothing runs while it is paused, hidden or out of sight, the 3D view's auto-turn and the race share one frame, and destroy leaves nothing. The demo's circuits page has a **Race** button, kept in the address with the speed and the moment.
+
+## [0.54.0] - 2026-11-03
+
+### Added
+
+- **Play a game wherever the rink is (KYOGIJO-STADIUMS-42)** ([example games](./docs/example-games.md#the-index)): the demo's **Play a game** toggle is on every view that can play an example game: the real arenas' page in 3D (after Labels; `game=1` in the address), the home page's Try it surface, flat with `mount.replay` and in 3D with `view.replay` (after Dark; `game=1`), and the home page's arena as before (`fgame=1`). Where it shows is the index's to say: `examples/games/index.json` lists each game with the surface it is played on, its file, its frame and its title in English and Japanese, so a new game is its file and one line, and no code. Off until pressed; the game is fetched on the first press only; pressing again gives back the empty surface, and on Try it the reader's own teams and score exactly as they were (the game's sides and live score are laid over them while it plays, and the module code shows the replay). A change of arena, of flat and 3D, of the crowd or of the theme keeps the game at the same moment; another surface, a badge or the flat arena stops it and leaves nothing behind. On an arena with its LED boards on, the scoreboard over the ice follows the game (the replay board of 0.53.0), on the arenas page as on the home page's arena. One controller, `demo/play-game.js`, serves the three, and `e2e/game.demo.mjs` holds the replay's freeze and leak budgets on these pages (no frame while paused, hidden or out of sight; one a frame with the auto-turn; the same elements and listeners after ten times round; nothing left after it stops) and the index's say with a fake index. The 3D views of the arenas page and of Try it no longer leave two listeners on their stage each time they are made again.
+
+### Changed
+
+- The demo's surface picker (KYOGIJO-STADIUMS-43): the Try it panel's Surface choice, 43 chips in one unordered block, is now a row of kinds (field, court, ice, pool, track, budō, mat and ring), then that kind's sports A to Z in the page's language (in Japanese by reading, in gojūon order), then for gridiron football its NFL, CFL and IFAF fields in a small row under it. Each row is a radio group (arrow keys, Home and End move, Space and Enter choose); the address still names the surface (`?sport=cfl`) and brings back its kind and sport; a surface with an example game in `examples/games/index.json` carries a small play mark. The logic is `demo/surface-kinds.js`, with `src/surface-kinds.test.js` and `e2e/surface.demo.mjs`.
+
 ## [0.53.0] - 2026-11-03
 
 - **The arena's scoreboard shows the game being played (KYOGIJO-STADIUMS-35)** ([the scoreboard over the arena](./docs/replay.md#the-scoreboard-over-the-arena-follows-the-game)): while a replay plays on a 3D view whose venue has its LED boards on, the scoreboard hung over centre ice shows the replay's score, period and game clock instead of the fixed score of its options. `replayBoard(timeline, t)` (pure, from `replay`) works the board out from the timeline's goals and its new optional `periods` (`start`, `end`, `number`, `length`) and `clock` (`down` or `up`). The board is written when it changes: at once for a goal, a period, a seek, a step or a pause; the clock at most once a second while playing; nothing runs while paused, hidden or out of sight. Without a replay, or after `destroy`, the board is as before, and `view.replay(timeline, { board: false })` leaves it so. The demo's hero passes the example game's periods (a period is twenty minutes on the board's clock). About 4 kB more source for the 3D replay (its budget in `replay.budget.test.js` is 24 kB now).

package/README.md

@@ -114,6 +114,13 @@ Real buildings drawn in the outline OpenStreetMap maps for them, each with a pla
 </picture>
 <br><em>The same lap 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/circuits-race-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kyogijo-stadiums/main/docs/images/circuits-race-desk-light.webp" alt="A simulated race on the same circuit half an hour in: twenty coloured dots with their positions, the race clock at Lap 18 of 50 and the timing board under it." width="250">
+</picture>
+<br><em>A simulated race, with its clock and timing board</em>
+</td>
 </tr>
 </table>
 
@@ -247,7 +254,7 @@ console.log(svg.startsWith("<svg"), svg.includes("USA 3, Canada 2"));
 - **A catalogue of venues**: every venue drawn today, the ones being built and the ones wanted (every NBA, MLB, NFL, CFL and NHL venue of the season, world soccer, cricket, rugby, the Olympics, Formula One and more), with ids, names in English and Japanese and Wikidata items, as a [JSON file](https://johnmorrisdotca.github.io/kyogijo-stadiums/catalogue.json) and a typed entry. [The catalogue](./docs/catalogue.md).
 - **Real venues**: arenas and stadiums in the outline of their buildings, districts of several venues on one plan, the crowd in the stands and outside. [Ballparks](./docs/ballparks.md), [venues](./docs/venues.md), [districts](./docs/district.md).
 - **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).
+- **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, and a simulated race on it: twenty made-up cars over a full race distance, with a race clock, a timing board and 1×, 10× and 60×. [Circuits](./docs/circuits.md#a-race).
 - **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).
 - **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).
@@ -262,7 +269,7 @@ console.log(svg.startsWith("<svg"), svg.includes("USA 3, Canada 2"));
 | `drawKyogijo`, `drawSurface`, `drawScore`, `drawBadge` | The drawing, as a string of SVG. |
 | `SPORTS`, `PARKS`, `COURT_THEMES`, `SOCCER_PITCHES`, `GROUNDS`, `EVENTS` | The forty-three sports, the 94 ballparks, the court looks, the pitches, the 64 grounds, the 18 special games. |
 | `./venues`, `./stadiums`, `./district`, `./turn` | Real arenas and stadiums in their buildings' outlines; districts on one plan; a surface as a 3D view that turns. |
-| `./circuits` | Race tracks as OpenStreetMap maps them, in 2D and 3D ([demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/circuits.html)). |
+| `./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. |
 | `./athletics`, `./budo`, `./skating` | The athletics stadium, the budō (areas, dohyō, the dojo builder) and the skating rinks. |

package/catalogue.json

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

package/dist/circuits-entry.d.ts

@@ -9,3 +9,17 @@ export { CIRCUIT_WORDS } from "./circuits.words.ts";
 export type { CircuitWords } from "./circuits.words.ts";
 export { lineLength } from "./circuits.geo.ts";
 export type { Circuit, CircuitBasis, CircuitData, CircuitFact, CircuitOptions, CircuitOsm, CircuitOsmPoint } from "./circuits.types.ts";
+export { RACE_PACE, cornerSpeed, paceProfile, speedAt } from "./circuits.pace.ts";
+export type { PaceProfile } from "./circuits.pace.ts";
+export { RACE_DISTANCE, raceLaps, simulateRace } from "./circuits.race.ts";
+export type { CircuitRace, RaceCar, RaceOptions, RaceStop } from "./circuits.race.ts";
+export { carAt, raceAt, racePoint } from "./circuits.race.moment.ts";
+export type { RaceMoment, RaceStanding, RaceStatus } from "./circuits.race.moment.ts";
+export { RACE_STYLE, drawRace, gapText, lapTime, raceBoard, raceClock, raceDrawing, raceStage } from "./circuits.race.draw.ts";
+export type { RaceDrawOptions, RaceDrawing } from "./circuits.race.draw.ts";
+export { RACE_SPEEDS, mountCircuitRace } from "./circuits.race.dom.ts";
+export type { KyogijoRace, RaceState, RaceViewOptions, RaceViewSettings } from "./circuits.race.dom.ts";
+export { RACE_CARS_MAX, RACE_DRIVERS, RACE_TEAMS } from "./circuits.race.field.ts";
+export type { RaceDriver, RaceTeam } from "./circuits.race.field.ts";
+export { RACE_WORDS } from "./circuits.race.words.ts";
+export type { RaceWords } from "./circuits.race.words.ts";

package/dist/circuits-entry.js

@@ -7,3 +7,11 @@ export { CIRCUIT_MARKER, CIRCUIT_PLANES_MAX, CIRCUIT_PRESETS, buildCircuitTurn,
 export { KYOGIJO_CIRCUIT_STYLE } from "./circuits.style.js";
 export { CIRCUIT_WORDS } from "./circuits.words.js";
 export { lineLength } from "./circuits.geo.js";
+// A simulated race on any circuit: made-up cars from the grid to the flag, its moments, its drawing and board, and its view in a page.
+export { RACE_PACE, cornerSpeed, paceProfile, speedAt } from "./circuits.pace.js";
+export { RACE_DISTANCE, raceLaps, simulateRace } from "./circuits.race.js";
+export { carAt, raceAt, racePoint } from "./circuits.race.moment.js";
+export { RACE_STYLE, drawRace, gapText, lapTime, raceBoard, raceClock, raceDrawing, raceStage } from "./circuits.race.draw.js";
+export { RACE_SPEEDS, mountCircuitRace } from "./circuits.race.dom.js";
+export { RACE_CARS_MAX, RACE_DRIVERS, RACE_TEAMS } from "./circuits.race.field.js";
+export { RACE_WORDS } from "./circuits.race.words.js";

package/dist/circuits.pace.d.ts

@@ -0,0 +1,96 @@
+import type { Pt } from "./crowd.ts";
+import type { CircuitPlan } from "./circuits.ts";
+/** The figures of the model, in metres and seconds. */
+export declare const RACE_PACE: Readonly<{
+    /** The fastest the car goes on a straight: 94 m/s, about 338 km/h. */
+    top: 94;
+    /** Grip across the car: `grip + downforce × v²` metres a second squared at a speed `v`, about 2.4 g in a hairpin and 5 g in a fast bend. */
+    grip: 22;
+    downforce: 0.0036;
+    /** How hard it brakes, and how hard it pulls away at rest; the pull falls to nothing at `top`. */
+    brake: 34;
+    launch: 17;
+    /** The line is read every `step` metres, and a bend is measured over `reach` either side: a racing car does not follow the middle of the road, so a short kink of it is not a bend. */
+    step: 5;
+    reach: 32;
+    /** The speed limit of the pit lane: 80 km/h. */
+    pitLimit: number;
+}>;
+/** A lap's speeds: one each `step` metres round the line from its first point, the time at each, and the lap's time and length. */
+export interface PaceProfile {
+    /** Metres between two samples. */
+    step: number;
+    /** The length of the line, in metres. */
+    length: number;
+    /** The speed at each sample, metres a second, and the seconds from the line's first point to each (one more than the speeds: the last is the lap's time). */
+    speed: Float64Array;
+    time: Float64Array;
+    /** The time of a flying lap, in seconds. */
+    lap: number;
+}
+/** The cumulative length of a ring at each of its points (the first 0, one more than the points: the last is the whole length). */
+export declare function ringLengths(points: readonly Pt[]): Float64Array;
+/** The point of a ring `along` units round it from its first point (wrapped), from its lengths (`ringLengths`): found by halving, so a page can ask for twenty a frame. */
+export declare function ringPoint(points: readonly Pt[], lengths: Float64Array, along: number): Pt;
+/** The same for an open line: held to its ends. */
+export declare function linePoint(points: readonly Pt[], lengths: Float64Array, along: number): Pt;
+/** The fastest speed a bend of radius `r` metres allows: `v² = r × (grip + downforce × v²)`, and the top speed where the downforce holds it at any speed. */
+export declare function cornerSpeed(r: number, pace?: Readonly<{
+    /** The fastest the car goes on a straight: 94 m/s, about 338 km/h. */
+    top: 94;
+    /** Grip across the car: `grip + downforce × v²` metres a second squared at a speed `v`, about 2.4 g in a hairpin and 5 g in a fast bend. */
+    grip: 22;
+    downforce: 0.0036;
+    /** How hard it brakes, and how hard it pulls away at rest; the pull falls to nothing at `top`. */
+    brake: 34;
+    launch: 17;
+    /** The line is read every `step` metres, and a bend is measured over `reach` either side: a racing car does not follow the middle of the road, so a short kink of it is not a bend. */
+    step: 5;
+    reach: 32;
+    /** The speed limit of the pit lane: 80 km/h. */
+    pitLimit: number;
+}>): number;
+/** How hard the car can pull away at a speed: `launch` at rest, nothing at the top speed. */
+export declare const pullAt: (v: number, pace?: Readonly<{
+    /** The fastest the car goes on a straight: 94 m/s, about 338 km/h. */
+    top: 94;
+    /** Grip across the car: `grip + downforce × v²` metres a second squared at a speed `v`, about 2.4 g in a hairpin and 5 g in a fast bend. */
+    grip: 22;
+    downforce: 0.0036;
+    /** How hard it brakes, and how hard it pulls away at rest; the pull falls to nothing at `top`. */
+    brake: 34;
+    launch: 17;
+    /** The line is read every `step` metres, and a bend is measured over `reach` either side: a racing car does not follow the middle of the road, so a short kink of it is not a bend. */
+    step: 5;
+    reach: 32;
+    /** The speed limit of the pit lane: 80 km/h. */
+    pitLimit: number;
+}>) => number;
+/**
+ * A plan's speeds round its lap (`circuitPlan`), from its line alone: the bends' radii give each sample's fastest speed, and two passes round (twice, so that the lap closes on itself) hold it to the engine and the
+ * brakes. The same plan always gives the same profile.
+ * @example
+ * ```ts
+ * import { circuitById, circuitPlan, paceProfile } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const pace = paceProfile(circuitPlan(circuitById("las-vegas")!));
+ * console.log(pace.lap > 90 && pace.lap < 105, Math.max(...pace.speed) * 3.6 > 300);
+ * // true true
+ * ```
+ */
+export declare function paceProfile(plan: CircuitPlan, pace?: Readonly<{
+    /** The fastest the car goes on a straight: 94 m/s, about 338 km/h. */
+    top: 94;
+    /** Grip across the car: `grip + downforce × v²` metres a second squared at a speed `v`, about 2.4 g in a hairpin and 5 g in a fast bend. */
+    grip: 22;
+    downforce: 0.0036;
+    /** How hard it brakes, and how hard it pulls away at rest; the pull falls to nothing at `top`. */
+    brake: 34;
+    launch: 17;
+    /** The line is read every `step` metres, and a bend is measured over `reach` either side: a racing car does not follow the middle of the road, so a short kink of it is not a bend. */
+    step: 5;
+    reach: 32;
+    /** The speed limit of the pit lane: 80 km/h. */
+    pitLimit: number;
+}>): PaceProfile;
+/** The speed at `along` metres round the lap from the line's first point (wrapped), between the two samples either side. */
+export declare function speedAt(profile: PaceProfile, along: number): number;

package/dist/circuits.pace.js

@@ -0,0 +1,131 @@
+import { FEET_PER_METRE as FT } from "./geometry.js";
+/** The figures of the model, in metres and seconds. */
+export const RACE_PACE = Object.freeze({
+    /** The fastest the car goes on a straight: 94 m/s, about 338 km/h. */
+    top: 94,
+    /** Grip across the car: `grip + downforce × v²` metres a second squared at a speed `v`, about 2.4 g in a hairpin and 5 g in a fast bend. */
+    grip: 22,
+    downforce: 0.0036,
+    /** How hard it brakes, and how hard it pulls away at rest; the pull falls to nothing at `top`. */
+    brake: 34,
+    launch: 17,
+    /** The line is read every `step` metres, and a bend is measured over `reach` either side: a racing car does not follow the middle of the road, so a short kink of it is not a bend. */
+    step: 5,
+    reach: 32,
+    /** The speed limit of the pit lane: 80 km/h. */
+    pitLimit: 80 / 3.6,
+});
+/** The cumulative length of a ring at each of its points (the first 0, one more than the points: the last is the whole length). */
+export function ringLengths(points) {
+    const out = new Float64Array(points.length + 1);
+    for (let i = 0; i < points.length; i += 1) {
+        const a = points[i];
+        const b = points[(i + 1) % points.length];
+        out[i + 1] = out[i] + Math.hypot(b[0] - a[0], b[1] - a[1]);
+    }
+    return out;
+}
+/** The point of a ring `along` units round it from its first point (wrapped), from its lengths (`ringLengths`): found by halving, so a page can ask for twenty a frame. */
+export function ringPoint(points, lengths, along) {
+    const total = lengths[lengths.length - 1];
+    if (!(total > 0))
+        return points[0];
+    const d = ((along % total) + total) % total;
+    let lo = 0;
+    let hi = points.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lengths[mid] <= d)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    const a = points[lo];
+    const b = points[(lo + 1) % points.length];
+    const long = lengths[lo + 1] - lengths[lo];
+    const t = long > 0 ? (d - lengths[lo]) / long : 0;
+    return [a[0] + t * (b[0] - a[0]), a[1] + t * (b[1] - a[1])];
+}
+/** The same for an open line: held to its ends. */
+export function linePoint(points, lengths, along) {
+    const total = lengths[points.length - 1];
+    const d = Math.min(Math.max(along, 0), total);
+    let lo = 0;
+    let hi = points.length - 2;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lengths[mid] <= d)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    const a = points[lo];
+    const b = points[Math.min(lo + 1, points.length - 1)];
+    const long = lengths[lo + 1] - lengths[lo];
+    const t = long > 0 ? (d - lengths[lo]) / long : 0;
+    return [a[0] + t * (b[0] - a[0]), a[1] + t * (b[1] - a[1])];
+}
+/** The radius of the circle through three points, or Infinity when they lie in a line. */
+function radius(a, b, c) {
+    const ab = Math.hypot(b[0] - a[0], b[1] - a[1]);
+    const bc = Math.hypot(c[0] - b[0], c[1] - b[1]);
+    const ca = Math.hypot(a[0] - c[0], a[1] - c[1]);
+    const cross = Math.abs((b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]));
+    return cross < 1e-9 ? Infinity : (ab * bc * ca) / (2 * cross);
+}
+/** The fastest speed a bend of radius `r` metres allows: `v² = r × (grip + downforce × v²)`, and the top speed where the downforce holds it at any speed. */
+export function cornerSpeed(r, pace = RACE_PACE) {
+    const room = 1 - pace.downforce * r;
+    if (!(r < Infinity) || room <= 0)
+        return pace.top;
+    return Math.min(pace.top, Math.sqrt((pace.grip * r) / room));
+}
+/** How hard the car can pull away at a speed: `launch` at rest, nothing at the top speed. */
+export const pullAt = (v, pace = RACE_PACE) => Math.max(0.4, pace.launch * (1 - (v / pace.top) ** 2));
+/**
+ * A plan's speeds round its lap (`circuitPlan`), from its line alone: the bends' radii give each sample's fastest speed, and two passes round (twice, so that the lap closes on itself) hold it to the engine and the
+ * brakes. The same plan always gives the same profile.
+ * @example
+ * ```ts
+ * import { circuitById, circuitPlan, paceProfile } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const pace = paceProfile(circuitPlan(circuitById("las-vegas")!));
+ * console.log(pace.lap > 90 && pace.lap < 105, Math.max(...pace.speed) * 3.6 > 300);
+ * // true true
+ * ```
+ */
+export function paceProfile(plan, pace = RACE_PACE) {
+    const metres = plan.lap.map(([x, y]) => [x / FT, y / FT]);
+    const lengths = ringLengths(metres);
+    const length = lengths[lengths.length - 1];
+    const n = Math.max(8, Math.round(length / pace.step));
+    const step = length / n;
+    const limit = new Float64Array(n);
+    for (let i = 0; i < n; i += 1) {
+        const s = i * step;
+        limit[i] = cornerSpeed(radius(ringPoint(metres, lengths, s - pace.reach), ringPoint(metres, lengths, s), ringPoint(metres, lengths, s + pace.reach)), pace);
+    }
+    const speed = Float64Array.from(limit);
+    for (let round = 0; round < 2; round += 1) {
+        for (let k = 1; k <= n; k += 1) {
+            const i = k % n;
+            const before = speed[(k - 1) % n];
+            speed[i] = Math.min(speed[i], Math.sqrt(before * before + 2 * pullAt(before, pace) * step));
+        }
+        for (let k = n - 1; k >= 0; k -= 1) {
+            const after = speed[(k + 1) % n];
+            speed[k] = Math.min(speed[k], Math.sqrt(after * after + 2 * pace.brake * step));
+        }
+    }
+    const time = new Float64Array(n + 1);
+    for (let i = 0; i < n; i += 1)
+        time[i + 1] = time[i] + (2 * step) / (speed[i] + speed[(i + 1) % n]);
+    return { step, length, speed, time, lap: time[n] };
+}
+/** The speed at `along` metres round the lap from the line's first point (wrapped), between the two samples either side. */
+export function speedAt(profile, along) {
+    const n = profile.speed.length;
+    const d = ((along % profile.length) + profile.length) % profile.length;
+    const i = Math.floor(d / profile.step) % n;
+    const t = d / profile.step - Math.floor(d / profile.step);
+    return profile.speed[i] + t * (profile.speed[(i + 1) % n] - profile.speed[i]);
+}

package/dist/circuits.race.d.ts

@@ -0,0 +1,80 @@
+import { type CircuitPlan } from "./circuits.ts";
+import { type PaceProfile } from "./circuits.pace.ts";
+import { type RaceDriver, type RaceTeam } from "./circuits.race.field.ts";
+import type { Circuit } from "./circuits.types.ts";
+/** What a race is made from: the circuit, and a seed, laps and cars of your own. */
+export interface RaceOptions {
+    /** The circuit's key: `las-vegas`. */
+    circuit: string;
+    /** The seed every choice of the race is drawn from: a whole number, 1 by default. Another seed is another race. */
+    seed?: number;
+    /** How many laps: by default a full race distance, the fewest laps that make 305 km (`raceLaps`). 1 to 200. */
+    laps?: number;
+    /** How many cars: 2 to 20, 20 by default. */
+    cars?: number;
+}
+/** A car of the race: its driver and team (made up) and where it started. */
+export interface RaceCar {
+    /** The driver's code in lower case: `hlv`. */
+    id: string;
+    driver: RaceDriver;
+    team: RaceTeam;
+    /** Its place on the grid, 1 for pole. */
+    grid: number;
+}
+/** A pit stop: the lap it ends, the time the car left the track and joined it again, and how long it stood still. */
+export interface RaceStop {
+    lap: number;
+    in: number;
+    out: number;
+    stop: number;
+}
+/** A race worked out: the cars, and each one's distance at every second, its laps, stops and finish. */
+export interface CircuitRace {
+    circuit: Circuit;
+    plan: CircuitPlan;
+    seed: number;
+    laps: number;
+    cars: readonly RaceCar[];
+    /** The lap's length along the drawn line, in metres, and how far round it from the line's first point the timing line (the finish) is. */
+    lapLength: number;
+    lineAlong: number;
+    /** The pit lane: where it leaves the lap and joins it again (metres round the lap from the line's first point), and its length in metres. */
+    pitLane: {
+        entry: number;
+        exit: number;
+        length: number;
+    };
+    /** The lap's speeds the cars run. */
+    pace: PaceProfile;
+    /** Seconds between two samples, the time the chequered flag fell and the time the race ends (every car home and slowed). */
+    sample: number;
+    flag: number;
+    duration: number;
+    /** Each car's race distance at every sample, in metres: 0 at the timing line, a lap is done at each `lapLength`. A car on the grid behind the line starts below 0. */
+    distance: readonly Float64Array[];
+    /** Each car's distance along the pit lane at every sample, in metres, or NaN while it is on the track. */
+    pit: readonly Float32Array[];
+    /** The time each car completed each lap, from the start. */
+    crossings: readonly (readonly number[])[];
+    stops: readonly (readonly RaceStop[])[];
+    /** The time a car took the chequered flag, or retired: `undefined` for neither. */
+    finish: readonly (number | undefined)[];
+    out: readonly (number | undefined)[];
+}
+/** The distance of a race: the fewest laps that make more than 305 km, as a Grand Prix's is set. */
+export declare const RACE_DISTANCE = 305000;
+/** The laps of a full race distance on a circuit: 50 at Las Vegas. */
+export declare const raceLaps: (circuit: Pick<Circuit, "length">) => number;
+/**
+ * A race on a circuit, worked out from a seed: made-up cars from the grid to the flag over a full race distance (50 laps of Las Vegas, about an hour and a half), with the gaps, overtakes, pit stops and retirements
+ * the model gives. The same options always give the same race; the last few asked for are kept.
+ * @example
+ * ```ts
+ * import { simulateRace } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const race = simulateRace({ circuit: "las-vegas", laps: 5, cars: 6, seed: 7 });
+ * console.log(race.laps, race.cars.length, race.flag > 5 * 90 && race.flag < 5 * 110);
+ * // 5 6 true
+ * ```
+ */
+export declare function simulateRace(options: RaceOptions): CircuitRace;

package/dist/circuits.race.dom.d.ts

@@ -0,0 +1,68 @@
+import { type RaceMoment } from "./circuits.race.moment.ts";
+import { type CircuitRace, type RaceOptions } from "./circuits.race.ts";
+import type { CircuitOptions } from "./circuits.types.ts";
+import { type KyogijoTurn } from "./turn.dom.ts";
+import type { TurnSettings } from "./turn.model.ts";
+/** The speeds the controls offer: real time, ten times and sixty times (a minute of the race a second). */
+export declare const RACE_SPEEDS: readonly number[];
+/** What a race's view is drawn from: the circuit's options and the race's. */
+export type RaceViewOptions = CircuitOptions & Omit<RaceOptions, "circuit">;
+/** How a race is shown and played. */
+export interface RaceViewSettings {
+    /** `flat` (the default) or `3d`: the circuit's 3D view, with the cars standing on it as discs that face the eye. */
+    view?: "flat" | "3d";
+    /** The 3D view's own settings (its viewpoint, its controls). */
+    turn?: TurnSettings;
+    /** 1 (the default), 10 or 60; any speed from 1 to 600 is allowed. */
+    speed?: number;
+    /** Seconds from the start to begin at: 0 (the grid) by default. */
+    start?: number;
+    /** Play at once. Ignored for a reader who prefers reduced motion, and while the page is hidden. */
+    autoplay?: boolean;
+    /** `auto` (the default) follows `prefers-reduced-motion`; `smooth` and `step` force one. */
+    motion?: "auto" | "smooth" | "step";
+    /** The timing board under the controls: on by default. */
+    board?: boolean;
+    /** Told when the reader plays, pauses, seeks or changes speed, and when the race ends: not at every frame. */
+    onChange?: (state: RaceState) => void;
+}
+/** What a race's view is doing. */
+export interface RaceState {
+    t: number;
+    duration: number;
+    playing: boolean;
+    ended: boolean;
+    speed: number;
+    motion: "smooth" | "step";
+}
+/** What `mountCircuitRace` gives back. */
+export interface KyogijoRace {
+    readonly race: CircuitRace;
+    /** The 3D view, when the race is on one. */
+    readonly turn: KyogijoTurn<CircuitOptions> | undefined;
+    state(): RaceState;
+    /** The race at the clock's time: the standings, the lap, the fastest lap. */
+    moment(): RaceMoment;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Go to a time, in seconds from the start. */
+    seek(t: number): void;
+    /** Go to the moment the leader next crosses the line. */
+    nextLap(): void;
+    setSpeed(speed: number): void;
+    /** Draw again with new options (the language, the theme): the clock and the race stay where they are. A new circuit, seed, laps or cars is a new race: mount it again. */
+    update(options: RaceViewOptions): void;
+    destroy(): void;
+}
+/**
+ * Mount a simulated race on a circuit: the circuit flat (or in 3D) with a dot for each made-up car, the race clock, play and pause, the speeds 1×, 10× and 60×, a slider over the whole race and the timing board, moving
+ * together. It does nothing until it is played, and nothing while it is paused, hidden or out of sight.
+ * @example
+ * ```ts no-run
+ * import { mountCircuitRace } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const race = mountCircuitRace(document.querySelector("#race")!, { circuit: "las-vegas" }, { speed: 10 });
+ * race.play();
+ * ```
+ */
+export declare function mountCircuitRace(host: HTMLElement, initial: RaceViewOptions, settings?: RaceViewSettings): KyogijoRace;