@johnmorrisdotca/kyogijo-stadiums 0.54.0 → 0.55.0

package/dist/circuits.race.dom.js

@@ -0,0 +1,434 @@
+// A simulated race in a page: the circuit flat or in 3D with a dot for each car, the race clock, the controls (play, the speeds 1×, 10× and 60×, and a slider over the whole race) and the timing board, all moving
+// together. Each animation frame moves only the dots that moved and writes the board and the clock only where their words changed (the board at most four times a second); no element is made while it plays.
+// Nothing runs until the reader plays it, and nothing runs while it is paused, the page is hidden or the race is out of sight. With reduced motion nothing plays by itself: play moves to the leader's next lap.
+import { CIRCUIT_MARKER, buildCircuitTurn } from "./circuits.turn.js";
+import { RACE_STYLE, carMarkup, carRadius, lapTime, raceBoard, raceClock, raceDrawing, raceStage, standingGap } from "./circuits.race.draw.js";
+import { raceAt } from "./circuits.race.moment.js";
+import { simulateRace } from "./circuits.race.js";
+import { RACE_WORDS } from "./circuits.race.words.js";
+import { num } from "./format.js";
+import { fill } from "./strings.core.js";
+import { mountTurn } from "./turn.dom.js";
+/** The speeds the controls offer: real time, ten times and sixty times (a minute of the race a second). */
+export const RACE_SPEEDS = Object.freeze([1, 10, 60]);
+const ICONS = { play: "M8 5v14l11-7z", pause: "M6 5h4v14H6zM14 5h4v14h-4z", next: "M6 5l8.5 7L6 19zM16 5h2v14h-2z" };
+const icon = (d) => `<svg viewBox="0 0 24 24" width="22" height="22" aria-hidden="true" focusable="false" fill="currentColor"><path d="${d}"/></svg>`;
+/** The plane of a car standing in a 3D view: a disc that faces the eye, its lower edge on the floor over its place. */
+const carPlane = (id, x, y, d, svg) => ({ id: `car-${id}`, kind: "player", o: [x - d / 2, y, d], u: [d, 0, 0], v: [0, 0, -d], svg, billboard: true, lean: true });
+/**
+ * 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 function mountCircuitRace(host, initial, settings = {}) {
+    const doc = host.ownerDocument;
+    let options = { ...initial };
+    let language = options.language === "ja" ? "ja" : "en";
+    const race = simulateRace(options);
+    const media = typeof matchMedia === "function" ? matchMedia("(prefers-reduced-motion: reduce)") : undefined;
+    const motionNow = () => (settings.motion === "smooth" ? "smooth" : settings.motion === "step" ? "step" : media?.matches === true ? "step" : "smooth");
+    const clampSpeed = (n) => Math.min(600, Math.max(1, n));
+    const state = { t: Math.min(Math.max(settings.start ?? 0, 0), race.duration), duration: race.duration, playing: false, ended: false, speed: clampSpeed(Number.isFinite(settings.speed) ? settings.speed : 1), motion: motionNow() };
+    const tell = () => settings.onChange?.({ ...state });
+    // ---- The parts: the stage, the clock, the controls, the note, the live region and the board. ----
+    const root = doc.createElement("div");
+    root.className = "ky-race";
+    const style = doc.createElement("style");
+    style.textContent = RACE_STYLE;
+    const stage = doc.createElement("div");
+    stage.className = "ky-race-view";
+    const clock = doc.createElement("div");
+    clock.className = "ky-race-clock";
+    const time = doc.createElement("span");
+    time.className = "ky-race-time";
+    const stageLine = doc.createElement("span");
+    stageLine.className = "ky-race-stage";
+    clock.append(time, stageLine);
+    const bar = doc.createElement("div");
+    bar.className = "ky-race-bar";
+    bar.setAttribute("role", "group");
+    const play = doc.createElement("button");
+    play.type = "button";
+    play.className = "ky-race-play";
+    const speeds = doc.createElement("span");
+    speeds.className = "ky-race-speeds";
+    speeds.setAttribute("role", "group");
+    const speedButtons = RACE_SPEEDS.map((n) => {
+        const b = doc.createElement("button");
+        b.type = "button";
+        b.dataset.speed = String(n);
+        b.textContent = `${n}×`;
+        speeds.append(b);
+        return b;
+    });
+    const range = doc.createElement("input");
+    range.type = "range";
+    range.className = "ky-race-position";
+    range.min = "0";
+    range.max = String(race.duration);
+    range.step = "1";
+    bar.append(play, speeds, range);
+    const note = doc.createElement("p");
+    note.className = "ky-race-note";
+    const live = doc.createElement("div");
+    live.className = "ky-race-live";
+    live.setAttribute("role", "status");
+    live.setAttribute("aria-live", "polite");
+    const boardWrap = doc.createElement("div");
+    boardWrap.className = "ky-race-board-wrap";
+    boardWrap.hidden = settings.board === false;
+    root.append(style, stage, clock, bar, note, live, boardWrap);
+    host.replaceChildren(root);
+    // ---- The drawing: flat, or the circuit's 3D view with the cars standing on it. ----
+    let turn;
+    let inner;
+    /** Each car's element (a group in the flat drawing, a plane's element in 3D), the text of its position, and what each was last given. */
+    let cars = new Map();
+    const planes = new Map();
+    let disc = 0;
+    let moment = raceAt(race, state.t);
+    const bindFlat = () => {
+        cars = new Map();
+        for (const el of stage.querySelectorAll(".ky-ci-car")) {
+            const id = el.getAttribute("data-car") ?? "";
+            cars.set(id, { el, text: el.querySelector("text"), r: Number(el.querySelector("circle")?.getAttribute("r") ?? 0), at: el.getAttribute("transform") ?? "", position: Number(el.querySelector("text")?.textContent ?? 0), status: el.getAttribute("data-status") ?? "" });
+        }
+    };
+    const drawFlat = () => {
+        stage.innerHTML = raceDrawing({ ...options, t: state.t }).svg;
+        bindFlat();
+    };
+    /** The model of the 3D view with a disc for each car at the clock's time. */
+    const withCars = (model) => {
+        const area = model.uprights.area ?? { x0: 0, y0: 0, x1: model.viewBox.w, y1: model.viewBox.h };
+        const k = Math.max(area.x1 - area.x0, area.y1 - area.y0) / 1000;
+        disc = 2 * carRadius(k) * (CIRCUIT_MARKER.size / 30);
+        const r = disc / 2;
+        planes.clear();
+        for (const line of [...moment.standings].sort((a, b) => a.index - b.index)) {
+            const svg = carMarkup({ ...line, at: [r, r] }, r * 0.9, language).replace(/ role="img"[^>]*?aria-label="[^"]*"/, "");
+            planes.set(line.car.id, carPlane(line.car.id, line.at[0], line.at[1], disc, svg));
+        }
+        return { ...model, planes: [...model.planes, ...planes.values()] };
+    };
+    const bindTurn = () => {
+        cars = new Map();
+        if (inner === undefined)
+            return;
+        for (const line of moment.standings) {
+            const el = inner.root.querySelector(`.ky-up[data-part="car-${line.car.id}"]`);
+            cars.set(line.car.id, { el, text: el?.querySelector("text") ?? null, r: (disc / 2) * 0.9, at: "", position: line.position, status: line.status });
+        }
+    };
+    const mountView = () => {
+        if (settings.view === "3d") {
+            const holder = doc.createElement("div");
+            stage.replaceChildren(holder);
+            turn = mountTurn(holder, options, settings.turn ?? {}, buildCircuitTurn, false, (lent) => {
+                inner = lent;
+            });
+            if (inner !== undefined) {
+                inner.setDecorate(withCars, bindTurn);
+                return;
+            }
+            // Where the browser cannot draw the 3D view, the race is drawn flat.
+            turn.destroy();
+            turn = undefined;
+        }
+        drawFlat();
+    };
+    // ---- Painting a moment: the dots that moved, and (at most four times a second, or at once when asked) the clock and the board. ----
+    let boardRows = [];
+    const buildBoard = () => {
+        boardWrap.innerHTML = raceBoard(moment, language);
+        boardRows = [...boardWrap.querySelectorAll("tbody tr")].map((row) => ({
+            row,
+            cells: new Map([...row.querySelectorAll("[data-col]")].map((cell) => [cell.dataset.col ?? "", cell])),
+            swatch: row.querySelector(".ky-race-swatch"),
+            code: row.querySelector(".ky-race-code"),
+            name: row.querySelector(".ky-race-name"),
+        }));
+    };
+    const setText = (el, text) => {
+        if (el !== null && el !== undefined && el.textContent !== text)
+            el.textContent = text;
+    };
+    const setAttr = (el, name, value) => {
+        if (el === null || el === undefined || el.getAttribute(name) === value)
+            return;
+        if (value === null)
+            el.removeAttribute(name);
+        else
+            el.setAttribute(name, value);
+    };
+    const writeBoard = () => {
+        const w = RACE_WORDS[language];
+        setText(time, raceClock(state.t));
+        setAttr(time, "aria-label", fill(w.elapsed, { time: raceClock(state.t) }));
+        setText(stageLine, raceStage(moment, language));
+        const at = String(Math.round(state.t));
+        if (range.value !== at)
+            range.value = at;
+        setAttr(range, "aria-valuetext", fill(w.positionValue, { time: raceClock(state.t), total: raceClock(race.duration) }));
+        moment.standings.forEach((line, i) => {
+            const r = boardRows[i];
+            if (r === undefined)
+                return;
+            setAttr(r.row, "data-car", line.car.id);
+            setAttr(r.row, "data-status", line.status);
+            setText(r.cells.get("pos"), String(line.position));
+            if (r.swatch !== null && r.swatch.style.background !== line.car.team.colour)
+                r.swatch.style.background = line.car.team.colour;
+            setText(r.code, line.car.driver.code);
+            setText(r.name, line.car.driver.name[language]);
+            setText(r.cells.get("team"), line.car.team.name[language]);
+            setText(r.cells.get("gap"), line.status === "pit" ? w.board.pit : standingGap(line, language, "gap"));
+            setText(r.cells.get("interval"), standingGap(line, language, "interval"));
+            setText(r.cells.get("last"), line.last === undefined ? "" : lapTime(line.last));
+            setText(r.cells.get("best"), line.best === undefined ? "" : lapTime(line.best));
+            const fastest = moment.fastest?.index === line.index;
+            setAttr(r.cells.get("best"), "data-fastest", fastest ? "true" : null);
+            setAttr(r.cells.get("best"), "title", fastest ? w.board.fastest : null);
+            setText(r.cells.get("stops"), String(line.stops));
+        });
+    };
+    let boardAt = -Infinity;
+    let leader = moment.standings[0]?.car.id;
+    let flagSaid = moment.flag;
+    const paint = (now, crossed) => {
+        moment = raceAt(race, state.t);
+        const w = RACE_WORDS[language];
+        let moved = false;
+        for (const line of moment.standings) {
+            const car = cars.get(line.car.id);
+            if (car === undefined)
+                continue;
+            if (inner !== undefined) {
+                const plane = planes.get(line.car.id);
+                if (plane !== undefined && (plane.o[0] !== line.at[0] - disc / 2 || plane.o[1] !== line.at[1])) {
+                    plane.o = [line.at[0] - disc / 2, line.at[1], disc];
+                    moved = true;
+                }
+            }
+            else {
+                const at = `translate(${num(line.at[0])} ${num(line.at[1])})`;
+                if (car.at !== at) {
+                    car.at = at;
+                    car.el?.setAttribute("transform", at);
+                }
+            }
+            if (car.position !== line.position) {
+                car.position = line.position;
+                setText(car.text, String(line.position));
+                setAttr(car.text, "font-size", num(car.r * (line.position >= 10 ? 1 : 1.15)));
+                if (inner === undefined)
+                    setAttr(car.el, "aria-label", fill(w.car, { position: line.position, name: line.car.driver.name[language], team: line.car.team.name[language] }));
+            }
+            if (car.status !== line.status) {
+                car.status = line.status;
+                setAttr(car.el, "data-status", line.status);
+            }
+        }
+        if (moved)
+            inner?.repaint();
+        // What is said aloud: a new leader, and the flag, only as the race plays forward.
+        if (crossed) {
+            const first = moment.standings[0];
+            if (moment.flag && !flagSaid && first !== undefined)
+                setText(live, fill(w.wins, { name: first.car.driver.name[language] }));
+            else if (first !== undefined && first.car.id !== leader && state.t > 0)
+                setText(live, fill(w.leads, { name: first.car.driver.name[language], lap: moment.lap }));
+        }
+        leader = moment.standings[0]?.car.id;
+        flagSaid = moment.flag;
+        if (now === undefined || now - boardAt >= 250) {
+            boardAt = now ?? -Infinity;
+            writeBoard();
+        }
+    };
+    // ---- The controls. ----
+    const label = () => {
+        const w = RACE_WORDS[language];
+        bar.setAttribute("aria-label", w.group);
+        speeds.setAttribute("aria-label", w.speed);
+        const step = state.motion === "step";
+        const name = step ? w.nextLap : state.playing ? w.pause : w.play;
+        if (play.getAttribute("aria-label") !== name) {
+            play.setAttribute("aria-label", name);
+            play.title = name;
+            play.innerHTML = icon(step ? ICONS.next : state.playing ? ICONS.pause : ICONS.play);
+        }
+        speeds.hidden = step;
+        for (const b of speedButtons) {
+            const n = Number(b.dataset.speed);
+            b.setAttribute("aria-label", `${w.speed} ${fill(w.speedValue, { speed: n })}`);
+            b.setAttribute("aria-pressed", String(n === state.speed));
+        }
+        range.setAttribute("aria-label", w.position);
+        setText(note, w.simulated);
+        root.dataset.state = state.ended ? "ended" : state.playing ? "playing" : "paused";
+        root.dataset.motion = state.motion;
+    };
+    // ---- The clock on the page: animation frames while playing and in sight (the 3D view's own, so that its turn and the race share one), and nothing else. ----
+    let frameId = 0;
+    let last = 0;
+    let onScreen = true;
+    const request = (callback) => (inner !== undefined ? inner.requestFrame(callback) : requestAnimationFrame(callback));
+    const cancel = (id) => (inner !== undefined ? inner.cancelFrame(id) : cancelAnimationFrame(id));
+    const stopFrames = () => {
+        if (frameId !== 0)
+            cancel(frameId);
+        frameId = 0;
+    };
+    const want = () => {
+        if (frameId !== 0 || !onScreen || !state.playing)
+            return;
+        last = performance.now();
+        frameId = request(frame);
+    };
+    function frame(now) {
+        frameId = 0;
+        if (!state.playing || !onScreen)
+            return;
+        const dt = Math.min(0.25, Math.max(0, (now - last) / 1000));
+        last = now;
+        state.t = Math.min(race.duration, state.t + dt * state.speed);
+        if (state.t >= race.duration) {
+            state.playing = false;
+            state.ended = true;
+            paint(undefined, true);
+            label();
+            tell();
+            return;
+        }
+        paint(now, true);
+        frameId = request(frame);
+    }
+    const api = {
+        race,
+        get turn() {
+            return turn;
+        },
+        state: () => ({ ...state }),
+        moment: () => moment,
+        play() {
+            if (state.motion === "step")
+                return api.nextLap();
+            if (state.playing)
+                return;
+            if (state.t >= race.duration)
+                state.t = 0;
+            state.playing = true;
+            state.ended = false;
+            label();
+            tell();
+            want();
+        },
+        pause() {
+            if (!state.playing)
+                return;
+            state.playing = false;
+            stopFrames();
+            label();
+            paint(undefined, false);
+            tell();
+        },
+        toggle() {
+            if (state.playing)
+                api.pause();
+            else
+                api.play();
+        },
+        seek(t) {
+            if (!Number.isFinite(t))
+                return;
+            state.t = Math.min(Math.max(t, 0), race.duration);
+            state.ended = state.t >= race.duration;
+            paint(undefined, false);
+            label();
+            tell();
+        },
+        nextLap() {
+            const first = moment.standings[0];
+            const next = first === undefined ? undefined : race.crossings[first.index].find((at) => at > state.t + 1e-6);
+            api.pause();
+            api.seek(next ?? race.duration);
+        },
+        setSpeed(speed) {
+            if (!Number.isFinite(speed))
+                return;
+            const next = clampSpeed(speed);
+            if (next === state.speed)
+                return;
+            state.speed = next;
+            label();
+            tell();
+        },
+        update(next) {
+            options = { ...next, circuit: options.circuit, seed: options.seed, laps: options.laps, cars: options.cars };
+            language = options.language === "ja" ? "ja" : "en";
+            if (turn !== undefined)
+                turn.update(options);
+            else
+                drawFlat();
+            buildBoard();
+            label();
+            paint(undefined, false);
+        },
+        destroy() {
+            stopFrames();
+            state.playing = false;
+            seen?.disconnect();
+            doc.removeEventListener("visibilitychange", hidden);
+            if (typeof media?.removeEventListener === "function")
+                media.removeEventListener("change", motionChanged);
+            turn?.destroy();
+            turn = undefined;
+            inner = undefined;
+            cars = new Map();
+            host.replaceChildren();
+        },
+    };
+    play.addEventListener("click", () => api.toggle());
+    for (const b of speedButtons)
+        b.addEventListener("click", () => api.setSpeed(Number(b.dataset.speed)));
+    range.addEventListener("input", () => api.seek(Number(range.value)));
+    // Scrolled out of sight, the clock holds (no frame is asked for) and goes on when it is back.
+    let seen;
+    if (typeof IntersectionObserver === "function") {
+        seen = new IntersectionObserver((entries) => {
+            onScreen = entries[entries.length - 1]?.isIntersecting !== false;
+            if (onScreen)
+                want();
+            else
+                stopFrames();
+        });
+        seen.observe(stage);
+    }
+    // A page that is hidden does no work: the race stops, and the reader starts it again.
+    const hidden = () => {
+        if (doc.visibilityState === "hidden")
+            api.pause();
+    };
+    doc.addEventListener("visibilitychange", hidden);
+    const motionChanged = () => {
+        state.motion = motionNow();
+        if (state.motion === "step")
+            api.pause();
+        label();
+    };
+    if ((settings.motion === undefined || settings.motion === "auto") && typeof media?.addEventListener === "function")
+        media.addEventListener("change", motionChanged);
+    mountView();
+    buildBoard();
+    label();
+    paint(undefined, false);
+    if (settings.autoplay === true && state.motion === "smooth" && doc.visibilityState !== "hidden")
+        api.play();
+    return api;
+}

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

