@johnmorrisdotca/kyogijo-stadiums 0.44.2 → 0.45.1

package/dist/turn.dom.d.ts

@@ -2,6 +2,7 @@ import { type TurnDirection, type TurnPreset, type TurnView } from "./turn.camer
 import { type TurnModel, type TurnSettings } from "./turn.model.ts";
 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";
 /** What `mountKyogijoTurn` gives back. `O` is what `update` takes: the options of a drawing, or (for `mountMultiTurn`) of a tournament layout. */
 export interface KyogijoTurn<O = SurfaceOptions | ScoreOptions> {
@@ -43,6 +44,12 @@ export interface KyogijoTurn<O = SurfaceOptions | ScoreOptions> {
         mode: string;
         pixels: number;
     } | undefined;
+    /** What the view was asked to draw: `auto`, or the tier it is held at. */
+    readonly quality: Quality;
+    /** The tier the view is drawn at now: what `quality` says, and for `auto` the one the frames have led it to (`high` at first). */
+    readonly tier: QualityTier;
+    /** Change what the view is asked to draw: a tier is taken at once, `auto` goes on from the tier it is at. The camera and the auto-turn are not touched. */
+    setQuality(quality: Quality): void;
     /** The flat drawing that is the floor, or `null` after `destroy`. */
     svg(): SVGSVGElement | null;
     /** Stop listening and empty the container. */

package/dist/turn.dom.js

@@ -10,6 +10,8 @@ import { KYOGIJO_TURN_STYLE } from "./turn.style.js";
 import { esc } from "./format.js";
 import { turnBoardMarkup } from "./overlay.js";
 import { attachOutside3d } from "./outside.dom.js";
+import { TIER_PROFILES, createGovernor, handheld, layerBudget, qualityOf, rasterOf, rasterShares, tierOf } from "./quality.js";
+import { size } from "./turn.kit.js";
 /** True where the page can draw a plane in 3D by one `matrix3d`: that is, nearly everywhere with a stylesheet. */
 export function turnSupported(win = typeof window === "undefined" ? undefined : window) {
     const css = win?.CSS;
@@ -43,7 +45,33 @@ export function mountTurn(host, options, settings, build) {
     const win = doc.defaultView;
     /** The venue's settings as they are now: the mounted ones, altered by `update`. */
     let venue = settings.venue;
-    let model = build(options, settings);
+    // How much is drawn: what was asked, and the tier it is drawn at (`auto` starts on `high` and is moved by the frames the view makes while it turns).
+    let quality = qualityOf(settings.quality);
+    let tier = tierOf(quality);
+    // (Set again below, once the model is built, for a view that has no tiers.)
+    const isHandheld = handheld(win);
+    /** The share of its size each layer is made at for a model, now: one number when they all are, one each when the biggest are held to a budget of pixels. */
+    const rasterFor = (of) => {
+        // (Only a model that has tiers is made smaller: a surface on its own is small, and nothing of it would be left out.)
+        if (of.tiered !== true)
+            return 1;
+        const dpr = win?.devicePixelRatio ?? 1;
+        const share = rasterOf(quality, tier, dpr, isHandheld);
+        const budget = layerBudget(tier, isHandheld);
+        if (share === 1 && budget === Infinity)
+            return 1;
+        const boxes = [[of.viewBox.w * of.scale, of.viewBox.h * of.scale], ...of.planes.map((p) => { const [w, h] = size(p); return [w * of.scale, h * of.scale]; })];
+        return rasterShares(boxes, share, dpr, budget);
+    };
+    const sameRaster = (a, b) => (typeof a === "number" || typeof b === "number" ? a === b : a.length === b.length && a.every((x, i) => x === b[i]));
+    let current = options;
+    let model = build(options, { ...settings, quality: tier });
+    if (model.tiered !== true)
+        tier = "high";
+    let raster = rasterFor(model);
+    /** The models built at each tier for the options now, so that a step back to a tier is not built again. */
+    let made = new Map([[tier, model]]);
+    const baseId = model.id;
     /** What names the four viewpoints: the model's own table (a tournament layout has one), else the sport's. */
     const sport = () => model.presets ?? model.options.sport;
     const supported = turnSupported(win ?? undefined) && model.turnable;
@@ -66,6 +94,9 @@ export function mountTurn(host, options, settings, build) {
             direction: () => turnDirection(settings.direction),
             setDirection: () => undefined,
             togglePlay: () => false,
+            quality: qualityOf(settings.quality),
+            tier: tierOf(settings.quality),
+            setQuality: () => undefined,
             update: (next, change) => {
                 if (change?.venue !== undefined)
                     venue = { ...(typeof venue === "object" ? venue : {}), ...change.venue };
@@ -79,7 +110,7 @@ export function mountTurn(host, options, settings, build) {
             },
         };
     }
-    host.innerHTML = turnMarkupOf(model, settings);
+    host.innerHTML = turnMarkupOf(model, settings, raster);
     const root = host.querySelector(".ky-turn");
     const stage = root.querySelector(".ky-turn-view");
     const live = root.querySelector(".ky-turn-live");
@@ -119,8 +150,116 @@ export function mountTurn(host, options, settings, build) {
         outside?.destroy();
         const floor = stage.querySelector(".ky-turn-floor");
         outside = model.outside === undefined || floor === null ? undefined : attachOutside3d(floor, model.outside);
+        outside?.setDetail(TIER_PROFILES[tier].outside);
     };
     crowd();
+    root.dataset.quality = quality;
+    root.dataset.tier = tier;
+    // ---- Quality: in `auto`, the frames the view makes while it turns decide the tier. ----
+    let governor = quality === "auto" && win !== null && model.tiered === true ? createGovernor(tier, settings.qualityTuning) : undefined;
+    let meterFrame;
+    let lastStamp;
+    let lastPaint = 0;
+    /** The display's own interval, measured once with nothing else going on: an idle loop of frames a moment after the mount (the lower decile of their intervals, so that a busy moment does not count). */
+    let probe;
+    let displayMs;
+    const probeDisplay = () => {
+        if (win === null || probe !== undefined || displayMs !== undefined)
+            return;
+        const found = [];
+        let before;
+        const step = (stamp) => {
+            probe = undefined;
+            if (!alive || win === null)
+                return;
+            if (doc.hidden === true) {
+                // Hidden: start over when it can be seen.
+                found.length = 0;
+                before = undefined;
+                probe = win.setTimeout(() => (probe = win.requestAnimationFrame(step)), 400);
+                return;
+            }
+            if (before !== undefined)
+                found.push(stamp - before);
+            before = stamp;
+            if (found.length < 24)
+                probe = win.requestAnimationFrame(step);
+            else {
+                displayMs = [...found].sort((a, b) => a - b)[Math.floor(found.length * 0.1)];
+                governor?.display(displayMs);
+            }
+        };
+        probe = win.setTimeout(() => (probe = win.requestAnimationFrame(step)), 350);
+    };
+    const stopMeter = () => {
+        if (meterFrame !== undefined)
+            win?.cancelAnimationFrame(meterFrame);
+        meterFrame = undefined;
+        lastStamp = undefined;
+    };
+    if (governor !== undefined)
+        probeDisplay();
+    /** The loop that times the frames: it runs while the view is being painted and for a third of a second after, and does nothing while the view is still. */
+    const meterTick = (stamp) => {
+        meterFrame = undefined;
+        if (!alive || governor === undefined || win === null)
+            return;
+        if (doc.hidden === true || stamp - lastPaint > 300) {
+            lastStamp = undefined;
+            governor.pause();
+            return;
+        }
+        const next = lastStamp === undefined ? undefined : governor.frame(stamp - lastStamp, stamp);
+        lastStamp = next === undefined ? stamp : undefined;
+        // (A step draws the view again, which asks for the loop itself: only one is ever running.)
+        if (next !== undefined)
+            retier(next);
+        if (meterFrame === undefined)
+            meterFrame = win.requestAnimationFrame(meterTick);
+    };
+    /** The view was painted: the frames are timed from now until it is still. */
+    const touched = () => {
+        if (governor === undefined || win === null)
+            return;
+        lastPaint = win.performance.now();
+        if (meterFrame === undefined)
+            meterFrame = win.requestAnimationFrame(meterTick);
+    };
+    /** Draw the world again, from the model of the tier and the options now: the camera, the auto-turn and the pointer are not touched (the elements are the only thing replaced). */
+    const renderWorld = () => {
+        const known = made.get(tier);
+        model = known ?? build(current, { ...settings, quality: tier, id: settings.id ?? baseId, venue, preset: undefined, view });
+        made.set(tier, model);
+        raster = rasterFor(model);
+        const layout = layoutOf(model, shown, stage.clientWidth || 960, stage.clientHeight || 600, settings.lens, false, raster);
+        const world = root.querySelector(".ky-turn-world");
+        world.innerHTML = worldMarkup(model, layout, raster);
+        // The look the floor is painted in (and the theme) are attributes of the world.
+        for (const name of ["data-sport", "data-look", "data-theme"])
+            world.removeAttribute(name);
+        world.className = model.look === undefined ? "ky-turn-world" : "ky-turn-world kyogijo";
+        if (model.look !== undefined) {
+            world.setAttribute("data-sport", model.look.sport);
+            world.setAttribute("data-look", model.look.look);
+            const forced = model.options.theme;
+            if (forced === "light" || forced === "dark")
+                world.setAttribute("data-theme", forced);
+        }
+        gather();
+        crowd();
+        root.dataset.quality = quality;
+        root.dataset.tier = tier;
+    };
+    /** The governor stepped: draw at the new tier. */
+    const retier = (next) => {
+        if (next === tier)
+            return;
+        tier = next;
+        renderWorld();
+        paint(shown);
+        label();
+        settings.onQualityChange?.(tier, quality);
+    };
     const buttons = () => root.querySelectorAll("button[data-preset]");
     /** The Play button says what it is and what it does: pressed while the view turns. */
     const syncPlay = () => {
@@ -138,7 +277,7 @@ export function mountTurn(host, options, settings, build) {
     const paint = (now) => {
         const width = stage.clientWidth || 960;
         const height = stage.clientHeight || 600;
-        const layout = layoutOf(model, now, width, height, settings.lens, true);
+        const layout = layoutOf(model, now, width, height, settings.lens, true, raster);
         outside?.zoom(now.zoom);
         const culled = layout.culled;
         elements.forEach((one, i) => {
@@ -159,6 +298,7 @@ export function mountTurn(host, options, settings, build) {
             if (faded[i] !== o)
                 one.style.opacity = faded[i] = o;
         });
+        touched();
     };
     const label = () => {
         const here = presetOf(view, sport());
@@ -481,25 +621,11 @@ export function mountTurn(host, options, settings, build) {
                 return;
             if (change?.venue !== undefined)
                 venue = { ...(typeof venue === "object" ? venue : {}), ...change.venue };
-            model = build(next, { ...settings, id: settings.id ?? model.id, venue, preset: undefined, view });
+            current = next;
+            made = new Map();
             view = clampView(view);
+            renderWorld();
             opening = openingView(settings, sport());
-            const layout = layoutOf(model, shown, stage.clientWidth || 960, stage.clientHeight || 600, settings.lens);
-            const world = root.querySelector(".ky-turn-world");
-            world.innerHTML = worldMarkup(model, layout);
-            // The look the floor is painted in (and the theme) are attributes of the world.
-            for (const name of ["data-sport", "data-look", "data-theme"])
-                world.removeAttribute(name);
-            world.className = model.look === undefined ? "ky-turn-world" : "ky-turn-world kyogijo";
-            if (model.look !== undefined) {
-                world.setAttribute("data-sport", model.look.sport);
-                world.setAttribute("data-look", model.look.look);
-                const forced = model.options.theme;
-                if (forced === "light" || forced === "dark")
-                    world.setAttribute("data-theme", forced);
-            }
-            gather();
-            crowd();
             // The board is a layer of its own over the view, after the scene: it is written again, and the view's turn is not touched.
             stage.querySelector(".ky-turn-board")?.remove();
             if (model.board !== undefined)
@@ -525,6 +651,45 @@ export function mountTurn(host, options, settings, build) {
         get playing() {
             return playing;
         },
+        get quality() {
+            return quality;
+        },
+        get tier() {
+            return tier;
+        },
+        setQuality(asked) {
+            if (!alive)
+                return;
+            quality = qualityOf(asked, quality);
+            const was = tier;
+            if (model.tiered !== true) {
+                // A view that has no tiers draws as it does whatever is asked: the question is kept, and answered `high`.
+                governor = undefined;
+                stopMeter();
+                tier = "high";
+            }
+            else if (quality === "auto") {
+                stopMeter();
+                governor = win === null ? undefined : createGovernor(tier, settings.qualityTuning);
+                if (displayMs !== undefined)
+                    governor?.display(displayMs);
+                else
+                    probeDisplay();
+            }
+            else {
+                governor = undefined;
+                stopMeter();
+                tier = quality;
+            }
+            root.dataset.quality = quality;
+            // The tier, or the share its layers are made at, has changed: the world is drawn again (the shares are worked out for the model of the tier, in `renderWorld`).
+            if (tier !== was || !sameRaster(rasterFor(model), raster)) {
+                renderWorld();
+                paint(shown);
+                label();
+            }
+            settings.onQualityChange?.(tier, quality);
+        },
         play() {
             setPlaying(true);
             return playing;
@@ -557,6 +722,7 @@ export function mountTurn(host, options, settings, build) {
             outside?.destroy();
             stop();
             stopTick();
+            stopMeter();
             seen?.disconnect();
             doc.removeEventListener("visibilitychange", onVisible);
             clearTimeout(spoken);

package/dist/turn.markup.d.ts

@@ -2,6 +2,8 @@ import { type Placement, type TurnDirection, type TurnView } from "./turn.camera
 import { type Plane } from "./turn.kit.ts";
 import { type TurnModel, type TurnSettings } from "./turn.model.ts";
 import type { ScoreOptions, SurfaceOptions } from "./types.ts";
+/** The share of its size each layer is made at: one number for all, or one for each (the floor first, then the planes in the model's order). */
+export type Raster = number | readonly number[];
 /**
  * The matrix that stands a plane in the scene, before the camera: its x along `u`, its y along `v`, its corner `o`, in pixels from the middle of the scene
  * (`centre`, in feet).
@@ -28,18 +30,19 @@ export interface Layout {
 }
 /**
  * Work a view out in a container `width` by `height` pixels. With `cull`, the faces of a closed solid that are turned away from the eye (`Plane.cull`) are left out: they have no transform and no place in the stack, and `culled` says
- * which, so that a page need not write them at all; without it every plane is laid out, as a still picture needs.
+ * which, so that a page need not write them at all; without it every plane is laid out, as a still picture needs. `raster` is the share of its size an element is made at (`rasterOf`): each element's matrix widens it back, so that the
+ * picture is the same and the layers hold `raster` squared as many pixels.
  */
-export declare function layoutOf(model: TurnModel, view: TurnView, width: number, height: number, lens?: number, cull?: boolean): Layout;
+export declare function layoutOf(model: TurnModel, view: TurnView, width: number, height: number, lens?: number, cull?: boolean, raster?: Raster): Layout;
 /** One plane as an element: its box in pixels and the SVG drawn on it in feet. */
-export declare function planeMarkup(p: Plane, scale: number, transform: string, stack: number, fade?: number): string;
+export declare function planeMarkup(p: Plane, scale: number, transform: string, stack: number, fade?: number, raster?: number): string;
 /**
  * A plane that is the floor's own drawing seen through its rectangle (`Plane.crop`): the floor's SVG again, its viewBox cut down to the plane's rectangle, in the plane's own box. It is a picture, not a second
  * description: it carries no role, title or description of its own.
  */
-export declare function cropMarkup(model: TurnModel, p: Plane, transform: string, stack: number, fade?: number): string;
+export declare function cropMarkup(model: TurnModel, p: Plane, transform: string, stack: number, fade?: number, raster?: number): string;
 /** The floor as an element: the flat drawing, in the pixels of the scene. */
-export declare function floorMarkup(model: TurnModel, transform: string, stack: number): string;
+export declare function floorMarkup(model: TurnModel, transform: string, stack: number, raster?: number): string;
 /** The patterns the venue's planes are drawn with, once, in a box of no size: every plane's SVG reads them by id, and the crowd's colours are on this element. */
 export declare function defsMarkup(model: TurnModel): string;
 /**
@@ -48,7 +51,7 @@ export declare function defsMarkup(model: TurnModel): string;
  */
 export declare function worldAttributes(model: TurnModel): string;
 /** The floor and the planes of a model, laid out. */
-export declare function worldMarkup(model: TurnModel, layout: Layout): string;
+export declare function worldMarkup(model: TurnModel, layout: Layout, raster?: Raster): string;
 /** The buttons under the view. */
 export declare function controlsMarkup(model: TurnModel, view: TurnView, playing?: boolean, direction?: TurnDirection): string;
 /** The size, in pixels, the first view is worked out for. */
@@ -57,7 +60,7 @@ export declare const sizeOf: (settings: TurnSettings) => {
     height: number;
 };
 /** The 3D view of a model as markup, laid out for `settings.size`; a page's script then makes it turn. */
-export declare function turnMarkupOf(model: TurnModel, settings?: TurnSettings): string;
+export declare function turnMarkupOf(model: TurnModel, settings?: TurnSettings, raster?: Raster): string;
 /**
  * A surface as a 3D view, as markup: the flat drawing for a floor, what stands on it as planes, and the controls under it. Pure, so it can be made on a
  * server; it is a still picture until `mountKyogijoTurn` (or the element) makes it turn in a page.

package/dist/turn.markup.js

@@ -9,6 +9,8 @@ import { KYOGIJO_TURN_STYLE } from "./turn.style.js";
 import { esc } from "./format.js";
 import { turnBoardMarkup } from "./overlay.js";
 const px = (value) => `${Math.round(value * 1000) / 1000}`;
+/** The share of the layer at `index` (0 the floor, then the planes). */
+const shareOf = (raster, index) => (typeof raster === "number" ? raster : (raster[index] ?? 1));
 /**
  * The matrix that stands a plane in the scene, before the camera: its x along `u`, its y along `v`, its corner `o`, in pixels from the middle of the scene
  * (`centre`, in feet).
@@ -88,9 +90,10 @@ function prepare(model) {
 const turnedAway = (m, side) => side * (m[0] * (m[5] * m[15] - m[13] * m[7]) - m[4] * (m[1] * m[15] - m[13] * m[3]) + m[12] * (m[1] * m[7] - m[5] * m[3])) <= 0;
 /**
  * Work a view out in a container `width` by `height` pixels. With `cull`, the faces of a closed solid that are turned away from the eye (`Plane.cull`) are left out: they have no transform and no place in the stack, and `culled` says
- * which, so that a page need not write them at all; without it every plane is laid out, as a still picture needs.
+ * which, so that a page need not write them at all; without it every plane is laid out, as a still picture needs. `raster` is the share of its size an element is made at (`rasterOf`): each element's matrix widens it back, so that the
+ * picture is the same and the layers hold `raster` squared as many pixels.
  */
-export function layoutOf(model, view, width, height, lens, cull = false) {
+export function layoutOf(model, view, width, height, lens, cull = false, raster = 1) {
     const distance = eyeDistance(width, height, lens ?? model.lens);
     const at = fit(model.box, { ...view, zoom: 1 }, width, height, distance);
     const camera = cameraMatrix(view, at, distance);
@@ -99,15 +102,24 @@ export function layoutOf(model, view, width, height, lens, cull = false) {
     const known = prepare(model);
     const floor = { id: "floor", kind: "ground", o: [model.viewBox.x, model.viewBox.y, model.uprights.lift], u: [model.viewBox.w, 0, 0], v: [0, model.viewBox.h, 0], svg: "" };
     const count = model.planes.length;
+    const widen = (m, index) => {
+        const share = shareOf(raster, index);
+        if (share === 1)
+            return m;
+        const back = 1 / share;
+        for (let i = 0; i < 8; i += 1)
+            m[i] *= back;
+        return m;
+    };
     const transforms = new Array(count + 1);
     const culled = cull ? new Array(count + 1).fill(false) : undefined;
     // A billboard faces the eye at this view.
     const planes = new Array(count);
     for (let i = 0; i < count; i += 1)
         planes[i] = facing(model.planes[i], view.yaw, view.pitch);
-    transforms[0] = matrix3d(multiply(camera, planeMatrix(floor, s, centre)));
+    transforms[0] = matrix3d(widen(multiply(camera, planeMatrix(floor, s, centre)), 0));
     for (let i = 0; i < count; i += 1) {
-        const m = multiply(camera, known.base[i] ?? planeMatrix(planes[i], s, centre));
+        const m = widen(multiply(camera, known.base[i] ?? planeMatrix(planes[i], s, centre)), i + 1);
         const side = planes[i].cull;
         if (culled !== undefined && side !== undefined && turnedAway(m, side)) {
             culled[i + 1] = true;
@@ -159,15 +171,16 @@ export function layoutOf(model, view, width, height, lens, cull = false) {
     return { at, transforms, stack, fade, ...(culled === undefined ? {} : { culled }) };
 }
 /** One plane as an element: its box in pixels and the SVG drawn on it in feet. */
-export function planeMarkup(p, scale, transform, stack, fade = 1) {
+export function planeMarkup(p, scale, transform, stack, fade = 1, raster = 1) {
     const [w, h] = size(p);
-    return `<div class="ky-up ky-up-${p.kind}" data-part="${esc(p.id)}" style="width:${px(w * scale)}px;height:${px(h * scale)}px;transform:${transform};z-index:${stack}${fade < 1 ? `;opacity:${n(fade)}` : ""}"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${n(w)} ${n(h)}" width="${px(w * scale)}" height="${px(h * scale)}" aria-hidden="true" focusable="false">${p.svg}</svg></div>`;
+    const [bw, bh] = [px(w * scale * raster), px(h * scale * raster)];
+    return `<div class="ky-up ky-up-${p.kind}" data-part="${esc(p.id)}" style="width:${bw}px;height:${bh}px;transform:${transform};z-index:${stack}${fade < 1 ? `;opacity:${n(fade)}` : ""}"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${n(w)} ${n(h)}" width="${bw}" height="${bh}" aria-hidden="true" focusable="false">${p.svg}</svg></div>`;
 }
 /**
  * A plane that is the floor's own drawing seen through its rectangle (`Plane.crop`): the floor's SVG again, its viewBox cut down to the plane's rectangle, in the plane's own box. It is a picture, not a second
  * description: it carries no role, title or description of its own.
  */
-export function cropMarkup(model, p, transform, stack, fade = 1) {
+export function cropMarkup(model, p, transform, stack, fade = 1, raster = 1) {
     const [w, h] = size(p);
     const box = `${px(p.o[0])} ${px(p.o[1])} ${px(w)} ${px(h)}`;
     const picture = model.floor
@@ -177,12 +190,12 @@ export function cropMarkup(model, p, transform, stack, fade = 1) {
         .replace(/^<svg([^>]*?)\srole="img"/, '<svg$1 aria-hidden="true"')
         .replace(/^<svg([^>]*?)\saria-labelledby="[^"]*"/, "<svg$1")
         .replace(/<title\b[^>]*>[\s\S]*?<\/title>|<desc\b[^>]*>[\s\S]*?<\/desc>/g, "");
-    return `<div class="ky-up ky-up-${p.kind}" data-part="${esc(p.id)}" data-crop="floor" style="width:${px(w * model.scale)}px;height:${px(h * model.scale)}px;transform:${transform};z-index:${stack}${fade < 1 ? `;opacity:${n(fade)}` : ""}">${picture}</div>`;
+    return `<div class="ky-up ky-up-${p.kind}" data-part="${esc(p.id)}" data-crop="floor" style="width:${px(w * model.scale * raster)}px;height:${px(h * model.scale * raster)}px;transform:${transform};z-index:${stack}${fade < 1 ? `;opacity:${n(fade)}` : ""}">${picture}</div>`;
 }
 /** The floor as an element: the flat drawing, in the pixels of the scene. */
-export function floorMarkup(model, transform, stack) {
+export function floorMarkup(model, transform, stack, raster = 1) {
     const vb = model.viewBox;
-    return `<div class="ky-turn-floor" style="width:${px(vb.w * model.scale)}px;height:${px(vb.h * model.scale)}px;transform:${transform};z-index:${stack}">${model.floor}</div>`;
+    return `<div class="ky-turn-floor"${raster === 1 ? "" : ` data-raster="${raster}"`} style="width:${px(vb.w * model.scale * raster)}px;height:${px(vb.h * model.scale * raster)}px;transform:${transform};z-index:${stack}">${model.floor}</div>`;
 }
 /** The patterns the venue's planes are drawn with, once, in a box of no size: every plane's SVG reads them by id, and the crowd's colours are on this element. */
 export function defsMarkup(model) {
@@ -197,8 +210,8 @@ export function worldAttributes(model) {
     return model.look === undefined ? 'class="ky-turn-world"' : `class="ky-turn-world kyogijo" data-sport="${esc(model.look.sport)}" data-look="${esc(model.look.look)}"${theme === "light" || theme === "dark" ? ` data-theme="${theme}"` : ""}`;
 }
 /** The floor and the planes of a model, laid out. */
-export function worldMarkup(model, layout) {
-    return defsMarkup(model) + floorMarkup(model, layout.transforms[0], layout.stack[0]) + model.planes.map((p, i) => (p.crop === true ? cropMarkup(model, p, layout.transforms[i + 1], layout.stack[i + 1], layout.fade[i + 1]) : planeMarkup(p, model.scale, layout.transforms[i + 1], layout.stack[i + 1], layout.fade[i + 1]))).join("");
+export function worldMarkup(model, layout, raster = 1) {
+    return defsMarkup(model) + floorMarkup(model, layout.transforms[0], layout.stack[0], shareOf(raster, 0)) + model.planes.map((p, i) => (p.crop === true ? cropMarkup(model, p, layout.transforms[i + 1], layout.stack[i + 1], layout.fade[i + 1], shareOf(raster, i + 1)) : planeMarkup(p, model.scale, layout.transforms[i + 1], layout.stack[i + 1], layout.fade[i + 1], shareOf(raster, i + 1)))).join("");
 }
 /** The buttons under the view. */
 export function controlsMarkup(model, view, playing = false, direction = "counterclockwise") {
@@ -223,18 +236,18 @@ export function controlsMarkup(model, view, playing = false, direction = "counte
 /** The size, in pixels, the first view is worked out for. */
 export const sizeOf = (settings) => settings.size ?? { width: 960, height: 600 };
 /** The 3D view of a model as markup, laid out for `settings.size`; a page's script then makes it turn. */
-export function turnMarkupOf(model, settings = {}) {
+export function turnMarkupOf(model, settings = {}, raster = 1) {
     const words = turnWords(model);
     const { width, height } = sizeOf(settings);
     const view = model.view;
-    const layout = layoutOf(model, view, width, height, settings.lens);
+    const layout = layoutOf(model, view, width, height, settings.lens, false, raster);
     const keys = `${words.keys}${model.standing === "" ? "" : ` ${model.standing}`}`;
     const sheet = model.options.style === "none" ? "" : `<style>${KYOGIJO_TURN_STYLE}</style>`;
     const theme = model.options.theme;
     const sport = model.options.sport;
     return (`<div class="ky-turn" id="${esc(model.id)}" data-sport="${esc(String(sport))}" data-mode="3d" data-touch="${settings.touch === "turn" ? "turn" : "scroll"}" data-preset="${presetOf(view, model.presets ?? sport) ?? "custom"}"${model.lighting === undefined ? "" : ` data-lighting="${model.lighting}"`}${theme === "light" || theme === "dark" ? ` data-theme="${theme}"` : ""} lang="${model.language}">` +
         sheet +
-        `<div class="ky-turn-view" tabindex="0" role="group" aria-roledescription="${esc(words.region)}" aria-label="${esc(model.title)}" aria-describedby="${esc(model.id)}-help" aria-keyshortcuts="ArrowLeft ArrowRight ArrowUp ArrowDown + - 0 1 2 3 4 Home Space"><div ${worldAttributes(model)}>${worldMarkup(model, layout)}</div>${model.board === undefined ? "" : turnBoardMarkup(model.board)}</div>` +
+        `<div class="ky-turn-view" tabindex="0" role="group" aria-roledescription="${esc(words.region)}" aria-label="${esc(model.title)}" aria-describedby="${esc(model.id)}-help" aria-keyshortcuts="ArrowLeft ArrowRight ArrowUp ArrowDown + - 0 1 2 3 4 Home Space"><div ${worldAttributes(model)}>${worldMarkup(model, layout, raster)}</div>${model.board === undefined ? "" : turnBoardMarkup(model.board)}</div>` +
         `<p class="ky-turn-help" id="${esc(model.id)}-help">${esc(keys)}</p>` +
         (settings.controls === false ? "" : controlsMarkup(model, view, false, turnDirection(settings.direction))) +
         `<div class="ky-turn-live" role="status" aria-live="polite"></div>` +

package/dist/turn.model.d.ts

@@ -6,6 +6,7 @@ import { type ResolvedBoard } from "./overlay.ts";
 import type { VenueSettings } from "./venue.ts";
 import type { Box3 } from "./turn.camera.ts";
 import type { OutsideSpec } from "./outside.dom.ts";
+import type { GovernorTuning, Quality, QualityTier } from "./quality.ts";
 import type { Language, LightingOptions, LightingPreset, ScoreOptions, SurfaceOptions } from "./types.ts";
 /** What can be asked of a 3D view. */
 export interface TurnSettings {
@@ -53,6 +54,16 @@ export interface TurnSettings {
     onDirectionChange?: (direction: TurnDirection) => void;
     /** Called with `true` when the auto-turn starts and `false` when it stops, whatever stopped it. */
     onPlayChange?: (playing: boolean) => void;
+    /**
+     * How much the view draws, so that it turns well on every device: `"auto"` (the default) starts on `high` and watches the frames the view makes while it turns, stepping a tier down when they run over budget for a while and back up
+     * when they have been steady for longer; `"high"` is everything as it always was; `"medium"` and `"low"` draw less (the buildings round a district stand up fewer, the trees and the crowd are thinner, a small venue is a block, and the layers
+     * are rastered at a lower pixel ratio). A tier asked for by name is kept; `setQuality` changes it at once, and the camera and the auto-turn go on. See `docs/quality.md`.
+     */
+    quality?: Quality;
+    /** How the frames are judged in `auto` (see `GovernorTuning`): for a test or a screen that is unusual; the defaults suit a 60 Hz display. */
+    qualityTuning?: Partial<GovernorTuning>;
+    /** Called with the tier the view is drawn at when it is first mounted and each time `auto` or `setQuality` changes it. */
+    onQualityChange?: (tier: QualityTier, quality: Quality) => void;
     /** Called after the view has changed by a key, a button or the pointer, with the view and the viewpoint it is (`undefined` when it has been turned by hand). */
     onChange?: (view: TurnView, preset: TurnPreset | undefined) => void;
 }
@@ -113,6 +124,8 @@ export interface TurnModel {
     }[];
     /** The board the options ask for (`board`), laid over the view: a layer of its own, never a plane of the scene. */
     board?: ResolvedBoard;
+    /** Whether the model has tiers: a district's does (`quality`), a single surface's does not, and the view does not time its frames or make its layers smaller for one that has none. */
+    tiered?: boolean;
     /** The crowd outside the venues of a district, asked for (`DistrictOptions.outside`): a canvas on the floor that the mount paints (`outside.dom.ts`), never a plane of the scene. */
     outside?: OutsideSpec;
 }

package/dist/turn.style.js

@@ -80,6 +80,12 @@ export const KYOGIJO_TURN_STYLE = `
 .ky-turn .u-slab-top{fill:var(--ky-up-blk-roof);stroke:var(--ky-up-blk-line);stroke-width:.5}
 .ky-turn .u-floorplate{fill:var(--ky-up-plate);stroke:var(--ky-up-plate-line);stroke-width:1.2;stroke-linejoin:round}
 .ky-turn .u-block-roof{fill:var(--ky-up-blk-roof);stroke:var(--ky-up-blk-line);stroke-width:.5;stroke-linejoin:round}
+/* A venue drawn as a proxy in the lower tiers (district.turn.ts): the tones of the buildings round it, darker and bluer, as a stadium's concrete and roof read against a city's. */
+.ky-turn .u-proxy{stroke:var(--ky-up-blk-line);stroke-width:.6}
+.ky-turn .u-proxy-a{fill:color-mix(in srgb,var(--ky-up-blk-a) 52%,#4d6fa0)}
+.ky-turn .u-proxy-b{fill:color-mix(in srgb,var(--ky-up-blk-b) 52%,#3f5c88)}
+.ky-turn .u-proxy-c{fill:color-mix(in srgb,var(--ky-up-blk-c) 52%,#324b72)}
+.ky-turn .u-proxy-roof{fill:color-mix(in srgb,var(--ky-up-blk-roof) 60%,#5f7fae);stroke:var(--ky-up-blk-line);stroke-width:.6;stroke-linejoin:round}
 .ky-turn .u-roof{fill:var(--ky-up-roof);stroke:var(--ky-up-roofline);stroke-width:.8;stroke-linejoin:round}
 .ky-turn .u-signplate{fill:var(--ky-turn-bg);fill-opacity:.9;stroke:var(--ky-turn-rule);stroke-width:.5}
 .ky-turn .u-sign{fill:var(--ky-turn-ink);font-family:var(--ky-font,system-ui,-apple-system,"Segoe UI","Hiragino Sans","Noto Sans JP",sans-serif);font-weight:600}

package/dist/uprights.fields.d.ts

@@ -1,7 +1,7 @@
 import type { FieldPlan } from "./fields.types.ts";
 import { type FencePoint, type FootballSpec } from "./geometry.ts";
 import type { SoccerSpec } from "./surfaces/soccer-spec.ts";
-import type { ParkWall } from "./parks.ts";
+import type { ParkWall } from "./parks.core.ts";
 import { type Plane, type Upright } from "./turn.kit.ts";
 /**
  * The crossbar of a football post is 10 ft over the ground (NFL 2026 Rule 1-3-1: "the top face of which is 10 feet above the ground"; CFL 2026 Rule 1-1-1:

package/dist/uprights.js

@@ -11,7 +11,7 @@ import { diamondFence } from "./leagues/baseball.js";
 import { NBA_COURT } from "./leagues/basketball.js";
 import { NHL_RINK } from "./leagues/hockey.js";
 import { chooseLeague, courtOf, diamondOf, fieldOf, rinkOf } from "./leagues.js";
-import { fenceFor, parkById, parkWallsIn } from "./parks.js";
+import { fenceFor, heldPark, parkWallsIn } from "./parks.core.js";
 import { fenceOutline } from "./surfaces/baseball.js";
 import { KYOGIJO_STRINGS, fill } from "./strings.js";
 import { soccerSpec } from "./surfaces/soccer-spec.js";
@@ -65,7 +65,7 @@ export function uprightsFor(o, settings = {}) {
     }
     else if (sport === "mlb") {
         const diamond = league?.family === "baseball" ? diamondOf(league, o.year) : undefined;
-        const park = parkById(o.park);
+        const park = heldPark(o.park);
         const points = fenceFor(park, feetFence(o.fence, unit), o.year, diamond === undefined ? undefined : diamondFence(diamond));
         thin = 0.4;
         items = ballparkUprights(points, park === undefined ? [] : parkWallsIn(park, o.year), thin);

package/dist/venue-data-entry.d.ts

@@ -0,0 +1,5 @@
+export { loadArena, loadGround, loadPark, loadVenueDataFor, venueDataKeysFor, venueName } from "./venue-data.ts";
+export type { VenueDataKeys } from "./venue-data.ts";
+export type { Arena } from "./arenas.core.ts";
+export type { Ground } from "./grounds.core.ts";
+export type { Park } from "./parks.core.ts";

package/dist/venue-data-entry.js

@@ -0,0 +1,2 @@
+// The data of the venues a page shows, one file each, read when asked for: `loadVenueDataFor` for the venues of a district, `loadArena`, `loadPark` and `loadGround` for one, `venueName` to list the venues by name without reading any of them.
+export { loadArena, loadGround, loadPark, loadVenueDataFor, venueDataKeysFor, venueName } from "./venue-data.js";

package/dist/venue-data.d.ts

@@ -0,0 +1,64 @@
+import { type Arena } from "./arenas.core.ts";
+import { type Ground } from "./grounds.core.ts";
+import { type Park } from "./parks.core.ts";
+import type { Language } from "./types.ts";
+/**
+ * An arena by its key, read from its own file the first time and held for the drawing after: asking again gives the same promise. A key that is not an arena rejects, naming the keys there are.
+ * @example
+ * ```ts
+ * import { loadArena } from "@johnmorrisdotca/kyogijo-stadiums/venue-data";
+ * const arena = await loadArena("rogers-arena");
+ * console.log(arena.name, arena.city);
+ * // Rogers Arena Vancouver
+ * ```
+ */
+export declare const loadArena: (id: string) => Promise<Arena>;
+/** A park by its key, read from its own file the first time and held for the drawing after (see `loadArena`). */
+export declare const loadPark: (id: string) => Promise<Park>;
+/** A ground by its key, read from its own file the first time and held for the drawing after (see `loadArena`). */
+export declare const loadGround: (id: string) => Promise<Ground>;
+/** The keys of the arenas, parks and grounds whose records the drawing of some venues reads. */
+export interface VenueDataKeys {
+    arenas: string[];
+    parks: string[];
+    grounds: string[];
+}
+/**
+ * The records the drawing of some venues of a district reads, by kind: an arena's own, a ballpark's park, a stadium's ground, and nothing for a hall (which carries its own names) or the Kodokan. The keys are a district's (`rogers-arena`,
+ * `bc-place:cfl`).
+ * @example
+ * ```ts
+ * import { venueDataKeysFor } from "@johnmorrisdotca/kyogijo-stadiums/venue-data";
+ * console.log(venueDataKeysFor(["rogers-arena", "bc-place:cfl", "t-mobile-park:mlb"]));
+ * // {
+ * //   arenas: [ 'rogers-arena' ],
+ * //   parks: [ 't-mobile-park' ],
+ * //   grounds: [ 'bc-place' ]
+ * // }
+ * ```
+ */
+export declare function venueDataKeysFor(venues: readonly string[]): VenueDataKeys;
+/**
+ * The records of the venues a page is about to draw, each read from its own file and no other, and held for the drawing: what `planDistrict`, `drawDistrict` and `mountDistrictTurn` of the lean district read. Await it before the
+ * first call and again when the venues change; a venue whose records are held is not read twice.
+ * @example
+ * ```ts
+ * import { loadVenueDataFor, planDistrict } from "@johnmorrisdotca/kyogijo-stadiums/district-lean";
+ * const venues = ["bc-place:cfl", "rogers-arena"];
+ * await loadVenueDataFor(venues);
+ * console.log(planDistrict({ venues }).members.length);
+ * // 2
+ * ```
+ */
+export declare function loadVenueDataFor(venues: readonly string[]): Promise<void>;
+/**
+ * The name of a venue of a district in a language, from the lists of names alone: no record is read, so a page can list every venue to choose from and read only the records of those chosen. It is the name `districtMember(key, language).name[language]` gives.
+ * `undefined` for a key that is not a venue of a district.
+ * @example
+ * ```ts
+ * import { venueName } from "@johnmorrisdotca/kyogijo-stadiums/venue-data";
+ * console.log(venueName("rogers-arena", "en"), venueName("bc-place:cfl", "ja"));
+ * // Rogers Arena BCプレイス
+ * ```
+ */
+export declare function venueName(key: string, language?: Language): string | undefined;