@johnmorrisdotca/kyogijo-stadiums 0.62.0 → 0.63.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ 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

package/README.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.62.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.62.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");
+        },
+    };
+}

package/dist/feeds.js

@@ -0,0 +1,211 @@
+// A feed of a game read into a replay: kyogijo's own open timeline (a bare timeline, or a game file with its sides and periods) or a play-by-play of a shape that is common, each read by a pure function of
+// its own (an adapter). The answer is the user's: it comes from a file they picked, text they pasted or an address they gave, and nothing in it is trusted. Every number is checked, every list is capped,
+// and a name is only ever text. Nothing here fetches: `feeds.fetch.ts` is the page's side.
+import { FEED_LIMITS, FeedError, feedText } from "./feeds.core.js";
+import { nhlPlayByPlay } from "./feeds.nhl.js";
+export { FEED_FORMATS, FEED_LIMITS, FeedError, feedText } from "./feeds.core.js";
+const TEAMS = ["home", "away", "ball", "puck", "official"];
+const isNum = (value) => typeof value === "number" && Number.isFinite(value);
+const isObj = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A side of a feed's game, as a scoreboard writes it: its letters, name and colour as text. */
+const sideOf = (value) => {
+    if (!isObj(value))
+        return undefined;
+    const name = isObj(value.name) ? feedText(value.name.en ?? Object.values(value.name)[0]) : feedText(value.name);
+    const side = {};
+    const abbr = feedText(value.abbr, 8);
+    const color = feedText(value.color, 32);
+    if (abbr !== undefined)
+        side.abbr = abbr;
+    if (name !== undefined)
+        side.name = name;
+    if (color !== undefined && /^#[0-9a-f]{3,8}$/i.test(color))
+        side.color = color;
+    return side;
+};
+/** An object of a frame, checked: an id, a known team and a place, else nothing. */
+function objectOf(value) {
+    if (!isObj(value) || !isNum(value.x) || !isNum(value.y))
+        return undefined;
+    const id = feedText(value.id, 40);
+    const team = TEAMS.find((t) => t === value.team);
+    if (id === undefined || team === undefined)
+        return undefined;
+    const o = { id, team, x: value.x, y: value.y };
+    const label = feedText(value.label);
+    if (label !== undefined)
+        o.label = label;
+    if (isNum(value.number) || typeof value.number === "string")
+        o.number = typeof value.number === "string" ? (feedText(value.number, 4) ?? "") : value.number;
+    return o;
+}
+/** An event, checked: a time and a kind, and what else it has that is of the right type. */
+function eventOf(value) {
+    if (!isObj(value) || !isNum(value.t))
+        return undefined;
+    const kind = feedText(value.kind, 24);
+    if (kind === undefined)
+        return undefined;
+    const e = { t: value.t, kind };
+    if (value.team === "home" || value.team === "away")
+        e.team = value.team;
+    for (const key of ["x", "y", "x2", "y2", "until"])
+        if (isNum(value[key]))
+            e[key] = value[key];
+    for (const key of ["by", "to"]) {
+        const text = feedText(value[key], 40);
+        if (text !== undefined)
+            e[key] = text;
+    }
+    const label = feedText(value.label);
+    if (label !== undefined)
+        e.label = label;
+    return e;
+}
+/** A period, checked: a start and an end no earlier than it, and its number and game-clock length when they are numbers. */
+function periodOf(value) {
+    if (!isObj(value) || !isNum(value.start) || !isNum(value.end) || value.end < value.start)
+        return undefined;
+    return { start: value.start, end: value.end, ...(isNum(value.number) ? { number: value.number } : {}), ...(isNum(value.length) && value.length > 0 ? { length: value.length } : {}) };
+}
+/** A stoppage, checked: a start and an end no earlier than it, and its reason, the place of its restart and the side it was called against when they are of the right type. */
+function stoppageOf(value) {
+    if (!isObj(value) || !isNum(value.start) || !isNum(value.end) || value.end < value.start)
+        return undefined;
+    const s = { start: value.start, end: value.end };
+    const reason = feedText(value.reason, 24);
+    if (reason !== undefined)
+        s.reason = reason;
+    if (isNum(value.x))
+        s.x = value.x;
+    if (isNum(value.y))
+        s.y = value.y;
+    if (value.team === "home" || value.team === "away")
+        s.team = value.team;
+    return s;
+}
+/** A penalty, checked: a side, a start and its minutes on the game clock, and who serves it, when he leaves the box, its kind, whether his side plays short and whether a goal ended it, when they are of the right type. */
+function penaltyOf(value) {
+    if (!isObj(value) || (value.team !== "home" && value.team !== "away") || !isNum(value.start) || !isNum(value.minutes) || value.minutes <= 0)
+        return undefined;
+    const p = { team: value.team, start: value.start, minutes: value.minutes };
+    if (isNum(value.end) && value.end >= value.start)
+        p.end = value.end;
+    const by = feedText(value.by, 40);
+    if (by !== undefined)
+        p.by = by;
+    const kind = feedText(value.kind, 24);
+    if (kind !== undefined)
+        p.kind = kind;
+    if (typeof value.short === "boolean")
+        p.short = value.short;
+    if (value.endedBy === "goal")
+        p.endedBy = "goal";
+    return p;
+}
+const FROM = /^[a-z0-9-]{1,32}$/;
+/**
+ * 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 function kyogijoFeed(json) {
+    if (!isObj(json))
+        throw new FeedError("format", "not a kyogijo timeline: the answer is not a JSON object");
+    const game = json.kind === "kyogijo-game" && isObj(json.timeline);
+    const source = game ? json.timeline : json;
+    if (!Array.isArray(source.frames))
+        throw new FeedError("format", "not a kyogijo timeline: it has no list of frames");
+    const frames = [];
+    for (const f of source.frames.slice(0, FEED_LIMITS.frames)) {
+        if (!isObj(f) || !isNum(f.t) || !Array.isArray(f.objects))
+            continue;
+        const objects = f.objects.slice(0, FEED_LIMITS.objects).map(objectOf).filter((o) => o !== undefined);
+        const frame = { t: f.t, objects };
+        if (f.possession === null || typeof f.possession === "string")
+            frame.possession = f.possession === null ? null : feedText(f.possession, 40) ?? null;
+        frames.push(frame);
+    }
+    if (frames.length === 0)
+        throw new FeedError("empty", "the timeline has no frame to play");
+    const events = (Array.isArray(source.events) ? source.events.slice(0, FEED_LIMITS.events) : []).map(eventOf).filter((e) => e !== undefined);
+    const periodsIn = game ? json.periods : source.periods;
+    const periods = (Array.isArray(periodsIn) ? periodsIn.slice(0, FEED_LIMITS.periods) : []).map(periodOf).filter((p) => p !== undefined);
+    const stoppages = (Array.isArray(source.stoppages) ? source.stoppages.slice(0, FEED_LIMITS.stoppages) : [])
+        .map(stoppageOf)
+        .filter((s) => s !== undefined)
+        .sort((a, b) => a.start - b.start);
+    const penalties = (Array.isArray(source.penalties) ? source.penalties.slice(0, FEED_LIMITS.penalties) : [])
+        .map(penaltyOf)
+        .filter((p) => p !== undefined)
+        .sort((a, b) => a.start - b.start);
+    const teamsIn = game ? json.teams : source.teams;
+    const home = isObj(teamsIn) ? sideOf(teamsIn.home) : undefined;
+    const away = isObj(teamsIn) ? sideOf(teamsIn.away) : undefined;
+    const timeline = {
+        frames,
+        events,
+        ...(typeof source.from === "string" && FROM.test(source.from) ? { from: source.from } : {}),
+        ...(periods.length > 0 ? { periods } : {}),
+        ...(source.clock === "up" || source.clock === "down" ? { clock: source.clock } : {}),
+        ...(stoppages.length > 0 ? { stoppages } : {}),
+        ...(penalties.length > 0 ? { penalties } : {}),
+    };
+    const players = {};
+    const rosters = game && isObj(json.rosters) ? json.rosters : {};
+    for (const side of ["home", "away"]) {
+        const roster = rosters[side];
+        if (!Array.isArray(roster))
+            continue;
+        for (const p of roster.slice(0, 80)) {
+            const id = isObj(p) ? feedText(p.id, 40) : undefined;
+            if (id === undefined || !isObj(p))
+                continue;
+            const name = isObj(p.name) ? feedText(p.name.en ?? Object.values(p.name)[0]) : feedText(p.name);
+            players[id] = { side, ...(isNum(p.number) ? { number: p.number } : {}), ...(name === undefined ? {} : { name }) };
+        }
+    }
+    const sport = game ? feedText(json.sport, 24) : undefined;
+    return { format: "kyogijo", ...(sport === undefined ? {} : { sport }), timeline, teams: { home: home ?? {}, away: away ?? {} }, ended: true, players };
+}
+/** 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 function feedFormatOf(json) {
+    if (!isObj(json))
+        return undefined;
+    if (json.kind === "kyogijo-game" || Array.isArray(json.frames))
+        return "kyogijo";
+    if (Array.isArray(json.plays) && (isObj(json.homeTeam) || isObj(json.awayTeam)))
+        return "nhl";
+    return 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 function readFeed(json, format = "auto") {
+    const as = format === "auto" ? feedFormatOf(json) : format;
+    if (as === "kyogijo")
+        return kyogijoFeed(json);
+    if (as === "nhl")
+        return nhlPlayByPlay(json);
+    throw new FeedError("format", "not a feed this package reads: neither a kyogijo timeline nor an NHL-style play-by-play");
+}
+/** Read text (a file or what was pasted) as JSON and then as a feed. */
+export function readFeedText(text, format = "auto") {
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        throw new FeedError("format", "not JSON: the text could not be read");
+    }
+    return readFeed(json, format);
+}

