@johnmorrisdotca/kazoku-ui 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.2.1] - 2026-11-01
+
+- `ignore` now sees through shadow DOM: it tests the elements on the event's `composedPath()`, from the innermost up to the view, so a button inside a web component's open shadow root is left alone. Before, only the event's target (the host) was tested. A closed shadow root stays a limit: mark its host with `data-kazoku-ignore`.
+
+## [0.2.0] - 2026-11-01
+
+- A button, link or form control inside the view still works: a pointer press on a child that matches the new `ignore` selector is not captured, so the click goes through and a drag from the empty view still turns it. Attribute `ignore` and `createViewController` option `ignore`; the default is `button, a, input, select, textarea, label, [data-kazoku-ignore]` (`DEFAULT_IGNORE`); `ignore=""` leaves nothing alone.
+- Open at a zoom set against the page's fit scale: `zoom` is `fit` (the default, unchanged) or a number where 1 is the scene's natural size, and `fit-scale` / `setFitScale(n)` / the `fitScale` option tell the controls what zoom 1 means. The event's `zoom` stays 1 at Fit. New controller members `fitScale`, `startZoom`, `setStartZoom`; a new `fit-scale` reason in the event. `formatAddress` takes a fifth argument, `startZoom`, so the opening zoom keeps the address plain.
+
 ## [0.1.0] - 2026-11-01
 
 The first release, and its first part: view controls, at `@johnmorrisdotca/kazoku-ui/view-controls`.

package/README.md

