@johnmorrisdotca/kazoku-ui 0.16.0 → 0.17.0

package/dist/view-controls/controller.js

@@ -1,5 +1,5 @@
 import { turnOnlyInSight } from "./sight.js";
-import { between, clamp, clampPan, DEFAULT_LIMITS, dragTurn, PAN_STEP, pinchTo, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOMED, zoomAbout } from "./math.js";
+import { between, clamp, clampPan, DEFAULT_LIMITS, dragTurn, eulerFromQuat, PAN_STEP, pendulumTilt, pinchTo, quatFromEuler, quatIdentity, spinLocal, tumbleRates, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOMED, zoomAbout } from "./math.js";
 /** What `bind` leaves alone by default: the page's own controls inside the view. */
 export const DEFAULT_IGNORE = "button, a, input, select, textarea, label, [data-kazoku-ignore]";
 /** How long a move to the middle takes. */
@@ -21,11 +21,15 @@ export function createViewController(options = {}) {
     let destroyed = false;
     let centring = 0;
     let stepping = false;
+    let tiltPhase = 0;
     let fitScale = positive(options.fitScale) ?? 1;
     let start = positive(options.zoom) ?? "fit";
     let atStart = true;
     const startState = () => (start === "fit" ? 1 : start / fitScale);
-    const state = { yaw: 0, tilt: 0, zoom: 1, panX: 0, panY: 0, turning: false, drag: "move", ...options.initial };
+    const state = { yaw: 0, tilt: 0, roll: 0, orientation: quatIdentity(), zoom: 1, panX: 0, panY: 0, turning: false, drag: "move", ...options.initial };
+    if (state.orientation === undefined)
+        state.orientation = quatIdentity();
+    state.roll ??= 0;
     if (start !== "fit")
         state.zoom = clamp(startState(), limits.zoomMin, limits.zoomMax);
     atStart = state.zoom === clamp(startState(), limits.zoomMin, limits.zoomMax);
@@ -51,17 +55,25 @@ export function createViewController(options = {}) {
     };
     const camera = () => ({ yaw: state.yaw, tilt: state.tilt, zoom: state.zoom, panX: state.panX, panY: state.panY });
     /** Take a camera in, held to the limits and, once the view's size is known, to the room the zoom gives. */
+    const pose = () => {
+        state.orientation = quatFromEuler(state.yaw, state.tilt, state.roll ?? 0);
+    };
     const take = (next) => {
         if (!stepping)
             stopCentre();
-        const held = clampPan({ ...next, zoom: clamp(next.zoom, limits.zoomMin, limits.zoomMax), tilt: clamp(next.tilt, -limits.tiltMax, limits.tiltMax) }, size(), controller.objectSize);
+        const rollMax = limits.rollMax;
+        const roll = clamp(wrapYaw(next.roll ?? state.roll ?? 0), -rollMax, rollMax);
+        const held = clampPan({ ...next, roll, zoom: clamp(next.zoom, limits.zoomMin, limits.zoomMax), tilt: clamp(next.tilt, -limits.tiltMax, limits.tiltMax) }, size(), controller.objectSize);
         state.yaw = controller.turnable ? wrapYaw(held.yaw) : state.yaw;
         state.tilt = controller.turnable ? held.tilt : state.tilt;
+        state.roll = controller.turnable ? roll : state.roll;
         if (held.zoom !== state.zoom)
             atStart = false;
         state.zoom = held.zoom;
         state.panX = held.panX;
         state.panY = held.panY;
+        pose();
+        tiltPhase = Math.asin(clamp(state.tilt / (limits.tiltMax || 1), -1, 1));
     };
     const centre = () => {
         if (bound === undefined)
@@ -86,20 +98,71 @@ export function createViewController(options = {}) {
             last = 0;
             return;
         }
-        const dt = last === 0 ? 0 : Math.min(0.1, (now - last) / 1000);
+        const gap = last === 0 ? 0 : (now - last) / 1000;
+        // The picture moves at most a tenth of a second in one frame, so a late frame does not jump. The limit counts the time that really passed, up to a second, so a turn that stops itself does so when that time has passed.
+        const dt = Math.min(0.1, gap);
         last = now;
-        if (dt === 0)
+        if (gap === 0)
             return;
-        state.yaw = wrapYaw(state.yaw + controller.speed * dt);
-        turned += dt;
+        const rate = controller.speed;
+        if (controller.turnAxis === "tilt")
+            stepTilt(dt, rate);
+        else if (controller.turnAxis === "roll")
+            stepRoll(dt, rate);
+        else if (controller.turnAxis === "all")
+            stepAll(dt);
+        else {
+            state.yaw = wrapYaw(state.yaw + rate * dt);
+            pose();
+        }
+        turned += Math.min(gap, 1);
         emit(false, "auto");
         if (limit > 0 && turned >= limit)
             controller.pause();
     };
+    /** Tilt within the limit swings back. At 90 degrees or more it rolls over on the quaternion, so the up axis never flips. */
+    const stepTilt = (dt, rate) => {
+        if (limits.tiltMax >= 90) {
+            state.orientation = spinLocal(state.orientation, 0, rate * dt, 0);
+            const euler = eulerFromQuat(state.orientation);
+            state.yaw = euler.yaw;
+            state.tilt = euler.tilt;
+            state.roll = euler.roll;
+            return;
+        }
+        tiltPhase += (rate * dt * Math.PI) / 180;
+        state.tilt = pendulumTilt(tiltPhase, limits.tiltMax);
+        pose();
+    };
+    const stepRoll = (dt, rate) => {
+        const max = limits.rollMax;
+        state.roll = max >= 180 ? wrapYaw((state.roll ?? 0) + rate * dt) : clamp((state.roll ?? 0) + rate * dt, -max, max);
+        pose();
+    };
+    const stepAll = (dt) => {
+        const signs = { yaw: controller.speed, tilt: controller.tiltSign, roll: controller.rollSign };
+        const rates = tumbleRates(turned, Math.abs(controller.speed), signs);
+        if (limits.tiltMax >= 90) {
+            state.orientation = spinLocal(state.orientation, rates.yaw * dt, rates.tilt * dt, rates.roll * dt);
+            const euler = eulerFromQuat(state.orientation);
+            state.yaw = euler.yaw;
+            state.tilt = euler.tilt;
+            state.roll = euler.roll;
+            return;
+        }
+        state.yaw = wrapYaw(state.yaw + rates.yaw * dt);
+        state.roll = wrapYaw((state.roll ?? 0) + rates.roll * dt);
+        tiltPhase += (rates.tilt * dt * Math.PI) / 180;
+        state.tilt = pendulumTilt(tiltPhase, limits.tiltMax);
+        pose();
+    };
     const controller = {
         state,
         turnable: options.turnable ?? true,
         speed: options.speed ?? 30,
+        turnAxis: options.turnAxis ?? "angle",
+        tiltSign: 1,
+        rollSign: 1,
         limits,
         ignore: options.ignore ?? DEFAULT_IGNORE,
         anchor: options.anchor,
@@ -193,7 +256,7 @@ export function createViewController(options = {}) {
             last = 0;
         },
         front() {
-            take({ ...camera(), yaw: 0, tilt: 0 });
+            take({ ...camera(), yaw: 0, tilt: 0, roll: 0 });
             emit(true, "front");
         },
         fit() {
@@ -203,7 +266,7 @@ export function createViewController(options = {}) {
         centre(animate = true) {
             stopCentre();
             const from = camera();
-            const to = { yaw: 0, tilt: 0, zoom: 1, panX: 0, panY: 0 };
+            const to = { yaw: 0, tilt: 0, roll: 0, zoom: 1, panX: 0, panY: 0 };
             const reduced = globalThis.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches === true;
             const same = from.yaw === 0 && from.tilt === 0 && from.zoom === 1 && from.panX === 0 && from.panY === 0;
             if (!animate || reduced || same || destroyed) {

package/dist/view-controls/element.js

@@ -6,7 +6,7 @@ import { localStore, remember } from "../shared/store.js";
 import { DEFAULT_KEYS, formatAddress, parseAddress, parseKeys } from "./address.js";
 import { createViewController, DEFAULT_IGNORE } from "./controller.js";
 import { EVENT, TAG } from "./index.js";
-import { LEVEL_STORAGE_KEY, parseDirection, parseLayout, parseLevel, zoomText } from "./levels.js";
+import { LEVEL_STORAGE_KEY, parseAxis, parseDirection, parseLayout, parseLevel, zoomText } from "./levels.js";
 import { ZOOM_STEP, ZOOMED } from "./math.js";
 import { turnOnlyInSight } from "./sight.js";
 import "../speed-buttons/define.js";
@@ -35,7 +35,14 @@ const THUMB = 28;
 const HTML = `
 <div class="bar" part="bar" role="group">
   <div class="field angle" part="field angle"><label data-w="angle" for="yaw"></label><input id="yaw" type="range" min="-180" max="180" step="1" value="0" part="slider" /><output for="yaw" data-o="yaw">0°</output></div>
-  <div class="field tilt adv" part="field tilt"><label data-w="tilt" for="tilt"></label><input id="tilt" type="range" min="-30" max="30" step="1" value="0" part="slider" /><output for="tilt" data-o="tilt">0°</output></div>
+  <div class="field tilt" part="field tilt"><label data-w="tilt" for="tilt"></label><input id="tilt" type="range" min="-30" max="30" step="1" value="0" part="slider" /><output for="tilt" data-o="tilt">0°</output></div>
+  <div class="field roll" part="field roll"><label data-w="roll" for="roll"></label><input id="roll" type="range" min="-180" max="180" step="1" value="0" part="slider" /><output for="roll" data-o="roll">0°</output></div>
+  <div class="group axes" role="group" data-g="axes">
+    <button type="button" data-b="axis-angle" aria-pressed="true" part="button"><span data-w="angle"></span></button>
+    <button type="button" data-b="axis-tilt" aria-pressed="false" part="button"><span data-w="tilt"></span></button>
+    <button type="button" data-b="axis-roll" aria-pressed="false" part="button"><span data-w="roll"></span></button>
+    <button type="button" data-b="axis-all" aria-pressed="false" part="button"><span data-w="tumble"></span></button>
+  </div>
   <button type="button" class="pace-now" data-b="pace-now" part="button" hidden><span class="lbl" data-w="speed"></span><span data-o="pace"></span></button>
   <button type="button" class="play" data-b="play" aria-pressed="false" part="button">${ICON.play}${ICON.pause}<span class="text" data-w="autoTurn"></span></button>
   <div class="pacing adv" data-g="pacing">
@@ -78,7 +85,7 @@ const HTML = `
  * or dark), `overlay` (sit over the bottom of a positioned parent).
  */
 export class ViewControlsElement extends HTMLElement {
-    static observedAttributes = ["for", "lang", "yaw", "tilt", "zoom", "fit-scale", "ignore", "anchor", "key-tilt", "stop-turn", "tilt-step", "grab-radius", "object-size", "speed", "direction", "pace", "paces", "controls", "layout", "flat", "tilt-max", "zoom-min", "zoom-max", "address-keys"];
+    static observedAttributes = ["for", "lang", "yaw", "tilt", "roll", "zoom", "fit-scale", "ignore", "anchor", "key-tilt", "stop-turn", "tilt-step", "grab-radius", "object-size", "speed", "direction", "tilt-direction", "roll-direction", "axis", "pace", "paces", "controls", "layout", "flat", "tilt-max", "roll-max", "zoom-min", "zoom-max", "address-keys"];
     #root;
     #controller;
     #view;
@@ -100,6 +107,9 @@ export class ViewControlsElement extends HTMLElement {
     /** Which way the turn goes now, and the way the page itself starts it (its `direction`, else the sign of its `speed`): the address keeps a way only when it is not the start. */
     #direction = "right";
     #start;
+    #axis = "angle";
+    #tiltWay = "right";
+    #rollWay = "right";
     #writing = false;
     #labels = wordsFor("en");
     #said = "";
@@ -173,13 +183,28 @@ export class ViewControlsElement extends HTMLElement {
         this.#arrange();
         this.#limits();
         const start = {};
-        for (const key of ["yaw", "tilt"]) {
+        for (const key of ["yaw", "tilt", "roll"]) {
             const value = Number(this.getAttribute(key));
             if (this.hasAttribute(key) && Number.isFinite(value))
                 start[key] = value;
         }
-        const { pace, direction, ...chosen } = this.hasAttribute("address") ? parseAddress(globalThis.location?.search ?? "", this.#keys, c.limits) : {};
+        const { pace, direction, axis, tiltDirection, rollDirection, ...chosen } = this.hasAttribute("address") ? parseAddress(globalThis.location?.search ?? "", this.#keys, c.limits) : {};
         Object.assign(start, chosen);
+        this.#axis = axis ?? parseAxis(this.getAttribute("axis")) ?? this.#axis;
+        if (tiltDirection)
+            this.#tiltWay = tiltDirection;
+        else {
+            const tiltWay = parseDirection(this.getAttribute("tilt-direction"));
+            if (tiltWay !== undefined)
+                this.#tiltWay = tiltWay;
+        }
+        if (rollDirection)
+            this.#rollWay = rollDirection;
+        else {
+            const rollWay = parseDirection(this.getAttribute("roll-direction"));
+            if (rollWay !== undefined)
+                this.#rollWay = rollWay;
+        }
         c.turnable = !this.hasAttribute("flat");
         this.#level = parseLevel(this.#remembered()) ?? parseLevel(this.getAttribute("controls")) ?? "basic";
         this.#pace = this.#nearestPace(pace ?? parseSpeed(this.getAttribute("pace"), this.#paces()) ?? 1);
@@ -238,10 +263,15 @@ export class ViewControlsElement extends HTMLElement {
             this.#resolveView();
         else if (name === "lang")
             this.#label();
-        else if (name === "yaw" || name === "tilt") {
+        else if (name === "yaw" || name === "tilt" || name === "roll") {
             if (value !== null && Number.isFinite(Number(value)))
                 c.set({ [name]: Number(value) });
         }
+        else if (name === "axis") {
+            this.#axis = parseAxis(value) ?? "angle";
+            this.#speed();
+            this.#show();
+        }
         else if (name === "zoom")
             c.setStartZoom(this.#startZoom());
         else if (name === "fit-scale")
@@ -266,6 +296,17 @@ export class ViewControlsElement extends HTMLElement {
             this.#speed();
             this.#show();
         }
+        else if (name === "tilt-direction" || name === "roll-direction") {
+            if (this.#writing)
+                return;
+            const way = parseDirection(value) ?? "right";
+            if (name === "tilt-direction")
+                this.#tiltWay = way;
+            else
+                this.#rollWay = way;
+            this.#speed();
+            this.#show();
+        }
         else if (name === "pace" || name === "paces") {
             this.#pace = this.#nearestPace(parseSpeed(this.getAttribute("pace"), this.#paces()) ?? this.#pace);
             this.#speed();
@@ -341,27 +382,30 @@ export class ViewControlsElement extends HTMLElement {
         const c = () => this.#ensure();
         const slider = (id) => {
             const input = q(`#${id}`);
-            // A hand on the angle slider holds the automatic turn still while it is down; the turn then goes on from where the hand left it.
+            // A hand on a turn slider holds the automatic turn still while it is down; the turn then goes on from where the hand left it.
             const hold = () => {
                 this.#sliderHeld += 1;
-                if (this.#sliderHeld === 1 && id === "yaw")
+                if (this.#sliderHeld === 1)
                     c().holdTurn();
             };
             const free = () => {
                 if (this.#sliderHeld === 0)
                     return;
                 this.#sliderHeld = 0;
-                if (id === "yaw")
-                    c().releaseTurn();
+                c().releaseTurn();
             };
             input.addEventListener("pointerdown", () => hold());
             input.addEventListener("pointerup", free);
             input.addEventListener("pointercancel", free);
-            input.addEventListener("input", () => c().set({ [id]: Number(input.value) }, false, "slider"));
-            input.addEventListener("change", () => c().set({ [id]: Number(input.value) }, true, "slider"));
+            input.addEventListener("input", () => c().set({ [id === "yaw" ? this.#hand() : id]: Number(input.value) }, false, "slider"));
+            input.addEventListener("change", () => c().set({ [id === "yaw" ? this.#hand() : id]: Number(input.value) }, true, "slider"));
         };
         slider("yaw");
         slider("tilt");
+        slider("roll");
+        for (const axis of ["angle", "tilt", "roll", "all"]) {
+            q(`[data-b="axis-${axis}"]`).addEventListener("click", () => this.#chooseAxis(axis));
+        }
         this.#zoomSlider(q("#zoom"), c);
         const on = (b, run) => q(`[data-b="${b}"]`).addEventListener("click", run);
         on("play", () => {
@@ -507,22 +551,71 @@ export class ViewControlsElement extends HTMLElement {
         const seconds = Number(this.getAttribute("autoplay-for"));
         return seconds > 0 && Number.isFinite(seconds) ? seconds : undefined;
     }
-    /** A way was pressed. It is written to the `direction` attribute and the address; the angle goes on from where it was, at the same speed. */
+    /** A way was pressed. It sets the active axis's direction (all three when All is on). The angle goes on from where it was. */
     #chooseDirection(direction) {
-        this.#direction = direction;
+        const axes = this.#axis === "all" ? ["angle", "tilt", "roll"] : [this.#axis];
+        for (const axis of axes)
+            this.#putWay(axis, direction);
         this.#speed();
-        if (this.getAttribute("direction") !== direction) {
+        this.#show();
+        if (this.hasAttribute("address"))
+            this.#save();
+    }
+    #putWay(axis, direction) {
+        const name = axis === "tilt" ? "tilt-direction" : axis === "roll" ? "roll-direction" : "direction";
+        if (axis === "tilt")
+            this.#tiltWay = direction;
+        else if (axis === "roll")
+            this.#rollWay = direction;
+        else
+            this.#direction = direction;
+        if (this.getAttribute(name) !== direction) {
+            this.#writing = true;
+            this.setAttribute(name, direction);
+            this.#writing = false;
+        }
+    }
+    /** Which axis Auto-turn drives, and which slider a reader last named. Angle is the start, so it leaves the attribute. */
+    #chooseAxis(axis) {
+        this.#axis = axis;
+        const written = axis === "angle" ? null : axis;
+        if (this.getAttribute("axis") !== written) {
             this.#writing = true;
-            this.setAttribute("direction", direction);
+            if (written === null)
+                this.removeAttribute("axis");
+            else
+                this.setAttribute("axis", written);
             this.#writing = false;
         }
+        this.#speed();
         this.#show();
         if (this.hasAttribute("address"))
             this.#save();
     }
-    /** The turn's degrees a second: the size of the `speed` attribute (30) times the pace, going left when it is negative. */
+    /** The slider shows this axis. All is a tumble, so the slider stays on the angle. */
+    #hand() {
+        if (this.#axis === "tilt")
+            return "tilt";
+        if (this.#axis === "roll")
+            return "roll";
+        return "yaw";
+    }
+    /** The way Left and Right show for the axis that is on. All shows the angle's way. */
+    #activeWay() {
+        if (this.#axis === "tilt")
+            return this.#tiltWay;
+        if (this.#axis === "roll")
+            return this.#rollWay;
+        return this.#direction;
+    }
+    /** The turn's degrees a second: the size of the `speed` attribute (30) times the pace, going left when the active axis says so. */
     #speed() {
-        this.#ensure().speed = Math.abs(Number(this.getAttribute("speed")) || 30) * this.#pace * (this.#direction === "left" ? -1 : 1);
+        const c = this.#ensure();
+        const size = Math.abs(Number(this.getAttribute("speed")) || 30) * this.#pace;
+        c.turnAxis = this.#axis;
+        c.tiltSign = this.#tiltWay === "left" ? -1 : 1;
+        c.rollSign = this.#rollWay === "left" ? -1 : 1;
+        c.speed = size * (this.#activeWay() === "left" ? -1 : 1);
     }
     #limits() {
         const c = this.#ensure();
@@ -531,6 +624,7 @@ export class ViewControlsElement extends HTMLElement {
             return this.hasAttribute(name) && Number.isFinite(value) && value > 0 ? value : fallback;
         };
         c.limits.tiltMax = read("tilt-max", 30);
+        c.limits.rollMax = read("roll-max", 180);
         c.limits.zoomMin = Math.min(1, read("zoom-min", 1));
         c.limits.zoomMax = Math.max(c.limits.zoomMin, read("zoom-max", 5));
         const tilt = this.#root.querySelector("#tilt");
@@ -538,6 +632,11 @@ export class ViewControlsElement extends HTMLElement {
             tilt.min = String(-c.limits.tiltMax);
             tilt.max = String(c.limits.tiltMax);
         }
+        const roll = this.#root.querySelector("#roll");
+        if (roll !== null) {
+            roll.min = String(-c.limits.rollMax);
+            roll.max = String(c.limits.rollMax);
+        }
         this.#drawMarks();
     }
     #resolveView() {
@@ -581,6 +680,7 @@ export class ViewControlsElement extends HTMLElement {
         set('[data-g="zoom"]', words.zoom);
         set('[data-g="pan"]', words.pan);
         set('[data-g="direction"]', words.direction);
+        set('[data-g="axes"]', words.axis);
         set('[data-g="drag"]', words.drag);
         const speeds = this.#root.querySelector("kazoku-speed-buttons");
         speeds?.setAttribute("lang", language);
@@ -599,17 +699,37 @@ export class ViewControlsElement extends HTMLElement {
         const q = (selector) => this.#root.querySelector(selector);
         const yaw = q("#yaw");
         const tilt = q("#tilt");
-        yaw.value = String(Math.round(s.yaw));
+        const roll = q("#roll");
         tilt.value = String(Math.round(s.tilt));
-        q('[data-o="yaw"]').value = `${Math.round(s.yaw)}°`;
+        roll.value = String(Math.round(s.roll ?? 0));
+        // The one slider shows the axis the chips have chosen. All keeps the angle, which is where a tumble is read from.
+        const hand = this.#hand();
+        const span = hand === "tilt" ? c.limits.tiltMax : hand === "roll" ? c.limits.rollMax : 180;
+        const value = hand === "tilt" ? s.tilt : hand === "roll" ? (s.roll ?? 0) : s.yaw;
+        const text = String(Math.round(value));
+        if (yaw.max !== String(span)) {
+            yaw.max = String(span);
+            yaw.min = String(-span);
+        }
+        if (yaw.value !== text)
+            yaw.value = text;
+        const words = this.#labels;
+        const name = hand === "tilt" ? words.tilt : hand === "roll" ? words.roll : words.angle;
+        const label = q('[data-w="angle"]');
+        if (label.textContent !== name)
+            label.textContent = name;
+        q('[data-o="yaw"]').value = `${text}°`;
         q('[data-o="tilt"]').value = `${Math.round(s.tilt)}°`;
+        q('[data-o="roll"]').value = `${Math.round(s.roll ?? 0)}°`;
+        for (const axis of ["angle", "tilt", "roll", "all"]) {
+            q(`[data-b="axis-${axis}"]`).setAttribute("aria-pressed", String(this.#axis === axis));
+        }
         q('[data-b="play"]').setAttribute("aria-pressed", String(s.turning));
         // Centre comes in once the view has been zoomed or moved, which is when the object can be lost; it puts it back in the middle at Fit and the default angle.
         q(".centre").hidden = s.zoom === 1 && s.panX === 0 && s.panY === 0;
         q('[data-b="out"]').disabled = s.zoom <= c.limits.zoomMin + 1e-6;
         q('[data-b="in"]').disabled = s.zoom >= c.limits.zoomMax - 1e-6;
         const advanced = this.#level === "advanced";
-        const words = this.#labels;
         const zoom = zoomText(s.zoom);
         // A frame of the automatic turn comes through here: what has not changed is not written.
         const write = (node, text) => {
@@ -645,8 +765,9 @@ export class ViewControlsElement extends HTMLElement {
         const pace = speedText(this.#pace);
         write(q('[data-o="pace"]'), pace);
         say(q('[data-b="pace-now"]'), `${words.speed}: ${pace}`);
-        q('[data-b="turn-left"]').setAttribute("aria-pressed", String(this.#direction === "left"));
-        q('[data-b="turn-right"]').setAttribute("aria-pressed", String(this.#direction === "right"));
+        const way = this.#activeWay();
+        q('[data-b="turn-left"]').setAttribute("aria-pressed", String(way === "left"));
+        q('[data-b="turn-right"]').setAttribute("aria-pressed", String(way === "right"));
         const more = q('[data-b="more"]');
         more.setAttribute("aria-expanded", String(advanced));
         this.dataset.level = this.#level;
@@ -657,9 +778,9 @@ export class ViewControlsElement extends HTMLElement {
         q('[data-b="turn"]').setAttribute("aria-pressed", String(s.drag === "turn"));
         // A flat view cannot turn: the angle, tilt, auto-turn and front are not shown, and a drag only moves.
         const flat = !c.turnable;
-        for (const selector of [".angle", ".play"])
+        for (const selector of [".angle", ".tilt", ".roll", ".play", '[data-g="axes"]'])
             q(selector).hidden = flat;
-        for (const selector of [".tilt", ".front", '[data-g="drag"]', '[data-g="pacing"]'])
+        for (const selector of [".front", '[data-g="drag"]', '[data-g="pacing"]'])
             q(selector).hidden = flat || !advanced;
         // The speed is always in sight while the view turns: one small button in basic, which steps through the three; advanced always has the three.
         q(".pace-now").hidden = flat || advanced || !s.turning;
@@ -697,7 +818,14 @@ export class ViewControlsElement extends HTMLElement {
     #save() {
         this.#writer.write((search) => {
             const s = this.#ensure().state;
-            return formatAddress(search, { ...s, pace: this.#pace, direction: this.#direction === (this.#start ?? this.#direction) ? null : this.#direction }, this.#keys, s.turning, this.#ensure().startZoom);
+            return formatAddress(search, {
+                ...s,
+                pace: this.#pace,
+                direction: this.#direction === (this.#start ?? this.#direction) ? null : this.#direction,
+                axis: this.#axis,
+                tiltDirection: this.#tiltWay === "right" ? null : this.#tiltWay,
+                rollDirection: this.#rollWay === "right" ? null : this.#rollWay,
+            }, this.#keys, s.turning, this.#ensure().startZoom);
         });
     }
 }

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

@@ -1,8 +1,8 @@
 export { DEFAULT_KEYS, formatAddress, parseAddress, parseKeys, type AddressChoices, type AddressKeys, type DragMode } from "./address.ts";
 export { createViewController, DEFAULT_IGNORE, type ChangeInfo, type Clock, type ViewController, type ViewControllerOptions, type ViewState } from "./controller.ts";
-export { between, clamp, clampPan, DEFAULT_LIMITS, degreesPerPixel, dragTurn, PAN_STEP, pinchTo, TILT_ACROSS, TURN_ACROSS, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout, type Camera, type Limits, type PinchStart, type Point, type Size } from "./math.ts";
+export { between, clamp, clampPan, DEFAULT_LIMITS, degreesPerPixel, dragTurn, eulerFromQuat, PAN_STEP, pendulumTilt, pinchTo, quatFromEuler, quatIdentity, rateSign, spinLocal, TILT_ACROSS, tumbleRates, TURN_ACROSS, upVector, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout, type Camera, type Limits, type PinchStart, type Point, type Quat, type Size, type TumbleSigns, type Vec3 } from "./math.ts";
 export { languageOf, WORDS, wordsFor, type Language, type ViewWords } from "./words.ts";
 export declare const EVENT = "kazoku-viewchange";
 export declare const TAG = "kazoku-view-controls";
-export { LAYOUTS, LEVEL_STORAGE_KEY, PACE_FACTOR, PACES, parseLayout, parseLevel, parsePace, zoomText, type Layout, type Level, type Pace } from "./levels.ts";
+export { LAYOUTS, LEVEL_STORAGE_KEY, PACE_FACTOR, PACES, parseAxis, parseLayout, parseLevel, parsePace, zoomText, type Layout, type Level, type Pace, type TurnAxis } from "./levels.ts";
 export { COMMON_ZOOMS, MARK_GAP, SLIDER_STEP, SNAP_PX, zoomAtPosition, zoomMarks, zoomPosition, zoomSnap, zoomStep, zoomToMark, type ZoomMark } from "./zoomScale.ts";

package/dist/view-controls/index.js

@@ -1,9 +1,9 @@
 // The view controls without the element: the controller, the arithmetic, the address and the labels. Nothing here touches the DOM until `bind` is called, so it imports on a server.
 export { DEFAULT_KEYS, formatAddress, parseAddress, parseKeys } from "./address.js";
 export { createViewController, DEFAULT_IGNORE } from "./controller.js";
-export { between, clamp, clampPan, DEFAULT_LIMITS, degreesPerPixel, dragTurn, PAN_STEP, pinchTo, TILT_ACROSS, TURN_ACROSS, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout } from "./math.js";
+export { between, clamp, clampPan, DEFAULT_LIMITS, degreesPerPixel, dragTurn, eulerFromQuat, PAN_STEP, pendulumTilt, pinchTo, quatFromEuler, quatIdentity, rateSign, spinLocal, TILT_ACROSS, tumbleRates, TURN_ACROSS, upVector, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout } from "./math.js";
 export { languageOf, WORDS, wordsFor } from "./words.js";
 export const EVENT = "kazoku-viewchange";
 export const TAG = "kazoku-view-controls";
-export { LAYOUTS, LEVEL_STORAGE_KEY, PACE_FACTOR, PACES, parseLayout, parseLevel, parsePace, zoomText } from "./levels.js";
+export { LAYOUTS, LEVEL_STORAGE_KEY, PACE_FACTOR, PACES, parseAxis, parseLayout, parseLevel, parsePace, zoomText } from "./levels.js";
 export { COMMON_ZOOMS, MARK_GAP, SLIDER_STEP, SNAP_PX, zoomAtPosition, zoomMarks, zoomPosition, zoomSnap, zoomStep, zoomToMark } from "./zoomScale.js";

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

@@ -11,6 +11,9 @@ export declare const parsePace: (text: string | null | undefined) => Pace | unde
 /** Which way Auto-turn goes. By the drag rule `yaw` goes up as the hand goes right, so `right` is a positive speed and `left` a negative one; the page's drawing decides what that looks like. */
 export type Direction = "left" | "right";
 export declare const parseDirection: (text: string | null | undefined) => Direction | undefined;
+/** Which axis Auto-turn drives. `angle` is yaw, the default. `all` is a tumble on yaw, tilt and roll at once. */
+export type TurnAxis = "angle" | "tilt" | "roll" | "all";
+export declare const parseAxis: (text: string | null | undefined) => TurnAxis | undefined;
 /** The zoom as the readout shows it: `1×`, `2.4×`; below 1, two figures, so a small zoom never reads `0×`. */
 export declare const zoomText: (zoom: number) => string;
 /**

package/dist/view-controls/levels.js

@@ -6,6 +6,7 @@ export const PACES = ["slow", "medium", "fast"];
 export const PACE_FACTOR = { slow: 0.5, medium: 1, fast: 2 };
 export const parsePace = (text) => PACES.find((pace) => pace === text);
 export const parseDirection = (text) => (text === "left" || text === "right" ? text : undefined);
+export const parseAxis = (text) => (text === "angle" || text === "tilt" || text === "roll" || text === "all" ? text : undefined);
 /** The zoom as the readout shows it: `1×`, `2.4×`; below 1, two figures, so a small zoom never reads `0×`. */
 export const zoomText = (zoom) => `${Number(zoom < 1 ? zoom.toPrecision(2) : zoom.toFixed(1))}×`;
 export const LAYOUTS = ["classic", "horizontal", "vertical", "compact"];

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

@@ -10,12 +10,16 @@ export interface Size {
 export interface Camera {
     yaw: number;
     tilt: number;
+    /** Degrees about the view's forward axis. Left out, it is 0. */
+    roll?: number;
     zoom: number;
     panX: number;
     panY: number;
 }
 export interface Limits {
     tiltMax: number;
+    /** How far a hand may roll, in degrees. 180 (the default) is a full turn. */
+    rollMax: number;
     zoomMin: number;
     zoomMax: number;
 }
@@ -64,3 +68,49 @@ export declare function between(from: Camera, to: Camera, fraction: number): Cam
 export declare const wheelZoomFactor: (deltaY: number, deltaMode: number, kind?: "pinch" | "wheel") => number;
 /** Wheel steps closer together than this, in milliseconds, belong to one turn of the wheel or one swipe (with its glide). */
 export declare const WHEEL_GESTURE_MS = 300;
+/** A rotation. `w` is the real part. The identity is `{ x: 0, y: 0, z: 0, w: 1 }`. */
+export interface Quat {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export declare const quatIdentity: () => Quat;
+/** Which way a signed rate points: -1 or 1. Zero and anything that is not a number count as 1. */
+export declare const rateSign: (value: number) => number;
+export declare const normalizeQuat: (q: Quat) => Quat;
+/**
+ * Yaw about Y, then tilt about X, then roll about Z, in degrees. Past a right angle the numbers fold, so a tumble that rolls over keeps its quaternion and only shows these for the sliders.
+ */
+export declare function quatFromEuler(yaw: number, tilt: number, roll: number): Quat;
+/** The yaw, tilt and roll a quaternion shows on the sliders. Tilt stays within a right angle; the quaternion itself does not flip. */
+export declare function eulerFromQuat(q: Quat): {
+    yaw: number;
+    tilt: number;
+    roll: number;
+};
+/**
+ * Turn `q` by `yaw`, `tilt` and `roll` degrees about its own axes (Y, X, then Z). Small steps stay continuous through the poles: the up vector never jumps.
+ */
+export declare function spinLocal(q: Quat, yaw: number, tilt: number, roll: number): Quat;
+/** The view's up axis after `q`. */
+export declare function upVector(q: Quat): Vec3;
+/**
+ * Tilt swinging inside `amplitude` degrees. `phase` is radians of the swing. At the ends it comes back, so a limited tilt never rolls over.
+ */
+export declare const pendulumTilt: (phase: number, amplitude: number) => number;
+export interface TumbleSigns {
+    yaw: number;
+    tilt: number;
+    roll: number;
+}
+/**
+ * Degrees a second for a tumble. The three rates differ, and each drifts on its own incommensurate wave, so the motion does not repeat.
+ * `speed` is the size of the angle's rate. A sign below 0 reverses that axis.
+ */
+export declare function tumbleRates(seconds: number, speed: number, signs: TumbleSigns): TumbleSigns;