@@ -0,0 +1,59 @@
+import type { CircuitDrawing } from "./circuits.draw.ts";
+import { type RaceMoment, type RaceStanding } from "./circuits.race.moment.ts";
+import { type CircuitRace, type RaceOptions } from "./circuits.race.ts";
+import type { CircuitOptions } from "./circuits.types.ts";
+import type { Language } from "./types.ts";
+/** A race clock: `23:45` or `1:23:45`. */
+export declare function raceClock(seconds: number): string;
+/** A lap's time: `1:36.512`. */
+export declare function lapTime(seconds: number): string;
+/** A gap: `+1.234`, `+1:02.345` past a minute, or the laps down in the words of the language. */
+export declare function gapText(seconds: number | undefined, laps: number, language: Language): string;
+/** The race clock's line at a moment: the lap, the final lap, the flag or the grid. */
+export declare function raceStage(moment: RaceMoment, language: Language): string;
+/** What a line of the board shows in its gap column: the leader, a gap, laps down, the pit lane or out. */
+export declare function standingGap(line: RaceStanding, language: Language, of?: "gap" | "interval"): string;
+/** The size of a car's dot on a drawing whose type and marks are sized by `k` (a thousandth of its longer side). */
+export declare const carRadius: (k: number) => number;
+/** The markup of one car's dot: a circle in the team's colour, edged in the ground's, with its position on it, laid at the origin (the page moves it with `transform`). */
+export declare function carMarkup(line: RaceStanding, r: number, language: Language): string;
+/** The cars of a moment as one group, the last car drawn first so that the leader lies on top. */
+export declare function carsMarkup(moment: RaceMoment, r: number, language: Language): string;
+/** What a race's drawing is made from: the circuit's options, the race's, and the moment. */
+export interface RaceDrawOptions extends CircuitOptions, Omit<RaceOptions, "circuit"> {
+    /** Seconds from the start: 0 (the grid) by default. */
+    t?: number;
+}
+/** A race's drawing at a moment, and what it was made from. */
+export interface RaceDrawing extends CircuitDrawing {
+    race: CircuitRace;
+    moment: RaceMoment;
+}
+/** The race, the drawing of its circuit and the moment, with the cars on it. */
+export declare function raceDrawing(options: RaceDrawOptions): RaceDrawing;
+/**
+ * A simulated race on a circuit at a moment, as one SVG string: the circuit's drawing with a dot for each made-up car where the race has it then, in its team's colour, with the position it holds written on it.
+ * @example
+ * ```ts
+ * import { drawRace } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const svg = drawRace({ circuit: "las-vegas", laps: 3, cars: 6, t: 120 });
+ * console.log(svg.match(/class="ky-ci-car"/g)!.length, svg.includes("simulation"));
+ * // 6 true
+ * ```
+ */
+export declare function drawRace(options: RaceDrawOptions): string;
+/**
+ * The timing board at a moment, as a table: position, driver and team, the gap to the leader and to the car in front, the last and best laps and the pit stops, the fastest lap marked. The colours of the teams are
+ * swatches beside their names, never the only way a car is told.
+ * @example
+ * ```ts
+ * import { raceAt, raceBoard, simulateRace } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const race = simulateRace({ circuit: "las-vegas", laps: 3, cars: 4 });
+ * const table = raceBoard(raceAt(race, 200));
+ * console.log(table.startsWith("<table"), (table.match(/<tr data-car/g) ?? []).length);
+ * // true 4
+ * ```
+ */
+export declare function raceBoard(moment: RaceMoment, language?: Language): string;
+/** The rules of a race: the cars on the drawing, the clock, the controls and the board. Scoped to `.ky-race` and the drawing's cars, in the page's own colours. */
+export declare const RACE_STYLE: string;

