@johnmorrisdotca/kazoku-ui 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.11.0] - 2026-11-03
+
+- **Exact grab** (KAZOKU-UI-28, from chikyu-earth's MODULES-200). `grab-radius` on `<kazoku-view-controls>` (and `grabRadius` on `createViewController`, `degreesPerPixel` and a `grabRadius` argument to `dragTurn`): the on-screen radius of a globe or turnable piece in CSS pixels at Fit, or `fit` for half the smaller side of the view. A drag then turns the view by the angle that keeps the touched point under the pointer, on both axes, and the radius grows with the zoom. Left out, nothing changes: the fixed angle across the view (180 degrees across the width, 60 down the height) that moved a globe's ground about 1.5 pixels for each pixel of drag sideways and half a pixel up and down.
+- **A Centre button** (KAZOKU-UI-33). Once the view is zoomed or moved, a Centre button (中央) puts the object back in the middle at Fit and the default angle, with a quarter of a second's move (at once under reduced motion; a hand on the view stops it): `element.centre()`, `controller.centre(animate)`, the `centre` word in both languages, `between()` in the maths. The keys Home and 0 do the same without the move. `object-size` (`objectSize`) holds a pan so that at least a quarter of an object smaller than the view stays in view.
+- **The drag rule**, written down in `docs/drag-rule.md`: the surface under the pointer follows the pointer, the arrow keys agree, Auto-turn goes the object's real way.
+- **`templates/e2e-ground.mjs`**, the shared browser check of the rule (`checkFollowsTheHand`, `checkExactGrab`, and the parts; `picture` names what is photographed and `window` the part of it that is followed, for a thin object such as a rocket), copied unchanged into a package's `e2e/`; a unit test holds its finder. The demo's `grab.html` draws a globe turned with exact grab and is tested with the helper.
+
 ## [0.10.1] - 2026-11-02
 
 - **`onContext("restored")`** (KAZOKU-UI-15, found by chikyu-earth). The shared renderer's `onContext` was told `"lost"` and `"unavailable"` but never `"restored"`, although `docs/renderer.md` and the `SharedRendererOptions` type said it was. It is now called when the browser gives the context back, after the focused view draws again. `e2e/renderer.demo.mjs`'s lost-and-restored check reads the events the demo records (`["lost"]`, then `["lost", "restored"]`); it fails on 0.10.0, where the second list is `["lost"]`.

package/README.md

@@ -9,7 +9,7 @@ The family's shared interface parts, as their own versioned package: one part pe
 The first part is the **view controls** for any 3D or zoomable view. They never draw the scene: they tell your page what the reader chose, and your canvas, WebGL,
 SVG or CSS 3D applies it.
 
-[Demo](https://johnmorrisdotca.github.io/kazoku-ui/) · [Strict-CSP demo](https://johnmorrisdotca.github.io/kazoku-ui/csp.html) · [Theme switch](docs/theme-switch.md) · [Language picker](docs/language-picker.md) · [Address state](docs/address-state.md) · [Save image](docs/save-image.md) · [Shared 3D renderer](docs/renderer.md) · [Content-Security-Policy](docs/csp.md) · [Labels, English and 日本語](docs/labels.md) · [Changelog](CHANGELOG.md)
+[Demo](https://johnmorrisdotca.github.io/kazoku-ui/) · [Strict-CSP demo](https://johnmorrisdotca.github.io/kazoku-ui/csp.html) · [Theme switch](docs/theme-switch.md) · [Language picker](docs/language-picker.md) · [Address state](docs/address-state.md) · [Save image](docs/save-image.md) · [Shared 3D renderer](docs/renderer.md) · [The drag rule](docs/drag-rule.md) · [Content-Security-Policy](docs/csp.md) · [Labels, English and 日本語](docs/labels.md) · [Changelog](CHANGELOG.md)
 
 ```sh
 npm install @johnmorrisdotca/kazoku-ui
@@ -113,7 +113,7 @@ myZoomIn.onclick = () => view.zoomBy(1.4);
 
 The automatic turn is idle whenever nothing can see the view: while the `for` element (else the controls) is scrolled out of sight, and while the tab is hidden. Its frame loop is stopped, so no animation frame is asked for and no `kazoku-viewchange` event with reason `auto` is sent; `state.turning` stays true, and the turn goes on from where it was when the view is back (the first frame back only restarts the clock). A view that opens off screen asks for no frame until it is seen, and an element on no page asks for none. One frame is asked for at a time, and at most one `auto` change is sent a page frame. A page does not need to pause it for these. Without the element, `view.bind(element)` watches the bound element the same way; `view.suspendTurn()` and `view.resumeTurn()` do the same for your own visibility test (they nest, on top of what `bind` does), and `view.play(seconds)` stops the turn by itself after that many seconds of turning.
 
-Options of `createViewController` that match: `zoom` (`"fit"` or a number), `fitScale`, `ignore`, `anchor`, `keyTilt`, `stopTurn`, `tiltStep`. `anchor`, `keyTilt`, `stopTurn` and `tiltStep` are also members you can change at any time. The controller also has `ignore` (changeable), `fitScale`, `startZoom` (the `zoom` the view opens at) and `setFitScale(n)`, `setStartZoom(zoom)`; `DEFAULT_IGNORE` is the default selector.
+Options of `createViewController` that match: `zoom` (`"fit"` or a number), `fitScale`, `ignore`, `anchor`, `keyTilt`, `stopTurn`, `tiltStep`, `grabRadius`. `anchor`, `keyTilt`, `stopTurn`, `tiltStep` and `grabRadius` are also members you can change at any time. The controller also has `ignore` (changeable), `fitScale`, `startZoom` (the `zoom` the view opens at) and `setFitScale(n)`, `setStartZoom(zoom)`; `DEFAULT_IGNORE` is the default selector.
 
 ### Buttons and links inside the view
 
@@ -131,6 +131,14 @@ controls.anchor = { x: 60, y: -30 }; // pixels from the view's middle when it is
 
 Zoom is about that point of the picture, so it stays put on screen however far in the reader is and wherever the view has been moved to: `+` then `-` leaves it where it was within a pixel. Without the element, set `view.anchor` on the controller, or pass `anchor` to `createViewController`; `view.zoomBy(f)` and `view.zoomAt(z)` with no point use it.
 
+### Centre
+
+Zoom in and drag the object away and a **Centre** button (中央) comes into the bar. It puts the object back in the middle at Fit and the default angle (yaw and tilt 0) with a quarter of a second's move, at once for a reader who prefers reduced motion, and a hand on the view (a press, the wheel, a key) stops the move where it is. `element.centre()` and `controller.centre(animate = true)` do the same from code, ending with a change whose `reason` is `"centre"`. The keys Home and 0 are the same without the move (they send `front` and `fit`). The pan is held so the object cannot be lost: the picture keeps covering the view, or, with `object-size`, a quarter of the object stays in view.
+
+### The drag rule and exact grab
+
+In every turnable view the surface under the pointer follows the pointer, the arrow keys agree, and Auto-turn goes the object's real way; `grab-radius` makes a drag keep the touched point under the pointer on a globe. The rule, the option and the shared browser check (`templates/e2e-ground.mjs`) are in [docs/drag-rule.md](docs/drag-rule.md); the demo's `grab.html` shows it.
+
 ### Keys, the wheel and the turn
 
 Arrow Up tips like a drag up (`tilt` gets larger). A page whose wheel and keys should agree sets `key-tilt="wheel"`: Arrow Up then tips the way a wheel turned up does (`tilt` gets smaller), and Arrow Down the other way. `stop-turn` stops the automatic turn when the reader takes hold of the view with a press, the wheel or a key (a `pause` event is sent first); the defaults keep it turning, and a button or slider never stops it. `tilt-step="1"` makes a drag give whole degrees of tilt.
@@ -179,6 +187,8 @@ An `init` event is sent once, a moment after the element connects, with the star
 | `key-tilt` | Which way Arrow Up tips the view: `drag` (the default: like a drag up) or `wheel` (the way a wheel turned up tips it, the other way). Arrow Down goes the other way from Up. |
 | `stop-turn` | A press on the view, the wheel over it or a key it handles stops the automatic turn. Off by default, so the turn carries on. Buttons and sliders never stop it. |
 | `tilt-step` | Round the tilt of a drag to a multiple of this many degrees (`1` gives whole degrees). 0 by default: not rounded. |
+| `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 Medium (30); Slow is half and Fast twice. |

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

@@ -41,6 +41,10 @@ export interface ViewControllerOptions {
     stopTurn?: boolean;
     /** Round the tilt of a drag to a multiple of this many degrees; 0 (the default) leaves it unrounded, 1 gives whole degrees. */
     tiltStep?: number;
+    /** Exact grab: the on-screen radius, in CSS pixels at Fit, of the globe or turnable piece, 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 (`degreesPerPixel`), and at a zoom the radius grows with it. 0 (the default) keeps the fixed angle across the view. */
+    grabRadius?: number | "fit";
+    /** 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 it in view (see `clampPan`). Left out, the object is the picture, which covers the view. */
+    objectSize?: Size;
     /** The view's size in CSS pixels, for holding the pan; `bind` gives it from the element when this is left out. */
     size?: () => Size | undefined;
     onChange?: (state: ViewState, info: ChangeInfo) => void;
@@ -59,6 +63,10 @@ export interface ViewController {
     keyTilt: KeyTilt;
     stopTurn: boolean;
     tiltStep: number;
+    /** Exact grab (see `ViewControllerOptions.grabRadius`). Can be changed at any time. */
+    grabRadius: number | "fit";
+    /** The object's size at Fit (see `ViewControllerOptions.objectSize`). Can be changed at any time. */
+    objectSize: Size | undefined;
     /** What zoom 1 means to the page (see `ViewControllerOptions.fitScale`). */
     readonly fitScale: number;
     /** The `state.zoom` the view opens at: 1 for "fit", else the starting scale divided by `fitScale`. The address leaves a zoom at this value out. */
@@ -81,6 +89,8 @@ export interface ViewController {
     releaseTurn(): void;
     front(): void;
     fit(): void;
+    /** Put the object back in the middle at Fit and the default angle (yaw and tilt 0). It moves there over a quarter of a second, and at once for `animate` false or for a reader who prefers reduced motion; any hand on the view stops the move where it is. Ends with a change `{ final: true, reason: "centre" }`. */
+    centre(animate?: boolean): void;
     /** Zoom to `next` about the point `at` (client pixels); left out, about the `anchor`, else the view's middle. */
     zoomAt(next: number, at?: Point, final?: boolean): void;
     zoomBy(factor: number, at?: Point): void;

package/dist/view-controls/controller.js

@@ -1,7 +1,9 @@
 import { turnOnlyInSight } from "./sight.js";
-import { clamp, clampPan, DEFAULT_LIMITS, dragTurn, PAN_STEP, pinchTo, wheelZoomFactor, wrapYaw, ZOOMED, zoomAbout } from "./math.js";
+import { between, clamp, clampPan, DEFAULT_LIMITS, dragTurn, PAN_STEP, pinchTo, 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. */
+const CENTRE_MS = 250;
 const HANDLED_KEYS = ["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "+", "=", "-", "_", "0", "Home"];
 const positive = (value) => (typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined);
 const browserClock = () => ({ request: (callback) => globalThis.requestAnimationFrame(callback), cancel: (id) => globalThis.cancelAnimationFrame(id) });
@@ -17,6 +19,8 @@ export function createViewController(options = {}) {
     let limit = 0;
     let turned = 0;
     let destroyed = false;
+    let centring = 0;
+    let stepping = false;
     let fitScale = positive(options.fitScale) ?? 1;
     let start = positive(options.zoom) ?? "fit";
     let atStart = true;
@@ -39,10 +43,18 @@ export function createViewController(options = {}) {
             bound.style.touchAction = state.zoom > ZOOMED ? "none" : "pan-y";
         options.onChange?.({ ...state }, { final, reason });
     };
+    const stopCentre = () => {
+        if (centring === 0)
+            return;
+        clock.cancel(centring);
+        centring = 0;
+    };
     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 take = (next) => {
-        const held = clampPan({ ...next, zoom: clamp(next.zoom, limits.zoomMin, limits.zoomMax), tilt: clamp(next.tilt, -limits.tiltMax, limits.tiltMax) }, size());
+        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);
         state.yaw = controller.turnable ? wrapYaw(held.yaw) : state.yaw;
         state.tilt = controller.turnable ? held.tilt : state.tilt;
         if (held.zoom !== state.zoom)
@@ -70,7 +82,7 @@ export function createViewController(options = {}) {
         if (!state.turning || suspends > 0)
             return;
         frame = clock.request(tick);
-        if (holds > 0) {
+        if (holds > 0 || centring !== 0) {
             last = 0;
             return;
         }
@@ -94,6 +106,8 @@ export function createViewController(options = {}) {
         keyTilt: options.keyTilt ?? "drag",
         stopTurn: options.stopTurn ?? false,
         tiltStep: options.tiltStep ?? 0,
+        grabRadius: options.grabRadius ?? 0,
+        objectSize: options.objectSize,
         get fitScale() {
             return fitScale;
         },
@@ -186,6 +200,35 @@ export function createViewController(options = {}) {
             take({ ...camera(), zoom: 1, panX: 0, panY: 0 });
             emit(true, "fit");
         },
+        centre(animate = true) {
+            stopCentre();
+            const from = camera();
+            const to = { yaw: 0, tilt: 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) {
+                take(to);
+                emit(true, "centre");
+                return;
+            }
+            let began = -1;
+            const step = (now) => {
+                if (began < 0)
+                    began = now;
+                const fraction = (now - began) / CENTRE_MS;
+                stepping = true;
+                take(between(from, to, fraction));
+                stepping = false;
+                if (fraction >= 1) {
+                    centring = 0;
+                    emit(true, "centre");
+                    return;
+                }
+                emit(false, "centre");
+                centring = clock.request(step);
+            };
+            centring = clock.request(step);
+        },
         zoomAt(next, at, final = true) {
             take(zoomAbout(camera(), next, fromMiddle(at), limits));
             emit(final, "zoom");
@@ -209,6 +252,7 @@ export function createViewController(options = {}) {
         },
         destroy() {
             destroyed = true;
+            stopCentre();
             clock.cancel(frame);
             state.turning = false;
             unbind?.();
@@ -233,6 +277,7 @@ export function createViewController(options = {}) {
         };
         const canTurn = () => controller.turnable;
         const grab = () => {
+            stopCentre();
             if (controller.stopTurn)
                 controller.pause();
         };
@@ -311,7 +356,8 @@ export function createViewController(options = {}) {
                     return;
                 const r = view.getBoundingClientRect();
                 // Up and down tips it for a mouse; on a finger the browser keeps the vertical drag to scroll the page, and the tilt slider tips it.
-                take({ ...camera(), ...dragTurn(gesture.camera, dx, dy, { width: r.width, height: r.height }, e.pointerType !== "touch", limits, controller.tiltStep) });
+                const radius = controller.grabRadius === "fit" ? Math.min(r.width, r.height) / 2 : controller.grabRadius;
+                take({ ...camera(), ...dragTurn(gesture.camera, dx, dy, { width: r.width, height: r.height }, e.pointerType !== "touch", limits, controller.tiltStep, radius * gesture.camera.zoom) });
                 emit(false, "drag");
             }
         };

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

@@ -14,7 +14,7 @@ export interface ViewChangeDetail extends ViewState {
  * buttons, links and form controls by default), `autoplay` (turn by itself from the start, unless the reader prefers reduced motion), `autoplay-for` (stop that turn by itself after this many seconds of turning), `speed` (degrees a second),
  * `anchor` (`x,y`: the point the zoom buttons and keys zoom about, in pixels from the view's middle at Fit), `key-tilt` (`drag`, the default, or `wheel`: which way Arrow Up tips),
  * `controls` (`basic`, the default, or `advanced`: which controls are shown, the zoom readout in both, and the speed in both while the view turns; the reader's own choice with the More button is remembered in localStorage, under `kazoku-view-controls` or the key `storage` names, and wins),
- * `stop-turn` (a press, the wheel or a key on the view stops the automatic turn), `tilt-step` (round a drag's tilt to a multiple of this many degrees), `flat` (the view cannot turn), `tilt-max`, `zoom-min`, `zoom-max`, `address` (keep the choices in the page's address), `address-keys` (`yaw:a,tilt:b`), `theme` (light
+ * `stop-turn` (a press, the wheel or a key on the view stops the automatic turn), `tilt-step` (round a drag's tilt to a multiple of this many degrees), `object-size` (`w,h`: the object's size at Fit in pixels when it is smaller than the view, so a pan keeps a quarter of it in view), `grab-radius` (exact grab: the on-screen radius of the piece in pixels, or `fit`; a drag then keeps the touched point under the pointer), `flat` (the view cannot turn), `tilt-max`, `zoom-min`, `zoom-max`, `address` (keep the choices in the page's address), `address-keys` (`yaw:a,tilt:b`), `theme` (light
  * or dark), `overlay` (sit over the bottom of a positioned parent).
  */
 export declare class ViewControlsElement extends HTMLElement {
@@ -33,6 +33,8 @@ export declare class ViewControlsElement extends HTMLElement {
     play(): void;
     pause(): void;
     front(): void;
+    /** Put the object back in the middle at Fit and the default angle, with a brief move (at once for a reader who prefers reduced motion, or with `false`). */
+    centre(animate?: boolean): void;
     fit(): void;
     set(next: Partial<ViewState>): void;
     /** The point the zoom buttons and keys zoom about: `{ x, y }` in CSS pixels from the view's middle when it is at Fit, moving with the picture. `undefined` zooms about the view's middle. The `anchor` attribute (`"x,y"`) sets the same. */

package/dist/view-controls/element.js

@@ -22,6 +22,7 @@ const ICON = {
     right: icon("M9 5l9 7-9 7z"),
     up: icon("M5 15l7-9 7 9z"),
     down: icon("M5 9l7 9 7-9z"),
+    centre: icon("M11 2h2v5h-2zM11 17h2v5h-2zM2 11h5v2H2zM17 11h5v2h-5zM12 8.5a3.5 3.5 0 1 0 0 7 3.5 3.5 0 1 0 0-7z"),
     more: icon("M3 7h18v2H3zM3 15h18v2H3zM8 4a3 3 0 1 0 0 6 3 3 0 1 0 0-6zM16 12a3 3 0 1 0 0 6 3 3 0 1 0 0-6z"),
 };
 const HTML = `
@@ -36,6 +37,7 @@ const HTML = `
     <button type="button" data-b="fast" aria-pressed="false" part="button"><span data-w="fast"></span></button>
   </div>
   <button type="button" class="front adv" data-b="front" part="button"><span data-w="front"></span></button>
+  <button type="button" class="centre" data-b="centre" part="button" hidden>${ICON.centre}<span class="text" data-w="centre"></span></button>
   <div class="group zoom" role="group" data-g="zoom">
     <button type="button" data-b="out" part="button">${ICON.minus}</button>
     <button type="button" class="level" data-b="level" part="button"><span data-o="zoom">1×</span></button>
@@ -61,11 +63,11 @@ const HTML = `
  * buttons, links and form controls by default), `autoplay` (turn by itself from the start, unless the reader prefers reduced motion), `autoplay-for` (stop that turn by itself after this many seconds of turning), `speed` (degrees a second),
  * `anchor` (`x,y`: the point the zoom buttons and keys zoom about, in pixels from the view's middle at Fit), `key-tilt` (`drag`, the default, or `wheel`: which way Arrow Up tips),
  * `controls` (`basic`, the default, or `advanced`: which controls are shown, the zoom readout in both, and the speed in both while the view turns; the reader's own choice with the More button is remembered in localStorage, under `kazoku-view-controls` or the key `storage` names, and wins),
- * `stop-turn` (a press, the wheel or a key on the view stops the automatic turn), `tilt-step` (round a drag's tilt to a multiple of this many degrees), `flat` (the view cannot turn), `tilt-max`, `zoom-min`, `zoom-max`, `address` (keep the choices in the page's address), `address-keys` (`yaw:a,tilt:b`), `theme` (light
+ * `stop-turn` (a press, the wheel or a key on the view stops the automatic turn), `tilt-step` (round a drag's tilt to a multiple of this many degrees), `object-size` (`w,h`: the object's size at Fit in pixels when it is smaller than the view, so a pan keeps a quarter of it in view), `grab-radius` (exact grab: the on-screen radius of the piece in pixels, or `fit`; a drag then keeps the touched point under the pointer), `flat` (the view cannot turn), `tilt-max`, `zoom-min`, `zoom-max`, `address` (keep the choices in the page's address), `address-keys` (`yaw:a,tilt:b`), `theme` (light
  * 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", "speed", "controls", "flat", "tilt-max", "zoom-min", "zoom-max", "address-keys"];
+    static observedAttributes = ["for", "lang", "yaw", "tilt", "zoom", "fit-scale", "ignore", "anchor", "key-tilt", "stop-turn", "tilt-step", "grab-radius", "object-size", "speed", "controls", "flat", "tilt-max", "zoom-min", "zoom-max", "address-keys"];
     #root;
     #controller;
     #view;
@@ -115,6 +117,10 @@ export class ViewControlsElement extends HTMLElement {
     front() {
         this.#ensure().front();
     }
+    /** Put the object back in the middle at Fit and the default angle, with a brief move (at once for a reader who prefers reduced motion, or with `false`). */
+    centre(animate = true) {
+        this.#ensure().centre(animate);
+    }
     fit() {
         this.#ensure().fit();
     }
@@ -157,7 +163,7 @@ export class ViewControlsElement extends HTMLElement {
         this.#pace = pace ?? "medium";
         this.#speed();
         c.ignore = this.getAttribute("ignore") ?? DEFAULT_IGNORE;
-        for (const name of ["key-tilt", "stop-turn", "tilt-step"])
+        for (const name of ["key-tilt", "stop-turn", "tilt-step", "grab-radius", "object-size"])
             this.#option(name);
         if (this.hasAttribute("anchor"))
             this.#option("anchor");
@@ -216,7 +222,7 @@ export class ViewControlsElement extends HTMLElement {
             c.setFitScale(Number(value));
         else if (name === "ignore")
             c.ignore = value ?? DEFAULT_IGNORE;
-        else if (name === "anchor" || name === "key-tilt" || name === "stop-turn" || name === "tilt-step")
+        else if (name === "anchor" || name === "key-tilt" || name === "stop-turn" || name === "tilt-step" || name === "grab-radius" || name === "object-size")
             this.#option(name);
         else if (name === "speed")
             this.#speed();
@@ -249,6 +255,12 @@ export class ViewControlsElement extends HTMLElement {
             c.stopTurn = value !== null;
         else if (name === "tilt-step")
             c.tiltStep = Number(value) > 0 && Number.isFinite(Number(value)) ? Number(value) : 0;
+        else if (name === "object-size") {
+            const [w, h] = (value ?? "").trim().split(/[\s,x]+/).map(Number);
+            c.objectSize = w !== undefined && w > 0 && Number.isFinite(w) ? { width: w, height: h !== undefined && h > 0 && Number.isFinite(h) ? h : w } : undefined;
+        }
+        else if (name === "grab-radius")
+            c.grabRadius = value?.trim() === "fit" ? "fit" : Number(value) > 0 && Number.isFinite(Number(value)) ? Number(value) : 0;
     }
     #startZoom() {
         const value = Number(this.getAttribute("zoom"));
@@ -307,6 +319,7 @@ export class ViewControlsElement extends HTMLElement {
         on("out", () => c().zoomBy(1 / ZOOM_STEP));
         on("in", () => c().zoomBy(ZOOM_STEP));
         on("fit", () => c().fit());
+        on("centre", () => c().centre());
         on("level", () => c().fit());
         on("more", () => {
             this.#level = this.#level === "basic" ? "advanced" : "basic";
@@ -421,6 +434,8 @@ export class ViewControlsElement extends HTMLElement {
         q('[data-o="yaw"]').value = `${Math.round(s.yaw)}°`;
         q('[data-o="tilt"]').value = `${Math.round(s.tilt)}°`;
         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";

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

@@ -1,6 +1,6 @@
 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 { clamp, clampPan, DEFAULT_LIMITS, dragTurn, PAN_STEP, pinchTo, TILT_ACROSS, TURN_ACROSS, 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, PAN_STEP, pinchTo, TILT_ACROSS, TURN_ACROSS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout, type Camera, type Limits, type PinchStart, type Point, type Size } 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";

package/dist/view-controls/index.js

@@ -1,7 +1,7 @@
 // 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 { clamp, clampPan, DEFAULT_LIMITS, dragTurn, PAN_STEP, pinchTo, TILT_ACROSS, TURN_ACROSS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout } from "./math.js";
+export { between, clamp, clampPan, DEFAULT_LIMITS, degreesPerPixel, dragTurn, PAN_STEP, pinchTo, TILT_ACROSS, TURN_ACROSS, 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";

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

@@ -34,8 +34,11 @@ export declare const clamp: (value: number, low: number, high: number) => number
 export declare const wrapYaw: (angle: number) => number;
 /** Zoom to `next` (held between the limits) keeping the point `at` (pixels from the view's middle) where it is. */
 export declare function zoomAbout(camera: Camera, next: number, at: Point, limits?: Limits): Camera;
-/** Hold the pan so the picture still covers the view: at zoom z the picture may move (z - 1) / 2 of the view's size either way. */
-export declare function clampPan(camera: Camera, size: Size | undefined): Camera;
+/**
+ * Hold the pan so the object cannot be lost. By default the object is the picture, which fills the view at Fit: at zoom z it may move (z - 1) / 2 of the view's size either way, so the picture still covers the view.
+ * A page whose object is smaller than the view gives its `object` (its size at Fit, in CSS pixels): it may then move until a quarter of it is still in view, in a view of any size, so it can never be dragged out.
+ */
+export declare function clampPan(camera: Camera, size: Size | undefined, object?: Size): Camera;
 /** What a pinch starts from: the distance between two fingers, their middle, and the camera at that moment. */
 export interface PinchStart {
     distance: number;
@@ -44,7 +47,14 @@ export interface PinchStart {
 }
 /** The camera for two fingers now at `a` and `b`: zoom by the change of distance about where the pinch began, and the middle of the fingers also drags the view. `centre` is the view's middle in client pixels. */
 export declare function pinchTo(start: PinchStart, a: Point, b: Point, centre: Point, limits?: Limits): Camera;
-/** A one-pointer drag that turns: `dx` and `dy` pixels from where it began, in a view of `size`. A finger does not tilt (the page's own scroll keeps the vertical drag). A `step` above 0 rounds the tilt to a multiple of it. */
-export declare function dragTurn(start: Camera, dx: number, dy: number, size: Size, tips: boolean, limits?: Limits, step?: number): Pick<Camera, "yaw" | "tilt">;
+/** Degrees of turn for one pixel of drag when the piece's on-screen radius is `radius` pixels: the pixel that a point at the middle of a sphere's face moves by, so the touched point stays under the pointer. */
+export declare const degreesPerPixel: (radius: number) => number;
+/**
+ * A one-pointer drag that turns: `dx` and `dy` pixels from where it began, in a view of `size`. A finger does not tilt (the page's own scroll keeps the vertical drag). A `step` above 0 rounds the tilt to a multiple of it.
+ * A `grabRadius` above 0 is the on-screen radius, in pixels, of a globe or any turnable piece: both axes then turn by the angle that carries a point at the middle of its face by the pixels dragged (`degreesPerPixel`), instead of a fixed angle across the view.
+ */
+export declare function dragTurn(start: Camera, dx: number, dy: number, size: Size, tips: boolean, limits?: Limits, step?: number, grabRadius?: number): Pick<Camera, "yaw" | "tilt">;
+/** The camera `fraction` of the way (0 to 1) from `from` to `to`, eased out: quick at first, slow at the end. */
+export declare function between(from: Camera, to: Camera, fraction: number): Camera;
 /** The factor a Ctrl or Command wheel turn zooms by (a trackpad's pinch arrives that way). `deltaMode` 1 is lines. */
 export declare const wheelZoomFactor: (deltaY: number, deltaMode: number) => number;

package/dist/view-controls/math.js

@@ -19,14 +19,17 @@ export function zoomAbout(camera, next, at, limits = DEFAULT_LIMITS) {
     const atOne = zoom <= 1;
     return { ...camera, zoom, panX: atOne ? 0 : at.x - (at.x - camera.panX) * k, panY: atOne ? 0 : at.y - (at.y - camera.panY) * k };
 }
-/** Hold the pan so the picture still covers the view: at zoom z the picture may move (z - 1) / 2 of the view's size either way. */
-export function clampPan(camera, size) {
+/**
+ * Hold the pan so the object cannot be lost. By default the object is the picture, which fills the view at Fit: at zoom z it may move (z - 1) / 2 of the view's size either way, so the picture still covers the view.
+ * A page whose object is smaller than the view gives its `object` (its size at Fit, in CSS pixels): it may then move until a quarter of it is still in view, in a view of any size, so it can never be dragged out.
+ */
+export function clampPan(camera, size, object) {
     if (camera.zoom <= 1)
         return { ...camera, panX: 0, panY: 0 };
     if (size === undefined)
         return camera;
-    const roomX = (size.width * (camera.zoom - 1)) / 2;
-    const roomY = (size.height * (camera.zoom - 1)) / 2;
+    const roomX = object === undefined ? (size.width * (camera.zoom - 1)) / 2 : size.width / 2 + (object.width * camera.zoom) / 4;
+    const roomY = object === undefined ? (size.height * (camera.zoom - 1)) / 2 : size.height / 2 + (object.height * camera.zoom) / 4;
     return { ...camera, panX: clamp(camera.panX, -roomX, roomX), panY: clamp(camera.panY, -roomY, roomY) };
 }
 /** The camera for two fingers now at `a` and `b`: zoom by the change of distance about where the pinch began, and the middle of the fingers also drags the view. `centre` is the view's middle in client pixels. */
@@ -38,12 +41,24 @@ export function pinchTo(start, a, b, centre, limits = DEFAULT_LIMITS) {
         return zoomed;
     return { ...zoomed, panX: zoomed.panX + (middle.x - start.middle.x), panY: zoomed.panY + (middle.y - start.middle.y) };
 }
-/** A one-pointer drag that turns: `dx` and `dy` pixels from where it began, in a view of `size`. A finger does not tilt (the page's own scroll keeps the vertical drag). A `step` above 0 rounds the tilt to a multiple of it. */
-export function dragTurn(start, dx, dy, size, tips, limits = DEFAULT_LIMITS, step = 0) {
-    const yaw = wrapYaw(start.yaw + (dx / (size.width || 360)) * TURN_ACROSS);
-    const raw = start.tilt - (dy / (size.height || 360)) * TILT_ACROSS;
+/** Degrees of turn for one pixel of drag when the piece's on-screen radius is `radius` pixels: the pixel that a point at the middle of a sphere's face moves by, so the touched point stays under the pointer. */
+export const degreesPerPixel = (radius) => (180 / Math.PI) / radius;
+/**
+ * A one-pointer drag that turns: `dx` and `dy` pixels from where it began, in a view of `size`. A finger does not tilt (the page's own scroll keeps the vertical drag). A `step` above 0 rounds the tilt to a multiple of it.
+ * A `grabRadius` above 0 is the on-screen radius, in pixels, of a globe or any turnable piece: both axes then turn by the angle that carries a point at the middle of its face by the pixels dragged (`degreesPerPixel`), instead of a fixed angle across the view.
+ */
+export function dragTurn(start, dx, dy, size, tips, limits = DEFAULT_LIMITS, step = 0, grabRadius = 0) {
+    const exact = grabRadius > 0 && Number.isFinite(grabRadius) ? degreesPerPixel(grabRadius) : 0;
+    const yaw = wrapYaw(start.yaw + (exact > 0 ? dx * exact : (dx / (size.width || 360)) * TURN_ACROSS));
+    const raw = start.tilt - (exact > 0 ? dy * exact : (dy / (size.height || 360)) * TILT_ACROSS);
     const tilt = tips ? clamp(step > 0 ? Math.round(raw / step) * step : raw, -limits.tiltMax, limits.tiltMax) : start.tilt;
     return { yaw, tilt };
 }
+/** The camera `fraction` of the way (0 to 1) from `from` to `to`, eased out: quick at first, slow at the end. */
+export function between(from, to, fraction) {
+    const t = 1 - (1 - clamp(fraction, 0, 1)) ** 3;
+    const mix = (a, b) => a + (b - a) * t;
+    return { yaw: mix(from.yaw, to.yaw), tilt: mix(from.tilt, to.tilt), zoom: mix(from.zoom, to.zoom), panX: mix(from.panX, to.panX), panY: mix(from.panY, to.panY) };
+}
 /** The factor a Ctrl or Command wheel turn zooms by (a trackpad's pinch arrives that way). `deltaMode` 1 is lines. */
 export const wheelZoomFactor = (deltaY, deltaMode) => Math.exp(-deltaY * (deltaMode === 1 ? 0.05 : 0.01));

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

@@ -10,6 +10,7 @@ export interface ViewWords {
     zoomTwo: string;
     zoomIn: string;
     fit: string;
+    centre: string;
     pan: string;
     panLeft: string;
     panRight: string;

package/dist/view-controls/words.js

@@ -11,6 +11,7 @@ export const WORDS = {
         zoomTwo: "Zoom to 2 times",
         zoomIn: "Zoom in",
         fit: "Fit",
+        centre: "Centre",
         pan: "Move the view",
         panLeft: "Move left",
         panRight: "Move right",
@@ -38,6 +39,7 @@ export const WORDS = {
         zoomTwo: "2倍にする",
         zoomIn: "拡大",
         fit: "全体",
+        centre: "中央",
         pan: "表示を動かす",
         panLeft: "左へ",
         panRight: "右へ",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/kazoku-ui",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Kazoku UI 家族, the family's shared interface parts as their own versioned package: view controls for any 3D or zoomable view (angle, tilt, auto-turn, zoom about the pointer, pan, touch, address state) a light, dark and auto theme switch, a language picker, choices kept in the address and a save-as-image button, each a framework-free custom element and a plain controller. Zero dependencies; the shared 3D renderer takes three.js as an optional peer.",
   "keywords": [
     "view-controls",