@johnmorrisdotca/kyogijo-stadiums 0.4.0 → 0.6.0

package/dist/turn.dom.js

@@ -0,0 +1,353 @@
+// The 3D view in a page: `mountKyogijoTurn` writes the scene (`turn.markup.ts`) into a container and makes it turn, as the cube of kyuubu turns: a drag turns and
+// tips it, a pinch or Ctrl and the wheel zoom, the arrow keys step it, four viewpoints and a reset are a button or a number key away, a reader who prefers
+// reduced motion gets jumps for glides, and where the browser cannot draw in 3D the flat drawing stays. Nothing is polled and nothing runs while the view is
+// still: the elements' `transform`s are written when the view changes, and a glide between viewpoints is a short run of animation frames.
+import { drawKyogijo } from "./draw.js";
+import { STEP, TURN_PRESET_NAMES, clampView, drag, nearest, nudge, presetOf, presetView, step } from "./turn.camera.js";
+import { buildTurn, floorOptions, openingView, turnWords } from "./turn.model.js";
+import { controlsMarkup, layoutOf, turnMarkupOf, worldMarkup } from "./turn.markup.js";
+import { KYOGIJO_TURN_STYLE } from "./turn.style.js";
+import { esc } from "./format.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;
+    if (css === undefined || css === null || typeof css.supports !== "function")
+        return false;
+    return css.supports("transform", "matrix3d(1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1)");
+}
+const KEYS = { ArrowLeft: true, ArrowRight: true, ArrowUp: true, ArrowDown: true, "+": true, "=": true, "-": true, _: true, "0": true, Home: true, "1": true, "2": true, "3": true, "4": true };
+/** The view part of the way from one to another, `t` from 0 to 1, the turn taken the short way round. */
+const between = (from, to, t) => ({ yaw: from.yaw + (nearest(from.yaw, to.yaw) - from.yaw) * t, pitch: from.pitch + (to.pitch - from.pitch) * t, zoom: from.zoom * Math.pow(to.zoom / from.zoom, t) });
+/**
+ * Mount a surface as a 3D view in a container, over the static drawing it would otherwise hold: the drawing is the floor, tilted and turned by the pointer, the
+ * touch, the wheel and the keys, with what stands on the surface (a net and its posts, a basket, a goal, the posts of a football field) standing on it.
+ * @example
+ * ```ts no-run
+ * import { mountKyogijoTurn } from "@johnmorrisdotca/kyogijo-stadiums/turn";
+ * const view = mountKyogijoTurn(document.querySelector("#court")!, { sport: "volleyball", home: { name: "Harbour City Gulls", score: 3 }, away: { name: "Prairie Ridge Bison", score: 2 } }, { preset: "end" });
+ * view.preset("corner");
+ * view.set({ yaw: 60, pitch: 40 });
+ * ```
+ */
+export function mountKyogijoTurn(host, options, settings = {}) {
+    const doc = host.ownerDocument;
+    const win = doc.defaultView;
+    let model = buildTurn(options, settings);
+    const sport = () => model.options.sport;
+    const supported = turnSupported(win ?? undefined) && model.turnable;
+    let alive = true;
+    if (!supported) {
+        // The flat drawing, with a sentence that says why it does not turn when the browser is the reason.
+        const flat = (next) => {
+            host.innerHTML = `<div class="ky-turn" data-mode="flat"><style>${KYOGIJO_TURN_STYLE}</style>${drawKyogijo(floorOptions(next))}${model.turnable ? `<p class="ky-turn-flat">${esc(turnWords(model).flat)}</p>` : ""}</div>`;
+        };
+        flat(options);
+        return {
+            mode: "flat",
+            view: () => model.view,
+            set: () => undefined,
+            preset: () => undefined,
+            reset: () => undefined,
+            update: (next) => {
+                model = buildTurn(next, settings);
+                flat(next);
+            },
+            svg: () => (alive ? host.querySelector("svg.kyogijo") : null),
+            destroy: () => {
+                alive = false;
+                host.replaceChildren();
+            },
+        };
+    }
+    host.innerHTML = turnMarkupOf(model, settings);
+    const root = host.querySelector(".ky-turn");
+    const stage = root.querySelector(".ky-turn-view");
+    const live = root.querySelector(".ky-turn-live");
+    const media = win?.matchMedia?.("(prefers-reduced-motion: reduce)");
+    /** Where the view is going, and where it is on the screen now (the two differ while it glides). */
+    let view = model.view;
+    let shown = view;
+    let opening = model.view;
+    let flight;
+    let spoken;
+    const calm = () => settings.motion === "none" || (settings.motion !== "smooth" && media?.matches === true);
+    // The elements, floor first, and what was written to each, so that only a change is written.
+    let elements = [];
+    let written = [];
+    let stacked = [];
+    let faded = [];
+    const gather = () => {
+        elements = [...stage.querySelectorAll(".ky-turn-floor, .ky-up")];
+        written = elements.map((one) => one.style.transform);
+        stacked = elements.map((one) => one.style.zIndex);
+        faded = elements.map((one) => one.style.opacity);
+    };
+    gather();
+    const buttons = () => root.querySelectorAll("button[data-preset]");
+    /** Put a view on the screen. */
+    const paint = (now) => {
+        const width = stage.clientWidth || 960;
+        const height = stage.clientHeight || 600;
+        const layout = layoutOf(model, now, width, height, settings.lens);
+        elements.forEach((one, i) => {
+            if (written[i] !== layout.transforms[i])
+                one.style.transform = written[i] = layout.transforms[i];
+            const z = String(layout.stack[i]);
+            if (stacked[i] !== z)
+                one.style.zIndex = stacked[i] = z;
+            const o = layout.fade[i] < 1 ? String(layout.fade[i]) : "";
+            if (faded[i] !== o)
+                one.style.opacity = faded[i] = o;
+        });
+    };
+    const label = () => {
+        const here = presetOf(view, sport());
+        root.dataset.preset = here ?? "custom";
+        for (const button of buttons())
+            button.setAttribute("aria-pressed", String(button.dataset.preset === here));
+    };
+    paint(shown);
+    label();
+    const stop = () => {
+        if (flight !== undefined)
+            win?.cancelAnimationFrame(flight.frame);
+        flight = undefined;
+    };
+    /** Go to a view: by a glide of `ms` milliseconds, or at once. */
+    const show = (to, ms) => {
+        stop();
+        view = to;
+        label();
+        if (ms <= 0 || calm() || win === null) {
+            shown = to;
+            paint(shown);
+            return;
+        }
+        const from = shown;
+        const run = (stamp) => {
+            if (flight === undefined)
+                return;
+            const t = Math.min(1, (stamp - flight.start) / flight.ms);
+            const eased = 1 - Math.pow(1 - t, 3);
+            shown = t >= 1 ? flight.to : between(flight.from, flight.to, eased);
+            paint(shown);
+            if (t < 1)
+                flight.frame = win.requestAnimationFrame(run);
+            else
+                flight = undefined;
+        };
+        flight = { from, to, start: win.performance.now(), ms, frame: 0 };
+        flight.frame = win.requestAnimationFrame(run);
+    };
+    const say = (text, wait = 0) => {
+        clearTimeout(spoken);
+        const write = () => {
+            // A repeated sentence is cleared first, so that a screen reader says it again.
+            if (live.textContent === text)
+                live.textContent = "";
+            live.textContent = text;
+        };
+        if (wait === 0)
+            write();
+        else
+            spoken = setTimeout(write, wait);
+    };
+    const angles = () => turnWords(model).announceAngle.replace("{yaw}", String(Math.round(((view.yaw % 360) + 360) % 360))).replace("{pitch}", String(Math.round(90 - view.pitch)));
+    const changed = () => settings.onChange?.(view, presetOf(view, sport()));
+    /** Move to a view the controls asked for: glide, say where it is, tell the page. */
+    const go = (next, ms, speak = "angle") => {
+        // A turn takes the short way round, even from 170 degrees to -170.
+        show(clampView({ ...next, yaw: nearest(view.yaw, next.yaw) }), ms);
+        if (speak === "preset") {
+            const here = presetOf(view, sport());
+            if (here !== undefined)
+                say(turnWords(model).announce.replace("{name}", turnWords(model)[here]));
+        }
+        else if (speak === "angle")
+            say(angles(), 450);
+        changed();
+    };
+    const toPreset = (name) => go(presetView(name, sport()) ?? opening, 560, "preset");
+    const toOpening = () => {
+        go(opening, 560, "none");
+        say(turnWords(model).reset);
+    };
+    // ---- Buttons. ----
+    const onClick = (event) => {
+        const target = event.target?.closest("button");
+        if (target === null || target === undefined || !root.contains(target))
+            return;
+        const name = target.dataset.preset;
+        if (name !== undefined)
+            return toPreset(name);
+        const big = event.shiftKey === true;
+        switch (target.dataset.act) {
+            // The buttons take the surface toward their side as a drag and the arrow keys do.
+            case "turn-left": return go(nudge(view, "left", big ? STEP.yawBig : STEP.yaw * 2), 180);
+            case "turn-right": return go(nudge(view, "right", big ? STEP.yawBig : STEP.yaw * 2), 180);
+            case "raise": return go(nudge(view, "up", big ? STEP.pitchBig : STEP.pitch * 2), 180);
+            case "lower": return go(nudge(view, "down", big ? STEP.pitchBig : STEP.pitch * 2), 180);
+            case "zoom-in": return go(step(view, { zoom: STEP.zoom }), 180, "none");
+            case "zoom-out": return go(step(view, { zoom: 1 / STEP.zoom }), 180, "none");
+            case "reset": return toOpening();
+            default:
+        }
+    };
+    root.addEventListener("click", onClick);
+    // ---- Keys. ----
+    const onKey = (event) => {
+        if (event.ctrlKey || event.metaKey || event.altKey || KEYS[event.key] !== true)
+            return;
+        const big = event.shiftKey;
+        const yaw = big ? STEP.yawBig : STEP.yaw;
+        const pitch = big ? STEP.pitchBig : STEP.pitch;
+        event.preventDefault();
+        switch (event.key) {
+            // A key takes the surface toward its side as a drag toward that side does: the side nearest the eye goes to the right on ArrowRight, and ArrowUp tips it as a drag up does.
+            case "ArrowLeft": return go(nudge(view, "left", yaw), 120);
+            case "ArrowRight": return go(nudge(view, "right", yaw), 120);
+            case "ArrowUp": return go(nudge(view, "up", pitch), 120);
+            case "ArrowDown": return go(nudge(view, "down", pitch), 120);
+            case "+":
+            case "=": return go(step(view, { zoom: STEP.zoom }), 120, "none");
+            case "-":
+            case "_": return go(step(view, { zoom: 1 / STEP.zoom }), 120, "none");
+            case "0":
+            case "Home": return toOpening();
+            default: toPreset(TURN_PRESET_NAMES[Number(event.key) - 1]);
+        }
+    };
+    stage.addEventListener("keydown", onKey);
+    // ---- The pointer: one finger or the mouse turns and tips; two fingers pinch. ----
+    const down = new Map();
+    let pinch;
+    let moved = false;
+    const tilts = (type) => type !== "touch" || settings.touch === "turn";
+    /** The pointer takes the view over from a glide: from where it is on the screen. */
+    const grab = () => {
+        stop();
+        view = shown;
+    };
+    const onDown = (event) => {
+        if (event.pointerType === "mouse" && event.button !== 0)
+            return;
+        down.set(event.pointerId, { x: event.clientX, y: event.clientY });
+        try {
+            stage.setPointerCapture(event.pointerId);
+        }
+        catch {
+            /* A pointer that is already gone. */
+        }
+        moved = false;
+        grab();
+        if (down.size === 1)
+            root.setAttribute("data-dragging", "");
+        if (down.size === 2) {
+            const [a, b] = [...down.values()];
+            pinch = { distance: Math.hypot(a.x - b.x, a.y - b.y) || 1, zoom: view.zoom };
+        }
+    };
+    const onMove = (event) => {
+        const before = down.get(event.pointerId);
+        if (before === undefined)
+            return;
+        const here = { x: event.clientX, y: event.clientY };
+        down.set(event.pointerId, here);
+        if (down.size >= 2 && pinch !== undefined) {
+            const [a, b] = [...down.values()];
+            view = clampView({ ...view, zoom: pinch.zoom * ((Math.hypot(a.x - b.x, a.y - b.y) || 1) / pinch.distance) });
+        }
+        else {
+            view = drag(view, here.x - before.x, here.y - before.y, tilts(event.pointerType));
+            if (Math.abs(here.x - before.x) + Math.abs(here.y - before.y) > 0)
+                moved = true;
+        }
+        shown = view;
+        paint(shown);
+    };
+    const onUp = (event) => {
+        if (!down.delete(event.pointerId))
+            return;
+        if (down.size < 2)
+            pinch = undefined;
+        if (down.size === 0) {
+            root.removeAttribute("data-dragging");
+            label();
+            if (moved) {
+                say(angles(), 450);
+                changed();
+            }
+        }
+    };
+    stage.addEventListener("pointerdown", onDown);
+    stage.addEventListener("pointermove", onMove);
+    stage.addEventListener("pointerup", onUp);
+    stage.addEventListener("pointercancel", onUp);
+    stage.addEventListener("dblclick", toOpening);
+    // ---- The wheel: Ctrl and the wheel (a pinch on a trackpad) zoom; with the view focused the wheel tips and turns it; otherwise the page scrolls as ever. ----
+    const onWheel = (event) => {
+        if (event.ctrlKey) {
+            event.preventDefault();
+            grab();
+            view = clampView({ ...view, zoom: view.zoom * Math.exp(-event.deltaY * 0.01) });
+        }
+        else if (doc.activeElement === stage) {
+            event.preventDefault();
+            grab();
+            view = event.shiftKey || Math.abs(event.deltaX) > Math.abs(event.deltaY) ? clampView({ ...view, yaw: view.yaw + (event.deltaX || event.deltaY) * 0.25 }) : clampView({ ...view, pitch: view.pitch + event.deltaY * 0.15 });
+        }
+        else
+            return;
+        shown = view;
+        paint(shown);
+        label();
+    };
+    stage.addEventListener("wheel", onWheel, { passive: false });
+    // ---- The size of the box. ----
+    let observer;
+    if (typeof ResizeObserver === "function") {
+        observer = new ResizeObserver(() => alive && paint(shown));
+        observer.observe(stage);
+    }
+    return {
+        mode: "3d",
+        view: () => ({ ...view }),
+        set(next, glide = true) {
+            go({ ...view, ...next }, glide ? 560 : 0, "angle");
+        },
+        preset: toPreset,
+        reset: toOpening,
+        update(next) {
+            if (!alive)
+                return;
+            model = buildTurn(next, { ...settings, preset: undefined, view });
+            view = clampView(view);
+            opening = openingView(settings, sport());
+            const layout = layoutOf(model, shown, stage.clientWidth || 960, stage.clientHeight || 600, settings.lens);
+            root.querySelector(".ky-turn-world").innerHTML = worldMarkup(model, layout);
+            gather();
+            stage.setAttribute("aria-label", model.title);
+            root.querySelector(".ky-turn-help").textContent = `${turnWords(model).keys}${model.standing === "" ? "" : ` ${model.standing}`}`;
+            const theme = model.options.theme;
+            if (theme === "light" || theme === "dark")
+                root.dataset.theme = theme;
+            else
+                root.removeAttribute("data-theme");
+            const controls = root.querySelector(".ky-turn-controls");
+            if (controls !== null)
+                controls.outerHTML = controlsMarkup(model, view);
+            paint(shown);
+            label();
+        },
+        svg: () => (alive ? root.querySelector(".ky-turn-floor svg.kyogijo") : null),
+        destroy() {
+            if (!alive)
+                return;
+            alive = false;
+            stop();
+            clearTimeout(spoken);
+            observer?.disconnect();
+            host.replaceChildren();
+        },
+    };
+}

