@johnmorrisdotca/wakusei-planets 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.5.0
+
+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
+
+"Put it in your page" is a configurator.
+
+- **Set up a body, copy the code.** The demo's last section follows what is set up above it (body, look, sky and date, moons, turning) and a size (160, 240, 320 or 480), and writes working code for plain HTML from jsDelivr, an ES module, React, Vue, Angular, Svelte and an iframe of the embed page, on tabs that answer the arrow keys, beside a picture made from the same choices, with a Copy button and the credits that go with the picture. The choices are kept in the address (`?embed=react&size=240`).
+- **`embedCode(options, kind, settings)` and `embedCredit(options)`** make the same text for a page of your own (`EMBED_KINDS`: `html`, `module`, `react`, `vue`, `angular`, `svelte`, `iframe`). Pattern: senshu-jerseys' `embedCode` and its tabbed "Put it in your page". Every snippet is tested (`test/embed.test.ts`): the React component is built and rendered, the Vue and Svelte components compiled, the Angular template parsed, the module checked as TypeScript, the iframe's address read the way the embed page reads it, and every body's entry point exists in the package.
+- 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
 
 The Earth is a body like the others, and "To scale" is a comparison.

package/README.md

@@ -11,9 +11,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.3.1/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.0/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.3.1/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.0/docs/images/lineup-desk.png" width="640"></p>
 
 ## One minute
 
@@ -94,6 +94,7 @@ Give a body a `time` and it is drawn as the sky shows it then: its pole and rota
 | An ES module in Vite or webpack, only the bodies you need | [bundlers guide](docs/guides/bundlers.md) |
 | React, Vue, Svelte, Angular; Next.js, Nuxt, SvelteKit | [frameworks guide](docs/guides/frameworks.md) |
 | An `<iframe>` of the embed page, no script of your own | [iframe guide](docs/guides/embed-in-an-iframe.md) |
