@johnmorrisdotca/kazoku-ui 0.3.0 → 0.7.2

package/dist/theme-switch/element.js

@@ -0,0 +1,203 @@
+// <kazoku-theme-switch>: Light, Dark and Auto as a row of buttons. It writes the choice as `data-theme` on a target (the page's <html> by default; `auto` removes it),
+// keeps it in the address and, if asked, in localStorage, and tells the page with a `kazoku-themechange` event. It draws nothing of the page: the page's CSS reads `data-theme`.
+import { createAddressState } from "../address-state/address.js";
+import { adoptStyles } from "../shared/adopt.js";
+import { watchScheme } from "../shared/scheme.js";
+import { localStore, remember } from "../shared/store.js";
+import { resolveTarget } from "../shared/target.js";
+import { EVENT, TAG } from "./index.js";
+import { STYLES } from "./styles.js";
+import { applyTheme, parseModes, parseTheme, readTheme, resolveTheme, THEME_ADDRESS_KEY, THEME_STORAGE_KEY, themeOf } from "./theme.js";
+import { languageOf, wordsFor } from "./words.js";
+export { EVENT, TAG };
+const icon = (body) => `<svg viewBox="0 0 24 24" aria-hidden="true">${body}</svg>`;
+const ICON = {
+    light: icon('<path d="M12 7a5 5 0 1 0 0 10 5 5 0 0 0 0-10zM11 1h2v3h-2zM11 20h2v3h-2zM1 11h3v2H1zM20 11h3v2h-3zM4.2 5.6l1.4-1.4 2.1 2.1-1.4 1.4zM16.3 17.7l1.4-1.4 2.1 2.1-1.4 1.4zM5.6 19.8l-1.4-1.4 2.1-2.1 1.4 1.4zM17.7 7.7l-1.4-1.4 2.1-2.1 1.4 1.4z"/>'),
+    dark: icon('<path d="M20 14.5A8.5 8.5 0 0 1 9.5 4 8.5 8.5 0 1 0 20 14.5z"/>'),
+    auto: icon('<circle cx="12" cy="12" r="8.5" fill="none" stroke="currentColor" stroke-width="2"/><path d="M12 3.5a8.5 8.5 0 0 0 0 17z"/>'),
+};
+/**
+ * Attributes: `value` (`light`, `dark` or `auto`; the choice), `target` (a CSS selector for the element that gets `data-theme`; the page's <html> by default),
+ * `modes` (which buttons: `light dark` leaves Auto out), `address` (keep the choice in `?theme=`, or the key `address-key` names), `storage` (also remember it in
+ * localStorage under that key; a bare `storage` uses `kazoku-theme`), `lang` (`en` or `ja`), `theme` (`light` or `dark`: its own look, otherwise the page's).
+ * The choice is read, in this order, from the address, the store, `value`, then what the target already holds.
+ */
+export class ThemeSwitchElement extends HTMLElement {
+    static observedAttributes = ["value", "target", "modes", "lang"];
+    #root;
+    #choice = "auto";
+    #target;
+    #words = {};
+    #ready = false;
+    #styled = false;
+    #address = createAddressState({ delay: 0 });
+    #stop = [];
+    #watching;
+    constructor() {
+        super();
+        this.#root = this.attachShadow({ mode: "open" });
+    }
+    /** The choice now: `light`, `dark` or `auto`. Setting it applies it (event reason `set`). */
+    get value() {
+        return this.#choice;
+    }
+    set value(next) {
+        const theme = parseTheme(next);
+        if (theme !== undefined)
+            this.#choose(theme, "set");
+    }
+    /** The colours showing now: `light` or `dark`. */
+    get scheme() {
+        return resolveTheme(this.#choice, this.#prefersDark());
+    }
+    /** The element the choice is written on. */
+    get target() {
+        return this.#target;
+    }
+    set target(element) {
+        this.#aim(element);
+    }
+    /** Your own labels over the language's, for example `{ auto: "System" }`. */
+    set words(words) {
+        this.#words = words;
+        this.#render();
+    }
+    connectedCallback() {
+        if (!this.#styled) {
+            adoptStyles(this.#root, STYLES, this.nonce);
+            this.#styled = true;
+        }
+        this.#stop.push(watchScheme(this));
+        this.#resolveTarget();
+        const target = this.#target;
+        const remembered = readTheme({
+            ...(this.hasAttribute("address") ? { search: globalThis.location?.search ?? "", addressKey: this.#addressKey() } : {}),
+            ...(this.hasAttribute("storage") ? { storage: localStore(), storageKey: this.#storageKey() } : {}),
+        });
+        this.#choice = remembered ?? parseTheme(this.getAttribute("value")) ?? (target !== undefined && target.hasAttribute("data-theme") ? themeOf(target) : "auto");
+        if (target !== undefined)
+            applyTheme(target, this.#choice);
+        this.#render();
+        const media = globalThis.matchMedia?.("(prefers-color-scheme: dark)");
+        const onSystem = () => {
+            if (this.#choice === "auto")
+                this.#dispatch("system");
+        };
+        media?.addEventListener("change", onSystem);
+        this.#stop.push(() => media?.removeEventListener("change", onSystem));
+        this.#ready = true;
+        // Said once the page has had its turn to listen; `value` can be read at any time.
+        queueMicrotask(() => {
+            if (this.isConnected)
+                this.#dispatch("init");
+        });
+    }
+    disconnectedCallback() {
+        for (const stop of this.#stop.splice(0))
+            stop();
+        this.#watching?.disconnect();
+        this.#watching = undefined;
+        this.#ready = false;
+    }
+    attributeChangedCallback(name, _old, value) {
+        if (!this.#ready)
+            return;
+        if (name === "value") {
+            const theme = parseTheme(value);
+            if (theme !== undefined)
+                this.#choose(theme, "set");
+        }
+        else if (name === "target") {
+            this.#resolveTarget();
+            if (this.#target !== undefined)
+                applyTheme(this.#target, this.#choice);
+        }
+        else
+            this.#render();
+    }
+    #addressKey() {
+        return this.getAttribute("address-key") || THEME_ADDRESS_KEY;
+    }
+    #storageKey() {
+        return this.getAttribute("storage") || THEME_STORAGE_KEY;
+    }
+    #prefersDark() {
+        return globalThis.matchMedia?.("(prefers-color-scheme: dark)").matches === true;
+    }
+    #resolveTarget() {
+        this.#aim(resolveTarget(this, this.getAttribute("target")));
+    }
+    #aim(element) {
+        if (element === this.#target)
+            return;
+        this.#watching?.disconnect();
+        this.#target = element;
+        if (element === undefined)
+            return;
+        // Something else writing the target's data-theme (a page's own button, another switch) moves this one with it.
+        this.#watching = new MutationObserver(() => {
+            const held = themeOf(element);
+            if (held !== this.#choice) {
+                this.#choice = held;
+                this.#render();
+                this.#dispatch("external");
+            }
+        });
+        this.#watching.observe(element, { attributes: true, attributeFilter: ["data-theme"] });
+    }
+    #choose(theme, reason) {
+        if (this.#target !== undefined)
+            applyTheme(this.#target, theme);
+        const changed = theme !== this.#choice;
+        this.#choice = theme;
+        this.#render();
+        if (this.hasAttribute("address"))
+            this.#address.set(this.#addressKey(), theme === "auto" ? null : theme);
+        if (this.hasAttribute("storage")) {
+            remember(this.#storageKey(), theme);
+        }
+        if (changed || reason === "user")
+            this.#dispatch(reason);
+    }
+    #language() {
+        return languageOf(this.getAttribute("lang") ?? this.closest("[lang]")?.getAttribute("lang") ?? this.ownerDocument.documentElement.lang);
+    }
+    #render() {
+        const language = this.#language();
+        const words = wordsFor(language, this.#words);
+        const modes = parseModes(this.getAttribute("modes"));
+        let group = this.#root.querySelector(".group");
+        if (group === null) {
+            group = this.ownerDocument.createElement("div");
+            group.className = "group";
+            group.setAttribute("part", "group");
+            group.setAttribute("role", "group");
+            this.#root.append(group);
+        }
+        group.setAttribute("aria-label", words.group);
+        group.setAttribute("lang", language);
+        const have = [...group.querySelectorAll("button")];
+        if (have.length !== modes.length || have.some((button, index) => button.dataset.v !== modes[index])) {
+            group.replaceChildren(...modes.map((mode) => {
+                const button = this.ownerDocument.createElement("button");
+                button.type = "button";
+                button.dataset.v = mode;
+                button.setAttribute("part", "button");
+                button.innerHTML = `${ICON[mode]}<span class="t"></span>`;
+                button.addEventListener("click", () => this.#choose(mode, "user"));
+                return button;
+            }));
+        }
+        for (const button of group.querySelectorAll("button")) {
+            const mode = button.dataset.v;
+            button.querySelector(".t").textContent = words[mode];
+            button.setAttribute("aria-pressed", String(mode === this.#choice));
+        }
+    }
+    #dispatch(reason) {
+        if (this.#target === undefined)
+            return;
+        const detail = { choice: this.#choice, scheme: this.scheme, reason, target: this.#target };
+        this.dispatchEvent(new CustomEvent(EVENT, { detail, bubbles: true, composed: true }));
+    }
+}

package/dist/theme-switch/index.d.ts

@@ -0,0 +1,4 @@
+export { applyTheme, parseModes, parseTheme, readTheme, resolveTheme, THEME_ADDRESS_KEY, THEME_ATTRIBUTE, THEME_STORAGE_KEY, themeOf, THEMES, type RememberedTheme, type Scheme, type Theme } from "./theme.ts";
+export { languageOf, WORDS, wordsFor, type Language, type ThemeWords } from "./words.ts";
+export declare const EVENT = "kazoku-themechange";
+export declare const TAG = "kazoku-theme-switch";

package/dist/theme-switch/index.js

@@ -0,0 +1,5 @@
+// The theme switch without the element: the choices, how one is applied and where one is remembered. Nothing here touches the DOM until `applyTheme` is called with an element.
+export { applyTheme, parseModes, parseTheme, readTheme, resolveTheme, THEME_ADDRESS_KEY, THEME_ATTRIBUTE, THEME_STORAGE_KEY, themeOf, THEMES } from "./theme.js";
+export { languageOf, WORDS, wordsFor } from "./words.js";
+export const EVENT = "kazoku-themechange";
+export const TAG = "kazoku-theme-switch";

package/dist/theme-switch/styles.d.ts

@@ -0,0 +1 @@
+export declare const STYLES = "\n:host {\n  --_ink: var(--kazoku-ink, #1b1b1f);\n  --_surface: var(--kazoku-surface, #ffffff);\n  --_line: var(--kazoku-line, #c9ccd3);\n  --_accent: var(--kazoku-accent, #2457d6);\n  display: inline-block;\n  box-sizing: border-box;\n  color: var(--_ink);\n  font: 600 0.9rem/1.2 system-ui, -apple-system, \"Hiragino Sans\", \"Noto Sans JP\", \"Segoe UI\", sans-serif;\n  color-scheme: light dark;\n}\n@media (prefers-color-scheme: dark) {\n  :host(:not([theme=\"light\"]):not([data-scheme=\"light\"])) {\n    --_ink: var(--kazoku-ink, #f1f2f6);\n    --_surface: var(--kazoku-surface, #1c1d22);\n    --_line: var(--kazoku-line, #4a4d58);\n    --_accent: var(--kazoku-accent, #8fb0ff);\n  }\n}\n:host([theme=\"dark\"]), :host([data-scheme=\"dark\"]:not([theme=\"light\"])) {\n  --_ink: var(--kazoku-ink, #f1f2f6);\n  --_surface: var(--kazoku-surface, #1c1d22);\n  --_line: var(--kazoku-line, #4a4d58);\n  --_accent: var(--kazoku-accent, #8fb0ff);\n  color-scheme: dark;\n}\n:host([theme=\"light\"]) { color-scheme: light; }\n[hidden] { display: none !important; }\n.vh { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }\n.group { display: inline-flex; align-items: center; flex-wrap: wrap; gap: 4px; }\nbutton { -webkit-appearance: none; appearance: none; box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center; gap: 6px; min-width: 48px; min-height: 48px; margin: 0; padding: 0 14px; border: 1px solid var(--_line); border-radius: 24px; background: var(--_surface); color: var(--_ink); font: inherit; cursor: pointer; white-space: nowrap; }\nbutton:hover:not(:disabled) { border-color: var(--_ink); }\nbutton:focus-visible { outline: 2px solid var(--_ink); outline-offset: 2px; }\nbutton[aria-pressed=\"true\"] { background: var(--_ink); color: var(--_surface); border-color: var(--_ink); }\nbutton:disabled { opacity: 0.4; cursor: default; }\nsvg { width: 18px; height: 18px; fill: currentColor; flex: none; }\n\n@media (max-width: 640px) {\n  .t { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }\n  button { padding: 0; }\n}\n";

package/dist/theme-switch/styles.js

@@ -0,0 +1,8 @@
+import { BASE_STYLES } from "../shared/base.js";
+// Light, Dark and Auto as one row of buttons. On a phone the words are left to a screen reader and the icons stay.
+export const STYLES = `${BASE_STYLES}
+@media (max-width: 640px) {
+  .t { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
+  button { padding: 0; }
+}
+`;

package/dist/theme-switch/theme.d.ts

@@ -0,0 +1,29 @@
+export declare const THEMES: readonly ["light", "dark", "auto"];
+export type Theme = (typeof THEMES)[number];
+export type Scheme = "light" | "dark";
+/** The attribute the choice is written to on the target. `auto` removes it, so the page's own `prefers-color-scheme` rules decide. */
+export declare const THEME_ATTRIBUTE = "data-theme";
+/** The address parameter, with `address`. */
+export declare const THEME_ADDRESS_KEY = "theme";
+/** The localStorage key, with a bare `storage`. */
+export declare const THEME_STORAGE_KEY = "kazoku-theme";
+export declare const parseTheme: (value: unknown) => Theme | undefined;
+/** The colours a choice gives: light and dark are themselves, auto is the device's. */
+export declare const resolveTheme: (choice: Theme, prefersDark: boolean) => Scheme;
+/** The choices a switch offers, from `modes="light dark"`: the known ones, once each, in the order light, dark, auto. Nothing usable gives all three. */
+export declare function parseModes(value: string | null | undefined): Theme[];
+/** What a target holds now: `light` or `dark` when forced, `auto` when it says nothing or something else. */
+export declare const themeOf: (target: Element) => Theme;
+/** Writes the choice on the target (`data-theme="light"`, `"dark"`, or no attribute for auto). */
+export declare function applyTheme(target: Element, choice: Theme): void;
+/** Where a remembered choice may be read from. A page that keeps nothing passes neither. */
+export interface RememberedTheme {
+    /** An address' search string such as `?theme=dark`, read with `addressKey`. */
+    search?: string;
+    addressKey?: string;
+    /** A localStorage-like object and the key in it. A store that throws is the same as an empty one. */
+    storage?: Pick<Storage, "getItem">;
+    storageKey?: string;
+}
+/** The remembered choice: the address first, then the store. `undefined` when neither holds a valid one. */
+export declare function readTheme(from: RememberedTheme): Theme | undefined;

package/dist/theme-switch/theme.js

@@ -0,0 +1,43 @@
+// The theme choice without the element: the three choices, what each means, and how a choice is applied to a page. Nothing here touches the DOM until a function is called with an element.
+export const THEMES = ["light", "dark", "auto"];
+/** The attribute the choice is written to on the target. `auto` removes it, so the page's own `prefers-color-scheme` rules decide. */
+export const THEME_ATTRIBUTE = "data-theme";
+/** The address parameter, with `address`. */
+export const THEME_ADDRESS_KEY = "theme";
+/** The localStorage key, with a bare `storage`. */
+export const THEME_STORAGE_KEY = "kazoku-theme";
+export const parseTheme = (value) => THEMES.includes(value) ? value : undefined;
+/** The colours a choice gives: light and dark are themselves, auto is the device's. */
+export const resolveTheme = (choice, prefersDark) => (choice === "auto" ? (prefersDark ? "dark" : "light") : choice);
+/** The choices a switch offers, from `modes="light dark"`: the known ones, once each, in the order light, dark, auto. Nothing usable gives all three. */
+export function parseModes(value) {
+    const named = new Set((value ?? "").split(/[\s,]+/).map((word) => parseTheme(word.toLowerCase())));
+    const kept = THEMES.filter((theme) => named.has(theme));
+    return kept.length > 0 ? kept : [...THEMES];
+}
+/** What a target holds now: `light` or `dark` when forced, `auto` when it says nothing or something else. */
+export const themeOf = (target) => parseTheme(target.getAttribute(THEME_ATTRIBUTE)) ?? "auto";
+/** Writes the choice on the target (`data-theme="light"`, `"dark"`, or no attribute for auto). */
+export function applyTheme(target, choice) {
+    if (choice === "auto")
+        target.removeAttribute(THEME_ATTRIBUTE);
+    else
+        target.setAttribute(THEME_ATTRIBUTE, choice);
+}
+/** The remembered choice: the address first, then the store. `undefined` when neither holds a valid one. */
+export function readTheme(from) {
+    if (from.search !== undefined) {
+        const asked = parseTheme(new URLSearchParams(from.search).get(from.addressKey ?? THEME_ADDRESS_KEY));
+        if (asked !== undefined)
+            return asked;
+    }
+    if (from.storage !== undefined) {
+        try {
+            return parseTheme(from.storage.getItem(from.storageKey ?? THEME_STORAGE_KEY));
+        }
+        catch {
+            /* a browser that keeps nothing */
+        }
+    }
+    return undefined;
+}

package/dist/theme-switch/words.d.ts

@@ -0,0 +1,11 @@
+export interface ThemeWords {
+    group: string;
+    light: string;
+    dark: string;
+    auto: string;
+}
+export type Language = "en" | "ja";
+export declare const WORDS: Record<Language, ThemeWords>;
+/** The language to use for a `lang` value such as "ja", "ja-JP" or "en-CA": Japanese for ja, English for anything else. */
+export declare const languageOf: (lang: string | null | undefined) => Language;
+export declare const wordsFor: (language: Language, overrides?: Partial<ThemeWords>) => ThemeWords;

package/dist/theme-switch/words.js

@@ -0,0 +1,7 @@
+export const WORDS = {
+    en: { group: "Colour theme", light: "Light", dark: "Dark", auto: "Auto" },
+    ja: { group: "テーマ", light: "ライト", dark: "ダーク", auto: "自動" },
+};
+/** The language to use for a `lang` value such as "ja", "ja-JP" or "en-CA": Japanese for ja, English for anything else. */
+export const languageOf = (lang) => (/^ja\b/i.test(lang ?? "") ? "ja" : "en");
+export const wordsFor = (language, overrides = {}) => ({ ...WORDS[language], ...overrides });

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

@@ -68,9 +68,14 @@ export interface ViewController {
     /** 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;
+    /** Turn by itself. With `seconds`, stop by itself (as `pause`) after that many seconds of turning; time spent suspended does not count. `toggle` and a bare `play()` turn without a limit. */
+    play(seconds?: number): void;
     pause(): void;
     toggle(): void;
+    /** Stop the frame loop while nothing can see the view (it is off screen, the tab is hidden): no frames are asked for and no "auto" change is sent. `state.turning` stays true. Counts, so suspends nest. */
+    suspendTurn(): void;
+    /** Undo one `suspendTurn`; the turn goes on from where it was when the last one is undone. */
+    resumeTurn(): void;
     /** Hold the automatic turn still while a hand (a slider being dragged) has the angle; `releaseTurn` lets it carry on from where the hand left it. Counts, so holds nest. */
     holdTurn(): void;
     releaseTurn(): void;

package/dist/view-controls/controller.js

@@ -12,6 +12,9 @@ export function createViewController(options = {}) {
     let frame = 0;
     let last = 0;
     let holds = 0;
+    let suspends = 0;
+    let limit = 0;
+    let turned = 0;
     let fitScale = positive(options.fitScale) ?? 1;
     let start = positive(options.zoom) ?? "fit";
     let atStart = true;
@@ -62,7 +65,7 @@ export function createViewController(options = {}) {
         return { x: at.x - c.x, y: at.y - c.y };
     };
     const tick = (now) => {
-        if (!state.turning)
+        if (!state.turning || suspends > 0)
             return;
         frame = clock.request(tick);
         if (holds > 0) {
@@ -74,7 +77,10 @@ export function createViewController(options = {}) {
         if (dt === 0)
             return;
         state.yaw = wrapYaw(state.yaw + controller.speed * dt);
+        turned += dt;
         emit(false, "auto");
+        if (limit > 0 && turned >= limit)
+            controller.pause();
     };
     const controller = {
         state,
@@ -125,12 +131,15 @@ export function createViewController(options = {}) {
             }
             emit(final, reason);
         },
-        play() {
+        play(seconds) {
             if (state.turning || !controller.turnable)
                 return;
             state.turning = true;
             last = 0;
-            frame = clock.request(tick);
+            turned = 0;
+            limit = positive(seconds) ?? 0;
+            if (suspends === 0)
+                frame = clock.request(tick);
             emit(true, "play");
         },
         pause() {
@@ -146,6 +155,20 @@ export function createViewController(options = {}) {
             else
                 controller.play();
         },
+        suspendTurn() {
+            suspends += 1;
+            if (suspends === 1)
+                clock.cancel(frame);
+        },
+        resumeTurn() {
+            if (suspends === 0)
+                return;
+            suspends -= 1;
+            if (suspends > 0 || !state.turning)
+                return;
+            last = 0;
+            frame = clock.request(tick);
+        },
         holdTurn() {
             holds += 1;
         },

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

@@ -11,7 +11,7 @@ export interface ViewChangeDetail extends ViewState {
 /**
  * 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),
+ * 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),
  * `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

@@ -1,5 +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 { createAddressWriter } from "../address-state/address.js";
+import { adoptStyles } from "../shared/adopt.js";
 import { DEFAULT_KEYS, formatAddress, parseAddress, parseKeys } from "./address.js";
 import { createViewController, DEFAULT_IGNORE } from "./controller.js";
 import { EVENT, TAG } from "./index.js";
@@ -44,7 +46,7 @@ const HTML = `
 /**
  * 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),
+ * 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),
  * `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).
@@ -58,8 +60,11 @@ export class ViewControlsElement extends HTMLElement {
     #words = {};
     #ready = false;
     #sliderHeld = 0;
-    #saveTimer = 0;
+    #writer = createAddressWriter({ delay: 250 });
     #keys = DEFAULT_KEYS;
+    #seen;
+    #onScreen = true;
+    #suspended = false;
     constructor() {
         super();
         this.#root = this.attachShadow({ mode: "open" });
@@ -145,25 +150,30 @@ export class ViewControlsElement extends HTMLElement {
             this.ownerDocument.addEventListener("DOMContentLoaded", () => this.#resolveView(), { once: true });
         this.#ready = true;
         this.#show();
+        this.ownerDocument.addEventListener("visibilitychange", this.#sight);
+        this.#watch();
         // Said once the page has had its turn to listen; a page can also read `state` at any time.
         queueMicrotask(() => {
             if (!this.isConnected)
                 return;
             this.#dispatch(c.state, { final: true, reason: "init" });
             if (this.hasAttribute("autoplay") && !globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches)
-                c.play();
+                c.play(Number(this.getAttribute("autoplay-for")));
         });
     }
     disconnectedCallback() {
+        this.ownerDocument.removeEventListener("visibilitychange", this.#sight);
+        this.#seen?.disconnect();
+        this.#seen = undefined;
+        this.#suspended = false;
+        this.#onScreen = true;
         this.#unbind?.();
         this.#unbind = undefined;
         this.#controller?.destroy();
         this.#controller = undefined;
         this.#view = undefined;
         this.#ready = false;
-        if (this.#saveTimer !== 0)
-            globalThis.clearTimeout(this.#saveTimer);
-        this.#saveTimer = 0;
+        this.#writer.cancel();
     }
     attributeChangedCallback(name, _old, value) {
         if (!this.#ready)
@@ -221,7 +231,8 @@ export class ViewControlsElement extends HTMLElement {
         return this.#controller;
     }
     #build() {
-        this.#root.innerHTML = `<style>${STYLES}</style>${HTML}`;
+        this.#root.innerHTML = HTML;
+        adoptStyles(this.#root, STYLES, this.nonce);
         const q = (selector) => this.#root.querySelector(selector);
         const c = this.#ensure();
         const slider = (id) => {
@@ -291,11 +302,40 @@ export class ViewControlsElement extends HTMLElement {
         this.#unbind?.();
         this.#unbind = undefined;
         this.#view = element;
-        if (element === undefined)
-            return;
         // A view takes the keys only if it can be focused: a page that wants arrows and plus and minus on it gives it a tabindex.
-        this.#unbind = this.#ensure().bind(element);
+        if (element !== undefined)
+            this.#unbind = this.#ensure().bind(element);
+        this.#watch();
     }
+    /** The automatic turn runs only while the view (else this element) is on screen in a visible tab; otherwise its frame loop is stopped. */
+    #watch() {
+        this.#seen?.disconnect();
+        this.#seen = undefined;
+        this.#onScreen = true;
+        if (typeof IntersectionObserver === "function" && this.isConnected) {
+            this.#seen = new IntersectionObserver((entries) => {
+                const last = entries[entries.length - 1];
+                if (last === undefined)
+                    return;
+                this.#onScreen = last.isIntersecting;
+                this.#sight();
+            });
+            this.#seen.observe(this.#view ?? this);
+        }
+        this.#sight();
+    }
+    #sight = () => {
+        if (this.#controller === undefined)
+            return;
+        const idle = !this.#onScreen || this.ownerDocument.visibilityState === "hidden";
+        if (idle === this.#suspended)
+            return;
+        this.#suspended = idle;
+        if (idle)
+            this.#controller.suspendTurn();
+        else
+            this.#controller.resumeTurn();
+    };
     #label() {
         const language = languageOf(this.getAttribute("lang") ?? this.closest("[lang]")?.getAttribute("lang") ?? this.ownerDocument.documentElement.lang);
         const words = wordsFor(language, this.#words);
@@ -351,19 +391,9 @@ export class ViewControlsElement extends HTMLElement {
     }
     /** The address is written at most four times a second: Safari stops a page that changes its address more than a hundred times in thirty seconds. */
     #save() {
-        if (this.#saveTimer !== 0)
-            return;
-        this.#saveTimer = globalThis.setTimeout(() => {
-            this.#saveTimer = 0;
-            try {
-                const s = this.#ensure().state;
-                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}`);
-            }
-            catch {
-                /* an address that cannot be changed (a sandboxed frame): the view still works */
-            }
-        }, 250);
+        this.#writer.write((search) => {
+            const s = this.#ensure().state;
+            return formatAddress(search, s, this.#keys, s.turning, this.#ensure().startZoom);
+        });
     }
 }