@johnmorrisdotca/kyogijo-stadiums 0.55.0 → 0.57.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.57.0] - 2026-11-03
+
+### Changed
+
+- **The wheel zooms the 3D view** (KAZOKU-UI-45). The wheel over the view now zooms it, as a map does (up in, down out, about the view's middle, which is where the pinch and the buttons zoom; a notch about as much as the + key); before, the plain wheel was the page's and tipped a focused view. A trackpad's pinch (Ctrl or Command and the wheel) still zooms. Shift and the wheel, or a sideways swipe, turns the view. The wheel never tips it: a drag, the arrows and the buttons do. With the pointer anywhere else the wheel scrolls the page, and a wheel that starts while the zoom is already at its end that way scrolls the page too, so a page of views is never trapped; the steps of a turn that reaches the end part-way through stay with the view, so the page does not jump.
+
+
+## [0.56.0] - 2026-11-03
+
+### Added
+
+- **Bring your own race feed (KYOGIJO-STADIUMS-38)** ([the race feed](./docs/race-feed.md), [where to find a feed](./docs/where-to-find-a-feed.md)): a race on a circuit plays from a feed the reader chooses instead of the simulation. kyogijo's open race timeline (`kind: "kyogijo-race"`: cars, lap crossings, pit stops, retirements, location samples, `live`) is read strictly by `readRaceFeed` and played by `raceFromFeed` (between the times a feed gives, the cars run at the lap's own speeds; location samples are laid on the circuit's line by how far round the lap they are); `openF1Feed` adapts OpenF1-style lap, pit and driver rows. `loadRaceFeed` reads an address with the reader's own browser (no server or proxy of ours, nothing kept) and says in words when a source will not let a page read it (CORS), refuses (403) or is busy (429); `feedFromText` reads pasted text or a file; `followRaceFeed` asks a live race again every 15 seconds, only while the page is visible, and stops when it is over or refused; `mountCircuitRace` takes `race` and `replace`. `raceToFeed` writes any race in the format: the demo's **Sample feed (made up)** (`examples/races/las-vegas-sample.json`) is the simulated race so written, listed first among the suggestions of `examples/feeds/where-to-find.json` (OpenF1, Jolpica F1), which the circuits page shows beside the address field with what each gives, how to find a race and its docs and terms. Every test runs on made-up stubs; none makes a real request.
+
+### Fixed
+
+- A 3D view that goes asks for no frame after it: the measure of the display a view takes in its first moments is stopped on destroy (a view destroyed then asked for one more frame, seen in WebKit when Play a game stopped on another surface), and the frame the auto-turn, a replay and a race share is cleared, a request made in the same tick included (`src/turn.frames.ts`, with unit tests).
+- The docs of the race and of the race feed link straight into the live demo (`circuits.html?race=1`, `circuits.html?race=1&feed=sample`).
+
 ## [0.55.0] - 2026-11-03
 
 ### Added

package/README.md

@@ -255,6 +255,7 @@ console.log(svg.startsWith("<svg"), svg.includes("USA 3, Canada 2"));
 - **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, 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).
+- **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).
 - **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).

package/catalogue.json

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

package/dist/circuits-entry.d.ts

@@ -23,3 +23,9 @@ export { RACE_CARS_MAX, RACE_DRIVERS, RACE_TEAMS } from "./circuits.race.field.t
 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";
+export { FEED_LIMITS, raceFromFeed, raceToFeed, readRaceFeed } from "./circuits.feed.ts";
+export type { FeedResult, RaceFeed, RaceFeedCar } from "./circuits.feed.ts";
+export { looksLikeOpenF1Laps, openF1Feed } from "./circuits.feed.openf1.ts";
+export type { OpenF1Driver, OpenF1Lap, OpenF1Location, OpenF1Pit, OpenF1Rows } from "./circuits.feed.openf1.ts";
+export { FEED_MAX_BYTES, FOLLOW_EVERY, RaceFeedError, feedAddress, feedFromText, followRaceFeed, loadRaceFeed, openF1Siblings } from "./circuits.feed.fetch.ts";
+export type { FeedFollower, FeedProblemKind } from "./circuits.feed.fetch.ts";

package/dist/circuits-entry.js

