@johnmorrisdotca/wakusei-planets 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,6 +1,21 @@
 # Changelog
 
-## 0.4.0
+## 0.5.1 - 2026-11-03
+
+- kazoku-ui 0.12.0: the demo's view controls have a zoom slider, on top of 0.11's Centre button and exact grab.
+- Documentation: an architecture guide and a fuller upgrading guide, each with its Japanese twin; a code builder page (`builder.html`); eight new pictures; a longer README whose examples run (`pnpm test:readme`); and every release of this changelog dated. No behaviour changed.
+- 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`.
+
+## 0.5.0 - 2026-11-03
+
+The bodies for someone else's three.js scene.
+
+- **`@johnmorrisdotca/wakusei-planets/painter`**: `painter.make(three, "Jupiter", { look, invalidate, ratio })` makes the Sun, a planet, Pluto or a moon as an object of radius 1 for a perspective-camera scene of your own, in the realistic or the painted look, lit from any direction in the scene's own axes (equatorial J2000, y up), turned about its real pole at the moment given, with its rings and the Sun's glow. Nothing is drawn by it and it holds no renderer, loop or clock: the caller places, scales and calls `update({ toSun, ms, radiusPx })` at each draw. A painted body shows the shaded look until its map arrives, fetches a sharper map only when it is big on the screen, and lets the big one go a few seconds after it shrinks. `painter.moons("Jupiter", ms)` places a planet's moons in planet radii. Its shape is chikyu-earth's `BodyPainter`, so `setBodyPainter(painter)` is the whole wiring (chikyu-earth 0.11).
+- New shaders for it (`VERTEX_WORLD` and friends): the lighting, the ring's shadow and the limb are worked out from the direction to the camera, not from an orthographic viewer's frame.
+- `orientation(id, ms)` and `moonOffset(id, ms)`: a body's pole and prime meridian, and a moon's place from its planet, in the same axes.
+- A guide, "In your own three.js scene", in English and Japanese.
+
+## 0.4.0 - 2026-11-03
 
 "Put it in your page" is a configurator.
 
@@ -9,7 +24,7 @@
 - A guide, "Put it in your page", in English and Japanese.
 - **kazoku-ui 0.11.0**: the view controls' Centre button (it appears once the body is dragged away), a pan that keeps a quarter of the body in sight (told the body's size with `object-size`), and a drag that keeps the touched point under the pointer (`grab-radius`). The 0.3.1 stopgap that made Fit re-centre is gone.
 
-## 0.3.1
+## 0.3.1 - 2026-11-03
 
 The Earth is a body like the others, and "To scale" is a comparison.
 
@@ -19,7 +34,7 @@ The Earth is a body like the others, and "To scale" is a comparison.
 - **The body cannot be dragged out of the view** (a quarter of it stays in), and Fit centres it and returns it to its first angle.
 - The README's pictures are absolute addresses pinned to the release's tag (npm's page showed a different picture from GitHub's), and a test holds it (`pnpm readme:images` pins them after a version bump).
 
-## 0.3.0
+## 0.3.0 - 2026-11-03
 
 Painted moons, Saturn's rings from Cassini, and a drag that goes the right way up.
 
@@ -31,7 +46,7 @@ Painted moons, Saturn's rings from Cassini, and a drag that goes the right way u
 - **A drag up moves the surface up** (it moved it down), in every look: the controls' tilt tipped the pole toward you as it grew, and now tips the top of the body away, so the near surface goes up, as in chikyu-earth 0.9.1. Drag right, the right arrow and the up arrow agree. Test (`e2e/drag.demo.ts`): a real pointer and real key presses on Mars (line, shaded, painted), Venus and the Moon (painted); the vertical checks fail on 0.2.0.
 - `scripts/make-textures.py` makes the moons and the ring strip too (`python3 scripts/make-textures.py io saturn-ring`) and writes each source's file page, licence and credit into `textures/SOURCES.json`.
 
-## 0.2.0
+## 0.2.0 - 2026-11-02
 
 The painted looks.
 
@@ -39,7 +54,7 @@ The painted looks.
 - Small pictures by default: the 512 and 1024 pixel widths are in the package (0.53 MB in all); a view that is zoomed in fetches the 2048 pixel width from the repository by jsDelivr's GitHub address (`texture-far-base` to serve it yourself). A picture that fails to load leaves the shaded look drawn, and no picture is asked for twice.
 - A texture is freed when a sharper one replaces it and when the element leaves.
 
-## 0.1.0
+## 0.1.0 - 2026-11-03
 
 The first release. The package, to the family's standard from the start: a demo and an embed page on GitHub Pages, a documentation site in English and Japanese, a README with every way to use it (each one tested), the shared release workflow with its freeze test.
 

package/README.md

@@ -1,3 +1,5 @@
+<p align="center"><a href="https://johnmorrisdotca.github.io/wakusei-planets/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/main/docs/images/thumbnail-dark.png"><img src="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/main/docs/images/thumbnail.png" alt="Wakusei Planets: Mars, the Earth, Saturn with its rings, Jupiter and Neptune, shaded in 3D, side by side." width="1200"></picture></a></p>
+
 <h1 align="center">Wakusei Planets <sub>惑星</sub></h1>
 
 <p align="center"><strong>The Sun, the planets and their moons, for the web.</strong><br>
@@ -11,9 +13,9 @@ A clean line drawing, a shaded realistic drawing, or a painted surface map, with
 
 <p align="center"><a href="https://johnmorrisdotca.github.io/wakusei-planets/"><strong>Open the demo →</strong></a> · <a href="https://johnmorrisdotca.github.io/wakusei-planets/embed.html">Embed page</a> · <a href="https://johnmorrisdotca.github.io/wakusei-planets/docs/">Docs</a></p>
 
-<p align="center"><img alt="Jupiter and Saturn drawn in the realistic look, and Saturn as a line drawing" src="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/v0.4.0/docs/images/hero-desk.png" width="640"></p>
+<p align="center"><img alt="Jupiter and Saturn drawn in the realistic look, and Saturn as a line drawing" src="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/v0.5.1/docs/images/hero-desk.png" width="640"></p>
 
-<p align="center"><img alt="Every body at one scale, the Earth among them: each small body has a magnified picture joined by a line, and the Sun shows only its edge" src="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/v0.4.0/docs/images/lineup-desk.png" width="640"></p>
+<p align="center"><img alt="Every body at one scale, the Earth among them: each small body has a magnified picture joined by a line, and the Sun shows only its edge" src="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/v0.5.1/docs/images/lineup-desk.png" width="640"></p>
 
 ## One minute
 
@@ -68,6 +70,37 @@ The same tag with the shared [kazoku-ui](https://github.com/johnmorrisdotca/kazo
 
 A bundled app imports it: `import "@johnmorrisdotca/wakusei-planets/element"` (and `import { lineSvg } from "@johnmorrisdotca/wakusei-planets"` for the SVG string, which needs no browser). For the shaded look add the body's own entry point, `import "@johnmorrisdotca/wakusei-planets/jupiter"`, and `three` (an optional peer).
 
+## Who it is for
+
+- **A developer who wants a planet on a page** with one tag, no build step, and a drawing that is an SVG before any 3D has loaded.
+- **A teacher, writer or museum** who needs the Sun, the planets and their moons at their real sizes and tilts, with every number traceable to the IAU, NASA or JPL.
+- **A maker of sky tools** who wants a planet's pole, phase, ring opening and its moons' places for any date and time as plain data, on a server or in a browser.
+- **A three.js developer** who wants the bodies as objects for a scene of their own.
+
+## Features
+
+- The Sun, the eight planets, Pluto and 25 moons, each with its real size, flattening, axial tilt, pole and rotation as data.
+- Three looks: a clean `line` drawing (an SVG string), a shaded `realistic` sphere worked out in a shader, and a `painted` surface map from public-domain imagery.
+- The sky for any date and time: a body's pole, rotation, phase and ring opening as the Earth sees it, and a planet's moons where they are then.
+- One WebGL context for the page, nothing drawn at rest, at most thirty frames a second, and everything freed when an element leaves.
+- A pure side that runs on a server: `BODIES`, `apparent`, `system`, `orbitPath`, `portrait` and `lineSvg`.
+- `embedCode` writes the code that puts a body in a page for HTML, a module, React, Vue, Angular, Svelte or an iframe.
+- `painter.make` hands a body to a three.js scene of your own.
+- Every guide in English and Japanese; the demo's words too.
+
+## Use it in your project
+
+```sh
+npm install @johnmorrisdotca/wakusei-planets three
+```
+
+```ts no-run
+import "@johnmorrisdotca/wakusei-planets/element";
+import "@johnmorrisdotca/wakusei-planets/saturn";
+```
+
+Import the element once in client code, and the entry point of each body you draw in a shaded look (or `/all`). A line drawing needs neither `three` nor an entry point. [Bundlers](docs/guides/bundlers.md) and [Frameworks](docs/guides/frameworks.md) go through it.
+
 ## Three looks
 
 | Look | What it is | Needs |
@@ -145,6 +178,229 @@ The pure side has no DOM: `BODIES`, `apparent(id, time)`, `system(planet, time)`
 
 Sizes, flattening, poles and rotation are the IAU's and NASA's; planet positions are JPL's approximate elements; the Moon's are Meeus's largest terms; the other moons are JPL's mean elements. Nothing is fetched at run time by the line and shaded looks, which use no pictures. See [NOTICE.md](NOTICE.md).
 
+## Examples
+
+Every `ts` block in this README is type-checked and run against the package as npm packs it (`pnpm test:readme`).
+
+```ts
+import { BODIES, MOONS_OF, PLANET_IDS } from "@johnmorrisdotca/wakusei-planets";
+
+BODIES.saturn.radiusKm; // 60268
+PLANET_IDS.length; // 9
+Object.values(MOONS_OF).flat().length; // 25
+```
+
+The planets' state as the Earth sees them on a date:
+
+```ts
+import { apparent } from "@johnmorrisdotca/wakusei-planets";
+
+const saturn = apparent("saturn", Date.UTC(2026, 10, 2));
+console.log(saturn.subObserverLat.toFixed(1), saturn.illumination.toFixed(2));
+```
+
+A planet's moons where they are on a date, as offsets from it in the planet's radii:
+
+```ts
+import { system } from "@johnmorrisdotca/wakusei-planets";
+
+const { moons } = system("jupiter", Date.UTC(2026, 10, 2));
+console.log(moons.map((moon) => `${moon.id} ${moon.x.toFixed(1)}`).join(", "));
+```
+
+A line drawing as an SVG string, with no browser:
+
+```ts
+import { lineSvg } from "@johnmorrisdotca/wakusei-planets";
+
+const svg = lineSvg("mars", { size: 200, tilt: 15, lang: "ja" });
+if (!svg.startsWith("<svg") || !svg.includes("火星")) throw new Error("not a Mars drawing");
+```
+
+The code that puts a body in a page, for any of the ways a page is made:
+
+```ts
+import { EMBED_KINDS, embedCode } from "@johnmorrisdotca/wakusei-planets";
+
+for (const kind of EMBED_KINDS) console.log(kind, embedCode({ body: "mars", look: "line", size: 240 }, kind).split("\n")[0]);
+```
+
+A body for your own three.js scene, in the browser:
+
+The moons' places on an orbit, as points for a line you draw yourself:
+
+```ts
+import { orbitPath } from "@johnmorrisdotca/wakusei-planets";
+
+const path = orbitPath("io", Date.UTC(2026, 10, 2), 8);
+console.log(path.length / 3, "points");
+```
+
+How much of the Moon is lit on a date:
+
+```ts
+import { apparent } from "@johnmorrisdotca/wakusei-planets";
+
+const moon = apparent("moon", Date.UTC(2026, 10, 24, 14));
+if (moon.illumination < 0.9) throw new Error("the Moon is nearly full on 24 November 2026");
+```
+
+A page that cannot run script uses an iframe of the embed page:
+
+```html
+<iframe src="https://johnmorrisdotca.github.io/wakusei-planets/embed.html?body=mars&look=line" title="Mars" width="320" height="320" style="border:0"></iframe>
+```
+
+```ts no-run
+import * as THREE from "three";
+import { painter } from "@johnmorrisdotca/wakusei-planets/painter";
+
+const scene = new THREE.Scene();
+const jupiter = painter.make(THREE, "Jupiter", { look: "realistic", invalidate: () => {}, ratio: 1 });
+scene.add(jupiter.object);
+```
+
+A body that turns by itself and a moving sky, in HTML:
+
+```html
+<wakusei-body body="jupiter" look="line" moons time="now" rate="600" size="360"></wakusei-body>
+<wakusei-body body="venus" look="realistic" time="2026-11-02T12:00:00Z" turn="12" live="hover"></wakusei-body>
+```
+
+## The code builder
+
+[The code builder](https://johnmorrisdotca.github.io/wakusei-planets/builder.html) is one screen: choose which planet's system, the body, the look, the size, the sky and the turning, then pick how your page is made and copy the code. It is built from `embedCode`, so it writes what the package writes. [Put it in your page](docs/guides/put-it-in-your-page.md) is its guide.
+
+## 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/wakusei-planets/docs/).
+
+| Entry point | What it gives |
+| --- | --- |
+| `@johnmorrisdotca/wakusei-planets` | The pure side: `BODIES`, `apparent`, `system`, `orbitPath`, `portrait`, `lineSvg`, `embedCode`. No browser. |
+| `.../element` | `<wakusei-body>`; three.js is loaded only for a shaded look. |
+| `.../look` | What a body needs to be drawn with three.js. |
+| `.../painter` | The bodies as objects for a scene of your own. |
+| `.../all` | Every body's shaded look, at once. |
+| `.../saturn`, `.../jupiter` and the rest | One body's shaded look. `.../moons-jupiter` and its siblings: a planet's moons. |
+
+```ts
+import * as pure from "@johnmorrisdotca/wakusei-planets";
+
+console.log(Object.keys(pure).sort().join(", "));
+```
+
+## Guides
+
+Each guide has a Japanese twin in [docs/guides/ja](docs/guides/ja/getting-started.md).
+
+| Guide | What it is for |
+| --- | --- |
+| [Getting started](docs/guides/getting-started.md) | A body on a page |
+| [HTML and CDN](docs/guides/html-and-cdn.md) | A script tag from jsDelivr or unpkg |
+| [Bundlers](docs/guides/bundlers.md) | Vite and webpack, only the bodies you need |
+| [Frameworks](docs/guides/frameworks.md) | React, Vue, Svelte, Angular |
+| [Embed in an iframe](docs/guides/embed-in-an-iframe.md) | No script of your own |
+| [Put it in your page](docs/guides/put-it-in-your-page.md) | Set up a body and copy the code |
+| [Looks and bodies](docs/guides/looks-and-bodies.md) | The looks and each body's entry point |
+| [Moons and time](docs/guides/moons-and-time.md) | The sky on a date, time that runs fast |
+| [In your own three.js scene](docs/guides/in-your-own-scene.md) | `painter.make` |
+| [TypeScript and Node](docs/guides/typescript-and-node.md) | Types and the pure side |
+| [How it works](docs/guides/how-it-works.md) | Where the numbers come from |
+| [Architecture](docs/guides/architecture.md) | How the layers fit |
+| [Troubleshooting](docs/guides/troubleshooting.md) | Something does not appear |
+| [Upgrading](docs/guides/upgrading.md) | What to act on between versions |
+
+## Limits
+
+```ts
+import { BODIES } from "@johnmorrisdotca/wakusei-planets";
+
+BODIES.pluto.kind; // "dwarf-planet"
+```
+
+- A fact with no source is left out, never guessed. Moon positions are JPL's mean elements and are accurate to a few degrees on the orbit, about the size of the moon on screen.
+- The shaded `realistic` look works out a surface from the body's real colours and features in a shader: it is a likeness, not a map. The `painted` look is a real map where one exists; the Sun, Saturn, Uranus and Neptune have no global map, so theirs are made from one photograph each, as `NOTICE.md` says.
+- A shaded look needs WebGL. Without it the line drawing is drawn.
+- Saturn and Uranus have their rings drawn.
+- Pictures for the painted look are 1.31 MB in the package at 512 and 1024 pixels; a sharper picture is fetched when you zoom in.
+
+## Accessibility
+
+- Every `<wakusei-body>` is an image with an accessible name from its body and look, such as "Saturn, line drawing", or the Japanese name with `lang="ja"`.
+- A reader who prefers reduced motion gets no turning and no moving sky.
+- A body can be turned, tipped, zoomed and panned with the keyboard, and the view controls are at least 48 pixels.
+- Names and labels are in English and Japanese (`lang="ja"`).
+
+```html
+<wakusei-body body="saturn" look="line" lang="ja" size="320"></wakusei-body>
+```
+
+## Browser and runtime support
+
+- The package needs Node 24 or later. The pure side runs in Node and in any current browser; the element needs a current browser.
+- The shaded looks need WebGL and `three` `>=0.160.0` (an optional peer).
+- The tests run the demo in Chromium and WebKit, at a phone's width and a desk's, and draw WebGL in software.
+
+## Languages
+
+The names and labels in the element are in English and Japanese (`lang`), and so are the demo's words and every guide: each guide in [docs/guides](docs/guides) has a twin in [docs/guides/ja](docs/guides/ja/getting-started.md), one language to a page.
+
+```ts
+import { lineSvg } from "@johnmorrisdotca/wakusei-planets";
+
+console.log(lineSvg("saturn", { size: 160, lang: "ja" }).includes("土星"));
+```
+
+Japanese names and labels need only the `lang` attribute; the SVG string takes the same option.
+
+## Architecture
+
+The lowest layers are pure and import with no browser: the facts, the positions, the pose and the line drawing. The shaded looks are one entry point for each body, registered by name, and every `<wakusei-body>` shares one WebGL context through kazoku-ui. [Architecture](docs/guides/architecture.md) has the layers.
+
+```ts
+import { portrait } from "@johnmorrisdotca/wakusei-planets";
+
+const pose = portrait("uranus");
+console.log(pose.pole.length);
+```
+
+## Development
+
+```sh
+pnpm install
+pnpm check         # lint, types, unit tests, the build and the packed package
+pnpm test:readme   # every ts block of the README, type-checked and run against the packed package
+pnpm test:usage    # every way of using it in the README and the guides, built and opened
+pnpm docs:check    # the reference site's checks
+pnpm test:demo     # the demo and the docs site in a real browser
+pnpm dev           # the demo on http://127.0.0.1:8300/wakusei-planets/
+```
+
+The pictures in `docs/images` are made by the package's own script:
+
+```sh
+ONLY=hero-saturn-painted,builder-desk pnpm screenshots
+```
+
+## Contributing
+
+Work in a git worktree from `origin/main`, one branch per change:
+
+```sh
+git worktree add ../wakusei-work -b my-change origin/main
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The rules that matter most: draw from public facts and cite them, pictures only from public-domain sources, a fact with no source is left out, and performance is not optional.
+
+## Changes
+
+[CHANGELOG.md](CHANGELOG.md) lists every release with its date.
+
+## Licence
+
+MIT: see [LICENSE](LICENSE). The pictures are public-domain NASA, USGS and JPL imagery, each file credited in [NOTICE.md](NOTICE.md).
+
 ## The name
 
 Wakusei (惑星, わくせい) is Japanese for a planet.