package/dist/feeds.nhl.d.ts

@@ -0,0 +1,28 @@
+import { type FeedGame } from "./feeds.core.ts";
+/** A regulation period, and an overtime in the regular season (the playoffs play twenty-minute overtimes): seconds. */
+export declare const NHL_PERIOD = 1200;
+export declare const NHL_OVERTIME = 300;
+/**
+ * Read a play-by-play shaped as the NHL's public one into a game: the puck's places at the plays that have one (between them it moves in a straight line), a mark for each shot, goal and whistle, the periods with their
+ * clocks (a twenty-minute period, the board counting it down, an overtime of five minutes in the regular season and twenty in the playoffs, the shoot-out left out), each side's letters and name from the feed, and the players it names
+ * (by `p` and their id). Times are the game's, so the board's clock is the game's: period 2 starts at 1200 s. Throws a `FeedError` when it is not of the shape, or has no play with a place.
+ * @example
+ * ```ts
+ * import { nhlPlayByPlay } from "@johnmorrisdotca/kyogijo-stadiums/feeds";
+ * const answer = {
+ *   gameState: "LIVE", gameType: 2,
+ *   homeTeam: { id: 1, abbrev: "AAA", commonName: { default: "Aardvarks" } }, awayTeam: { id: 2, abbrev: "BBB" },
+ *   plays: [
+ *     { periodDescriptor: { number: 1, periodType: "REG" }, timeInPeriod: "00:00", typeDescKey: "faceoff", sortOrder: 1, details: { xCoord: 0, yCoord: 0 } },
+ *     { periodDescriptor: { number: 1, periodType: "REG" }, timeInPeriod: "01:30", typeDescKey: "goal", sortOrder: 2, details: { xCoord: 80, yCoord: -4, eventOwnerTeamId: 1, scoringPlayerId: 9 } },
+ *   ],
+ *   rosterSpots: [{ teamId: 1, playerId: 9, sweaterNumber: 19, firstName: { default: "Ada" }, lastName: { default: "Example" } }],
+ * };
+ * const game = nhlPlayByPlay(answer);
+ * console.log(game.timeline.events, game.teams.home, game.ended);
+ * console.log(game.players.p9);
+ * // [ { t: 90, kind: 'goal', x: 80, y: -4, team: 'home', by: 'p9' } ] { abbr: 'AAA', name: 'Aardvarks' } false
+ * // { side: 'home', number: 19, name: 'Ada Example' }
+ * ```
+ */
+export declare function nhlPlayByPlay(json: unknown): FeedGame;