package/dist/turn.kit.d.ts

@@ -0,0 +1,86 @@
+/** A point or a direction: x, y, z in feet. */
+export type V3 = readonly [number, number, number];
+/** What a plane is a part of: it is the class of its element (`ky-up-<kind>`) and what a test finds it by. */
+export type PartKind = "post" | "net" | "tape" | "antenna" | "board" | "glass" | "rim" | "stanchion" | "frame" | "goal" | "flag" | "stump" | "leg" | "table" | "pylon" | "wall" | "screen" | "pole" | "ground" | "target";
+/** One flat rectangle. Its own x runs along `u` (its whole length) and its own y along `v`; `o` is the corner both start from. `svg` is what is drawn on it, in feet along `u` and `v`. */
+export interface Plane {
+    /** A name that says what it is and where: `net`, `post-left`, `goal-right-back`. */
+    id: string;
+    kind: PartKind;
+    o: V3;
+    u: V3;
+    v: V3;
+    svg: string;
+    /**
+     * A plane that turns to face the eye, about the vertical through its middle: a scoreboard is read from wherever the view is. `u` and `v` give its size and its
+     * place as it lies at a yaw of 0; `v` must be vertical.
+     */
+    billboard?: boolean;
+    /**
+     * A wall round the surface that gives way when it is between the eye and what it surrounds: the horizontal direction (x, y, a unit vector) that points from the surface out through the
+     * wall. The nearer the eye is to that side, and the lower it is, the more the wall is cut away (see `fadeOf`), so that the court is never hidden behind its own glass.
+     */
+    shy?: readonly [number, number];
+}
+/** What stands on the surface as a thing a reader would name: a net, a basket, a goal, a pair of posts. */
+export type UprightKind = "scoreboard" | "net" | "antennae" | "goalposts" | "netposts" | "hoop" | "goal" | "boards" | "stumps" | "pylons" | "flags" | "fence" | "backstop" | "foul-poles" | "table-legs" | "walls" | "starting-blocks" | "backstroke-flags" | "false-start-rope" | "springboards" | "platforms" | "judges-stand" | "hurdles" | "steeplechase" | "high-jump" | "pole-vault" | "cage" | "padding" | "rink-boards" | "mound" | "azuchi" | "targets";
+/** A thing that stands on the surface: where, how high, and the planes it is made of. */
+export interface Upright {
+    id: string;
+    kind: UprightKind;
+    /** Where it stands on the surface, in feet. */
+    at: readonly [number, number];
+    /** The height of its top above the surface, in feet. */
+    height: number;
+    /** A second height worth saying (a net's height at the centre, a post's crossbar), in feet. */
+    low?: number;
+    planes: Plane[];
+}
+/** The four numbers a plane's SVG needs: its length along `u` and along `v`, in feet. */
+export declare const size: (p: Pick<Plane, "u" | "v">) => [number, number];
+export declare const add: (a: V3, b: V3) => V3;
+export declare const sub: (a: V3, b: V3) => V3;
+export declare const times: (a: V3, k: number) => V3;
+export declare const length: (a: V3) => number;
+export declare const unit: (a: V3) => V3;
+export declare const cross: (a: V3, b: V3) => V3;
+/** A number for markup: millimetres of a foot, no more. */
+export declare const n: (value: number) => string;
+/** A billboard turned to face an eye whose view is turned `yaw` degrees: its width runs along the screen's x, which in the scene is (cos yaw, -sin yaw, 0). */
+export declare function facing(p: Plane, yaw: number): Plane;
+/** A plane. */
+export declare const plane: (id: string, kind: PartKind, o: V3, u: V3, v: V3, svg: string) => Plane;
+/**
+ * A rectangle standing upright over a line on the surface, from (x0, y0) to (x1, y1), between the heights z0 and z1. Its own y runs down from z1, so
+ * that what is drawn on it hangs from the top as a net does.
+ */
+export declare function wall(id: string, kind: PartKind, x0: number, y0: number, x1: number, y1: number, z0: number, z1: number, svg: string): Plane;
+/** A rectangle lying flat at the height `z`, from (x0, y0) to (x1, y1). */
+export declare function flat(id: string, kind: PartKind, x0: number, y0: number, x1: number, y1: number, z: number, svg: string): Plane;
+/**
+ * A strip of width `w` along the line from `a` to `b`: a post, a crossbar, an arm. A single strip vanishes when the eye is level with it, so it is two,
+ * crossed, one the width of the other's thickness. `paint` draws on each (its length along the line and its width), a plain strip in `cls` if it is missing.
+ */
+export declare function bar(id: string, kind: PartKind, a: V3, b: V3, w: number, cls: string, paint?: (long: number, wide: number) => string): Plane[];
+/** An upright strip from the surface up to the height `top`. */
+export declare const pole: (id: string, kind: PartKind, x: number, y: number, z0: number, z1: number, w: number, cls: string, paint?: (long: number, wide: number) => string) => Plane[];
+/** The lines of a net's mesh over a rectangle w by h feet, one every `cell` feet each way: a path. */
+export declare function mesh(w: number, h: number, cell: number): string;
+/** The mesh of a net as a path element: threads a tenth of a cell thick. */
+export declare const threads: (d: string, cell: number) => string;
+/** A closed outline of points, as a path. */
+export declare const polygon: (points: readonly (readonly [number, number])[]) => string;
+/** A point `t` of the way from `a` to `b`. */
+export declare const lerp: (a: number, b: number, t: number) => number;
+/**
+ * The least thickness, in feet, of anything drawn thin on a surface this big: a post of 3 inches on a 500-foot ground would be a hair, so every strip and every
+ * line is at least a thousandth of the surface's diagonal.
+ */
+export declare const thinnest: (w: number, h: number) => number;
+/** A wall plane marked to give way: its outward direction is the way the wall faces away from `centre` (x, y in feet), which is where the surface's middle is. */
+export declare function shy(p: Plane, centre: readonly [number, number]): Plane;
+/**
+ * How much of a wall is left (1 whole, down to 0.08) at a view: none is cut away unless the wall is on the eye's side of the surface, and then more the lower the eye is, because a wall seen
+ * from straight above hides nothing. `yaw` and `pitch` are the view's, in degrees.
+ */
+export declare function fadeOf(p: Pick<Plane, "shy">, yaw: number, pitch: number): number;