package/dist/element.d.ts

@@ -25,7 +25,7 @@ export type WakuseiState = "line" | "loading" | "still" | "live" | "lost" | "una
  * console.log(TEXTURE_BASE);
  * ```
  */
-export declare const TEXTURE_BASE = "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/wakusei-planets@0.4.0/dist/textures/";
+export declare const TEXTURE_BASE = "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/wakusei-planets@0.5.1/dist/textures/";
 /**
  * Where the sharpest surface pictures are: the files of this exact version in the repository, on jsDelivr's GitHub address. The npm package holds only the two smaller widths, so a page that
  * never zooms in never fetches them. Set `texture-far-base` on an element to serve them yourself.
@@ -37,7 +37,7 @@ export declare const TEXTURE_BASE = "https://cdn.jsdelivr.net/npm/@johnmorrisdot
  * console.log(TEXTURE_FAR_BASE);
  * ```
  */
-export declare const TEXTURE_FAR_BASE = "https://cdn.jsdelivr.net/gh/johnmorrisdotca/wakusei-planets@v0.4.0/textures/";
+export declare const TEXTURE_FAR_BASE = "https://cdn.jsdelivr.net/gh/johnmorrisdotca/wakusei-planets@v0.5.1/textures/";
 /**
  * The `<wakusei-body>` custom element: a body of the solar system, drawn in a look.
  *

package/dist/scene/glsl.d.ts

@@ -2,11 +2,20 @@ export declare const VERTEX = "\nvarying vec3 vObj;\nvarying vec3 vN;\nvarying v
 /** Noise, craters and the band palette, for the surface code of a body to call. */
 export declare const PRELUDE = "\nfloat hash13(vec3 p) { p = fract(p * 0.1031); p += dot(p, p.zyx + 31.32); return fract((p.x + p.y) * p.z); }\nvec3 hash33(vec3 p) { p = fract(p * vec3(0.1031, 0.1030, 0.0973)); p += dot(p, p.yxz + 33.33); return fract((p.xxy + p.yxx) * p.zyx); }\nfloat vnoise(vec3 p) {\n  vec3 i = floor(p); vec3 f = fract(p); f = f * f * (3.0 - 2.0 * f);\n  return mix(mix(mix(hash13(i), hash13(i + vec3(1,0,0)), f.x), mix(hash13(i + vec3(0,1,0)), hash13(i + vec3(1,1,0)), f.x), f.y),\n             mix(mix(hash13(i + vec3(0,0,1)), hash13(i + vec3(1,0,1)), f.x), mix(hash13(i + vec3(0,1,1)), hash13(i + vec3(1,1,1)), f.x), f.y), f.z);\n}\nfloat fbm(vec3 p) { float a = 0.5; float s = 0.0; for (int i = 0; i < 5; i++) { s += a * vnoise(p); p = p * 2.03 + vec3(1.7, 9.2, 3.1); a *= 0.5; } return s; }\n// Craters: a bowl and a raised rim in each cell that has one. Returns a height, negative in a bowl.\nfloat craters(vec3 p, float freq, float amp, float seed) {\n  vec3 q = p * freq + seed; vec3 ip = floor(q); float h = 0.0;\n  for (int x = -1; x <= 1; x++) for (int y = -1; y <= 1; y++) for (int z = -1; z <= 1; z++) {\n    vec3 c = ip + vec3(float(x), float(y), float(z));\n    float on = step(0.52, hash13(c + 3.7));\n    vec3 ctr = c + hash33(c);\n    float rad = mix(0.12, 0.36, hash13(c + 17.3));\n    float d = length(q - ctr) / rad;\n    float bowl = d < 1.0 ? (d * d - 1.0) : 0.0;\n    float rim = d >= 1.0 ? exp(-pow((d - 1.0) * 5.0, 2.0)) * 0.3 : 0.0;\n    h += on * amp * rad * (bowl + rim);\n  }\n  return h;\n}\nfloat lon(vec3 p) { return atan(p.y, p.x); }\nfloat lat(vec3 p) { return asin(clamp(p.z, -1.0, 1.0)); }\nfloat wrapPi(float a) { return a - 6.2831853 * floor((a + 3.1415927) / 6.2831853); }\nvec3 dirOf(float lonDeg, float latDeg) { float lo = radians(lonDeg); float la = radians(latDeg); return vec3(cos(la) * cos(lo), cos(la) * sin(lo), sin(la)); }\n// One big round bowl with a rim, by longitude, latitude and angular radius in degrees. Negative inside.\nfloat bowl(vec3 p, float lonDeg, float latDeg, float radDeg, float depth) {\n  float d = acos(clamp(dot(p, dirOf(lonDeg, latDeg)), -1.0, 1.0)) / radians(radDeg);\n  return d < 1.0 ? depth * (d * d - 1.0) : depth * exp(-pow((d - 1.0) * 5.0, 2.0)) * 0.3;\n}\n// A soft oval on the body, 1 inside and 0 outside, by longitude and latitude in degrees.\nfloat oval(vec3 p, float lon0, float lat0, float rx, float ry, float soft) {\n  float dx = wrapPi(lon(p) - radians(lon0)) * cos(radians(lat0)) / radians(rx);\n  float dy = (lat(p) - radians(lat0)) / radians(ry);\n  return 1.0 - smoothstep(1.0 - soft, 1.0, sqrt(dx * dx + dy * dy));\n}";
 /** The fragment shader of a body: the surface code goes between the prelude and `main`. */
