@johnmorrisdotca/uchusen-rockets 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-11-03
+
+- Demo: the rocket, variant, parts, look and view (the From row) are kept in the address with the maker, the Earth and the view controls' choices, each at a default that leaves the address clean, so a link or a reload opens what was on the screen.
+- Demo: kazoku-ui 0.12 (Centre came in 0.11). Once the view is zoomed or moved, a Centre button brings the rocket back to the middle at Fit and the default angle (the keys Home and 0 too). A rocket is thin, so the controls are told its size on the screen (`object-size`) and hold a pan so that at least a quarter of it stays in view. There is no `grab-radius`: a rocket is not round, so the default drag is kept. A browser test drags it far off and presses Centre.
+- The drag rule has its browser check: `e2e/direction.demo.ts` runs kazoku-ui's shared `e2e/ground.mjs` on the Space Shuttle's stack (a plain rocket body has nothing to follow up or down), and reads Starship's camera angle. A drag right moves the surface right, a drag up moves it up, the arrow keys agree and Auto-turn takes the near side to the right.
+- Demo: the Earth behind the rocket takes chikyu-earth 0.10: `max-ratio="1"` instead of sizing the element at half and scaling it, the Sun and the view are set on the same tick (one draw, so the every-fourth-draw workaround is gone), and the page's Content-Security-Policy has no style hash: `style-src 'self'` alone, which a test now holds (a refused stylesheet is an error).
+- The release runs the freeze test before anything is published: `release.yml` calls kazoku-ui's shared release workflow at v0.11.0 with `freeze-command: pnpm test:freeze`.
+- Engines: the parts whose data lists engines but whose drawing has no bell stay dark on purpose, and a test names them (Jupiter-C, Dragon 1, Dragon 2, Cargo Dragon 2, Apollo's service module, the lunar module's ascent stage, Dragon on top of Falcon 9). No source read here gives a Draco or SuperDraco thruster's size, the service propulsion engine's or the A-7's, and a bell's size is never estimated.
+- 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: a reference site made from the source's doc comments (every export has a summary, its parameters, what it returns and an example that runs), thirteen guides with a Japanese twin of each, a code builder page (`builder.html`), eighteen pictures, a longer README, and every release of this changelog dated. `pnpm docs:check` and `pnpm docs:site` are new, and `pnpm test:readme` now runs the guides too. No behaviour changed.
+
 ## [0.3.0] - 2026-11-02
 
 - Falcon 1, and the Falcon 1e that was announced and never flew, drawn by this package's code. Sizes from SpaceX's 2008 user's guide, with Wikipedia's other figures kept beside them. A part placed rather than stacked can now stand above the ground (`strapOn.y`).
@@ -41,12 +52,12 @@
 - Demo: a Background row, None or Earth, beside Look and From, off by default and kept in the address (`?background=earth`). It is the page's own: the embed page and what is copied carry the rocket, and say so. The rocket floats in front of the Earth from [`@johnmorrisdotca/chikyu-earth`](https://www.npmjs.com/package/@johnmorrisdotca/chikyu-earth), turning once in 12 minutes: a line-drawn globe behind Line drawing and Thick lines, one SVG and no canvas, and the realistic Earth behind Painted, a second WebGL context given back when it is left. A person who does not choose it loads nothing of it and pays nothing. It draws 2 or 4 times a second, not at all out of sight, on a hidden tab or under reduced motion, and stops turning when nobody has touched the page for five minutes. `e2e/freeze.demo.ts` holds its budgets, and `pnpm test:freeze` runs that file alone. None of this is in the published package.
 - Demo: kazoku-ui 0.10 (chikyu-earth needs >=0.9.0), with `controls="advanced"` on the bar, so it keeps tilt, Front and the pan pad on show; its `2×` preset is gone, and a double press on the view still goes to 2 times. The Content-Security-Policy's `style-src` gains one hash, for the realistic Earth's inline `<style>`, until chikyu-earth adopts its styles as kazoku-ui does.
 
-## [0.2.2]
+## [0.2.2] - 2026-11-02
 
 - Demo: kazoku-ui 0.7 (a dev dependency, used only by the demo). The demo's strict Content-Security-Policy is now plain `style-src 'self'`: the controls adopt their styles as a constructable stylesheet since kazoku-ui 0.3.1, so the build no longer writes the controls' style text's hash into the page (the `%KAZOKU_STYLE%` step of `scripts/site.ts` is gone). The introduction's own pause (a one-minute timer and a scroll observer in `demo/demo.ts`) is replaced by the controls' `autoplay-for="60"` and their idle-out-of-sight, from kazoku-ui 0.7.1; `docs/element.md` says so.
 - Repository: `release.yml` calls kazoku-ui's shared `reusable-release.yml` (pinned to v0.7.3): the same checks, tag, GitHub release with the tarball and npm publish by trusted publishing; the trusted publisher entry stays `release.yml`. The GitHub release's notes are generated by GitHub until the shared workflow reads `scripts/release-notes.ts`. `AGENTS.md` is written from kazoku-ui's template.
 
