@johnmorrisdotca/kazoku-ui 0.7.2 → 0.9.0

package/dist/testing/index.d.ts

@@ -0,0 +1,34 @@
+/** The GL object kinds counted. */
+export declare const GPU_KINDS: readonly ["Buffer", "Texture", "VertexArray", "Program", "Framebuffer", "Renderbuffer"];
+export type GpuKind = (typeof GPU_KINDS)[number];
+export interface GlCounts {
+    /** WebGL contexts made. */
+    contexts: number;
+    /** Draw calls (drawArrays, drawElements and their instanced forms). */
+    draws: number;
+    /** `requestAnimationFrame` calls made, and the callbacks that ran. */
+    rafRequests: number;
+    rafCallbacks: number;
+    created: Record<GpuKind, number>;
+    deleted: Record<GpuKind, number>;
+}
+/** Install the counters in a page, before its own scripts run. A string, so `page.addInitScript(COUNT_SCRIPT)` takes it as it is. */
+export declare const COUNT_SCRIPT: string;
+/** What the page needs to be: Playwright's `Page` fits. */
+export interface PageLike {
+    evaluate<R>(fn: () => R): Promise<R>;
+}
+/** The counters now, as a copy. */
+export declare function readCounts(page: PageLike): Promise<GlCounts>;
+/** GPU objects alive: made minus deleted, over every kind. Flat across a run of changes means nothing leaks. */
+export declare function gpuObjects(counts: GlCounts): number;
+export interface CanvasSize {
+    /** The most pixels any canvas on the page holds, and the longest side of any. */
+    pixels: number;
+    side: number;
+    count: number;
+}
+/** The biggest canvas on the page, in device pixels. */
+export declare function canvasSize(page: PageLike): Promise<CanvasSize>;
+/** True when a canvas is within the budget (the renderer's own: 6 million pixels, 4096 a side). */
+export declare function withinPixelBudget(size: CanvasSize, maxPixels?: number, maxSide?: number): boolean;

package/dist/testing/index.js

@@ -0,0 +1,64 @@
+// A test kit for a package's freeze checks, so every 3D package asserts the same things: how many WebGL contexts, how many GPU objects stay alive, how many
+// draws and animation frames a page at rest costs, and how big its biggest canvas is. It names no test framework: hand it Playwright's `page` (or anything with
+// `addInitScript` and `evaluate`). Nothing here touches the DOM until the script runs in a page, so it imports on a server.
+//
+//   await page.addInitScript(COUNT_SCRIPT);              // before page.goto
+//   await page.goto(url);
+//   const before = await readCounts(page);
+//   ...the changes under test...
+//   const after = await readCounts(page);
+//   expect(after.contexts).toBe(1);
+//   expect(after.draws - before.draws).toBe(0);           // at rest
+//   expect(gpuObjects(after)).toBe(gpuObjects(before));   // nothing leaked
+/** The GL object kinds counted. */
+export const GPU_KINDS = ["Buffer", "Texture", "VertexArray", "Program", "Framebuffer", "Renderbuffer"];
+/** Install the counters in a page, before its own scripts run. A string, so `page.addInitScript(COUNT_SCRIPT)` takes it as it is. */
+export const COUNT_SCRIPT = `(() => {
+  const c = (window.__kazokuCount = { contexts: 0, draws: 0, rafRequests: 0, rafCallbacks: 0, created: {}, deleted: {} });
+  const kinds = ${JSON.stringify(GPU_KINDS)};
+  for (const k of kinds) { c.created[k] = 0; c.deleted[k] = 0; }
+  const seen = new WeakSet();
+  for (const proto of [window.HTMLCanvasElement && HTMLCanvasElement.prototype, window.OffscreenCanvas && OffscreenCanvas.prototype]) {
+    if (!proto) continue;
+    const getContext = proto.getContext;
+    proto.getContext = function (type, ...rest) {
+      const context = getContext.call(this, type, ...rest);
+      if (context && /^(experimental-)?webgl/.test(String(type)) && !seen.has(context)) { seen.add(context); c.contexts += 1; }
+      return context;
+    };
+  }
+  for (const proto of [window.WebGLRenderingContext && WebGLRenderingContext.prototype, window.WebGL2RenderingContext && WebGL2RenderingContext.prototype]) {
+    if (!proto) continue;
+    for (const k of kinds) {
+      const make = proto["create" + k];
+      const remove = proto["delete" + k];
+      if (make) proto["create" + k] = function (...a) { c.created[k] += 1; return make.apply(this, a); };
+      if (remove) proto["delete" + k] = function (o) { if (o) c.deleted[k] += 1; return remove.call(this, o); };
+    }
+    for (const name of ["drawArrays", "drawElements", "drawArraysInstanced", "drawElementsInstanced", "drawRangeElements"]) {
+      const draw = proto[name];
+      if (draw) proto[name] = function (...a) { c.draws += 1; return draw.apply(this, a); };
+    }
+  }
+  const raf = window.requestAnimationFrame.bind(window);
+  window.requestAnimationFrame = (callback) => { c.rafRequests += 1; return raf((t) => { c.rafCallbacks += 1; callback(t); }); };
+})();`;
+/** The counters now, as a copy. */
+export function readCounts(page) {
+    return page.evaluate(() => JSON.parse(JSON.stringify(window.__kazokuCount)));
+}
+/** GPU objects alive: made minus deleted, over every kind. Flat across a run of changes means nothing leaks. */
+export function gpuObjects(counts) {
+    return GPU_KINDS.reduce((sum, kind) => sum + counts.created[kind] - counts.deleted[kind], 0);
+}
+/** The biggest canvas on the page, in device pixels. */
+export function canvasSize(page) {
+    return page.evaluate(() => {
+        const all = [...document.querySelectorAll("canvas")];
+        return { pixels: Math.max(0, ...all.map((c) => c.width * c.height)), side: Math.max(0, ...all.map((c) => Math.max(c.width, c.height))), count: all.length };
+    });
+}
+/** True when a canvas is within the budget (the renderer's own: 6 million pixels, 4096 a side). */
+export function withinPixelBudget(size, maxPixels = 6_000_000, maxSide = 4096) {
+    return size.pixels <= maxPixels && size.side <= maxSide;
+}

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