package/dist/feeds.nhl.js

@@ -0,0 +1,132 @@
+// An adapter: a play-by-play shaped as the NHL's public one (`plays`, each with `periodDescriptor`, `timeInPeriod`, `typeDescKey` and `details` with `xCoord` and `yCoord` in feet from centre ice; `homeTeam` and
+// `awayTeam` with their `id` and `abbrev`; `rosterSpots`; `gameState`) read into a replay. A play-by-play has events and no tracking: the puck goes from one event's place to the next in a straight line (it is
+// modelled between the known places), the shots, the goals and the whistles are marked where they were, and the clock is the game's (twenty minutes a period). Pure; every value is checked. The shape was read
+// from public descriptions of the answer; tests run on answers we made up.
+import { FEED_LIMITS, FeedError, feedText } from "./feeds.core.js";
+const isNum = (value) => typeof value === "number" && Number.isFinite(value);
+const isObj = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A text field of the NHL's shape: a string, or `{ default: string }`. */
+const textOf = (value, most) => feedText(isObj(value) ? value.default : value, most);
+/** `mm:ss` as seconds; `undefined` for anything else. */
+const secondsOf = (value) => {
+    const m = typeof value === "string" ? /^(\d{1,3}):([0-5]\d)$/.exec(value.trim()) : null;
+    return m === null ? undefined : Number(m[1]) * 60 + Number(m[2]);
+};
+/** A regulation period, and an overtime in the regular season (the playoffs play twenty-minute overtimes): seconds. */
+export const NHL_PERIOD = 1200;
+export const NHL_OVERTIME = 300;
+/** What a kind of play is on the replay: the shots, the goal, and a whistle for a stoppage or a penalty. The rest only moves the puck. */
+const KINDS = { "shot-on-goal": "shot", "missed-shot": "shot", "blocked-shot": "shot", goal: "goal", stoppage: "whistle", penalty: "whistle", "delayed-penalty": "whistle" };
+/** The states of a game the NHL's shape says are over. */
+const OVER = new Set(["OFF", "FINAL"]);
+/**
+ * Read a play-by-play shaped as the NHL's public one into a game: the puck's places at the plays that have one (between them it moves in a straight line), a mark for each shot, goal and whistle, the periods with their
+ * clocks (a twenty-minute period, the board counting it down, an overtime of five minutes in the regular season and twenty in the playoffs, the shoot-out left out), each side's letters and name from the feed, and the players it names
+ * (by `p` and their id). Times are the game's, so the board's clock is the game's: period 2 starts at 1200 s. Throws a `FeedError` when it is not of the shape, or has no play with a place.
+ * @example
+ * ```ts
+ * import { nhlPlayByPlay } from "@johnmorrisdotca/kyogijo-stadiums/feeds";
+ * const answer = {
+ *   gameState: "LIVE", gameType: 2,
+ *   homeTeam: { id: 1, abbrev: "AAA", commonName: { default: "Aardvarks" } }, awayTeam: { id: 2, abbrev: "BBB" },
+ *   plays: [
+ *     { periodDescriptor: { number: 1, periodType: "REG" }, timeInPeriod: "00:00", typeDescKey: "faceoff", sortOrder: 1, details: { xCoord: 0, yCoord: 0 } },
+ *     { periodDescriptor: { number: 1, periodType: "REG" }, timeInPeriod: "01:30", typeDescKey: "goal", sortOrder: 2, details: { xCoord: 80, yCoord: -4, eventOwnerTeamId: 1, scoringPlayerId: 9 } },
+ *   ],
+ *   rosterSpots: [{ teamId: 1, playerId: 9, sweaterNumber: 19, firstName: { default: "Ada" }, lastName: { default: "Example" } }],
+ * };
+ * const game = nhlPlayByPlay(answer);
+ * console.log(game.timeline.events, game.teams.home, game.ended);
+ * console.log(game.players.p9);
+ * // [ { t: 90, kind: 'goal', x: 80, y: -4, team: 'home', by: 'p9' } ] { abbr: 'AAA', name: 'Aardvarks' } false
+ * // { side: 'home', number: 19, name: 'Ada Example' }
+ * ```
+ */
+export function nhlPlayByPlay(json) {
+    if (!isObj(json) || !Array.isArray(json.plays))
+        throw new FeedError("format", "not an NHL-style play-by-play: it has no list of plays");
+    const home = isObj(json.homeTeam) ? json.homeTeam : {};
+    const away = isObj(json.awayTeam) ? json.awayTeam : {};
+    const sideOf = (teamId) => (teamId !== undefined && teamId === home.id ? "home" : teamId !== undefined && teamId === away.id ? "away" : undefined);
+    const playoffs = json.gameType === 3;
+    const lengthOf = (number, type) => (type === "OT" || (type === undefined && number > 3) ? (playoffs ? NHL_PERIOD : NHL_OVERTIME) : NHL_PERIOD);
+    // The plays in order, the shoot-out left out (it has no clock, and its goals are not the score's).
+    const plays = json.plays
+        .slice(0, FEED_LIMITS.events)
+        .filter(isObj)
+        .map((play, i) => ({ play, order: isNum(play.sortOrder) ? play.sortOrder : i }))
+        .sort((a, b) => a.order - b.order)
+        .map((one) => one.play);
+    const periods = new Map();
+    const frames = [];
+    const events = [];
+    /** The time a period starts on the game's clock: the lengths of the periods before it. */
+    const startOf = (number, type) => {
+        let start = 0;
+        for (let p = 1; p < number; p += 1)
+            start += lengthOf(p, p <= 3 ? "REG" : type);
+        return start;
+    };
+    for (const play of plays) {
+        const d = isObj(play.periodDescriptor) ? play.periodDescriptor : {};
+        const number = isNum(d.number) && d.number >= 1 && d.number <= FEED_LIMITS.periods ? Math.trunc(d.number) : undefined;
+        if (number === undefined || d.periodType === "SO")
+            continue;
+        const length = lengthOf(number, d.periodType);
+        const start = startOf(number, d.periodType);
+        if (!periods.has(number))
+            periods.set(number, { number, start, end: start + length });
+        const into = secondsOf(play.timeInPeriod);
+        if (into === undefined)
+            continue;
+        const t = start + Math.min(length, into);
+        const details = isObj(play.details) ? play.details : {};
+        const placed = isNum(details.xCoord) && isNum(details.yCoord);
+        const [x, y] = placed ? [Math.max(-100, Math.min(100, details.xCoord)), Math.max(-42.5, Math.min(42.5, details.yCoord))] : [0, 0];
+        const type = typeof play.typeDescKey === "string" ? play.typeDescKey : "";
+        // A period starts with the puck at centre ice.
+        if (type === "period-start")
+            frames.push({ t, objects: [{ id: "puck", team: "puck", x: 0, y: 0 }] });
+        if (placed)
+            frames.push({ t, objects: [{ id: "puck", team: "puck", x, y }] });
+        const kind = KINDS[type];
+        if (kind === undefined)
+            continue;
+        const team = sideOf(details.eventOwnerTeamId);
+        const by = isNum(details.scoringPlayerId) ? details.scoringPlayerId : isNum(details.shootingPlayerId) ? details.shootingPlayerId : isNum(details.committedByPlayerId) ? details.committedByPlayerId : undefined;
+        events.push({ t, kind, ...(placed ? { x, y } : {}), ...(team === undefined ? {} : { team }), ...(by === undefined ? {} : { by: `p${by}` }) });
+    }
+    if (frames.length === 0)
+        throw new FeedError("empty", "the play-by-play has no play with a place on the ice yet");
+    // Frames at one time keep the last; the timeline is in order.
+    const byTime = new Map();
+    for (const f of frames)
+        byTime.set(f.t, f);
+    const ordered = [...byTime.values()].sort((a, b) => a.t - b.t);
+    const side = (team) => {
+        const abbr = textOf(team.abbrev, 8);
+        const name = textOf(team.commonName) ?? textOf(team.name) ?? textOf(team.placeName);
+        return { ...(abbr === undefined ? {} : { abbr }), ...(name === undefined ? {} : { name }) };
+    };
+    const players = {};
+    if (Array.isArray(json.rosterSpots)) {
+        for (const spot of json.rosterSpots.slice(0, 120)) {
+            if (!isObj(spot) || !isNum(spot.playerId))
+                continue;
+            const s = sideOf(spot.teamId);
+            if (s === undefined)
+                continue;
+            const name = [textOf(spot.firstName, 40), textOf(spot.lastName, 40)].filter((part) => part !== undefined).join(" ");
+            players[`p${spot.playerId}`] = { side: s, ...(isNum(spot.sweaterNumber) ? { number: spot.sweaterNumber } : {}), ...(name === "" ? {} : { name }) };
+        }
+    }
+    const state = typeof json.gameState === "string" ? json.gameState : "";
+    return {
+        format: "nhl",
+        sport: "nhl",
+        timeline: { from: "nhl-api", frames: ordered, events, periods: [...periods.values()].sort((a, b) => a.start - b.start) },
+        teams: { home: side(home), away: side(away) },
+        ended: OVER.has(state),
+        players,
+    };
+}