package/dist/turn.kit.js

@@ -0,0 +1,110 @@
+// What the 3D view is built from: planes. A plane is a flat rectangle standing anywhere in space (a net, a backboard, a pane of glass, the two crossed
+// strips that make a post), with a little SVG drawn on it. The floor is the drawing itself, flat at the height of the surface; everything that stands on it is a
+// few planes, each placed by three vectors, so that the whole scene is a handful of elements and no model. Nothing here touches a page.
+//
+// The frame is the drawing's own: x along the surface and y across it, both in feet, as the SVG has them (y grows downwards on the page), and z the height
+// above the surface, in feet, growing towards the eye of someone looking straight down.
+/** The four numbers a plane's SVG needs: its length along `u` and along `v`, in feet. */
+export const size = (p) => [Math.hypot(...p.u), Math.hypot(...p.v)];
+export const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+export const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+export const times = (a, k) => [a[0] * k, a[1] * k, a[2] * k];
+export const length = (a) => Math.hypot(a[0], a[1], a[2]);
+export const unit = (a) => {
+    const n = length(a);
+    return n === 0 ? [0, 0, 0] : [a[0] / n, a[1] / n, a[2] / n];
+};
+export const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+/** A number for markup: millimetres of a foot, no more. */
+export const n = (value) => String(Math.round(value * 1000) / 1000);
+/** A billboard turned to face an eye whose view is turned `yaw` degrees: its width runs along the screen's x, which in the scene is (cos yaw, -sin yaw, 0). */
+export function facing(p, yaw) {
+    if (p.billboard !== true)
+        return p;
+    const [w, h] = size(p);
+    const a = (yaw * Math.PI) / 180;
+    const u = [w * Math.cos(a), -w * Math.sin(a), 0];
+    const middle = [p.o[0] + (p.u[0] + p.v[0]) / 2, p.o[1] + (p.u[1] + p.v[1]) / 2, p.o[2] + (p.u[2] + p.v[2]) / 2];
+    const v = [0, 0, p.v[2] < 0 ? -h : h];
+    return { ...p, o: [middle[0] - (u[0] + v[0]) / 2, middle[1] - (u[1] + v[1]) / 2, middle[2] - (u[2] + v[2]) / 2], u, v };
+}
+/** A plane. */
+export const plane = (id, kind, o, u, v, svg) => ({ id, kind, o, u, v, svg });
+/**
+ * A rectangle standing upright over a line on the surface, from (x0, y0) to (x1, y1), between the heights z0 and z1. Its own y runs down from z1, so
+ * that what is drawn on it hangs from the top as a net does.
+ */
+export function wall(id, kind, x0, y0, x1, y1, z0, z1, svg) {
+    return plane(id, kind, [x0, y0, z1], [x1 - x0, y1 - y0, 0], [0, 0, z0 - z1], svg);
+}
+/** A rectangle lying flat at the height `z`, from (x0, y0) to (x1, y1). */
+export function flat(id, kind, x0, y0, x1, y1, z, svg) {
+    return plane(id, kind, [x0, y0, z], [x1 - x0, 0, 0], [0, y1 - y0, 0], svg);
+}
+/**
+ * A strip of width `w` along the line from `a` to `b`: a post, a crossbar, an arm. A single strip vanishes when the eye is level with it, so it is two,
+ * crossed, one the width of the other's thickness. `paint` draws on each (its length along the line and its width), a plain strip in `cls` if it is missing.
+ */
+export function bar(id, kind, a, b, w, cls, paint) {
+    const d = sub(b, a);
+    const long = length(d);
+    if (long === 0)
+        return [];
+    const along = unit(d);
+    // A line that is nearly upright is crossed with the x axis; any other with the upright, so that no strip lies edge-on to a cross strip.
+    const first = Math.abs(along[2]) > 0.98 ? [1, 0, 0] : unit(cross(along, [0, 0, 1]));
+    const second = unit(cross(along, first));
+    const drawn = paint === undefined ? `<rect width="${n(long)}" height="${n(w)}" class="${cls}"/>` : paint(long, w);
+    return [first, second].map((side, i) => plane(`${id}${i === 0 ? "" : "-x"}`, kind, sub(a, times(side, w / 2)), d, times(side, w), drawn));
+}
+/** An upright strip from the surface up to the height `top`. */
+export const pole = (id, kind, x, y, z0, z1, w, cls, paint) => bar(id, kind, [x, y, z0], [x, y, z1], w, cls, paint);
+/** The lines of a net's mesh over a rectangle w by h feet, one every `cell` feet each way: a path. */
+export function mesh(w, h, cell) {
+    const across = Math.max(1, Math.round(w / cell));
+    const down = Math.max(1, Math.round(h / cell));
+    let d = "";
+    for (let i = 1; i < across; i += 1)
+        d += `M${n((w * i) / across)} 0V${n(h)}`;
+    for (let j = 1; j < down; j += 1)
+        d += `M0 ${n((h * j) / down)}H${n(w)}`;
+    return d;
+}
+/** The mesh of a net as a path element: threads a tenth of a cell thick. */
+export const threads = (d, cell) => `<path d="${d}" class="u-mesh" fill="none" stroke-width="${n(Math.max(cell * 0.09, 0.02))}"/>`;
+/** A closed outline of points, as a path. */
+export const polygon = (points) => `M${points.map(([x, y]) => `${n(x)} ${n(y)}`).join("L")}Z`;
+/** A point `t` of the way from `a` to `b`. */
+export const lerp = (a, b, t) => a + (b - a) * t;
+/**
+ * The least thickness, in feet, of anything drawn thin on a surface this big: a post of 3 inches on a 500-foot ground would be a hair, so every strip and every
+ * line is at least a thousandth of the surface's diagonal.
+ */
+export const thinnest = (w, h) => Math.hypot(w, h) * 0.0012;
+/** A wall plane marked to give way: its outward direction is the way the wall faces away from `centre` (x, y in feet), which is where the surface's middle is. */
+export function shy(p, centre) {
+    // The plane stands over a line on the surface: the horizontal part of `u` (or of `v` for one lying down) is that line, and its normal in the surface is the way out or the way in.
+    const line = Math.hypot(p.u[0], p.u[1]) >= Math.hypot(p.v[0], p.v[1]) ? [p.u[0], p.u[1]] : [p.v[0], p.v[1]];
+    const length = Math.hypot(line[0], line[1]);
+    if (length === 0)
+        return p;
+    let normal = [-line[1] / length, line[0] / length];
+    const middle = [p.o[0] + (p.u[0] + p.v[0]) / 2, p.o[1] + (p.u[1] + p.v[1]) / 2];
+    if (normal[0] * (middle[0] - centre[0]) + normal[1] * (middle[1] - centre[1]) < 0)
+        normal = [-normal[0], -normal[1]];
+    return { ...p, shy: normal };
+}
+/**
+ * How much of a wall is left (1 whole, down to 0.08) at a view: none is cut away unless the wall is on the eye's side of the surface, and then more the lower the eye is, because a wall seen
+ * from straight above hides nothing. `yaw` and `pitch` are the view's, in degrees.
+ */
+export function fadeOf(p, yaw, pitch) {
+    if (p.shy === undefined)
+        return 1;
+    const a = (yaw * Math.PI) / 180;
+    // The horizontal direction from the surface to the eye (the same sum as the depth of a point).
+    const toward = p.shy[0] * Math.sin(a) + p.shy[1] * Math.cos(a);
+    const hides = toward * Math.sin((pitch * Math.PI) / 180);
+    const t = Math.min(1, Math.max(0, (hides - 0.1) / 0.25));
+    return Math.round((1 - 0.92 * t) * 1000) / 1000;
+}