+| Set up a body in the demo and copy the code for HTML, React, Vue, Angular, Svelte or an iframe | [Put it in your page](docs/guides/put-it-in-your-page.md), or `embedCode()` |
 | TypeScript types, an SVG string on a server, Node | [TypeScript and Node guide](docs/guides/typescript-and-node.md) |
 | The looks, the entry points, one WebGL context | [looks and bodies](docs/guides/looks-and-bodies.md) |
 | Moons where they are on a date, time that runs fast | [moons and time](docs/guides/moons-and-time.md) |

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.3.1/dist/textures/";
+export declare const TEXTURE_BASE = "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/wakusei-planets@0.5.0/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.3.1/textures/";
+export declare const TEXTURE_FAR_BASE = "https://cdn.jsdelivr.net/gh/johnmorrisdotca/wakusei-planets@v0.5.0/textures/";
 /**
  * The `<wakusei-body>` custom element: a body of the solar system, drawn in a look.
  *

package/dist/embed.d.ts

@@ -0,0 +1,96 @@
+import { type BodyId, type Look } from "./facts.ts";
+/**
+ * The ways `embedCode` writes a body into a page.
+ *
+ * @example
+ * ```ts
+ * import { EMBED_KINDS } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(EMBED_KINDS.join(", "));
+ * ```
+ */
+export declare const EMBED_KINDS: readonly ["html", "module", "react", "vue", "angular", "svelte", "iframe"];
+/**
+ * One of the ways in `EMBED_KINDS`.
+ *
+ * @example
+ * ```ts
+ * import { EMBED_KINDS, type EmbedKind } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const kind: EmbedKind = EMBED_KINDS[2];
+ * console.log(kind);
+ * ```
+ */
+export type EmbedKind = (typeof EMBED_KINDS)[number];
+/**
+ * What the reader chose: the body, how it is drawn, and whether it is a portrait or the sky at a date.
+ *
+ * @example
+ * ```ts
+ * import { embedCode, type EmbedOptions } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const options: EmbedOptions = { body: "saturn", look: "painted", size: 320, turn: 12 };
+ * console.log(embedCode(options, "html"));
+ * ```
+ */
+export interface EmbedOptions {
+    body: BodyId;
+    look?: Look;
+    /** The date and time as an ISO string, or `now`: the body as the Earth sees it then. Left out, a portrait. */
+    time?: string;
+    /** A planet with its moons on their orbits (needs `time`). */
+    moons?: boolean;
+    /** Degrees a second it turns by itself; left out or 0, it is still. */
+    turn?: number;
+    /** Pixels across. */
+    size?: number;
+}
+/**
+ * Where the embed code points: the package's version on jsDelivr, and the published demo, where `embed.html` is.
+ *
+ * @example
+ * ```ts
+ * import { embedCode } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(embedCode({ body: "mars", look: "line" }, "iframe", { site: "https://example.com/wakusei/" }));
+ * ```
+ */
+export interface EmbedSettings {
+    /** The published demo's address, ending in a slash. */
+    site?: string;
+    /** The package's address on the CDN, with its version. */
+    cdn?: string;
+}
+/** The entry point that holds a body's shaded and painted look. */
+export declare function entryOf(id: BodyId): string;
+/**
+ * The text that puts a body in a page, for one way of making the page. Each way is built, parsed or run by the package's tests: the plain HTML one with a script tag from jsDelivr, an ES module, a React component,
+ * a Vue single-file component, an Angular standalone component, a Svelte component, and an iframe of the demo's `embed.html`.
+ *
+ * @param options - The body, its look, the date, the moons, the turn and the size.
+ * @param kind - The way the page is made; `html` by default.
+ * @param settings - The CDN and the demo's address, when they are not the package's own.
+ * @returns The text to paste into the page's source.
+ *
+ * @example
+ * ```ts
+ * import { embedCode } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(embedCode({ body: "jupiter", look: "realistic", time: "now", moons: true }, "react"));
+ * ```
+ */
+export declare function embedCode(options: EmbedOptions, kind?: EmbedKind, settings?: EmbedSettings): string;
+/**
+ * The credits that travel with a picture of a body: the line and shaded looks are drawn from numbers, the painted look uses public-domain pictures.
+ *
+ * @param options - The choices, so only what is used is named.
+ * @returns A short line of credit to put near the picture.
+ *
+ * @example
+ * ```ts
+ * import { embedCredit } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(embedCredit({ body: "mars", look: "painted" }));
+ * ```
+ */
+export declare function embedCredit(options: EmbedOptions): string;

package/dist/embed.js