package/dist/judging.mount.js

@@ -62,7 +62,7 @@ export function mountJudgingBroadcast(host, options, settings = {}) {
         direction: () => turn.direction(),
         setDirection: (direction) => turn.setDirection(direction),
         togglePlay: () => turn.togglePlay(),
-        replay: (timeline, replaySettings) => turn.replay(timeline, replaySettings),
+        replay: turn.replay,
         get quality() {
             return turn.quality;
         },

package/dist/mount-entry.d.ts

@@ -2,3 +2,4 @@ import "./full.ts";
 import "./venues.all.ts";
 export { containerAspect, kyogijoElement, mountKyogijo } from "./mount.ts";
 export type { KyogijoMount, KyogijoReplay, MountSettings } from "./mount.ts";
+export type { FeedReplay, FeedReplayOptions, ReplayCall, ReplayFollow, ReplayFollowOptions } from "./replay.feed.ts";

package/dist/mount.d.ts

@@ -1,5 +1,5 @@
 import type { ReplayController } from "./replay.control.ts";
-import type { ReplaySettings, ReplayTimeline } from "./replay.types.ts";
+import { type ReplayCall } from "./replay.feed.ts";
 import type { ScoreOptions, SurfaceOptions } from "./types.ts";
 /** A replay on a mount: the controller of its clock, and `destroy` to take the replay away and leave the surface. */
 export type KyogijoReplay = ReplayController & {
@@ -16,9 +16,10 @@ export interface KyogijoMount {
     /**
      * Play tracking data on the surface: the players, the ball and the events of a timeline, with controls under the drawing (play, pause, step,
      * speed, loop, position), the keyboard (space, the arrow keys, Home and End) and a live region for goals and shots. Only the marks that move are
-     * moved, on animation frames. A reader who prefers reduced motion gets steps, and nothing plays by itself; a hidden page pauses. `update` keeps the replay.
+     * moved, on animation frames. A reader who prefers reduced motion gets steps, and nothing plays by itself; a hidden page pauses. `update` keeps the replay. `replay.fromUrl(url, options)` plays a feed from an
+     * address the reader gives, and `replay.follow(url, options)` follows one live, once the `/feeds` entry is loaded (see `docs/feeds.md`).
      */
-    replay(timeline: ReplayTimeline, settings?: ReplaySettings): KyogijoReplay;
+    replay: ReplayCall;
     /** Stop watching the container and empty it. */
     destroy(): void;
 }

package/dist/mount.js

@@ -2,6 +2,7 @@ import { drawKyogijo, isPortrait } from "./draw.js";
 import { resolveHomeSide } from "./homeside.js";
 import { chooseLeague } from "./leagues.js";
 import { createReplayView } from "./replay.dom.js";
+import { withFeeds } from "./replay.feed.js";
 const isScored = (o) => o.home !== undefined && o.away !== undefined;
 const scoreText = (team) => (team.score === undefined || team.score === null ? "" : String(team.score));
 /**
@@ -120,7 +121,7 @@ export function mountKyogijo(host, options, settings = {}) {
             if (settings.highlight !== false)
                 highlightScores(host, before, next);
         },
-        replay(timeline, replaySettings = {}) {
+        replay: withFeeds((timeline, replaySettings = {}) => {
             if (!alive)
                 throw new Error("this mount was destroyed");
             view?.destroy();
@@ -136,7 +137,7 @@ export function mountKyogijo(host, options, settings = {}) {
                     render();
                 },
             };
-        },
+        }),
         svg: () => (alive ? host.querySelector("svg.kyogijo") : null),
         orientation: () => (portrait ? "portrait" : "landscape"),
         destroy() {

package/dist/replay.feed.d.ts

@@ -0,0 +1,54 @@
+import type { FeedFormat, FeedGame } from "./feeds.core.ts";
+import type { FeedError } from "./feeds.core.ts";
+import type { FeedFollowState } from "./feeds.fetch.ts";
+import type { KyogijoReplay } from "./mount.ts";
+import type { ReplaySettings, ReplayTimeline } from "./replay.types.ts";
+/** What a feed played from an address can be told: its format, the replay's settings, and for a test the function that fetches. */
+export interface FeedReplayOptions {
+    format?: FeedFormat;
+    settings?: ReplaySettings;
+    base?: string;
+    signal?: AbortSignal;
+    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+}
+/** A replay of a feed: the replay's controller, and the game the feed was read into. */
+export type FeedReplay = KyogijoReplay & {
+    feed: FeedGame;
+};
+/** What a live follow can be told, beyond `FeedReplayOptions`. */
+export interface ReplayFollowOptions extends FeedReplayOptions {
+    /** Seconds between asks: 15 by default, never less than 10. */
+    every?: number;
+    /** Each new answer, after it is played. */
+    onGame?: (game: FeedGame, replay: KyogijoReplay) => void;
+    onError?: (error: FeedError) => void;
+    onState?: (state: FeedFollowState) => void;
+    /** The document whose visibility it follows: the page's by default. */
+    doc?: Document;
+}
+/** A replay that follows a feed live: the replay playing now (a new one on each answer that changed), the follow's state, and `stop`, which stops asking and leaves the replay. */
+export interface ReplayFollow {
+    replay(): KyogijoReplay | undefined;
+    state(): FeedFollowState;
+    stop(): void;
+}
+/** A mount's or a view's `replay`: play a timeline, or a feed from an address. */
+export interface ReplayCall {
+    (timeline: ReplayTimeline, settings?: ReplaySettings): KyogijoReplay;
+    /**
+     * Fetch a feed from an address, by the reader's browser (no server of ours, no cookie, nothing kept), read it (`readFeed`: kyogijo's open timeline, or an NHL-style play-by-play) and play it. Rejects with a
+     * `FeedError` that says what was wrong: a server that does not let the page read it (`cors`), a status (`http`), an answer that is not a feed (`format`).
+     */
+    fromUrl(url: string, options?: FeedReplayOptions): Promise<FeedReplay>;
+    /** Follow a feed live: ask it every 15 seconds or more while the page is shown, play each answer that changed from where the replay was (or at its newest moment, when it was there), and stop when the game is over or the server says no. */
+    follow(url: string, options?: ReplayFollowOptions): ReplayFollow;
+}
+/** What `feeds.dom.ts` lends a `replay`. */
+export interface FeedKit {
+    fromUrl(play: (timeline: ReplayTimeline, settings?: ReplaySettings) => KyogijoReplay, url: string, options?: FeedReplayOptions): Promise<FeedReplay>;
+    follow(play: (timeline: ReplayTimeline, settings?: ReplaySettings) => KyogijoReplay, url: string, options?: ReplayFollowOptions): ReplayFollow;
+}
+/** Put the feeds' code in: called once by `feeds.dom.ts`. */
+export declare function useFeedKit(next: FeedKit): void;
+/** A `replay` with `fromUrl` and `follow` on it. */
+export declare function withFeeds(play: (timeline: ReplayTimeline, settings?: ReplaySettings) => KyogijoReplay): ReplayCall;

package/dist/replay.feed.js

@@ -0,0 +1,17 @@
+let kit;
+/** Put the feeds' code in: called once by `feeds.dom.ts`. */
+export function useFeedKit(next) {
+    kit = next;
+}
+const need = () => {
+    if (kit === undefined)
+        throw new Error("the feeds are not loaded: import \"@johnmorrisdotca/kyogijo-stadiums/feeds\" once, before replay.fromUrl or replay.follow");
+    return kit;
+};
+/** A `replay` with `fromUrl` and `follow` on it. */
+export function withFeeds(play) {
+    return Object.assign(play, {
+        fromUrl: (url, options) => need().fromUrl(play, url, options),
+        follow: (url, options) => need().follow(play, url, options),
+    });
+}

package/dist/turn-entry.d.ts

@@ -6,6 +6,7 @@ export { discSize, keepOnFloor, replayTurnModel } from "./turn.replay.ts";
 export type { TurnReplayLook, TurnReplayModel } from "./turn.replay.ts";
 export type { TurnReplaySettings } from "./turn.replay.dom.ts";
 import "./turn.replay.dom.ts";
+export type { FeedReplay, FeedReplayOptions, ReplayCall, ReplayFollow, ReplayFollowOptions } from "./replay.feed.ts";
 export { buildTurn, floorOptions, openingView } from "./turn.model.ts";
 export { turnDirection } from "./turn.camera.ts";
 export type { TurnDirection } from "./turn.camera.ts";

package/dist/turn.dom.d.ts

@@ -4,6 +4,7 @@ import type { ScoreOptions, SurfaceOptions } from "./types.ts";
 import type { VenueSettings } from "./venue.ts";
 import { type Quality, type QualityTier } from "./quality.ts";
 import type { OutsideLevel } from "./outside.paint.ts";
+import { type ReplayCall } from "./replay.feed.ts";
 import type { ReplaySettings, ReplayTimeline } from "./replay.types.ts";
 import type { KyogijoReplay } from "./mount.ts";
 import type { TurnInternals } from "./turn.replay.dom.ts";
@@ -70,8 +71,9 @@ export interface KyogijoTurn<O = SurfaceOptions | ScoreOptions> {
      * Play tracking data on the view: the players stand up on the surface as discs that face the eye (home circles, away squares, numbers), the ball or the puck runs on the floor with its trail, and the passes, shots and
      * goals are drawn on the floor as in the flat replay. The replay's controls go under the view's; the view still turns, tips and zooms while it plays. Space on the view plays and pauses, comma and full stop step; the
      * arrow keys still turn the view. `destroy` on what it gives takes the replay away and leaves the view. A tournament layout has no replay. Where the browser cannot draw the 3D view, the flat replay plays instead.
+     * `replay.fromUrl(url, options)` plays a feed from an address the reader gives, and `replay.follow(url, options)` follows one live, once the `/feeds` entry is loaded (see `docs/feeds.md`).
      */
-    replay(timeline: ReplayTimeline, settings?: ReplaySettings): KyogijoReplay;
+    replay: ReplayCall;
     /** Stop listening and empty the container. */
     destroy(): void;
 }

package/dist/turn.dom.js

@@ -13,6 +13,7 @@ import { turnBoardMarkup } from "./overlay.js";
 import { attachOutside3d } from "./outside.dom.js";
 import { TIER_PROFILES, createGovernor, handheld, layerBudget, qualityOf, rasterOf, rasterShares, tierOf, viewShare, FLOOR_SHARE } from "./quality.js";
 import { size } from "./turn.kit.js";
+import { withFeeds } from "./replay.feed.js";
 /**
  * The replay's own code, which `turn.replay.dom.ts` puts in when it is loaded (the `/turn` entry and the element load it): a page that only turns a view (a district, a tournament layout) carries none of the replay
  * and its layers.
@@ -148,7 +149,7 @@ export function mountTurn(host, options, settings, build, replayable = false, le
             },
             svg: () => (alive ? host.querySelector("svg.kyogijo") : null),
             // The flat replay, where the 3D view cannot be drawn.
-            replay(timeline, replaySettings = {}) {
+            replay: withFeeds((timeline, replaySettings = {}) => {
                 if (!replayable)
                     throw new Error("a replay plays on one surface, not on a layout");
                 flatReplay?.view.destroy();
@@ -165,7 +166,7 @@ export function mountTurn(host, options, settings, build, replayable = false, le
                         flat(current);
                     },
                 };
-            },
+            }),
             destroy: () => {
                 alive = false;
                 flatReplay?.view.destroy();
@@ -887,7 +888,7 @@ export function mountTurn(host, options, settings, build, replayable = false, le
             return last === undefined ? undefined : { ms: last.ms, people: last.stats.people, mode: last.stats.mode, pixels: last.pixels };
         },
         svg: () => (alive ? root.querySelector(".ky-turn-floor svg.kyogijo") : null),
-        replay(timeline, replaySettings = {}) {
+        replay: withFeeds((timeline, replaySettings = {}) => {
             if (!alive)
                 throw new Error("this view was destroyed");
             if (!replayable)
@@ -904,7 +905,7 @@ export function mountTurn(host, options, settings, build, replayable = false, le
                     mine.destroy();
                 },
             };
-        },
+        }),
         destroy() {
             if (!alive)
                 return;

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.62.0";
+export declare const VERSION = "0.63.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.62.0";
+export const VERSION = "0.63.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/kyogijo-stadiums",
-  "version": "0.62.0",
+  "version": "0.63.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",
@@ -68,6 +68,7 @@
   "sideEffects": [
     "./dist/element-define.js",
     "./dist/turn.replay.dom.js",
+    "./dist/feeds.dom.js",
     "./dist/frames.providers.js",
     "./dist/full.js",
     "./dist/arenas.js",
@@ -244,6 +245,11 @@
       "import": "./dist/sound-entry.js",
       "default": "./dist/sound-entry.js"
     },
+    "./feeds": {
+      "types": "./dist/feeds-entry.d.ts",
+      "import": "./dist/feeds-entry.js",
+      "default": "./dist/feeds-entry.js"
+    },
     "./scene": {
       "types": "./dist/scene-entry.d.ts",
       "import": "./dist/scene-entry.js",