@johnmorrisdotca/dougu-sports 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -6,6 +6,32 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-14
+
+### Added
+
+- **`bindTurn` takes an emblem object and is light.** `bindTurn(element, TROPHY_HOCKEY_CUP, options)` draws and turns the emblem it is given with its own `frame` and imports neither a drawing nor the registry, so a bundle of `bindTurn` and one cup is about 9.4 kB gzipped (the turning is about 2.5 kB of it), where it was about 81 kB. `test/size.test.ts` holds it to 10 kB, and the other emblems stay tree-shakeable.
+- **`ready`** on the controller `bindTurn` returns: a promise that resolves when the emblem is drawn and bound (already, for an emblem object) and rejects for an id that names nothing.
+
+### Changed
+
+- **`bindTurn` of `./turn` loads the registry only for an id.** An id (`"trophy:tennis-cup"`) is read from the registry, which `bindTurn` now imports on demand (a dynamic import, a chunk of its own in a bundler) instead of at the top. The first id bound is drawn when `ready` resolves, not before; later ones at once. `bindTurn` of the main entry (`@johnmorrisdotca/dougu-sports`) has the registry already and draws an id at once, as before. New modules: `src/turn-registry.ts` (what is loaded) and `src/turn-full.ts` (the main entry's `bindTurn`).
+
+## [0.7.3] - 2026-10-14
+
+The repository's own tooling is TypeScript. No change to the package: the same files are published, and the pictures are byte for byte the same.
+
+### Changed
+
+- **The scripts, the browser tests, the test helpers and the demo's source are `.ts`.** `scripts/*.ts` (build, gallery, package check, README examples, release notes, contact sheets, the pictures script, the demo's server and page maker), `e2e/*.demo.ts`, `playwright.config.ts` and `test/pieces-gallery.test.ts` were `.mjs` or `.js`. They run with Node's own type stripping, with no `tsx` and no build step, so `package.json`'s scripts call the `.ts` files directly. The shared family files stay as they are, byte for byte: `scripts/family-template.mjs` and `scripts/family-readme.mjs` (plain JavaScript, with the types of the template written by hand in `scripts/family-template.d.mts`) and `scripts/family-backgrounds.ts`.
+- **`pnpm typecheck` checks all of it.** `tsconfig.check.json` covers `src` and `test`, the new `tsconfig.tools.json` covers `scripts`, `e2e` and the Playwright config (with the browser's types, since the tests and the pictures script run code in the page), and the new `tsconfig.demo.json` covers `demo`. The syntax is the erasable kind only (`erasableSyntaxOnly` was already on), with `import type` and `.ts` extensions.
+- **The demo's scripts are `demo/*.ts`, built with esbuild.** A browser cannot run TypeScript, so `scripts/page.ts` builds each one into `demo.js`, `compose.js` and `gallery.js` for the dev server (on each request) and for `pnpm site`. A script imports the package from `../src/index.ts`, so that it is type-checked against the real source; the build changes that one import to `./dist/index.js`, the built package, as before. The page is the same.
+- **Node.** Working on the repository needs Node 22.18 or later (where type stripping is on by default); CI already runs 22 and 24. `engines` stays `>=22`, because the published package is plain JavaScript and needs no more. `CONTRIBUTING.md` says so.
+
+### Fixed
+
+- **The belts note counted the two-colour pairs wrong.** `docs/japanese-sports.md` and `docs/japanese-sports.ja.md` said the IJF names "these four pairs" under a table of five. The IJF's page names four (white-yellow, yellow-orange, orange-green, green-blue); blue-brown is drawn for completeness and no source found names it. Both pages now say that.
+
 ## [0.7.2] - 2026-10-14
 
 The docs are one language to a page. No change to the pictures; the only change to the package is one English description.

package/NOTICE.md

@@ -72,4 +72,4 @@ Facts only: a dimension or a mass is a fact, not a work. The NHL's puck rule was
 | What | Made from | Terms |
 | --- | --- | --- |
 | The demo's page | Written for this package, with the family stylesheet `demo/family.css` | MIT |
-| The README's pictures (`docs/images`) | Taken by `scripts/screenshots.mjs` from the demo, which draws the package's own emblems | MIT |
+| The README's pictures (`docs/images`) | Taken by `scripts/screenshots.ts` from the demo, which draws the package's own emblems | MIT |

package/README.md

@@ -137,7 +137,7 @@ The alias is a name in your `package.json` only: the same package, the same code
 | --- | --- |
 | `@johnmorrisdotca/dougu-sports` | The full registry: every emblem by id, the functions, and each emblem as a constant |
 | `@johnmorrisdotca/dougu-sports/emblems` | `renderEmblem`, the ids and the types, with no single drawing imported by name |
-| `@johnmorrisdotca/dougu-sports/turn` | `emblemFrame`, `ballFrame` and `bindTurn` |
+| `@johnmorrisdotca/dougu-sports/turn` | `emblemFrame`, `ballFrame` and `bindTurn`; `bindTurn` with an emblem object takes nothing else with it |
 | `@johnmorrisdotca/dougu-sports/<group>/<name>` | One emblem, alone: `trophy/hockey-cup`, `medal/gold`, `crest/shield`, `sport/nhl`, `award/crown`, `ball/soccer`, `pennant/championship`, `gear/<name>` |
 
 ### One emblem and nothing else
@@ -379,12 +379,13 @@ Both are one SVG string in the page's text colour, with a title and a descriptio
 
 ```js no-run
 import { bindTurn } from "@johnmorrisdotca/dougu-sports/turn";
+import { TROPHY_TENNIS_CUP } from "@johnmorrisdotca/dougu-sports/trophy/tennis-cup";
 
-const turner = bindTurn(document.getElementById("cup"), "trophy:tennis-cup", { size: 160, speed: 36 });
+const turner = bindTurn(document.getElementById("cup"), TROPHY_TENNIS_CUP, { size: 160, speed: 36 });
 document.getElementById("spin").onclick = () => turner.togglePlay();
 ```
 
-A drag turns it, the arrow keys turn it, Space starts and stops an auto-turn, and nothing moves until you ask; see [docs/turning.md](./docs/turning.md).
+A drag turns it, the arrow keys turn it, Space starts and stops an auto-turn, and nothing moves until you ask. Pass the emblem itself and the page carries the turning and that one emblem and nothing else (a cup and the turning are about 9 kB gzipped); pass an id, `"trophy:tennis-cup"`, and the registry is loaded when it is needed. See [docs/turning.md](./docs/turning.md).
 
 ### In React, Vue and the rest
 
@@ -434,7 +435,7 @@ The thirty-eight sports the ball, gear and sport emblems are made for are `SPORT
 | `sportIcon(sport, options?)` | The pictogram of a sport, by the names of `SPORT_NAMES`; an unknown sport is an error |
 | `lineup(ids, options?)` | Several balls side by side, at their true relative sizes (or all as large as the largest) |
 | `emblemFrame(ref, options?)` | An emblem turned by `yaw` and `pitch` degrees (and `roll` for a ball) |
-| `bindTurn(element, ref, options?)` | Draws an emblem into an element and lets a drag, the arrow keys, Space or a clock turn it; returns a controller with `angles`, `playing`, `turnable`, `setAngles`, `update`, `play`, `pause`, `togglePlay` and `destroy` |
+| `bindTurn(element, ref, options?)` | Draws an emblem (the emblem itself, or its id) into an element and lets a drag, the arrow keys, Space or a clock turn it; returns a controller with `angles`, `playing`, `turnable`, `ready`, `setAngles`, `update`, `play`, `pause`, `togglePlay` and `destroy` |
 | `emblemDataUri(ref, options?)` | An emblem as a `data:image/svg+xml;utf8,…` address for an `<img>`, a CSS background or a canvas, with the ink made a colour (`color`, or the theme's) |
 | `emblemSprite(ids, options?)` | A hidden sheet of `<symbol>`s with unique ids, and `use(id, { size, class, title })` for the markup of each use |
 | `sportEquipment(sport)` | The ball, gear, trophy and medal of a sport, as ids of the registry |
@@ -604,7 +605,7 @@ Bug reports and ideas go in the [issues](https://github.com/johnmorrisdotca/doug
 
 ## Changes
 
-See [CHANGELOG.md](./CHANGELOG.md). 0.7.2 makes every docs page single-language (a page in Japanese beside each page that had Japanese words in it, and a test that holds them apart), with no change to the pictures; 0.7.1 puts real countries (Canada, Japan) in the crest and puck examples in place of made-up teams, with no change to the code; 0.7.0 gives the national volleyballs layouts that tell them apart (Japan a crimson band, Poland white above and red below, the USA a navy field), strengthens the 2010-style grooved soccer ball, and adds six pictures of how the judo belt is tied, `gear:obi-step-1` to `gear:obi-step-6` (269 emblems: [docs/obi-steps.md](./docs/obi-steps.md)); 0.6.0 gives the judo suit and the karate suit their sleeves (a judogi has no short ones: they reach the wrist) and adds the judogi seen from behind with the IJF-style back number, a family name and a country code on a patch, with a `backnumber` option (269 emblems: [docs/judogi-back.md](./docs/judogi-back.md)); 0.5.1 redraws the judo suit, the belt and the football pictograms and adds the blue and folded suits and the belts of every grade (261 emblems: [docs/japanese-sports.md](./docs/japanese-sports.md)); 0.5.0 adds fifty balls: vintage leather soccer balls, era-style and shop-wall soccer balls, baseballs of other threads and volleyballs in national colours, with a `colors` option (244 emblems: [docs/vintage-balls.md](./docs/vintage-balls.md)); 0.4.0 adds eight printed pucks and a `face` option (194 emblems: [docs/pucks.md](./docs/pucks.md)); 0.3.0 adds nineteen soccer balls (26, 18, 14, 12 and 6 panels, winter orange and high-visibility yellow, futsal and beach soccer: 186 emblems); 0.2.1 draws every ball and implement to the rulebook's proportions; 0.2.0 is 167 emblems, every one drawn here, with the Japanese sports, engraving, a turn for every emblem and the compose helpers; 0.1.0 brought the first full set of 148; 0.0.1 was the first preview.
+See [CHANGELOG.md](./CHANGELOG.md). 0.8.0 makes `bindTurn` light: it takes an emblem object and then needs no registry, so a turnable cup is about 9.4 kB gzipped instead of about 81 kB, and an id loads the registry on demand; 0.7.3 turns the build, docs and picture scripts, the browser tests and the demo's source from JavaScript into TypeScript, with no change to the package; 0.7.2 makes every docs page single-language (a page in Japanese beside each page that had Japanese words in it, and a test that holds them apart), with no change to the pictures; 0.7.1 puts real countries (Canada, Japan) in the crest and puck examples in place of made-up teams, with no change to the code; 0.7.0 gives the national volleyballs layouts that tell them apart (Japan a crimson band, Poland white above and red below, the USA a navy field), strengthens the 2010-style grooved soccer ball, and adds six pictures of how the judo belt is tied, `gear:obi-step-1` to `gear:obi-step-6` (269 emblems: [docs/obi-steps.md](./docs/obi-steps.md)); 0.6.0 gives the judo suit and the karate suit their sleeves (a judogi has no short ones: they reach the wrist) and adds the judogi seen from behind with the IJF-style back number, a family name and a country code on a patch, with a `backnumber` option (269 emblems: [docs/judogi-back.md](./docs/judogi-back.md)); 0.5.1 redraws the judo suit, the belt and the football pictograms and adds the blue and folded suits and the belts of every grade (261 emblems: [docs/japanese-sports.md](./docs/japanese-sports.md)); 0.5.0 adds fifty balls: vintage leather soccer balls, era-style and shop-wall soccer balls, baseballs of other threads and volleyballs in national colours, with a `colors` option (244 emblems: [docs/vintage-balls.md](./docs/vintage-balls.md)); 0.4.0 adds eight printed pucks and a `face` option (194 emblems: [docs/pucks.md](./docs/pucks.md)); 0.3.0 adds nineteen soccer balls (26, 18, 14, 12 and 6 panels, winter orange and high-visibility yellow, futsal and beach soccer: 186 emblems); 0.2.1 draws every ball and implement to the rulebook's proportions; 0.2.0 is 167 emblems, every one drawn here, with the Japanese sports, engraving, a turn for every emblem and the compose helpers; 0.1.0 brought the first full set of 148; 0.0.1 was the first preview.
 
 ## Credits
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export * from "./emblems-entry.ts";
 export { ballFrame, emblemFrame } from "./emblems/emblem.api.ts";
-export { bindTurn } from "./turn-control.ts";
+export { bindTurn } from "./turn-full.ts";
 export type { TurnAngles, TurnContainer, TurnControlOptions, TurnController, TurnEvent } from "./turn-control.ts";
 export { EMBLEM_TABLE } from "./emblems/emblem.registry.ts";
 export { AWARD_MEDAL } from "./emblems/award/medal.ts";

package/dist/index.js

@@ -2,7 +2,7 @@
 // its own module (`@johnmorrisdotca/dougu-sports/trophy/hockey-cup`), and for the functions alone `@johnmorrisdotca/dougu-sports/emblems`.
 export * from "./emblems-entry.js";
 export { ballFrame, emblemFrame } from "./emblems/emblem.api.js";
-export { bindTurn } from "./turn-control.js";
+export { bindTurn } from "./turn-full.js";
 export { EMBLEM_TABLE } from "./emblems/emblem.registry.js";
 export { AWARD_MEDAL } from "./emblems/award/medal.js";
 export { AWARD_BADGE } from "./emblems/award/badge.js";

package/dist/turn-control.d.ts

@@ -1,5 +1,13 @@
-import { type EmblemRef } from "./emblems/emblem.api.ts";
-import type { FrameOptions } from "./emblems/emblem.core.ts";
+import type { EmblemRef } from "./emblems/emblem.api.ts";
+import type { Emblem, FrameOptions } from "./emblems/emblem.core.ts";
+/** What reading an id needs of the registry: `emblemOf`, `renderEmblem` and `emblemFrame` of `emblem.api`. The main entry hands them to `bindTurn` itself; `./turn` loads them when an id is bound. */
+export interface TurnRegistry {
+    emblemOf(ref: EmblemRef): {
+        emblem: Emblem;
+    };
+    renderEmblem(ref: EmblemRef, options?: FrameOptions): string;
+    emblemFrame(ref: EmblemRef, options?: FrameOptions): string;
+}
 /** The three angles of a turn, in degrees. */
 export interface TurnAngles {
     /** About the vertical axis, from -180 (excluded) to 180. */
@@ -37,8 +45,13 @@ export interface TurnController {
     readonly angles: TurnAngles;
     /** Whether the auto-turn is running. */
     readonly playing: boolean;
-    /** Whether the emblem now drawn can be turned at all (read from the registry, so an emblem that gains a turn is turnable here without a change). */
+    /** Whether the emblem now drawn can be turned at all (read from the emblem's own frames, so an emblem that gains a turn is turnable here without a change). `false` until an id has loaded; see `ready`. */
     readonly turnable: boolean;
+    /**
+     * Resolves when the emblem is drawn and bound. At once (already resolved) for an emblem object, and for an id from the main entry or once the registry has loaded; otherwise after the registry's chunk has loaded.
+     * Rejects for an id that names no emblem.
+     */
+    readonly ready: Promise<void>;
     /** Sets some of the angles (wrapped or clamped as a drag would) and draws. Pauses the auto-turn when `pauseOnInteract` is on. */
     setAngles(angles: Partial<TurnAngles>): void;
     /** Draws another emblem, or the same one with other options, and keeps the angles (unless the options carry some). */
@@ -86,16 +99,22 @@ export interface TurnContainer {
 /** An angle wrapped into -180 (excluded) to 180, as the demo's slider is. */
 export declare function wrapAngle(value: number): number;
 /**
- * Binds an emblem to an element so that it can be turned: it draws `emblemFrame` into `container`, and a drag turns it (left and right are yaw, up and down are pitch, and Shift on a ball is roll), the arrow keys turn
+ * Binds an emblem to an element so that it can be turned: it draws the emblem's `frame` into `container`, and a drag turns it (left and right are yaw, up and down are pitch, and Shift on a ball is roll), the arrow keys turn
  * it, Home or 0 puts it back, and Space starts and stops an auto-turn. An emblem that cannot turn is drawn as it is, and nothing is listened to. Nothing moves by itself: `autoPlay` is off by default and, under
  * `prefers-reduced-motion`, only starts when it is `"force"`. The element gets `touch-action: none`, `user-select: none`, a grab cursor, a tab stop, a role description and a hint; `destroy()` takes them away.
+ *
+ * Pass the emblem itself (`TROPHY_HOCKEY_CUP`, from its own module) and nothing but the turning and that one emblem is in the bundle. Pass an id (`"trophy:hockey-cup"`) and the registry is loaded on
+ * demand: the element is drawn when `ready` resolves, not before. The main entry's `bindTurn` has the registry already and draws an id at once.
  * @example
  * ```ts
  * import { bindTurn } from "@johnmorrisdotca/dougu-sports/turn";
- * const turner = bindTurn(document.getElementById("cup")!, "trophy:tennis-cup", { size: 160 });
+ * import { TROPHY_TENNIS_CUP } from "@johnmorrisdotca/dougu-sports/trophy/tennis-cup";
+ * const turner = bindTurn(document.getElementById("cup")!, TROPHY_TENNIS_CUP, { size: 160 });
  * turner.setAngles({ yaw: 40 });
  * console.log(turner.angles.yaw);
  * // 40
  * ```
  */
 export declare function bindTurn(container: TurnContainer, ref: EmblemRef, options?: TurnControlOptions): TurnController;
+/** `bindTurn` with the registry in hand (or none, to load it when an id is bound): the main entry gives it, so that an id is drawn at once. An emblem object needs neither. */
+export declare function bindTurnWith(registry: TurnRegistry | undefined, container: TurnContainer, ref: EmblemRef, options?: TurnControlOptions): TurnController;

package/dist/turn-control.js

@@ -1,6 +1,3 @@
-// `bindTurn`: an emblem that a pointer, the arrow keys, the Space bar or a clock can turn. It draws `emblemFrame` into an element and listens to that element, and it is a module of its own, so importing an
-// emblem never pulls it in. Nothing here moves by itself: an auto-turn starts only when the caller asks for it, and not at all under `prefers-reduced-motion` unless the caller forces it.
-import { emblemFrame, emblemOf, renderEmblem } from "./emblems/emblem.api.js";
 const WORDS = {
     en: { role: "turnable emblem", hint: "Drag, or use the arrow keys, to turn it. Space starts and stops the turning." },
     ja: { role: "回せるエンブレム", hint: "ドラッグするか矢印キーで回せます。スペースキーで自動回転を始めたり止めたりできます。" },
@@ -13,7 +10,7 @@ export function wrapAngle(value) {
 const finite = (value, fallback) => (typeof value === "number" && Number.isFinite(value) ? value : fallback);
 const clamp = (value, low, high) => Math.max(low, Math.min(high, value));
 const globals = globalThis;
-/** Whether an emblem turns at all, read from the registry's own frames: a turned view that differs from the resting one. An emblem may say so itself with a `turnable` flag. */
+/** Whether an emblem turns at all, read from the emblem's own frames: a turned view that differs from the resting one. An emblem may say so itself with a `turnable` flag. */
 const turns = new WeakMap();
 function canTurn(emblem) {
     const flag = emblem.turnable;
@@ -26,22 +23,41 @@ function canTurn(emblem) {
     }
     return known;
 }
+const fromEmblem = (emblem) => ({ emblem, still: (o) => emblem.svg(o), frame: (o) => emblem.frame(o) });
+const fromId = (registry, ref) => ({ emblem: registry.emblemOf(ref).emblem, still: (o) => registry.renderEmblem(ref, o), frame: (o) => registry.emblemFrame(ref, o) });
+/** The registry, once something has loaded it: later ids are bound at once. */
+let loaded;
+let loading;
+const load = () => {
+    loading ??= import("./turn-registry.js").then((api) => (loaded = api));
+    return loading;
+};
 /**
- * Binds an emblem to an element so that it can be turned: it draws `emblemFrame` into `container`, and a drag turns it (left and right are yaw, up and down are pitch, and Shift on a ball is roll), the arrow keys turn
+ * Binds an emblem to an element so that it can be turned: it draws the emblem's `frame` into `container`, and a drag turns it (left and right are yaw, up and down are pitch, and Shift on a ball is roll), the arrow keys turn
  * it, Home or 0 puts it back, and Space starts and stops an auto-turn. An emblem that cannot turn is drawn as it is, and nothing is listened to. Nothing moves by itself: `autoPlay` is off by default and, under
  * `prefers-reduced-motion`, only starts when it is `"force"`. The element gets `touch-action: none`, `user-select: none`, a grab cursor, a tab stop, a role description and a hint; `destroy()` takes them away.
+ *
+ * Pass the emblem itself (`TROPHY_HOCKEY_CUP`, from its own module) and nothing but the turning and that one emblem is in the bundle. Pass an id (`"trophy:hockey-cup"`) and the registry is loaded on
+ * demand: the element is drawn when `ready` resolves, not before. The main entry's `bindTurn` has the registry already and draws an id at once.
  * @example
  * ```ts
  * import { bindTurn } from "@johnmorrisdotca/dougu-sports/turn";
- * const turner = bindTurn(document.getElementById("cup")!, "trophy:tennis-cup", { size: 160 });
+ * import { TROPHY_TENNIS_CUP } from "@johnmorrisdotca/dougu-sports/trophy/tennis-cup";
+ * const turner = bindTurn(document.getElementById("cup")!, TROPHY_TENNIS_CUP, { size: 160 });
  * turner.setAngles({ yaw: 40 });
  * console.log(turner.angles.yaw);
  * // 40
  * ```
  */
 export function bindTurn(container, ref, options = {}) {
+    return bindTurnWith(undefined, container, ref, options);
+}
+/** `bindTurn` with the registry in hand (or none, to load it when an id is bound): the main entry gives it, so that an id is drawn at once. An emblem object needs neither. */
+export function bindTurnWith(registry, container, ref, options = {}) {
     let current = ref;
-    let emblem = emblemOf(ref).emblem;
+    let drawer;
+    let version = 0;
+    let pending;
     let turnable = false;
     let sensitivity = 1.5;
     let range = [-60, 60];
@@ -95,7 +111,9 @@ export function bindTurn(container, ref, options = {}) {
         }
         const at = angles.yaw === 0 && angles.pitch === 0 && angles.roll === 0;
         // The resting view of an emblem that turns is drawn in the box of the turn too, so that the element is the same size at every angle and a drag does not make the emblem jump or zoom at its first step.
-        container.innerHTML = !turnable ? renderEmblem(current, frame) : at ? renderEmblem(current, { turnBox: true, ...frame }) : emblemFrame(current, { ...frame, ...angles });
+        if (drawer === undefined)
+            return;
+        container.innerHTML = !turnable ? drawer.still(frame) : at ? drawer.still({ turnBox: true, ...frame }) : drawer.frame({ ...frame, ...angles });
     };
     /** One drawing for any number of changes within a frame. */
     const schedule = () => {
@@ -178,7 +196,7 @@ export function bindTurn(container, ref, options = {}) {
         drag.y = y;
         if (dx === 0 && dy === 0)
             return;
-        if (event.shiftKey === true && emblem.kind === "ball")
+        if (event.shiftKey === true && drawer?.emblem.kind === "ball")
             place({ roll: angles.roll + dx, pitch: angles.pitch - dy });
         else
             place({ yaw: angles.yaw + dx, pitch: angles.pitch - dy });
@@ -287,24 +305,46 @@ export function bindTurn(container, ref, options = {}) {
         drag = undefined;
         held = false;
     };
-    const settle = () => {
-        emblem = emblemOf(current).emblem;
-        turnable = canTurn(emblem);
+    const adopt = (next) => {
+        drawer = next;
+        turnable = canTurn(next.emblem);
+        detach();
         if (turnable)
             attach();
-        else {
-            detach();
+        else
             setPlaying(false);
-        }
     };
-    configure(options);
-    place({ yaw: options.yaw, pitch: options.pitch, roll: options.roll });
-    settle();
-    draw();
-    if (turnable && options.autoPlay !== undefined && options.autoPlay !== false) {
+    /** Binds what `current` names: at once for an emblem, or for an id when the registry is in hand; otherwise when it has loaded. Gives the wait, if there is one. */
+    const settle = (first) => {
+        const mine = ++version;
+        const now = current;
+        if (typeof now !== "string")
+            return void adopt(fromEmblem(now));
+        const known = registry ?? loaded;
+        if (known !== undefined)
+            return void adopt(fromId(known, now));
+        return load().then((api) => {
+            if (mine !== version || destroyed)
+                return;
+            adopt(fromId(api, now));
+            draw();
+            if (first)
+                autoStart();
+        });
+    };
+    const autoStart = () => {
+        if (!turnable || options.autoPlay === undefined || options.autoPlay === false)
+            return;
         const reduced = globals.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
         if (options.autoPlay === "force" || !reduced)
             setPlaying(true);
+    };
+    configure(options);
+    place({ yaw: options.yaw, pitch: options.pitch, roll: options.roll });
+    pending = settle(true);
+    if (pending === undefined) {
+        draw();
+        autoStart();
     }
     return {
         get angles() {
@@ -316,6 +356,9 @@ export function bindTurn(container, ref, options = {}) {
         get turnable() {
             return turnable;
         },
+        get ready() {
+            return pending ?? Promise.resolve();
+        },
         setAngles(partial) {
             if (destroyed)
                 return;
@@ -331,9 +374,9 @@ export function bindTurn(container, ref, options = {}) {
             place({ yaw: o.yaw, pitch: o.pitch, roll: o.roll });
             // The pitch the new range allows.
             place({ pitch: angles.pitch });
-            detach();
-            settle();
-            draw();
+            pending = settle(false);
+            if (pending === undefined)
+                draw();
         },
         play() {
             if (!turnable || destroyed)
@@ -355,6 +398,7 @@ export function bindTurn(container, ref, options = {}) {
                 return;
             setPlaying(false);
             destroyed = true;
+            version++;
             if (renderId !== undefined)
                 globals.cancelAnimationFrame?.(renderId);
             renderId = undefined;

package/dist/turn-full.d.ts

@@ -0,0 +1,15 @@
+import { type EmblemRef } from "./emblems/emblem.api.ts";
+import { type TurnContainer, type TurnControlOptions, type TurnController } from "./turn-control.ts";
+/**
+ * Binds an emblem to an element so that a drag, the arrow keys, Space or a clock turn it; see `bindTurn` of `@johnmorrisdotca/dougu-sports/turn`, which takes an emblem object and loads nothing else. This one is
+ * from the main entry: an id is read from the registry and drawn at once, with no `await`.
+ * @example
+ * ```ts
+ * import { bindTurn } from "@johnmorrisdotca/dougu-sports";
+ * const turner = bindTurn(document.getElementById("cup")!, "trophy:tennis-cup", { size: 160 });
+ * turner.setAngles({ yaw: 40 });
+ * console.log(turner.angles.yaw);
+ * // 40
+ * ```
+ */
+export declare function bindTurn(container: TurnContainer, ref: EmblemRef, options?: TurnControlOptions): TurnController;

package/dist/turn-full.js

@@ -0,0 +1,19 @@
+// `bindTurn` of the main entry: the same as the light one of `./turn`, with the registry already in hand, so an id is drawn at once (as it always was) and an emblem object works too. It is a function of its own, so
+// a page that imports only emblems from the main entry does not pull it in; one that imports `bindTurn` from here has the registry in the bundle anyway.
+import { emblemFrame, emblemOf, renderEmblem } from "./emblems/emblem.api.js";
+import { bindTurnWith } from "./turn-control.js";
+/**
+ * Binds an emblem to an element so that a drag, the arrow keys, Space or a clock turn it; see `bindTurn` of `@johnmorrisdotca/dougu-sports/turn`, which takes an emblem object and loads nothing else. This one is
+ * from the main entry: an id is read from the registry and drawn at once, with no `await`.
+ * @example
+ * ```ts
+ * import { bindTurn } from "@johnmorrisdotca/dougu-sports";
+ * const turner = bindTurn(document.getElementById("cup")!, "trophy:tennis-cup", { size: 160 });
+ * turner.setAngles({ yaw: 40 });
+ * console.log(turner.angles.yaw);
+ * // 40
+ * ```
+ */
+export function bindTurn(container, ref, options = {}) {
+    return bindTurnWith({ emblemOf, renderEmblem, emblemFrame }, container, ref, options);
+}

package/dist/turn-registry.d.ts

@@ -0,0 +1 @@
+export { emblemFrame, emblemOf, renderEmblem } from "./emblems/emblem.api.ts";

package/dist/turn-registry.js

@@ -0,0 +1,3 @@
+// What `bindTurn` loads when it is given an id: the three functions that read the registry. A module of its own, so that the dynamic import has a target no static import of `./turn` shares, and a bundler
+// makes it a chunk of its own.
+export { emblemFrame, emblemOf, renderEmblem } from "./emblems/emblem.api.js";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.7.2";
+export declare const VERSION = "0.8.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.7.2";
+export const VERSION = "0.8.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/dougu-sports",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Dougu Sports 道具, sports emblems as SVG strings: trophies, medals, crests, sport icons, and the ball and gear of every sport, in metal, line or flat colour, with optional 3D turning. Light and dark, accessible, tree-shakeable. Zero dependencies.",
   "keywords": [
     "sports",
@@ -113,18 +113,18 @@
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
     "lint": "eslint .",
-    "typecheck": "tsc -p tsconfig.check.json",
-    "test": "node --test test/*.test.ts test/*.test.js",
-    "test:package": "pnpm build && node scripts/check-package.mjs",
-    "test:readme": "pnpm build && node scripts/make-gallery.mjs --check && node scripts/check-readme-examples.mjs",
-    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build && node scripts/check-package.mjs",
+    "typecheck": "tsc -p tsconfig.check.json && tsc -p tsconfig.tools.json && tsc -p tsconfig.demo.json",
+    "test": "node --test test/*.test.ts",
+    "test:package": "pnpm build && node scripts/check-package.ts",
+    "test:readme": "pnpm build && node scripts/make-gallery.ts --check && node scripts/check-readme-examples.ts",
+    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build && node scripts/check-package.ts",
     "prepublishOnly": "pnpm check",
     "family:readme": "node scripts/family-readme.mjs",
-    "dev": "pnpm build && node scripts/dev.mjs",
-    "gallery": "pnpm build && node scripts/make-gallery.mjs",
-    "site": "pnpm build && node scripts/site.mjs",
+    "dev": "pnpm build && node scripts/dev.ts",
+    "gallery": "pnpm build && node scripts/make-gallery.ts",
+    "site": "pnpm build && node scripts/site.ts",
     "test:demo": "pnpm site && playwright test",
-    "screenshots": "pnpm site && node scripts/screenshots.mjs"
+    "screenshots": "pnpm site && node scripts/screenshots.ts"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",