@johnmorrisdotca/uchusen-rockets 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-11-03
+
+- Flights for the other variants, each from a page read for it and with a blank where the page gives none: Starship flight test 1 (Block 1 as it first flew: the stages never separated, and the stack was destroyed at T+4:01), Falcon 9 v1.1 with CASSIOPE (Spaceflight Now's live coverage), Falcon 9 Full Thrust with ABS-2A and Eutelsat 117 West B (Spaceflight Now's timeline; Wikipedia's ABS-2A names the version) and Grasshopper's highest hop (744 m in 79 s, Wikipedia's table of its hops). Not here: Falcon 9 v1.0 (no page read gives a v1.0 flight with a fairing), Starship Block 4 (not flown) and Dragon on its own (no timeline read); they stay without a flight.
+- Altitude and speed in the flights, only where a page gives one, in its words: flight test 1's 39 km and 29 km, 146 km on flight test 7, 195 km on flight test 12 and its booster's 1,450 km/h at the water, CASSIOPE's "more than 20 miles" and "310 kilometers", "Mach 1" on the Full Thrust flight, CRS-16's planned orbit and Grasshopper's 744 m. The flight bar shows a speed beside the altitude.
+- Grid fins, legs and flaps turn in a flight. Each is a group of pieces with a name, a pivot and an axis (`Piece.move`), a node of its own in the `.glb` (`booster~grid-fins~0`, with its axis), turned in the 3D view by setting one rotation and in the drawing by `moved` (`svg({ moves })`); `PartPose.moves` carries the angles a phase wants and `frameAt` mixes them. Falcon 9's grid fins are stowed for the ascent and open for the entry and its legs open before the touchdown, Super Heavy's fins steer after the boostback, the Ship's flaps turn at its entry and flip (the pages say each; how far is a picture). A painted model that is one shell does not turn: nothing is cut to fake a move. No new draw loop: a turn is set inside the flight's one frame, and the number of nodes, buffers and programs is the same each time (the freeze test holds it).
+
+- The family's must-have list passes (`node scripts/check-standard.mjs` says ok, and a test holds the file to its recorded hash): the demo is made with the family's header and footer (the language picker and the theme switch, Docs and Embed links, light and dark), the family's template and README writer list this package, the README has "The family", and the documentation site has its recorded-hash test and its browser test.
+- Usage, written and tested: `examples/` holds a script tag from jsDelivr and from unpkg, an iframe of the embed page, Vite, webpack, React (with a server render), Vue, Svelte, Angular, TypeScript and Node, and `pnpm test:usage` builds, type-checks or runs each against the package as npm packs it and opens each page in a browser, which must draw the rocket and reach its 3D view. CI runs it, and the guides hold each file word for word. Two new guides, Bundlers and CDNs and TypeScript and Node, each with a Japanese twin (the Japanese awaits a native reader).
+- A flame's colour comes from what its engine burns, each from a page read for it: `PROPELLANTS` and `propellantOf` (Merlin, Kestrel, F-1, Rutherford and the RD-107 and RD-108 burn kerosene; Raptor and BE-4 methane; J-2, RS-25 and BE-3 hydrogen; the Space Shuttle's boosters and the SLS's are solid; the lunar module's descent engine burns Aerozine 50 and nitrogen tetroxide). Before, any rocket with a Starship part had a methane flame and every other rocket a kerosene one, so Saturn V, the Space Shuttle, SLS, New Glenn and Soyuz were drawn as burning kerosene. A part with an engine no page read here names, such as the ship of the 2019 design and of Block 4, has a neutral grey-white flame. Each part has its own, in the drawing and the 3D view (`BuiltPart.flame`), and a Space Shuttle's orbiter and boosters burn two colours at once. No new draw: the flames of a kind share one program and one set of clocks, and the freeze test passes. The colours are a picture.
+- Fixed: the import map in the README and in the Getting started guide named `three` only, but the 3D view also imports `three/addons/` (its loaders and controls), so a page copied from them drew the line picture and never the 3D view. Both now name `three/addons/`, as the snippet the demo copies always did. `pnpm test:usage` found it.
+- WebKit's "Refused to apply a stylesheet" errors, which the demo test had been told to ignore, are gone and the ignore is removed. They came from the demo page's Content-Security-Policy after the page lost its style hash (chikyu-earth 0.10's realistic Earth then fell back to a style tag the policy refused). The page has no policy of its own now, because the family's header writes a script and a style, so there is nothing to refuse; the embed page and the code builder keep the strict policy (`style-src 'self'`, no inline style), and a browser test holds that they run under it with no report, in Chromium and in WebKit on CI.
+- Documentation: the family's docs-site files of 2026-11-03 (`scripts/docs-site.mjs`, `e2e/docs-site.demo.mjs`, held to their recorded hashes): the browser test reads a seeded sample of the pages and checks the links from the files, and every guide's picture is a real image (`![..](../images/..)`, `../../images/` in Japanese) that the docs site publishes, in place of a link to the picture.
+- Demo, at a desk's width: the family header is one row and the hint under the view is left out, so the choices and the view still end within a 900 px window; the line Earth is drawn in a shadow root of its own, so the family header's help switch does not wake for each of its redraws.
+- Demo: the page itself is English; only the header and footer are in Japanese too. The page no longer carries a Content-Security-Policy of its own, because the family's header writes a script and a style; the embed page keeps its strict one.
+
+## [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 +67,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 +84,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/NOTICE.md

@@ -60,6 +60,8 @@ Sizes are plain facts, each with its source in `src/data/sources.ts` and on the
 | Source | What was taken |
 | --- | --- |
 | Wikipedia: SpaceX Starship, SpaceX Super Heavy, SpaceX Starship (spacecraft), SpaceX Raptor, SpaceX Merlin, Starship flight test 1, List of Starship launches, Falcon 1, Falcon 9, Falcon 9 Block 5, Falcon Heavy, SpaceX Dragon 1, SpaceX Dragon 2, SpaceX Grasshopper (CC BY-SA 4.0, read 2026-10-31) | Heights, diameters (the vacuum Merlin's 3.3 m), engine counts, grid fin counts, flap changes, first flight dates in UTC. Facts only: no text is copied |
+| Wikipedia: SpaceX Kestrel, Blue Origin BE-4, Blue Origin BE-3, Rutherford (rocket engine), RD-107, Space Launch System Solid Rocket Booster, ABS-2A, SpaceX Grasshopper, Starship flight test 1, 7 and 12, Falcon 9 first-stage landing tests, with the engine and booster pages already named above (CC BY-SA 4.0, read 2026-11-03) | What each engine burns, which flights have timelines and which parts the pages say turn, and the altitudes and speeds they give. Facts only: no text is copied beyond the short quotation in a figure's note |
+| Spaceflight Now: the live coverage of the first Falcon 9 v1.1 launch (CASSIOPE) and the timeline for the launch for ABS and Eutelsat | The times of a launch's steps and the altitudes and speeds its page gives. Facts only |
 | SpaceX's Starship page, https://new.spacex.com/vehicles/starship, as a search engine quoted it: the page itself would not load | Rounded heights, kept as a second opinion |
 | SpaceX, Falcon 1 Launch Vehicle Payload User's Guide, Rev 7, 2008, read through the Internet Archive | Falcon 1's and Falcon 1e's heights and fairings. Facts only: no drawing is copied |
 | Wikipedia: Saturn V, Apollo command and service module, Apollo (spacecraft), Saturn V instrument unit, Rocketdyne F-1, Rocketdyne J-2 (CC BY-SA 4.0, read 2026-11-02) | Saturn V's and the Apollo spacecraft's lengths and widths, and the engines' sizes. Facts only: no text is copied |

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 in the colour of what they burn, and flights played phase by phase from published timelines, with grid fins, legs and flaps that turn.
+- `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", "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.186.1/examples/jsm/" } }
+</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,261 @@ 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, in the colour of what its engine burns (each from a page), and a flight lights only the engines that burn in each phase, from a published timeline, with the altitude and speed where its page gives them. Grid fins, legs and flaps turn in a flight where the pages say they do. How the picture moves between phases, how far a part turns, and a flame's length, is illustrative; the times, counts, altitudes and speeds 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 |
+| [Bundlers and CDNs](docs/guides/bundlers-and-cdn.md) | unpkg, Vite, webpack |
+| [TypeScript and Node](docs/guides/typescript-and-node.md) | Types, and the core in Node |
+| [Bundlers and CDNs](docs/guides/bundlers-and-cdn.md) | unpkg, Vite, webpack |
+| [TypeScript and Node](docs/guides/typescript-and-node.md) | Types, and the core in Node |
+| [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 test:usage     # every way to use it (CDN, Vite, webpack, React, Vue, Svelte, Angular, iframe, TypeScript, Node), built and opened from the package as npm packs it
+pnpm test:usage     # every way to use it (CDN, Vite, webpack, React, Vue, Svelte, Angular, iframe, TypeScript, Node), built and opened from the package as npm packs it
+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 family
+
+<!-- family:start (made by scripts/family-readme.mjs from scripts/family-template.mjs; change those, not this) -->
+Uchusen Rockets is one of thirty-five packages, each made for the same site, each at
+[github.com/johnmorrisdotca](https://github.com/johnmorrisdotca) or [github.com/spxis](https://github.com/spxis). The code of every one is MIT.
+
+**Games — board**
+
+- [Domino](https://github.com/johnmorrisdotca/domino) (ドミノ): dominoes and Mexican Train. [Demo](https://johnmorrisdotca.github.io/domino/).
+- [Gunjin](https://github.com/johnmorrisdotca/gunjin) (軍人): five hidden-rank strategy games with pass-the-device play. [Demo](https://johnmorrisdotca.github.io/gunjin/).
+- [Narabe](https://github.com/johnmorrisdotca/narabe) (並べ): one rules engine for abstract board games, from gomoku and Reversi to Go and checkers. [Demo](https://johnmorrisdotca.github.io/narabe/).
+- [Sugoroku](https://github.com/johnmorrisdotca/sugoroku) (双六): backgammon and its variants, with the doubling cube and match play. [Demo](https://johnmorrisdotca.github.io/sugoroku/).
+- [Tenka](https://github.com/johnmorrisdotca/tenka) (天下): world conquest for two to six, on a map of the real world. [Demo](https://johnmorrisdotca.github.io/tenka/).
+
+**Games — cards & tiles**
+
+- [Hitotsu](https://github.com/johnmorrisdotca/hitotsu) (一つ): a colour-card shedding game for two to eight, with the house rules people play. [Demo](https://johnmorrisdotca.github.io/hitotsu/).
+- [Jarajara](https://github.com/johnmorrisdotca/jarajara) (ジャラジャラ): mahjong tiles drawn as SVG, stacked layouts, and the matching solitaire Awase. [Demo](https://johnmorrisdotca.github.io/jarajara/).
+- [Kumimoji](https://github.com/johnmorrisdotca/kumimoji) (組み文字): a crossword tile race, in English and Japanese kana. [Demo](https://johnmorrisdotca.github.io/kumimoji/).
+- [Toranpu](https://github.com/johnmorrisdotca/toranpu) (トランプ): a deck of playing cards, card games with computer players, and solitaires. [Demo](https://johnmorrisdotca.github.io/toranpu/).
+
+**Games — puzzles**
+
+- [Houseki](https://github.com/johnmorrisdotca/houseki) (宝石): gem and stone matching puzzles: falling triplets, stone collapse, colour chains and gem swap. [Demo](https://johnmorrisdotca.github.io/houseki/).
+- [Jirai](https://github.com/johnmorrisdotca/jirai) (地雷): minesweeper on shaped grids with verified no-guess boards. [Demo](https://johnmorrisdotca.github.io/jirai/).
+- [Karakuri](https://github.com/johnmorrisdotca/karakuri) (からくり): eight hyper-casual puzzle games, some of them physics: draw a shield, pull pins, cut ropes, slide blocks, pour tubes. [Demo](https://johnmorrisdotca.github.io/karakuri/).
+- [Kazu](https://github.com/johnmorrisdotca/kazu) (数): grid number puzzles: Sudoku and its variants, Futoshiki and Skyscrapers. [Demo](https://johnmorrisdotca.github.io/kazu/).
+- [Kyuubu](https://github.com/johnmorrisdotca/kyuubu) (キューブ): a turning cube for the browser, 2×2 to 7×7, with record solves to replay. [Demo](https://johnmorrisdotca.github.io/kyuubu/).
+- [Meikyuu](https://github.com/johnmorrisdotca/meikyuu) (迷宮): mazes on squares, hexagons, triangles and circles, made from a seed and drawn through with a finger or the mouse. [Demo](https://johnmorrisdotca.github.io/meikyuu/).
+- [Suido](https://github.com/johnmorrisdotca/suido) (水道): a pipe puzzle: turn the pieces until the water reaches every drain. [Demo](https://johnmorrisdotca.github.io/suido/).
+- [Tobiishi](https://github.com/johnmorrisdotca/tobiishi) (飛び石): peg solitaire with nine boards and seeded solvable challenges. [Demo](https://johnmorrisdotca.github.io/tobiishi/).
+- [Tsunagi](https://github.com/johnmorrisdotca/tsunagi) (繋ぎ): a line-joining logic puzzle whose every level has exactly one answer. [Demo](https://johnmorrisdotca.github.io/tsunagi/).
+
+**Games — dice & random**
+
+- [Korokoro](https://github.com/johnmorrisdotca/korokoro) (コロコロ): dice, with notation, exact odds, real sounds and the dice of many games. [Demo](https://johnmorrisdotca.github.io/korokoro/).
+- [Tane](https://github.com/johnmorrisdotca/tane) (種): seeded random numbers and daily seeds, the same in every browser and on every server. [Demo](https://johnmorrisdotca.github.io/tane/).
+
+**Language**
+
+- [Bushu](https://github.com/johnmorrisdotca/bushu) (部首): find a kanji by the parts it is made of. [Demo](https://johnmorrisdotca.github.io/bushu/).
+- [Hikidashi](https://github.com/johnmorrisdotca/hikidashi) (引き出し): a drawer of small Japanese text tools: era dates, kanji numerals, readings and sentence difficulty. [Demo](https://johnmorrisdotca.github.io/hikidashi/).
+- [Kotoba](https://github.com/johnmorrisdotca/kotoba) (言葉): word lists and word-game rules in English, French, German and Japanese. [Demo](https://johnmorrisdotca.github.io/kotoba/).
+
+**Geography & data**
+
+- [address-plus](https://github.com/johnmorrisdotca/address-plus) (アドレスプラス): parse and format addresses in the United States, Canada, Japan, Australia, France, Germany and the United Kingdom. [Demo](https://johnmorrisdotca.github.io/address-plus/).
+- [Chikyu Earth](https://github.com/johnmorrisdotca/chikyu-earth) (地球): a line-drawn globe that turns at the Earth's own rate, with an optional realistic Earth from space and markers for any place. [Demo](https://johnmorrisdotca.github.io/chikyu-earth/).
+- [Chizu](https://github.com/johnmorrisdotca/chizu) (地図): maps of the world and of countries' regions, in English and Japanese, with a quiz and callouts. [Demo](https://johnmorrisdotca.github.io/chizu/).
+- [Hata](https://github.com/johnmorrisdotca/hata) (旗): country and regional flags as SVG, at their true proportions and keyed by ISO code. [Demo](https://johnmorrisdotca.github.io/hata/).
+- [Kuni](https://github.com/johnmorrisdotca/kuni) (国): countries and their regions, with ISO codes and names in English and Japanese. [Demo](https://johnmorrisdotca.github.io/kuni/).
+- [Uchusen Rockets](https://github.com/johnmorrisdotca/uchusen-rockets) (宇宙船): rockets drawn from sourced sizes, as line drawings and 3D views you can take apart and turn, with a check that a rocket really goes together. [Demo](https://johnmorrisdotca.github.io/uchusen-rockets/).
+- [Wakusei Planets](https://github.com/johnmorrisdotca/wakusei-planets) (惑星): the Sun, the planets and their moons, as line drawings, shaded drawings and painted surface maps, with their real sizes, tilt and rotation. [Demo](https://johnmorrisdotca.github.io/wakusei-planets/).
+
+**Sports**
+
+- [Dougu Sports](https://github.com/johnmorrisdotca/dougu-sports) (道具): sports emblems as SVG: trophies, medals, crests, and the ball and gear of every sport, with optional 3D turning. [Demo](https://johnmorrisdotca.github.io/dougu-sports/).
+- [Kyogijo Stadiums](https://github.com/johnmorrisdotca/kyogijo-stadiums) (競技場): sports fields, rinks, courts and ballparks drawn to scale as SVG, with each team and the score on them. [Demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/).
+- [Senshu Jerseys](https://github.com/johnmorrisdotca/senshu-jerseys) (選手): sports jerseys, sweaters, kits, caps, helmets and retired-number banners as SVG, front and back, with optional 2.5D turning. [Demo](https://johnmorrisdotca.github.io/senshu-jerseys/).
+- [Taisen Brackets](https://github.com/johnmorrisdotca/taisen-brackets) (対戦): a sport-agnostic tournament bracket, drawn as SVG, from a list of ties. [Demo](https://johnmorrisdotca.github.io/taisen-brackets/).
+
+**Developer tools**
+
+- [REST in Pieces](https://github.com/spxis/rest-in-pieces) (レスト・イン・ピーシーズ): seeded test data and REST APIs for frontend development, with latency and error drills. [Demo](https://spxis.github.io/rest-in-pieces/).
+
+
+**This package is Uchusen Rockets.** The demos of all thirty-five share one header and footer, so each links the rest.
+<!-- family:end -->
+
 ## 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