@@ -1,3 +1,4 @@
+import { type Pace } from "./levels.ts";
 import { type Limits } from "./math.ts";
 export type DragMode = "move" | "turn";
 export interface AddressKeys {
@@ -5,6 +6,8 @@ export interface AddressKeys {
     tilt: string;
     zoom: string;
     drag: string;
+    /** The auto-turn speed (`slow` or `fast`; Medium is the start and leaves the address). */
+    speed?: string;
 }
 export declare const DEFAULT_KEYS: AddressKeys;
 export interface AddressChoices {
@@ -12,6 +15,7 @@ export interface AddressChoices {
     tilt: number;
     zoom: number;
     drag: DragMode;
+    pace?: Pace;
 }
 /** Read the choices out of a query string (`?yaw=40`, with or without the `?`). Anything missing or not a number is left out of the result. */
 export declare function parseAddress(search: string, keys?: AddressKeys, limits?: Limits): Partial<AddressChoices>;

package/dist/view-controls/address.js

@@ -1,7 +1,8 @@
 // The choices kept in the page's address: pure string functions, so a server or a test can use them. Only what a person chose is kept
 // (angle, tilt, zoom, what a drag does); the pan is in pixels of one screen and the turning of a moment, so neither is.
+import { parsePace } from "./levels.js";
 import { clamp, DEFAULT_LIMITS, wrapYaw } from "./math.js";
-export const DEFAULT_KEYS = { yaw: "yaw", tilt: "tilt", zoom: "zoom", drag: "drag" };
+export const DEFAULT_KEYS = { yaw: "yaw", tilt: "tilt", zoom: "zoom", drag: "drag", speed: "speed" };
 const rounded = (value, places) => Number(value.toFixed(places));
 /** Read the choices out of a query string (`?yaw=40`, with or without the `?`). Anything missing or not a number is left out of the result. */
 export function parseAddress(search, keys = DEFAULT_KEYS, limits = DEFAULT_LIMITS) {
@@ -26,6 +27,9 @@ export function parseAddress(search, keys = DEFAULT_KEYS, limits = DEFAULT_LIMIT
     const drag = params.get(keys.drag);
     if (drag === "turn" || drag === "move")
         out.drag = drag;
+    const pace = parsePace(params.get(keys.speed ?? "speed"));
+    if (pace !== undefined)
+        out.pace = pace;
     return out;
 }
 /**
@@ -45,6 +49,10 @@ export function formatAddress(search, choices, keys = DEFAULT_KEYS, leaveYaw = f
     set(keys.tilt, Math.round(choices.tilt) === 0 ? undefined : String(rounded(choices.tilt, 0)));
     set(keys.zoom, Math.abs(choices.zoom - startZoom) < 0.005 ? undefined : String(rounded(choices.zoom, 2)));
     set(keys.drag, choices.drag === "turn" ? "turn" : undefined);
+    // The speed key is touched only when the caller has a pace, and a value that is not a pace word (a page's own `speed`) is left alone.
+    const speedKey = keys.speed ?? "speed";
+    if (choices.pace !== undefined && (choices.pace !== "medium" || parsePace(params.get(speedKey)) !== undefined))
+        set(speedKey, choices.pace === "medium" ? undefined : choices.pace);
     const text = params.toString();
     return text === "" ? "" : `?${text}`;
 }

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

@@ -13,6 +13,7 @@ export interface ViewChangeDetail extends ViewState {
  * 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), `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 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
  * or dark), `overlay` (sit over the bottom of a positioned parent).
  */

package/dist/view-controls/element.js

@@ -2,9 +2,11 @@
 // 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 { createAddressWriter } from "../address-state/address.js";
 import { adoptStyles } from "../shared/adopt.js";
+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, PACE_FACTOR, PACES, parseLevel, zoomText } from "./levels.js";
 import { ZOOM_STEP, ZOOMED } from "./math.js";
 import { STYLES } from "./styles.js";
 import { languageOf, wordsFor } from "./words.js";
@@ -19,20 +21,27 @@ const ICON = {
     right: icon("M9 5l9 7-9 7z"),
     up: icon("M5 15l7-9 7 9z"),
     down: icon("M5 9l7 9 7-9z"),
+    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 = `
 <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" 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 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>
   <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>
-  <button type="button" class="front" data-b="front" part="button"><span data-w="front"></span></button>
+  <div class="group pace adv" role="group" data-g="pace"><span class="lbl" data-w="speed" aria-hidden="true"></span>
+    <button type="button" data-b="slow" aria-pressed="false" part="button"><span data-w="slow"></span></button>
+    <button type="button" data-b="medium" aria-pressed="true" part="button"><span data-w="medium"></span></button>
+    <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>
   <div class="group zoom" role="group" data-g="zoom">
     <button type="button" data-b="out" part="button">${ICON.minus}</button>
-    <button type="button" class="two" data-b="two" part="button">2×</button>
+    <button type="button" class="level" data-b="level" part="button"><span data-o="zoom">1×</span></button>
     <button type="button" data-b="in" part="button">${ICON.plus}</button>
+    <button type="button" class="two adv" data-b="two" part="button">2×</button>
     <button type="button" data-b="fit" part="button"><span data-w="fit"></span></button>
   </div>
-  <div class="group pan" role="group" data-g="pan" hidden>
+  <div class="group pan adv" role="group" data-g="pan" hidden>
     <button type="button" data-b="left" part="button">${ICON.left}</button>
     <button type="button" data-b="up" part="button">${ICON.up}</button>
     <button type="button" data-b="down" part="button">${ICON.down}</button>
@@ -42,17 +51,20 @@ const HTML = `
       <button type="button" data-b="turn" aria-pressed="false" part="button"><span data-w="dragTurn"></span></button>
     </div>
   </div>
+  <button type="button" class="more" data-b="more" aria-expanded="false" part="button">${ICON.more}<span class="text" data-w="more"></span></button>
+  <span class="vh" role="status" aria-live="polite" data-live></span>
 </div>`;
 /**
  * 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), `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 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
  * 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", "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", "speed", "controls", "flat", "tilt-max", "zoom-min", "zoom-max", "address-keys"];
     #root;
     #controller;
     #view;
@@ -65,6 +77,11 @@ export class ViewControlsElement extends HTMLElement {
     #seen;
     #onScreen = true;
     #suspended = false;
+    #level = "basic";
+    #pace = "medium";
+    #labels = wordsFor("en");
+    #said = "";
+    #sayTimer;
     constructor() {
         super();
         this.#root = this.attachShadow({ mode: "open" });
@@ -130,10 +147,12 @@ export class ViewControlsElement extends HTMLElement {
             if (this.hasAttribute(key) && Number.isFinite(value))
                 start[key] = value;
         }
-        if (this.hasAttribute("address"))
-            Object.assign(start, parseAddress(globalThis.location?.search ?? "", this.#keys, c.limits));
+        const { pace, ...chosen } = this.hasAttribute("address") ? parseAddress(globalThis.location?.search ?? "", this.#keys, c.limits) : {};
+        Object.assign(start, chosen);
         c.turnable = !this.hasAttribute("flat");
-        c.speed = Number(this.getAttribute("speed")) || 30;
+        this.#level = parseLevel(this.#remembered()) ?? parseLevel(this.getAttribute("controls")) ?? "basic";
+        this.#pace = pace ?? "medium";
+        this.#speed();
         c.ignore = this.getAttribute("ignore") ?? DEFAULT_IGNORE;
         for (const name of ["key-tilt", "stop-turn", "tilt-step"])
             this.#option(name);
@@ -174,6 +193,8 @@ export class ViewControlsElement extends HTMLElement {
         this.#view = undefined;
         this.#ready = false;
         this.#writer.cancel();
+        clearTimeout(this.#sayTimer);
+        this.#said = "";
     }
     attributeChangedCallback(name, _old, value) {
         if (!this.#ready)
@@ -196,7 +217,11 @@ export class ViewControlsElement extends HTMLElement {
         else if (name === "anchor" || name === "key-tilt" || name === "stop-turn" || name === "tilt-step")
             this.#option(name);
         else if (name === "speed")
-            c.speed = Number(value) || 30;
+            this.#speed();
+        else if (name === "controls") {
+            this.#level = parseLevel(value) ?? "basic";
+            this.#show();
+        }
         else if (name === "flat") {
             c.turnable = value === null;
             this.#show();
@@ -265,6 +290,21 @@ export class ViewControlsElement extends HTMLElement {
         on("in", () => c.zoomBy(ZOOM_STEP));
         on("two", () => c.zoomAt(2));
         on("fit", () => c.fit());
+        on("level", () => c.fit());
+        on("more", () => {
+            this.#level = this.#level === "basic" ? "advanced" : "basic";
+            remember(this.#storageKey(), this.#level);
+            this.#show();
+        });
+        for (const pace of PACES) {
+            on(pace, () => {
+                this.#pace = pace;
+                this.#speed();
+                this.#show();
+                if (this.hasAttribute("address"))
+                    this.#save();
+            });
+        }
         on("left", () => c.panBy(-1, 0));
         on("right", () => c.panBy(1, 0));
         on("up", () => c.panBy(0, -1));
@@ -272,6 +312,21 @@ export class ViewControlsElement extends HTMLElement {
         on("move", () => c.setDrag("move"));
         on("turn", () => c.setDrag("turn"));
     }
+    #storageKey() {
+        return this.getAttribute("storage") || LEVEL_STORAGE_KEY;
+    }
+    #remembered() {
+        try {
+            return localStore()?.getItem(this.#storageKey()) ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The turn's degrees a second: the `speed` attribute (30) times the pace. */
+    #speed() {
+        this.#ensure().speed = (Number(this.getAttribute("speed")) || 30) * PACE_FACTOR[this.#pace];
+    }
     #limits() {
         const c = this.#ensure();
         const read = (name, fallback) => {
@@ -339,6 +394,7 @@ export class ViewControlsElement extends HTMLElement {
     #label() {
         const language = languageOf(this.getAttribute("lang") ?? this.closest("[lang]")?.getAttribute("lang") ?? this.ownerDocument.documentElement.lang);
         const words = wordsFor(language, this.#words);
+        this.#labels = words;
         for (const node of this.#root.querySelectorAll("[data-w]"))
             node.textContent = words[node.dataset.w];
         const set = (selector, label) => this.#root.querySelector(selector)?.setAttribute("aria-label", label);
@@ -350,11 +406,14 @@ export class ViewControlsElement extends HTMLElement {
         set('[data-g="zoom"]', words.zoom);
         set('[data-g="pan"]', words.pan);
         set('[data-g="drag"]', words.drag);
+        set('[data-g="pace"]', words.speed);
         set('[data-b="left"]', words.panLeft);
         set('[data-b="right"]', words.panRight);
         set('[data-b="up"]', words.panUp);
         set('[data-b="down"]', words.panDown);
         this.#root.querySelector(".bar")?.setAttribute("lang", language);
+        if (this.#ready)
+            this.#show();
     }
     #show() {
         const c = this.#ensure();
@@ -369,15 +428,45 @@ export class ViewControlsElement extends HTMLElement {
         q('[data-b="play"]').setAttribute("aria-pressed", String(s.turning));
         q('[data-b="out"]').disabled = s.zoom <= c.limits.zoomMin + 1e-6;
         q('[data-b="in"]').disabled = s.zoom >= c.limits.zoomMax - 1e-6;
-        q('[data-g="pan"]').hidden = s.zoom <= ZOOMED;
+        const advanced = this.#level === "advanced";
+        const words = this.#labels;
+        const zoom = zoomText(s.zoom);
+        q('[data-o="zoom"]').textContent = zoom;
+        q('[data-b="level"]').setAttribute("aria-label", `${words.zoomLevel} ${zoom}, ${words.zoomReset}`);
+        this.#sayZoom(`${words.zoomLevel} ${zoom}`);
+        for (const pace of PACES)
+            q(`[data-b="${pace}"]`).setAttribute("aria-pressed", String(this.#pace === pace));
+        const more = q('[data-b="more"]');
+        more.setAttribute("aria-expanded", String(advanced));
+        this.dataset.level = this.#level;
+        for (const node of this.#root.querySelectorAll(".adv"))
+            node.hidden = !advanced;
+        q('[data-g="pan"]').hidden = !advanced || s.zoom <= ZOOMED;
         q('[data-b="move"]').setAttribute("aria-pressed", String(s.drag === "move"));
         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", ".tilt", ".play", ".front", '[data-g="drag"]'])
+        for (const selector of [".angle", ".play"])
             q(selector).hidden = flat;
+        for (const selector of [".tilt", ".front", '[data-g="drag"]', '[data-g="pace"]'])
+            q(selector).hidden = flat || !advanced;
         this.toggleAttribute("data-turning", s.turning);
     }
+    /** Tells a screen reader the zoom once it has settled for a moment (a pinch or a wheel makes many steps). */
+    #sayZoom(text) {
+        if (text === this.#said)
+            return;
+        const first = this.#said === "";
+        this.#said = text;
+        if (first)
+            return;
+        clearTimeout(this.#sayTimer);
+        this.#sayTimer = setTimeout(() => {
+            const live = this.#root.querySelector('[data-live]');
+            if (live !== null)
+                live.textContent = text;
+        }, 400);
+    }
     #changed(state, info) {
         if (!this.#ready)
             return;
@@ -393,7 +482,7 @@ export class ViewControlsElement extends HTMLElement {
     #save() {
         this.#writer.write((search) => {
             const s = this.#ensure().state;
-            return formatAddress(search, s, this.#keys, s.turning, this.#ensure().startZoom);
+            return formatAddress(search, { ...s, pace: this.#pace }, this.#keys, s.turning, this.#ensure().startZoom);
         });
     }
 }

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

@@ -4,3 +4,4 @@ export { clamp, clampPan, DEFAULT_LIMITS, dragTurn, PAN_STEP, pinchTo, TILT_ACRO
 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 { LEVEL_STORAGE_KEY, PACE_FACTOR, PACES, parseLevel, parsePace, zoomText, type Level, type Pace } from "./levels.ts";

package/dist/view-controls/index.js

@@ -5,3 +5,4 @@ export { clamp, clampPan, DEFAULT_LIMITS, dragTurn, PAN_STEP, pinchTo, TILT_ACRO
 export { languageOf, WORDS, wordsFor } from "./words.js";
 export const EVENT = "kazoku-viewchange";
 export const TAG = "kazoku-view-controls";
+export { LEVEL_STORAGE_KEY, PACE_FACTOR, PACES, parseLevel, parsePace, zoomText } from "./levels.js";

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

@@ -0,0 +1,12 @@
+/** `basic` is the default: turn, zoom, Fit and Auto-turn. `advanced` adds tilt, speed, Front, 2 times and the pan pad. */
+export type Level = "basic" | "advanced";
+export declare const parseLevel: (text: string | null | undefined) => Level | undefined;
+/** The localStorage key the level is remembered under, unless `storage` names another. */
+export declare const LEVEL_STORAGE_KEY = "kazoku-view-controls";
+/** Auto-turn speed: Medium is the element's `speed`, Slow half of it and Fast twice it. */
+export type Pace = "slow" | "medium" | "fast";
+export declare const PACES: readonly Pace[];
+export declare const PACE_FACTOR: Record<Pace, number>;
+export declare const parsePace: (text: string | null | undefined) => Pace | undefined;
+/** The zoom as the readout shows it: `1×`, `2.4×`. */
+export declare const zoomText: (zoom: number) => string;

package/dist/view-controls/levels.js

@@ -0,0 +1,9 @@
+// The controls' two levels and the auto-turn pace: pure, so a server or a test can use them.
+export const parseLevel = (text) => (text === "basic" || text === "advanced" ? text : undefined);
+/** The localStorage key the level is remembered under, unless `storage` names another. */
+export const LEVEL_STORAGE_KEY = "kazoku-view-controls";
+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);
+/** The zoom as the readout shows it: `1×`, `2.4×`. */
+export const zoomText = (zoom) => `${Number(zoom.toFixed(1))}×`;

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

@@ -1 +1 @@
-export declare const STYLES = "\n:host {\n  --_ink: var(--kazoku-ink, #1b1b1f);\n  --_surface: var(--kazoku-surface, #ffffff);\n  --_line: var(--kazoku-line, #c9ccd3);\n  --_accent: var(--kazoku-accent, #2457d6);\n  display: block;\n  box-sizing: border-box;\n  color: var(--_ink);\n  font: 600 0.9rem/1.2 system-ui, -apple-system, \"Hiragino Sans\", \"Noto Sans JP\", \"Segoe UI\", sans-serif;\n  color-scheme: light dark;\n}\n@media (prefers-color-scheme: dark) {\n  :host(:not([theme=\"light\"])) {\n    --_ink: var(--kazoku-ink, #f1f2f6);\n    --_surface: var(--kazoku-surface, #1c1d22);\n    --_line: var(--kazoku-line, #4a4d58);\n    --_accent: var(--kazoku-accent, #8fb0ff);\n  }\n}\n:host([theme=\"dark\"]) {\n  --_ink: var(--kazoku-ink, #f1f2f6);\n  --_surface: var(--kazoku-surface, #1c1d22);\n  --_line: var(--kazoku-line, #4a4d58);\n  --_accent: var(--kazoku-accent, #8fb0ff);\n  color-scheme: dark;\n}\n:host([theme=\"light\"]) { color-scheme: light; }\n:host([overlay]) { position: absolute; inset-inline: 0; bottom: 0; z-index: 1; }\n:host([overlay]) .bar { background: color-mix(in srgb, var(--_surface) 88%, transparent); }\n[hidden] { display: none !important; }\n.bar { display: flex; flex-wrap: wrap; align-items: center; gap: 4px 12px; padding: 4px 8px; box-sizing: border-box; }\n.field { display: flex; align-items: center; gap: 8px; flex: 1 1 200px; min-width: 0; }\n.field.tilt { flex-basis: 150px; }\n.field label { flex: none; }\n.field output { flex: none; min-width: 3.2em; text-align: end; font-variant-numeric: tabular-nums; }\n.group { display: inline-flex; align-items: center; flex-wrap: wrap; gap: 4px; }\n.vh { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }\ninput[type=\"range\"] { -webkit-appearance: none; appearance: none; flex: 1 1 auto; width: 100%; min-width: 60px; height: 48px; margin: 0; padding: 0; background: transparent; cursor: pointer; }\ninput[type=\"range\"]::-webkit-slider-runnable-track { height: 6px; border-radius: 3px; background: var(--_line); }\ninput[type=\"range\"]::-moz-range-track { height: 6px; border-radius: 3px; background: var(--_line); }\ninput[type=\"range\"]::-webkit-slider-thumb { -webkit-appearance: none; appearance: none; width: 28px; height: 28px; margin-top: -11px; border-radius: 50%; background: var(--_accent); border: 3px solid var(--_surface); box-shadow: 0 0 0 1px var(--_ink); }\ninput[type=\"range\"]::-moz-range-thumb { width: 22px; height: 22px; border-radius: 50%; background: var(--_accent); border: 3px solid var(--_surface); box-shadow: 0 0 0 1px var(--_ink); }\ninput[type=\"range\"]:focus-visible { outline: 2px solid var(--_ink); outline-offset: -4px; border-radius: 8px; }\nbutton { -webkit-appearance: none; appearance: none; box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center; gap: 6px; min-width: 48px; min-height: 48px; margin: 0; padding: 0 14px; border: 1px solid var(--_line); border-radius: 24px; background: var(--_surface); color: var(--_ink); font: inherit; cursor: pointer; white-space: nowrap; }\nbutton:hover:not(:disabled) { border-color: var(--_ink); }\nbutton:focus-visible { outline: 2px solid var(--_ink); outline-offset: 2px; }\nbutton[aria-pressed=\"true\"] { background: var(--_ink); color: var(--_surface); border-color: var(--_ink); }\nbutton:disabled { opacity: 0.4; cursor: default; }\nsvg { width: 18px; height: 18px; fill: currentColor; flex: none; }\nbutton[aria-pressed=\"true\"] .i-play, button[aria-pressed=\"false\"] .i-pause { display: none; }\n.zoom button.two { min-width: 56px; }\n.drag { margin-inline-start: 8px; }\n/* A compact bar on a phone: three rows (angle, tilt and zoom, the pad when zoomed), labels read only by a screen reader. */\n@media (max-width: 640px) {\n  .bar { display: grid; grid-template-columns: minmax(0, 1fr) 48px auto; grid-template-areas: \"angle play front\" \"tilt zoom zoom\" \"pan pan pan\"; gap: 0 8px; padding: 2px 8px; }\n  .field.angle { grid-area: angle; }\n  .field.tilt { grid-area: tilt; }\n  .field label, .field output { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }\n  .play { grid-area: play; padding: 0; }\n  .play .text { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }\n  .front { grid-area: front; padding: 0 12px; }\n  .zoom { grid-area: zoom; justify-self: end; flex-wrap: nowrap; }\n  .zoom button { padding: 0 8px; }\n  .pan { grid-area: pan; justify-content: center; }\n  .drag { margin-inline-start: 4px; }\n}\n";
+export declare const STYLES = "\n:host {\n  --_ink: var(--kazoku-ink, #1b1b1f);\n  --_surface: var(--kazoku-surface, #ffffff);\n  --_line: var(--kazoku-line, #c9ccd3);\n  --_accent: var(--kazoku-accent, #2457d6);\n  display: block;\n  box-sizing: border-box;\n  color: var(--_ink);\n  font: 600 0.9rem/1.2 system-ui, -apple-system, \"Hiragino Sans\", \"Noto Sans JP\", \"Segoe UI\", sans-serif;\n  color-scheme: light dark;\n}\n@media (prefers-color-scheme: dark) {\n  :host(:not([theme=\"light\"])) {\n    --_ink: var(--kazoku-ink, #f1f2f6);\n    --_surface: var(--kazoku-surface, #1c1d22);\n    --_line: var(--kazoku-line, #4a4d58);\n    --_accent: var(--kazoku-accent, #8fb0ff);\n  }\n}\n:host([theme=\"dark\"]) {\n  --_ink: var(--kazoku-ink, #f1f2f6);\n  --_surface: var(--kazoku-surface, #1c1d22);\n  --_line: var(--kazoku-line, #4a4d58);\n  --_accent: var(--kazoku-accent, #8fb0ff);\n  color-scheme: dark;\n}\n:host([theme=\"light\"]) { color-scheme: light; }\n:host([overlay]) { position: absolute; inset-inline: 0; bottom: 0; z-index: 1; }\n:host([overlay]) .bar { background: color-mix(in srgb, var(--_surface) 88%, transparent); }\n[hidden] { display: none !important; }\n.bar { display: flex; flex-wrap: wrap; align-items: center; gap: 4px 12px; padding: 4px 8px; box-sizing: border-box; }\n.field { display: flex; align-items: center; gap: 8px; flex: 1 1 200px; min-width: 0; }\n.field.tilt { flex-basis: 150px; }\n.field label { flex: none; }\n.field output { flex: none; min-width: 3.2em; text-align: end; font-variant-numeric: tabular-nums; }\n.group { display: inline-flex; align-items: center; flex-wrap: wrap; gap: 4px; }\n.vh { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }\ninput[type=\"range\"] { -webkit-appearance: none; appearance: none; flex: 1 1 auto; width: 100%; min-width: 60px; height: 48px; margin: 0; padding: 0; background: transparent; cursor: pointer; }\ninput[type=\"range\"]::-webkit-slider-runnable-track { height: 6px; border-radius: 3px; background: var(--_line); }\ninput[type=\"range\"]::-moz-range-track { height: 6px; border-radius: 3px; background: var(--_line); }\ninput[type=\"range\"]::-webkit-slider-thumb { -webkit-appearance: none; appearance: none; width: 28px; height: 28px; margin-top: -11px; border-radius: 50%; background: var(--_accent); border: 3px solid var(--_surface); box-shadow: 0 0 0 1px var(--_ink); }\ninput[type=\"range\"]::-moz-range-thumb { width: 22px; height: 22px; border-radius: 50%; background: var(--_accent); border: 3px solid var(--_surface); box-shadow: 0 0 0 1px var(--_ink); }\ninput[type=\"range\"]:focus-visible { outline: 2px solid var(--_ink); outline-offset: -4px; border-radius: 8px; }\nbutton { -webkit-appearance: none; appearance: none; box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center; gap: 6px; min-width: 48px; min-height: 48px; margin: 0; padding: 0 14px; border: 1px solid var(--_line); border-radius: 24px; background: var(--_surface); color: var(--_ink); font: inherit; cursor: pointer; white-space: nowrap; }\nbutton:hover:not(:disabled) { border-color: var(--_ink); }\nbutton:focus-visible { outline: 2px solid var(--_ink); outline-offset: 2px; }\nbutton[aria-pressed=\"true\"] { background: var(--_ink); color: var(--_surface); border-color: var(--_ink); }\nbutton[aria-expanded=\"true\"] { border-color: var(--_ink); box-shadow: inset 0 0 0 1px var(--_ink); }\nbutton:disabled { opacity: 0.4; cursor: default; }\nsvg { width: 18px; height: 18px; fill: currentColor; flex: none; }\nbutton[aria-pressed=\"true\"] .i-play, button[aria-pressed=\"false\"] .i-pause { display: none; }\n.zoom button.two { min-width: 56px; }\n.zoom button.level { min-width: 64px; padding: 0 8px; font-variant-numeric: tabular-nums; }\n.pace .lbl { margin-inline-end: 4px; }\n.drag { margin-inline-start: 8px; }\n.more { margin-inline-start: auto; }\n/* A compact bar on a phone: two rows to start with (angle, Auto-turn and More; the zoom), more rows when the reader asks for more; labels read only by a screen reader. */\n@media (max-width: 640px) {\n  .bar { display: grid; grid-template-columns: minmax(0, 1fr) 48px 48px; grid-template-areas: \"angle play more\" \"tilt tilt front\" \"pace pace pace\" \"zoom zoom zoom\" \"pan pan pan\"; gap: 0 8px; padding: 2px 8px; }\n  .field.angle { grid-area: angle; }\n  .field.tilt { grid-area: tilt; }\n  .field label, .field output, .play .text, .more .text, .pace .lbl { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }\n  .play, .more { padding: 0; }\n  .play { grid-area: play; }\n  .more { grid-area: more; }\n  .front { grid-area: front; padding: 0 12px; }\n  .pace { grid-area: pace; justify-self: end; flex-wrap: nowrap; }\n  .pace button { padding: 0 12px; }\n  .zoom { grid-area: zoom; justify-self: end; flex-wrap: nowrap; }\n  .zoom button { padding: 0 8px; }\n  .zoom button.level { padding: 0 6px; }\n  .pan { grid-area: pan; justify-content: center; }\n  .drag { margin-inline-start: 4px; }\n}\n";

package/dist/view-controls/styles.js

@@ -48,22 +48,30 @@ button { -webkit-appearance: none; appearance: none; box-sizing: border-box; dis
 button:hover:not(:disabled) { border-color: var(--_ink); }
 button:focus-visible { outline: 2px solid var(--_ink); outline-offset: 2px; }
 button[aria-pressed="true"] { background: var(--_ink); color: var(--_surface); border-color: var(--_ink); }
+button[aria-expanded="true"] { border-color: var(--_ink); box-shadow: inset 0 0 0 1px var(--_ink); }
 button:disabled { opacity: 0.4; cursor: default; }
 svg { width: 18px; height: 18px; fill: currentColor; flex: none; }
 button[aria-pressed="true"] .i-play, button[aria-pressed="false"] .i-pause { display: none; }
 .zoom button.two { min-width: 56px; }
+.zoom button.level { min-width: 64px; padding: 0 8px; font-variant-numeric: tabular-nums; }
+.pace .lbl { margin-inline-end: 4px; }
 .drag { margin-inline-start: 8px; }
-/* A compact bar on a phone: three rows (angle, tilt and zoom, the pad when zoomed), labels read only by a screen reader. */
+.more { margin-inline-start: auto; }
+/* A compact bar on a phone: two rows to start with (angle, Auto-turn and More; the zoom), more rows when the reader asks for more; labels read only by a screen reader. */
 @media (max-width: 640px) {
-  .bar { display: grid; grid-template-columns: minmax(0, 1fr) 48px auto; grid-template-areas: "angle play front" "tilt zoom zoom" "pan pan pan"; gap: 0 8px; padding: 2px 8px; }
+  .bar { display: grid; grid-template-columns: minmax(0, 1fr) 48px 48px; grid-template-areas: "angle play more" "tilt tilt front" "pace pace pace" "zoom zoom zoom" "pan pan pan"; gap: 0 8px; padding: 2px 8px; }
   .field.angle { grid-area: angle; }
   .field.tilt { grid-area: tilt; }
-  .field label, .field output { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
-  .play { grid-area: play; padding: 0; }
-  .play .text { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
+  .field label, .field output, .play .text, .more .text, .pace .lbl { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
+  .play, .more { padding: 0; }
+  .play { grid-area: play; }
+  .more { grid-area: more; }
   .front { grid-area: front; padding: 0 12px; }
+  .pace { grid-area: pace; justify-self: end; flex-wrap: nowrap; }
+  .pace button { padding: 0 12px; }
   .zoom { grid-area: zoom; justify-self: end; flex-wrap: nowrap; }
   .zoom button { padding: 0 8px; }
+  .zoom button.level { padding: 0 6px; }
   .pan { grid-area: pan; justify-content: center; }
   .drag { margin-inline-start: 4px; }
 }

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

@@ -17,6 +17,13 @@ export interface ViewWords {
     drag: string;
     dragMove: string;
     dragTurn: string;
+    zoomLevel: string;
+    zoomReset: string;
+    more: string;
+    speed: string;
+    slow: string;
+    medium: string;
+    fast: string;
 }
 export type Language = "en" | "ja";
 export declare const WORDS: Record<Language, ViewWords>;

package/dist/view-controls/words.js

@@ -19,6 +19,13 @@ export const WORDS = {
         drag: "What a drag does",
         dragMove: "Move",
         dragTurn: "Turn",
+        zoomLevel: "Zoom level",
+        zoomReset: "back to Fit",
+        more: "More",
+        speed: "Speed",
+        slow: "Slow",
+        medium: "Medium",
+        fast: "Fast",
     },
     ja: {
         group: "表示の操作",
@@ -39,6 +46,13 @@ export const WORDS = {
         drag: "ドラッグの動作",
         dragMove: "移動",
         dragTurn: "回転",
+        zoomLevel: "ズーム倍率",
+        zoomReset: "全体に戻す",
+        more: "詳細",
+        speed: "速さ",
+        slow: "ゆっくり",
+        medium: "ふつう",
+        fast: "はやい",
     },
 };
 /** The language to use for a `lang` value such as "ja", "ja-JP" or "en-CA": Japanese for ja, English for anything else. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@johnmorrisdotca/kazoku-ui",
-  "version": "0.7.2",
-  "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.",
+  "version": "0.9.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",
     "3d",
@@ -26,7 +26,11 @@
     "save-image",
     "png",
     "svg",
-    "download"
+    "download",
+    "webgl",
+    "three",
+    "three.js",
+    "renderer"
   ],
   "homepage": "https://johnmorrisdotca.github.io/kazoku-ui/",
   "repository": {
@@ -118,6 +122,16 @@
       "types": "./dist/save-image/define.d.ts",
       "import": "./dist/save-image/define.js",
       "default": "./dist/save-image/define.js"
+    },
+    "./renderer": {
+      "types": "./dist/renderer/index.d.ts",
+      "import": "./dist/renderer/index.js",
+      "default": "./dist/renderer/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
     }
   },
   "files": [
@@ -129,6 +143,14 @@
   "engines": {
     "node": ">=22"
   },
+  "peerDependencies": {
+    "three": ">=0.160.0"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
     "lint": "eslint .",
@@ -147,6 +169,7 @@
     "@playwright/test": "^1.63.0",
     "@types/node": "^24.0.0",
     "eslint": "^9.0.0",
+    "three": "0.186.1",
     "typescript": "^5.9.0",
     "typescript-eslint": "^8.0.0"
   },