package/dist/circuits.race.draw.js

@@ -0,0 +1,153 @@
+// A simulated race drawn: the circuit's drawing with a dot for each car where it is at a moment (in its team's colour, with the position it holds written on it), the race clock's words, and the timing board as a
+// table. Pure: the same race, moment and language always give the same strings. The page that moves them is `circuits.race.dom.ts`.
+import { circuitDrawing } from "./circuits.draw.js";
+import { raceAt } from "./circuits.race.moment.js";
+import { simulateRace } from "./circuits.race.js";
+import { RACE_WORDS } from "./circuits.race.words.js";
+import { el, esc, num } from "./format.js";
+import { fill } from "./strings.core.js";
+/** A race clock: `23:45` or `1:23:45`. */
+export function raceClock(seconds) {
+    const whole = Math.max(0, Math.floor(Number.isFinite(seconds) ? seconds : 0));
+    const s = String(whole % 60).padStart(2, "0");
+    const m = Math.floor(whole / 60);
+    return m < 60 ? `${m}:${s}` : `${Math.floor(m / 60)}:${String(m % 60).padStart(2, "0")}:${s}`;
+}
+/** A lap's time: `1:36.512`. */
+export function lapTime(seconds) {
+    const thousandths = Math.round(Math.max(0, seconds) * 1000);
+    const m = Math.floor(thousandths / 60000);
+    const rest = thousandths - m * 60000;
+    return `${m}:${String(Math.floor(rest / 1000)).padStart(2, "0")}.${String(rest % 1000).padStart(3, "0")}`;
+}
+/** A gap: `+1.234`, `+1:02.345` past a minute, or the laps down in the words of the language. */
+export function gapText(seconds, laps, language) {
+    const w = RACE_WORDS[language].board;
+    if (laps >= 1)
+        return laps === 1 ? w.lapDown : fill(w.lapsDown, { n: laps });
+    if (seconds === undefined)
+        return "";
+    return seconds >= 60 ? `+${lapTime(seconds)}` : `+${seconds.toFixed(3)}`;
+}
+/** The race clock's line at a moment: the lap, the final lap, the flag or the grid. */
+export function raceStage(moment, language) {
+    const w = RACE_WORDS[language];
+    if (moment.flag)
+        return w.flag;
+    if (moment.t <= 0)
+        return w.grid;
+    if (moment.lap === moment.laps && moment.laps > 1)
+        return `${fill(w.lap, { lap: moment.lap, laps: moment.laps })} · ${w.finalLap}`;
+    return fill(w.lap, { lap: moment.lap, laps: moment.laps });
+}
+/** What a line of the board shows in its gap column: the leader, a gap, laps down, the pit lane or out. */
+export function standingGap(line, language, of = "gap") {
+    const w = RACE_WORDS[language].board;
+    if (line.status === "out")
+        return w.out;
+    if (line.position === 1)
+        return of === "gap" ? w.leader : "";
+    return of === "gap" ? gapText(line.gap, line.lapsDown, language) : gapText(line.interval, line.intervalLaps, language);
+}
+/** The size of a car's dot on a drawing whose type and marks are sized by `k` (a thousandth of its longer side). */
+export const carRadius = (k) => 11 * k;
+/** The markup of one car's dot: a circle in the team's colour, edged in the ground's, with its position on it, laid at the origin (the page moves it with `transform`). */
+export function carMarkup(line, r, language) {
+    const w = RACE_WORDS[language];
+    const label = fill(w.car, { position: line.position, name: line.car.driver.name[language], team: line.car.team.name[language] });
+    const inner = el("circle", { class: "ky-ci-car-dot", r: num(r), fill: line.car.team.colour, "stroke-width": num(r * 0.2) }) +
+        el("text", { class: "ky-ci-car-n", y: num(r * 0.4), "font-size": num(r * (line.position >= 10 ? 1 : 1.15)), fill: line.car.team.ink }, String(line.position));
+    return el("g", { class: "ky-ci-car", "data-car": line.car.id, "data-status": line.status, transform: `translate(${num(line.at[0])} ${num(line.at[1])})`, role: "img", "aria-label": label }, inner);
+}
+/** The cars of a moment as one group, the last car drawn first so that the leader lies on top. */
+export function carsMarkup(moment, r, language) {
+    const lines = [...moment.standings].sort((a, b) => a.index - b.index);
+    return el("g", { class: "ky-ci-cars" }, lines.map((line) => carMarkup(line, r, language)).join(""));
+}
+/** The race, the drawing of its circuit and the moment, with the cars on it. */
+export function raceDrawing(options) {
+    const language = options.language === "ja" ? "ja" : "en";
+    const race = simulateRace(options);
+    const moment = raceAt(race, options.t ?? 0);
+    const drawn = circuitDrawing(options);
+    const w = RACE_WORDS[language];
+    const extra = ` ${fill(w.description, { cars: race.cars.length, laps: race.laps })}`;
+    const description = `${drawn.description}${language === "ja" ? extra.trim() : extra}`;
+    const svg = drawn.svg.replace(/<desc id="([^"]+)">[^<]*<\/desc>/, (_, id) => `<desc id="${id}">${esc(description)}</desc>`).replace(/<\/svg>$/, `${carsMarkup(moment, carRadius(drawn.k), language)}</svg>`);
+    return { ...drawn, svg, description, race, moment };
+}
+/**
+ * A simulated race on a circuit at a moment, as one SVG string: the circuit's drawing with a dot for each made-up car where the race has it then, in its team's colour, with the position it holds written on it.
+ * @example
+ * ```ts
+ * import { drawRace } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const svg = drawRace({ circuit: "las-vegas", laps: 3, cars: 6, t: 120 });
+ * console.log(svg.match(/class="ky-ci-car"/g)!.length, svg.includes("simulation"));
+ * // 6 true
+ * ```
+ */
+export function drawRace(options) {
+    return raceDrawing(options).svg;
+}
+/**
+ * The timing board at a moment, as a table: position, driver and team, the gap to the leader and to the car in front, the last and best laps and the pit stops, the fastest lap marked. The colours of the teams are
+ * swatches beside their names, never the only way a car is told.
+ * @example
+ * ```ts
+ * import { raceAt, raceBoard, simulateRace } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const race = simulateRace({ circuit: "las-vegas", laps: 3, cars: 4 });
+ * const table = raceBoard(raceAt(race, 200));
+ * console.log(table.startsWith("<table"), (table.match(/<tr data-car/g) ?? []).length);
+ * // true 4
+ * ```
+ */
+export function raceBoard(moment, language = "en") {
+    const w = RACE_WORDS[language === "ja" ? "ja" : "en"].board;
+    const lang = language === "ja" ? "ja" : "en";
+    const heads = [w.position, w.driver, w.team, w.gap, w.interval, w.last, w.best, w.stops];
+    const cols = ["pos", "driver", "team", "gap", "interval", "last", "best", "stops"];
+    const head = `<thead><tr>${heads.map((h, i) => `<th scope="col" data-col="${cols[i]}">${esc(h)}</th>`).join("")}</tr></thead>`;
+    const rows = moment.standings.map((line) => {
+        const fastest = moment.fastest?.index === line.index;
+        const cells = [
+            `<th scope="row" data-col="pos">${line.position}</th>`,
+            `<td data-col="driver"><span class="ky-race-swatch" style="background:${esc(line.car.team.colour)}"></span><span class="ky-race-code">${esc(line.car.driver.code)}</span> <span class="ky-race-name">${esc(line.car.driver.name[lang])}</span></td>`,
+            `<td data-col="team">${esc(line.car.team.name[lang])}</td>`,
+            `<td data-col="gap">${esc(line.status === "pit" ? w.pit : standingGap(line, lang, "gap"))}</td>`,
+            `<td data-col="interval">${esc(standingGap(line, lang, "interval"))}</td>`,
+            `<td data-col="last">${line.last === undefined ? "" : lapTime(line.last)}</td>`,
+            `<td data-col="best"${fastest ? ` data-fastest="true" title="${esc(w.fastest)}"` : ""}>${line.best === undefined ? "" : lapTime(line.best)}</td>`,
+            `<td data-col="stops">${line.stops}</td>`,
+        ];
+        return `<tr data-car="${esc(line.car.id)}" data-status="${line.status}">${cells.join("")}</tr>`;
+    });
+    return `<table class="ky-race-board"><caption>${esc(w.caption)}</caption>${head}<tbody>${rows.join("")}</tbody></table>`;
+}
+/** The rules of a race: the cars on the drawing, the clock, the controls and the board. Scoped to `.ky-race` and the drawing's cars, in the page's own colours. */
+export const RACE_STYLE = `
+.ky-circuit .ky-ci-car-dot,.ky-turn .ky-ci-car-dot{stroke:var(--ky-ci-ground,#fff)}
+.ky-circuit .ky-ci-car-n,.ky-turn .ky-ci-car-n{font-family:var(--ky-font,system-ui,sans-serif);font-weight:800;text-anchor:middle;font-variant-numeric:tabular-nums}
+.ky-circuit .ky-ci-car[data-status=out]{opacity:.45}
+.ky-race{display:block;color:inherit}
+.ky-race .ky-race-bar{display:flex;flex-wrap:wrap;align-items:center;gap:.5rem;margin-top:.5rem}
+.ky-race .ky-race-bar button{box-sizing:border-box;min-width:44px;min-height:44px;margin:0;padding:0 .7rem;border:1px solid currentColor;border-radius:8px;background:transparent;color:inherit;font:inherit;font-weight:700;cursor:pointer}
+.ky-race .ky-race-bar button[aria-pressed=true]{background:color-mix(in srgb,currentColor 22%,transparent)}
+.ky-race .ky-race-bar button:focus-visible,.ky-race .ky-race-bar input:focus-visible{outline:2px solid currentColor;outline-offset:2px}
+.ky-race .ky-race-speeds{display:inline-flex;gap:.25rem}
+.ky-race .ky-race-bar input[type=range]{flex:1 1 160px;min-width:120px;min-height:44px;margin:0;accent-color:currentColor}
+.ky-race .ky-race-clock{display:flex;flex-wrap:wrap;align-items:baseline;gap:.25rem .75rem;margin-top:.5rem;font-variant-numeric:tabular-nums}
+.ky-race .ky-race-time{font-size:1.5rem;font-weight:800}
+.ky-race .ky-race-stage{font-weight:700}
+.ky-race .ky-race-note{margin:.25rem 0 0;font-size:.85rem;opacity:.8}
+.ky-race .ky-race-board-wrap{overflow-x:auto;margin-top:.5rem}
+.ky-race .ky-race-board{border-collapse:collapse;width:100%;font-size:.85rem;font-variant-numeric:tabular-nums}
+.ky-race .ky-race-board caption{text-align:start;font-weight:700;padding:.25rem 0}
+.ky-race .ky-race-board th,.ky-race .ky-race-board td{padding:.2rem .45rem;border-bottom:1px solid color-mix(in srgb,currentColor 18%,transparent);text-align:start;white-space:nowrap}
+.ky-race .ky-race-board td[data-col=gap],.ky-race .ky-race-board td[data-col=interval],.ky-race .ky-race-board td[data-col=last],.ky-race .ky-race-board td[data-col=best],.ky-race .ky-race-board td[data-col=stops]{text-align:end}
+.ky-race .ky-race-board tr[data-status=out]{opacity:.6}
+.ky-race .ky-race-board td[data-fastest=true]{font-weight:800;text-decoration:underline}
+.ky-race .ky-race-swatch{display:inline-block;width:.7em;height:.7em;margin-inline-end:.35em;border-radius:50%;border:1px solid color-mix(in srgb,currentColor 40%,transparent);vertical-align:baseline}
+.ky-race .ky-race-code{font-weight:800}
+.ky-race .ky-race-live{position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0}
+@media (max-width:560px){.ky-race .ky-race-board [data-col=team],.ky-race .ky-race-board [data-col=best],.ky-race .ky-race-board [data-col=last],.ky-race .ky-race-board .ky-race-name{display:none}}
+`.trim();