@@ -98,6 +98,27 @@ myPlayButton.onclick = () => view.toggle();
 myZoomIn.onclick = () => view.zoomBy(1.4);
 ```
 
+Options of `createViewController` that match: `zoom` (`"fit"` or a number), `fitScale`, `ignore`. 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
+
+The hands capture the pointer on the `for` element, so a press on a button or link placed inside it would be taken for a drag and its click lost. A press on anything that matches `ignore` is left alone (no capture, no drag, no double-tap), and the click goes through. Mark any other child with `data-kazoku-ignore`. Dragging from the empty part of the view turns it as before.
+
+`ignore` also sees through shadow DOM: it tests every element on the event's path from the innermost one up to the view, so a button inside a web component's open shadow root (a card's own Animate button, say) is left alone even though the event's target is the component. A closed shadow root hides its inside from the page, so only the component itself can be matched: mark the host with `data-kazoku-ignore`, or add its tag name to `ignore`.
+
+### Opening at the scene's natural size
+
+Zoom 1 is Fit, whatever size that is on the page. A page that draws its scene at `fitScale` (for example 0.4 of natural size when it fits the view) and wants to open at natural size sets `zoom="1"` and tells the controls the scale:
+
+```js
+const controls = document.querySelector("kazoku-view-controls");
+controls.setAttribute("zoom", "1"); // natural size
+controls.setFitScale(measure()); // the scale the scene is drawn at when it fits, for example 0.4
+// the event's zoom is now 2.5; draw at event.detail.zoom * controls.fitScale
+```
+
+`setFitScale` moves the view to the opening zoom for the new scale, unless the reader has already zoomed. Fit and the Fit key still go to zoom 1, and the address leaves a zoom out when it is the opening one. `zoom="fit"`, or no `zoom`, changes nothing from before.
+
 ## The event API
 
 `kazoku-viewchange` is dispatched on the element (it bubbles and crosses shadow roots). `event.detail`, and the first argument of `onChange`, is:
@@ -106,12 +127,12 @@ myZoomIn.onclick = () => view.zoomBy(1.4);
 |---|---|
 | `yaw` | Degrees, -180 up to 180: the turn about the vertical. Dragging right makes it larger. |
 | `tilt` | Degrees, held to plus or minus `tilt-max` (30): the top tips away as it gets larger (dragging up). |
-| `zoom` | 1 to 5 (`zoom-min`, `zoom-max`). |
+| `zoom` | 1 to 5 (`zoom-min`, `zoom-max`): 1 is Fit. The scene is drawn at `zoom * fitScale` (see below). |
 | `panX`, `panY` | CSS pixels the zoomed picture is moved from the middle of the view; 0 at 1x. |
 | `turning` | True while Auto-turn is running. |
 | `drag` | `"move"` or `"turn"`: what a plain drag does while zoomed in. |
 | `final` | False for the steps of a drag, a pinch, a slider and the automatic turn; true when something settled. Do the costly drawing on `final`, the cheap transform on every event. |
-| `reason` | What changed it: `init`, `auto`, `drag`, `pinch`, `wheel`, `key`, `slider`, `zoom`, `pan`, `front`, `fit`, `play`, `pause` or `set`. |
+| `reason` | What changed it: `init`, `auto`, `drag`, `pinch`, `wheel`, `key`, `slider`, `zoom`, `pan`, `front`, `fit`, `fit-scale`, `play`, `pause` or `set`. |
 
 An `init` event is sent once, a moment after the element connects, with the starting view (from the attributes and the address). `element.state` is the current view at any time.
 
@@ -121,7 +142,10 @@ An `init` event is sent once, a moment after the element connects, with the star
 |---|---|
 | `for` | The id of the view the hands bind to. Or set `element.view = someElement`. |
 | `lang` | `en` or `ja`. Otherwise the nearest `lang` above it, else English. |
-| `yaw`, `tilt`, `zoom` | The starting view. |
+| `yaw`, `tilt` | The starting angle and tilt. |
+| `zoom` | The starting zoom: `fit` (the default) or a number, a scale where 1 is the scene's natural size. It opens at that number divided by `fit-scale`; with `fit-scale` left at 1 it is the `zoom` of the event. |
+| `fit-scale` | The scale your page draws the scene at when it is at Fit (event `zoom` 1): what zoom 1 means. 1 by default. Or call `element.setFitScale(n)` once the scene is measured. |
+| `ignore` | A CSS selector for what inside the view a pointer press leaves alone, so its click goes through: `button, a, input, select, textarea, label, [data-kazoku-ignore]` by default. A bare `ignore=""` leaves nothing alone. |
 | `autoplay` | Turn by itself from the start, unless the reader prefers reduced motion. |
 | `speed` | Degrees a second (30). |
 | `flat` | The view cannot turn: no angle, tilt, Auto-turn or Front, and a drag moves it. |
@@ -131,12 +155,12 @@ An `init` event is sent once, a moment after the element connects, with the star
 | `theme` | `light` or `dark`; otherwise the page's colour scheme. |
 | `overlay` | Sit over the bottom of a positioned parent. |
 
-Methods: `play()`, `pause()`, `front()`, `fit()`, `set({ yaw, tilt, zoom, panX, panY, drag })`, and `controller` (the `createViewController` object behind it). `element.words = { front: "Home" }` replaces labels.
+Methods: `play()`, `pause()`, `front()`, `fit()`, `set({ yaw, tilt, zoom, panX, panY, drag })`, `setFitScale(n)`, and `controller` (the `createViewController` object behind it). `element.words = { front: "Home" }` replaces labels.
 Colours are custom properties: `--kazoku-ink`, `--kazoku-surface`, `--kazoku-line`, `--kazoku-accent`; the parts are `bar`, `field`, `slider` and `button`.
 
 ### The address
 
-Only what a reader chose is kept: angle, tilt, zoom and the drag choice. The pan is in pixels of one screen and the turning is of a moment, so neither is; while the view turns by itself the angle is left out. A value at its start leaves the address, and other parameters are kept. The address is written at most four times a second (Safari stops a page that changes its address more than 100 times in 30 seconds). Without the element: `parseAddress(search, keys?)` and `formatAddress(search, choices, keys?, leaveYaw?)`.
+Only what a reader chose is kept: angle, tilt, zoom and the drag choice. The pan is in pixels of one screen and the turning is of a moment, so neither is; while the view turns by itself the angle is left out. A value at its start (Fit, or the `zoom` the page opens at) leaves the address, and other parameters are kept. The address is written at most four times a second (Safari stops a page that changes its address more than 100 times in 30 seconds). Without the element: `parseAddress(search, keys?)` and `formatAddress(search, choices, keys?, leaveYaw?, startZoom?)`.
 
 ### Why the tag is only defined when it is free
 
@@ -144,11 +168,11 @@ Only what a reader chose is kept: angle, tilt, zoom and the drag choice. The pan
 
 ## Size
 
-Gzipped, unbundled: the element and its definition about 4.8 KB, the controller 3.5 KB, the maths 1.4 KB, the address 1.2 KB, the labels 0.7 KB and the styles 1.6 KB (`pnpm test:package` prints them). Nothing is loaded from the network.
+Gzipped, unbundled: the element and its definition about 5.0 KB, the controller 3.9 KB, the maths 1.4 KB, the address 1.2 KB, the labels 0.7 KB and the styles 1.6 KB (`pnpm test:package` prints them). Nothing is loaded from the network.
 
 ## Checks
 
-`pnpm check` (lint, types, 25 unit tests of the maths, the address and the controller, the build and the packed package), and `pnpm test:demo` (the demo in Chromium and WebKit at a phone's width and a desk's: the controls in the first screen, a toggle during Auto-turn leaves the angle advancing, zoom about the pointer, pan when zoomed, touch, the address, the labels, reduced motion).
+`pnpm check` (lint, types, 29 unit tests of the maths, the address, the controller and the package, the build and the packed package), and `pnpm test:demo` (the demo in Chromium and WebKit at a phone's width and a desk's: the controls in the first screen, a toggle during Auto-turn leaves the angle advancing, a button or link inside the view still clicks while a drag turns it, the opening zoom and fit scale, zoom about the pointer, pan when zoomed, touch, the address, the labels, reduced motion).
 
 ## Not yet
 

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

@@ -17,8 +17,8 @@ export interface AddressChoices {
 export declare function parseAddress(search: string, keys?: AddressKeys, limits?: Limits): Partial<AddressChoices>;
 /**
  * The query string (with its `?`, or empty) that keeps `choices` and every other parameter of `search`. A choice at its starting value is left out, so
- * the plain address stays plain. `leaveYaw` keeps the angle out while the view turns by itself (it would change every frame).
+ * the plain address stays plain. `leaveYaw` keeps the angle out while the view turns by itself (it would change every frame). `startZoom` is the zoom the view opens at (1, Fit, unless the page starts elsewhere).
  */
-export declare function formatAddress(search: string, choices: AddressChoices, keys?: AddressKeys, leaveYaw?: boolean): string;
+export declare function formatAddress(search: string, choices: AddressChoices, keys?: AddressKeys, leaveYaw?: boolean, startZoom?: number): string;
 /** Read `address-keys`: `yaw:a,tilt:b` renames the keys it names and leaves the others. */
 export declare function parseKeys(text: string | null): AddressKeys;

package/dist/view-controls/address.js

@@ -30,9 +30,9 @@ export function parseAddress(search, keys = DEFAULT_KEYS, limits = DEFAULT_LIMIT
 }
 /**
  * The query string (with its `?`, or empty) that keeps `choices` and every other parameter of `search`. A choice at its starting value is left out, so
- * the plain address stays plain. `leaveYaw` keeps the angle out while the view turns by itself (it would change every frame).
+ * the plain address stays plain. `leaveYaw` keeps the angle out while the view turns by itself (it would change every frame). `startZoom` is the zoom the view opens at (1, Fit, unless the page starts elsewhere).
  */
-export function formatAddress(search, choices, keys = DEFAULT_KEYS, leaveYaw = false) {
+export function formatAddress(search, choices, keys = DEFAULT_KEYS, leaveYaw = false, startZoom = 1) {
     const params = new URLSearchParams(search);
     const set = (key, value) => {
         if (value === undefined)
@@ -43,7 +43,7 @@ export function formatAddress(search, choices, keys = DEFAULT_KEYS, leaveYaw = f
     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.zoom, Math.abs(choices.zoom - 1) < 0.005 ? undefined : String(rounded(choices.zoom, 2)));
+    set(keys.zoom, Math.abs(choices.zoom - startZoom) < 0.005 ? undefined : String(rounded(choices.zoom, 2)));
     set(keys.drag, choices.drag === "turn" ? "turn" : undefined);
     const text = params.toString();
     return text === "" ? "" : `?${text}`;

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

@@ -12,6 +12,8 @@ export interface ChangeInfo {
     /** What changed it: "set", "auto", "drag", "pinch", "wheel", "key", "zoom", "pan", "front", "fit", "play", "pause", "tap". */
     reason: string;
 }
+/** What `bind` leaves alone by default: the page's own controls inside the view. */
+export declare const DEFAULT_IGNORE = "button, a, input, select, textarea, label, [data-kazoku-ignore]";
 export interface Clock {
     request(callback: (now: number) => void): number;
     cancel(id: number): void;
@@ -23,6 +25,12 @@ export interface ViewControllerOptions {
     /** Degrees a second when it turns by itself. */
     speed?: number;
     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;
+    /** The page's scale when the view is at Fit (`state.zoom` 1): what zoom 1 means. The scene is drawn at `state.zoom * fitScale`. 1 by default. */
+    fitScale?: number;
+    /** A CSS selector for what inside the view `bind` leaves alone: a press on a match is not captured, so its click goes through. An empty string leaves nothing alone. */
+    ignore?: string;
     /** 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;
@@ -34,6 +42,16 @@ export interface ViewController {
     turnable: boolean;
     speed: number;
     readonly limits: Limits;
+    /** What a pointer press leaves alone inside the view (see `ViewControllerOptions.ignore`). Can be changed at any time. */
+    ignore: string;
+    /** 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. */
+    readonly startZoom: number;
+    /** Tell the controller what zoom 1 means. If the reader has not zoomed since the start, the view moves to the starting zoom for the new scale. */
+    setFitScale(scale: number): void;
+    /** Start at "fit" or at a scale relative to natural size, and go there now. */
+    setStartZoom(zoom: "fit" | number): void;
     set(next: Partial<ViewState>, final?: boolean, reason?: string): void;
     play(): void;
     pause(): void;

package/dist/view-controls/controller.js

@@ -1,4 +1,7 @@
 import { 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]";
+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) });
 export function createViewController(options = {}) {
     const limits = { ...DEFAULT_LIMITS, ...options.limits };
@@ -8,7 +11,14 @@ export function createViewController(options = {}) {
     let frame = 0;
     let last = 0;
     let holds = 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 };
+    if (start !== "fit")
+        state.zoom = clamp(startState(), limits.zoomMin, limits.zoomMax);
+    atStart = state.zoom === clamp(startState(), limits.zoomMin, limits.zoomMax);
     const size = () => {
         const own = sizeOf?.();
         if (own !== undefined)
@@ -29,6 +39,8 @@ export function createViewController(options = {}) {
         const held = clampPan({ ...next, zoom: clamp(next.zoom, limits.zoomMin, limits.zoomMax), tilt: clamp(next.tilt, -limits.tiltMax, limits.tiltMax) }, size());
         state.yaw = controller.turnable ? wrapYaw(held.yaw) : state.yaw;
         state.tilt = controller.turnable ? held.tilt : state.tilt;
+        if (held.zoom !== state.zoom)
+            atStart = false;
         state.zoom = held.zoom;
         state.panX = held.panX;
         state.panY = held.panY;
@@ -66,6 +78,32 @@ export function createViewController(options = {}) {
         turnable: options.turnable ?? true,
         speed: options.speed ?? 30,
         limits,
+        ignore: options.ignore ?? DEFAULT_IGNORE,
+        get fitScale() {
+            return fitScale;
+        },
+        get startZoom() {
+            return clamp(startState(), limits.zoomMin, limits.zoomMax);
+        },
+        setFitScale(scale) {
+            const next = positive(scale);
+            if (next === undefined || next === fitScale)
+                return;
+            fitScale = next;
+            if (!atStart)
+                return;
+            const before = state.zoom;
+            take({ ...camera(), zoom: startState() });
+            atStart = true;
+            if (state.zoom !== before)
+                emit(true, "fit-scale");
+        },
+        setStartZoom(zoom) {
+            start = positive(zoom) ?? "fit";
+            take({ ...camera(), zoom: startState() });
+            atStart = true;
+            emit(true, "set");
+        },
         set(next, final = true, reason = "set") {
             const { turning, drag, ...cam } = next;
             take({ ...camera(), ...cam });
@@ -161,9 +199,33 @@ export function createViewController(options = {}) {
             holding = false;
         };
         const canTurn = () => controller.turnable;
+        const ignored = (e) => {
+            if (controller.ignore === "")
+                return false;
+            const path = typeof e.composedPath === "function" ? e.composedPath() : [];
+            try {
+                if (path.length === 0) {
+                    const target = e.target;
+                    const hit = typeof target?.closest === "function" ? target.closest(controller.ignore) : null;
+                    return hit !== null && hit !== view && view.contains(hit);
+                }
+                for (const node of path) {
+                    if (node === view)
+                        return false;
+                    if (typeof node.matches === "function" && node.matches(controller.ignore))
+                        return true;
+                }
+            }
+            catch {
+                return false;
+            }
+            return false;
+        };
         const onDown = (e) => {
             if (e.pointerType === "mouse" && e.button > 2)
                 return;
+            if (ignored(e))
+                return;
             pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
             try {
                 view.setPointerCapture(e.pointerId);

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

@@ -8,9 +8,11 @@ export interface ViewChangeDetail extends ViewState {
     reason: string;
 }
 /**
- * Attributes: `for` (the id of the view to bind), `lang` (en or ja; else the page's), `yaw`, `tilt`, `zoom` (the starting view), `autoplay` (turn by itself from the
- * start, unless the reader prefers reduced motion), `speed` (degrees a second), `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).
+ * Attributes: `for` (the id of the view to bind), `lang` (en or ja; else the page's), `yaw`, `tilt` (the starting view), `zoom` (`fit`, the default, or a scale where 1
+ * is the scene's natural size), `fit-scale` (the page's scale at Fit: what zoom 1 means), `ignore` (a selector for what inside the view a pointer press leaves alone;
+ * buttons, links and form controls by default), `autoplay` (turn by itself from the start, unless the reader prefers reduced motion), `speed` (degrees a second),
+ * `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 {
     #private;
@@ -30,6 +32,9 @@ export declare class ViewControlsElement extends HTMLElement {
     front(): void;
     fit(): void;
     set(next: Partial<ViewState>): void;
+    /** What zoom 1 means to the page: the scene is drawn at `state.zoom * fitScale`. */
+    get fitScale(): number;
+    setFitScale(scale: number): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;

package/dist/view-controls/element.js

@@ -1,7 +1,7 @@
 // <kazoku-view-controls>: the view controls as a framework-free custom element. It never draws the scene. It binds the pointer, pinch, wheel and keys
 // to the element named by `for`, and tells the page what the view is now with a `kazoku-viewchange` event; the page applies it to its canvas, WebGL, SVG or CSS 3D.
 import { DEFAULT_KEYS, formatAddress, parseAddress, parseKeys } from "./address.js";
-import { createViewController } from "./controller.js";
+import { createViewController, DEFAULT_IGNORE } from "./controller.js";
 import { EVENT, TAG } from "./index.js";
 import { ZOOM_STEP, ZOOMED } from "./math.js";
 import { STYLES } from "./styles.js";
@@ -42,12 +42,14 @@ const HTML = `
   </div>
 </div>`;
 /**
- * Attributes: `for` (the id of the view to bind), `lang` (en or ja; else the page's), `yaw`, `tilt`, `zoom` (the starting view), `autoplay` (turn by itself from the
- * start, unless the reader prefers reduced motion), `speed` (degrees a second), `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).
+ * Attributes: `for` (the id of the view to bind), `lang` (en or ja; else the page's), `yaw`, `tilt` (the starting view), `zoom` (`fit`, the default, or a scale where 1
+ * is the scene's natural size), `fit-scale` (the page's scale at Fit: what zoom 1 means), `ignore` (a selector for what inside the view a pointer press leaves alone;
+ * buttons, links and form controls by default), `autoplay` (turn by itself from the start, unless the reader prefers reduced motion), `speed` (degrees a second),
+ * `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", "speed", "flat", "tilt-max", "zoom-min", "zoom-max", "address-keys"];
+    static observedAttributes = ["for", "lang", "yaw", "tilt", "zoom", "fit-scale", "ignore", "speed", "flat", "tilt-max", "zoom-min", "zoom-max", "address-keys"];
     #root;
     #controller;
     #view;
@@ -96,6 +98,13 @@ export class ViewControlsElement extends HTMLElement {
     set(next) {
         this.#ensure().set(next);
     }
+    /** What zoom 1 means to the page: the scene is drawn at `state.zoom * fitScale`. */
+    get fitScale() {
+        return this.#ensure().fitScale;
+    }
+    setFitScale(scale) {
+        this.#ensure().setFitScale(scale);
+    }
     connectedCallback() {
         const c = this.#ensure();
         if (this.#root.querySelector(".bar") === null)
@@ -103,7 +112,7 @@ export class ViewControlsElement extends HTMLElement {
         this.#keys = parseKeys(this.getAttribute("address-keys"));
         this.#limits();
         const start = {};
-        for (const key of ["yaw", "tilt", "zoom"]) {
+        for (const key of ["yaw", "tilt"]) {
             const value = Number(this.getAttribute(key));
             if (this.hasAttribute(key) && Number.isFinite(value))
                 start[key] = value;
@@ -112,6 +121,11 @@ export class ViewControlsElement extends HTMLElement {
             Object.assign(start, parseAddress(globalThis.location?.search ?? "", this.#keys, c.limits));
         c.turnable = !this.hasAttribute("flat");
         c.speed = Number(this.getAttribute("speed")) || 30;
+        c.ignore = this.getAttribute("ignore") ?? DEFAULT_IGNORE;
+        const fitScale = Number(this.getAttribute("fit-scale"));
+        if (this.hasAttribute("fit-scale"))
+            c.setFitScale(fitScale);
+        c.setStartZoom(this.#startZoom());
         c.set(start, true, "init");
         this.#label();
         this.#resolveView();
@@ -147,10 +161,16 @@ export class ViewControlsElement extends HTMLElement {
             this.#resolveView();
         else if (name === "lang")
             this.#label();
-        else if (name === "yaw" || name === "tilt" || name === "zoom") {
+        else if (name === "yaw" || name === "tilt") {
             if (value !== null && Number.isFinite(Number(value)))
                 c.set({ [name]: Number(value) });
         }
+        else if (name === "zoom")
+            c.setStartZoom(this.#startZoom());
+        else if (name === "fit-scale")
+            c.setFitScale(Number(value));
+        else if (name === "ignore")
+            c.ignore = value ?? DEFAULT_IGNORE;
         else if (name === "speed")
             c.speed = Number(value) || 30;
         else if (name === "flat") {
@@ -162,6 +182,10 @@ export class ViewControlsElement extends HTMLElement {
         else
             this.#limits();
     }
+    #startZoom() {
+        const value = Number(this.getAttribute("zoom"));
+        return this.hasAttribute("zoom") && Number.isFinite(value) && value > 0 ? value : "fit";
+    }
     #ensure() {
         if (this.#controller === undefined) {
             this.#controller = createViewController({ onChange: (state, info) => this.#changed(state, info) });
@@ -305,7 +329,7 @@ export class ViewControlsElement extends HTMLElement {
             this.#saveTimer = 0;
             try {
                 const s = this.#ensure().state;
-                const next = formatAddress(globalThis.location.search, s, this.#keys, s.turning);
+                const next = formatAddress(globalThis.location.search, s, this.#keys, s.turning, this.#ensure().startZoom);
                 if (next !== globalThis.location.search)
                     globalThis.history.replaceState(globalThis.history.state, "", `${globalThis.location.pathname}${next}${globalThis.location.hash}`);
             }

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

@@ -1,5 +1,5 @@
 export { DEFAULT_KEYS, formatAddress, parseAddress, parseKeys, type AddressChoices, type AddressKeys, type DragMode } from "./address.ts";
-export { createViewController, type ChangeInfo, type Clock, type ViewController, type ViewControllerOptions, type ViewState } from "./controller.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 { languageOf, WORDS, wordsFor, type Language, type ViewWords } from "./words.ts";
 export declare const EVENT = "kazoku-viewchange";

package/dist/view-controls/index.js

@@ -1,6 +1,6 @@
 // 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 } from "./controller.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 { languageOf, WORDS, wordsFor } from "./words.js";
 export const EVENT = "kazoku-viewchange";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/kazoku-ui",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Kazoku UI 家族, the family's shared interface parts as their own versioned package. First part: view controls for any 3D or zoomable view (angle, tilt, auto-turn, zoom about the pointer, pan, touch, address state) as a framework-free custom element and a plain controller. Zero dependencies.",
   "keywords": [
     "view-controls",