@johnmorrisdotca/kazoku-ui 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [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.

package/README.md

@@ -553,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,4 +1,4 @@
-import { type Direction } from "./levels.ts";
+import { type Direction, type TurnAxis } from "./levels.ts";
 import { type Limits } from "./math.ts";
 export type DragMode = "move" | "turn";
 export interface AddressKeys {
@@ -10,6 +10,14 @@ export interface AddressKeys {
     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 {
@@ -21,6 +29,13 @@ export interface AddressChoices {
     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, parseDirection, 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", direction: "direction" };
+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);
@@ -36,6 +42,12 @@ export function parseAddress(search, keys = DEFAULT_KEYS, limits = DEFAULT_LIMIT
     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;
 }
 /**
@@ -50,9 +62,12 @@ 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.
@@ -61,6 +76,12 @@ export function formatAddress(search, choices, keys = DEFAULT_KEYS, leaveYaw = f
         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;