-## [0.2.1]
+## [0.2.1] - 2026-11-02
 
 - Fixed: the demo could hang the screen while turning. When the 3D view turned by itself, or glided to a stop after a drag, the controls' change event asked for the next frame while the view's own loop did too, so each frame started two and the number of draws doubled every frame: thousands of draws a second, enough to starve the graphics card (measured in a real browser on a real graphics card: 12,308 draws in 3 seconds, against 181 now at 60 frames a second). One frame is asked for, once.
 - Fixed: every change of variant, look or parts left the old shapes in the graphics card (about 60 buffers each), and a painted model's pictures with them. They are given back now, and the glow's too.
@@ -58,18 +69,18 @@
 - `pixelRatioFor(width, height, deviceRatio)`, with `MAX_PIXELS`, `MAX_SIDE` and `MAX_RATIO`.
 - New browser tests: draws per frame, nothing drawing when still or out of sight, no growth of contexts, buffers, vertex arrays or textures over changes, a lost context, and the canvas within its budget from 1x to 5x on a 5K screen.
 
-## [0.2.0]
+## [0.2.0] - 2026-11-01
 
 - `element.drive({ yaw, tilt, zoom, panX, panY })`: a page can hand the turn, tip, zoom and move to the family's `<kazoku-view-controls>` ([`@johnmorrisdotca/kazoku-ui`](https://www.npmjs.com/package/@johnmorrisdotca/kazoku-ui)). The element's own drag, wheel, keys and spin stand down, and the 3D view and the drawing both follow, so it works with no WebGL as well. `drive(null)` takes them back. kazoku-ui is not imported by the package: the demo uses it, as a dev dependency.
 - The demo uses the shared view controls: angle, tilt, auto-turn, Front, zoom, Fit and move, with the same drag, pinch and keys as the rest of the family, and the choices kept in the address (`?yaw=40&tilt=10&zoom=2`). Its own slow-spin switch and hint are gone.
 - `turnedBy(base, yaw, tilt)` and the `ViewChoice` type: the camera angle for a view turned and tipped by the controls.
 
-## [0.1.1]
+## [0.1.1] - 2026-11-01
 
 - The painted Falcon 9 Block 5 second stage shows this package's own engine nozzle when it stands apart or alone, as the model has none, and not when it is nested in the first stage.
 - The Falcon 9's drawn vacuum nozzle is 3.3 m across at the exit, the figure Wikipedia's Merlin infobox gives, in the line looks too (the v1.0 keeps its narrower bell).
 
-## [0.1.0]
+## [0.1.0] - 2026-10-31
 
 - Starship: Super Heavy and the Ship, in Block 1, Block 1 as it first flew, Block 2, Block 3 and the announced Block 4, each with its own sourced sizes, and an artist's model of the 2019 design.
 - Falcon 9 in v1.0, v1.1, Full Thrust and Block 5, with a fairing or with Dragon 2; Falcon Heavy; Dragon 1 and Dragon 2; Grasshopper, the test vehicle.

package/README.md

@@ -1,3 +1,5 @@
+<p align="center"><a href="https://johnmorrisdotca.github.io/uchusen-rockets/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/uchusen-rockets/main/docs/images/thumbnail-dark.png"><img src="https://raw.githubusercontent.com/johnmorrisdotca/uchusen-rockets/main/docs/images/thumbnail.png" alt="Uchusen Rockets: Saturn V, Starship, the Space Shuttle, Falcon Heavy and SLS, painted in 3D, side by side." width="1200"></picture></a></p>
+
 <h1 align="center">Uchusen Rockets <sub>宇宙船</sub></h1>
 
 <p align="center"><strong>Rockets drawn from sourced sizes, that you drop into a page, take apart and turn round.</strong><br>
@@ -10,7 +12,7 @@ Uchūsen means "spaceship". Each rocket comes in every variant a source document
   <img alt="TypeScript" src="https://img.shields.io/badge/types-TypeScript-3178c6">
 </p>
 
