@johnmorrisdotca/kyogijo-stadiums 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.26.0] - 2026-10-20
+
+### Added
+
+- **The fly-through** (`mountFlythrough`, [the fly-through](./docs/flythrough.md), entry `@johnmorrisdotca/kyogijo-stadiums/flythrough`): one smooth camera from a map to a real arena. It starts on a map drawn with chizu (handed over as `start: { map, draw, project }`, so the package keeps no dependency; a plain graticule without one), falls to the city and to the building of the arena as OpenStreetMap maps it, and the building rises into the 3D arena, which tips to the sport's main camera and turns. `mountFlythrough(host, { arena, start?, stages?, language?, theme? }, settings?)` gives back `play`, `pause`, `toggle`, `next`, `back`, `goTo(stage)`, `seek(seconds)`, `camera()` and `destroy`. This first release ends on the turning arena; into the bowl, down to the rink and a game on it are the next ones.
+- **One path, no jumps.** The camera is ten numbers (how far in, where the arena stands on the screen, how far the map is turned, how much of the map, the plan and the arena shows, the 3D view's turn, tip and zoom), each running through the path's keyframes as a monotone cubic: smooth at every keyframe, still at the start, never overshooting a layer's share. The map's viewBox is true to the ground round the arena and turned to the venue's own orientation as it comes in; the plan hands over to the 3D arena at the same size and place, measured in the stage as it is. `flightPlan`, `cameraAt` and `stageAt` are the path as plain numbers, pure and testable in Node.
+- **Controls and reduced motion.** Back, Play or Pause (the clock eases to a stop), Next and a button for each stage; Space, the arrows, the number keys and Home; a skip glides along the path and does not cut. A reader who prefers reduced motion gets each stage as a still (the map, the plan, the arena at the main camera), Next, Back and the stage buttons show the next still at once, and Play steps through them every five seconds.
+- **The demo's fly-through page** (`flythrough.html?arena=honda-center`): each of the eight venues, English and Japanese, light and dark, desk and phone, with the OpenStreetMap credit under the stage. No word is stretched (the words are HTML over the layers) and no team's or league's mark is drawn.
+- Tests that walk the path at 60 frames a second for every list of stages (no step, no jump of speed), check that every stage is reachable, that the stills show one layer whole, and, in a real browser, that the pin, the plan and the 3D floor never jump on the screen at 30 frames a second and are the same size where they hand over.
+
+### Fixed
+
+- The shared background module in `scripts/` (tooling for the demo and the README pictures; the package ships none of it) is now the family's version 1.0.1: the `id` it is given is made safe (letters, digits, `_` and `-`; `bg-` in front of one that does not start with a letter) before it is written into element ids and `url(#...)`. `test/family-backgrounds.test.ts` draws every preset with hostile ids.
+
 ## [0.25.0] - 2026-10-20
 
 ### Added

package/dist/flythrough-entry.d.ts

@@ -0,0 +1,8 @@
+export { mountFlythrough } from "./flythrough.dom.ts";
+export type { Flythrough, FlythroughOptions, FlythroughSettings, FlythroughStart } from "./flythrough.dom.ts";
+export { CHANNELS, PACE, RAMP, STAGE_IDS, cameraAt, flightPlan, foldTime, glide, glideSeconds, mainView, mapBox, mapFrame, monotoneSlopes, nextRate, stageAt, startOf, stagesOf } from "./flythrough.path.ts";
+export type { Camera, Channel, Flight, FlightInput, Keyframe, MapFrame, StageId } from "./flythrough.path.ts";
+export { flythroughMarkup, graticuleMarkup, mapMarkup } from "./flythrough.markup.ts";
+export { FLYTHROUGH_STYLE } from "./flythrough.style.ts";
+export { FLYTHROUGH_WORDS } from "./flythrough.words.ts";
+export type { FlythroughWords } from "./flythrough.words.ts";

package/dist/flythrough-entry.js

@@ -0,0 +1,6 @@
+// The fly-through: one smooth camera from a map to the real arena, over the map (chizu's, handed over), the building's site plan and the 3D arena.
+export { mountFlythrough } from "./flythrough.dom.js";
+export { CHANNELS, PACE, RAMP, STAGE_IDS, cameraAt, flightPlan, foldTime, glide, glideSeconds, mainView, mapBox, mapFrame, monotoneSlopes, nextRate, stageAt, startOf, stagesOf } from "./flythrough.path.js";
+export { flythroughMarkup, graticuleMarkup, mapMarkup } from "./flythrough.markup.js";
+export { FLYTHROUGH_STYLE } from "./flythrough.style.js";
+export { FLYTHROUGH_WORDS } from "./flythrough.words.js";

package/dist/flythrough.dom.d.ts

@@ -0,0 +1,103 @@
+import { type Camera, type StageId } from "./flythrough.path.ts";
+import type { Language } from "./types.ts";
+/** A map to start on: chizu's world (or any map of the same shape) with chizu's `drawChizu` and `projectPoint`, which are handed over, not imported, so that the package has no dependency. */
+export interface FlythroughStart<M extends {
+    width: number;
+    height: number;
+} = {
+    width: number;
+    height: number;
+}> {
+    /** The map: chizu's `WORLD`, for instance. */
+    map?: M;
+    /** Draws the map as an SVG string: chizu's `drawChizu`. It is called with `{ style: true, language }`. */
+    draw?: (map: M, options: {
+        style: boolean;
+        language: Language;
+    }) => string;
+    /** Puts a longitude and latitude on the map's canvas: chizu's `projectPoint`; `null` where the map has no place for it. */
+    project?: (map: M, lon: number, lat: number) => readonly [number, number] | null;
+    /** The metres the container's width shows at the start. 9,000 km by default. */
+    span?: number;
+    /** Where the camera starts looking, `[longitude, latitude]`: the arena stands off the middle of the screen and comes to the middle as the camera falls. The arena itself by default. */
+    centre?: readonly [number, number];
+}
+/** What a fly-through is of. */
+export interface FlythroughOptions<M extends {
+    width: number;
+    height: number;
+} = {
+    width: number;
+    height: number;
+}> {
+    /** The arena's key in `ARENAS`: an arena that has a real venue (`VENUE_IDS`). */
+    arena: string;
+    start?: FlythroughStart<M>;
+    /** The stages to fly, in the order of the path; all of them by default. */
+    stages?: readonly StageId[];
+    language?: Language;
+    /** `light` or `dark`; the device's setting decides when it is left out. */
+    theme?: "light" | "dark";
+}
+/** How it behaves. */
+export interface FlythroughSettings {
+    /** `auto` (the default) flies unless the reader prefers reduced motion, and then shows each stage as a still; `smooth` flies anyway and `none` shows stills. */
+    motion?: "auto" | "smooth" | "none";
+    /** Whether it starts flying when it is mounted (it does by default, unless the reader prefers reduced motion). */
+    autoPlay?: boolean;
+    /** How many times faster than the path's own pace the clock runs. 1 by default. */
+    speed?: number;
+    /** Whether the buttons under the stage are drawn. True when left out; the keys work either way. */
+    controls?: boolean;
+    /** The prefix of the ids in the page, for a page with more than one. */
+    id?: string;
+    /** Called with the stage when the camera enters one. */
+    onStage?: (stage: StageId) => void;
+    /** Called with `true` when it starts flying and `false` when it stops. */
+    onPlayChange?: (playing: boolean) => void;
+}
+/** What `mountFlythrough` gives back. */
+export interface Flythrough {
+    /** `motion` flies; `stages` shows each stage as a still. */
+    readonly mode: "motion" | "stages";
+    readonly playing: boolean;
+    /** The stage the camera is in. */
+    readonly stage: StageId;
+    /** The stages flown, in order. */
+    readonly stages: readonly StageId[];
+    /** Seconds along the path now. */
+    readonly time: number;
+    /** The seconds the path takes from the first stage to the last one's start (and then the arena turns for ever). */
+    readonly duration: number;
+    /** The camera now. */
+    camera(): Camera;
+    play(): void;
+    pause(): void;
+    /** Play when paused, pause when playing; gives whether it plays now. */
+    toggle(): boolean;
+    /** Go to the stage after this one (the last one stays), and to the one before (the first starts again). */
+    next(): void;
+    back(): void;
+    /** Go to a stage (its name or its place in `stages`): the camera glides there along the path, or shows its still. */
+    goTo(stage: StageId | number): void;
+    /** Put the camera at a moment of the path at once, whatever the mode (a scrubber, a test). */
+    seek(seconds: number): void;
+    destroy(): void;
+}
+/**
+ * Mount a fly-through of an arena in a container: a map that falls to the city and the building, which rises into the arena in 3D, turning.
+ * @example
+ * ```ts no-run
+ * import { mountFlythrough } from "@johnmorrisdotca/kyogijo-stadiums/flythrough";
+ * import WORLD from "@johnmorrisdotca/chizu/world";
+ * import { drawChizu } from "@johnmorrisdotca/chizu/draw";
+ * import { projectPoint } from "@johnmorrisdotca/chizu";
+ *
+ * const trip = mountFlythrough(document.querySelector("#trip")!, { arena: "honda-center", start: { map: WORLD, draw: drawChizu, project: projectPoint } });
+ * trip.goTo("city");
+ * ```
+ */
+export declare function mountFlythrough<M extends {
+    width: number;
+    height: number;
+}>(host: HTMLElement, options: FlythroughOptions<M>, settings?: FlythroughSettings): Flythrough;

package/dist/flythrough.dom.js

@@ -0,0 +1,517 @@
+// The fly-through in a page: `mountFlythrough` writes the stage into a container and moves one camera along the path of `flythrough.path.ts`. Three layers are stacked under one set of numbers: the map (chizu's, when
+// the page hands it over, else a plain graticule) turned and zoomed in a viewBox that is true to the ground round the arena, the site plan (the building's outline, from OpenStreetMap) in pixels at the same
+// scale, and the 3D arena of `mountKyogijoTurn`, driven by its own view. Nothing runs on a timer: a frame is drawn only while the clock moves (playing, or gliding to a stage), and not while the page is hidden
+// or the stage is off the screen. A reader who prefers reduced motion gets each stage as a still, and the controls step from one to the next.
+import { arenaById, arenaNameIn } from "./arenas.js";
+import { STAGE_IDS, cameraAt, coverSide, flightPlan, foldTime, glide, glideSeconds, lengthWords, mainView, mapBox, mapFrame, nextRate, niceLength, stageAt, startOf, stagesOf, } from "./flythrough.path.js";
+import { flythroughMarkup, graticuleMarkup, gridPath, mapMarkup, stageWords } from "./flythrough.markup.js";
+import { FLYTHROUGH_WORDS, say } from "./flythrough.words.js";
+import { mountKyogijoTurn } from "./turn.dom.js";
+import { arenaOfVenue, planVenue, venueById, venueOrientation, venueRink } from "./venues.js";
+/**
+ * Mount a fly-through of an arena in a container: a map that falls to the city and the building, which rises into the arena in 3D, turning.
+ * @example
+ * ```ts no-run
+ * import { mountFlythrough } from "@johnmorrisdotca/kyogijo-stadiums/flythrough";
+ * import WORLD from "@johnmorrisdotca/chizu/world";
+ * import { drawChizu } from "@johnmorrisdotca/chizu/draw";
+ * import { projectPoint } from "@johnmorrisdotca/chizu";
+ *
+ * const trip = mountFlythrough(document.querySelector("#trip")!, { arena: "honda-center", start: { map: WORLD, draw: drawChizu, project: projectPoint } });
+ * trip.goTo("city");
+ * ```
+ */
+export function mountFlythrough(host, options, settings = {}) {
+    const venue = venueById(options.arena);
+    if (venue === undefined)
+        throw new Error(`${options.arena} has no real venue: choose one of the keys of VENUES`);
+    const arena = arenaById(venue.id) ?? arenaOfVenue(venue);
+    const doc = host.ownerDocument;
+    const win = doc.defaultView;
+    const language = options.language === "ja" ? "ja" : "en";
+    const words = FLYTHROUGH_WORDS[language];
+    const id = settings.id ?? `kf-${venue.id}`;
+    const speed = typeof settings.speed === "number" && Number.isFinite(settings.speed) && settings.speed > 0 ? settings.speed : 1;
+    const orientation = venueOrientation(venue);
+    const name = arenaNameIn(arena, undefined, language);
+    const region = (() => {
+        try {
+            return new Intl.DisplayNames([language], { type: "region" }).of(arena.country) ?? arena.country;
+        }
+        catch {
+            return arena.country;
+        }
+    })();
+    const place = `${arena.city}, ${region}`;
+    const values = { arena: name, place };
+    const wanted = (options.stages ?? STAGE_IDS).filter((stage, i, all) => STAGE_IDS.includes(stage) && all.indexOf(stage) === i);
+    const stageList = STAGE_IDS.filter((stage) => wanted.includes(stage));
+    if (stageList.length === 0)
+        throw new Error("a fly-through needs at least one stage: choose from map, city and arena");
+    // ---- The map: chizu's where it is handed over and has a place for the arena, else a plain graticule. ----
+    const [lon, lat] = venue.osm.axis.centre;
+    const start = options.start;
+    let frame;
+    let mapSvg;
+    let chizu = false;
+    if (start?.map !== undefined && start.draw !== undefined && start.project !== undefined) {
+        const { map, project } = start;
+        frame = mapFrame((a, b) => project(map, a, b), lon, lat);
+        if (frame !== undefined) {
+            mapSvg = mapMarkup(start.draw(map, { style: true, language }));
+            chizu = true;
+        }
+    }
+    if (frame === undefined || mapSvg === undefined) {
+        const plain = graticuleMarkup(lat);
+        mapSvg = plain.svg;
+        frame = { at: [0, 0], metresX: 1, metresY: 1 };
+    }
+    const mapFrameNow = frame;
+    host.innerHTML = flythroughMarkup({ id, language, theme: options.theme, arena: name, place, stages: stageList, map: mapSvg, mapCredit: chizu, controls: settings.controls });
+    const root = host.querySelector(".kf");
+    const stage = root.querySelector(".kf-stage");
+    const mapLayer = root.querySelector(".kf-map");
+    const mapBoxEl = root.querySelector(".kf-map-box");
+    const mapSvgEl = mapBoxEl.querySelector("svg");
+    const siteEl = root.querySelector(".kf-site");
+    const gridEl = siteEl.querySelector(".kf-grid");
+    const planEl = siteEl.querySelector(".kf-plan");
+    const turnHost = root.querySelector(".kf-3d");
+    const pin = root.querySelector(".kf-pin");
+    const scale = root.querySelector(".kf-scale");
+    const scaleBar = root.querySelector(".kf-scale-bar");
+    const scaleText = root.querySelector(".kf-scale-text");
+    const caption = root.querySelector(".kf-caption");
+    const live = root.querySelector(".kf-live");
+    const media = win?.matchMedia?.("(prefers-reduced-motion: reduce)");
+    const calm = () => settings.motion === "none" || (settings.motion !== "smooth" && media?.matches === true);
+    // ---- The 3D arena, from above to begin with: the view the path hands over at. ----
+    const drawing = { sport: "nhl", arena: venue.id, crowd: { real: true }, language, ...(options.theme === undefined ? {} : { theme: options.theme }) };
+    let turn;
+    if (stageList.includes("arena"))
+        turn = mountKyogijoTurn(turnHost, drawing, { preset: "overhead", controls: false, venue: { roof: true }, motion: "none", id: `${id}-turn` });
+    // ---- The site plan: the building's outline and the rink, in the drawing's own feet; the sheet under it is the floor's. ----
+    const plan = planVenue(venue);
+    const rink = venueRink(venue);
+    const rinkMiddle = [rink.x + rink.w / 2, rink.y + rink.h / 2];
+    const footprint = `M${plan.footprint.map(([x, y]) => `${x.toFixed(1)} ${y.toFixed(1)}`).join("L")}Z`;
+    let sheet = { x: -200, y: -200, w: 600, h: 490 };
+    const drawPlan = () => {
+        planEl.innerHTML = `<rect class="ky-apron" x="${sheet.x}" y="${sheet.y}" width="${sheet.w}" height="${sheet.h}"/><path class="ky-cr-shell" d="${footprint}"/><rect class="kf-rink" x="${rink.x}" y="${rink.y}" width="${rink.w}" height="${rink.h}" rx="${Math.min(28, rink.h / 3)}"/>`;
+    };
+    drawPlan();
+    // ---- The path, worked out for this container: the plan hands over to the 3D arena where the two are the same size. ----
+    let width = 0;
+    let height = 0;
+    const startCentre = start?.centre;
+    const anchorStart = (w, h, span) => {
+        if (startCentre === undefined || start?.project === undefined || start.map === undefined)
+            return [0, 0];
+        const here = start.project(start.map, lon, lat);
+        const there = start.project(start.map, startCentre[0], startCentre[1]);
+        if (here === null || there === null)
+            return [0, 0];
+        // The arena's offset from the middle, in metres on the ground, as a share of what the stage shows.
+        const dx = ((here[0] - there[0]) * mapFrameNow.metresX) / span;
+        const dy = ((here[1] - there[1]) * mapFrameNow.metresY) / (span * (h / w));
+        return [Math.max(-0.4, Math.min(0.4, dx)), Math.max(-0.4, Math.min(0.4, dy))];
+    };
+    const makeFlight = () => {
+        width = stage.clientWidth || 960;
+        height = stage.clientHeight || 600;
+        let siteSpan = 400;
+        let anchorEnd = [0, 0];
+        const floor = turn?.svg() ?? null;
+        if (turn !== undefined && floor !== null) {
+            // Measure the arena seen from straight above, as the 3D view lays it out in this container: where the rink stands and how big a foot is.
+            const was = turn.view();
+            turn.set({ yaw: 0, pitch: 0, zoom: 1 }, false);
+            const box = floor.getBoundingClientRect();
+            // The stage's own area, inside its border: the layers are laid out in it.
+            const outer = stage.getBoundingClientRect();
+            const [left, top] = [outer.left + stage.clientLeft, outer.top + stage.clientTop];
+            const vb = floor.viewBox.baseVal;
+            if (box.width > 0 && vb.width > 0 && width > 0) {
+                const pxPerFoot = box.width / vb.width;
+                siteSpan = (0.3048 * width) / pxPerFoot;
+                const x = box.left - left + (rinkMiddle[0] - vb.x) * pxPerFoot;
+                const y = box.top - top + (rinkMiddle[1] - vb.y) * pxPerFoot;
+                anchorEnd = [(x - width / 2) / width, (y - height / 2) / height];
+                sheet = { x: vb.x, y: vb.y, w: vb.width, h: vb.height };
+                drawPlan();
+            }
+            turn.set(was, false);
+        }
+        const startSpan = start?.span ?? 9000000;
+        return flightPlan({ north: orientation.north, siteSpan, startSpan, anchorStart: anchorStart(width, height, startSpan), anchorEnd, stages: stageList, view: mainView("nhl") });
+    };
+    let flight = makeFlight();
+    // ---- Drawing a camera. ----
+    let current = cameraAt(flight, 0);
+    let shownStage;
+    let written = {};
+    const put = (key, el, prop, value) => {
+        const k = `${key}:${prop}`;
+        if (written[k] === value)
+            return;
+        written[k] = value;
+        if (prop.startsWith("@"))
+            el.setAttribute(prop.slice(1), value);
+        else
+            el.style.setProperty(prop, value);
+    };
+    const num = (value, places = 2) => String(Math.round(value * 10 ** places) / 10 ** places);
+    /** Put a camera on the screen. */
+    const render = (cam) => {
+        current = cam;
+        const W = width;
+        const H = height;
+        const ax = W / 2 + cam.ax * W;
+        const ay = H / 2 + cam.ay * H;
+        const metresPerPixel = Math.exp(cam.logSpan) / W;
+        const live3d = cam.arena > 0.003 && turn !== undefined;
+        // The map, turned about the arena, in a square that covers the stage.
+        const mapOn = cam.map > 0.003;
+        put("map", mapLayer, "visibility", mapOn ? "visible" : "hidden");
+        if (mapOn) {
+            const side = coverSide(W, H, ax, ay);
+            const box = mapBox(mapFrameNow, side * metresPerPixel);
+            put("map", mapLayer, "opacity", num(cam.map, 3));
+            put("map", mapBoxEl, "width", `${num(side, 1)}px`);
+            put("map", mapBoxEl, "height", `${num(side, 1)}px`);
+            put("map", mapBoxEl, "left", `${num(ax - side / 2, 1)}px`);
+            put("map", mapBoxEl, "top", `${num(ay - side / 2, 1)}px`);
+            put("map", mapBoxEl, "transform", `rotate(${num(cam.north, 3)}deg)`);
+            put("map", mapSvgEl, "@viewBox", `${box.x} ${box.y} ${box.w} ${box.h}`);
+        }
+        // The site plan, in pixels: the drawing's feet at this scale, turned to the venue's own orientation as the map is, about the arena.
+        const siteOn = cam.site > 0.003;
+        put("site", siteEl, "visibility", siteOn ? "visible" : "hidden");
+        if (siteOn) {
+            const pxPerFoot = 0.3048 / metresPerPixel;
+            put("site", siteEl, "opacity", num(cam.site, 3));
+            put("site", siteEl, "@viewBox", `0 0 ${W} ${H}`);
+            put("site", planEl, "@transform", `translate(${num(ax, 2)} ${num(ay, 2)}) rotate(${num(cam.north - flight.input.north, 3)}) scale(${pxPerFoot.toPrecision(7)}) translate(${-rinkMiddle[0]} ${-rinkMiddle[1]})`);
+            const spacing = niceLength(metresPerPixel, 170) / metresPerPixel;
+            put("site", gridEl, "@d", gridPath(ax, ay, spacing, Math.hypot(W, H)));
+            put("site", gridEl, "@transform", `rotate(${num(cam.north, 3)} ${num(ax, 2)} ${num(ay, 2)})`);
+        }
+        // The 3D arena.
+        put("3d", turnHost, "visibility", live3d ? "visible" : "hidden");
+        if (live3d && turn !== undefined) {
+            put("3d", turnHost, "opacity", num(cam.arena, 3));
+            const view = `${num(cam.yaw, 3)}|${num(cam.pitch, 3)}|${num(cam.logZoom, 4)}`;
+            if (written["3d:view"] !== view) {
+                written["3d:view"] = view;
+                turn.set({ yaw: cam.yaw, pitch: cam.pitch, zoom: Math.exp(cam.logZoom) }, false);
+            }
+        }
+        // The pin, the scale bar (true on the map and the plan, not in perspective) and the stage's words.
+        put("pin", pin, "visibility", mapOn ? "visible" : "hidden");
+        put("pin", pin, "opacity", num(cam.map, 3));
+        put("pin", pin, "transform", `translate(${num(ax, 1)}px, ${num(ay, 1)}px)`);
+        const barOpacity = 1 - cam.arena;
+        put("scale", scale, "opacity", num(barOpacity, 3));
+        put("scale", scale, "visibility", barOpacity > 0.01 ? "visible" : "hidden");
+        if (barOpacity > 0.01) {
+            const length = niceLength(metresPerPixel, 140);
+            put("scale", scaleBar, "width", `${num(length / metresPerPixel, 1)}px`);
+            const text = lengthWords(length);
+            if (scaleText.textContent !== text)
+                scaleText.textContent = text;
+        }
+    };
+    /** Say where the camera is in words: the caption, the buttons, the live region, the page's callback. */
+    const enter = (id2, announce) => {
+        if (shownStage === id2)
+            return;
+        shownStage = id2;
+        const said = stageWords(language, id2, values);
+        caption.querySelector(".kf-title").textContent = said.name;
+        caption.querySelector(".kf-text").textContent = said.text;
+        root.dataset.stage = id2;
+        for (const chip of root.querySelectorAll("button[data-stage]")) {
+            if (chip.dataset.stage === id2)
+                chip.setAttribute("aria-current", "step");
+            else
+                chip.removeAttribute("aria-current");
+        }
+        if (announce)
+            live.textContent = say(words.announce, { n: stageList.indexOf(id2) + 1, total: stageList.length, name: said.name, text: said.text });
+        settings.onStage?.(id2);
+    };
+    // ---- The clock. ----
+    let time = 0;
+    let rate = 0;
+    let playing = false;
+    let journey;
+    let frameId;
+    let last;
+    let alive = true;
+    let onScreen = true;
+    const hidden = () => doc.hidden === true;
+    const syncPlay = () => {
+        const button = root.querySelector("button[data-act=play]");
+        if (button === null)
+            return;
+        button.setAttribute("aria-pressed", String(playing));
+        const glyph = button.querySelector("[data-glyph]");
+        const word = button.querySelector("[data-word]");
+        if (glyph !== null)
+            glyph.textContent = playing ? "❚❚" : "▶";
+        if (word !== null)
+            word.textContent = playing ? words.pause : words.play;
+    };
+    const show = (at, announce = true) => {
+        time = foldTime(flight, at);
+        const cam = cameraAt(flight, time);
+        render(cam);
+        enter(stageAt(flight, time), announce);
+    };
+    const stopLoop = () => {
+        if (frameId !== undefined)
+            win?.cancelAnimationFrame(frameId);
+        frameId = undefined;
+        last = undefined;
+    };
+    const busy = () => journey !== undefined || playing || rate > 0;
+    const loop = () => {
+        if (frameId === undefined && alive && win !== null && busy() && !hidden() && onScreen && !calm())
+            frameId = win.requestAnimationFrame(tick);
+    };
+    const tick = (stamp) => {
+        frameId = undefined;
+        if (!alive)
+            return;
+        const dt = last === undefined ? 0 : Math.min(0.1, (stamp - last) / 1000);
+        last = stamp;
+        if (journey !== undefined) {
+            journey.elapsed += dt;
+            const done = journey.elapsed >= journey.seconds;
+            time = done ? journey.to : glide(journey.from, journey.to, journey.elapsed, journey.seconds);
+            if (done)
+                journey = undefined;
+        }
+        else {
+            rate = nextRate(rate, playing, dt);
+            time += rate * dt * speed;
+        }
+        show(time, true);
+        if (busy())
+            loop();
+        else
+            last = undefined;
+    };
+    const setPlaying = (next) => {
+        if (playing === next)
+            return;
+        playing = next;
+        syncPlay();
+        settings.onPlayChange?.(next);
+        if (calm())
+            scheduleStill();
+        else if (next)
+            loop();
+    };
+    // Reduced motion: a stage is a still, and playing steps to the next one every few seconds, with no motion between.
+    let stillTimer;
+    const STILL_SECONDS = 5;
+    const clearStill = () => {
+        if (stillTimer !== undefined)
+            clearTimeout(stillTimer);
+        stillTimer = undefined;
+    };
+    const stillStage = (to, announce = true) => {
+        time = startOf(flight, to) ?? 0;
+        render(flight.rest[to]);
+        enter(to, announce);
+    };
+    const scheduleStill = () => {
+        clearStill();
+        if (!playing || !alive)
+            return;
+        stillTimer = setTimeout(() => {
+            const index = stageList.indexOf(stageAt(flight, time));
+            if (index >= stageList.length - 1)
+                return setPlaying(false);
+            stillStage(stageList[index + 1]);
+            scheduleStill();
+        }, STILL_SECONDS * 1000);
+    };
+    const here = () => stageAt(flight, time);
+    const goTo = (target) => {
+        const to = typeof target === "number" ? stageList[target] : target;
+        if (to === undefined || !stageList.includes(to))
+            return;
+        if (calm()) {
+            clearStill();
+            stillStage(to);
+            if (playing)
+                scheduleStill();
+            return;
+        }
+        const from = foldTime(flight, time);
+        const goal = startOf(flight, to) ?? 0;
+        rate = 0;
+        journey = { from, to: goal, elapsed: 0, seconds: glideSeconds(goal - from) };
+        time = from;
+        last = undefined;
+        loop();
+    };
+    const step = (by) => {
+        const index = stageList.indexOf(here());
+        // Back from a stage that has run a while goes to its start; from its start, to the stage before; from the first stage's start, it starts again.
+        if (by < 0) {
+            const into = time - (startOf(flight, stageList[index]) ?? 0);
+            return goTo(into > 1.5 && !calm() ? index : Math.max(0, index - 1));
+        }
+        goTo(Math.min(stageList.length - 1, index + 1));
+    };
+    // ---- Buttons and keys. ----
+    const onClick = (event) => {
+        const target = event.target?.closest("button");
+        if (target === null || target === undefined || !root.contains(target))
+            return;
+        const wanted2 = target.dataset.stage;
+        if (wanted2 !== undefined)
+            return goTo(wanted2);
+        if (target.dataset.act === "play")
+            return void toggle();
+        if (target.dataset.act === "next")
+            return step(1);
+        if (target.dataset.act === "back")
+            return step(-1);
+    };
+    root.addEventListener("click", onClick);
+    const toggle = () => {
+        setPlaying(!playing);
+        return playing;
+    };
+    const onKey = (event) => {
+        if (event.ctrlKey || event.metaKey || event.altKey)
+            return;
+        if (event.key === " ") {
+            event.preventDefault();
+            return void toggle();
+        }
+        if (event.key === "ArrowRight") {
+            event.preventDefault();
+            return step(1);
+        }
+        if (event.key === "ArrowLeft") {
+            event.preventDefault();
+            return step(-1);
+        }
+        if (event.key === "Home") {
+            event.preventDefault();
+            return goTo(0);
+        }
+        const number = Number(event.key);
+        if (Number.isInteger(number) && number >= 1 && number <= stageList.length) {
+            event.preventDefault();
+            goTo(number - 1);
+        }
+    };
+    stage.addEventListener("keydown", onKey);
+    // ---- The page: a stage off the screen or a hidden page does not fly, and a change of size works the path out again. ----
+    let seen;
+    if (typeof IntersectionObserver === "function") {
+        seen = new IntersectionObserver((entries) => {
+            onScreen = entries[entries.length - 1]?.isIntersecting !== false;
+            if (onScreen)
+                loop();
+        });
+        seen.observe(stage);
+    }
+    const onVisible = () => {
+        last = undefined;
+        loop();
+    };
+    doc.addEventListener("visibilitychange", onVisible);
+    let observer;
+    if (typeof ResizeObserver === "function") {
+        observer = new ResizeObserver(() => {
+            if (!alive || (stage.clientWidth === width && stage.clientHeight === height))
+                return;
+            flight = makeFlight();
+            written = {};
+            if (calm())
+                stillStage(here(), false);
+            else
+                show(time, false);
+        });
+        observer.observe(stage);
+    }
+    const onMotion = () => {
+        if (!alive)
+            return;
+        stopLoop();
+        journey = undefined;
+        rate = 0;
+        if (calm())
+            stillStage(here(), false);
+        else
+            show(time, false);
+    };
+    media?.addEventListener?.("change", onMotion);
+    // ---- Start. ----
+    if (calm()) {
+        stillStage(stageList[0], false);
+        root.dataset.mode = "stages";
+        const still = doc.createElement("p");
+        still.className = "kf-still";
+        still.textContent = words.still;
+        (root.querySelector(".kf-controls") ?? root.querySelector(".kf-help"))?.after(still);
+    }
+    else {
+        root.dataset.mode = "motion";
+        show(0, false);
+    }
+    if (settings.autoPlay !== false && !calm())
+        setPlaying(true);
+    return {
+        get mode() {
+            return calm() ? "stages" : "motion";
+        },
+        get playing() {
+            return playing;
+        },
+        get stage() {
+            return here();
+        },
+        stages: stagesOf(flight),
+        get time() {
+            return time;
+        },
+        get duration() {
+            return flight.end;
+        },
+        camera: () => ({ ...current }),
+        play: () => setPlaying(true),
+        pause: () => setPlaying(false),
+        toggle,
+        next: () => step(1),
+        back: () => step(-1),
+        goTo,
+        seek(seconds) {
+            stopLoop();
+            journey = undefined;
+            rate = 0;
+            show(Math.max(0, seconds), false);
+        },
+        destroy() {
+            if (!alive)
+                return;
+            alive = false;
+            stopLoop();
+            clearStill();
+            seen?.disconnect();
+            observer?.disconnect();
+            doc.removeEventListener("visibilitychange", onVisible);
+            media?.removeEventListener?.("change", onMotion);
+            turn?.destroy();
+            host.replaceChildren();
+        },
+    };
+}