-export declare function bodyFragment(surface: string, painted: boolean): string;
+export declare function bodyFragment(surface: string, painted: boolean, world?: boolean): string;
 /** A painted body's surface code: the map by longitude and latitude, with the seam at 180 degrees left alone. */
 export declare const PAINTED_SURFACE = "\nvec4 surface(vec3 p) {\n  float u1 = atan(p.y, p.x) / 6.2831853 + 0.5;\n  float u2 = fract(u1 + 0.5) - 0.5;\n  float v = asin(clamp(p.z, -1.0, 1.0)) / 3.1415927 + 0.5;\n  vec2 a = vec2(u1, v); vec2 b = vec2(u2, v);\n  vec2 ax = dFdx(a); vec2 ay = dFdy(a); vec2 bx = dFdx(b); vec2 by = dFdy(b);\n  bool useA = dot(ax, ax) + dot(ay, ay) <= dot(bx, bx) + dot(by, by);\n  vec3 c = textureGrad(uMap, useA ? a : b, useA ? ax : bx, useA ? ay : by).rgb;\n  return vec4(c, dot(c, vec3(0.3, 0.59, 0.11)));\n}";
 export declare const RING_FRAGMENT = "\nprecision highp float;\nuniform sampler2D uRingTex;\nuniform vec2 uRingR;\nuniform vec3 uLight;\nuniform vec3 uRingN;\nvarying vec3 vL;\nvarying vec3 vW;\nvoid main() {\n  float u = (length(vL.xy) - uRingR.x) / (uRingR.y - uRingR.x);\n  if (u < 0.0 || u > 1.0) discard;\n  vec4 t = texture2D(uRingTex, vec2(u, 0.5));\n  float nl = dot(uRingN, uLight);\n  float side = nl * uRingN.z;\n  float bright = 0.16 + 0.84 * clamp(abs(nl) * 2.0, 0.0, 1.0);\n  if (side < 0.0) bright *= 0.38;\n  float b = dot(vW, uLight);\n  float closest = sqrt(max(dot(vW, vW) - b * b, 0.0));\n  float shadow = b < 0.0 ? smoothstep(1.02, 0.97, closest) : 0.0;\n  vec3 c = pow(t.rgb, vec3(2.2)) * bright * (1.0 - 0.93 * shadow);\n  gl_FragColor = vec4(pow(c, vec3(1.0 / 2.2)), t.a);\n}";
 export declare const RING_VERTEX = "\nvarying vec3 vL;\nvarying vec3 vW;\nvoid main() {\n  vL = position;\n  vec4 w = modelMatrix * vec4(position, 1.0);\n  vW = w.xyz;\n  gl_Position = projectionMatrix * viewMatrix * w;\n}";