-<p align="center"><a href="https://johnmorrisdotca.github.io/uchusen-rockets/"><strong>Open the demo →</strong></a> · <a href="./docs/variants.md">Variants and sizes</a> · <a href="./docs/parts.md">Build from parts</a> · <a href="./docs/element.md">The element</a> · <a href="./docs/flight.md">Lit engines and flights</a> · <a href="./docs/embed.md">Use one on your site</a> · <a href="./docs/assets.md">Assets</a></p>
+<p align="center"><a href="https://johnmorrisdotca.github.io/uchusen-rockets/"><strong>Open the demo →</strong></a> · <a href="./docs/variants.md">Variants and sizes</a> · <a href="./docs/parts.md">Build from parts</a> · <a href="./docs/element.md">The element</a> · <a href="./docs/flight.md">Lit engines and flights</a> · <a href="./docs/embed.md">Use one on your site</a> · <a href="./docs/assets.md">Assets</a> · <a href="./docs/guides/getting-started.md">Guides</a> · <a href="https://johnmorrisdotca.github.io/uchusen-rockets/builder.html">Code builder</a> · <a href="https://johnmorrisdotca.github.io/uchusen-rockets/docs/">Docs site</a></p>
 
 <p align="center"><img alt="Block 3 of the rocket as a painted 3D view, stainless steel with black tiles, beside its controls and its sizes, each with a source." src="https://raw.githubusercontent.com/johnmorrisdotca/uchusen-rockets/main/docs/images/main-painted.jpg" width="820"></p>
 
@@ -23,7 +25,7 @@ Uchūsen means "spaceship". Each rocket comes in every variant a source document
 
 <p align="center"><img alt="Every rocket at one scale: Starship, Falcon 9, Falcon 9 with Dragon 2, Falcon Heavy, Grasshopper and Dragon 2, as line drawings beside a ruler, a building and a person." src="https://raw.githubusercontent.com/johnmorrisdotca/uchusen-rockets/main/docs/images/family.jpg" width="820"></p>
 
