@johnmorrisdotca/kazoku-ui 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-11-03
+
+The wheel over the view zooms it, in every family package that uses the view controls.
+
+- **The wheel zooms** (KAZOKU-UI-45). The wheel over the view now zooms it about the pointer, like a map, about 1.2 times a notch; before, the plain wheel tipped a focused view and only Ctrl or Command with the wheel zoomed. A trackpad's pinch (Ctrl and the wheel) still zooms. Shift and the wheel, or a sideways swipe, turns the view. Tipping is a drag, the arrow keys or the tilt slider. With the pointer anywhere else the wheel scrolls the page; a wheel that starts while the zoom is already at its end that way (turned down at Fit, or up at the most) scrolls the page as well, so it is never trapped, while the steps of a turn that reaches the end part-way through stay with the view, so the page does not jump. A flat view leaves Shift and the wheel and a sideways swipe to the page. `wheelZoomFactor` takes a third argument, `"pinch"` (the default, as before) or `"wheel"`, and `WHEEL_GESTURE_MS` (300) is exported. `key-tilt="wheel"` still swaps the up and down keys.
+- The README opens with the package's thumbnail, and the demo carries it as its link preview (og:image) and publishes the card, a dark card and an icon on Pages at `thumbnail.png`, `thumbnail-dark.png` and `icon.png`.
+
+### Documentation
+
+- **Fourteen guides, each with a Japanese page, and a generated API reference.** `docs/guides/` has getting started, view controls, layouts and the zoom slider, the view controller and its arithmetic, the theme switch, the language picker, address state, save image, the shared renderer, frameworks and CSP, accessibility and labels, architecture, troubleshooting and upgrading; each has its Japanese page of the same name in `docs/guides/ja/`. `docs/API.md` is written from the built declarations (`pnpm docs:api`). The README is rewritten into sections around the same material, and no longer says the package is unpublished.
+- **Every example runs, and the documentation is checked.** `pnpm test:readme` runs each `ts`, `js` and `html` block of the README and the guides (Node for the scripts, headless Chromium in software for the HTML); `pnpm docs:check` fails when `docs/API.md` is out of date, a guide has no Japanese page or a different set of code blocks, a link or picture is missing, or an export is named nowhere. Both run in `.github/workflows/docs.yml`.
+- **Twelve more pictures** in `docs/images/` (the layouts on a phone, the header's switches, address state, save image, the shared renderer and the builder, light and dark), made by `pnpm screenshots`. The hero and the layouts pictures were taken again, because the demo's links now include the builder.
+- New demo page: `demo/builder.html`, to choose a part, set its options, see it live and copy the code, in English and in Japanese, with `e2e/builder.demo.mjs`.
+
 ## [0.12.0] - 2026-11-03
 
 The view controls in four layouts, chosen by one attribute, and the zoom as a slider with marks. A page that names no layout looks exactly as before.

package/README.md

@@ -1,3 +1,5 @@
+<p align="center"><a href="https://johnmorrisdotca.github.io/kazoku-ui/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/thumbnail-dark.png"><img src="https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/thumbnail.png" alt="Kazoku UI: a card with a blue circle and a black triangle, turned and tipped in 3D, over the view controls that turn it." width="1200"></picture></a></p>
+
 # Kazoku UI 家族
 
 <picture>
@@ -9,13 +11,136 @@ The family's shared interface parts, as their own versioned package: one part pe
 The first part is the **view controls** for any 3D or zoomable view. They never draw the scene: they tell your page what the reader chose, and your canvas, WebGL,
 SVG or CSS 3D applies it.
 
-[Demo](https://johnmorrisdotca.github.io/kazoku-ui/) · [Layouts demo](https://johnmorrisdotca.github.io/kazoku-ui/layouts.html) · [Strict-CSP demo](https://johnmorrisdotca.github.io/kazoku-ui/csp.html) · [Theme switch](docs/theme-switch.md) · [Language picker](docs/language-picker.md) · [Address state](docs/address-state.md) · [Save image](docs/save-image.md) · [Shared 3D renderer](docs/renderer.md) · [The drag rule](docs/drag-rule.md) · [Content-Security-Policy](docs/csp.md) · [Labels, English and 日本語](docs/labels.md) · [Changelog](CHANGELOG.md)
+[Demo](https://johnmorrisdotca.github.io/kazoku-ui/) · [Layouts demo](https://johnmorrisdotca.github.io/kazoku-ui/layouts.html) · [Strict-CSP demo](https://johnmorrisdotca.github.io/kazoku-ui/csp.html) · [Theme switch](docs/theme-switch.md) · [Language picker](docs/language-picker.md) · [Address state](docs/address-state.md) · [Save image](docs/save-image.md) · [Shared 3D renderer](docs/renderer.md) · [The drag rule](docs/drag-rule.md) · [Content-Security-Policy](docs/csp.md) · [Labels, English and 日本語](docs/labels.md) · [Changelog](CHANGELOG.md) · [Builder](https://johnmorrisdotca.github.io/kazoku-ui/builder.html) · [API reference](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/API.md) · [Guides](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides)
+
+## In 30 seconds
+
+```sh
+npm install @johnmorrisdotca/kazoku-ui
+```
+
+```html
+<div id="scene" tabindex="0" style="height: 200px">Your scene</div>
+<kazoku-view-controls for="scene" address></kazoku-view-controls>
+<script type="module">
+  import "@johnmorrisdotca/kazoku-ui/view-controls/define";
+
+  document.querySelector("kazoku-view-controls").addEventListener("kazoku-viewchange", (event) => {
+    const { yaw, tilt, zoom, panX, panY } = event.detail;
+    document.getElementById("scene").style.transform = `translate(${panX}px, ${panY}px) scale(${zoom}) rotateX(${tilt}deg) rotateY(${yaw}deg)`;
+  });
+</script>
+```
+
+And the pure functions, with no page at all:
+
+```js
+import { formatAddress, parseAddress, zoomMarks, zoomText } from "@johnmorrisdotca/kazoku-ui/view-controls";
+
+console.log(formatAddress("?x=1", { yaw: 40, tilt: 10, zoom: 2, drag: "turn" })); // ?x=1&yaw=40&tilt=10&zoom=2&drag=turn
+console.log(JSON.stringify(parseAddress("?yaw=40&zoom=2"))); // {"yaw":40,"zoom":2}
+console.log(zoomMarks(1, 5).map((mark) => mark.zoom).join(" ")); // 1 2 3 5
+console.log(zoomText(2.44)); // 2.4×
+```
+
+## Who it is for
+
+- A page or a package that shows a 3D or zoomable view (a card, a globe, a rocket, a map) and wants the reader to turn, tip, zoom and move it, without writing the controls again.
+- A site with a language choice and a Light, Dark or Auto switch that should look and behave the same across every page and every package of a family.
+- A page that wants Save PNG and Save SVG for a canvas, an SVG or a piece of the page.
+- A page of many 3D views that must stay inside one WebGL context and a pixel budget.
+- A framework app: the parts are plain custom elements with plain modules beside them.
+
+## Features
+
+- **No runtime dependencies, one part to a subpath.** A page loads only what it uses.
+- **View controls** in four layouts, with a zoom slider, a readout, Auto-turn, Centre, keys, touch and the address.
+- **Theme switch** (Light, Dark, Auto) and **language picker** (each language in its own name) that write `data-theme` and `lang` and tell the page.
+- **Save image** for a canvas, an SVG or any element, as PNG or SVG.
+- **Address state**, with no element: choices kept in the link with `replaceState`.
+- **A shared 3D renderer** and its **freeze checks**: one WebGL context, shared assets, stills, a pixel budget.
+- **Labels in English and Japanese**, light and dark, 48 px touch targets, reduced motion respected.
+- **A strict Content-Security-Policy is fine:** styles are adopted as constructable stylesheets.
+
+## Install
 
 ```sh
 npm install @johnmorrisdotca/kazoku-ui
 ```
 
-Parts (each its own subpath; later ones: picture-tile pickers, Help, GitHub and npm pills, the family's backgrounds):
+```sh
+pnpm add @johnmorrisdotca/kazoku-ui
+```
+
+Node 22 or later builds and tests it; the parts run in any current browser. Each part is its own subpath, and the `define` file of an element registers its tag, once, and only if the tag is free.
+
+## Use it in your project
+
+In a bundler or a framework, import the `define` file of each element you use once, in code that runs in the browser, and import the pure modules wherever you like:
+
+```ts no-run
+import "@johnmorrisdotca/kazoku-ui/view-controls/define";
+import "@johnmorrisdotca/kazoku-ui/theme-switch/define";
+import { createAddressState } from "@johnmorrisdotca/kazoku-ui/address-state";
+import type { ViewChangeDetail } from "@johnmorrisdotca/kazoku-ui/view-controls/element";
+
+export const state = createAddressState({ defaults: { size: "m" } });
+export const draw = (detail: ViewChangeDetail) => console.log(detail.yaw, detail.zoom);
+```
+
+## Use it anywhere
+
+On a page with no bundler, an import map tells the browser where each subpath lives, and the `dist` folder is served as it is:
+
+```html
+<script type="importmap">
+{ "imports": {
+  "@johnmorrisdotca/kazoku-ui/theme-switch/define": "/node_modules/@johnmorrisdotca/kazoku-ui/dist/theme-switch/define.js"
+} }
+</script>
+<kazoku-theme-switch address storage></kazoku-theme-switch>
+<script type="module">import "@johnmorrisdotca/kazoku-ui/theme-switch/define";</script>
+```
+
+## Examples
+
+A theme switch and a language picker side by side, with the page answering their events:
+
+```html
+<kazoku-theme-switch address storage></kazoku-theme-switch>
+<kazoku-language-picker languages="en ja" address storage></kazoku-language-picker>
+<script type="module">
+  import "@johnmorrisdotca/kazoku-ui/theme-switch/define";
+  import "@johnmorrisdotca/kazoku-ui/language-picker/define";
+
+  document.addEventListener("kazoku-themechange", ({ detail }) => console.log(detail.choice, detail.scheme));
+  document.addEventListener("kazoku-languagechange", ({ detail }) => console.log(detail.lang));
+</script>
+```
+
+Save a canvas as a PNG:
+
+```html
+<canvas id="art" width="360" height="200"></canvas>
+<kazoku-save-image for="art" name="my-picture"></kazoku-save-image>
+<script type="module">import "@johnmorrisdotca/kazoku-ui/save-image/define";</script>
+```
+
+The same idea in code, with the address and the theme as plain functions:
+
+```js
+import { applyParams } from "@johnmorrisdotca/kazoku-ui/address-state";
+import { resolveTheme } from "@johnmorrisdotca/kazoku-ui/theme-switch";
+import { filenameFor } from "@johnmorrisdotca/kazoku-ui/save-image";
+
+console.log(applyParams("?a=1&size=m", { size: "l", a: null }, { size: "m" })); // ?size=l
+console.log(resolveTheme("auto", true)); // dark
+console.log(filenameFor("My Card/x", "png")); // My Card-x.png
+```
+
+## Parts
+
+Each its own subpath; later ones: picture-tile pickers, Help, GitHub and npm pills, the family's backgrounds.
 
 | Subpath | What it is |
 |---|---|
@@ -40,7 +165,7 @@ Parts (each its own subpath; later ones: picture-tile pickers, Help, GitHub and
 - **Two levels, so the bar stays simple.** The default, `controls="basic"`, shows the angle slider, Auto-turn, zoom out and in with a **zoom readout** (`2.4×`; tap it to go back to Fit), Fit, and a small More button; while the view turns, one small **speed** button beside Auto-turn (it shows the word Speed over `Medium`, and a press steps to the next speed). More (or `controls="advanced"`) adds the tilt slider, all three speeds (Slow, Medium, Fast), Front, and, once zoomed in, the four-arrow pan pad and the Move or Turn choice for what a drag does. The reader's choice with More is remembered in `localStorage` and beats the attribute.
 - The zoom readout is the view's `zoom` (1× is Fit, whatever `fit-scale` is), one decimal, the one zoom number on the bar: it follows the buttons, the wheel, a pinch, a double press, Fit, the keys, the address, `set` and a changed limit. A screen reader is told "Zoom level 2.4×" once the zoom has settled for a moment, not for every step of a pinch.
 - Auto-turn with play and pause; its speed is Slow (half the `speed` attribute), Medium (the `speed` attribute, 30 degrees a second) or Fast (twice it), kept in the address as `?speed=slow` or `?speed=fast`.
-- Zoom is about the pointer (and Ctrl or Command with the wheel, or a trackpad's pinch).
+- **The wheel zooms.** The wheel over the view zooms it about the pointer, like a map; a trackpad's pinch (and Ctrl or Command with the wheel) zooms too. Shift and the wheel, or a sideways swipe, turns it. Tipping is a drag, the arrow keys or the tilt slider. With the pointer anywhere else the wheel scrolls the page, and a wheel that starts while the zoom is already at its end that way (turned down at Fit) scrolls the page too, so the page is never trapped.
 - Touch: one finger turns at 1x and moves the view when zoomed in; two fingers pinch.
 - Keys on the view: arrows turn and tip it, `+` and `-` zoom, `0` or Home is Front and Fit.
 - The choices are kept in the address, with keys you can rename.
@@ -66,7 +191,7 @@ The `layout` attribute says where the controls sit; `controls` (`basic` or `adva
 | `vertical` | A column beside the view, `--kazoku-column-width` wide (16rem). Auto-turn and More at the top, so More does not move when it opens; then the Angle slider, the zoom slider, and − readout + and Fit. On a narrow screen put it under the view and give it `width: auto`. | Auto-turn, More, Angle, the zoom slider, − readout +, Fit | Tilt, the speeds, Front, the pan pad, in the column |
 | `compact` | The least room, for a card or a phone: **one row** of Auto-turn, −, the readout, + and More (icons, named for a screen reader). It never takes a second row until More is pressed; while it turns, the speed is in More, and Centre is there with Fit. | Auto-turn, − readout +, More | Everything else, one press away, under the row: the zoom slider and Fit, Angle, Tilt, the speeds, Front, the pan pad |
 
-```html
+```html no-check
 <!-- Horizontal: under the view -->
 <div id="view" tabindex="0">...your scene...</div>
 <kazoku-view-controls for="view" layout="horizontal"></kazoku-view-controls>
@@ -136,7 +261,7 @@ export function Viewer({ draw }) {
 
 `createViewController` is the same hands and state with no markup of its own, for a page that draws its own buttons. It touches the DOM only in `bind`.
 
-```js
+```js no-run
 import { createViewController } from "@johnmorrisdotca/kazoku-ui/view-controls";
 
 const view = createViewController({
@@ -164,7 +289,7 @@ The hands capture the pointer on the `for` element, so a press on a button or li
 
 The zoom buttons and keys have no pointer, so they zoom about the view's middle. If your scene's middle is not the view's (a piece standing to one side, say), tell the controls where it is:
 
-```js
+```js no-run
 controls.anchor = { x: 60, y: -30 }; // pixels from the view's middle when it is at Fit
 ```
 
@@ -180,13 +305,13 @@ In every turnable view the surface under the pointer follows the pointer, the ar
 
 ### Keys, the wheel and the turn
 
-Arrow Up tips like a drag up (`tilt` gets larger). A page whose wheel and keys should agree sets `key-tilt="wheel"`: Arrow Up then tips the way a wheel turned up does (`tilt` gets smaller), and Arrow Down the other way. `stop-turn` stops the automatic turn when the reader takes hold of the view with a press, the wheel or a key (a `pause` event is sent first); the defaults keep it turning, and a button or slider never stops it. `tilt-step="1"` makes a drag give whole degrees of tilt.
+The wheel over the view zooms it about the pointer, and the steps of one turn of the wheel or one swipe stay with the view even when the zoom reaches its end part-way through, so the page does not jump. A new turn of the wheel at that end scrolls the page. Shift and the wheel, or a sideways swipe, turns the view (on a flat view they are left to the page). Arrow Up tips like a drag up (`tilt` gets larger); `key-tilt="wheel"` makes it tip the other way (`tilt` gets smaller), the way the wheel turned up tipped the view before 0.13.0, and Arrow Down the other way. `stop-turn` stops the automatic turn when the reader takes hold of the view with a press, the wheel or a key (a `pause` event is sent first); the defaults keep it turning, and a button or slider never stops it. `tilt-step="1"` makes a drag give whole degrees of tilt.
 
 ### 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
+```js no-run
 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
@@ -223,7 +348,7 @@ An `init` event is sent once, a moment after the element connects, with the star
 | `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. |
 | `anchor` | `x,y`: the point the + and - buttons, the 2x button and the + and - keys zoom about, in CSS pixels from the middle of the view when it is at Fit (zoom 1, no pan). It is a point on the picture, so it moves with it and stays fixed on screen while the buttons zoom. Left out, they zoom about the view's middle, as before. The wheel, a pinch and a double tap still zoom about the pointer. Or set `element.anchor = { x, y }` (`undefined` clears it). |
-| `key-tilt` | Which way Arrow Up tips the view: `drag` (the default: like a drag up) or `wheel` (the way a wheel turned up tips it, the other way). Arrow Down goes the other way from Up. |
+| `key-tilt` | Which way Arrow Up tips the view: `drag` (the default: like a drag up) or `wheel` (the other way, as the wheel turned up tipped it before 0.13.0; the wheel zooms now). Arrow Down goes the other way from Up. |
 | `stop-turn` | A press on the view, the wheel over it or a key it handles stops the automatic turn. Off by default, so the turn carries on. Buttons and sliders never stop it. |
 | `tilt-step` | Round the tilt of a drag to a multiple of this many degrees (`1` gives whole degrees). 0 by default: not rounded. |
 | `object-size` | `w,h`: the object's size at Fit in CSS pixels, when it is smaller than the view. A pan then keeps at least a quarter of the object in view, however far it is dragged; left out, the object is the picture, which keeps covering the view. Or set `element.objectSize = { width, height }`. |
@@ -278,7 +403,7 @@ See [docs/language-picker.md](docs/language-picker.md). The demo's own English a
 
 Choices kept in the address, without an element: `createAddressState({ defaults })` with `get`, `set`, `remove`, `subscribe` and `flush`, writing with `replaceState` (no history entry, one write for the changes of a quarter of a second, a value at its default leaves the address, other parameters and the hash kept), and hearing back and forward. The theme switch, the language picker and the view controls keep their choices through it.
 
-```js
+```js no-run
 import { createAddressState } from "@johnmorrisdotca/kazoku-ui/address-state";
 
 const state = createAddressState({ defaults: { size: "m" } });
@@ -306,7 +431,7 @@ materials, textures and models are counted and freed when the last view lets go.
 requested at a time, and a canvas never passes 6 million pixels or 4096 a side. Context loss is handled in one place. **three.js is a peer dependency and is never bundled**:
 your page passes `load: () => import("three")`, so it loads only when the first view goes live. How a package uses it, the API and the freeze checks: [docs/renderer.md](docs/renderer.md). Demo: `renderer.html`.
 
-```ts
+```ts no-check
 import { createSharedRenderer } from "@johnmorrisdotca/kazoku-ui/renderer";
 const renderer = createSharedRenderer({ load: () => import("three") });
 const view = renderer.view(host, item);   // item: { key, build({ three, assets, width, height }) => { scene, camera } }
@@ -341,8 +466,104 @@ Gzipped, unbundled. View controls: the element and its definition about 9.3 KB,
 
 `pnpm check` (lint, types, 122 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, the frame loop counted at `requestAnimationFrame` (nothing out of sight or hidden, one callback a page frame otherwise, a moved element too), the zoom readout against the state after every way of zooming, the speed button adding no row, each layout's controls, rows and sizes (compact one row on a phone, turning adding no row), the zoom slider by keys, mouse and touch, its marks for several ranges and always the true zoom, the layouts page, a button or link inside the view still clicks while a drag turns it, the opening zoom and fit scale, zoom about the pointer, zoom about an anchor (`?anchor=pin`), Arrow Up either way (`?key-tilt=wheel`), `?stop-turn`, `?tilt-step=1`, pan when zoomed, touch, the address, the labels, reduced motion, the controls styled under a strict `style-src` with no violation, `demo/csp.html`, the theme switch and the language picker in each browser and size, the address state, back and forward and no history added, on `demo/address.html`, and the save buttons: each file read back from disk, on `demo/save-image.html`, and the shared 3D renderer on `demo/renderer.html`: one WebGL context over fifty focus changes, nothing drawn or requested at rest, the GPU objects and heap flat, the canvas within budget at 5K, context loss, out of sight, the stills' byte budget, and three.js fetched only when a view goes live).
 
-## Not yet
+## Theming
+
+Every part follows the page's colours: `data-theme="light"` or `"dark"` on the page forces them, and without it the device decides. `theme="light"` or `theme="dark"` on one element gives it a look of its own. The colours are custom properties on the element: `--kazoku-ink`, `--kazoku-surface`, `--kazoku-line` and `--kazoku-accent`; the parts are `bar`, `field`, `slider` and `button` (and `group` for the others).
+
+```html
+<style>
+  kazoku-theme-switch, kazoku-language-picker { --kazoku-accent: #2457d6; --kazoku-line: #c9cdd6; }
+</style>
+<kazoku-theme-switch></kazoku-theme-switch>
+<script type="module">import "@johnmorrisdotca/kazoku-ui/theme-switch/define";</script>
+```
+
+## Accessibility
+
+Controls are on or right beside the view and visible without scrolling; changing a control never stops or resets the turn; every control is 48 px; the choices are radio groups with one tab stop and the arrow keys; the zoom is announced politely once it has settled; each language button carries its own `lang`; reduced motion gets no automatic turn. The rules and the labels are in [Accessibility and labels](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/accessibility-and-labels.md).
+
+## Limits
+
+- **The Japanese labels have not yet been read by a native speaker.**
+- **The demo's scene is a CSS 3D card;** the package has no opinion about what draws.
+- **A picture of an element** (save image) cannot carry web fonts, `::before` or `::after`, or a cross-origin image: draw those into a canvas and save the canvas.
+- **Several visible live 3D views at once are not supported** by the shared renderer: that is its point.
+- **WebKit has no software GL switch,** so off CI its tests skip the pages that draw WebGL.
+- **Early development (0.x):** a minor version can add to the interface. [Upgrading](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/upgrading.md) lists what asks something of you.
+
+## Browser and runtime support
+
+The elements need custom elements, shadow DOM and constructable stylesheets (Chrome, Edge, Firefox and Safari 16.4 or later; older Safari falls back to a `<style>` that carries the element's `nonce`). The demo is played in Chromium and WebKit, at a phone's width and a desk's. Node 22 or later builds and tests it (22.18 or later to run the TypeScript tests directly); the pure modules import on a server. To load an element only where it can run:
+
+```js no-run
+if ("customElements" in window) {
+  await import("@johnmorrisdotca/kazoku-ui/theme-switch/define");
+}
+```
+
+## Languages
+
+Every label is in English and in Japanese, and a unit test holds that every key is in both. `lang="ja"` (on the element or on a parent) chooses Japanese; anything else is English. Your own words go over either set: `element.words = { front: "Home" }`, or `wordsFor("ja", { front: "ホーム" })`. The language picker names each language in its own language. The guides have a Japanese page each, in [docs/guides/ja](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/ja).
+
+## Roadmap
+
+Parts that arrive later: picture-tile pickers, Help, GitHub and npm pills and the family's backgrounds, each a new subpath that changes nothing that exists. Next for what is here: the Japanese labels read by a native speaker, and the family's other packages moving to the shared parts.
+
+## Architecture
+
+One part, one subpath; the pure code, the element and the registration are three files; a part never draws the page's scene; the shared internals (styles, adoption, scheme, store, target) are not exported. See the [architecture guide](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/architecture.md).
+
+## Demos
+
+[The demo](https://johnmorrisdotca.github.io/kazoku-ui/) has the view controls, the language picker and the theme switch in its header. Beside it: [layouts](https://johnmorrisdotca.github.io/kazoku-ui/layouts.html), [the builder](https://johnmorrisdotca.github.io/kazoku-ui/builder.html), [address state](https://johnmorrisdotca.github.io/kazoku-ui/address.html), [save image](https://johnmorrisdotca.github.io/kazoku-ui/save-image.html), [the shared renderer](https://johnmorrisdotca.github.io/kazoku-ui/renderer.html), [exact grab](https://johnmorrisdotca.github.io/kazoku-ui/grab.html) and [a strict Content-Security-Policy](https://johnmorrisdotca.github.io/kazoku-ui/csp.html).
+
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/builder-dark.webp">
+<img alt="The builder: the part chosen in a row of buttons, its options beside the live preview, and the code to copy under them" src="https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/builder-light.webp">
+</picture>
+
+## Documentation
+
+| Guide | What it covers |
+|---|---|
+| [Getting started](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/getting-started.md) | The parts in a few minutes |
+| [View controls](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/view-controls.md) | Every attribute, the event, the keys, the address |
+| [Layouts and the zoom slider](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/layouts-and-zoom.md) | The four layouts and the slider's scale |
+| [The view controller and its arithmetic](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/view-controller.md) | The controller without the element |
+| [Theme switch](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/theme-switch.md) | Light, Dark and Auto |
+| [Language picker](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/language-picker.md) | Each language in its own name |
+| [Address state](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/address-state.md) | Choices kept in the link |
+| [Save image](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/save-image.md) | A canvas, an SVG or an element as a picture |
+| [The shared renderer](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/renderer.md) | One WebGL context, and the freeze checks |
+| [Frameworks and CSP](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/frameworks-and-csp.md) | React, Vue, Svelte, Angular, servers, strict policies |
+| [Accessibility and labels](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/accessibility-and-labels.md) | The rules and the words |
+| [Architecture](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/architecture.md) | The parts and the rules |
+| [Troubleshooting and FAQ](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/troubleshooting.md) | A bar that does nothing, an unknown tag |
+| [Upgrading](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/upgrading.md) | What each version asks of you |
+
+Each guide has a Japanese page of the same name in [docs/guides/ja](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/guides/ja). The reference for every export is [docs/API.md](https://github.com/johnmorrisdotca/kazoku-ui/blob/main/docs/API.md), written from the built declarations. The repository's own notes: [theme switch](docs/theme-switch.md), [language picker](docs/language-picker.md), [address state](docs/address-state.md), [save image](docs/save-image.md), [renderer](docs/renderer.md), [the drag rule](docs/drag-rule.md), [CSP](docs/csp.md), [labels](docs/labels.md), [the package standard](docs/package-standard.md).
+
+## Development
+
+```sh
+pnpm check          # lint, types, tests, the build and the packed package
+pnpm test:package   # pack it as npm does, install it in an empty project, import every entry
+pnpm test:demo      # build the demo and play it in Chromium and WebKit
+pnpm test:readme    # every example of the README and the guides, run in Node and in a browser
+pnpm docs:api       # rewrite docs/API.md from the built declarations
+pnpm docs:check     # the reference is current, every guide has its Japanese page, every link and picture is there
+pnpm screenshots    # the pictures of the README and the guides (docs/images)
+pnpm dev            # the demo on http://127.0.0.1:8400/
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md): no runtime dependencies, one part to a subpath, a part never draws the page's scene, labels in both languages, no marks, and tests for what you change. Add a line to `CHANGELOG.md` under **Unreleased** for a change a user would notice. `templates/` and `docs/package-standard.md` are what the family's other packages copy unchanged.
+
+## Changes
+
+Every release, dated, is in [CHANGELOG.md](CHANGELOG.md).
 
-Not published to npm yet. The Japanese labels have not yet been read by a native speaker. The demo's scene is a CSS 3D card; the package has no opinion about what draws.
+## Licence
 
-Licence: MIT. No brand, league or sponsor mark is in this package.
+MIT. No brand, league or sponsor mark is in this package.

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

@@ -14,7 +14,7 @@ export interface ChangeInfo {
 }
 /** 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]";
-/** Which way Arrow Up tips the view: like a drag up (`"drag"`, the default) or the way the wheel turned up does (`"wheel"`, the other way). */
+/** Which way Arrow Up tips the view: like a drag up (`"drag"`, the default) or the other way (`"wheel"`, the way the wheel turned up tipped it before 0.13.0; the wheel zooms now). */
 export type KeyTilt = "drag" | "wheel";
 export interface Clock {
     request(callback: (now: number) => void): number;
@@ -35,7 +35,7 @@ export interface ViewControllerOptions {
     ignore?: string;
     /** The point the zoom buttons and keys zoom about, in content coordinates: CSS pixels from the view's middle when it is at Fit (zoom 1, no pan). It moves with the picture, so the point stays where it is on screen while the view zooms. Left out, they zoom about the view's middle. */
     anchor?: Point;
-    /** Which way Arrow Up tips the view: `"drag"` (the default, as a drag up) or `"wheel"` (as a wheel turned up). */
+    /** Which way Arrow Up tips the view: `"drag"` (the default, as a drag up) or `"wheel"` (the other way, as the wheel turned up tipped it before 0.13.0; the wheel zooms now). */
     keyTilt?: KeyTilt;
     /** True to stop the automatic turn when the reader presses the view, uses the wheel on it or presses a key it handles. False (the default) lets it carry on. Buttons and sliders never stop it. */
     stopTurn?: boolean;

package/dist/view-controls/controller.js

@@ -1,5 +1,5 @@
 import { turnOnlyInSight } from "./sight.js";
-import { between, clamp, clampPan, DEFAULT_LIMITS, dragTurn, PAN_STEP, pinchTo, wheelZoomFactor, wrapYaw, ZOOMED, zoomAbout } from "./math.js";
+import { between, clamp, clampPan, DEFAULT_LIMITS, dragTurn, PAN_STEP, pinchTo, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOMED, zoomAbout } from "./math.js";
 /** What `bind` leaves alone by default: the page's own controls inside the view. */
 export const DEFAULT_IGNORE = "button, a, input, select, textarea, label, [data-kazoku-ignore]";
 /** How long a move to the middle takes. */
@@ -390,27 +390,36 @@ export function createViewController(options = {}) {
                 }
             }
         };
+        // The wheel over the view zooms it about the pointer, as a map does; the page scrolls when the pointer is anywhere else. Ctrl or Command
+        // and the wheel (a trackpad's pinch) zooms too. Shift and the wheel, or a sideways swipe, turns it. Tipping is left to a drag, the keys
+        // and the buttons. A wheel that starts while the zoom is already at its end that way (zooming out at Fit) goes on to scroll the page,
+        // so the page is never trapped; one that reaches the end part-way through stops there rather than flinging the page.
+        let wheelTaken = Number.NEGATIVE_INFINITY;
         const onWheel = (e) => {
-            if (e.ctrlKey || e.metaKey) {
-                // A trackpad's pinch arrives as Ctrl and the wheel; Command and the wheel does the same for a mouse.
+            const pinch = e.ctrlKey || e.metaKey;
+            const now = Number.isFinite(e.timeStamp) ? e.timeStamp : 0;
+            const continuing = now - wheelTaken < WHEEL_GESTURE_MS && now >= wheelTaken;
+            const horizontal = Math.abs(e.deltaX) > Math.abs(e.deltaY);
+            if (!pinch && (horizontal || e.shiftKey)) {
+                if (!canTurn())
+                    return;
                 e.preventDefault();
+                wheelTaken = now;
                 grab();
-                controller.zoomAt(state.zoom * wheelZoomFactor(e.deltaY, e.deltaMode), { x: e.clientX, y: e.clientY });
+                controller.set({ yaw: state.yaw + (e.deltaX || e.deltaY) * 0.3 }, true, "wheel");
                 return;
             }
-            const horizontal = Math.abs(e.deltaX) > Math.abs(e.deltaY);
-            const focused = view.ownerDocument.activeElement === view;
-            // A sideways swipe turns it wherever the pointer is over it; an up and down wheel only when the view has focus, as the page's scroll comes first.
-            if (!horizontal && !focused)
+            const factor = wheelZoomFactor(e.deltaY, e.deltaMode, pinch ? "pinch" : "wheel");
+            const atEnd = factor >= 1 ? state.zoom >= limits.zoomMax : state.zoom <= limits.zoomMin;
+            // Ctrl and the wheel is always the view's, or the browser would zoom the whole page.
+            if (!pinch && atEnd && !continuing)
                 return;
             e.preventDefault();
-            if (!canTurn())
+            wheelTaken = now;
+            if (atEnd)
                 return;
             grab();
-            if (horizontal || e.shiftKey)
-                controller.set({ yaw: state.yaw + (e.deltaX || e.deltaY) * 0.3 }, true, "wheel");
-            else
-                controller.set({ tilt: Math.round(state.tilt + e.deltaY * 0.15) }, true, "wheel");
+            controller.zoomAt(state.zoom * factor, { x: e.clientX, y: e.clientY });
         };
         const onKey = (e) => {
             if (e.ctrlKey || e.metaKey || e.altKey)

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

@@ -12,7 +12,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), `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),
+ * `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; the wheel itself zooms),
  * `controls` (`basic`, the default, or `advanced`: which controls are shown, the zoom readout in both, and the speed in both while the view turns; the reader's own choice with the More button is remembered in localStorage, under `kazoku-view-controls` or the key `storage` names, and wins),
  * `layout` (`classic`, the default, `horizontal`, `vertical` or `compact`: where the controls sit; the horizontal, vertical and compact layouts have the zoom slider),
  * `stop-turn` (a press, the wheel or a key on the view stops the automatic turn), `tilt-step` (round a drag's tilt to a multiple of this many degrees), `object-size` (`w,h`: the object's size at Fit in pixels when it is smaller than the view, so a pan keeps a quarter of it in view), `grab-radius` (exact grab: the on-screen radius of the piece in pixels, or `fit`; a drag then keeps the touched point under the pointer), `flat` (the view cannot turn), `tilt-max`, `zoom-min`, `zoom-max`, `address` (keep the choices in the page's address), `address-keys` (`yaw:a,tilt:b`), `theme` (light

package/dist/view-controls/element.js

@@ -66,7 +66,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), `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),
+ * `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; the wheel itself zooms),
  * `controls` (`basic`, the default, or `advanced`: which controls are shown, the zoom readout in both, and the speed in both while the view turns; the reader's own choice with the More button is remembered in localStorage, under `kazoku-view-controls` or the key `storage` names, and wins),
  * `layout` (`classic`, the default, `horizontal`, `vertical` or `compact`: where the controls sit; the horizontal, vertical and compact layouts have the zoom slider),
  * `stop-turn` (a press, the wheel or a key on the view stops the automatic turn), `tilt-step` (round a drag's tilt to a multiple of this many degrees), `object-size` (`w,h`: the object's size at Fit in pixels when it is smaller than the view, so a pan keeps a quarter of it in view), `grab-radius` (exact grab: the on-screen radius of the piece in pixels, or `fit`; a drag then keeps the touched point under the pointer), `flat` (the view cannot turn), `tilt-max`, `zoom-min`, `zoom-max`, `address` (keep the choices in the page's address), `address-keys` (`yaw:a,tilt:b`), `theme` (light

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

@@ -1,6 +1,6 @@
 export { DEFAULT_KEYS, formatAddress, parseAddress, parseKeys, type AddressChoices, type AddressKeys, type DragMode } from "./address.ts";
 export { createViewController, DEFAULT_IGNORE, type ChangeInfo, type Clock, type ViewController, type ViewControllerOptions, type ViewState } from "./controller.ts";
-export { between, clamp, clampPan, DEFAULT_LIMITS, degreesPerPixel, dragTurn, PAN_STEP, pinchTo, TILT_ACROSS, TURN_ACROSS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout, type Camera, type Limits, type PinchStart, type Point, type Size } from "./math.ts";
+export { between, clamp, clampPan, DEFAULT_LIMITS, degreesPerPixel, dragTurn, PAN_STEP, pinchTo, TILT_ACROSS, TURN_ACROSS, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout, type Camera, type Limits, type PinchStart, type Point, type Size } from "./math.ts";
 export { languageOf, WORDS, wordsFor, type Language, type ViewWords } from "./words.ts";
 export declare const EVENT = "kazoku-viewchange";
 export declare const TAG = "kazoku-view-controls";

package/dist/view-controls/index.js

@@ -1,7 +1,7 @@
 // The view controls without the element: the controller, the arithmetic, the address and the labels. Nothing here touches the DOM until `bind` is called, so it imports on a server.
 export { DEFAULT_KEYS, formatAddress, parseAddress, parseKeys } from "./address.js";
 export { createViewController, DEFAULT_IGNORE } from "./controller.js";
-export { between, clamp, clampPan, DEFAULT_LIMITS, degreesPerPixel, dragTurn, PAN_STEP, pinchTo, TILT_ACROSS, TURN_ACROSS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout } from "./math.js";
+export { between, clamp, clampPan, DEFAULT_LIMITS, degreesPerPixel, dragTurn, PAN_STEP, pinchTo, TILT_ACROSS, TURN_ACROSS, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout } from "./math.js";
 export { languageOf, WORDS, wordsFor } from "./words.js";
 export const EVENT = "kazoku-viewchange";
 export const TAG = "kazoku-view-controls";

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

@@ -56,5 +56,11 @@ export declare const degreesPerPixel: (radius: number) => number;
 export declare function dragTurn(start: Camera, dx: number, dy: number, size: Size, tips: boolean, limits?: Limits, step?: number, grabRadius?: number): Pick<Camera, "yaw" | "tilt">;
 /** The camera `fraction` of the way (0 to 1) from `from` to `to`, eased out: quick at first, slow at the end. */
 export declare function between(from: Camera, to: Camera, fraction: number): Camera;
-/** The factor a Ctrl or Command wheel turn zooms by (a trackpad's pinch arrives that way). `deltaMode` 1 is lines. */
-export declare const wheelZoomFactor: (deltaY: number, deltaMode: number) => number;
+/**
+ * The factor a wheel turn zooms by: up (a negative `deltaY`) zooms in. `deltaMode` 1 is lines and 2 is pages. `kind` `"pinch"` (the default) is a
+ * trackpad's pinch, which arrives as Ctrl and the wheel in small steps; `"wheel"` is a plain wheel or two-finger scroll, whose steps are larger
+ * (about 100 pixels a notch), so one notch zooms about 1.2 times, close to the + key, and one such event never zooms more than 2 times either way.
+ */
+export declare const wheelZoomFactor: (deltaY: number, deltaMode: number, kind?: "pinch" | "wheel") => number;
+/** Wheel steps closer together than this, in milliseconds, belong to one turn of the wheel or one swipe (with its glide). */
+export declare const WHEEL_GESTURE_MS = 300;

package/dist/view-controls/math.js

@@ -60,5 +60,14 @@ export function between(from, to, fraction) {
     const mix = (a, b) => a + (b - a) * t;
     return { yaw: mix(from.yaw, to.yaw), tilt: mix(from.tilt, to.tilt), zoom: mix(from.zoom, to.zoom), panX: mix(from.panX, to.panX), panY: mix(from.panY, to.panY) };
 }
-/** The factor a Ctrl or Command wheel turn zooms by (a trackpad's pinch arrives that way). `deltaMode` 1 is lines. */
-export const wheelZoomFactor = (deltaY, deltaMode) => Math.exp(-deltaY * (deltaMode === 1 ? 0.05 : 0.01));
+/**
+ * The factor a wheel turn zooms by: up (a negative `deltaY`) zooms in. `deltaMode` 1 is lines and 2 is pages. `kind` `"pinch"` (the default) is a
+ * trackpad's pinch, which arrives as Ctrl and the wheel in small steps; `"wheel"` is a plain wheel or two-finger scroll, whose steps are larger
+ * (about 100 pixels a notch), so one notch zooms about 1.2 times, close to the + key, and one such event never zooms more than 2 times either way.
+ */
+export const wheelZoomFactor = (deltaY, deltaMode, kind = "pinch") => {
+    const pixels = deltaMode === 1 ? deltaY * (kind === "pinch" ? 5 : 33) : deltaMode === 2 ? deltaY * 800 : deltaY;
+    return kind === "pinch" ? Math.exp(-pixels * 0.01) : clamp(Math.exp(-pixels * 0.002), 0.5, 2);
+};
+/** Wheel steps closer together than this, in milliseconds, belong to one turn of the wheel or one swipe (with its glide). */
+export const WHEEL_GESTURE_MS = 300;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/kazoku-ui",
-  "version": "0.12.0",
+  "version": "0.13.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",
@@ -163,7 +163,10 @@
     "site": "pnpm build && node scripts/site.mjs",
     "test:demo": "pnpm site && playwright test",
     "test:freeze": "pnpm site && playwright test e2e/renderer.demo.mjs --project=chromium-desk",
-    "screenshots": "pnpm site && node scripts/screenshots.mjs"
+    "screenshots": "pnpm site && node scripts/screenshots.mjs",
+    "docs:api": "pnpm build && node scripts/docs.mjs api",
+    "docs:check": "pnpm build && node scripts/docs.mjs check",
+    "test:readme": "pnpm build && node scripts/check-readme-examples.mjs"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",