@johnmorrisdotca/kazoku-ui 0.3.0 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## [0.7.2] - 2026-11-02
+
+One release workflow for all the family's packages.
+
+- `.github/workflows/reusable-release.yml` (`workflow_call`): from main, the tag equals `package.json`'s version, the repo's check script runs, a version already on npm is skipped, the `v<version>` tag is made if missing, then `npm publish --provenance` by trusted publishing. Inputs: `node-version`, `install-command`, `check-command`, `github-release`.
+- This repo's `release.yml` now only calls it (same file name, so its npmjs.com trusted-publisher entry is unchanged) and still makes the GitHub release with the tarball.
+- `docs/release-workflow.md`: npm trusted publishing accepts a called workflow; the publisher entry names the calling file; how to move another repo over.
+
+## [0.7.1] - 2026-11-02
+
+The automatic turn no longer runs when nothing can see the view.
+
+- While the `for` element (else the controls) is scrolled out of sight, or the tab is hidden, the frame loop stops: no animation frame is requested and no `kazoku-viewchange` with reason `auto` is sent. `turning` stays true and the turn resumes where it was. It uses `IntersectionObserver` and `visibilitychange`; without `IntersectionObserver` the view counts as on screen.
+- New attribute `autoplay-for` (seconds): the `autoplay` turn stops by itself after that long, counting only time spent turning. Left out, nothing changes.
+- The controller gains `suspendTurn()`, `resumeTurn()` (nesting) and `play(seconds)`. A bare `play()` and the Auto-turn button are unchanged.
+
+## [0.7.0] - 2026-11-02
+
+The fifth part: save as an image, at `@johnmorrisdotca/kazoku-ui/save-image` (and `/save-image/element`, `/save-image/define`).
+
+- `<kazoku-save-image for="id">`: Save PNG and Save SVG buttons (48 px, light and dark, English and Japanese) for a canvas, an SVG or any element. A canvas is saved as a PNG at its own pixel size. An SVG is saved as a stand-alone SVG (namespaces, size, `viewBox` and the styles it is drawn in written into it) or as a PNG; any other element as a PNG drawn through a `foreignObject` with its computed styles, a canvas inside it drawn in as a picture.
+- Attributes `formats`, `name`, `scale` (2 by default, held to 8192 pixels a side and 36 million in all), `background` (the colour behind a PNG), `manual` (make the picture and the event, download nothing), `no-inline-styles`, `lang`, `theme`. `element.save(format)` and `element.target`.
+- Events `kazoku-save` (`{ blob, format, width, height, filename, reason }`) and `kazoku-saveerror` (`{ format, error, reason }`), and a status line for a screen reader.
+- The element-free functions (`renderImage`, `saveImage`, `downloadBlob`, `serializeSvg`, `serializeElement`, `svgToPng`, `filenameFor`, `parseFormats`, `pixelSize`) import on a server. Docs: `docs/save-image.md`, with what a picture of an element cannot carry (web fonts, `::before`, cross-origin images).
+- Under a strict policy it needs `img-src data:` for an SVG or element PNG (a canvas needs nothing); `demo/csp.html` now has `img-src data:` and a save button.
+- The demo has `save-image.html`: a canvas, an SVG and a piece of the page, each saved and shown back. Existing elements are unchanged.
+
+## [0.6.0] - 2026-11-02
+
+The fourth part: choices kept in the address, at `@johnmorrisdotca/kazoku-ui/address-state`. No element.
+
+- `createAddressState({ defaults, delay, host })`: `get`, `has`, `all`, `set`, `setMany`, `remove`, `subscribe(listener, keys?)`, `flush`, `destroy`. It writes with `replaceState` (no history entry; the path, hash and other parameters kept; a value equal to its default leaves the address), as one write for the changes inside `delay` (250 ms by default; 0 writes at once). A subscriber hears each change made through any state on the page, with `{ key, value, previous, source }`, and the reader going back or forward (`source: "navigation"`). A page that cannot change its address still works.
+- The smaller pieces: `readParams`, `readParam`, `applyParams(search, changes, defaults?)` and `createAddressWriter({ delay, host })` (`write(compute)`, `flush()`, `cancel()`). All of it imports on a server.
+- The view controls now write their address through `createAddressWriter`, the theme switch and the language picker through `createAddressState`: the same addresses, the same quarter-second write for the view controls, nothing changes for a page.
+- Docs: `docs/address-state.md`. The demo's `address.html` keeps a name, a size and dots in the address beside the theme switch and the language picker.
+
+## [0.5.0] - 2026-11-02
+
+The third part: the language picker, at `@johnmorrisdotca/kazoku-ui/language-picker` (and `/language-picker/element`, `/language-picker/define`).
+
+- `<kazoku-language-picker languages="en ja">`: a button for each language the page lists, each in its own name (English, 日本語, Français; any other code is named by `Intl.DisplayNames` in its own language). It writes the choice as `lang` on a `target` (the page's `<html>` by default) and sends `kazoku-languagechange` with `{ lang, previous, reason, target }` (reasons `init`, `user`, `set`, `external`). Each button carries its own `lang`.
+- It starts in the language of the address (`address`, `?lang=`, `address-key`), else the store (`storage`, in a try/catch), else `value`, else the reader's browser languages (`ja-JP` is `ja`), else what the target's `lang` says, else the first code. Another writer of the target's `lang` moves it with it.
+- The pure entry (`parseLanguages`, `matchLanguage`, `languageName`, `startingLanguage`, `applyLanguage`, the words) imports on a server. Docs: `docs/language-picker.md`.
+- Under a strict `style-src`, like the others. The demo's English and 日本語 buttons are now a picker, and the view controls and theme switch answer to it.
+- The theme switch and the view controls are unchanged (the theme switch shares its target and store code with the picker; same behaviour).
+
+## [0.4.0] - 2026-11-01
+
+The second part: the theme switch, at `@johnmorrisdotca/kazoku-ui/theme-switch` (and `/theme-switch/element`, `/theme-switch/define`).
+
+- `<kazoku-theme-switch>`: Light, Dark and Auto as 48 px buttons. It writes the choice as `data-theme` on a `target` (the page's `<html>` by default; Auto removes the attribute so the device decides), and sends `kazoku-themechange` with `{ choice, scheme, reason, target }` (reasons `init`, `user`, `set`, `system`, `external`).
+- It remembers the choice in the address (`address`, `address-key`) and in `localStorage` (`storage`, in a try/catch: a browser that keeps nothing still switches). Read in the order address, store, `value`, the target's own `data-theme`.
+- Another writer of the target's `data-theme` moves the switch with it, and a change of the device's colours is an event while on Auto. `modes="light dark"` leaves Auto out. `target` is found in the switch's own tree first, so it works inside a shadow root.
+- The element is light or dark with the page's `data-theme`, not only the device's, so it is dark in a page forced dark on a light device. Labels in English and Japanese. Under a strict `style-src`, like the view controls.
+- The pure entry (`readTheme`, `applyTheme`, `resolveTheme`, `themeOf`, `parseModes`, `parseTheme`, the words) imports on a server. Docs: `docs/theme-switch.md`. The demo has a switch in its header and tells the view controls.
+- The view controls are unchanged.
+
+## [0.3.1] - 2026-11-01
+
+- The styles now pass a strict Content-Security-Policy. `<kazoku-view-controls>` adopts its styles as a constructable stylesheet (`adoptedStyleSheets`), which `style-src 'self'` allows with no `'unsafe-inline'` and no hash; before, it wrote a `<style>` into its shadow root and a strict `style-src` blocked it. Elements with the same styles share one sheet.
+- A browser without constructable stylesheets gets the `<style>` as before, now carrying the element's `nonce` (`<kazoku-view-controls nonce="...">` or `element.nonce`), so a page with `style-src 'nonce-...'` allows it.
+- What a page needs is in `docs/csp.md`. The demo has `csp.html` (`style-src 'self'`) and `csp-nonce.html`, both with `?fallback` to force the `<style>` route, and `e2e/csp.demo.mjs` plays them in Chromium and WebKit.
+- Defaults and the look are unchanged.
+
 ## [0.3.0] - 2026-11-01
 
 - Zoom about a point of your own: the `anchor` attribute (`x,y`), the `element.anchor` setter and the controller's `anchor` member and option take a point in CSS pixels from the view's middle at Fit. The + and - buttons, the 2x button and the + and - keys zoom about it, and it stays fixed on screen within a pixel; wheel, pinch and double tap still zoom about the pointer. With no anchor they zoom about the middle, as before. `zoomAt` and `zoomBy` with no point use it.

package/README.md

@@ -2,26 +2,36 @@
 
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/hero-dark.webp">
-<img alt="The demo: a white card with a blue circle and a black triangle, turned a little and tipped, in a frame with a dotted floor. Under it the view controls: Angle and Tilt sliders, Auto-turn and Front buttons, zoom out, 2 times, zoom in and Fit, four arrows to move the zoomed view, and the Move and Turn choice for a drag." src="https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/hero-light.webp" width="720">
+<img alt="The demo: in its header the English and 日本語 choice and the Light, Dark and Auto switch; below, a white card with a blue circle and a black triangle, turned a little and tipped, in a frame with a dotted floor. Under it the view controls: Angle and Tilt sliders, Auto-turn and Front buttons, zoom out, 2 times, zoom in and Fit, four arrows to move the zoomed view, and the Move and Turn choice for a drag." src="https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/hero-light.webp" width="720">
 </picture>
 
 The family's shared interface parts, as their own versioned package: one part per subpath, so a page loads only what it uses. No runtime dependencies, MIT.
 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/) · [Labels, English and 日本語](docs/labels.md) · [Changelog](CHANGELOG.md)
+[Demo](https://johnmorrisdotca.github.io/kazoku-ui/) · [Strict-CSP demo](https://johnmorrisdotca.github.io/kazoku-ui/csp.html) · [Theme switch](docs/theme-switch.md) · [Language picker](docs/language-picker.md) · [Address state](docs/address-state.md) · [Save image](docs/save-image.md) · [Content-Security-Policy](docs/csp.md) · [Labels, English and 日本語](docs/labels.md) · [Changelog](CHANGELOG.md)
 
 ```sh
 npm install @johnmorrisdotca/kazoku-ui
 ```
 
-Parts (each its own subpath; later ones: picture-tile pickers, theme swatches with light and dark, the English and 日本語 switch, Help, GitHub and npm pills, Save SVG and PNG, the family's backgrounds):
+Parts (each its own subpath; later ones: picture-tile pickers, Help, GitHub and npm pills, the family's backgrounds):
 
 | Subpath | What it is |
 |---|---|
 | `@johnmorrisdotca/kazoku-ui/view-controls` | The controller, the arithmetic, the address and the labels. Imports on a server. |
 | `@johnmorrisdotca/kazoku-ui/view-controls/element` | The `ViewControlsElement` class (needs a browser). |
 | `@johnmorrisdotca/kazoku-ui/view-controls/define` | Registers `<kazoku-view-controls>` (once, and only if the tag is free). |
+| `@johnmorrisdotca/kazoku-ui/theme-switch` | The theme choices, how one is applied and remembered. Imports on a server. |
+| `@johnmorrisdotca/kazoku-ui/theme-switch/element` | The `ThemeSwitchElement` class (needs a browser). |
+| `@johnmorrisdotca/kazoku-ui/theme-switch/define` | Registers `<kazoku-theme-switch>` (once, and only if the tag is free). |
+| `@johnmorrisdotca/kazoku-ui/language-picker` | The language codes, each language's own name, which one to start in, how one is applied. Imports on a server. |
+| `@johnmorrisdotca/kazoku-ui/language-picker/element` | The `LanguagePickerElement` class (needs a browser). |
+| `@johnmorrisdotca/kazoku-ui/language-picker/define` | Registers `<kazoku-language-picker>` (once, and only if the tag is free). |
+| `@johnmorrisdotca/kazoku-ui/save-image` | The formats, the file name, the size and the functions that render and download a canvas, an SVG or an element as PNG or SVG. Imports on a server. |
+| `@johnmorrisdotca/kazoku-ui/save-image/element` | The `SaveImageElement` class (needs a browser). |
+| `@johnmorrisdotca/kazoku-ui/save-image/define` | Registers `<kazoku-save-image>` (once, and only if the tag is free). |
+| `@johnmorrisdotca/kazoku-ui/address-state` | Choices kept in the address: read, write and subscribe to URL parameters with `replaceState`. No element; imports on a server. |
 
 ## View controls
 
@@ -98,6 +108,8 @@ myPlayButton.onclick = () => view.toggle();
 myZoomIn.onclick = () => view.zoomBy(1.4);
 ```
 
+The automatic turn is idle whenever nothing can see the view: while the `for` element (else the controls) is scrolled out of sight, and while the tab is hidden. Its frame loop is stopped, so no animation frame is asked for and no `kazoku-viewchange` event with reason `auto` is sent; `state.turning` stays true, and the turn goes on from where it was when the view is back (the first frame back only restarts the clock). A page does not need to pause it for these. Without the element, `view.suspendTurn()` and `view.resumeTurn()` do the same for your own visibility test (they nest), and `view.play(seconds)` stops the turn by itself after that many seconds of turning.
+
 Options of `createViewController` that match: `zoom` (`"fit"` or a number), `fitScale`, `ignore`, `anchor`, `keyTilt`, `stopTurn`, `tiltStep`. `anchor`, `keyTilt`, `stopTurn` and `tiltStep` are also members you can change at any time. The controller also has `ignore` (changeable), `fitScale`, `startZoom` (the `zoom` the view opens at) and `setFitScale(n)`, `setStartZoom(zoom)`; `DEFAULT_IGNORE` is the default selector.
 
 ### Buttons and links inside the view
@@ -165,6 +177,7 @@ An `init` event is sent once, a moment after the element connects, with the star
 | `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. |
 | `autoplay` | Turn by itself from the start, unless the reader prefers reduced motion. |
+| `autoplay-for` | Seconds of turning after which the `autoplay` turn stops by itself (as Auto-turn pressed). Left out, it never stops. Time spent paused off screen or in a hidden tab is not counted, and a reader's own Auto-turn press has no limit. |
 | `speed` | Degrees a second (30). |
 | `flat` | The view cannot turn: no angle, tilt, Auto-turn or Front, and a drag moves it. |
 | `tilt-max`, `zoom-min`, `zoom-max` | The limits (30, 1, 5). |
@@ -184,13 +197,76 @@ Only what a reader chose is kept: angle, tilt, zoom and the drag choice. The pan
 
 `customElements.define` throws when a name is taken, and a page can meet that without any fault: two copies of this package (an app and a widget that each bundle one, or two versions), the script loaded twice, or a page that registered the tag to supply its own element. A throw would stop the importing module and the page's script with it. So `define` calls `customElements.get` first and the first definition wins; `defineViewControls(registry?)` returns whether it defined the tag.
 
+## Theme switch
+
+`<kazoku-theme-switch>` is Light, Dark and Auto as one row of 48 px buttons. It writes `data-theme` on the page's `<html>` (or a `target` you name; Auto takes it off, so the device decides), keeps the choice in the address (`address`) and optionally in `localStorage` (`storage`), and sends `kazoku-themechange`.
+
+```html
+<kazoku-theme-switch address storage></kazoku-theme-switch>
+<script type="module">import "@johnmorrisdotca/kazoku-ui/theme-switch/define";</script>
+```
+
+The attributes, the event, the early-apply function for a server or a head script and the CSS to write are in [docs/theme-switch.md](docs/theme-switch.md). The demo has one in its header.
+
+## Language picker
+
+`<kazoku-language-picker languages="en ja">` is a button for each language the page lists, each in its own name (English, 日本語). It writes `lang` on the page's `<html>` (or a `target`), keeps the choice in the address (`address`, `?lang=ja`) and optionally in `localStorage` (`storage`), and sends `kazoku-languagechange` with `{ lang, previous, reason, target }`. It starts in the address' language, then the remembered one, then the page's `value`, then the reader's browser languages, then the first code. It translates nothing; the page answers the event.
+
+```html
+<kazoku-language-picker languages="en ja" address storage></kazoku-language-picker>
+<script type="module">import "@johnmorrisdotca/kazoku-ui/language-picker/define";</script>
+```
+
+See [docs/language-picker.md](docs/language-picker.md). The demo's own English and 日本語 choice is one.
+
+## Address state
+
+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
+import { createAddressState } from "@johnmorrisdotca/kazoku-ui/address-state";
+
+const state = createAddressState({ defaults: { size: "m" } });
+state.set("size", "l"); // ?size=l
+state.subscribe(({ key, value }) => redraw(key, value));
+```
+
+See [docs/address-state.md](docs/address-state.md); the demo's `address.html` shows it.
+
+## Save image
+
+`<kazoku-save-image for="art">` is Save PNG and Save SVG for a canvas, an SVG or any element: a canvas at its own pixel size; an SVG as a stand-alone SVG (the styles it is drawn in written into it) or a PNG at `scale` (2 by default); any other element as a PNG, drawn with its computed styles. `name` is the file name, `background` the colour behind a PNG, `manual` makes the picture and the `kazoku-save` event (`{ blob, format, width, height, filename, reason }`) but downloads nothing. `kazoku-saveerror` says why it could not.
+
+```html
+<kazoku-save-image for="jersey" name="senshu-jersey"></kazoku-save-image>
+<script type="module">import "@johnmorrisdotca/kazoku-ui/save-image/define";</script>
+```
+
+What a picture of an element cannot carry (web fonts, `::before`, cross-origin images), the element-free `renderImage` and `saveImage`, and the one `img-src data:` a strict policy needs are in [docs/save-image.md](docs/save-image.md); the demo's `save-image.html` saves all three kinds.
+
+## One release workflow for the family's packages
+
+`.github/workflows/reusable-release.yml` is the release written once: from main, the tag must equal `package.json`'s version, the repo's check script runs, a version already on npm is skipped, the `v<version>` tag is made if missing, and `npm publish --provenance` runs by trusted publishing (no token). A package repo's `release.yml` calls it:
+
+```yaml
+jobs:
+  release:
+    uses: johnmorrisdotca/kazoku-ui/.github/workflows/reusable-release.yml@v0.7.2
+```
+
+npm accepts a called workflow: the trusted-publisher entry on npmjs.com names the **calling** file (`release.yml`), and `id-token: write` goes on both. To move a repo over, keep its file name `release.yml`, replace the body with the call, and pin to a released tag. The inputs, the sources and the steps are in [docs/release-workflow.md](docs/release-workflow.md).
+
+## Content-Security-Policy
+
+The styles are adopted as a constructable stylesheet (`adoptedStyleSheets`), so a page with `style-src 'self'` and no `'unsafe-inline'` needs no hash and no allowance. A browser without it gets a `<style>` carrying the element's `nonce`. What a page needs is in [docs/csp.md](docs/csp.md), and the demo's `csp.html` runs under a strict policy.
+
 ## Size
 
-Gzipped, unbundled: the element and its definition about 5.0 KB, the controller 4.3 KB, the maths 1.4 KB, the address 1.2 KB, the labels 0.7 KB and the styles 1.6 KB (`pnpm test:package` prints them). Nothing is loaded from the network.
+Gzipped, unbundled. View controls: the element and its definition about 5.0 KB, the controller 4.3 KB, the maths 1.4 KB, the address 1.2 KB, the labels 0.7 KB and the styles 1.6 KB. Theme switch: the element and its definition 3.3 KB, the choices 1.0 KB, the labels 0.3 KB and the styles 0.3 KB. Language picker: the element and its definition 2.8 KB, the codes and names 1.7 KB, the labels 0.3 KB. Save image: the element and its definition 3.0 KB, the rendering 3.6 KB, the formats and file names 1.0 KB, the labels 0.4 KB. Address state: 2.1 KB. Shared by parts: the style adoption 0.8 KB, the base styles 1.0 KB, the page's colours 0.5 KB and the target and the store 0.6 KB. `pnpm test:package` prints them. Nothing is loaded from the network.
 
 ## Checks
 
-`pnpm check` (lint, types, 36 unit tests of the maths, the address, the controller and the package, the build and the packed package), and `pnpm test:demo` (the demo in Chromium and WebKit at a phone's width and a desk's: the controls in the first screen, a toggle during Auto-turn leaves the angle advancing, a button or link inside the view still clicks while a drag turns it, the opening zoom and fit scale, zoom about the pointer, 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).
+`pnpm check` (lint, types, 75 unit tests of the maths, the address, the controller and the package, the build and the packed package), and `pnpm test:demo` (the demo in Chromium and WebKit at a phone's width and a desk's: the controls in the first screen, a toggle during Auto-turn leaves the angle advancing, a button or link inside the view still clicks while a drag turns it, the opening zoom and fit scale, zoom about the pointer, 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`).
 
 ## Not yet
 

package/dist/address-state/address.d.ts

@@ -0,0 +1,76 @@
+/** What a parameter may be set to. `null` and `undefined` take it off the address. */
+export type AddressValue = string | number | null | undefined;
+/** The part of `window` the address needs: where we are, and how to change it without a history entry. */
+export interface AddressHost {
+    location: {
+        search: string;
+        pathname: string;
+        hash: string;
+    };
+    history: {
+        state: unknown;
+        replaceState(state: unknown, unused: string, url: string): void;
+    };
+    addEventListener?(type: "popstate", listener: () => void): void;
+    removeEventListener?(type: "popstate", listener: () => void): void;
+}
+/** The parameters of an address' search string. A repeated one keeps its first value. */
+export declare function readParams(search?: string): Record<string, string>;
+/** One parameter of an address' search string, or `null`. */
+export declare function readParam(key: string, search?: string): string | null;
+/**
+ * A search string with `changes` made to it: a value sets the parameter, `null` or `undefined` takes it off, and a value equal to that key's entry in `defaults` takes it off too
+ * (a choice at its start leaves the address plain). Other parameters are kept in their order. The result is `?a=1` or an empty string.
+ */
+export declare function applyParams(search: string, changes: Readonly<Record<string, AddressValue>>, defaults?: Readonly<Record<string, string>>): string;
+export interface AddressWriterOptions {
+    /** Milliseconds a write waits so that many changes become one: Safari stops a page that changes its address more than a hundred times in thirty seconds. 250 by default; 0 writes at once. */
+    delay?: number;
+    host?: AddressHost;
+}
+export interface AddressWriter {
+    /** Asks for the address to become `compute(its search string now)`. Calls inside the delay are one write, and `compute` is the latest, run when the time is up. */
+    write(compute: (search: string) => string): void;
+    /** Writes now what is waiting. */
+    flush(): void;
+    /** Drops what is waiting. */
+    cancel(): void;
+}
+/** Writes the address in place (`replaceState`), the pathname and hash kept. A page that cannot change its address (a sandboxed frame) is left as it is: nothing throws. */
+export declare function createAddressWriter(options?: AddressWriterOptions): AddressWriter;
+/** What a subscriber is told. */
+export interface AddressChange {
+    key: string;
+    /** What the address holds for the key now: the string, or `null` when it is not there. */
+    value: string | null;
+    /** What it held before; `null` when it was not there. */
+    previous: string | null;
+    /** `set` (a `set`, `setMany` or `remove` on a state of this page) or `navigation` (the reader went back or forward to another address). */
+    source: "set" | "navigation";
+}
+export interface AddressStateOptions {
+    /** A key's start: a value equal to it is left off the address, and `get` gives it when the address has none. */
+    defaults?: Readonly<Record<string, string>>;
+    /** As for `createAddressWriter`. */
+    delay?: number;
+    host?: AddressHost;
+}
+export interface AddressState {
+    /** The key's value as the page will have it (a change still waiting included), else its default, else `null`. */
+    get(key: string): string | null;
+    /** Whether the address (or a change waiting) holds the key. */
+    has(key: string): boolean;
+    /** Every parameter, as `get` sees them. */
+    all(): Record<string, string>;
+    /** Sets a key; `null`, `undefined` or the key's default takes it off. Subscribers hear it now; the address is written after the delay. */
+    set(key: string, value: AddressValue): void;
+    setMany(values: Readonly<Record<string, AddressValue>>): void;
+    remove(key: string): void;
+    /** Hears every change to the address made through a state of this page, and the reader going back or forward. `keys` limits it to those keys. Returns the way to stop. */
+    subscribe(listener: (change: AddressChange) => void, keys?: readonly string[]): () => void;
+    /** Writes what is waiting. */
+    flush(): void;
+    /** Writes what is waiting and stops listening for back and forward. */
+    destroy(): void;
+}
+export declare function createAddressState(options?: AddressStateOptions): AddressState;

package/dist/address-state/address.js

@@ -0,0 +1,171 @@
+// Choices kept in the page's address, without an element: read, write and watch the parameters of `?a=1&b=2` with `replaceState` (no history entry for a choice).
+// Every function that touches the page takes a `host` (the `window` by default), so a test can give it a stand-in. Nothing here touches the DOM until it is called.
+/** The parameters of an address' search string. A repeated one keeps its first value. */
+export function readParams(search = globalThis.location?.search ?? "") {
+    const found = {};
+    for (const [key, value] of new URLSearchParams(search))
+        if (!(key in found))
+            found[key] = value;
+    return found;
+}
+/** One parameter of an address' search string, or `null`. */
+export function readParam(key, search = globalThis.location?.search ?? "") {
+    return new URLSearchParams(search).get(key);
+}
+/**
+ * A search string with `changes` made to it: a value sets the parameter, `null` or `undefined` takes it off, and a value equal to that key's entry in `defaults` takes it off too
+ * (a choice at its start leaves the address plain). Other parameters are kept in their order. The result is `?a=1` or an empty string.
+ */
+export function applyParams(search, changes, defaults = {}) {
+    const query = new URLSearchParams(search);
+    for (const [key, value] of Object.entries(changes)) {
+        if (value === null || value === undefined || String(value) === defaults[key])
+            query.delete(key);
+        else
+            query.set(key, String(value));
+    }
+    return query.size > 0 ? `?${query}` : "";
+}
+/** Writes the address in place (`replaceState`), the pathname and hash kept. A page that cannot change its address (a sandboxed frame) is left as it is: nothing throws. */
+export function createAddressWriter(options = {}) {
+    const delay = options.delay ?? 250;
+    let timer;
+    let latest;
+    const run = () => {
+        const compute = latest;
+        latest = undefined;
+        if (compute === undefined)
+            return;
+        try {
+            const host = options.host ?? globalThis;
+            const next = compute(host.location.search);
+            if (next !== host.location.search)
+                host.history.replaceState(host.history.state, "", `${host.location.pathname}${next}${host.location.hash}`);
+        }
+        catch {
+            /* an address that cannot be changed: the choices still work */
+        }
+    };
+    const clear = () => {
+        if (timer !== undefined)
+            globalThis.clearTimeout(timer);
+        timer = undefined;
+    };
+    return {
+        write(compute) {
+            latest = compute;
+            if (delay <= 0)
+                return run();
+            if (timer !== undefined)
+                return;
+            timer = globalThis.setTimeout(() => {
+                timer = undefined;
+                run();
+            }, delay);
+        },
+        flush() {
+            clear();
+            run();
+        },
+        cancel() {
+            clear();
+            latest = undefined;
+        },
+    };
+}
+const rooms = new WeakMap();
+function roomOf(host) {
+    let room = rooms.get(host);
+    if (room === undefined) {
+        const made = {
+            listeners: new Set(),
+            seen: readParams(host.location.search),
+            attached: false,
+            onNavigation: () => {
+                const now = readParams(host.location.search);
+                const before = made.seen;
+                made.seen = now;
+                for (const key of new Set([...Object.keys(before), ...Object.keys(now)])) {
+                    if (before[key] !== now[key])
+                        tell(made, { key, value: now[key] ?? null, previous: before[key] ?? null, source: "navigation" });
+                }
+            },
+        };
+        rooms.set(host, (room = made));
+    }
+    return room;
+}
+function tell(room, change) {
+    for (const listener of [...room.listeners])
+        if (listener.keys === undefined || listener.keys.includes(change.key))
+            listener.run(change);
+}
+export function createAddressState(options = {}) {
+    const host = options.host ?? globalThis;
+    const defaults = options.defaults ?? {};
+    const writer = createAddressWriter({ ...(options.delay !== undefined ? { delay: options.delay } : {}), host });
+    const room = roomOf(host);
+    /** What was asked and has not been written yet: a key and its value, `null` for off. */
+    const queue = new Map();
+    const mine = new Set();
+    const held = (key) => (queue.has(key) ? queue.get(key) : (readParams(host.location.search)[key] ?? null));
+    const detach = (listener) => {
+        mine.delete(listener);
+        room.listeners.delete(listener);
+        if (room.listeners.size === 0 && room.attached) {
+            host.removeEventListener?.("popstate", room.onNavigation);
+            room.attached = false;
+        }
+    };
+    const state = {
+        get: (key) => held(key) ?? defaults[key] ?? null,
+        has: (key) => held(key) !== null,
+        all() {
+            const now = { ...readParams(host.location.search) };
+            for (const [key, value] of queue) {
+                if (value === null)
+                    delete now[key];
+                else
+                    now[key] = value;
+            }
+            return now;
+        },
+        set: (key, value) => state.setMany({ [key]: value }),
+        setMany(values) {
+            const changes = [];
+            for (const [key, raw] of Object.entries(values)) {
+                const value = raw === null || raw === undefined || String(raw) === defaults[key] ? null : String(raw);
+                const previous = held(key);
+                queue.set(key, value);
+                if (value !== previous)
+                    changes.push({ key, value, previous, source: "set" });
+            }
+            writer.write((search) => {
+                const next = applyParams(search, Object.fromEntries(queue), defaults);
+                queue.clear();
+                room.seen = readParams(next);
+                return next;
+            });
+            for (const change of changes)
+                tell(room, change);
+        },
+        remove: (key) => state.set(key, null),
+        subscribe(run, keys) {
+            const listener = { run, keys };
+            mine.add(listener);
+            room.listeners.add(listener);
+            if (!room.attached) {
+                room.attached = true;
+                host.addEventListener?.("popstate", room.onNavigation);
+            }
+            return () => detach(listener);
+        },
+        flush: () => writer.flush(),
+        destroy() {
+            writer.flush();
+            for (const listener of [...mine])
+                detach(listener);
+        },
+    };
+    return state;
+}

package/dist/address-state/index.d.ts

@@ -0,0 +1 @@
+export { applyParams, createAddressState, createAddressWriter, readParam, readParams, type AddressChange, type AddressHost, type AddressState, type AddressStateOptions, type AddressValue, type AddressWriter, type AddressWriterOptions } from "./address.ts";

package/dist/address-state/index.js

@@ -0,0 +1,2 @@
+// Choices kept in the address: read, write and watch URL parameters with `replaceState`. No element and no DOM at import, so it imports on a server.
+export { applyParams, createAddressState, createAddressWriter, readParam, readParams } from "./address.js";

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 /** The subpaths of the parts, in the order they were added. */
-export declare const PARTS: readonly ["view-controls"];
+export declare const PARTS: readonly ["view-controls", "theme-switch", "language-picker", "address-state", "save-image"];
 export type Part = (typeof PARTS)[number];

package/dist/index.js

@@ -1,3 +1,3 @@
 // Kazoku UI 家族: the family's shared interface parts, each its own subpath so a page loads only what it uses.
 /** The subpaths of the parts, in the order they were added. */
-export const PARTS = ["view-controls"];
+export const PARTS = ["view-controls", "theme-switch", "language-picker", "address-state", "save-image"];

package/dist/language-picker/define.d.ts

@@ -0,0 +1 @@
+export declare function defineLanguagePicker(registry?: CustomElementRegistry): boolean;

package/dist/language-picker/define.js

@@ -0,0 +1,9 @@
+// Importing this registers <kazoku-language-picker>, unless the tag is already taken (the first definition wins; see view-controls/define.ts for why a taken tag is left alone).
+import { LanguagePickerElement, TAG } from "./element.js";
+export function defineLanguagePicker(registry = customElements) {
+    if (registry.get(TAG) !== undefined)
+        return false;
+    registry.define(TAG, LanguagePickerElement);
+    return true;
+}
+defineLanguagePicker();

package/dist/language-picker/element.d.ts

@@ -0,0 +1,39 @@
+import { EVENT, TAG } from "./index.ts";
+import { type PickerWords } from "./words.ts";
+export { EVENT, TAG };
+/** What the `kazoku-languagechange` event carries in `detail`. */
+export interface LanguageChangeDetail {
+    /** The language now chosen: one of the codes the page gave, lower case ("en", "ja"). */
+    lang: string;
+    /** The one before; `undefined` at `init`. */
+    previous: string | undefined;
+    /** `init` (once, a moment after it connects), `user` (a button), `set` (the `value` property or attribute) or `external` (something else wrote the target's `lang`). */
+    reason: "init" | "user" | "set" | "external";
+    /** The element the choice is written on. */
+    target: Element;
+}
+/**
+ * Attributes: `languages` (the codes, `en ja` by default), `value` (the language to start in), `target` (a CSS selector for the element that gets `lang`; the page's <html>
+ * by default), `address` (keep the choice in `?lang=`, or the key `address-key` names), `storage` (also remember it in localStorage under that key; a bare `storage` uses
+ * `kazoku-lang`), `theme` (`light` or `dark`: its own look). The start is read, in this order, from the address, the store, `value`, the reader's languages
+ * (`navigator.languages`), the target's own `lang`, then the first code.
+ */
+export declare class LanguagePickerElement extends HTMLElement {
+    #private;
+    static observedAttributes: string[];
+    constructor();
+    /** The language now chosen. Setting it applies it (event reason `set`); a code that is not in `languages` is ignored. */
+    get value(): string;
+    set value(code: string);
+    /** The codes the picker offers. */
+    get languages(): readonly string[];
+    get target(): Element | undefined;
+    set target(element: Element | undefined);
+    /** Your own names over the family's, for example `{ fr: "Français (Canada)" }`. */
+    set names(names: Record<string, string>);
+    /** Your own words over the language's, for example `{ group: "Choose a language" }`. */
+    set words(words: Partial<PickerWords>);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+}