@johnmorrisdotca/kyogijo-stadiums 0.61.0 → 0.63.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.63.0] - 2026-11-03
+
+### Added
+
+- **Drop feed files on the demo, kept in the browser (KYOGIJO-STADIUMS-52)** ([feeds](./docs/feeds.md#in-the-demo)): drop one or more feed files (an NHL play-by-play file as the public answer has it, or a kyogijo timeline) on the game section's feed panel or its view, or choose several; the first good one plays, a file that is not a feed is refused by name, and every feed is kept in this browser (localStorage up to about 4 MB in all, IndexedDB past that), listed with its game, file, sport, date and size, with Play, Remove, Remove all and the space used, and still there after a reload. A whole folder can be dropped: files are read one at a time with progress, up to 200 at once and 200 MB kept in all; more is refused in words. Written only on a drop, a choice or a removal; nothing leaves the browser, and a browser that keeps nothing still plays the feed. The adapter is tested on an invented answer in the raw play-by-play shape (`src/feeds.nhl.stub.json`).
+- **Bring your own feed: a file or a paste (KYOGIJO-STADIUMS-37)** ([feeds](./docs/feeds.md)): a new entry, `/feeds`, reads a game from a feed into a replay. `readFeed` and `readFeedText` read kyogijo's open timeline (a bare timeline or a game file, with its stoppages and penalties, so that the game clock stops where the replay's does; every value checked, every list capped) and, through a pure adapter, `nhlPlayByPlay`, a play-by-play shaped as the NHL's public one: the puck moved between the plays' places, the shots, goals and whistles, the periods on the game's clock and the sides and players named from the feed at run time. A `FeedError` says what was wrong. The demo's game section has **Bring your own feed**: choose a file or paste a feed, and it plays with the score, the period and the clock on the board.
+- **Bring your own feed: an address, and where to find one (KYOGIJO-STADIUMS-37)** ([where to find a feed](./docs/where-to-find-a-feed.md)): with `/feeds` loaded, every mount's and 3D view's `replay` has `fromUrl(url, { format })`, fetched by the reader's browser with no cookie, no referrer and no cache, through no server of ours; `loadFeed` and `feedAddress` do it alone, and a refusal (CORS), a status or an answer too large is said plainly. The one list of where to find a feed, `examples/feeds/where-to-find.json`, has ice hockey beside racing (our made-up sample first, then the NHL's public play-by-play), with what each gives, a sample address, how to find a game, its docs and its terms; the docs page covers both sports in English and Japanese, and the demo's list beside the address field reads it, where **Use** fills the field.
+- **Bring your own feed: live (KYOGIJO-STADIUMS-37)**: `replay.follow(url)` and `followFeed` ask the address every 15 seconds (never less than 10) only while the page is shown, play each answer that changed from where the reader was, wait twice as long after an error, and stop when the game is over or the server says 403 or 429. The demo has **Follow live**.
+
+## [0.62.0] - 2026-11-03
+
+### Added
+
+- **Penalties, power plays and the penalty box (KYOGIJO-STADIUMS-48)** ([penalties](./docs/replay.md#penalties-and-the-power-play)): a penalty in a replay is a stoppage with the face-off in the offending side's end; the penalized player skates to his side's penalty box, across the ice from the benches, and sits there for the penalty's time on the game clock while his side plays a skater short (two for overlapping penalties, never below three skaters), then comes back into the play. A timeline has `penalties` now; the board over the arena shows each side's strength and each penalty's clock (the time left in the short side's block of colour, PP in the other's), and `replayBoard` gives `strength` and `penalties`. One rule set, in `/replay`: `hockeyPenaltyEnds` (a minor 2 minutes, a double minor 4, a major 5, a misconduct 10 with a substitute; a power-play goal ends a minor but not a major; coincidental penalties keep the strength even; a third penalty waits), `hockeyPenaltyKind` (the NHL play-by-play's kinds), `hockeyPenaltyBox` (a stand-in for the rink's own boxes), `penaltiesAt` and `replayGameTime`. The example game has its seven penalties (`examples/games/canada-japan.json`, 1.1 MB). Players on the bench are not drawn.
+
+### Fixed
+
+- **Stoppages play like hockey (KYOGIJO-STADIUMS-45)** ([stoppages](./docs/replay.md#stoppages-the-clock-stops-the-players-line-up)): after a goal the example game no longer moves the puck from the net to centre ice as if it were passed. A timeline has `stoppages` now: in each the game clock stands still (the board over the arena shows the same time from the goal to the drop) while the replay's own clock moves on, the puck is dead (it stays where play stopped, in the net after a goal, then is out of sight until the drop), and the players glide to the face-off's line-up at the spot the rules give, a line going off by its bench; the clock runs again at the drop. One rule set for hockey, in `/replay`: `hockeyFaceoffDot` (centre after a goal and at a period's start, the end-zone spot after a save or a frozen puck, the offending side's end after icing or a penalty, the neutral-zone spot after offside, the nearest spot in the zone otherwise), `hockeyFormation` (the line-up of Rule 76), `HOCKEY_DEAD_TIME` and `HOCKEY_RULES` (the speeds and seconds), `hockeyStopOf` (the NHL play-by-play's words), and, for any sport, `addDeadTime`, `replayGameClock`, `replayStoppages`, `stoppageAt` and `restartsBetween`. A `faceoff` event is said at each drop and draws no mark. A trail begins again after a frame its object is not in. `examples/games/canada-japan.json` is made again with the rules: 66 stoppages, about fifteen minutes, 1.1 MB (was 1.3 MB). The other sports' dead time is planned in the docs, not built.
+
 ## [0.61.0] - 2026-11-03
 
 ### Added

package/README.md

@@ -159,7 +159,7 @@ Real buildings drawn in the outline OpenStreetMap maps for them, each with a pla
 <td align="center" valign="top">
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kyogijo-stadiums/main/docs/images/replay-game-3d-desk-dark.webp">
-<img src="https://raw.githubusercontent.com/johnmorrisdotca/kyogijo-stadiums/main/docs/images/replay-game-3d-desk-light.webp" alt="A made-up game of Canada and Japan replayed on the rink in 3D from the main camera: the players standing up as discs with their numbers, red circles and blue squares, the score hung over centre ice, and a shot's arrow and a whistle's cross on the ice." width="250">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kyogijo-stadiums/main/docs/images/replay-game-3d-desk-light.webp" alt="A made-up game of Canada and Japan replayed on the rink in 3D from the main camera: the players standing up as discs with their numbers, red circles and blue squares, the score hung over centre ice, and a goal's arrow into the net." width="250">
 </picture>
 <br><em>A made-up game, replayed in 3D</em>
 </td>
@@ -182,7 +182,7 @@ Real buildings drawn in the outline OpenStreetMap maps for them, each with a pla
 
 A camera can follow the play, flat or in 3D: it closes in where the action is and pulls back as the players spread, or moves with the puck, while the view goes on turning ([following the play](./docs/replay.md#following-the-play)).
 
-The scoreboard hung over an arena's ice follows the replay: its score, period and game clock come from the same timeline and clock as the controls ([the scoreboard over the arena](./docs/replay.md#the-scoreboard-over-the-arena-follows-the-game)).
+The scoreboard hung over an arena's ice follows the replay: its score, period and game clock come from the same timeline and clock as the controls ([the scoreboard over the arena](./docs/replay.md#the-scoreboard-over-the-arena-follows-the-game)). In a stoppage its clock stands still while the players glide to the face-off's line-up and the dead puck is out of sight, and it runs again at the drop ([stoppages](./docs/replay.md#stoppages-the-clock-stops-the-players-line-up)). A penalized player sits in his box for his time while his side plays short, and the board shows the power play and each penalty's clock ([penalties](./docs/replay.md#penalties-and-the-power-play)).
 
 **Surfaces** ([the surfaces](./docs/surfaces.md), [score and layout](./docs/score.md))
 
@@ -259,7 +259,7 @@ console.log(svg.startsWith("<svg"), svg.includes("USA 3, Canada 2"));
 - **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×; on a district's ground beside T-Mobile Arena among the Strip, with the Sphere, the High Roller and the Fountains of Bellagio, where the race runs too. [Circuits](./docs/circuits.md#a-race), [Las Vegas](./docs/district.md#las-vegas-a-circuit-on-the-ground-and-the-strips-landmarks), [a race on the Strip](./docs/district.md#a-race-on-the-strip).
 - **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).
+- **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). Bring your own feed: a game from a file (drop several, kept in your browser), a paste or an address your browser fetches, live or after the game ([feeds](./docs/feeds.md), [where to find a feed](./docs/where-to-find-a-feed.md)).
 - **Sound**: the crowd of each kind of venue at a level from quiet to a roar, heard in the room its venue makes, and its game's sounds (the goal horn, the whistle, the buzzer, the bell) from a replay or live events; made in the browser, off until turned on. [Sound](./docs/sound.md).
 - **Looks and flags**: eight named looks, a flag or crest on each half, trophies and crests from Dougu Sports, flags from Hata, light and dark. [Theming](./docs/theming.md), [the pageant](./docs/pageant.md).
 - **Four ways in**: a function that returns SVG text, a helper that draws into a container, a custom element, a frame for pages with no script; renderers for a canvas, d3, Observable Plot, GeoJSON and PNG. [Entry points](./docs/entry-points.md), [renderers](./docs/renderers.md).
@@ -277,6 +277,7 @@ console.log(svg.startsWith("<svg"), svg.includes("USA 3, Canada 2"));
 | `./multi`, `./judging`, `./layouts` | Several surfaces for one event ([demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/halls.html)); who judges where; small multiples and backgrounds. |
 | `./layers`, `./charts`, `./frames`, `./zones`, `./pointer`, `./replay` | Data layers, charts, the providers' frames, zones by the rules, a click as a place, tracking data played on a surface. |
 | `./sound` | A surface's crowd and its game's sounds, made in the browser with Web Audio ([demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/venues.html?sound=on)). |
+| `./feeds` | A game from a feed (kyogijo's open timeline, an NHL-style play-by-play) read into a replay; `replay.fromUrl` and `replay.follow`. |
 | `./athletics`, `./budo`, `./skating` | The athletics stadium, the budō (areas, dohyō, the dojo builder) and the skating rinks. |
 | `./scene`, `./canvas`, `./d3`, `./plot`, `./geojson`, `./png` | The drawing as data, on a canvas, in d3, as an Observable Plot mark, as GeoJSON, as a PNG. |
 | `./mount`, `./react`, `./element`, `./element/define` | Draw into a container; React props; the `<kyogijo-field>` element and its registration. |

package/catalogue.json

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

package/dist/feeds-entry.d.ts

@@ -0,0 +1,7 @@
+import "./feeds.dom.ts";
+export { FEED_FORMATS, FEED_LIMITS, FeedError, feedFormatOf, feedText, kyogijoFeed, readFeed, readFeedText } from "./feeds.ts";
+export type { FeedFormat, FeedGame, FeedPlayer, FeedSide } from "./feeds.ts";
+export { NHL_OVERTIME, NHL_PERIOD, nhlPlayByPlay } from "./feeds.nhl.ts";
+export { FEED_MOST, FOLLOW_EVERY, feedAddress, fetchFeedText, followFeed, loadFeed } from "./feeds.fetch.ts";
+export type { FeedFetchOptions, FeedFollow, FeedFollowOptions, FeedFollowState } from "./feeds.fetch.ts";
+export type { FeedReplay, FeedReplayOptions, ReplayCall, ReplayFollow, ReplayFollowOptions } from "./replay.feed.ts";

package/dist/feeds-entry.js

@@ -0,0 +1,6 @@
+// Feeds: a game from a file, pasted text or an address the reader gives, read into a replay. kyogijo's own open timeline, and adapters (pure functions) for common play-by-play shapes; the fetch is the reader's browser's,
+// and a live follow asks no faster than every ten seconds, only while the page is shown. Loading this entry also gives every mount's and 3D view's `replay` its `fromUrl` and `follow`.
+import "./feeds.dom.js";
+export { FEED_FORMATS, FEED_LIMITS, FeedError, feedFormatOf, feedText, kyogijoFeed, readFeed, readFeedText } from "./feeds.js";
+export { NHL_OVERTIME, NHL_PERIOD, nhlPlayByPlay } from "./feeds.nhl.js";
+export { FEED_MOST, FOLLOW_EVERY, feedAddress, fetchFeedText, followFeed, loadFeed } from "./feeds.fetch.js";

package/dist/feeds.core.d.ts

@@ -0,0 +1,55 @@
+import type { ReplayTimeline } from "./replay.types.ts";
+/** The shapes a feed can be read in: `kyogijo` (the open timeline, or a game file), `nhl` (a play-by-play shaped as the NHL's public one), or `auto` to tell them apart. */
+export type FeedFormat = "auto" | "kyogijo" | "nhl";
+/** The formats there are, `auto` first. */
+export declare const FEED_FORMATS: readonly FeedFormat[];
+/** A player a feed names: its side, its number and its name, as the feed gives them (at run time only). */
+export interface FeedPlayer {
+    side: "home" | "away";
+    number?: number | string;
+    name?: string;
+}
+/** A side of a feed's game, as the feed names it (at run time only): its letters, its name and its colour. */
+export interface FeedSide {
+    abbr?: string;
+    name?: string;
+    color?: string;
+}
+/** A feed read into a game. */
+export interface FeedGame {
+    /** The format it was read in. */
+    format: Exclude<FeedFormat, "auto">;
+    /** The sport whose surface it is played on, when the feed says (`nhl`). */
+    sport?: string;
+    /** The replay: frames, events, and the periods for a scoreboard. */
+    timeline: ReplayTimeline;
+    /** The two sides as the feed names them. */
+    teams: {
+        home: FeedSide;
+        away: FeedSide;
+    };
+    /** Whether the feed says the game is over: a live follow stops then. */
+    ended: boolean;
+    /** The players the feed names, by the id the events use in `by`. */
+    players: Record<string, FeedPlayer>;
+}
+/** Why a feed could not be read. */
+export declare class FeedError extends Error {
+    /** `format`: not a feed of the format; `empty`: nothing to play; `cors`, `network`, `http`, `too-large`, `address`: from the fetch (`feeds.fetch.ts`). */
+    readonly kind: "format" | "empty" | "cors" | "network" | "http" | "too-large" | "address";
+    /** The HTTP status, for `http`. */
+    readonly status?: number;
+    constructor(kind: FeedError["kind"], message: string, status?: number);
+}
+/** The most a feed may hold: more is cut off, so that a hostile or broken answer cannot hold the page. */
+export declare const FEED_LIMITS: {
+    readonly frames: 200000;
+    readonly objects: 64;
+    readonly events: 50000;
+    readonly periods: 20;
+    readonly stoppages: 5000;
+    readonly penalties: 1000;
+    readonly text: 80;
+};
+/** Text from a feed: a string, without control characters, cut to a length. */
+export declare const feedText: (value: unknown, most?: number) => string | undefined;

package/dist/feeds.core.js

@@ -0,0 +1,21 @@
+/** The formats there are, `auto` first. */
+export const FEED_FORMATS = ["auto", "kyogijo", "nhl"];
+/** Why a feed could not be read. */
+export class FeedError extends Error {
+    constructor(kind, message, status) {
+        super(message);
+        this.name = "FeedError";
+        this.kind = kind;
+        if (status !== undefined)
+            this.status = status;
+    }
+}
+/** The most a feed may hold: more is cut off, so that a hostile or broken answer cannot hold the page. */
+export const FEED_LIMITS = { frames: 200000, objects: 64, events: 50000, periods: 20, stoppages: 5000, penalties: 1000, text: 80 };
+/** Text from a feed: a string, without control characters, cut to a length. */
+export const feedText = (value, most = FEED_LIMITS.text) => {
+    if (typeof value !== "string")
+        return undefined;
+    const clean = [...value].filter((ch) => ch.charCodeAt(0) >= 32 && ch.charCodeAt(0) !== 127).join("").trim().slice(0, most);
+    return clean === "" ? undefined : clean;
+};

package/dist/feeds.d.ts

@@ -0,0 +1,26 @@
+import { type FeedFormat, type FeedGame } from "./feeds.core.ts";
+export { FEED_FORMATS, FEED_LIMITS, FeedError, feedText } from "./feeds.core.ts";
+export type { FeedFormat, FeedGame, FeedPlayer, FeedSide } from "./feeds.core.ts";
+/**
+ * Read kyogijo's own open timeline: a bare timeline (`{ frames, events?, periods?, stoppages?, penalties?, teams?, from? }`) or a game file (`{ kind: "kyogijo-game", sport, teams, periods, timeline }`, as
+ * `examples/games` has them). Every frame, object, event, period, stoppage and penalty is checked; what is not of the format is left out, and a timeline with no frame is an error.
+ */
+export declare function kyogijoFeed(json: unknown): FeedGame;
+/** Which format a feed's answer is in: a timeline or a game file of kyogijo's, or a play-by-play shaped as the NHL's. `undefined` when it is neither. */
+export declare function feedFormatOf(json: unknown): Exclude<FeedFormat, "auto"> | undefined;
+/**
+ * Read a feed's answer into a game: in the format asked, or the one `feedFormatOf` finds. Throws a `FeedError` (`format`, `empty`) that says what was wrong in plain words.
+ * @example
+ * ```ts
+ * import { readFeed } from "@johnmorrisdotca/kyogijo-stadiums/feeds";
+ * const answer = { frames: [{ t: 0, objects: [{ id: "puck", team: "puck", x: 0, y: 0 }] }, { t: 30, objects: [{ id: "puck", team: "puck", x: 80, y: 4 }] }], events: [{ t: 30, kind: "goal", team: "home" }], from: "nhl-api" };
+ * const game = readFeed(answer);
+ * console.log(game.format, game.timeline.frames.length, game.timeline.events?.length);
+ * try { readFeed({ hello: "world" }); } catch (error) { console.log((error as Error).name, (error as { kind?: string }).kind); }
+ * // kyogijo 2 1
+ * // FeedError format
+ * ```
+ */
+export declare function readFeed(json: unknown, format?: FeedFormat): FeedGame;
+/** Read text (a file or what was pasted) as JSON and then as a feed. */
+export declare function readFeedText(text: string, format?: FeedFormat): FeedGame;

package/dist/feeds.dom.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/feeds.dom.js

@@ -0,0 +1,34 @@
+// A feed played on a mount or a 3D view: `replay.fromUrl` fetches it once and plays it, `replay.follow` follows it live and plays each answer that changed, from where the reader was. Loaded by the `/feeds` entry, it
+// puts its code into every `replay` (`replay.feed.ts`).
+import { followFeed, loadFeed } from "./feeds.fetch.js";
+import { useFeedKit } from "./replay.feed.js";
+const kit = {
+    async fromUrl(play, url, options = {}) {
+        const feed = await loadFeed(url, options);
+        return Object.assign(play(feed.timeline, options.settings), { feed });
+    },
+    follow(play, url, options = {}) {
+        let replay;
+        const follow = followFeed(url, {
+            ...options,
+            onGame(game) {
+                // From where the reader was; at the newest moment when it was there (or when it is the first answer).
+                const at = replay?.state();
+                const edge = at === undefined || at.t >= at.end - 0.5;
+                replay?.destroy();
+                replay = play(game.timeline, { ...options.settings, ...(edge ? { start: Number.MAX_SAFE_INTEGER } : { start: at.t - at.start, speed: at.speed }) });
+                if (at?.playing === true && !edge)
+                    replay.play();
+                options.onGame?.(game, replay);
+            },
+            onError: options.onError,
+            onState: options.onState,
+        });
+        return {
+            replay: () => replay,
+            state: follow.state,
+            stop: follow.stop,
+        };
+    },
+};
+useFeedKit(kit);

package/dist/feeds.fetch.d.ts

@@ -0,0 +1,62 @@
+import { FeedError, type FeedFormat, type FeedGame } from "./feeds.core.ts";
+/** What a fetch of a feed can be told. */
+export interface FeedFetchOptions {
+    /** The format to read the answer in; `auto` (the default) tells the formats apart. */
+    format?: FeedFormat;
+    /** The address a relative one is read against: the page's own by default. */
+    base?: string;
+    /** The most an answer may be, in bytes: 20 MB by default. */
+    most?: number;
+    /** Stop the request. */
+    signal?: AbortSignal;
+    /** The function that fetches: the browser's own `fetch` by default (a test gives its own). */
+    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+}
+/** The most an answer may be, by default: 20 MB. */
+export declare const FEED_MOST: number;
+/** An address the reader gave, as a URL: `http` or `https` only (a relative address is read against the page's). Throws a `FeedError` (`address`) for anything else. */
+export declare function feedAddress(url: string, base?: string): URL;
+/** Fetch an address's answer as text, by the reader's browser: no cookie, no referrer, no cache. */
+export declare function fetchFeedText(url: string, options?: Omit<FeedFetchOptions, "format">): Promise<string>;
+/**
+ * Fetch a feed from an address the reader gave and read it into a game. Throws a `FeedError` that says what was wrong: `address`, `cors`, `network`, `http` (with its `status`), `too-large`, `format` or `empty`.
+ * @example
+ * ```ts
+ * import { loadFeed } from "@johnmorrisdotca/kyogijo-stadiums/feeds";
+ * const stub = async () => new Response(JSON.stringify({ frames: [{ t: 0, objects: [] }, { t: 5, objects: [] }] }));
+ * const game = await loadFeed("https://example.com/feed.json", { fetch: stub });
+ * console.log(game.format, game.timeline.frames.length);
+ * const refused = async () => { throw new TypeError("Failed to fetch"); };
+ * await loadFeed("https://example.com/feed.json", { fetch: refused }).catch((error) => console.log(error.kind));
+ * // kyogijo 2
+ * // cors
+ * ```
+ */
+export declare function loadFeed(url: string, options?: FeedFetchOptions): Promise<FeedGame>;
+/** What a live follow can be told, beyond a fetch's options. */
+export interface FeedFollowOptions extends FeedFetchOptions {
+    /** Seconds between asks: 15 by default, never less than 10. */
+    every?: number;
+    /** A new answer, read: only when it differs from the one before. */
+    onGame?: (game: FeedGame) => void;
+    /** An answer that could not be had or read. The follow goes on, waiting longer, unless it is a 403 or a 429. */
+    onError?: (error: FeedError) => void;
+    /** Told each time the follow's state changes. */
+    onState?: (state: FeedFollowState) => void;
+    /** The document whose visibility it follows: the page's by default. */
+    doc?: Document;
+}
+/** What a follow is doing: `asking`, `waiting` for the next ask, `hidden` (the page is not shown: no ask until it is), `ended` (the game is over), `refused` (403 or 429) or `stopped`. */
+export type FeedFollowState = "asking" | "waiting" | "hidden" | "ended" | "refused" | "stopped";
+/** A live follow: its state, and a way to stop it. */
+export interface FeedFollow {
+    state(): FeedFollowState;
+    stop(): void;
+}
+/** The least and the greatest wait between asks, in seconds. */
+export declare const FOLLOW_EVERY: readonly [number, number];
+/**
+ * Follow a feed live: ask the address now and again every `every` seconds (15 by default, never less than 10) while the page is shown, and tell `onGame` of each answer that changed. Asking stops while the page is
+ * hidden and starts again when it is shown; after an error the wait doubles, up to two minutes; a 403 or a 429 stops it (`refused`), and so does a game the feed says is over (`ended`). One timer at most at any time.
+ */
+export declare function followFeed(url: string, options?: FeedFollowOptions): FeedFollow;

package/dist/feeds.fetch.js

@@ -0,0 +1,177 @@
+// A feed fetched by the reader's own browser, from an address the reader gave: never through a server of ours, with no cookie and no referrer, and nothing kept beyond the open page (no cache, no storage).
+// A refusal is said in plain words: a server that does not let another site's page read it (CORS), a status, an answer too large. A live follow asks again no faster than every ten seconds, only while the page
+// is shown, waits longer after an error, and stops when the game is over or the server says no (403, 429).
+import { FeedError } from "./feeds.core.js";
+import { readFeedText } from "./feeds.js";
+/** The most an answer may be, by default: 20 MB. */
+export const FEED_MOST = 20 * 1024 * 1024;
+/** An address the reader gave, as a URL: `http` or `https` only (a relative address is read against the page's). Throws a `FeedError` (`address`) for anything else. */
+export function feedAddress(url, base) {
+    let parsed;
+    try {
+        parsed = new URL(url.trim(), base ?? (typeof location === "undefined" ? undefined : location.href));
+    }
+    catch {
+        throw new FeedError("address", "not an address: give one that starts with https://");
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+        throw new FeedError("address", "only an http or https address can be read");
+    if (parsed.username !== "" || parsed.password !== "")
+        throw new FeedError("address", "an address with a login in it is not read: give the feed's address alone");
+    return parsed;
+}
+/** Fetch an address's answer as text, by the reader's browser: no cookie, no referrer, no cache. */
+export async function fetchFeedText(url, options = {}) {
+    const address = feedAddress(url, options.base);
+    const get = options.fetch ?? ((input, init) => fetch(input, init));
+    const most = options.most ?? FEED_MOST;
+    let answer;
+    try {
+        answer = await get(address.href, { credentials: "omit", cache: "no-store", referrerPolicy: "no-referrer", mode: "cors", redirect: "follow", signal: options.signal });
+    }
+    catch (error) {
+        if (error?.name === "AbortError")
+            throw error;
+        const offline = typeof navigator !== "undefined" && navigator.onLine === false;
+        throw offline
+            ? new FeedError("network", "the browser is offline: the feed could not be reached")
+            : new FeedError("cors", "the browser could not read the answer: the server does not let a page of another site read it (CORS), or it could not be reached. Paste the answer or pick it as a file, or point at a relay of your own");
+    }
+    if (!answer.ok)
+        throw new FeedError("http", `the server answered ${answer.status}${answer.status === 403 || answer.status === 429 ? ": it does not want to be asked now" : ""}`, answer.status);
+    const length = Number(answer.headers.get("content-length"));
+    if (Number.isFinite(length) && length > most)
+        throw new FeedError("too-large", `the answer is ${Math.round(length / 1e6)} MB: more than this page reads`);
+    const text = await answer.text();
+    if (text.length > most)
+        throw new FeedError("too-large", "the answer is larger than this page reads");
+    return text;
+}
+/**
+ * Fetch a feed from an address the reader gave and read it into a game. Throws a `FeedError` that says what was wrong: `address`, `cors`, `network`, `http` (with its `status`), `too-large`, `format` or `empty`.
+ * @example
+ * ```ts
+ * import { loadFeed } from "@johnmorrisdotca/kyogijo-stadiums/feeds";
+ * const stub = async () => new Response(JSON.stringify({ frames: [{ t: 0, objects: [] }, { t: 5, objects: [] }] }));
+ * const game = await loadFeed("https://example.com/feed.json", { fetch: stub });
+ * console.log(game.format, game.timeline.frames.length);
+ * const refused = async () => { throw new TypeError("Failed to fetch"); };
+ * await loadFeed("https://example.com/feed.json", { fetch: refused }).catch((error) => console.log(error.kind));
+ * // kyogijo 2
+ * // cors
+ * ```
+ */
+export async function loadFeed(url, options = {}) {
+    return readFeedText(await fetchFeedText(url, options), options.format);
+}
+/** The least and the greatest wait between asks, in seconds. */
+export const FOLLOW_EVERY = [10, 120];
+/**
+ * Follow a feed live: ask the address now and again every `every` seconds (15 by default, never less than 10) while the page is shown, and tell `onGame` of each answer that changed. Asking stops while the page is
+ * hidden and starts again when it is shown; after an error the wait doubles, up to two minutes; a 403 or a 429 stops it (`refused`), and so does a game the feed says is over (`ended`). One timer at most at any time.
+ */
+export function followFeed(url, options = {}) {
+    const doc = options.doc ?? (typeof document === "undefined" ? undefined : document);
+    const win = doc?.defaultView ?? (typeof window === "undefined" ? undefined : window);
+    const every = Math.min(FOLLOW_EVERY[1], Math.max(FOLLOW_EVERY[0], typeof options.every === "number" && Number.isFinite(options.every) ? options.every : 15));
+    let state = "waiting";
+    let wait = every;
+    let timer;
+    let last = "";
+    let due = 0;
+    let controller;
+    const set = (next) => {
+        if (next === state)
+            return;
+        state = next;
+        options.onState?.(state);
+    };
+    const over = () => state === "ended" || state === "refused" || state === "stopped";
+    /** Stop for good: no timer, no listener, no request. */
+    const finish = (next) => {
+        if (timer !== undefined)
+            (win ?? globalThis).clearTimeout(timer);
+        timer = undefined;
+        controller?.abort();
+        doc?.removeEventListener("visibilitychange", onVisible);
+        set(next);
+    };
+    const hidden = () => doc?.visibilityState === "hidden";
+    const schedule = (seconds) => {
+        if (over())
+            return;
+        due = Date.now() + seconds * 1000;
+        if (hidden()) {
+            set("hidden");
+            return;
+        }
+        set("waiting");
+        timer = (win ?? globalThis).setTimeout(ask, seconds * 1000);
+    };
+    async function ask() {
+        timer = undefined;
+        if (over())
+            return;
+        if (hidden()) {
+            set("hidden");
+            return;
+        }
+        set("asking");
+        controller = typeof AbortController === "function" ? new AbortController() : undefined;
+        try {
+            const text = await fetchFeedText(url, { ...options, signal: controller?.signal ?? options.signal });
+            if (over())
+                return;
+            if (text !== last) {
+                const game = readFeedText(text, options.format);
+                last = text;
+                options.onGame?.(game);
+                if (game.ended) {
+                    finish("ended");
+                    return;
+                }
+            }
+            wait = every;
+            schedule(wait);
+        }
+        catch (error) {
+            if (over())
+                return;
+            if (!(error instanceof FeedError)) {
+                if (error?.name === "AbortError")
+                    return;
+                throw error;
+            }
+            options.onError?.(error);
+            if (error.kind === "http" && (error.status === 403 || error.status === 429)) {
+                finish("refused");
+                return;
+            }
+            if (error.kind === "address") {
+                finish("stopped");
+                return;
+            }
+            wait = Math.min(FOLLOW_EVERY[1], wait * 2);
+            schedule(wait);
+        }
+    }
+    // Shown again: ask now if the time came while it was hidden, else wait for what is left of it.
+    const onVisible = () => {
+        if (over() || hidden() || state !== "hidden")
+            return;
+        const left = Math.max(0, (due - Date.now()) / 1000);
+        if (left === 0)
+            void ask();
+        else
+            schedule(left);
+    };
+    doc?.addEventListener("visibilitychange", onVisible);
+    void ask();
+    return {
+        state: () => state,
+        stop() {
+            if (state !== "stopped")
+                finish("stopped");
+        },
+    };
+}