+/**
+ * The body's vertex shader for a perspective camera and a body anywhere in the scene: the normal and the position are in the scene's axes, the position in body radii from the body's centre
+ * (`uScale` is the body's size in scene units), and `vV` points at the camera.
+ */
+export declare const VERTEX_WORLD = "\nuniform float uScale;\nvarying vec3 vObj;\nvarying vec3 vN;\nvarying vec3 vW;\nvarying vec3 vV;\nvoid main() {\n  vObj = vec3(position.z, position.x, position.y);\n  vec4 w = modelMatrix * vec4(position, 1.0);\n  vN = normalize(transpose(inverse(mat3(modelMatrix))) * normal);\n  vW = mat3(modelMatrix) * position / uScale;\n  vV = cameraPosition - w.xyz;\n  gl_Position = projectionMatrix * viewMatrix * w;\n}";
+/** The ring's vertex shader for a perspective camera, with the same frame as `VERTEX_WORLD`. */
+export declare const RING_VERTEX_WORLD = "\nuniform float uScale;\nvarying vec3 vL;\nvarying vec3 vW;\nvarying vec3 vV;\nvoid main() {\n  vL = position;\n  vec4 w = modelMatrix * vec4(position, 1.0);\n  vW = mat3(modelMatrix) * position / uScale;\n  vV = cameraPosition - w.xyz;\n  gl_Position = projectionMatrix * viewMatrix * w;\n}";
+/** The ring's fragment shader for a perspective camera: which side is seen comes from the direction to the camera. */
+export declare const RING_FRAGMENT_WORLD: string;
 export declare const GLOW_VERTEX = "\nvarying vec2 vP;\nvoid main() { vP = position.xy; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }";
 export declare const GLOW_FRAGMENT = "\nprecision highp float;\nvarying vec2 vP;\nuniform vec3 uColour;\nvoid main() {\n  float r = length(vP);\n  if (r < 0.98) discard;\n  float a = exp(-(r - 1.0) * 2.4) * 0.62;\n  float streak = 0.82 + 0.18 * sin(atan(vP.y, vP.x) * 9.0 + r * 3.0);\n  a *= streak * smoothstep(3.0, 1.6, r);\n  gl_FragColor = vec4(uColour * a, a);\n}";
 /** A cheap lit ball for a moon seen small beside its planet. */

package/dist/scene/glsl.js

@@ -51,7 +51,7 @@ float oval(vec3 p, float lon0, float lat0, float rx, float ry, float soft) {
   return 1.0 - smoothstep(1.0 - soft, 1.0, sqrt(dx * dx + dy * dy));
 }`;
 /** The fragment shader of a body: the surface code goes between the prelude and `main`. */
-export function bodyFragment(surface, painted) {
+export function bodyFragment(surface, painted, world = false) {
     return /* glsl */ `
 precision highp float;
 uniform vec3 uLight;
@@ -70,13 +70,14 @@ ${painted ? "uniform sampler2D uMap;" : ""}
 varying vec3 vObj;
 varying vec3 vN;
 varying vec3 vW;
