@johnmorrisdotca/kazoku-ui 0.15.2 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+- **The vertical demo sits beside the view.** The axis chips made that column tall enough that Centre's row scrolled the page and Auto-turn left the pointer. On a desk the column stands beside the scene, so Centre adds its row and Auto-turn stays where it was.
+
+## [0.17.0] - 2026-11-05
+
+The view turns on all three axes (KAZOKU-UI-55), and a shared replay bar (KAZOKU-UI-57).
+
+- **Roll, beside Angle and Tilt.** One slider, and chips for Angle, Tilt, Roll and All. The slider sets the axis the chips name (All keeps the angle). `roll` and `roll-max` (180) sit next to `tilt` and `tilt-max`.
+- **Auto-turn chooses an axis:** Angle, Tilt, Roll or All. All is a tumble: three rates that drift, so it does not repeat. Each axis has its own direction. Tilt swings inside `tilt-max` and, at 90 or more, rolls over on a quaternion (`orientation` on the event) so the up axis does not flip. Off under reduced motion, as before. The choice is the `axis` attribute and `?axis=all`.
+- **`<kazoku-replay-bar>`** (KAZOKU-UI-57). Play, pause, back to the start and repeat, with the family's speed buttons on the same row. The bar reports the choice (`kazoku-replay` with `{ action, playing, repeat, reason }`) and the page moves the thing. `playing` and `repeat` are attributes; `address` keeps them (`play=on`, `repeat=on`), and `address-keys` can rename either. The speed buttons use `steps` and `speed`, and their own address key `replay-speed` (`speed-key` renames it), so they do not share a view's `pace`. Reduced motion leaves play off. New part: `@johnmorrisdotca/kazoku-ui/replay-bar`, `/element` and `/define`.
+
+## [0.16.0] - 2026-11-04
+
+Which way Auto-turn goes is the reader's to choose.
+
+- **Left and Right buttons** (KAZOKU-UI-34 and KAZOKU-UI-22). Under More, beside the speed buttons, a pair of buttons chooses which way Auto-turn goes. The choice is kept in the new `direction` attribute (`left` or `right`) and in the address as `?direction=left`; the angle goes on from where it was, at the same speed. By the drag rule `yaw` goes up as the hand goes right, so right is the positive `speed`. With no `direction`, the sign of `speed` decides (a negative `speed` starts the turn to the left, as before), and the address keeps a way only when it is not the page's own start. `address-keys` can rename the key (`direction:dir`). New words in both languages: `direction` (Turn direction, 回る向き), `turnLeft` (Left, 左へ), `turnRight` (Right, 右へ). A package with its own Reverse button (senshu-jerseys, dougu-sports' old `?dir=cw`) can drop it for these.
+- **`autoplay-for` limits every turn** (KAZOKU-UI-22). A turn the Auto-turn button or `element.play()` starts now stops after `autoplay-for` seconds of turning, as the one `autoplay` starts always did; `play(seconds)` takes a limit of its own. Without `autoplay-for` nothing changes. A page that sets `autoplay-for` and wants its Auto-turn button unlimited keeps its own timer instead.
+- **Flaky tests fixed at the cause** (KAZOKU-UI-11, 31, 25, 36, 32; tests and a template only, no change to the package's code). `address-state` wrote the page's own choice a quarter of a second after the click and the theme and language at once, so the order of the parameters was the order of the writes, which a slow machine changes: the test compares the parts, not the order (13 of 160 runs failed before, 0 of 160 after). The renderer's "turning draws once a frame" counted the stills' draws as the turn's and a fixed 800 ms of a slow software frame as too few: it now waits for the stills to finish and for the turn to be drawing, and for the last frame after the pause. The autoplay tests' "it turns while the view is on screen" waited a fixed 700 ms: they wait for the changes to arrive. The docs site's Tab test (new family template `templates/docs-site.demo.mjs`, to replace the copy in chikyu-earth and wakusei-planets) presses Alt+Tab where WebKit on a Mac does not Tab to links.
+
 ## [0.15.2] - 2026-11-04
 
 The embed panel no longer scrolls the page.

package/README.md

@@ -172,7 +172,7 @@ Each its own subpath; later ones: picture-tile pickers, Help, GitHub and npm pil
 
 - **Two levels, so the bar stays simple.** The default, `controls="basic"`, shows the angle slider, Auto-turn, zoom out and in with a **zoom readout** (`2.4×`; tap it to go back to Fit), Fit, and a small More button; while the view turns, one small **speed** button beside Auto-turn (it shows the word Speed over `1×`, and a press steps to the next speed). More (or `controls="advanced"`) adds the tilt slider, the speed buttons (0.5×, 1×, 2×), Front, and, once zoomed in, the four-arrow pan pad and the Move or Turn choice for what a drag does. The reader's choice with More is remembered in `localStorage` and beats the attribute.
 - The zoom readout is the view's `zoom` (1× is Fit, whatever `fit-scale` is), one decimal, the one zoom number on the bar: it follows the buttons, the wheel, a pinch, a double press, Fit, the keys, the address, `set` and a changed limit. A screen reader is told "Zoom level 2.4×" once the zoom has settled for a moment, not for every step of a pinch.
-- Auto-turn with play and pause; its speed is chosen with the family's [speed buttons](docs/guides/speed-buttons.md): 0.5× (half the `speed` attribute), 1× (the `speed` attribute, 30 degrees a second) or 2× (twice it), kept in the `pace` attribute and in the address as `?pace=0.5` or `?pace=2`.
+- Auto-turn with play and pause; its speed is chosen with the family's [speed buttons](docs/guides/speed-buttons.md): 0.5× (half the `speed` attribute), 1× (the `speed` attribute, 30 degrees a second) or 2× (twice it), kept in the `pace` attribute and in the address as `?pace=0.5` or `?pace=2`. **Left and Right** (under More, beside the speed buttons) choose which way it goes, kept in the `direction` attribute and in the address as `?direction=left`; the angle goes on from where it was, at the same speed.
 - **The wheel zooms.** The wheel over the view zooms it about the pointer, like a map; a trackpad's pinch (and Ctrl or Command with the wheel) zooms too. Shift and the wheel, or a sideways swipe, turns it. Tipping is a drag, the arrow keys or the tilt slider. With the pointer anywhere else the wheel scrolls the page, and a wheel that starts while the zoom is already at its end that way (turned down at Fit) scrolls the page too, so the page is never trapped.
 - Touch: one finger turns at 1x and moves the view when zoomed in; two fingers pinch.
 - Keys on the view: arrows turn and tip it, `+` and `-` zoom, `0` or Home is Front and Fit.
@@ -362,8 +362,9 @@ An `init` event is sent once, a moment after the element connects, with the star
 | `object-size` | `w,h`: the object's size at Fit in CSS pixels, when it is smaller than the view. A pan then keeps at least a quarter of the object in view, however far it is dragged; left out, the object is the picture, which keeps covering the view. Or set `element.objectSize = { width, height }`. |
 | `grab-radius` | Exact grab, for a globe or any turnable piece: its on-screen radius in CSS pixels at Fit, or `fit` for half the smaller side of the view. A drag then turns it by the angle that keeps the touched point under the pointer (a drag of *d* pixels moves the ground at the middle by *d* pixels), and the radius grows with the zoom. Left out, a drag turns by a fixed angle across the view, as before. See [docs/drag-rule.md](docs/drag-rule.md). |
 | `autoplay` | Turn by itself from the start, unless the reader prefers reduced motion. |
-| `autoplay-for` | Seconds of turning after which the `autoplay` turn stops by itself (as Auto-turn pressed). Left out, it never stops. Time spent paused off screen or in a hidden tab is not counted, and a reader's own Auto-turn press has no limit. |
-| `speed` | Degrees a second at a pace of 1 (30). |
+| `autoplay-for` | Seconds of turning after which a turn stops by itself (as Auto-turn pressed): the one `autoplay` starts, and one the Auto-turn button or `play()` starts. Left out, a turn never stops. Time spent paused off screen or in a hidden tab is not counted. `play(seconds)` takes its own limit. |
+| `speed` | Degrees a second at a pace of 1 (30). A negative number starts the turn to the left. |
+| `direction` | Which way Auto-turn goes, `left` or `right` (by the drag rule `yaw` goes up as the hand goes right, so right is the positive `speed`). The reader's choice of the Left and Right buttons (under More) is written here and kept in the address as `direction`; the angle goes on from where it was, at the same speed. Left out, the sign of `speed` decides, and the address keeps a way only when it is not that start. |
 | `pace` | The Auto-turn speed as a multiple of `speed`: 1 by default, 0.5 and 2 on the default buttons. The reader's choice is written here, and kept in the address as `pace`. |
 | `paces` | The speeds the buttons stand for, `0.5 1 2` by default (any numbers: `paces="1 4 8"`). |
 | `controls` | `basic` (the default) or `advanced`: which controls are shown (see above; the zoom readout in both, the speed in both while the view turns). Written in the page's markup it is where the reader starts; what the reader chose with More is remembered under `kazoku-view-controls` in `localStorage` (or the key `storage` names) and wins. Setting the attribute later changes the level at once. The host carries `data-level` with the level now. |
@@ -371,7 +372,7 @@ An `init` event is sent once, a moment after the element connects, with the star
 | `storage` | The `localStorage` key the level is remembered under (`kazoku-view-controls`). |
 | `flat` | The view cannot turn: no angle, tilt, Auto-turn or Front, and a drag moves it. |
 | `tilt-max`, `zoom-min`, `zoom-max` | The limits (30, 1, 5). |
-| `address` | Keep the choices in the page's address (`?yaw=40&tilt=10&zoom=2&drag=turn&pace=2`). |
+| `address` | Keep the choices in the page's address (`?yaw=40&tilt=10&zoom=2&drag=turn&pace=2&direction=left`). |
 | `address-keys` | Other keys: `yaw:a,zoom:z`. |
 | `theme` | `light` or `dark`; otherwise the page's colour scheme. |
 | `overlay` | Sit over the bottom of a positioned parent. With `layout="compact"` the row floats 8 px in from the bottom start corner instead of spanning the bottom. |
@@ -381,7 +382,7 @@ Colours are custom properties: `--kazoku-ink`, `--kazoku-surface`, `--kazoku-lin
 
 ### The address
 
-Only what a reader chose is kept: angle, tilt, zoom, the drag choice and the auto-turn speed (`pace=0.5` or `pace=2`; 1 leaves the address; a page's own `speed` parameter is never touched, and `?pace=slow` or `fast` of 0.12 and 0.13 still read as 0.5 and 2). The pan is in pixels of one screen and the turning is of a moment, so neither is; while the view turns by itself the angle is left out. A value at its start (Fit, or the `zoom` the page opens at) leaves the address, and other parameters are kept. The address is written at most four times a second (Safari stops a page that changes its address more than 100 times in 30 seconds). Without the element: `parseAddress(search, keys?)` and `formatAddress(search, choices, keys?, leaveYaw?, startZoom?)`.
+Only what a reader chose is kept: angle, tilt, zoom, the drag choice, the auto-turn speed (`pace=0.5` or `pace=2`; 1 leaves the address) and the way it turns (`direction=left` or `direction=right`; the page's own start leaves the address). A page's own `speed` parameter is never touched, and `?pace=slow` or `fast` of 0.12 and 0.13 still read as 0.5 and 2. The pan is in pixels of one screen and the turning is of a moment, so neither is; while the view turns by itself the angle is left out. A value at its start (Fit, or the `zoom` the page opens at) leaves the address, and other parameters are kept. The address is written at most four times a second (Safari stops a page that changes its address more than 100 times in 30 seconds). Without the element: `parseAddress(search, keys?)` and `formatAddress(search, choices, keys?, leaveYaw?, startZoom?)`.
 
 ### Why the tag is only defined when it is free
 
@@ -552,7 +553,7 @@ One part, one subpath; the pure code, the element and the registration are three
 
 ## Demos
 
-[The demo](https://johnmorrisdotca.github.io/kazoku-ui/) has the view controls, the language picker and the theme switch in its header. Beside it: [speed buttons](https://johnmorrisdotca.github.io/kazoku-ui/speed.html), [layouts](https://johnmorrisdotca.github.io/kazoku-ui/layouts.html), [the builder](https://johnmorrisdotca.github.io/kazoku-ui/builder.html), [address state](https://johnmorrisdotca.github.io/kazoku-ui/address.html), [save image](https://johnmorrisdotca.github.io/kazoku-ui/save-image.html), [the shared renderer](https://johnmorrisdotca.github.io/kazoku-ui/renderer.html), [exact grab](https://johnmorrisdotca.github.io/kazoku-ui/grab.html) and [a strict Content-Security-Policy](https://johnmorrisdotca.github.io/kazoku-ui/csp.html).
+[The demo](https://johnmorrisdotca.github.io/kazoku-ui/) has the view controls, the language picker and the theme switch in its header. Beside it: [speed buttons](https://johnmorrisdotca.github.io/kazoku-ui/speed.html), [the replay bar](https://johnmorrisdotca.github.io/kazoku-ui/replay.html), [layouts](https://johnmorrisdotca.github.io/kazoku-ui/layouts.html), [the builder](https://johnmorrisdotca.github.io/kazoku-ui/builder.html), [address state](https://johnmorrisdotca.github.io/kazoku-ui/address.html), [save image](https://johnmorrisdotca.github.io/kazoku-ui/save-image.html), [the shared renderer](https://johnmorrisdotca.github.io/kazoku-ui/renderer.html), [exact grab](https://johnmorrisdotca.github.io/kazoku-ui/grab.html) and [a strict Content-Security-Policy](https://johnmorrisdotca.github.io/kazoku-ui/csp.html).
 
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/builder-dark.webp">

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 /** The subpaths of the parts, in the order they were added. */
-export declare const PARTS: readonly ["view-controls", "theme-switch", "language-picker", "address-state", "save-image", "speed-buttons", "embed-panel", "renderer", "testing"];
+export declare const PARTS: readonly ["view-controls", "theme-switch", "language-picker", "address-state", "save-image", "speed-buttons", "embed-panel", "renderer", "testing", "replay-bar"];
 export type Part = (typeof PARTS)[number];

package/dist/index.js

@@ -1,3 +1,3 @@
 // Kazoku UI 家族: the family's shared interface parts, each its own subpath so a page loads only what it uses.
 /** The subpaths of the parts, in the order they were added. */
-export const PARTS = ["view-controls", "theme-switch", "language-picker", "address-state", "save-image", "speed-buttons", "embed-panel", "renderer", "testing"];
+export const PARTS = ["view-controls", "theme-switch", "language-picker", "address-state", "save-image", "speed-buttons", "embed-panel", "renderer", "testing", "replay-bar"];

package/dist/replay-bar/define.d.ts

@@ -0,0 +1 @@
+export declare function defineReplayBar(registry?: CustomElementRegistry): boolean;

package/dist/replay-bar/define.js

@@ -0,0 +1,9 @@
+// Importing this registers <kazoku-replay-bar>, unless the tag is already taken (the first definition wins).
+import { ReplayBarElement, TAG } from "./element.js";
+export function defineReplayBar(registry = customElements) {
+    if (registry.get(TAG) !== undefined)
+        return false;
+    registry.define(TAG, ReplayBarElement);
+    return true;
+}
+defineReplayBar();

package/dist/replay-bar/element.d.ts

@@ -0,0 +1,34 @@
+import "../speed-buttons/define.ts";
+import { EVENT, TAG } from "./index.ts";
+import { type ReplayWords } from "./words.ts";
+export { EVENT, TAG };
+/** What the `kazoku-replay` event carries in `detail`. */
+export interface ReplayDetail {
+    /** What was pressed. `play` and `pause` are the one button. */
+    action: "play" | "pause" | "start" | "repeat";
+    playing: boolean;
+    repeat: boolean;
+    /** `init` (once, when it comes up), `user` (a button) or `set` (a property or attribute). */
+    reason: "init" | "user" | "set";
+}
+/**
+ * Attributes: `playing` (present, or `on`, while it plays), `repeat` (the loop), `steps` and `speed` (handed to the speed buttons),
+ * `address` (keep play, repeat and the speed in the address), `address-keys` (`play:p,repeat:r`), `speed-key` (the speed's own key, `replay-speed` by default),
+ * `lang`, `theme`.
+ */
+export declare class ReplayBarElement extends HTMLElement {
+    #private;
+    static observedAttributes: string[];
+    constructor();
+    /** Whether playback is going. Reduced motion keeps this false. */
+    get playing(): boolean;
+    set playing(next: boolean);
+    /** Whether the page should loop when it reaches the end. */
+    get repeat(): boolean;
+    set repeat(next: boolean);
+    /** Your own labels over the language's. */
+    set words(words: Partial<ReplayWords>);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+}

package/dist/replay-bar/element.js

@@ -0,0 +1,219 @@
+// <kazoku-replay-bar>: play, pause, back to the start, repeat, and the family's speed buttons, in one row. It moves nothing itself.
+// The page hears `kazoku-replay` and applies it, and hears `kazoku-speedchange` from the speed buttons. Reduced motion leaves play off.
+import { applyParams, createAddressWriter, readParam } from "../address-state/address.js";
+import { adoptStyles } from "../shared/adopt.js";
+import { watchScheme } from "../shared/scheme.js";
+import "../speed-buttons/define.js";
+import { EVENT, TAG } from "./index.js";
+import { addressKeys, DEFAULT_STEPS, flagOn, SPEED_KEY } from "./state.js";
+import { STYLES } from "./styles.js";
+import { languageOf, wordsFor } from "./words.js";
+export { EVENT, TAG };
+/**
+ * Attributes: `playing` (present, or `on`, while it plays), `repeat` (the loop), `steps` and `speed` (handed to the speed buttons),
+ * `address` (keep play, repeat and the speed in the address), `address-keys` (`play:p,repeat:r`), `speed-key` (the speed's own key, `replay-speed` by default),
+ * `lang`, `theme`.
+ */
+export class ReplayBarElement extends HTMLElement {
+    static observedAttributes = ["playing", "repeat", "steps", "speed", "lang", "label"];
+    #root;
+    #playing = false;
+    #repeat = false;
+    #ready = false;
+    #styled = false;
+    #words = {};
+    #writer = createAddressWriter({ delay: 0 });
+    #stop;
+    #motion;
+    #reflecting = false;
+    constructor() {
+        super();
+        this.#root = this.attachShadow({ mode: "open" });
+    }
+    /** Whether playback is going. Reduced motion keeps this false. */
+    get playing() {
+        return this.#playing;
+    }
+    set playing(next) {
+        this.#play(next, "set");
+    }
+    /** Whether the page should loop when it reaches the end. */
+    get repeat() {
+        return this.#repeat;
+    }
+    set repeat(next) {
+        this.#loop(next, "set");
+    }
+    /** Your own labels over the language's. */
+    set words(words) {
+        this.#words = words;
+        this.#paint();
+    }
+    connectedCallback() {
+        if (!this.#styled) {
+            const outer = this.getRootNode();
+            adoptStyles(this.#root, STYLES, this.nonce || (outer instanceof ShadowRoot ? outer.host.nonce : "") || "");
+            this.#styled = true;
+        }
+        this.#stop = watchScheme(this);
+        this.#motion = globalThis.matchMedia?.("(prefers-reduced-motion: reduce)");
+        this.#motion?.addEventListener?.("change", this.#onMotion);
+        const keys = addressKeys(this.getAttribute("address-keys"));
+        const askedPlay = this.hasAttribute("address") ? flagOn(readParam(keys.play)) : this.hasAttribute("playing") && this.getAttribute("playing") !== "off";
+        const askedRepeat = this.hasAttribute("address") ? flagOn(readParam(keys.repeat)) : this.hasAttribute("repeat") && this.getAttribute("repeat") !== "off";
+        this.#playing = askedPlay && !this.#reduced();
+        this.#repeat = askedRepeat;
+        this.#reflect("playing", this.#playing);
+        this.#reflect("repeat", this.#repeat);
+        this.#render();
+        this.#ready = true;
+        queueMicrotask(() => {
+            if (this.isConnected)
+                this.#dispatch(this.#playing ? "play" : "pause", "init");
+        });
+    }
+    disconnectedCallback() {
+        this.#stop?.();
+        this.#stop = undefined;
+        this.#motion?.removeEventListener?.("change", this.#onMotion);
+        this.#writer.cancel();
+        this.#ready = false;
+    }
+    attributeChangedCallback(name, _old, value) {
+        if (!this.#ready || this.#reflecting)
+            return;
+        if (name === "playing")
+            this.#play(value !== "off" && value !== null, "set");
+        else if (name === "repeat")
+            this.#loop(value !== "off" && value !== null, "set");
+        else if (name === "steps" || name === "speed")
+            this.#speeds();
+        else
+            this.#paint();
+    }
+    #reduced() {
+        return this.#motion?.matches === true;
+    }
+    #onMotion = () => {
+        if (this.#reduced() && this.#playing)
+            this.#play(false, "set");
+        else
+            this.#paint();
+    };
+    #play(next, reason) {
+        const on = next && !this.#reduced();
+        if (on === this.#playing) {
+            this.#paint();
+            return;
+        }
+        this.#playing = on;
+        this.#reflect("playing", on);
+        this.#paint();
+        this.#write();
+        this.#dispatch(on ? "play" : "pause", reason);
+    }
+    #loop(next, reason) {
+        if (next === this.#repeat)
+            return;
+        this.#repeat = next;
+        this.#reflect("repeat", next);
+        this.#paint();
+        this.#write();
+        this.#dispatch("repeat", reason);
+    }
+    #reflect(name, on) {
+        const have = this.hasAttribute(name) && this.getAttribute(name) !== "off";
+        if (have === on)
+            return;
+        this.#reflecting = true;
+        if (on)
+            this.setAttribute(name, "");
+        else
+            this.removeAttribute(name);
+        this.#reflecting = false;
+    }
+    #write() {
+        if (!this.hasAttribute("address"))
+            return;
+        const keys = addressKeys(this.getAttribute("address-keys"));
+        this.#writer.write((search) => applyParams(search, { [keys.play]: this.#playing ? "on" : null, [keys.repeat]: this.#repeat ? "on" : null }));
+    }
+    #speeds() {
+        const speeds = this.#root.querySelector("kazoku-speed-buttons");
+        if (!speeds)
+            return;
+        speeds.setAttribute("steps", this.getAttribute("steps") || DEFAULT_STEPS);
+        const speed = this.getAttribute("speed");
+        if (speed)
+            speeds.setAttribute("value", speed);
+    }
+    #render() {
+        const doc = this.ownerDocument;
+        const row = doc.createElement("div");
+        row.className = "row";
+        row.setAttribute("role", "group");
+        for (const act of ["play", "start", "repeat"]) {
+            const button = doc.createElement("button");
+            button.type = "button";
+            button.dataset.act = act;
+            button.setAttribute("part", act);
+            button.addEventListener("click", () => this.#press(act));
+            row.append(button);
+        }
+        const speeds = doc.createElement("kazoku-speed-buttons");
+        speeds.setAttribute("no-label", "");
+        speeds.setAttribute("steps", this.getAttribute("steps") || DEFAULT_STEPS);
+        if (this.hasAttribute("address")) {
+            speeds.setAttribute("address", "");
+            speeds.setAttribute("address-key", this.getAttribute("speed-key") || SPEED_KEY);
+        }
+        const speed = this.getAttribute("speed");
+        if (speed)
+            speeds.setAttribute("value", speed);
+        row.append(speeds);
+        this.#root.replaceChildren(row);
+        this.#paint();
+    }
+    #press(act) {
+        if (act === "play")
+            this.#play(!this.#playing, "user");
+        else if (act === "repeat")
+            this.#loop(!this.#repeat, "user");
+        else {
+            if (this.#playing) {
+                this.#playing = false;
+                this.#reflect("playing", false);
+                this.#write();
+            }
+            this.#paint();
+            this.#dispatch("start", "user");
+        }
+    }
+    #paint() {
+        const language = languageOf(this.getAttribute("lang") ?? this.closest("[lang]")?.getAttribute("lang") ?? this.ownerDocument.documentElement.lang);
+        const words = wordsFor(language, this.#words);
+        const row = this.#root.querySelector(".row");
+        if (!row)
+            return;
+        row.setAttribute("aria-label", this.getAttribute("label") || words.group);
+        const play = row.querySelector('[data-act="play"]');
+        const start = row.querySelector('[data-act="start"]');
+        const repeat = row.querySelector('[data-act="repeat"]');
+        if (play) {
+            play.textContent = this.#playing ? words.pause : words.play;
+            play.setAttribute("aria-pressed", String(this.#playing));
+            play.disabled = this.#reduced();
+        }
+        if (start)
+            start.textContent = words.start;
+        if (repeat) {
+            repeat.textContent = words.repeat;
+            repeat.setAttribute("aria-pressed", String(this.#repeat));
+        }
+        const speeds = row.querySelector("kazoku-speed-buttons");
+        speeds?.setAttribute("lang", language);
+    }
+    #dispatch(action, reason) {
+        this.dispatchEvent(new CustomEvent(EVENT, { detail: { action, playing: this.#playing, repeat: this.#repeat, reason }, bubbles: true, composed: true }));
+    }
+}

package/dist/replay-bar/index.d.ts

@@ -0,0 +1,4 @@
+export { addressKeys, DEFAULT_STEPS, flagOn, PLAY_KEY, REPEAT_KEY, SPEED_KEY } from "./state.ts";
+export { languageOf, WORDS, wordsFor, type Language, type ReplayWords } from "./words.ts";
+export declare const EVENT = "kazoku-replay";
+export declare const TAG = "kazoku-replay-bar";

package/dist/replay-bar/index.js

@@ -0,0 +1,5 @@
+// The replay bar without the element: the address keys and the on/off reading. Nothing here touches the DOM, so it imports on a server.
+export { addressKeys, DEFAULT_STEPS, flagOn, PLAY_KEY, REPEAT_KEY, SPEED_KEY } from "./state.js";
+export { languageOf, WORDS, wordsFor } from "./words.js";
+export const EVENT = "kazoku-replay";
+export const TAG = "kazoku-replay-bar";

package/dist/replay-bar/state.d.ts

@@ -0,0 +1,19 @@
+/** The address key for playing, unless `address-keys` names another. */
+export declare const PLAY_KEY = "play";
+/** The address key for the repeat loop, unless `address-keys` names another. */
+export declare const REPEAT_KEY = "repeat";
+/** The address key the bar's speed buttons use, so they do not share a view's `pace`. */
+export declare const SPEED_KEY = "replay-speed";
+/** A replay's usual speeds. A page sets its own with `steps`. */
+export declare const DEFAULT_STEPS = "0.25 0.5 1 2 4";
+/** Whether an address or attribute value means on. Anything else, including nothing, is off. */
+export declare function flagOn(value: string | null | undefined): boolean;
+/**
+ * The address keys for play and repeat. `play:p,repeat:r` renames either; an unknown name is ignored.
+ * @param spec The `address-keys` attribute.
+ * @returns The key for each choice.
+ */
+export declare function addressKeys(spec: string | null | undefined): {
+    play: string;
+    repeat: string;
+};

package/dist/replay-bar/state.js

@@ -0,0 +1,27 @@
+// The replay bar's own choices, with no DOM, so a server can read an address the same way the element does.
+/** The address key for playing, unless `address-keys` names another. */
+export const PLAY_KEY = "play";
+/** The address key for the repeat loop, unless `address-keys` names another. */
+export const REPEAT_KEY = "repeat";
+/** The address key the bar's speed buttons use, so they do not share a view's `pace`. */
+export const SPEED_KEY = "replay-speed";
+/** A replay's usual speeds. A page sets its own with `steps`. */
+export const DEFAULT_STEPS = "0.25 0.5 1 2 4";
+/** Whether an address or attribute value means on. Anything else, including nothing, is off. */
+export function flagOn(value) {
+    return value === "on" || value === "true" || value === "1";
+}
+/**
+ * The address keys for play and repeat. `play:p,repeat:r` renames either; an unknown name is ignored.
+ * @param spec The `address-keys` attribute.
+ * @returns The key for each choice.
+ */
+export function addressKeys(spec) {
+    const out = { play: PLAY_KEY, repeat: REPEAT_KEY };
+    for (const part of (spec ?? "").split(",")) {
+        const [name, key] = part.split(":").map((piece) => piece.trim());
+        if ((name === "play" || name === "repeat") && key)
+            out[name] = key;
+    }
+    return out;
+}

package/dist/replay-bar/styles.d.ts

@@ -0,0 +1 @@
+export declare const STYLES = "\n:host {\n  --_ink: var(--kazoku-ink, #1b1b1f);\n  --_surface: var(--kazoku-surface, #ffffff);\n  --_line: var(--kazoku-line, #c9ccd3);\n  --_accent: var(--kazoku-accent, #2457d6);\n  display: inline-block;\n  box-sizing: border-box;\n  color: var(--_ink);\n  font: 600 0.9rem/1.2 system-ui, -apple-system, \"Hiragino Sans\", \"Noto Sans JP\", \"Segoe UI\", sans-serif;\n  color-scheme: light dark;\n}\n@media (prefers-color-scheme: dark) {\n  :host(:not([theme=\"light\"]):not([data-scheme=\"light\"])) {\n    --_ink: var(--kazoku-ink, #f1f2f6);\n    --_surface: var(--kazoku-surface, #1c1d22);\n    --_line: var(--kazoku-line, #4a4d58);\n    --_accent: var(--kazoku-accent, #8fb0ff);\n  }\n}\n:host([theme=\"dark\"]), :host([data-scheme=\"dark\"]:not([theme=\"light\"])) {\n  --_ink: var(--kazoku-ink, #f1f2f6);\n  --_surface: var(--kazoku-surface, #1c1d22);\n  --_line: var(--kazoku-line, #4a4d58);\n  --_accent: var(--kazoku-accent, #8fb0ff);\n  color-scheme: dark;\n}\n:host([theme=\"light\"]) { color-scheme: light; }\n[hidden] { display: none !important; }\n.vh { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }\n.group { display: inline-flex; align-items: center; flex-wrap: wrap; gap: 4px; }\nbutton { -webkit-appearance: none; appearance: none; box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center; gap: 6px; min-width: 48px; min-height: 48px; margin: 0; padding: 0 14px; border: 1px solid var(--_line); border-radius: 24px; background: var(--_surface); color: var(--_ink); font: inherit; cursor: pointer; white-space: nowrap; }\nbutton:hover:not(:disabled) { border-color: var(--_ink); }\nbutton:focus-visible { outline: 2px solid var(--_ink); outline-offset: 2px; }\nbutton[aria-pressed=\"true\"] { background: var(--_ink); color: var(--_surface); border-color: var(--_ink); }\nbutton:disabled { opacity: 0.4; cursor: default; }\nsvg { width: 18px; height: 18px; fill: currentColor; flex: none; }\n\n:host([hidden]) { display: none; }\n:host { display: flex; vertical-align: middle; }\n.row { display: flex; align-items: center; flex-wrap: wrap; gap: 6px; }\nbutton[aria-pressed=\"true\"] { background: var(--_ink); color: var(--_surface); }\n";

package/dist/replay-bar/styles.js

@@ -0,0 +1,8 @@
+import { BASE_STYLES } from "../shared/base.js";
+// One row: play, back to the start, repeat, then the speed buttons. Nothing folds away. A narrow page wraps the row; it does not scroll the page sideways.
+export const STYLES = `${BASE_STYLES}
+:host([hidden]) { display: none; }
+:host { display: flex; vertical-align: middle; }
+.row { display: flex; align-items: center; flex-wrap: wrap; gap: 6px; }
+button[aria-pressed="true"] { background: var(--_ink); color: var(--_surface); }
+`;

package/dist/replay-bar/words.d.ts

@@ -0,0 +1,17 @@
+export interface ReplayWords {
+    /** The name of the bar, said by a screen reader. */
+    group: string;
+    /** The button that starts playback. */
+    play: string;
+    /** The same button while playback is going. */
+    pause: string;
+    /** The button that goes back to the start. */
+    start: string;
+    /** The button that loops. */
+    repeat: string;
+}
+export type Language = "en" | "ja";
+export declare const WORDS: Record<Language, ReplayWords>;
+/** The language to use for a `lang` value such as "ja", "ja-JP" or "en-CA": Japanese for ja, English for anything else. */
+export declare const languageOf: (lang: string | null | undefined) => Language;
+export declare const wordsFor: (language: Language, overrides?: Partial<ReplayWords>) => ReplayWords;

package/dist/replay-bar/words.js

@@ -0,0 +1,7 @@
+export const WORDS = {
+    en: { group: "Playback", play: "Play", pause: "Pause", start: "Start", repeat: "Repeat" },
+    ja: { group: "再生の操作", play: "再生", pause: "一時停止", start: "最初へ", repeat: "繰り返し" },
+};
+/** The language to use for a `lang` value such as "ja", "ja-JP" or "en-CA": Japanese for ja, English for anything else. */
+export const languageOf = (lang) => (/^ja\b/i.test(lang ?? "") ? "ja" : "en");
+export const wordsFor = (language, overrides = {}) => ({ ...WORDS[language], ...overrides });

package/dist/view-controls/address.d.ts

@@ -1,3 +1,4 @@
+import { type Direction, type TurnAxis } from "./levels.ts";
 import { type Limits } from "./math.ts";
 export type DragMode = "move" | "turn";
 export interface AddressKeys {
@@ -7,6 +8,16 @@ export interface AddressKeys {
     drag: string;
     /** The auto-turn speed, a number (`0.5`, `2`; 1 is the start and leaves the address). `pace` by default, because a page's own `speed` (a clock's, a replay's) is its own. */
     speed?: string;
+    /** Which way Auto-turn goes, `left` or `right`; `direction` by default. */
+    direction?: string;
+    /** The roll, degrees. `roll` by default. */
+    roll?: string;
+    /** Which axis Auto-turn drives. `axis` by default. */
+    axis?: string;
+    /** Which way tilt's auto-turn goes. `tiltDirection` by default. */
+    tiltDirection?: string;
+    /** Which way roll's auto-turn goes. `rollDirection` by default. */
+    rollDirection?: string;
 }
 export declare const DEFAULT_KEYS: AddressKeys;
 export interface AddressChoices {
@@ -16,6 +27,15 @@ export interface AddressChoices {
     drag: DragMode;
     /** The auto-turn speed as a multiple of the element's `speed`: the number of the button that is on. */
     pace?: number;
+    /** The way Auto-turn goes. In `formatAddress`: a way is written; `null` leaves it off the address (it is the page's own start); left out, the key is not touched. */
+    direction?: Direction | null;
+    roll?: number;
+    /** Which axis Auto-turn drives. `angle` is the start and leaves the address. Left out, the key is not touched. */
+    axis?: TurnAxis | null;
+    /** Tilt's own way. `null` leaves it off the address; left out, the key is not touched. */
+    tiltDirection?: Direction | null;
+    /** Roll's own way. `null` leaves it off the address; left out, the key is not touched. */
+    rollDirection?: Direction | null;
 }
 /** Read the choices out of a query string (`?yaw=40`, with or without the `?`). Anything missing or not a number is left out of the result. */
 export declare function parseAddress(search: string, keys?: AddressKeys, limits?: Limits): Partial<AddressChoices>;

package/dist/view-controls/address.js

@@ -1,8 +1,8 @@
 // The choices kept in the page's address: pure string functions, so a server or a test can use them. Only what a person chose is kept
 // (angle, tilt, zoom, what a drag does); the pan is in pixels of one screen and the turning of a moment, so neither is.
-import { PACE_FACTOR, parsePace } from "./levels.js";
+import { PACE_FACTOR, parseAxis, parseDirection, parsePace } from "./levels.js";
 import { clamp, DEFAULT_LIMITS, wrapYaw } from "./math.js";
-export const DEFAULT_KEYS = { yaw: "yaw", tilt: "tilt", zoom: "zoom", drag: "drag", speed: "pace" };
+export const DEFAULT_KEYS = { yaw: "yaw", tilt: "tilt", zoom: "zoom", drag: "drag", speed: "pace", direction: "direction", roll: "roll", axis: "axis", tiltDirection: "tiltDirection", rollDirection: "rollDirection" };
 const rounded = (value, places) => Number(value.toFixed(places));
 /** Read the choices out of a query string (`?yaw=40`, with or without the `?`). Anything missing or not a number is left out of the result. */
 export function parseAddress(search, keys = DEFAULT_KEYS, limits = DEFAULT_LIMITS) {
@@ -22,6 +22,12 @@ export function parseAddress(search, keys = DEFAULT_KEYS, limits = DEFAULT_LIMIT
         out.yaw = rounded(wrapYaw(yaw), 0);
     if (tilt !== undefined)
         out.tilt = rounded(clamp(tilt, -limits.tiltMax, limits.tiltMax), 0);
+    const roll = number(keys.roll ?? "roll");
+    if (roll !== undefined)
+        out.roll = rounded(clamp(wrapYaw(roll), -limits.rollMax, limits.rollMax), 0);
+    const axis = parseAxis(params.get(keys.axis ?? "axis"));
+    if (axis !== undefined)
+        out.axis = axis;
     if (zoom !== undefined)
         out.zoom = rounded(clamp(zoom, limits.zoomMin, limits.zoomMax), 2);
     const drag = params.get(keys.drag);
@@ -33,6 +39,15 @@ export function parseAddress(search, keys = DEFAULT_KEYS, limits = DEFAULT_LIMIT
     const value = named !== undefined ? PACE_FACTOR[named] : said === null || said.trim() === "" ? Number.NaN : Number(said);
     if (Number.isFinite(value))
         out.pace = value;
+    const direction = parseDirection(params.get(keys.direction ?? "direction"));
+    if (direction !== undefined)
+        out.direction = direction;
+    const tiltDirection = parseDirection(params.get(keys.tiltDirection ?? "tiltDirection"));
+    if (tiltDirection !== undefined)
+        out.tiltDirection = tiltDirection;
+    const rollDirection = parseDirection(params.get(keys.rollDirection ?? "rollDirection"));
+    if (rollDirection !== undefined)
+        out.rollDirection = rollDirection;
     return out;
 }
 /**
@@ -47,15 +62,26 @@ export function formatAddress(search, choices, keys = DEFAULT_KEYS, leaveYaw = f
         else
             params.set(key, value);
     };
-    if (!leaveYaw)
+    if (!leaveYaw) {
         set(keys.yaw, Math.round(choices.yaw) === 0 ? undefined : String(rounded(wrapYaw(choices.yaw), 0)));
-    set(keys.tilt, Math.round(choices.tilt) === 0 ? undefined : String(rounded(choices.tilt, 0)));
+        set(keys.tilt, Math.round(choices.tilt) === 0 ? undefined : String(rounded(choices.tilt, 0)));
+        if (choices.roll !== undefined)
+            set(keys.roll ?? "roll", Math.round(choices.roll) === 0 ? undefined : String(rounded(wrapYaw(choices.roll), 0)));
+    }
     set(keys.zoom, Math.abs(choices.zoom - startZoom) < 0.005 ? undefined : String(rounded(choices.zoom, 2)));
     set(keys.drag, choices.drag === "turn" ? "turn" : undefined);
     // The pace key is touched only when the caller has a pace; the start (1) leaves it off the address.
     const paceKey = keys.speed ?? "pace";
     if (choices.pace !== undefined)
         set(paceKey, choices.pace === 1 ? undefined : String(rounded(choices.pace, 3)));
+    if (choices.direction !== undefined)
+        set(keys.direction ?? "direction", choices.direction === null ? undefined : choices.direction);
+    if (choices.axis !== undefined)
+        set(keys.axis ?? "axis", choices.axis === null || choices.axis === "angle" ? undefined : choices.axis);
+    if (choices.tiltDirection !== undefined)
+        set(keys.tiltDirection ?? "tiltDirection", choices.tiltDirection === null || choices.tiltDirection === "right" ? undefined : choices.tiltDirection);
+    if (choices.rollDirection !== undefined)
+        set(keys.rollDirection ?? "rollDirection", choices.rollDirection === null || choices.rollDirection === "right" ? undefined : choices.rollDirection);
     const text = params.toString();
     return text === "" ? "" : `?${text}`;
 }

package/dist/view-controls/controller.d.ts

@@ -1,6 +1,9 @@
 import type { DragMode } from "./address.ts";
-import { type Camera, type Limits, type Point, type Size } from "./math.ts";
+import type { TurnAxis } from "./levels.ts";
+import { type Camera, type Limits, type Point, type Quat, type Size } from "./math.ts";
 export interface ViewState extends Camera {
+    /** The pose the page should draw. A tumble keeps this continuous when the slider numbers fold at a pole. */
+    orientation: Quat;
     /** True while the view turns by itself. A control never changes this; only play, pause and a grab of the view's own do not either (see `holdTurn`). */
     turning: boolean;
     /** What a plain drag does while zoomed in: move the view, or turn the piece. */
@@ -24,8 +27,10 @@ export interface ViewControllerOptions {
     initial?: Partial<ViewState>;
     /** False for a flat view that cannot turn: a drag then always moves it and the angle and tilt never change. */
     turnable?: boolean;
-    /** Degrees a second when it turns by itself. */
+    /** Degrees a second when it turns by itself. The sign is the active axis's direction. */
     speed?: number;
+    /** Which axis turns by itself. `angle` (yaw) by default. */
+    turnAxis?: TurnAxis;
     limits?: Partial<Limits>;
     /** The starting zoom: "fit" (the default) or a scale where 1 is the scene's natural size; it opens at that scale divided by `fitScale`. With `fitScale` left at 1 a number is a zoom as `ViewState.zoom` has it. `initial.zoom` is used only when this is left out. */
     zoom?: "fit" | number;
@@ -55,6 +60,12 @@ export interface ViewController {
     readonly state: ViewState;
     turnable: boolean;
     speed: number;
+    /** Which axis `play` turns. `angle` is yaw. `all` tumbles on three axes. */
+    turnAxis: TurnAxis;
+    /** Tilt's own direction while `turnAxis` is `all` (and the sign of `speed` while it is `tilt`). 1 or -1. */
+    tiltSign: number;
+    /** Roll's own direction. 1 or -1. */
+    rollSign: number;
     readonly limits: Limits;
     /** What a pointer press leaves alone inside the view (see `ViewControllerOptions.ignore`). Can be changed at any time. */
     ignore: string;