@@ -0,0 +1,112 @@
+// The text to put a body in a page, for each way a page is made: a script tag from a CDN, an ES module, React, Vue, Angular, Svelte, or an iframe of `embed.html`. The demo's "Put it in your page"
+// section shows these as the reader changes a choice, and the tests build or parse every one. Pure: no DOM.
+import { BODIES } from "./facts.js";
+import { VERSION } from "./version.js";
+/**
+ * The ways `embedCode` writes a body into a page.
+ *
+ * @example
+ * ```ts
+ * import { EMBED_KINDS } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(EMBED_KINDS.join(", "));
+ * ```
+ */
+export const EMBED_KINDS = ["html", "module", "react", "vue", "angular", "svelte", "iframe"];
+const SITE = "https://johnmorrisdotca.github.io/wakusei-planets/";
+const CDN = `https://cdn.jsdelivr.net/npm/@johnmorrisdotca/wakusei-planets@${VERSION}`;
+const PACKAGE = "@johnmorrisdotca/wakusei-planets";
+/** The entry point that holds a body's shaded and painted look. */
+export function entryOf(id) {
+    const parent = BODIES[id].parent;
+    return parent === undefined ? id : `moons-${parent}`;
+}
+/** The attributes of the element for these choices, in the order they are written. */
+function attributesOf(o) {
+    const out = [["body", o.body], ["look", o.look ?? "realistic"]];
+    if (o.size !== undefined && o.size !== 320)
+        out.push(["size", String(o.size)]);
+    if (o.time !== undefined)
+        out.push(["time", o.time]);
+    if (o.moons === true && o.time !== undefined)
+        out.push(["moons", ""]);
+    if (o.turn !== undefined && o.turn > 0)
+        out.push(["turn", String(o.turn)]);
+    return out;
+}
+const quote = (v) => `"${v.replace(/&/g, "&").replace(/"/g, """)}"`;
+const tagAttrs = (o) => attributesOf(o).map(([k, v]) => (v === "" ? k : `${k}=${quote(v)}`)).join(" ");
+const needsShading = (o) => (o.look ?? "realistic") !== "line";
+/**
+ * The text that puts a body in a page, for one way of making the page. Each way is built, parsed or run by the package's tests: the plain HTML one with a script tag from jsDelivr, an ES module, a React component,
+ * a Vue single-file component, an Angular standalone component, a Svelte component, and an iframe of the demo's `embed.html`.
+ *
+ * @param options - The body, its look, the date, the moons, the turn and the size.
+ * @param kind - The way the page is made; `html` by default.
+ * @param settings - The CDN and the demo's address, when they are not the package's own.
+ * @returns The text to paste into the page's source.
+ *
+ * @example
+ * ```ts
+ * import { embedCode } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(embedCode({ body: "jupiter", look: "realistic", time: "now", moons: true }, "react"));
+ * ```
+ */
+export function embedCode(options, kind = "html", settings = {}) {
+    const cdn = settings.cdn ?? CDN;
+    const site = settings.site ?? SITE;
+    const shaded = needsShading(options);
+    const entry = entryOf(options.body);
+    const size = options.size ?? 320;
+    if (kind === "iframe") {
+        const query = new URLSearchParams({ body: options.body, look: options.look ?? "realistic" });
+        if (options.time !== undefined)
+            query.set("time", options.time);
+        if (options.moons === true && options.time !== undefined)
+            query.set("moons", "1");
+        if (options.turn !== undefined && options.turn > 0)
+            query.set("turn", String(options.turn));
+        return `<iframe\n  src=${quote(`${site}embed.html?${query.toString()}`)}\n  title=${quote(BODIES[options.body].name.en)}\n  width="${size}"\n  height="${size}"\n  loading="lazy"\n  style="border: 0"\n></iframe>`;
+    }
+    if (kind === "html") {
+        const scripts = [`<script type="module" src="${cdn}/element/+esm"></script>`, ...(shaded ? [`<script type="module" src="${cdn}/${entry}/+esm"></script>`] : [])];
+        return `${scripts.join("\n")}\n\n<wakusei-body ${tagAttrs(options)}></wakusei-body>`;
+    }
+    const imports = [`import "${PACKAGE}/element";`, ...(shaded ? [`import "${PACKAGE}/${entry}";`] : [])];
+    if (kind === "module") {
+        const sets = attributesOf(options).map(([k, v]) => `planet.setAttribute(${JSON.stringify(k)}, ${JSON.stringify(v)});`);
+        return `${imports.join("\n")}\n\nconst planet = document.createElement("wakusei-body");\n${sets.join("\n")}\ndocument.querySelector("#planet").append(planet);`;
+    }
+    const dynamic = [`void import("${PACKAGE}/element");`, ...(shaded ? [`void import("${PACKAGE}/${entry}");`] : [])];
+    if (kind === "react") {
+        const props = attributesOf(options).map(([k, v]) => (v === "" ? k : `${k}=${quote(v)}`)).join(" ");
+        return `import { useEffect } from "react";\n\nexport function Planet() {\n  useEffect(() => {\n    // The element needs a browser, so it is imported in an effect, never at the top of the file.\n${dynamic.map((l) => `    ${l}`).join("\n")}\n  }, []);\n  return <wakusei-body ${props} />;\n}`;
+    }
+    if (kind === "vue") {
+        return `<script setup lang="ts">\nimport { onMounted } from "vue";\n\nonMounted(() => {\n${dynamic.map((l) => `  ${l}`).join("\n")}\n});\n</script>\n\n<template>\n  <wakusei-body ${tagAttrs(options)}></wakusei-body>\n</template>`;
+    }
+    if (kind === "angular") {
+        return `import { Component, CUSTOM_ELEMENTS_SCHEMA, OnInit } from "@angular/core";\n\n@Component({\n  selector: "app-planet",\n  standalone: true,\n  schemas: [CUSTOM_ELEMENTS_SCHEMA],\n  template: \`<wakusei-body ${tagAttrs(options)}></wakusei-body>\`,\n})\nexport class PlanetComponent implements OnInit {\n  ngOnInit(): void {\n    // The element needs a browser: ngOnInit also runs when a server renders.\n    if (typeof window !== "undefined") {\n${dynamic.map((l) => `      ${l}`).join("\n")}\n    }\n  }\n}`;
+    }
+    return `<script lang="ts">\n  import { onMount } from "svelte";\n\n  onMount(() => {\n${dynamic.map((l) => `    ${l}`).join("\n")}\n  });\n</script>\n\n<wakusei-body ${tagAttrs(options)}></wakusei-body>`;
+}
+/**
+ * The credits that travel with a picture of a body: the line and shaded looks are drawn from numbers, the painted look uses public-domain pictures.
+ *
+ * @param options - The choices, so only what is used is named.
+ * @returns A short line of credit to put near the picture.
+ *
+ * @example
+ * ```ts
+ * import { embedCredit } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(embedCredit({ body: "mars", look: "painted" }));
+ * ```
+ */
+export function embedCredit(options) {
+    const base = "Wakusei Planets by John Morris (MIT). Sizes, tilt and rotation: IAU and NASA fact sheets.";
+    const painted = (options.look ?? "realistic") === "painted" ? " Surface pictures: NASA, USGS and JPL imagery in the public domain (details in the package's NOTICE.md)." : "";
+    const earth = options.body === "earth" ? " Earth: NASA Earth Observatory, Blue Marble." : "";
+    return `${base}${painted}${earth}`;
+}

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export { apparent, moonGeocentric, heliocentric, orbitPath, system, type Apparen
 export { drawnTilt, portrait, type PortraitOptions } from "./pose.ts";
 export { lineSvg, mix, type LineOptions } from "./line.ts";
 export { ringStrip, type RingStrip } from "./scene/rings.ts";
+export { embedCode, embedCredit, EMBED_KINDS, type EmbedKind, type EmbedOptions, type EmbedSettings } from "./embed.ts";

package/dist/index.js

@@ -3,3 +3,4 @@ export { apparent, moonGeocentric, heliocentric, orbitPath, system } from "./eph
 export { drawnTilt, portrait } from "./pose.js";
 export { lineSvg, mix } from "./line.js";
 export { ringStrip } from "./scene/rings.js";
+export { embedCode, embedCredit, EMBED_KINDS } from "./embed.js";

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.3.1";
+export declare const VERSION = "0.5.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.3.1";
+export const VERSION = "0.5.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/wakusei-planets",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "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",
@@ -217,11 +222,11 @@
   },
   "packageManager": "pnpm@10.28.0",
   "dependencies": {
-    "@johnmorrisdotca/kazoku-ui": "^0.9.1"
+    "@johnmorrisdotca/kazoku-ui": "^0.11.0"
   },
   "peerDependencies": {
-    "three": ">=0.160.0",
-    "@johnmorrisdotca/chikyu-earth": ">=0.10.0"
+    "@johnmorrisdotca/chikyu-earth": ">=0.10.0",
+    "three": ">=0.160.0"
   },
   "peerDependenciesMeta": {
     "three": {