package/dist/turn.markup.d.ts

@@ -0,0 +1,48 @@
+import { type Placement, type TurnView } from "./turn.camera.ts";
+import { type Plane } from "./turn.kit.ts";
+import { type TurnModel, type TurnSettings } from "./turn.model.ts";
+import type { ScoreOptions, SurfaceOptions } from "./types.ts";
+/**
+ * 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).
+ */
+export declare function planeMatrix(p: Plane, scale: number, centre?: readonly [number, number]): number[];
+/** Where everything is for a view in a container: the placement, the matrix of each element and its place in the stack. */
+export interface Layout {
+    at: Placement;
+    /** The floor, then the planes in the model's order. */
+    transforms: string[];
+    /** The stack of each: 0 for the ground of a hall, 1 for the floor, then the planes far to near from 2. */
+    stack: number[];
+    /** How much of each is left: 1 for all but the walls that are between the eye and the surface, which are cut away as the view is low and on their side (`fadeOf`). */
+    fade: number[];
+}
+/** Work a view out in a container `width` by `height` pixels. */
+export declare function layoutOf(model: TurnModel, view: TurnView, width: number, height: number, lens?: number): 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;
+/** 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;
+/** The floor and the planes of a model, laid out. */
+export declare function worldMarkup(model: TurnModel, layout: Layout): string;
+/** The buttons under the view. */
+export declare function controlsMarkup(model: TurnModel, view: TurnView): string;
+/** The size, in pixels, the first view is worked out for. */
+export declare const sizeOf: (settings: TurnSettings) => {
+    width: number;
+    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;
+/**
+ * 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.
+ * @example
+ * ```ts
+ * import { turnMarkup } from "@johnmorrisdotca/kyogijo-stadiums/turn";
+ * const html = turnMarkup({ sport: "volleyball" }, { preset: "end" });
+ * console.log(html.includes("ky-turn"), html.includes('data-part="net"'));
+ * // true true
+ * ```
+ */
+export declare function turnMarkup(options: SurfaceOptions | ScoreOptions, settings?: TurnSettings): string;