@@ -15,3 +15,7 @@ export { RACE_STYLE, drawRace, gapText, lapTime, raceBoard, raceClock, raceDrawi
 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";
+// A race from a feed: the open race timeline, an adapter for OpenF1-style rows, and reading a feed the user names (a URL, pasted text, a file), once or while a race goes on.
+export { FEED_LIMITS, raceFromFeed, raceToFeed, readRaceFeed } from "./circuits.feed.js";
+export { looksLikeOpenF1Laps, openF1Feed } from "./circuits.feed.openf1.js";
+export { FEED_MAX_BYTES, FOLLOW_EVERY, RaceFeedError, feedAddress, feedFromText, followRaceFeed, loadRaceFeed, openF1Siblings } from "./circuits.feed.fetch.js";

package/dist/circuits.feed.d.ts

@@ -0,0 +1,101 @@
+import type { CircuitRace } from "./circuits.race.ts";
+/** A car of a feed: an id the rest of the feed uses, and what the board shows of it. Everything but `id` is optional. */
+export interface RaceFeedCar {
+    id: string;
+    /** A short code, as a timing board shows one: three letters. Missing, the id is used. */
+    code?: string;
+    name?: string;
+    team?: string;
+    /** The team's colour, `#rrggbb`. Missing, one of the package's is used. */
+    colour?: string;
+    /** Its place on the grid, 1 for pole. Missing, the order of `cars`. */
+    grid?: number;
+}
+/** kyogijo's open race timeline: any feed, file or program can write it. Times are seconds from the start (the lights going out). */
+export interface RaceFeed {
+    kind: "kyogijo-race";
+    version: 1;
+    /** The circuit's key (`las-vegas`). A page may draw a feed on another circuit; the lap's shape is then the page's. */
+    circuit?: string;
+    /** The laps of the race, if the feed knows them; else the most any car has done. */
+    laps?: number;
+    /** A line about where the race comes from, shown with it. */
+    title?: string;
+    cars: RaceFeedCar[];
+    /** When each car completed each lap: lap 1 is the first time it crossed the line after the start. */
+    crossings: {
+        car: string;
+        lap: number;
+        t: number;
+    }[];
+    /** When a car left the track for the pit lane and joined it again, and how long it stood still. */
+    pits?: {
+        car: string;
+        in: number;
+        out: number;
+        stop?: number;
+    }[];
+    /** When a car retired. */
+    out?: {
+        car: string;
+        t: number;
+    }[];
+    /** Where a car was, in the feed's own frame (any unit, any way up): laid on the circuit's line by how far round the lap it is. */
+    positions?: {
+        car: string;
+        t: number;
+        x: number;
+        y: number;
+    }[];
+    /** True while the race is going on: the last lap seen is not the end. */
+    live?: boolean;
+}
+/** What reading a feed gives: the feed, or why it is not one, in words. */
+export type FeedResult = {
+    ok: true;
+    feed: RaceFeed;
+} | {
+    ok: false;
+    error: string;
+};
+/** The most a feed may hold: cars, and rows of each list. */
+export declare const FEED_LIMITS: Readonly<{
+    cars: 40;
+    rows: 200000;
+    laps: 200;
+}>;
+/**
+ * Read a feed strictly: anything that is not the open race timeline is refused with a sentence that says why, and anything a feed carries that the format does not name is left behind. Text is kept as text (never markup).
+ * @example
+ * ```ts
+ * import { readRaceFeed } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const read = readRaceFeed({ kind: "kyogijo-race", version: 1, cars: [{ id: "a" }], crossings: [{ car: "a", lap: 1, t: 101 }] });
+ * console.log(read.ok, readRaceFeed({ kind: "something" }).ok);
+ * // true false
+ * ```
+ */
+export declare function readRaceFeed(input: unknown): FeedResult;
+/**
+ * A feed as a race (`CircuitRace`): the same shape a simulation gives, so that `raceAt`, `drawRace`, `raceBoard` and `mountCircuitRace` play it. The circuit is the feed's, or the one named here (a page draws a feed on the
+ * circuit it shows). Between the moments a feed gives, the cars run at the lap's own speeds.
+ * @example
+ * ```ts
+ * import { raceAt, raceFromFeed } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const race = raceFromFeed({ kind: "kyogijo-race", version: 1, cars: [{ id: "a", code: "AAA" }, { id: "b", code: "BBB" }], crossings: [{ car: "a", lap: 1, t: 101 }, { car: "b", lap: 1, t: 102.5 }, { car: "a", lap: 2, t: 198 }, { car: "b", lap: 2, t: 200 }] }, "las-vegas");
+ * const end = raceAt(race, race.duration);
+ * console.log(race.laps, end.standings[0].car.driver.code, end.standings[1].gap);
+ * // 2 AAA 2
+ * ```
+ */
+export declare function raceFromFeed(feed: RaceFeed, circuitId?: string): CircuitRace;
+/**
+ * A race as the open race timeline: what a simulated race is, written as a feed (the demo's sample feed is one). Lap times are rounded to thousandths.
+ * @example
+ * ```ts
+ * import { raceToFeed, simulateRace } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const feed = raceToFeed(simulateRace({ circuit: "las-vegas", laps: 3, cars: 4 }));
+ * console.log(feed.kind, feed.cars.length, feed.crossings.length);
+ * // kyogijo-race 4 12
+ * ```
+ */
+export declare function raceToFeed(race: CircuitRace, title?: string): RaceFeed;

package/dist/circuits.feed.fetch.d.ts

@@ -0,0 +1,69 @@
+import { type FeedResult, type RaceFeed } from "./circuits.feed.ts";
+/** Why a feed could not be read. */
+export type FeedProblemKind = "address" | "blocked" | "refused" | "busy" | "http" | "big" | "json" | "format";
+/** A feed that could not be read: what kind of problem, the answer's status if there was one, and a sentence. */
+export declare class RaceFeedError extends Error {
+    readonly kind: FeedProblemKind;
+    readonly status?: number;
+    constructor(kind: FeedProblemKind, message: string, status?: number);
+}
+/** The most text a feed may be: 30 MB. */
+export declare const FEED_MAX_BYTES = 30000000;
+type Fetch = (url: string, init?: RequestInit) => Promise<Response>;
+/**
+ * Read a feed from text (pasted, or a file's): kyogijo's open race timeline, or the lap rows of an OpenF1-style API. The answer is a feed, or a sentence that says why not.
+ * @example
+ * ```ts
+ * import { feedFromText } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * console.log(feedFromText('{"kind":"kyogijo-race","version":1,"cars":[{"id":"a"}],"crossings":[{"car":"a","lap":1,"t":99}]}').ok, feedFromText("not json").ok);
+ * // true false
+ * ```
+ */
+export declare function feedFromText(text: string): FeedResult;
+/** An address the user typed, if it is one a page may read: http or https, nothing else. */
+export declare function feedAddress(text: string, base?: string): URL | undefined;
+/** For an OpenF1-style lap address (`…/laps?session_key=…`), the same source's pit and driver addresses for that session. */
+export declare function openF1Siblings(url: URL): {
+    pit: string;
+    drivers: string;
+} | undefined;
+/**
+ * Read a race feed from an address the user gave, with the user's browser: kyogijo's open race timeline, or an OpenF1-style lap list (whose pit stops and drivers are then asked for from the same source and session,
+ * if it has them). It throws a `RaceFeedError` whose message says what went wrong in words: a source that does not let pages read it (CORS), a refusal (403), too many requests (429), not JSON, not a feed.
+ * @example
+ * ```ts no-run
+ * import { loadRaceFeed, raceFromFeed } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const feed = await loadRaceFeed("https://example.org/my-race.json");
+ * const race = raceFromFeed(feed, "las-vegas");
+ * ```
+ */
+export declare function loadRaceFeed(address: string, options?: {
+    fetch?: Fetch;
+    signal?: AbortSignal;
+    base?: string;
+}): Promise<RaceFeed>;
+/** What `followRaceFeed` gives back. */
+export interface FeedFollower {
+    /** Stop asking. */
+    stop(): void;
+    /** Whether it is still following. */
+    readonly following: boolean;
+}
+/** How often a feed is asked again while it is followed: no faster than every 10 seconds, every 15 by default. */
+export declare const FOLLOW_EVERY: Readonly<{
+    least: 10000;
+    normal: 15000;
+    most: 120000;
+}>;
+/**
+ * Follow a race that is going on: ask the user's address again every 15 seconds (never faster than 10), only while the page is visible, and hand each new feed to `onFeed`. It stops by itself when the feed is no longer
+ * live (the race is over), when the source refuses (403) or says it is busy (429), and when `stop` is called; after any other failure it waits twice as long each time, up to two minutes. A hidden page asks nothing.
+ */
+export declare function followRaceFeed(address: string, onFeed: (feed: RaceFeed) => void, options?: {
+    every?: number;
+    fetch?: Fetch;
+    doc?: Document;
+    onError?: (error: RaceFeedError) => void;
+    onStop?: (why: "over" | "refused" | "stopped") => void;
+}): FeedFollower;
+export {};

package/dist/circuits.feed.fetch.js

@@ -0,0 +1,205 @@
+// A race feed the user names: read from a URL by the user's own browser, from pasted text or from a file, and followed while a race is going on. Nothing goes through a server of ours (there is none), nothing is kept
+// beyond the page, and nothing is sent anywhere but to the address the user typed (and, for an OpenF1-style address, to the same source's pit and driver lists of the same session). A source that does not let a page
+// read it (CORS) is said to be so, in words, with the way round it: paste the answer or choose a file.
+import { readRaceFeed } from "./circuits.feed.js";
+import { looksLikeOpenF1Laps, openF1Feed } from "./circuits.feed.openf1.js";
+/** A feed that could not be read: what kind of problem, the answer's status if there was one, and a sentence. */
+export class RaceFeedError extends Error {
+    constructor(kind, message, status) {
+        super(message);
+        this.name = "RaceFeedError";
+        this.kind = kind;
+        if (status !== undefined)
+            this.status = status;
+    }
+}
+/** The most text a feed may be: 30 MB. */
+export const FEED_MAX_BYTES = 30000000;
+/**
+ * Read a feed from text (pasted, or a file's): kyogijo's open race timeline, or the lap rows of an OpenF1-style API. The answer is a feed, or a sentence that says why not.
+ * @example
+ * ```ts
+ * import { feedFromText } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * console.log(feedFromText('{"kind":"kyogijo-race","version":1,"cars":[{"id":"a"}],"crossings":[{"car":"a","lap":1,"t":99}]}').ok, feedFromText("not json").ok);
+ * // true false
+ * ```
+ */
+export function feedFromText(text) {
+    if (text.length > FEED_MAX_BYTES)
+        return { ok: false, error: "This is too big to be a race feed (over 30 MB)." };
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, error: "This is not JSON." };
+    }
+    if (looksLikeOpenF1Laps(data))
+        return { ok: true, feed: openF1Feed({ laps: data }) };
+    return readRaceFeed(data);
+}
+/** An address the user typed, if it is one a page may read: http or https, nothing else. */
+export function feedAddress(text, base) {
+    try {
+        const url = new URL(text.trim(), base);
+        return url.protocol === "https:" || url.protocol === "http:" ? url : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function getJson(fetcher, url, signal) {
+    let answer;
+    try {
+        // No cookies, no referrer: the request carries nothing of the page's.
+        answer = await fetcher(url, { signal, credentials: "omit", referrerPolicy: "no-referrer", cache: "no-store" });
+    }
+    catch (error) {
+        if (error?.name === "AbortError")
+            throw error;
+        throw new RaceFeedError("blocked", "The browser could not read this address: the source may not let pages on other sites read it (CORS), or it could not be reached. Paste its answer, or save it and choose the file.");
+    }
+    if (answer.status === 403 || answer.status === 401)
+        throw new RaceFeedError("refused", `The source refused the request (${answer.status}): it may need a sign-in or a key, or not allow this use.`, answer.status);
+    if (answer.status === 429)
+        throw new RaceFeedError("busy", "The source says it has had too many requests (429): wait before trying again.", 429);
+    if (!answer.ok)
+        throw new RaceFeedError("http", `The source answered ${answer.status}.`, answer.status);
+    const text = await answer.text();
+    if (text.length > FEED_MAX_BYTES)
+        throw new RaceFeedError("big", "The answer is too big to be a race feed (over 30 MB).");
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new RaceFeedError("json", "The answer is not JSON.");
+    }
+}
+/** For an OpenF1-style lap address (`…/laps?session_key=…`), the same source's pit and driver addresses for that session. */
+export function openF1Siblings(url) {
+    const session = url.searchParams.get("session_key");
+    if (!/\/laps\/?$/.test(url.pathname) || session === null)
+        return undefined;
+    const base = url.pathname.replace(/\/laps\/?$/, "");
+    const at = (name) => `${url.origin}${base}/${name}?session_key=${encodeURIComponent(session)}`;
+    return { pit: at("pit"), drivers: at("drivers") };
+}
+/**
+ * Read a race feed from an address the user gave, with the user's browser: kyogijo's open race timeline, or an OpenF1-style lap list (whose pit stops and drivers are then asked for from the same source and session,
+ * if it has them). It throws a `RaceFeedError` whose message says what went wrong in words: a source that does not let pages read it (CORS), a refusal (403), too many requests (429), not JSON, not a feed.
+ * @example
+ * ```ts no-run
+ * import { loadRaceFeed, raceFromFeed } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const feed = await loadRaceFeed("https://example.org/my-race.json");
+ * const race = raceFromFeed(feed, "las-vegas");
+ * ```
+ */
+export async function loadRaceFeed(address, options = {}) {
+    const url = feedAddress(address, options.base);
+    if (url === undefined)
+        throw new RaceFeedError("address", "This is not a web address (it needs to start with https://).");
+    const fetcher = options.fetch ?? ((u, init) => fetch(u, init));
+    const data = await getJson(fetcher, url.href, options.signal);
+    if (looksLikeOpenF1Laps(data)) {
+        const more = openF1Siblings(url);
+        // The pit stops and the drivers make the board readable; without them the race still plays, by car numbers.
+        const optional = async (href) => {
+            if (href === undefined)
+                return undefined;
+            try {
+                const list = await getJson(fetcher, href, options.signal);
+                return Array.isArray(list) ? list : undefined;
+            }
+            catch (error) {
+                if (error?.name === "AbortError")
+                    throw error;
+                return undefined;
+            }
+        };
+        const pit = await optional(more?.pit);
+        const drivers = await optional(more?.drivers);
+        return openF1Feed({ laps: data, ...(pit === undefined ? {} : { pit }), ...(drivers === undefined ? {} : { drivers }) });
+    }
+    const read = readRaceFeed(data);
+    if (!read.ok)
+        throw new RaceFeedError("format", read.error);
+    return read.feed;
+}
+/** How often a feed is asked again while it is followed: no faster than every 10 seconds, every 15 by default. */
+export const FOLLOW_EVERY = Object.freeze({ least: 10000, normal: 15000, most: 120000 });
+/**
+ * Follow a race that is going on: ask the user's address again every 15 seconds (never faster than 10), only while the page is visible, and hand each new feed to `onFeed`. It stops by itself when the feed is no longer
+ * live (the race is over), when the source refuses (403) or says it is busy (429), and when `stop` is called; after any other failure it waits twice as long each time, up to two minutes. A hidden page asks nothing.
+ */
+export function followRaceFeed(address, onFeed, options = {}) {
+    const doc = options.doc ?? (typeof document === "undefined" ? undefined : document);
+    const every = Math.min(FOLLOW_EVERY.most, Math.max(FOLLOW_EVERY.least, options.every ?? FOLLOW_EVERY.normal));
+    let wait = every;
+    let timer;
+    let busy;
+    let alive = true;
+    const end = (why) => {
+        if (!alive)
+            return;
+        alive = false;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        busy?.abort();
+        doc?.removeEventListener("visibilitychange", seen);
+        options.onStop?.(why);
+    };
+    const hidden = () => doc?.visibilityState === "hidden";
+    const later = () => {
+        if (!alive || hidden() || timer !== undefined || busy !== undefined)
+            return;
+        timer = setTimeout(ask, wait);
+    };
+    async function ask() {
+        timer = undefined;
+        if (!alive || hidden())
+            return;
+        busy = new AbortController();
+        try {
+            const feed = await loadRaceFeed(address, { ...(options.fetch === undefined ? {} : { fetch: options.fetch }), signal: busy.signal });
+            busy = undefined;
+            if (!alive)
+                return;
+            wait = every;
+            onFeed(feed);
+            if (feed.live !== true)
+                return end("over");
+        }
+        catch (error) {
+            busy = undefined;
+            if (!alive || error?.name === "AbortError")
+                return;
+            const problem = error instanceof RaceFeedError ? error : new RaceFeedError("http", String(error?.message ?? error));
+            options.onError?.(problem);
+            if (problem.kind === "refused" || problem.kind === "busy")
+                return end("refused");
+            wait = Math.min(FOLLOW_EVERY.most, wait * 2);
+        }
+        later();
+    }
+    // Hidden, the timer is let go; shown again, the feed is asked at once and then on the clock.
+    function seen() {
+        if (!alive)
+            return;
+        if (hidden()) {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+        }
+        else if (timer === undefined && busy === undefined)
+            void ask();
+    }
+    doc?.addEventListener("visibilitychange", seen);
+    void ask();
+    return {
+        stop: () => end("stopped"),
+        get following() {
+            return alive;
+        },
+    };
+}

package/dist/circuits.feed.js

@@ -0,0 +1,332 @@
+// A race from a feed: kyogijo's open race timeline (`kyogijo-race`, version 1), read strictly, and turned into the same race a simulation gives (`CircuitRace`), so that every moment, drawing, board and page of a
+// simulated race plays it unchanged. A feed says when each car completed each lap, and may say when it was in the pit lane, when it retired and where it was (location samples in the feed's own frame); the cars run
+// between those moments at the lap's own speeds (`paceProfile`), and location samples are laid on the circuit's own line by how far round the lap they are, so the dots stay on the road. Pure: no request is made here.
+import { nearestOn } from "./circuits.geo.js";
+import { circuitOf, circuitPlan } from "./circuits.js";
+import { lineLength } from "./circuits.geo.js";
+import { paceProfile } from "./circuits.pace.js";
+import { FEET_PER_METRE as FT } from "./geometry.js";
+/** The most a feed may hold: cars, and rows of each list. */
+export const FEED_LIMITS = Object.freeze({ cars: 40, rows: 200000, laps: 200 });
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+const isText = (v) => typeof v === "string" && v.length > 0 && v.length <= 80;
+const COLOUR = /^#[0-9a-f]{6}$/i;
+/** The colours a feed's car takes when it gives none, in turn (the made-up teams' own). */
+const FALLBACK = ["#1d4ed8", "#0f766e", "#db2777", "#c026d3", "#65a30d", "#0ea5e9", "#b91c1c", "#94a3b8", "#ca8a04", "#7c3aed"];
+/**
+ * Read a feed strictly: anything that is not the open race timeline is refused with a sentence that says why, and anything a feed carries that the format does not name is left behind. Text is kept as text (never markup).
+ * @example
+ * ```ts
+ * import { readRaceFeed } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const read = readRaceFeed({ kind: "kyogijo-race", version: 1, cars: [{ id: "a" }], crossings: [{ car: "a", lap: 1, t: 101 }] });
+ * console.log(read.ok, readRaceFeed({ kind: "something" }).ok);
+ * // true false
+ * ```
+ */
+export function readRaceFeed(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return { ok: false, error: "A race feed is a JSON object." };
+    const o = input;
+    if (o.kind !== "kyogijo-race")
+        return { ok: false, error: 'This is not a race feed: its "kind" is not "kyogijo-race".' };
+    if (o.version !== 1)
+        return { ok: false, error: "This race feed is of a version this package does not read (it reads version 1)." };
+    if (!Array.isArray(o.cars) || o.cars.length === 0)
+        return { ok: false, error: "The race feed has no cars." };
+    if (o.cars.length > FEED_LIMITS.cars)
+        return { ok: false, error: `The race feed has more than ${FEED_LIMITS.cars} cars.` };
+    const cars = [];
+    const ids = new Set();
+    for (const raw of o.cars) {
+        const c = (typeof raw === "object" && raw !== null ? raw : {});
+        const id = typeof c.id === "number" ? String(c.id) : c.id;
+        if (!isText(id) || ids.has(id))
+            return { ok: false, error: "Each car of the race feed needs an id of its own." };
+        ids.add(id);
+        cars.push({
+            id,
+            ...(isText(c.code) ? { code: c.code.slice(0, 4) } : {}),
+            ...(isText(c.name) ? { name: c.name } : {}),
+            ...(isText(c.team) ? { team: c.team } : {}),
+            ...(typeof c.colour === "string" && COLOUR.test(c.colour) ? { colour: c.colour } : {}),
+            ...(isNum(c.grid) && c.grid >= 1 ? { grid: Math.round(c.grid) } : {}),
+        });
+    }
+    const rows = (name, keep) => {
+        const list = o[name];
+        if (list === undefined)
+            return [];
+        if (!Array.isArray(list))
+            return `The race feed's "${name}" is not a list.`;
+        if (list.length > FEED_LIMITS.rows)
+            return `The race feed's "${name}" has more than ${FEED_LIMITS.rows} rows.`;
+        const out = [];
+        for (const r of list) {
+            if (typeof r !== "object" || r === null)
+                continue;
+            const row = r;
+            const car = typeof row.car === "number" ? String(row.car) : row.car;
+            if (typeof car !== "string" || !ids.has(car))
+                continue;
+            const kept = keep({ ...row, car });
+            if (kept !== undefined)
+                out.push(kept);
+        }
+        return out;
+    };
+    const crossings = rows("crossings", (r) => (isNum(r.lap) && r.lap >= 1 && r.lap <= FEED_LIMITS.laps && isNum(r.t) && r.t > 0 ? { car: r.car, lap: Math.round(r.lap), t: r.t } : undefined));
+    const pits = rows("pits", (r) => (isNum(r.in) && isNum(r.out) && r.out > r.in ? { car: r.car, in: r.in, out: r.out, ...(isNum(r.stop) && r.stop >= 0 ? { stop: r.stop } : {}) } : undefined));
+    const out = rows("out", (r) => (isNum(r.t) && r.t >= 0 ? { car: r.car, t: r.t } : undefined));
+    const positions = rows("positions", (r) => (isNum(r.t) && isNum(r.x) && isNum(r.y) ? { car: r.car, t: r.t, x: r.x, y: r.y } : undefined));
+    for (const list of [crossings, pits, out, positions])
+        if (typeof list === "string")
+            return { ok: false, error: list };
+    if (crossings.length === 0)
+        return { ok: false, error: "The race feed has no lap times: it needs at least one car's completed lap." };
+    return {
+        ok: true,
+        feed: {
+            kind: "kyogijo-race",
+            version: 1,
+            ...(isText(o.circuit) ? { circuit: o.circuit } : {}),
+            ...(isNum(o.laps) && o.laps >= 1 && o.laps <= FEED_LIMITS.laps ? { laps: Math.round(o.laps) } : {}),
+            ...(typeof o.title === "string" && o.title.length <= 200 ? { title: o.title } : {}),
+            cars,
+            crossings: crossings,
+            ...(pits.length > 0 ? { pits: pits } : {}),
+            ...(out.length > 0 ? { out: out } : {}),
+            ...(positions.length > 0 ? { positions: positions } : {}),
+            ...(o.live === true ? { live: true } : {}),
+        },
+    };
+}
+/** The colour of what is written on a colour: dark on a light one, white on a dark one. */
+const inkOn = (hex) => {
+    const n = Number.parseInt(hex.slice(1), 16);
+    const lum = 0.299 * ((n >> 16) & 255) + 0.587 * ((n >> 8) & 255) + 0.114 * (n & 255);
+    return lum > 150 ? "#10151b" : "#ffffff";
+};
+const mod = (a, n) => ((a % n) + n) % n;
+/** Where the location samples of a car lie round the lap, as shares of it from the timing line: the feed's own line is the path of the car with the most samples over its second lap. */
+function lapShares(feed, crossed) {
+    const out = new Map();
+    const positions = feed.positions ?? [];
+    if (positions.length === 0)
+        return out;
+    const byCar = new Map();
+    for (const p of positions) {
+        let list = byCar.get(p.car);
+        if (list === undefined)
+            byCar.set(p.car, (list = []));
+        list.push({ t: p.t, at: [p.x, p.y] });
+    }
+    for (const list of byCar.values())
+        list.sort((a, b) => a.t - b.t);
+    // The reference: a lap of one car, from one crossing to the next.
+    let ref = [];
+    let refStart;
+    for (const [car, list] of byCar) {
+        const cr = crossed.get(car) ?? [];
+        for (let k = 1; k < cr.length; k += 1) {
+            const lap = list.filter((s) => s.t >= cr[k - 1] && s.t <= cr[k]);
+            if (lap.length > ref.length) {
+                ref = lap.map((s) => s.at);
+                refStart = lap[0].at;
+            }
+        }
+    }
+    if (ref.length < 20 || refStart === undefined)
+        return out;
+    const total = lineLength(ref, true);
+    const zero = nearestOn(ref, refStart, true).along;
+    for (const [car, list] of byCar)
+        out.set(car, list.map((s) => ({ t: s.t, share: mod(nearestOn(ref, s.at, true).along - zero, total) / total })));
+    return out;
+}
+/**
+ * A feed as a race (`CircuitRace`): the same shape a simulation gives, so that `raceAt`, `drawRace`, `raceBoard` and `mountCircuitRace` play it. The circuit is the feed's, or the one named here (a page draws a feed on the
+ * circuit it shows). Between the moments a feed gives, the cars run at the lap's own speeds.
+ * @example
+ * ```ts
+ * import { raceAt, raceFromFeed } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const race = raceFromFeed({ kind: "kyogijo-race", version: 1, cars: [{ id: "a", code: "AAA" }, { id: "b", code: "BBB" }], crossings: [{ car: "a", lap: 1, t: 101 }, { car: "b", lap: 1, t: 102.5 }, { car: "a", lap: 2, t: 198 }, { car: "b", lap: 2, t: 200 }] }, "las-vegas");
+ * const end = raceAt(race, race.duration);
+ * console.log(race.laps, end.standings[0].car.driver.code, end.standings[1].gap);
+ * // 2 AAA 2
+ * ```
+ */
+export function raceFromFeed(feed, circuitId) {
+    const circuit = circuitOf(circuitId ?? feed.circuit ?? "las-vegas");
+    const plan = circuitPlan(circuit);
+    const pace = paceProfile(plan);
+    const L = pace.length;
+    const lineAlong = plan.finish.along / FT;
+    const entry = nearestOn(plan.lap, plan.pitLane[0], true).along / FT;
+    const exit = nearestOn(plan.lap, plan.pitLane[plan.pitLane.length - 1], true).along / FT;
+    const pitLength = lineLength(plan.pitLane, false) / FT;
+    const bypass = mod(exit - entry, L);
+    let ahead = mod(plan.start.along / FT - lineAlong, L);
+    if (ahead > L / 2)
+        ahead -= L;
+    const order = [...feed.cars].map((c, i) => ({ c, i })).sort((a, b) => (a.c.grid ?? a.i + 1) - (b.c.grid ?? b.i + 1));
+    const cars = order.map(({ c, i }, place) => {
+        const colour = c.colour ?? FALLBACK[i % FALLBACK.length];
+        const team = { id: `feed-${c.team ?? c.id}`, name: { en: c.team ?? "", ja: c.team ?? "" }, colour, ink: inkOn(colour) };
+        const driver = { code: c.code ?? c.id.slice(0, 4).toUpperCase(), name: { en: c.name ?? c.code ?? c.id, ja: c.name ?? c.code ?? c.id }, team: team.id };
+        return { id: c.id, driver, team, grid: place + 1 };
+    });
+    const crossed = new Map(cars.map((c) => [c.id, []]));
+    for (const row of [...feed.crossings].sort((a, b) => a.lap - b.lap || a.t - b.t)) {
+        const list = crossed.get(row.car);
+        // Lap n is the n-th crossing: a lap the feed skipped is left as the feed has it, and a crossing that goes back in time is dropped.
+        if (list.length < row.lap && (list.length === 0 || row.t > list[list.length - 1]))
+            list.push(row.t);
+    }
+    const maxLaps = Math.max(...[...crossed.values()].map((l) => l.length));
+    const laps = feed.live === true ? Math.max(feed.laps ?? 0, maxLaps) : Math.min(feed.laps ?? maxLaps, Math.max(maxLaps, 1));
+    const outAt = new Map((feed.out ?? []).map((o) => [o.car, o.t]));
+    const lastSeen = Math.max(...feed.crossings.map((c) => c.t), ...(feed.out ?? []).map((o) => o.t), ...(feed.pits ?? []).map((p) => p.out));
+    // The flag: the first car to complete the race's laps, when the feed says the race has its end.
+    const leaderAt = [...crossed.values()].map((l) => l[laps - 1]).filter((t) => t !== undefined);
+    const flag = feed.live === true || leaderAt.length === 0 ? Number.NaN : Math.min(...leaderAt);
+    const duration = Math.ceil(lastSeen + (Number.isNaN(flag) ? 0 : 20));
+    const size = duration + 1;
+    const shares = lapShares(feed, crossed);
+    // The lap's own time to each place round it, from the timing line: the shape of the run between two moments.
+    const timeTo = (s) => {
+        const whole = Math.floor(s / L);
+        const along = mod(lineAlong + s, L);
+        const at = (x) => {
+            const i = Math.min(Math.floor(x / pace.step), pace.speed.length - 1);
+            const f = x / pace.step - i;
+            return pace.time[i] + f * (pace.time[i + 1] - pace.time[i]);
+        };
+        const fromLine = mod(at(along) - at(mod(lineAlong, L)), pace.lap);
+        return whole * pace.lap + fromLine;
+    };
+    /** The race distance between `a` (at `ta`) and `b` (at `tb`) at a time, at the lap's speeds. */
+    const between = (a, b, ta, tb, t) => {
+        if (tb <= ta || b <= a)
+            return a;
+        const target = timeTo(a) + ((t - ta) / (tb - ta)) * (timeTo(b) - timeTo(a));
+        let lo = a;
+        let hi = b;
+        for (let i = 0; i < 30; i += 1) {
+            const mid = (lo + hi) / 2;
+            if (timeTo(mid) < target)
+                lo = mid;
+            else
+                hi = mid;
+        }
+        return (lo + hi) / 2;
+    };
+    const distance = cars.map(() => new Float64Array(size));
+    const pit = cars.map(() => new Float32Array(size).fill(Number.NaN));
+    const stops = cars.map(() => []);
+    const finish = cars.map(() => undefined);
+    const out = cars.map(() => undefined);
+    cars.forEach((car, c) => {
+        const cr = crossed.get(car.id);
+        const start = ahead - 8 * (car.grid - 1);
+        // The moments of this car: the start, every crossing, every location sample, and the ends of the pit lane.
+        const points = [{ t: 0, s: start }, ...cr.map((t, k) => ({ t, s: (k + 1) * L }))];
+        const lapsAt = (t) => cr.filter((x) => x <= t).length;
+        for (const sample of shares.get(car.id) ?? []) {
+            const k = lapsAt(sample.t);
+            let s = k * L + sample.share * L;
+            // A sample just after a crossing whose share is still near the end of the lap belongs to the lap before.
+            if (sample.share > 0.9 && k > 0 && sample.t - cr[k - 1] < 10)
+                s -= L;
+            if (s > start)
+                points.push({ t: sample.t, s });
+        }
+        const pits = (feed.pits ?? []).filter((p) => p.car === car.id).sort((a, b) => a.in - b.in);
+        for (const p of pits) {
+            const k = lapsAt(p.in);
+            const sIn = k * L + mod(entry - lineAlong, L);
+            points.push({ t: p.in, s: sIn, pitTo: p.out }, { t: p.out, s: sIn + bypass });
+            stops[c].push({ lap: k + 1, in: p.in, out: p.out, stop: p.stop ?? 0 });
+        }
+        // A car still running when the feed ends goes on round at its last lap's pace, so that a race that is going on does not hold its dots on the line.
+        const retired0 = outAt.get(car.id);
+        const done = !Number.isNaN(flag) && cr.some((t) => t >= flag);
+        if (retired0 === undefined && !done && cr.length > 0) {
+            const lastLap = cr.length > 1 ? cr[cr.length - 1] - cr[cr.length - 2] : pace.lap;
+            points.push({ t: cr[cr.length - 1] + lastLap, s: (cr.length + 1) * L });
+        }
+        points.sort((a, b) => a.t - b.t);
+        // Distance never goes back.
+        for (let i = 1; i < points.length; i += 1)
+            if (points[i].s < points[i - 1].s)
+                points[i].s = points[i - 1].s;
+        const retired = outAt.get(car.id);
+        if (retired !== undefined)
+            out[c] = retired;
+        if (!Number.isNaN(flag))
+            finish[c] = cr.find((t) => t >= flag);
+        let j = 0;
+        for (let second = 0; second < size; second += 1) {
+            const t = second;
+            while (j + 1 < points.length && points[j + 1].t <= t)
+                j += 1;
+            const a = points[j];
+            const b = points[j + 1];
+            const pitWindow = a.pitTo !== undefined && t < a.pitTo;
+            if (pitWindow) {
+                const f = (t - a.t) / (a.pitTo - a.t);
+                pit[c][second] = f * pitLength;
+                distance[c][second] = a.s + f * bypass;
+            }
+            else if (b === undefined || (retired !== undefined && t >= retired)) {
+                distance[c][second] = second === 0 ? a.s : distance[c][second - 1];
+            }
+            else
+                distance[c][second] = between(a.s, b.s, a.t, b.t, t);
+        }
+    });
+    return Object.freeze({
+        circuit,
+        plan,
+        seed: 0,
+        laps,
+        cars: Object.freeze(cars),
+        lapLength: L,
+        lineAlong,
+        pitLane: { entry, exit, length: pitLength },
+        pace,
+        sample: 1,
+        flag: Number.isNaN(flag) ? duration + 1 : flag,
+        duration,
+        distance,
+        pit,
+        crossings: cars.map((car) => crossed.get(car.id)),
+        stops,
+        finish,
+        out,
+    });
+}
+/**
+ * A race as the open race timeline: what a simulated race is, written as a feed (the demo's sample feed is one). Lap times are rounded to thousandths.
+ * @example
+ * ```ts
+ * import { raceToFeed, simulateRace } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const feed = raceToFeed(simulateRace({ circuit: "las-vegas", laps: 3, cars: 4 }));
+ * console.log(feed.kind, feed.cars.length, feed.crossings.length);
+ * // kyogijo-race 4 12
+ * ```
+ */
+export function raceToFeed(race, title) {
+    const r3 = (n) => Math.round(n * 1000) / 1000;
+    const feed = {
+        kind: "kyogijo-race",
+        version: 1,
+        circuit: race.circuit.id,
+        laps: race.laps,
+        ...(title === undefined ? {} : { title }),
+        cars: race.cars.map((c) => ({ id: c.id, code: c.driver.code, name: c.driver.name.en, team: c.team.name.en, colour: c.team.colour, grid: c.grid })),
+        crossings: race.cars.flatMap((c, i) => race.crossings[i].map((t, k) => ({ car: c.id, lap: k + 1, t: r3(t) }))),
+    };
+    const pits = race.cars.flatMap((c, i) => race.stops[i].map((s) => ({ car: c.id, in: r3(s.in), out: r3(s.out), stop: r3(s.stop) })));
+    const out = race.cars.flatMap((c, i) => (race.out[i] === undefined ? [] : [{ car: c.id, t: r3(race.out[i]) }]));
+    return { ...feed, ...(pits.length > 0 ? { pits } : {}), ...(out.length > 0 ? { out } : {}) };
+}

package/dist/circuits.feed.openf1.d.ts

@@ -0,0 +1,61 @@
+import type { RaceFeed } from "./circuits.feed.ts";
+/** A lap row: who, which lap, when it started and how long it took. */
+export interface OpenF1Lap {
+    driver_number: number;
+    lap_number: number;
+    date_start?: string | null;
+    lap_duration?: number | null;
+}
+/** A pit row: who, on which lap, when it entered the pit lane and how long it was in it and standing. */
+export interface OpenF1Pit {
+    driver_number: number;
+    lap_number?: number;
+    date: string;
+    pit_duration?: number | null;
+    lane_duration?: number | null;
+    stop_duration?: number | null;
+}
+/** A driver row: the code, the name and the team as the source gives them. */
+export interface OpenF1Driver {
+    driver_number: number;
+    name_acronym?: string;
+    broadcast_name?: string;
+    last_name?: string;
+    team_name?: string;
+    team_colour?: string;
+}
+/** A location row: where a car was, in the source's own frame. */
+export interface OpenF1Location {
+    driver_number: number;
+    date: string;
+    x: number;
+    y: number;
+}
+/** What the adapter is given: the rows of each answer the user's source gave. Only `laps` is needed. */
+export interface OpenF1Rows {
+    laps: readonly OpenF1Lap[];
+    pit?: readonly OpenF1Pit[];
+    drivers?: readonly OpenF1Driver[];
+    location?: readonly OpenF1Location[];
+    /** The laps of the race, if known. */
+    totalLaps?: number;
+    /** True while the session is going on. */
+    live?: boolean;
+}
+/** Whether a list looks like OpenF1's lap rows: objects with a driver number and a lap number. */
+export declare const looksLikeOpenF1Laps: (input: unknown) => input is OpenF1Lap[];
+/**
+ * OpenF1-style rows as a race feed. The start is the earliest start of a first lap; a lap is completed at its start plus its duration (or, where the duration is missing, at the next lap's start). A pit stop runs from
+ * its row's time for its lane duration. Location rows, when given, become the feed's positions.
+ * @example
+ * ```ts
+ * import { openF1Feed } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const feed = openF1Feed({ laps: [
+ *   { driver_number: 7, lap_number: 1, date_start: "2030-01-01T20:00:00Z", lap_duration: 101 },
+ *   { driver_number: 7, lap_number: 2, date_start: "2030-01-01T20:01:41Z", lap_duration: 97.5 },
+ * ], drivers: [{ driver_number: 7, name_acronym: "ABC", team_name: "Made-up Team", team_colour: "3366CC" }] });
+ * console.log(feed.cars[0].code, feed.cars[0].colour, feed.crossings.map((c) => c.t).join(" "));
+ * // ABC #3366cc 101 198.5
+ * ```
+ */
+export declare function openF1Feed(rows: OpenF1Rows): RaceFeed;

package/dist/circuits.feed.openf1.js

@@ -0,0 +1,65 @@
+const ms = (date) => (typeof date === "string" ? Date.parse(date) : Number.NaN);
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+/** Whether a list looks like OpenF1's lap rows: objects with a driver number and a lap number. */
+export const looksLikeOpenF1Laps = (input) => Array.isArray(input) && input.length > 0 && input.slice(0, 5).every((r) => typeof r === "object" && r !== null && isNum(r.driver_number) && isNum(r.lap_number));
+/**
+ * OpenF1-style rows as a race feed. The start is the earliest start of a first lap; a lap is completed at its start plus its duration (or, where the duration is missing, at the next lap's start). A pit stop runs from
+ * its row's time for its lane duration. Location rows, when given, become the feed's positions.
+ * @example
+ * ```ts
+ * import { openF1Feed } from "@johnmorrisdotca/kyogijo-stadiums/circuits";
+ * const feed = openF1Feed({ laps: [
+ *   { driver_number: 7, lap_number: 1, date_start: "2030-01-01T20:00:00Z", lap_duration: 101 },
+ *   { driver_number: 7, lap_number: 2, date_start: "2030-01-01T20:01:41Z", lap_duration: 97.5 },
+ * ], drivers: [{ driver_number: 7, name_acronym: "ABC", team_name: "Made-up Team", team_colour: "3366CC" }] });
+ * console.log(feed.cars[0].code, feed.cars[0].colour, feed.crossings.map((c) => c.t).join(" "));
+ * // ABC #3366cc 101 198.5
+ * ```
+ */
+export function openF1Feed(rows) {
+    const laps = rows.laps.filter((l) => isNum(l.driver_number) && isNum(l.lap_number));
+    const firsts = laps.filter((l) => l.lap_number === 1).map((l) => ms(l.date_start)).filter(Number.isFinite);
+    const zero = firsts.length > 0 ? Math.min(...firsts) : Math.min(...laps.map((l) => ms(l.date_start)).filter(Number.isFinite));
+    const at = (date) => (ms(date) - zero) / 1000;
+    const numbers = [...new Set(laps.map((l) => l.driver_number))];
+    const drivers = new Map((rows.drivers ?? []).map((d) => [d.driver_number, d]));
+    const cars = numbers.map((n) => {
+        const d = drivers.get(n);
+        const colour = typeof d?.team_colour === "string" && /^[0-9a-f]{6}$/i.test(d.team_colour) ? `#${d.team_colour.toLowerCase()}` : undefined;
+        return {
+            id: String(n),
+            code: (d?.name_acronym ?? String(n)).slice(0, 4),
+            name: d?.last_name ?? d?.broadcast_name ?? String(n),
+            ...(d?.team_name === undefined ? {} : { team: d.team_name }),
+            ...(colour === undefined ? {} : { colour }),
+        };
+    });
+    const crossings = [];
+    for (const n of numbers) {
+        const mine = laps.filter((l) => l.driver_number === n).sort((a, b) => a.lap_number - b.lap_number);
+        mine.forEach((l, i) => {
+            const next = mine[i + 1];
+            const end = isNum(l.lap_duration) && Number.isFinite(at(l.date_start)) ? at(l.date_start) + l.lap_duration : next !== undefined && next.lap_number === l.lap_number + 1 ? at(next.date_start) : Number.NaN;
+            if (Number.isFinite(end) && end > 0)
+                crossings.push({ car: String(n), lap: l.lap_number, t: Math.round(end * 1000) / 1000 });
+        });
+    }
+    const pits = (rows.pit ?? [])
+        .filter((p) => isNum(p.driver_number) && Number.isFinite(at(p.date)))
+        .map((p) => {
+        const lane = [p.lane_duration, p.pit_duration].find(isNum) ?? 20;
+        return { car: String(p.driver_number), in: at(p.date), out: at(p.date) + lane, ...(isNum(p.stop_duration) ? { stop: p.stop_duration } : {}) };
+    })
+        .filter((p) => p.in >= 0);
+    const positions = (rows.location ?? []).filter((p) => isNum(p.driver_number) && isNum(p.x) && isNum(p.y) && Number.isFinite(at(p.date))).map((p) => ({ car: String(p.driver_number), t: at(p.date), x: p.x, y: p.y }));
+    return {
+        kind: "kyogijo-race",
+        version: 1,
+        ...(isNum(rows.totalLaps) ? { laps: rows.totalLaps } : {}),
+        cars,
+        crossings,
+        ...(pits.length > 0 ? { pits } : {}),
+        ...(positions.length > 0 ? { positions } : {}),
+        ...(rows.live === true ? { live: true } : {}),
+    };
+}

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

@@ -23,6 +23,8 @@ export interface RaceViewSettings {
     motion?: "auto" | "smooth" | "step";
     /** The timing board under the controls: on by default. */
     board?: boolean;
+    /** A race already worked out to play instead of a simulation: one from a feed (`raceFromFeed`). */
+    race?: CircuitRace;
     /** Told when the reader plays, pauses, seeks or changes speed, and when the race ends: not at every frame. */
     onChange?: (state: RaceState) => void;
 }
@@ -37,6 +39,7 @@ export interface RaceState {
 }
 /** What `mountCircuitRace` gives back. */
 export interface KyogijoRace {
+    /** The race it plays. */
     readonly race: CircuitRace;
     /** The 3D view, when the race is on one. */
     readonly turn: KyogijoTurn<CircuitOptions> | undefined;
@@ -53,6 +56,8 @@ export interface KyogijoRace {
     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;
+    /** Play another race in the same view (a feed that came in again while a race is followed): the clock stays where it is, held to the new race's end, and stays playing or paused. */
+    replace(race: CircuitRace): void;
     destroy(): void;
 }
 /**

package/dist/circuits.race.dom.js

@@ -29,7 +29,8 @@ export function mountCircuitRace(host, initial, settings = {}) {
     const doc = host.ownerDocument;
     let options = { ...initial };
     let language = options.language === "ja" ? "ja" : "en";
-    const race = simulateRace(options);
+    let race = settings.race ?? simulateRace(options);
+    let fromFeed = settings.race !== undefined;
     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));
@@ -100,7 +101,7 @@ export function mountCircuitRace(host, initial, settings = {}) {
         }
     };
     const drawFlat = () => {
-        stage.innerHTML = raceDrawing({ ...options, t: state.t }).svg;
+        stage.innerHTML = raceDrawing({ ...options, t: state.t }, fromFeed ? race : undefined).svg;
         bindFlat();
     };
     /** The model of the 3D view with a disc for each car at the clock's time. */
@@ -270,7 +271,7 @@ export function mountCircuitRace(host, initial, settings = {}) {
             b.setAttribute("aria-pressed", String(n === state.speed));
         }
         range.setAttribute("aria-label", w.position);
-        setText(note, w.simulated);
+        setText(note, fromFeed ? w.feedNote : w.simulated);
         root.dataset.state = state.ended ? "ended" : state.playing ? "playing" : "paused";
         root.dataset.motion = state.motion;
     };
@@ -310,7 +311,9 @@ export function mountCircuitRace(host, initial, settings = {}) {
         frameId = request(frame);
     }
     const api = {
-        race,
+        get race() {
+            return race;
+        },
         get turn() {
             return turn;
         },
@@ -380,6 +383,25 @@ export function mountCircuitRace(host, initial, settings = {}) {
             label();
             paint(undefined, false);
         },
+        replace(next) {
+            const cars = race.cars.length;
+            race = next;
+            fromFeed = true;
+            state.duration = race.duration;
+            range.max = String(race.duration);
+            if (state.t > race.duration)
+                state.t = race.duration;
+            state.ended = !state.playing && state.t >= race.duration;
+            moment = raceAt(race, state.t);
+            if (inner !== undefined)
+                inner.setDecorate(withCars, bindTurn);
+            else
+                drawFlat();
+            if (cars !== race.cars.length || boardRows.length !== race.cars.length)
+                buildBoard();
+            label();
+            paint(undefined, false);
+        },
         destroy() {
             stopFrames();
             state.playing = false;

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

@@ -29,8 +29,8 @@ 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;
+/** The race, the drawing of its circuit and the moment, with the cars on it: the race the options make, or one given (from a feed). */
+export declare function raceDrawing(options: RaceDrawOptions, given?: CircuitRace): 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

package/dist/circuits.race.draw.js

@@ -64,14 +64,14 @@ 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) {
+/** The race, the drawing of its circuit and the moment, with the cars on it: the race the options make, or one given (from a feed). */
+export function raceDrawing(options, given) {
     const language = options.language === "ja" ? "ja" : "en";
-    const race = simulateRace(options);
+    const race = given ?? 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 extra = ` ${fill(given === undefined ? w.description : w.fromFeed, { 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 };

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

@@ -3,6 +3,8 @@ import type { Language } from "./types.ts";
 export interface RaceWords {
     /** The line that says what this is: a model, not a real race. */
     simulated: string;
+    /** The same line for a race from a feed the reader chose. */
+    feedNote: string;
     /** The race clock: the lap the leader is on, and the line under it once the flag has fallen. */
     lap: string;
     finalLap: string;
@@ -43,7 +45,8 @@ export interface RaceWords {
     /** What is said aloud as the race goes. */
     leads: string;
     wins: string;
-    /** The drawing's description, added to the circuit's. */
+    /** The drawing's description, added to the circuit's: a simulation's, and a race from a feed's. */
     description: string;
+    fromFeed: string;
 }
 export declare const RACE_WORDS: Readonly<Record<Language, RaceWords>>;

package/dist/circuits.race.words.js

@@ -1,6 +1,7 @@
 export const RACE_WORDS = Object.freeze({
     en: {
         simulated: "A simulated race: made-up cars and drivers, worked out from a seed. No real race, driver or team.",
+        feedNote: "A race from a feed you chose: its names, times and results are the feed's, shown in this page only. Between the times it gives, each car runs at the lap's own speeds.",
         lap: "Lap {lap} / {laps}",
         finalLap: "Final lap",
         flag: "Chequered flag",
@@ -19,9 +20,11 @@ export const RACE_WORDS = Object.freeze({
         leads: "{name} leads, lap {lap}.",
         wins: "Chequered flag: {name} wins.",
         description: "{cars} made-up cars race {laps} laps from the grid to the chequered flag: a simulation, not a real race.",
+        fromFeed: "{cars} cars race {laps} laps, from a feed the reader chose: where each car is between the times it gives is worked out at the lap's own speeds.",
     },
     ja: {
         simulated: "シミュレーションによるレースです。架空のマシンとドライバーで、シード値から計算しています。実在のレース・ドライバー・チームとは関係ありません。",
+        feedNote: "選んだフィードのレースです。名前、タイム、結果はフィードのもので、このページの中だけに表示します。フィードが示す時刻の間は、各マシンがそのコースの速度で走るものとして計算しています。",
         lap: "{lap} / {laps}周",
         finalLap: "ファイナルラップ",
         flag: "チェッカーフラッグ",
@@ -40,5 +43,6 @@ export const RACE_WORDS = Object.freeze({
         leads: "{lap}周目、{name}がトップ。",
         wins: "チェッカーフラッグ：{name}が優勝。",
         description: "架空のマシン{cars}台が、グリッドからチェッカーフラッグまで{laps}周を走ります。実際のレースではなく、シミュレーションです。",
+        fromFeed: "選んだフィードから、{cars}台のマシンが{laps}周を走ります。フィードが示す時刻の間の各マシンの位置は、そのコースの速度から計算しています。",
     },
 });

package/dist/turn.camera.d.ts

@@ -78,11 +78,14 @@ export declare function nudge(view: TurnView, toward: TurnToward, amount: number
  * yaw falls) and a drag down tips the top toward the eye (the pitch falls).
  */
 export declare function drag(view: TurnView, dx: number, dy: number, tilt?: boolean, degreesPerPixel?: number): TurnView;
+/** Wheel steps closer together than this, in milliseconds, are one turn of the wheel or one swipe (with its glide). */
+export declare const WHEEL_GESTURE_MS = 300;
 /**
- * The view after the wheel turns by `deltaY` (positive is down, as `WheelEvent.deltaY` says) while the view has focus: the wheel up tips the surface as a drag up does (the near edge goes up, the
- * front is lifted: the pitch rises) and the wheel down as a drag down does.
+ * The view after the wheel turns by `deltaY` (positive is down, as `WheelEvent.deltaY` says; `deltaMode` 1 is lines and 2 is pages): the wheel up zooms in and the wheel down zooms out,
+ * about the view's middle, as the pinch and the buttons do (the view has no pan). A trackpad's pinch (`pinch`: it arrives as Ctrl and the wheel) comes in small steps; a plain wheel's
+ * notch is about 100 pixels and zooms about 1.2 times, as the + key does, and one step of it never zooms more than twice either way.
  */
-export declare const wheelTip: (view: TurnView, deltaY: number) => TurnView;
+export declare function wheelZoom(view: TurnView, deltaY: number, deltaMode?: number, pinch?: boolean): TurnView;
 /** A box in the scene, in pixels from the scene's middle, the floor at `z0` and the highest thing at `z1`. */
 export interface Box3 {
     x0: number;

package/dist/turn.camera.js

@@ -100,11 +100,18 @@ export function nudge(view, toward, amount) {
 export function drag(view, dx, dy, tilt = true, degreesPerPixel = 0.4) {
     return clampView({ ...view, yaw: view.yaw - dx * degreesPerPixel, pitch: tilt ? view.pitch - dy * degreesPerPixel * 0.75 : view.pitch });
 }
+/** Wheel steps closer together than this, in milliseconds, are one turn of the wheel or one swipe (with its glide). */
+export const WHEEL_GESTURE_MS = 300;
 /**
- * The view after the wheel turns by `deltaY` (positive is down, as `WheelEvent.deltaY` says) while the view has focus: the wheel up tips the surface as a drag up does (the near edge goes up, the
- * front is lifted: the pitch rises) and the wheel down as a drag down does.
+ * The view after the wheel turns by `deltaY` (positive is down, as `WheelEvent.deltaY` says; `deltaMode` 1 is lines and 2 is pages): the wheel up zooms in and the wheel down zooms out,
+ * about the view's middle, as the pinch and the buttons do (the view has no pan). A trackpad's pinch (`pinch`: it arrives as Ctrl and the wheel) comes in small steps; a plain wheel's
+ * notch is about 100 pixels and zooms about 1.2 times, as the + key does, and one step of it never zooms more than twice either way.
  */
-export const wheelTip = (view, deltaY) => clampView({ ...view, pitch: view.pitch - deltaY * 0.15 });
+export function wheelZoom(view, deltaY, deltaMode = 0, pinch = false) {
+    const pixels = deltaMode === 1 ? deltaY * (pinch ? 5 : 33) : deltaMode === 2 ? deltaY * 800 : deltaY;
+    const factor = pinch ? Math.exp(clamp(-pixels * 0.01, -10, 10)) : clamp(Math.exp(-pixels * 0.002), 0.5, 2);
+    return clampView({ ...view, zoom: view.zoom * factor });
+}
 const RAD = Math.PI / 180;
 /** Where a point of the scene falls on the screen, in pixels from the middle of the container, when the scene is placed as given and the eye is `distance` pixels away. */
 export function project(point, view, at, distance) {

package/dist/turn.dom.js

@@ -1,10 +1,10 @@
 // The 3D view in a page: `mountKyogijoTurn` writes the scene (`turn.markup.ts`) into a container and makes it turn, as the cube of kyuubu turns: a drag turns and
-// tips it, a pinch or Ctrl and the wheel zoom, the arrow keys step it, four viewpoints and a reset are a button or a number key away, a reader who prefers
+// tips it, the wheel or a pinch zooms, the arrow keys step it, four viewpoints and a reset are a button or a number key away, a reader who prefers
 // reduced motion gets jumps for glides, and where the browser cannot draw in 3D the flat drawing stays. Nothing is polled and nothing runs while the view is
 // still: the elements' `transform`s are written when the view changes, and a glide between viewpoints is a short run of animation frames.
 import { displayProbe, frameBatch } from "./turn.frames.js";
 import { drawKyogijo } from "./draw.js";
-import { STEP, TURN_PRESET_NAMES, clampView, drag, nearest, nudge, presetOf, presetView, step, turnDirection, viewScale, wheelTip } from "./turn.camera.js";
+import { STEP, TURN_PRESET_NAMES, clampView, drag, nearest, nudge, presetOf, presetView, step, turnDirection, viewScale, wheelZoom, WHEEL_GESTURE_MS, ZOOM_MAX, ZOOM_MIN } from "./turn.camera.js";
 import { buildTurn, floorOptions, openingView, turnWords } from "./turn.model.js";
 import { controlsMarkup, layoutOf, turnMarkupOf, worldMarkup } from "./turn.markup.js";
 import { KYOGIJO_TURN_STYLE } from "./turn.style.js";
@@ -656,20 +656,33 @@ export function mountTurn(host, options, settings, build, replayable = false, le
     stage.addEventListener("pointerup", onUp);
     stage.addEventListener("pointercancel", onUp);
     stage.addEventListener("dblclick", toOpening);
-    // ---- The wheel: Ctrl and the wheel (a pinch on a trackpad) zoom; with the view focused the wheel tips and turns it; otherwise the page scrolls as ever. ----
+    // ---- The wheel over the view zooms it, as a map does; with the pointer anywhere else the page scrolls. Ctrl or Command and the wheel (a pinch on a trackpad) zoom too. Shift and the
+    // wheel, or a sideways swipe, turn it. Tipping is a drag, the keys and the buttons. A wheel that starts while the zoom is already at its end that way goes on to scroll the page, so the page is
+    // never trapped; one that reaches the end part-way through stops there rather than flinging the page. ----
+    let wheelTaken = Number.NEGATIVE_INFINITY;
     const onWheel = (event) => {
-        if (event.ctrlKey) {
+        const pinch = event.ctrlKey || event.metaKey;
+        const now = Number.isFinite(event.timeStamp) ? event.timeStamp : 0;
+        const continuing = now >= wheelTaken && now - wheelTaken < WHEEL_GESTURE_MS;
+        if (!pinch && (event.shiftKey || Math.abs(event.deltaX) > Math.abs(event.deltaY))) {
             event.preventDefault();
+            wheelTaken = now;
             grab();
-            view = clampView({ ...view, zoom: view.zoom * Math.exp(-event.deltaY * 0.01) });
+            view = clampView({ ...view, yaw: view.yaw + (event.deltaX || event.deltaY) * 0.25 });
         }
-        else if (doc.activeElement === stage) {
+        else {
+            const next = wheelZoom(view, event.deltaY, event.deltaMode, pinch);
+            const atEnd = event.deltaY <= 0 ? view.zoom >= ZOOM_MAX : view.zoom <= ZOOM_MIN;
+            // Ctrl and the wheel is always the view's, or the browser would zoom the whole page.
+            if (!pinch && atEnd && !continuing)
+                return;
             event.preventDefault();
+            wheelTaken = now;
+            if (next.zoom === view.zoom)
+                return;
             grab();
-            view = event.shiftKey || Math.abs(event.deltaX) > Math.abs(event.deltaY) ? clampView({ ...view, yaw: view.yaw + (event.deltaX || event.deltaY) * 0.25 }) : wheelTip(view, event.deltaY);
+            view = next;
         }
-        else
-            return;
         shown = view;
         paint(shown);
         label();

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** The package's version: the same as package.json's, and a test holds them to each other. */
-export declare const VERSION = "0.55.0";
+export declare const VERSION = "0.57.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** The package's version: the same as package.json's, and a test holds them to each other. */
-export const VERSION = "0.55.0";
+export const VERSION = "0.57.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/kyogijo-stadiums",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "description": "Kyogijo Stadiums 競技場, 40 sports' surfaces as SVG, drawn to scale from the rulebooks: NFL, CFL and IFAF football fields, an NHL rink, an NBA court, MLB ballparks, soccer pitches, curling sheets, athletics stadiums, speed skating, short track and figure skating rinks, swimming pools, water polo fields, diving wells, artistic swimming areas, and the courts and fields of tennis, volleyball (indoor, beach and sitting), badminton, pickleball, table tennis, padel, squash, racquetball, sepak takraw, teqball, roundnet, netball, lacrosse, rugby, Australian football, Gaelic games, cricket, field hockey and handball, and the budo of judo, karate, kendo, sumo and kyudo with a dojo of tatami laid as real units, the MMA cage, with each team's name and logo on its side and the score in the middle, stands and a crowd, a pageant of flags, and a 3D view. Light and dark, accessible, a compact badge for lists, a helper for React and a custom element. Zero dependencies.",
   "keywords": [
     "sports",