-## One minute
+## In 30 seconds
 
 ```sh
 npm install @johnmorrisdotca/uchusen-rockets three
@@ -41,6 +43,54 @@ npm install @johnmorrisdotca/uchusen-rockets three
 
 That is all a page needs with a bundler. The drawing shows at once; when the element comes on screen and the browser can draw WebGL, the 3D view takes over without a jump. Drag to turn it, use the arrow keys, or leave it to its slow spin. `engines="on"` lights each engine at full thrust, in the painted look and as a drawn flame in the line looks, and a reader who asked for reduced motion has them off. A flame's length and its shock diamonds are a picture, not a measurement. [A flight](docs/flight.md) plays each phase with the engines that burn in it, from published timelines. With no WebGL, under Save-Data, or on any failure, the drawing stays.
 
+## Who it is for
+
+- **A developer who wants a rocket on a page** with one tag, no build step, and a drawing that is there before any 3D has loaded.
+- **A writer or teacher** who needs a rocket to scale, beside a person and a building, with every size traceable to a source.
+- **A maker of tools** who wants rockets as data: variants, sourced sizes, parts that carry their own joints, and a check that says whether a mix goes together.
+- **Anyone who must credit what they show**: a painted rocket's licence travels with it, in every form it is copied.
+
+## Features
+
+- Twenty-three kinds of thing, from Starship to the Hubble Space Telescope, each in every variant a source documents, with its own sizes.
+- Three looks (`line`, `thick`, `painted`), five views, together, apart and each part alone, for every one of them.
+- A drawing made by code, and a 3D view that takes over without a jump. With no WebGL, under Save-Data or on any failure, the drawing stays.
+- Lit engines at full thrust, and flights played phase by phase from published timelines.
+- `check` and `build`: a typed part record, a fit check, a `.glb` mesh and an SVG, in Node or a browser, with no three.js.
+- `<uchusen-lineup>`: rockets at one scale with a ruler, a person and a building.
+- Six ways to copy a rocket into your own page, with the credit written in.
+- A strict content security policy is enough. No network request but the painted model you ask for.
+
+## Use it in your project
+
+```sh
+npm install @johnmorrisdotca/uchusen-rockets three
+```
+
+```ts no-run
+import "@johnmorrisdotca/uchusen-rockets/element";
+```
+
+Import the element once, anywhere in your client code, and use the tag. `three` is an optional peer dependency, loaded only for a 3D view. Copy `node_modules/@johnmorrisdotca/uchusen-rockets/dist/assets` to a folder your site serves and call `setAssetBase("/that/folder/")` if you want painted models. [Getting started](docs/guides/getting-started.md) and [React and other frameworks](docs/guides/react-and-frameworks.md) go through it step by step.
+
+## Use it anywhere
+
+A page with no bundler loads the element from a CDN, with an import map for three.js:
+
+```html
+<script type="importmap">
+  { "imports": { "three": "https://cdn.jsdelivr.net/npm/three@0.186.1/build/three.module.js" } }
+</script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@johnmorrisdotca/uchusen-rockets@0/dist/element.js"></script>
+<uchusen-rocket rocket="falcon-heavy" look="thick" view="below"></uchusen-rocket>
+```
+
+A page that cannot run script uses an iframe of the embed page:
+
+```html
+<iframe src="https://johnmorrisdotca.github.io/uchusen-rockets/embed.html?rocket=starship&variant=v3&look=line" title="Starship Block 3" style="width:100%;max-width:480px;aspect-ratio:3 / 4;border:0"></iframe>
+```
+
 ## Put one on your own site
 
 The drawings are there to be used. The demo copies the code for the rocket on the screen, in six ways: a CDN script and the element, an iframe of the embed page (for a site that cannot run script), a module, the SVG, a data address, and a link to the picture in the package. It saves an SVG or a PNG too. [docs/embed.md](docs/embed.md) has each one.
@@ -74,6 +124,10 @@ embedCode({ rocket: "starship", variant: "v3", look: "line" }, "element").includ
 
 Changing `look` keeps the angle. Changing `show` is an animated move, and a cut under reduced motion. Each part alone fills the frame and has its own listed size. Every look works for every variant and every choice of parts. Front is the windward, tiled side; back is the steel side.
 
+<p align="center"><img alt="The code builder: a row of makers, rockets, variants, parts, looks and views beside the rocket, and the code to copy below." src="https://raw.githubusercontent.com/johnmorrisdotca/uchusen-rockets/main/docs/images/builder.jpg" width="820"></p>
+
+<p align="center"><img alt="The demo on a phone, the rocket on a screen 390 pixels wide." src="https://raw.githubusercontent.com/johnmorrisdotca/uchusen-rockets/main/docs/images/phone.jpg" width="320"></p>
+
 ## The rockets
 
 Starship; Falcon 9 in v1.0, v1.1, Full Thrust and Block 5, with a fairing or with Dragon 2; Falcon Heavy; Dragon 1, Dragon 2 and Cargo Dragon 2, and Crew Dragon cut open to see inside; Grasshopper, the test vehicle; and Falcon 1, with the Falcon 1e that was announced and never flew. From other makers, to compare at one scale, each drawn by this package's code from its published sizes: Saturn V; the Space Shuttle, stacked with its tank and boosters, each part alone too, and Discovery, a real scan; the Space Launch System, Block 1 with Orion; New Glenn 7×2; Electron; and Soyuz-2. And where a booster lands: drone ships and landing zones. The Starbase integration tower too, with its mount and arms, a Block 3 stacked on it, or catching its booster. And Starbase, as a scene from the map: `launch-site`, `build-site` and `city`. The Apollo lunar module, painted by NASA's model. Apollo docked to Soyuz, painted by NASA's model, stood on end. The Gemini spacecraft, painted by NASA's model. The Mercury spacecraft, as Friendship 7, painted by NASA's model. Jupiter-C, painted by NASA's model. The International Space Station, painted by NASA's model, of the station as it was when that was made. And the Hubble Space Telescope, painted by NASA's model. <!-- more rockets -->
@@ -168,7 +222,14 @@ import { UchusenRocket } from "@johnmorrisdotca/uchusen-rockets/react";
 
 ## Licences, credits and a word on trademarks
 
-The code, the code-made meshes and the drawings are under the MIT licence. **The painted models are not: they stay under Creative Commons Attribution 4.0, or public domain where the row says so, and using them means crediting them.** `check(description).credits` says which belong to a rocket. **Starbase's coordinates and outlines, its map heights and the tower's 13 m footprint are © OpenStreetMap contributors, under ODbL 1.0, not MIT** (https://www.openstreetmap.org/copyright).
+The code, the code-made meshes and the drawings are under the MIT licence. **The painted models are not: they stay under Creative Commons Attribution 4.0, or public domain where the row says so, and using them means crediting them.** `check(description).credits` says which belong to a rocket.
+
+```ts
+import { check } from "@johnmorrisdotca/uchusen-rockets";
+
+check({ rocket: "starship", variant: "v3" }).credits[0].licence; // "CC BY 4.0"
+```
+ **Starbase's coordinates and outlines, its map heights and the tower's 13 m footprint are © OpenStreetMap contributors, under ODbL 1.0, not MIT** (https://www.openstreetmap.org/copyright).
 
 | Painted | Title | Creator | Source | Changed |
 | --- | --- | --- | --- | --- |
@@ -198,10 +259,186 @@ All but Discovery and NASA's are under [CC BY 4.0](https://creativecommons.org/l
 
 **No mesh or drawing carries a logo, a wordmark or a flag.** Rocket names appear only as plain descriptive words. All trademarks belong to their owners, and this project is not affiliated with or endorsed by SpaceX, NASA or any other maker or agency named here. [NOTICE.md](NOTICE.md) names each source and what was taken from it.
 
-## Still to come
+## Examples
+
+Every `ts` block in this README and in the guides runs against the built package (`pnpm test:readme`).
+
+```ts
+import { check, variantOf } from "@johnmorrisdotca/uchusen-rockets";
+
+const falcon = variantOf("falcon-9", "block-5");
+falcon.facts.height.value; // 69.8
+check({ rocket: "falcon-9", variant: "block-5" }).ok; // true
+check({ rocket: "falcon-9", variant: "block-5" }).custom; // false
+```
+
+```ts
+import { showsOf, variantOf } from "@johnmorrisdotca/uchusen-rockets";
+
+showsOf(variantOf("falcon-9", "block-5").slots).includes("apart"); // true
+```
+
+```ts
+import { lineupSvg } from "@johnmorrisdotca/uchusen-rockets/build";
+
+const picture = lineupSvg({ items: ["starship:v3", "falcon-9:block-5", "person"], unit: 4, ruler: true, labels: true });
+picture.items.length; // 3
+picture.svg.startsWith("<svg"); // true
+```
+
+```ts
+import { cleanLook, cleanView } from "@johnmorrisdotca/uchusen-rockets";
+
+cleanLook("shiny"); // "line"
+cleanView("below"); // "below"
+```
+
+Anything from outside is treated as text: an attribute that is not in its list falls back to the default and nothing else.
+
+## The code builder
+
+[The code builder](https://johnmorrisdotca.github.io/uchusen-rockets/builder.html) is one screen: choose the maker, the rocket, the variant, the parts, the look, the view and the engines, see the rocket, and copy the code for any of the six ways. A painted rocket's credit is under the code. It is built from `ROCKETS`, `showsOf`, `embedCode` and `paintedCredit`, so it offers every rocket the package has, as it gains them.
+
+## Lit engines and flights
+
+```html
+<uchusen-rocket id="rocket" rocket="falcon-9" variant="block-5" look="painted" engines="on"></uchusen-rocket>
+<uchusen-flight for="rocket"></uchusen-flight>
+```
+
+<p align="center"><img alt="Falcon 9 painted, seen from below with its engines lit." src="https://raw.githubusercontent.com/johnmorrisdotca/uchusen-rockets/main/docs/images/engines.jpg" width="360"></p>
+
+<p align="center"><img alt="The flight bar: play, back, a slider and next, what happens at hot staging and a chart of the engines that burn." src="https://raw.githubusercontent.com/johnmorrisdotca/uchusen-rockets/main/docs/images/flight.jpg" width="720"></p>
+
+`engines="on"` lights each engine that shows, and a flight lights only the engines that burn in each phase, from a published timeline. How the picture moves between phases, and a flame's length, is illustrative; the times and counts are sourced. [The guide](docs/guides/engines-and-flights.md) has the details.
+
+## NASA's models
+
+The Apollo lunar module, Apollo docked to Soyuz, Gemini, Mercury, Jupiter-C, the Space Shuttle, the International Space Station and the Hubble Space Telescope are painted by NASA's own public-domain models, each with its marks removed and its sizes set from a source.
+
+<p align="center">
+  <img alt="The Apollo lunar module painted from NASA's model." src="https://raw.githubusercontent.com/johnmorrisdotca/uchusen-rockets/main/docs/images/lunar-module.jpg" width="300">
+  <img alt="The Space Shuttle stacked for launch, painted from NASA's models." src="https://raw.githubusercontent.com/johnmorrisdotca/uchusen-rockets/main/docs/images/shuttle.jpg" width="300">
+</p>
+
+## API
+
+The reference is a site, made from the source's own doc comments: every export has a summary, its parameters, what it returns, and an example that runs when the site is built. [Open the reference](https://johnmorrisdotca.github.io/uchusen-rockets/docs/).
+
+```ts
+import { ROCKETS, PART_ENTRIES, SOURCES, MODEL_CREDITS } from "@johnmorrisdotca/uchusen-rockets";
+
+Object.keys(ROCKETS).length > 20; // true
+PART_ENTRIES.length > 100; // true
+Object.keys(SOURCES).length > 20; // true
+Object.keys(MODEL_CREDITS).length > 10; // true
+```
+
+<p align="center"><img alt="The documentation site: a search box, the entry points, the guides in sections, and every export with its example." src="https://raw.githubusercontent.com/johnmorrisdotca/uchusen-rockets/main/docs/images/docs-site.jpg" width="720"></p>
+
+## Guides
+
+Each guide has a Japanese twin in [docs/guides/ja](docs/guides/ja).
+
+| Guide | What it is for |
+| --- | --- |
+| [Getting started](docs/guides/getting-started.md) | A rocket on a page in ten minutes |
+| [Looks, views and parts](docs/guides/looks-views-and-parts.md) | The three choices that change what you see |
+| [Build a rocket from parts](docs/guides/build-from-parts.md) | Part records, the fit check, `build`, the builder |
+| [Lit engines and flights](docs/guides/engines-and-flights.md) | Engines at full thrust, flights, what is sourced |
+| [Rockets to scale](docs/guides/scale-lineups.md) | `<uchusen-lineup>` and `lineupSvg` |
+| [Put a rocket on your own site](docs/guides/embed-on-your-site.md) | Six ways, and the credit |
+| [React and other frameworks](docs/guides/react-and-frameworks.md) | React, Vue, Svelte, Angular |
+| [Ready files and 3D models](docs/guides/assets-and-3d-files.md) | The `.glb` and `.svg` files |
+| [Variants and sourced sizes](docs/guides/variants-and-sources.md) | Why a figure names its source |
+| [Licences, credits and trademarks](docs/guides/licences-and-credits.md) | What is MIT, CC BY, public domain, ODbL |
+| [Architecture](docs/guides/architecture.md) | How the layers fit |
+| [Troubleshooting](docs/guides/troubleshooting.md) | Why the 3D view or the model is missing |
+| [Upgrading](docs/guides/upgrading.md) | What to look for between versions |
+
+## Limits
+
+- A rocket is only as good as its sources. A figure no source gives is blank, never estimated, and a blank is shown as one.
+- A flame's length and its shock diamonds, how parts move between flight phases, smoke and the ground falling away are pictures, not measurements.
+- A part with no licensed model is painted by this package's own code from photographs and sizes. It is a likeness, not a scan.
+- A flight exists only for the variants a published timeline covers. A custom build has none.
+- A painted model is up to 8 MB and is fetched only when asked for. Code-made meshes stay under 600 KB and drawings under 80 KB.
+- There is no logo, wordmark or flag on anything, so a rocket is never "the real livery".
+
+```ts
+import { variantOf } from "@johnmorrisdotca/uchusen-rockets";
+
+variantOf("starship", "2019").facts.diameter.value; // null
+```
+
+## Accessibility
+
+- The element has an accessible name from its `label` attribute, or from the fit report's label (such as "Block 3 (V3)") when there is none. The 3D view's canvas says how to turn it.
+- A reader who asked for reduced motion gets no spin, no flames, no played flight and a cut instead of an animated move. The slider and charts still work.
+- Turning works by drag, touch and the keyboard: the arrow keys turn it, `+` and `-` zoom, Home puts it back.
+- The demo's controls are at least 44 pixels tall and work with a keyboard.
+
+```html
+<uchusen-rocket rocket="starship" variant="v3" label="Starship Block 3, taken apart" show="apart"></uchusen-rocket>
+```
+
+## Browser and runtime support
+
+- Using the package needs Node 22 or later. Working on it needs 22.18 or later.
+- In a browser, any current one. The 3D view needs WebGL; without it the drawing stays.
+- The test suite runs the demo in Chromium and WebKit at a phone's width and a desk's, and the packed package on Linux, macOS and Windows, on Node 22 and 24.
+- `three` `>=0.170.0` and `react` `>=18` are optional peer dependencies.
+
+## Languages
+
+The documentation is in English and Japanese: each guide in [docs/guides](docs/guides) has a twin in [docs/guides/ja](docs/guides/ja), and the documentation site switches between them. The rockets' own names are plain descriptive words and are the same in both.
+
+## Architecture
+
+The data is typed once. A part is a table of numbers: its real size in metres and the joints it mates at. A mesh and a drawing come from the same pieces, so they cannot disagree with each other or with the data. The root and `build` entries import neither three.js nor the DOM; the element loads three.js only for a 3D view.
+
+```ts
+import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+
+const a = build({ rocket: "falcon-9", variant: "block-5" }).glb().bytes;
+const b = build({ rocket: "falcon-9", variant: "block-5" }).glb().bytes;
+a.length === b.length; // true
+```
+
+A mesh is a pure function of its description: the same description gives the same bytes. [Architecture](docs/guides/architecture.md) has the layers.
+
+## Development
+
+```sh
+pnpm install
+pnpm check          # lint, types, tests, the build and the packed package
+pnpm test:readme    # run every example of the README, the docs and the guides
+pnpm docs:check     # the reference site's checks: every export documented, every example run
+pnpm test:demo      # the demo in a real browser
+pnpm dev            # the demo on http://127.0.0.1:7900/uchusen-rockets/
+pnpm screenshots    # the pictures in docs/images
+```
+
+## Contributing
+
+Bug reports, ideas and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). The rules that matter most: a figure names its source or is blank, no logos or marks, a mesh is a pure function of its description, and anything from outside is text.
+
+## Changes
+
+[CHANGELOG.md](CHANGELOG.md) lists every release with its date.
+
+## Roadmap
 
 `PLANNED_ROCKETS` lists rockets with sourced facts and no shape yet: Vulcan Centaur and Ariane 6.
 
+```ts
+import { PLANNED_ROCKETS } from "@johnmorrisdotca/uchusen-rockets";
+
+PLANNED_ROCKETS.map((rocket) => rocket.id).length > 0; // true
+```
+
+A rocket goes in only when a source documents it.
+
 ## The rest
 
 [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) · [CHANGELOG.md](CHANGELOG.md) · [NOTICE.md](NOTICE.md) · MIT licence, CC BY 4.0 for the painted models, and ODbL 1.0 for the map data

package/dist/attrs.d.ts

@@ -1,4 +1,25 @@
+/**
+ * The attributes of `<uchusen-rocket>` that choose what is drawn, in the order the demo writes them. The `embed.html` query uses the same words.
+ *
+ * @example
+ * ```ts
+ * import { OPTION_ATTRIBUTES } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(OPTION_ATTRIBUTES.join(", "));
+ * ```
+ */
 export declare const OPTION_ATTRIBUTES: readonly ["rocket", "variant", "show", "look", "view", "build", "mode", "spin", "way", "label", "assets", "engines", "phase"];
+/**
+ * Every choice that draws a rocket, as plain text: the same names and values as the element's attributes. Nothing here is trusted. A value outside its list falls back to a default when it is drawn.
+ *
+ * @example
+ * ```ts
+ * import type { RocketOptions } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const options: RocketOptions = { rocket: "falcon-9", variant: "block-5", look: "thick", view: "below" };
+ * console.log(options);
+ * ```
+ */
 export interface RocketOptions {
     rocket?: string;
     variant?: string;
@@ -17,11 +38,56 @@ export interface RocketOptions {
     /** A phase of the rocket's flight, by its id: the engines that burn there. */
     phase?: string;
 }
-/** The attributes that draw these options. Empty values are left out. */
+/**
+ * The attributes that draw these options. Empty values are left out.
+ *
+ * @param options The choices to turn into attributes.
+ * @returns The attributes by name, as text. A choice left out or empty has no entry.
+ * @example
+ * ```ts
+ * import { attributesFromOptions } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(attributesFromOptions({ rocket: "starship", variant: "v3", look: "painted", show: "" }));
+ * ```
+ */
 export declare function attributesFromOptions(options: RocketOptions): Record<string, string>;
-/** The options `read` finds. A missing attribute is left out; nothing here is trusted as a real rocket. */
+/**
+ * The options `read` finds. A missing attribute is left out; nothing here is trusted as a real rocket.
+ *
+ * @param read Reads one attribute by name and gives null when it is missing, as `element.getAttribute` does.
+ * @returns The choices found, as written. A missing attribute is left out of the result.
+ * @example
+ * ```ts
+ * import { optionsFromAttributes } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const attributes: Record<string, string> = { rocket: "starship", look: "thick" };
+ * console.log(optionsFromAttributes((name) => attributes[name] ?? null));
+ * ```
+ */
 export declare function optionsFromAttributes(read: (name: string) => string | null): RocketOptions;
-/** The options as a query for `embed.html`. */
+/**
+ * The options as a query for `embed.html`.
+ *
+ * @param options The choices to write.
+ * @returns A query for `embed.html`, with one entry for each choice made.
+ * @example
+ * ```ts
+ * import { rocketToParams } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(rocketToParams({ rocket: "falcon-9", show: "apart" }).toString());
+ * ```
+ */
 export declare function rocketToParams(options: RocketOptions): URLSearchParams;
-/** The options a query names. */
+/**
+ * The options a query names.
+ *
+ * @param params The query of an `embed.html` address.
+ * @returns The choices the query names.
+ * @example
+ * ```ts
+ * import { rocketFromParams } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(rocketFromParams(new URLSearchParams("rocket=falcon-9&look=thick")));
+ * ```
+ */
 export declare function rocketFromParams(params: URLSearchParams): RocketOptions;

package/dist/attrs.js

@@ -1,7 +1,28 @@
 // A rocket's options as text: the attributes of `<uchusen-rocket>` and the query of `embed.html` are the same words, read by one function and written by another.
+/**
+ * The attributes of `<uchusen-rocket>` that choose what is drawn, in the order the demo writes them. The `embed.html` query uses the same words.
+ *
+ * @example
+ * ```ts
+ * import { OPTION_ATTRIBUTES } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(OPTION_ATTRIBUTES.join(", "));
+ * ```
+ */
 export const OPTION_ATTRIBUTES = ["rocket", "variant", "show", "look", "view", "build", "mode", "spin", "way", "label", "assets", "engines", "phase"];
 const text = (value) => (typeof value === "string" && value !== "" ? value : undefined);
-/** The attributes that draw these options. Empty values are left out. */
+/**
+ * The attributes that draw these options. Empty values are left out.
+ *
+ * @param options The choices to turn into attributes.
+ * @returns The attributes by name, as text. A choice left out or empty has no entry.
+ * @example
+ * ```ts
+ * import { attributesFromOptions } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(attributesFromOptions({ rocket: "starship", variant: "v3", look: "painted", show: "" }));
+ * ```
+ */
 export function attributesFromOptions(options) {
     const out = {};
     for (const name of OPTION_ATTRIBUTES) {
@@ -11,7 +32,19 @@ export function attributesFromOptions(options) {
     }
     return out;
 }
-/** The options `read` finds. A missing attribute is left out; nothing here is trusted as a real rocket. */
+/**
+ * The options `read` finds. A missing attribute is left out; nothing here is trusted as a real rocket.
+ *
+ * @param read Reads one attribute by name and gives null when it is missing, as `element.getAttribute` does.
+ * @returns The choices found, as written. A missing attribute is left out of the result.
+ * @example
+ * ```ts
+ * import { optionsFromAttributes } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * const attributes: Record<string, string> = { rocket: "starship", look: "thick" };
+ * console.log(optionsFromAttributes((name) => attributes[name] ?? null));
+ * ```
+ */
 export function optionsFromAttributes(read) {
     const options = {};
     for (const name of OPTION_ATTRIBUTES) {
@@ -21,11 +54,33 @@ export function optionsFromAttributes(read) {
     }
     return options;
 }
-/** The options as a query for `embed.html`. */
+/**
+ * The options as a query for `embed.html`.
+ *
+ * @param options The choices to write.
+ * @returns A query for `embed.html`, with one entry for each choice made.
+ * @example
+ * ```ts
+ * import { rocketToParams } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(rocketToParams({ rocket: "falcon-9", show: "apart" }).toString());
+ * ```
+ */
 export function rocketToParams(options) {
     return new URLSearchParams(attributesFromOptions(options));
 }
-/** The options a query names. */
+/**
+ * The options a query names.
+ *
+ * @param params The query of an `embed.html` address.
+ * @returns The choices the query names.
+ * @example
+ * ```ts
+ * import { rocketFromParams } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(rocketFromParams(new URLSearchParams("rocket=falcon-9&look=thick")));
+ * ```
+ */
 export function rocketFromParams(params) {
     return optionsFromAttributes((name) => params.get(name));
 }

package/dist/build/glb.d.ts

@@ -5,8 +5,33 @@ export interface GlbPart {
     mesh: PartMesh;
     at: readonly [number, number, number];
 }
+/**
+ * A binary glTF file: its bytes and how many triangles it holds. Save the bytes as a `.glb` file or hand them to any glTF viewer.
+ *
+ * @example
+ * ```ts
+ * import { build } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const glb = build({ rocket: "starship", variant: "v3" }).glb();
+ * console.log(glb.bytes.length > 1000, glb.triangles > 0);
+ * ```
+ */
 export interface Glb {
     bytes: Uint8Array;
     triangles: number;
 }
+/**
+ * Writes parts into one small binary glTF file, in Node or a browser, with no dependency: one node for each part and one primitive for each material. The same parts always give the same bytes.
+ *
+ * @param parts The parts to write: each has a node name, its mesh and where it stands in metres.
+ * @returns The file's bytes and its triangle count.
+ * @example
+ * ```ts
+ * import { build, toGlb } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const rocket = build({ rocket: "falcon-9", variant: "block-5" });
+ * const glb = toGlb(rocket.parts.map((part) => ({ name: part.slot, mesh: part.mesh, at: [0, 0, 0] as const })));
+ * console.log(glb.bytes.length > 1000, glb.triangles > 0);
+ * ```
+ */
 export declare function toGlb(parts: readonly GlbPart[]): Glb;

package/dist/build/glb.js

@@ -10,6 +10,20 @@ const LINES = 1;
 const round6 = (v) => Math.round(v * 1e6) / 1e6;
 const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
 const linearOf = (hex) => [1, 3, 5].map((i) => round6(toLinear(Number.parseInt(hex.slice(i, i + 2), 16) / 255)));
+/**
+ * Writes parts into one small binary glTF file, in Node or a browser, with no dependency: one node for each part and one primitive for each material. The same parts always give the same bytes.
+ *
+ * @param parts The parts to write: each has a node name, its mesh and where it stands in metres.
+ * @returns The file's bytes and its triangle count.
+ * @example
+ * ```ts
+ * import { build, toGlb } from "@johnmorrisdotca/uchusen-rockets/build";
+ *
+ * const rocket = build({ rocket: "falcon-9", variant: "block-5" });
+ * const glb = toGlb(rocket.parts.map((part) => ({ name: part.slot, mesh: part.mesh, at: [0, 0, 0] as const })));
+ * console.log(glb.bytes.length > 1000, glb.triangles > 0);
+ * ```
+ */
 export function toGlb(parts) {
     const chunks = [];
     let offset = 0;