@johnmorrisdotca/kyogijo-stadiums 0.54.0 → 0.56.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [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
+
+- **A simulated race on a circuit (KYOGIJO-STADIUMS-32)** ([a race](./docs/circuits.md#a-race)): twenty made-up cars as dots from the grid to the chequered flag over a full race distance (50 laps of Las Vegas, about an hour and twenty-two minutes), with gaps, passes, trains, one or two pit stops each and now and then a retirement, all from a seed. `simulateRace` works it out (the lap's speeds from the bends, `paceProfile`), `raceAt` gives any moment (the order, the gaps to the leader and the car in front, the last and best laps, the stops), `drawRace` and `raceBoard` draw it, and `mountCircuitRace` plays it in a page, flat or in 3D (the cars standing as discs), with a race clock, play, 1×, 10× and 60×, a slider over the whole race and the timing board, in English and Japanese. It is labelled a simulation: every team, driver, code and colour is invented, and no real race is in it; the model's figures were guided by public timing data read once and kept outside the package. Nothing runs while it is paused, hidden or out of sight, the 3D view's auto-turn and the race share one frame, and destroy leaves nothing. The demo's circuits page has a **Race** button, kept in the address with the speed and the moment.
+
 ## [0.54.0] - 2026-11-03
 
 ### Added

package/README.md

@@ -114,6 +114,13 @@ Real buildings drawn in the outline OpenStreetMap maps for them, each with a pla
 </picture>
 <br><em>The same lap in 3D</em>
 </td>
+<td align="center" valign="top">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kyogijo-stadiums/main/docs/images/circuits-race-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kyogijo-stadiums/main/docs/images/circuits-race-desk-light.webp" alt="A simulated race on the same circuit half an hour in: twenty coloured dots with their positions, the race clock at Lap 18 of 50 and the timing board under it." width="250">
+</picture>
+<br><em>A simulated race, with its clock and timing board</em>
+</td>
 </tr>
 </table>
 
@@ -247,7 +254,8 @@ console.log(svg.startsWith("<svg"), svg.includes("USA 3, Canada 2"));
 - **A catalogue of venues**: every venue drawn today, the ones being built and the ones wanted (every NBA, MLB, NFL, CFL and NHL venue of the season, world soccer, cricket, rugby, the Olympics, Formula One and more), with ids, names in English and Japanese and Wikidata items, as a [JSON file](https://johnmorrisdotca.github.io/kyogijo-stadiums/catalogue.json) and a typed entry. [The catalogue](./docs/catalogue.md).
 - **Real venues**: arenas and stadiums in the outline of their buildings, districts of several venues on one plan, the crowd in the stands and outside. [Ballparks](./docs/ballparks.md), [venues](./docs/venues.md), [districts](./docs/district.md).
 - **A 3D view** of any surface or venue that turns by mouse, touch or keys, with the roof and the walls to switch and a quality level for every device. [The 3D view](./docs/turn.md), [quality](./docs/quality.md).
-- **Circuits**: a famous race track as OpenStreetMap maps it, the Las Vegas Strip Circuit first, with its turns numbered and its pit building standing in 3D. [Circuits](./docs/circuits.md).
+- **Circuits**: a famous race track as OpenStreetMap maps it, the Las Vegas Strip Circuit first, with its turns numbered and its pit building standing in 3D, and a simulated race on it: twenty made-up cars over a full race distance, with a race clock, a timing board and 1×, 10× and 60×. [Circuits](./docs/circuits.md#a-race).
+- **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).
@@ -262,7 +270,7 @@ console.log(svg.startsWith("<svg"), svg.includes("USA 3, Canada 2"));
 | `drawKyogijo`, `drawSurface`, `drawScore`, `drawBadge` | The drawing, as a string of SVG. |
 | `SPORTS`, `PARKS`, `COURT_THEMES`, `SOCCER_PITCHES`, `GROUNDS`, `EVENTS` | The forty-three sports, the 94 ballparks, the court looks, the pitches, the 64 grounds, the 18 special games. |
 | `./venues`, `./stadiums`, `./district`, `./turn` | Real arenas and stadiums in their buildings' outlines; districts on one plan; a surface as a 3D view that turns. |
-| `./circuits` | Race tracks as OpenStreetMap maps them, in 2D and 3D ([demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/circuits.html)). |
+| `./circuits` | Race tracks as OpenStreetMap maps them, in 2D and 3D, and a simulated race on them with its clock and timing board ([demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/circuits.html?race=1)). |
 | `./multi`, `./judging`, `./layouts` | Several surfaces for one event ([demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/halls.html)); who judges where; small multiples and backgrounds. |
 | `./layers`, `./charts`, `./frames`, `./zones`, `./pointer`, `./replay` | Data layers, charts, the providers' frames, zones by the rules, a click as a place, tracking data played on a surface. |
 | `./athletics`, `./budo`, `./skating` | The athletics stadium, the budō (areas, dohyō, the dojo builder) and the skating rinks. |

package/catalogue.json

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

package/dist/circuits-entry.d.ts

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

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