+${world ? "varying vec3 vV;" : ""}
 ${PRELUDE}
 ${surface}
 void main() {
   vec3 p = normalize(vObj);
   vec4 s = surface(p);
   vec3 n = normalize(vN);
-  float mu = clamp(n.z, 0.0, 1.0);
+  float mu = ${world ? "clamp(dot(n, normalize(vV)), 0.0, 1.0)" : "clamp(n.z, 0.0, 1.0)"};
   if (uEmissive > 0.5) {
     float edge = pow(mu, uLimb);
     vec3 c = s.rgb * mix(vec3(1.0, 0.55, 0.25), vec3(1.0), edge) * (0.55 + 0.45 * edge);
@@ -153,6 +154,39 @@ void main() {
   vW = w.xyz;
   gl_Position = projectionMatrix * viewMatrix * w;
 }`;
+/**
+ * The body's vertex shader for a perspective camera and a body anywhere in the scene: the normal and the position are in the scene's axes, the position in body radii from the body's centre
+ * (`uScale` is the body's size in scene units), and `vV` points at the camera.
+ */
+export const VERTEX_WORLD = /* glsl */ `
+uniform float uScale;
+varying vec3 vObj;
+varying vec3 vN;
+varying vec3 vW;
+varying vec3 vV;
+void main() {
+  vObj = vec3(position.z, position.x, position.y);
+  vec4 w = modelMatrix * vec4(position, 1.0);
+  vN = normalize(transpose(inverse(mat3(modelMatrix))) * normal);
+  vW = mat3(modelMatrix) * position / uScale;
+  vV = cameraPosition - w.xyz;
+  gl_Position = projectionMatrix * viewMatrix * w;
+}`;
+/** The ring's vertex shader for a perspective camera, with the same frame as `VERTEX_WORLD`. */
+export const RING_VERTEX_WORLD = /* glsl */ `
+uniform float uScale;
+varying vec3 vL;
+varying vec3 vW;
+varying vec3 vV;
+void main() {
+  vL = position;
+  vec4 w = modelMatrix * vec4(position, 1.0);
+  vW = mat3(modelMatrix) * position / uScale;
+  vV = cameraPosition - w.xyz;
+  gl_Position = projectionMatrix * viewMatrix * w;
+}`;
+/** The ring's fragment shader for a perspective camera: which side is seen comes from the direction to the camera. */
+export const RING_FRAGMENT_WORLD = RING_FRAGMENT.replace("varying vec3 vW;", "varying vec3 vW;\nvarying vec3 vV;").replace("float side = nl * uRingN.z;", "float side = nl * dot(uRingN, normalize(vV));");
 export const GLOW_VERTEX = /* glsl */ `
 varying vec2 vP;
 void main() { vP = position.xy; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }`;

package/dist/scene/orient.d.ts

@@ -0,0 +1,38 @@
+import { type BodyId, type MoonId } from "../facts.ts";
+import { type Vec3 } from "../vec.ts";
+/**
+ * Where a moon is from its planet's centre, in planet radii, in the scene's axes (x to the vernal equinox, y north).
+ *
+ * @param id - The moon's name.
+ * @param ms - The instant, in milliseconds since 1970.
+ * @returns The offset, in radii of the planet the moon goes round.
+ *
+ * @example
+ * ```ts
+ * import { moonOffset } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const [x, y, z] = moonOffset("io", Date.UTC(2026, 10, 2));
+ * console.log(Math.hypot(x, y, z).toFixed(1));
+ * ```
+ */
+export declare function moonOffset(id: MoonId, ms: number): Vec3;
+/**
+ * The north pole and the prime meridian of a body at a time, as unit vectors in the scene's axes (x to the vernal equinox, y north). A moon that keeps one face to its planet is
+ * given the direction to the planet as its meridian, so its near side faces the planet.
+ *
+ * @param id - The body's name.
+ * @param ms - The instant, in milliseconds since 1970.
+ * @returns The pole and the direction of longitude 0, both unit vectors.
+ *
+ * @example
+ * ```ts
+ * import { orientation } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const { pole } = orientation("mars", Date.UTC(2026, 10, 2));
+ * console.log(pole.map((n) => n.toFixed(2)).join(", "));
+ * ```
+ */
+export declare function orientation(id: BodyId, ms: number): {
+    pole: Vec3;
+    meridian: Vec3;
+};

package/dist/scene/orient.js

@@ -0,0 +1,72 @@
+// How a body is turned in space at a time, in the axes of an equatorial J2000 scene with y up (x to the vernal equinox, y to the celestial north pole, z toward -y of the equator).
+// Pure: no three.js. The painter uses it to turn each body about its real pole, and to find where a moon is round its planet.
+import { moonVector } from "../ephemeris.js";
+import { BODIES } from "../facts.js";
+import { cross, dot, fromRaDec, OBLIQUITY, RAD, unit, wrap360 } from "../vec.js";
+const J2000 = Date.UTC(2000, 0, 1, 12);
+const DAY = 86_400_000;
+/** An equatorial vector (x to the vernal equinox, z to the north pole) in the scene's axes. */
+const toScene = (v) => [v[0], v[2], -v[1]];
+/** An ecliptic J2000 vector in equatorial J2000 axes. */
+const fromEcliptic = (v) => {
+    const c = Math.cos(OBLIQUITY * RAD);
+    const s = Math.sin(OBLIQUITY * RAD);
+    return [v[0], v[1] * c - v[2] * s, v[1] * s + v[2] * c];
+};
+/**
+ * Where a moon is from its planet's centre, in planet radii, in the scene's axes (x to the vernal equinox, y north).
+ *
+ * @param id - The moon's name.
+ * @param ms - The instant, in milliseconds since 1970.
+ * @returns The offset, in radii of the planet the moon goes round.
+ *
+ * @example
+ * ```ts
+ * import { moonOffset } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const [x, y, z] = moonOffset("io", Date.UTC(2026, 10, 2));
+ * console.log(Math.hypot(x, y, z).toFixed(1));
+ * ```
+ */
+export function moonOffset(id, ms) {
+    const facts = BODIES[id];
+    const radius = BODIES[facts.parent ?? "earth"].radiusKm;
+    const v = toScene(fromEcliptic(moonVector(id, ms)));
+    return [v[0] / radius, v[1] / radius, v[2] / radius];
+}
+/**
+ * The north pole and the prime meridian of a body at a time, as unit vectors in the scene's axes (x to the vernal equinox, y north). A moon that keeps one face to its planet is
+ * given the direction to the planet as its meridian, so its near side faces the planet.
+ *
+ * @param id - The body's name.
+ * @param ms - The instant, in milliseconds since 1970.
+ * @returns The pole and the direction of longitude 0, both unit vectors.
+ *
+ * @example
+ * ```ts
+ * import { orientation } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const { pole } = orientation("mars", Date.UTC(2026, 10, 2));
+ * console.log(pole.map((n) => n.toFixed(2)).join(", "));
+ * ```
+ */
+export function orientation(id, ms) {
+    const facts = BODIES[id];
+    const { ra, dec } = facts.pole;
+    const pole = fromRaDec(ra, dec);
+    let meridian;
+    if (facts.synchronous === true && facts.parent !== undefined) {
+        const planetward = unit(fromEcliptic(moonVector(id, ms)).map((n) => -n));
+        const d = dot(planetward, pole);
+        meridian = unit([planetward[0] - pole[0] * d, planetward[1] - pole[1] * d, planetward[2] - pole[2] * d]);
+    }
+    else {
+        const w = wrap360(facts.prime.w0 + facts.prime.rate * ((ms - J2000) / DAY));
+        const node = fromRaDec(ra + 90, 0);
+        const third = cross(pole, node);
+        const c = Math.cos(w * RAD);
+        const s = Math.sin(w * RAD);
+        meridian = [node[0] * c + third[0] * s, node[1] * c + third[1] * s, node[2] * c + third[2] * s];
+    }
+    return { pole: toScene(pole), meridian: toScene(meridian) };
+}

package/dist/scene/painter.d.ts

@@ -0,0 +1,164 @@
+import type * as THREE from "three";
+import "../bodies/all.ts";
+import { type Vec3 } from "../vec.ts";
+import { moonOffset, orientation } from "./orient.ts";
+export { moonOffset, orientation };
+/**
+ * The looks the painter draws: `realistic` (shaded from the body's real colours and features) and `painted` (a public-domain surface map, with the shaded look until it arrives).
+ *
+ * @example
+ * ```ts no-run
+ * import { LOOKS, type PainterLook } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const first: PainterLook = LOOKS[0];
+ * console.log(first);
+ * ```
+ */
+export declare const LOOKS: readonly ["realistic", "painted"];
+/**
+ * One of the looks in `LOOKS`: `realistic` or `painted`.
+ *
+ * @example
+ * ```ts no-run
+ * import type { PainterLook } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const look: PainterLook = "painted";
+ * console.log(look);
+ * ```
+ */
+export type PainterLook = (typeof LOOKS)[number];
+/**
+ * What the caller gives the painter when it makes a body.
+ *
+ * @example
+ * ```ts no-run
+ * import type { PaintContext } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const context: PaintContext = { look: "painted", invalidate: () => undefined, ratio: 2 };
+ * console.log(context.look);
+ * ```
+ */
+export interface PaintContext {
+    /** `realistic` (the default) or `painted`. */
+    look?: string;
+    /** Ask for a new draw: a sharper picture has arrived. */
+    invalidate?(): void;
+    /** Device pixels to a CSS pixel; default 1. */
+    ratio?: number;
+    /** The widest picture the GPU should be given, in pixels; default 2048. */
+    maxTexture?: number;
+}
+/**
+ * What the caller tells a painted body at each draw: the direction to the Sun (a unit vector in the scene's axes), the time, and how many CSS pixels across its radius the body is on the screen.
+ *
+ * @example
+ * ```ts no-run
+ * import type { PaintInfo } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const info: PaintInfo = { toSun: [1, 0, 0], ms: Date.UTC(2026, 10, 2), radiusPx: 80 };
+ * console.log(info.radiusPx);
+ * ```
+ */
+export interface PaintInfo {
+    toSun: Vec3;
+    ms: number;
+    radiusPx: number;
+}
+/**
+ * One body made by the painter: an object of radius 1 at the origin for the caller to move and scale.
+ *
+ * @example
+ * ```ts no-run
+ * import type { Painting } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const stop = (painting: Painting): void => painting.dispose();
+ * console.log(typeof stop);
+ * ```
+ */
+export interface Painting {
+    object: THREE.Object3D;
+    /** True to have the caller turn the object to face the camera (the Sun, which carries a glow). */
+    billboard?: boolean;
+    /** Call at each draw, after the object has been placed and scaled. */
+    update(info: PaintInfo): void;
+    dispose(): void;
+}
+/**
+ * One moon of a planet at a time: where it is from the planet's centre and how big it is, both in radii of the planet, in the scene's axes.
+ *
+ * @example
+ * ```ts no-run
+ * import { painter } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const io = painter.moons("Jupiter", Date.UTC(2026, 10, 2))[0];
+ * console.log(io?.name, io?.radius.toFixed(3));
+ * ```
+ */
+export interface MoonSite {
+    /** The moon's name as `make` takes it, for example `Io`. */
+    name: string;
+    offset: Vec3;
+    radius: number;
+}
+/**
+ * Where the pictures are, if not on jsDelivr: a folder address that ends in a slash. `farBase` holds the widest pictures (2048), which the npm package leaves out.
+ *
+ * @example
+ * ```ts no-run
+ * import { createPainter, type PainterOptions } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const options: PainterOptions = { textureBase: "/textures/", farBase: "/textures/" };
+ * console.log(createPainter(options).looks);
+ * ```
+ */
+export interface PainterOptions {
+    textureBase?: string;
+    farBase?: string;
+}
+/**
+ * A painter: makes the bodies as three.js objects (`make`) and tells where a planet's moons are (`moons`). Its shape is chikyu-earth's `BodyPainter`, so `setBodyPainter(painter)` is all the wiring.
+ *
+ * @example
+ * ```ts no-run
+ * import { createPainter, type WakuseiPainter } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const mine: WakuseiPainter = createPainter({ textureBase: "/pictures/", farBase: "/pictures/" });
+ * console.log(mine.looks.join(", "));
+ * ```
+ */
+export interface WakuseiPainter {
+    /** The looks `make` takes in `context.look`. */
+    readonly looks: readonly PainterLook[];
+    /** Make a body: `Sun`, a planet, `Pluto` or a moon, in any case. Throws for a name it does not know. */
+    /** `three` is the three.js module (or a subset of it holding the parts `PainterThree` names); it is typed loosely so that another package can hand over its own subset. */
+    make(three: object, name: string, context?: PaintContext): Painting;
+    /** The moons the painter draws for a planet (none for the Earth: its Moon is the viewer's own), where they are at a time, nearest first. */
+    moons(planet: string, ms: number): MoonSite[];
+}
+/**
+ * Make a painter that takes its pictures from the given folders (jsDelivr's copy of this version by default).
+ *
+ * @param options - Where the pictures are.
+ * @returns The painter.
+ *
+ * @example
+ * ```ts no-run
+ * import { createPainter } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const painter = createPainter();
+ * console.log(painter.moons("Mars", Date.UTC(2026, 10, 2)).map((m) => m.name));
+ * ```
+ */
+export declare function createPainter(options?: PainterOptions): WakuseiPainter;
+/**
+ * The painter with its default pictures: pass it to chikyu-earth's `setBodyPainter`.
+ *
+ * @example
+ * ```ts no-run
+ * import { painter } from "@johnmorrisdotca/wakusei-planets/painter";
+ * import { setBodyPainter } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * setBodyPainter(painter);
+ * ```
+ */
+export declare const painter: WakuseiPainter;

package/dist/scene/painter.js

@@ -0,0 +1,355 @@
+import "../bodies/all.js";
+import { BODIES, MOONS_OF } from "../facts.js";
+import { VERSION } from "../version.js";
+import { cross } from "../vec.js";
+import { bodyFragment, GLOW_FRAGMENT, GLOW_VERTEX, PAINTED_SURFACE, RING_FRAGMENT_WORLD, RING_VERTEX_WORLD, VERTEX_WORLD } from "./glsl.js";
+import { lookOf } from "./look.js";
+import { moonOffset, orientation } from "./orient.js";
+import { ringStrip } from "./rings.js";
+export { moonOffset, orientation };
+/**
+ * The looks the painter draws: `realistic` (shaded from the body's real colours and features) and `painted` (a public-domain surface map, with the shaded look until it arrives).
+ *
+ * @example
+ * ```ts no-run
+ * import { LOOKS, type PainterLook } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const first: PainterLook = LOOKS[0];
+ * console.log(first);
+ * ```
+ */
+export const LOOKS = ["realistic", "painted"];
+const TEXTURE_BASE = `https://cdn.jsdelivr.net/npm/@johnmorrisdotca/wakusei-planets@${VERSION}/dist/textures/`;
+const TEXTURE_FAR_BASE = `https://cdn.jsdelivr.net/gh/johnmorrisdotca/wakusei-planets@v${VERSION}/textures/`;
+const slash = (base) => (base.endsWith("/") ? base : `${base}/`);
+const titled = (id) => id.charAt(0).toUpperCase() + id.slice(1);
+const pools = new WeakMap();
+function acquire(three, key, make) {
+    let pool = pools.get(three);
+    if (pool === undefined)
+        pools.set(three, (pool = new Map()));
+    let held = pool.get(key);
+    if (held === undefined)
+        pool.set(key, (held = { value: make(), users: 0 }));
+    held.users += 1;
+    const mine = held;
+    const owner = pool;
+    let released = false;
+    return {
+        value: mine.value,
+        release() {
+            if (released)
+                return;
+            released = true;
+            mine.users -= 1;
+            if (mine.users <= 0) {
+                mine.value.dispose();
+                owner.delete(key);
+            }
+        },
+    };
+}
+const fallbackLook = (id) => {
+    const c = [1, 3, 5].map((i) => (parseInt(BODIES[id].colour.slice(i, i + 2), 16) / 255).toFixed(3)).join(", ");
+    return { id, surface: `vec4 surface(vec3 p) { float n = fbm(p * 5.0); return vec4(vec3(${c}) * (0.85 + 0.3 * n), 0.0); }` };
+};
+/** The name of a body as the painter takes it: any case, `Sun`, a planet or Pluto, or a moon such as `Io`. */
+function idOf(name) {
+    const id = name.toLowerCase();
+    if (!(id in BODIES))
+        throw new Error(`wakusei-planets: no body called ${name}`);
+    return id;
+}
+const moonsOf = (planet) => {
+    const id = planet.toLowerCase();
+    return id === "earth" ? [] : id in MOONS_OF ? MOONS_OF[id] : [];
+};
+function paint(T, id, context, bases) {
+    const facts = BODIES[id];
+    const look = lookOf(id) ?? fallbackLook(id);
+    const wantPainted = (context.look === "painted" || look.mapped === true) && look.painted !== undefined;
+    const ratio = context.ratio ?? 1;
+    const maxWidth = context.maxTexture ?? 2048;
+    const redraw = () => context.invalidate?.();
+    const releases = [];
+    const disposables = [];
+    const sphere = acquire(T, "sphere", () => new T.SphereGeometry(1, 96, 48));
+    releases.push(sphere.release);
+    const group = new T.Group();
+    group.name = facts.name.en;
+    const uniforms = (painted) => {
+        const a = look.atmosphere;
+        return {
+            uLight: { value: new T.Vector3(1, 0, 0) },
+            uRelief: { value: painted ? (look.painted?.relief ?? 0) : (look.relief ?? 0.6) },
+            uAmbient: { value: look.ambient ?? 0.04 },
+            uLimb: { value: look.limb ?? 0 },
+            uWrap: { value: look.wrap ?? (a === undefined ? 0.04 : 0.3) },
+            uAtmos: { value: new T.Vector3(...(a?.colour ?? [0, 0, 0])) },
+            uAtmosPow: { value: a?.power ?? 3 },
+            uEmissive: { value: look.emissive === true ? 1 : 0 },
+            uRingN: { value: new T.Vector3(0, 1, 0) },
+            uRingR: { value: new T.Vector2(1, 2) },
+            uRingOn: { value: 0 },
+            uRingTex: { value: null },
+            uMap: { value: null },
+            uScale: { value: 1 },
+        };
+    };
+    const material = (painted) => {
+        const m = new T.ShaderMaterial({ vertexShader: VERTEX_WORLD, fragmentShader: bodyFragment(painted ? PAINTED_SURFACE : look.surface, painted, true), uniforms: uniforms(painted) });
+        disposables.push(m);
+        return m;
+    };
+    const shader = material(false);
+    const paintedMaterial = wantPainted ? material(true) : undefined;
+    const materials = [shader, ...(paintedMaterial ? [paintedMaterial] : [])];
+    const mesh = new T.Mesh(sphere.value, shader);
+    mesh.matrixAutoUpdate = false;
+    group.add(mesh);
+    // rings: the table's strip at once, the picture of them (painted) when it arrives
+    let ringMesh;
+    let ringMaterial;
+    let ringTexture;
+    let ringInner = 1;
+    let ringOuter = 2;
+    const table = look.emissive === true ? null : ringStrip(facts, 1024);
+    const loadImage = (url) => new Promise((resolve, reject) => {
+        const loader = new T.TextureLoader();
+        loader.setCrossOrigin("anonymous");
+        loader.load(url, resolve, undefined, (e) => reject(e instanceof Error ? e : new Error("texture failed")));
+    });
+    let gone = false;
+    if (table !== null) {
+        ringInner = table.inner;
+        ringOuter = table.outer;
+        const strip = new T.DataTexture(table.data, table.width, 1, T.RGBAFormat);
+        strip.magFilter = T.LinearFilter;
+        strip.minFilter = T.LinearFilter;
+        strip.wrapS = T.ClampToEdgeWrapping;
+        strip.needsUpdate = true;
+        ringTexture = strip;
+        const ringGeometry = new T.RingGeometry(ringInner, ringOuter, 256, 1);
+        disposables.push(ringGeometry);
+        ringMaterial = new T.ShaderMaterial({
+            vertexShader: RING_VERTEX_WORLD,
+            fragmentShader: RING_FRAGMENT_WORLD,
+            side: T.DoubleSide,
+            transparent: true,
+            depthWrite: false,
+            uniforms: { uRingTex: { value: strip }, uRingR: { value: new T.Vector2(ringInner, ringOuter) }, uLight: { value: new T.Vector3(1, 0, 0) }, uRingN: { value: new T.Vector3(0, 1, 0) }, uScale: { value: 1 } },
+        });
+        disposables.push(ringMaterial);
+        ringMesh = new T.Mesh(ringGeometry, ringMaterial);
+        ringMesh.matrixAutoUpdate = false;
+        ringMesh.renderOrder = 1;
+        group.add(ringMesh);
+        const photo = wantPainted ? look.painted?.rings : undefined;
+        if (photo !== undefined) {
+            void loadImage(`${bases.near}${photo.map}-${photo.width}.webp`).then((t) => {
+                if (gone) {
+                    t.dispose();
+                    return;
+                }
+                t.magFilter = T.LinearFilter;
+                t.minFilter = T.LinearFilter;
+                t.generateMipmaps = false;
+                t.wrapS = T.ClampToEdgeWrapping;
+                t.colorSpace = T.NoColorSpace;
+                ringTexture?.dispose();
+                ringTexture = t;
+                ringInner = photo.from / facts.radiusKm;
+                ringOuter = photo.to / facts.radiusKm;
+                ringMesh.geometry.dispose();
+                ringMesh.geometry = new T.RingGeometry(ringInner, ringOuter, 256, 1);
+                disposables.push(ringMesh.geometry);
+                ringMaterial.uniforms.uRingTex.value = t;
+                ringMaterial.uniforms.uRingR.value.set(ringInner, ringOuter);
+                for (const m of materials) {
+                    m.uniforms.uRingTex.value = t;
+                    m.uniforms.uRingR.value.set(ringInner, ringOuter);
+                }
+                redraw();
+            }, () => undefined);
+        }
+        for (const m of materials) {
+            m.uniforms.uRingOn.value = 1;
+            m.uniforms.uRingTex.value = strip;
+            m.uniforms.uRingR.value.set(ringInner, ringOuter);
+        }
+    }
+    // the glow of a star: a plane through its centre that the caller turns to the camera
+    if (look.emissive === true) {
+        const glowGeometry = acquire(T, "glow", () => new T.PlaneGeometry(6, 6));
+        releases.push(glowGeometry.release);
+        const glowMaterial = new T.ShaderMaterial({ vertexShader: GLOW_VERTEX, fragmentShader: GLOW_FRAGMENT, transparent: true, depthWrite: false, blending: T.AdditiveBlending, uniforms: { uColour: { value: new T.Vector3(1, 0.7, 0.3) } } });
+        disposables.push(glowMaterial);
+        const glow = new T.Mesh(glowGeometry.value, glowMaterial);
+        glow.renderOrder = 4;
+        glow.frustumCulled = false;
+        group.add(glow);
+    }
+    // the painted map: the smallest width at once, a sharper one when the body is big on the screen, back to the small one when it is not
+    const widths = (look.painted?.widths ?? []).filter((w, i) => i === 0 || w <= maxWidth);
+    let small;
+    let sharp;
+    let sharpWidth = 0;
+    let loading = false;
+    let failed = false;
+    let tooBigSince = 0;
+    const tried = new Set();
+    const urlOf = (w) => `${look.painted.far !== undefined && w >= look.painted.far ? bases.far : bases.near}${look.painted.map}-${w}.webp`;
+    const prepare = (t) => {
+        t.anisotropy = 4;
+        t.wrapS = T.RepeatWrapping;
+        t.colorSpace = T.NoColorSpace;
+        return t;
+    };
+    const show = (t) => {
+        paintedMaterial.uniforms.uMap.value = t;
+        mesh.material = paintedMaterial;
+        redraw();
+    };
+    if (wantPainted && paintedMaterial !== undefined && widths[0] !== undefined) {
+        void loadImage(urlOf(widths[0])).then((t) => {
+            if (gone) {
+                t.dispose();
+                return;
+            }
+            small = prepare(t);
+            if (sharp === undefined)
+                show(small);
+        }, () => {
+            failed = true;
+        });
+    }
+    const keepSized = (radiusPx) => {
+        if (!wantPainted || failed || small === undefined || loading)
+            return;
+        const wanted = radiusPx * 2 * ratio * 1.6;
+        const next = widths.find((w) => w >= wanted) ?? widths[widths.length - 1];
+        if (next > sharpWidth && next > widths[0] && !tried.has(next)) {
+            tried.add(next);
+            loading = true;
+            void loadImage(urlOf(next)).then((t) => {
+                loading = false;
+                if (gone) {
+                    t.dispose();
+                    return;
+                }
+                const old = sharp;
+                sharp = prepare(t);
+                sharpWidth = next;
+                show(sharp);
+                old?.dispose();
+            }, () => {
+                loading = false;
+            });
+        }
+        else if (sharp !== undefined && wanted * 2 < sharpWidth) {
+            // much smaller on the screen than the picture it holds: after a few seconds, let the big picture go
+            const now = Date.now();
+            if (tooBigSince === 0)
+                tooBigSince = now;
+            else if (now - tooBigSince > 4000) {
+                show(small);
+                sharp.dispose();
+                sharp = undefined;
+                sharpWidth = 0;
+                tried.clear();
+                tooBigSince = 0;
+            }
+        }
+        else
+            tooBigSince = 0;
+    };
+    const axes = facts.axesKm;
+    const scaleX = axes ? axes[1] / facts.radiusKm : 1;
+    const scaleY = axes ? axes[2] / facts.radiusKm : 1 - facts.flattening;
+    const scaleZ = axes ? axes[0] / facts.radiusKm : 1;
+    const basis = (object, x, y, z, sx = 1, sy = 1, sz = 1) => {
+        object.matrix.makeBasis(new T.Vector3(x[0] * sx, x[1] * sx, x[2] * sx), new T.Vector3(y[0] * sy, y[1] * sy, y[2] * sy), new T.Vector3(z[0] * sz, z[1] * sz, z[2] * sz));
+    };
+    const light = new T.Vector3();
+    const poleVec = new T.Vector3();
+    return {
+        object: group,
+        ...(look.emissive === true ? { billboard: true } : {}),
+        update(info) {
+            light.set(info.toSun[0], info.toSun[1], info.toSun[2]);
+            const scale = group.scale.x || 1;
+            if (look.emissive !== true) {
+                const { pole, meridian } = orientation(id, info.ms);
+                const east = cross(pole, meridian);
+                basis(mesh, east, pole, meridian, scaleX, scaleY, scaleZ);
+                if (ringMesh !== undefined)
+                    basis(ringMesh, meridian, east, pole);
+                poleVec.set(pole[0], pole[1], pole[2]);
+            }
+            for (const m of materials) {
+                m.uniforms.uLight.value.copy(light);
+                m.uniforms.uScale.value = scale;
+                m.uniforms.uRingN.value.copy(poleVec);
+            }
+            if (ringMaterial !== undefined) {
+                ringMaterial.uniforms.uLight.value.copy(light);
+                ringMaterial.uniforms.uRingN.value.copy(poleVec);
+                ringMaterial.uniforms.uScale.value = scale;
+            }
+            keepSized(info.radiusPx);
+        },
+        dispose() {
+            gone = true;
+            small?.dispose();
+            sharp?.dispose();
+            ringTexture?.dispose();
+            for (const d of disposables)
+                d.dispose();
+            for (const r of releases)
+                r();
+            group.clear();
+        },
+    };
+}
+/**
+ * Make a painter that takes its pictures from the given folders (jsDelivr's copy of this version by default).
+ *
+ * @param options - Where the pictures are.
+ * @returns The painter.
+ *
+ * @example
+ * ```ts no-run
+ * import { createPainter } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const painter = createPainter();
+ * console.log(painter.moons("Mars", Date.UTC(2026, 10, 2)).map((m) => m.name));
+ * ```
+ */
+export function createPainter(options = {}) {
+    const near = slash(options.textureBase ?? TEXTURE_BASE);
+    const far = slash(options.farBase ?? (options.textureBase !== undefined ? options.textureBase : TEXTURE_FAR_BASE));
+    return {
+        looks: LOOKS,
+        make: (three, name, context = {}) => paint(three, idOf(name), context, { near, far }),
+        moons(planet, ms) {
+            const radius = BODIES[idOf(planet)]?.radiusKm;
+            if (radius === undefined)
+                return [];
+            return moonsOf(planet)
+                .map((moon) => ({ name: titled(moon), offset: moonOffset(moon, ms), radius: BODIES[moon].radiusKm / radius }))
+                .sort((a, b) => Math.hypot(...a.offset) - Math.hypot(...b.offset));
+        },
+    };
+}
+/**
+ * The painter with its default pictures: pass it to chikyu-earth's `setBodyPainter`.
+ *
+ * @example
+ * ```ts no-run
+ * import { painter } from "@johnmorrisdotca/wakusei-planets/painter";
+ * import { setBodyPainter } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * setBodyPainter(painter);
+ * ```
+ */
+export const painter = createPainter();

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.5.1";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.4.0";
+export const VERSION = "0.5.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/wakusei-planets",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Wakusei Planets 惑星 — The Sun, planets and moons for the web: each as a clean line drawing, a shaded realistic drawing or a painted surface map, with real sizes, axial tilt and rotation as data, and positions of the moons for any date and time. SVG for the lines, three.js (optional) for the rest.",
   "keywords": [
     "planets",
@@ -57,6 +57,11 @@
       "import": "./dist/scene/look.js",
       "default": "./dist/scene/look.js"
     },
+    "./painter": {
+      "types": "./dist/scene/painter.d.ts",
+      "import": "./dist/scene/painter.js",
+      "default": "./dist/scene/painter.js"
+    },
     "./all": {
       "types": "./dist/bodies/all.d.ts",
       "import": "./dist/bodies/all.js",
@@ -179,7 +184,8 @@
     "docs:check": "pnpm build && node scripts/docs-site.mjs check",
     "size": "node scripts/docs-site.mjs size",
     "test:usage": "pnpm site && node scripts/check-usage.ts",
-    "check:standard": "node scripts/check-standard.mjs"
+    "check:standard": "node scripts/check-standard.mjs",
+    "test:readme": "pnpm build && node scripts/check-usage.ts readme"
   },
   "devDependencies": {
     "@angular/common": "^22.2.4",
@@ -217,7 +223,7 @@
   },
   "packageManager": "pnpm@10.28.0",
   "dependencies": {
-    "@johnmorrisdotca/kazoku-ui": "^0.11.0"
+    "@johnmorrisdotca/kazoku-ui": "^0.12.0"
   },
   "peerDependencies": {
     "@johnmorrisdotca/chikyu-earth": ">=0.10.0",