@johnmorrisdotca/chikyu-earth 0.4.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## 0.7.0
+
+The space view can look at any body, bodies can be chosen, and how the Sun and the planets are drawn is a seam another package can fill.
+
+- **Look at a body**: `element.body = "Mars"` (any of Earth, Moon, Sun and the seven planets) points the camera at it; at zoom 1 it fills the view, and the shared controls turn the camera round it and zoom in and out from it. The demo's "Look at" row does it.
+- **Bodies can be chosen**: each name beside a body is a real button (Tab and Enter), and a press on a body (not a drag) fires `chikyu-body-click`; `chikyu-body-focus` for the keyboard. The event carries `name`, `radiusKm` and `distanceKm` (`element.bodyInfo(name)` gives the same for a caption); the demo prints "Jupiter: radius 69,911 km, 666,000,000 km from the Earth".
+- **A seam for drawing the bodies** (`BodyPainter`, `setBodyPainter`, `plainPainter` from `@johnmorrisdotca/chikyu-earth/space`): the space view keeps each body's place, size, light direction, name and orbit, and asks a painter only for what to draw there (an object of radius 1; `light(toSun)` each draw; the Sun's turns to face the camera). The default is what 0.6.0 drew: spheres in the planets' colours and a glow for the Sun. John chose a separate package (wakusei-planets) for the bodies' own looks, so chikyu ships no planet pictures and no rings; the Earth and the Moon keep theirs.
+- Tests: e2e (a body looked at, its name chosen by keyboard, a press on it chooses it, a drag that turns the view does not) and a unit test of the default painter.
+
+## 0.6.0 (never published on its own: it ships in 0.7.0)
+
+The Sun, the Moon and the planets: `<chikyu-space>`, an optional entry point, under the same performance budget as the Earth from space.
+
+- **`<chikyu-space>`** (`@johnmorrisdotca/chikyu-earth/space/element`) places the Earth, the Moon, the Sun and the planets (Mercury to Neptune) in their positions for a date and time, with the Moon's
+  phase and the Earth's sunlit side coming out of the light (the Moon is half lit on 2 November 2026, last quarter). Positions are computed in the browser by **astronomy-engine** (MIT, a new optional peer dependency;
+  nothing is fetched). Time controls: `time` (an ISO date or `now`), `speed` (1 real time, 0 held, 3600 an hour a second, 86400 a day a second, negative backwards). Zoom from the Earth out to the solar system and back with
+  the shared controls (`zoom-min`, `zoom-max`), and `zoomFor("moon" | "sun" | "inner" | "solar-system" | "earth")` for the jumps. Names beside the bodies and the planets' orbits can be switched off.
+- **Two scales, and it says which**: `compressed` (default; every direction real, the Moon 10 Earth radii away instead of 60, the Sun 44, the planets round the Sun at 44 radii times their distance in astronomical
+  units to the power 0.45, sizes enlarged) and `true` (real distances and sizes, where the planets are specks). The demo says "Compressed scale: ..." whenever it is on. [docs/space.md](docs/space.md).
+- **Budget, each line tested** (`e2e/space.gl.ts`): paused, 0 draw calls and 0 frame requests in 4 s; real time, 0 draw calls in 6 s (a draw a minute); a day a second: 1.00 days a second of game time, 29.4 draws a second,
+  and 2.0 ephemeris lookups a second (the ephemeris is looked up once a game-second span and interpolated, within 0.1 degree of the Moon's true place); nothing drawn out of sight at a day a second; the textures follow the zoom and
+  are freed after it; removal frees what it held; a lost context is recovered. The space soak (10 minutes, 945 steps from the Earth to the solar system and back, at every speed, both scales, orbits and names toggled): JS heap 8.05 to 8.45 MB after garbage collection (flat from the fifth minute), GPU objects 46 to 46, textures, buffers and programs equal to the start, the average 76 GL draw calls a second (about 25 a frame, so 3 frames a second), one WebGL context, no error.
+- **Pictures**: the Moon (NASA SVS 4720, LROC colour mosaic, 1024 and 2048 wide, 306 KB) joins the Earth's; the package's textures are 1.85 MB. The planets are plain colours.
+- **Shared parts**: the texture loader (`src/realistic/textures.ts`) and the page's one renderer (`src/realistic/shared.ts`) now serve both the Earth from space and the space view, so a page keeps one WebGL context between them. The
+  Earth's shaders look at the camera instead of assuming one, so they work from any angle.
+- **Research, no code** ([docs/satellite-sources.md](docs/satellite-sources.md), MODULES-85): CelesTrak (grey), Space-Track (red for a package), the r/SpaceX API (archived, offline), Launch Library 2 (grey), Wikipedia and Wikidata
+  (green) for launches; the recommendation is a satellite view that takes elements the page supplies. John chooses before MODULES-86 and MODULES-87 start.
+
+### The family's published parts: demo, embed, docs and usage
+
+Chikyu Earth now has what every package of the family has, and it was missing from 0.3.0 to 0.5.0.
+
+- **Demo on GitHub Pages**, set as the repository's and the package's homepage: <https://johnmorrisdotca.github.io/chikyu-earth/>, with the family header (the kazoku-ui language picker, English and Japanese, and theme switch, the table cloths and the Help switch), light and dark, and the family footer. `pnpm site` builds it, and the Pages workflow publishes it on every push to `main`.
+- **An embed page**, `embed.html`, for an `<iframe>` with no script of your own: `?look=line|thick|realistic`, `center`, `graticule`, `turn=0|1|auto`, `time`, `clouds`, `lights`. Still by default, no controls, no location prompt; it draws only when something changes and nothing while hidden. Tested in Chromium and WebKit, and on the realistic look: one WebGL context, canvas inside its budget, nothing drawn at rest.
+- **A documentation site** at `/docs/`: a page for every export (from its TSDoc, with an example that is run when the site is built), ten guides in English and in Japanese, one language to a page, search, `llms.txt` and the family's header. Every export of every entry point has a summary, `@param`, `@returns` and an `@example` that imports the package by its name; `pnpm check` fails when one does not.
+- **Every way to use it, written down and tested** (`pnpm test:usage`): a script tag from jsDelivr and from unpkg, the realistic Earth from a CDN, the shared controls, Vite, webpack, React (and a server render of it), Vue, Svelte, Angular, an iframe, TypeScript types and Node. Each example is built or run against the package as npm packs it, opened in a browser and made to show a globe; the guides and the README must hold the same text word for word.
+- **`look` attribute**: `<chikyu-earth look="thick">` is the new name of `style`, which frameworks read as CSS (React refuses a string `style`). `style` still works.
+- **Types for the tags**: `document.querySelector("chikyu-earth")` is a `ChikyuEarth` (and `"chikyu-earth-realistic"`, `"chikyu-space"`) once the element's entry is imported.
+- **A freeze test in the release** (`e2e/freeze.demo.ts`, `pnpm test:freeze`): at rest nothing is drawn and no frame asked for, turning draws at most once for each frame of the page and asks for one frame at a time, out of sight or in a hidden tab nothing is drawn, the canvas stays inside 6 million pixels and 4096 a side on a 5K screen at a pixel ratio of 2 in the Earth from space and the space view, and six rounds of changing the look leave the GPU objects flat in one WebGL context and let the context go at the end. Every Chromium project draws WebGL in software, never on the machine's graphics card. The release workflow runs it (`freeze-command`, kazoku-ui 0.9.1).
+- **The family's must-have list**, checked: `scripts/check-standard.mjs` (kazoku-ui's, unchanged) fails `pnpm check` when a package lacks its demo, embed page, docs site with Japanese twins, family files or tested usage.
+- **Family files**: `family-template.mjs` and `family-readme.mjs` of 2026-11-02 with Chikyu Earth added to the family's list (33 packages), `family.css`, and the README's "The family" block. Added to the list here only; the other packages take the new files when they are next touched.
+
+## 0.5.0
+
+The Earth from space, and markers for any place on either globe, both under a hard performance budget.
+
+### Markers
+
+- **`attachMarkers(element)`** (`@johnmorrisdotca/chikyu-earth/markers`) puts your places on `<chikyu-earth>` or `<chikyu-earth-realistic>`: add, update and remove markers at `[lon, lat]` with a label, colour, icon and size; groups (cities, stadiums) shown or hidden together; markers that turn, zoom and pan with the globe and fade on the far side; crowded places gathered into clusters; labels that make room for each other; `chikyu-marker-hover`, `-click` and `-focus` events carrying your own `data`; a button for each shown label (Tab and Enter work) and a hidden list of every place for a screen reader. Chikyu ships no places; the demo shows 22 cities and 10 stadiums (Wikidata coordinates, CC0). [docs/markers.md](docs/markers.md).
+- **Budget**, each line tested: all dots in one 2D canvas pass, and a pool of 24 label buttons, never an element per place; 5,000 markers cost 0.36 ms a view change on the flat globe; a 5,000-marker drag on the Earth from space made 117 draws in 4 s (29 a second), the markers drawn with them one for one and not at all at rest or out of sight; the overlay canvas holds the same 4096-a-side, 6 MP limit.
+- The flat element's picture now sits in a holder beside the markers' overlay (a redraw replaces only the picture), and `lookAt` moves to `view.ts`.
+
+### The Earth from space
+
+An optional realistic look, drawn with three.js through kazoku-ui's shared renderer.
+
+- **`<chikyu-earth-realistic>`** (`@johnmorrisdotca/chikyu-earth/realistic/element`): day side from NASA's Blue Marble, the cities' lights on the night side, a cloud
+  layer that drifts with the date, a sun glint on the sea, an atmosphere at the rim, and the day and night line placed by the real Sun for a date and time (now by
+  default). The same shared controls (turn, tilt, zoom, pan) and the same `setView(view, final)` as the flat globe. `time`, `clouds`, `lights`, `center`,
+  `texture-base`, `max-texture` and `live-seconds` attributes; `chikyu-ready`, `chikyu-unavailable` and `chikyu-tier` events. [docs/realistic.md](docs/realistic.md).
+- **The flat look stays**: `<chikyu-earth>` is unchanged (and gains a `centre` getter); the demo's Line, Thick and Realistic buttons choose between them, keep the
+  camera, and keep the choice, the graticule, the clouds, the lights and the time in the address (kazoku-ui's address state). Without WebGL the demo says so and
+  shows the line globe.
+- **Optional, so the base install stays small**: `three` and `@johnmorrisdotca/kazoku-ui` are optional peer dependencies; the base entry and `<chikyu-earth>` need neither.
+  The realistic element, its Sun, its scene and its shaders, with kazoku-ui's renderer, are 22.6 KB minified (9.2 KB gzipped); three.js is the page's, and the demo's
+  subset of it (`demo/three-subset.ts`) is 188 KB gzipped. Sun position: `subsolarPoint(ms)` in `@johnmorrisdotca/chikyu-earth/realistic`, tested against the almanac
+  (declination within 0.05 degree, the equation of time in the longitude).
+- **Pictures** (1.55 MB in `dist/textures/`, WebP, all NASA public domain, credited in NOTICE.md): day at 1024, 2048 and 4096; night, clouds and a water mask at 1024 and 2048.
+  The 1024 ones load first; a larger one loads when the zoom needs it (about 3 texels per pixel of the disc's radius), replaces the smaller, and is freed 4 s after the
+  zoom drops. No texture is wider than 4096 (2048 on a device with 2 GB or less); `pnpm textures` rebuilds them.
+- **Performance, each proved by `e2e/realistic.gl.ts` (Chromium, software WebGL)**: 0 draw calls and 0 animation frames in 4 s at rest; a drag at 125 moves a second
+  draws 29.3 times a second, and 2,700 `setView` calls in 2 s make 59 draws; an Auto-turn at the Earth's rate draws 0 times in 6 s; one WebGL context; the canvas on a
+  5K screen at ratio 2 is 3264 x 1835 = 5.99 MP; the textures alive grow one a layer with the zoom and return to the start after it; 0 draws and 0 frames while out of
+  sight or in a hidden tab; after removal 0 buffers, 0 programs and none of our textures remain, and the element can come back; a lost context draws nothing and then
+  recovers, not black; no WebGL gives `chikyu-unavailable`. The soak (10 minutes, 976 moves, 2,000 markers on): JS heap 7.29 to 7.80 MB after garbage collection, GPU objects 20 to 20, textures, buffers and programs the same as at the start, the draw rate 5.4 a second on average, one WebGL context, no error.
+- `pnpm test:soak` (`SOAK_MINUTES`, 10 by default; CI runs 1) turns, zooms, re-times and toggles for that long and compares the heap, the GPU objects and the draw rate with the start.
+- `pnpm screenshots` also makes the realistic pictures; `scripts/make-textures.py` makes the textures from NASA's sources.
+
 ## 0.4.0
 
 The outlines now come from chizu, the controls from kazoku-ui 0.9, and the release from the family's shared workflow.

package/NOTICE.md

@@ -16,6 +16,44 @@ Each outline's English name, Japanese name and country code come from **chizu**'
 **kuni**'s (https://github.com/johnmorrisdotca/kuni, also by John Morris) and Unicode CLDR's
 (https://www.unicode.org/license.txt) and Wikidata's (CC0). chizu's own NOTICE.md has the terms.
 
+## The realistic Earth's pictures
+
+The pictures in `textures/` (and `dist/textures/`) are made by `scripts/make-textures.py` from four NASA Earth Observatory images, resized and
+re-encoded as WebP. NASA says its content "generally are not subject to copyright in the United States" and asks that "NASA should be acknowledged as the
+source of the material" (https://www.nasa.gov/nasa-brand-center/images-and-media/, read 2026-11-02). These are NASA's own images, not third-party
+material, so no other licence applies. This package is not endorsed by NASA and uses none of NASA's insignia or logotype.
+
+| Picture | Source | Credit |
+|---|---|---|
+| `day-*.webp` | Blue Marble: Next Generation with topography and bathymetry, September 2004, 5400 x 2700 (https://eoimages.gsfc.nasa.gov/images/imagerecords/73000/73801/world.topo.bathy.200409.3x5400x2700.jpg, Visible Earth 73801) | NASA Earth Observatory (Reto Stöckli, Blue Marble Next Generation) |
+| `water-*.webp` | made by `scripts/make-textures.py` from the day picture: where it is blue and dark | as above |
+| `night-*.webp` | Earth at Night, Black Marble 2016 color map at 0.1 degree, 3600 x 1800 (https://eoimages.gsfc.nasa.gov/images/imagerecords/144000/144898/BlackMarble_2016_01deg.jpg, Visible Earth 144898) | NASA Earth Observatory, Suomi NPP VIIRS data (Miguel Roman, NASA's Goddard Space Flight Center) |
+| `clouds-*.webp` | Blue Marble clouds, 2048 x 1024 (https://eoimages.gsfc.nasa.gov/images/imagerecords/57000/57747/cloud_combined_2048.jpg, Visible Earth 57747) | NASA Earth Observatory (Reto Stöckli) |
+
+The credit names are NASA's usual lines for these series; the Visible Earth pages (now at science.nasa.gov/earth/earth-observatory) did not show a credit line in the
+text read on 2026-11-02, so check them if you need the exact wording for print.
+
+## The Moon's picture
+
+`moon-*.webp` is made by `scripts/make-textures.py` from NASA's Scientific Visualization Studio item 4720, "Moon: LROC colour mosaic" (https://svs.gsfc.nasa.gov/4720/,
+`lroc_color_2k.jpg`), a natural-colour mosaic of the Lunar Reconnaissance Orbiter's wide-angle camera (Arizona State University and NASA/GSFC). NASA's page asks: "Please give credit for this
+item to: NASA's Scientific Visualization Studio" (Visualizer Ernie Wright, USRA; Scientist Noah Petro, NASA/GSFC). Same NASA terms as above.
+
+## The planets' places
+
+`<chikyu-space>` computes positions with **astronomy-engine** (https://github.com/cosinekitty/astronomy, MIT, copyright Don Cross), the page's own optional peer dependency: this package does not
+bundle or ship it. The planets are drawn as plain colours, from no picture.
+
+## Sun position
+
+`src/realistic/sun.ts` uses the low-precision solar position formulas of NOAA's solar calculator (https://gml.noaa.gov/grad/solcalc/, after Jean Meeus,
+*Astronomical Algorithms*). Formulas are not copyrightable; the code is this package's own and MIT.
+
+## three.js
+
+The realistic look draws with three.js (https://threejs.org, MIT, copyright the three.js authors), the page's own optional peer dependency; this package
+does not bundle or ship it.
+
 ## Projection
 
 The orthographic projection, the spherical clipping and the SVG path generation are **d3-geo**
@@ -25,7 +63,7 @@ d3-geo is the package's projection dependency.
 ## Shared view controls
 
 The turn, tilt, zoom, pan and touch controls are **kazoku-ui** (https://github.com/johnmorrisdotca/kazoku-ui),
-also by John Morris, under the MIT licence. The package has no third-party dependencies of its own.
+also by John Morris, under the MIT licence. Its shared 3D renderer draws the realistic Earth.
 
 ## Marks
 

package/README.md

@@ -9,41 +9,143 @@ Country outlines in the same thin-line style as Hako Devices and Uchusen Rockets
   <img alt="TypeScript" src="https://img.shields.io/badge/types-TypeScript-3178c6">
 </p>
 
+<p align="center"><a href="https://johnmorrisdotca.github.io/chikyu-earth/"><strong>Open the demo →</strong></a> · <a href="https://johnmorrisdotca.github.io/chikyu-earth/embed.html">Embed page</a> · <a href="https://johnmorrisdotca.github.io/chikyu-earth/docs/">Docs</a></p>
+
 <p align="center"><img alt="The line-drawn globe, Europe and Africa in view, with the shared control bar" src="docs/images/line-desk.png" width="640"></p>
 
-## One minute
+## Install and use
 
 ```sh
 npm install @johnmorrisdotca/chikyu-earth
 ```
 
+Or use no install at all: every example below was run in a browser, built or type-checked by `pnpm test:usage` against the package as npm packs it, and the guides hold the same text.
+
+### In a plain HTML page
+
+One script tag from [jsDelivr](https://www.jsdelivr.com/package/npm/@johnmorrisdotca/chikyu-earth) and the tag. (From unpkg, with the realistic Earth, and pinning a version: [the CDN guide](docs/guides/html-and-cdn.md).)
+
 ```html
-<script type="module">
-  import "@johnmorrisdotca/kazoku-ui/view-controls/define";
-  import "@johnmorrisdotca/chikyu-earth/element";
-</script>
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Chikyu Earth from jsDelivr</title>
+    <script type="module" src="https://cdn.jsdelivr.net/npm/@johnmorrisdotca/chikyu-earth/element/+esm"></script>
+  </head>
+  <body>
+    <chikyu-earth center="139.7,35.7" look="thick" graticule size="320"></chikyu-earth>
+  </body>
+</html>
+```
 
-<div id="globe" tabindex="0">
-  <chikyu-earth size="420"></chikyu-earth>
-</div>
-<kazoku-view-controls id="controls" for="globe" address controls="advanced" tilt-max="90" speed="0.004178" autoplay></kazoku-view-controls>
+The globe appears centred where you say; with no `center` it centres on the reader (the browser asks for their location; until they answer, and if they decline, it starts on the Greenwich meridian). `look` is `line` or `thick`.
+
+### With the shared controls
+
+The [kazoku-ui](https://github.com/johnmorrisdotca/kazoku-ui) view controls turn, tip, zoom and pan it, and keep the view in the address. One listener passes their camera on:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Chikyu Earth with the shared controls</title>
+    <script type="module">
+      import "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/kazoku-ui/view-controls/define/+esm";
+      import "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/chikyu-earth/element/+esm";
+
+      const earth = document.querySelector("chikyu-earth");
+      document.querySelector("kazoku-view-controls").addEventListener("kazoku-viewchange", (event) => {
+        earth.setView(event.detail, event.detail.final);
+      });
+    </script>
+  </head>
+  <body>
+    <div id="globe" tabindex="0">
+      <chikyu-earth size="420" look="thick" center="139.7,35.7"></chikyu-earth>
+    </div>
+    <kazoku-view-controls for="globe" address controls="advanced" tilt-max="90" speed="0.004178"></kazoku-view-controls>
+  </body>
+</html>
+```
+
+Auto-turn (add `autoplay`) moves at the Earth's own rate: `0.004178` degrees a second, one sidereal day — 23 h 56 min 4.0905 s — per revolution.
 
+### In React
+
+The element needs a browser, so it is imported inside the effect, never at the top of the file; that keeps a server render working. (Vue, Svelte and Angular do the same: [the frameworks guide](docs/guides/frameworks.md).)
+
+```tsx
+import { useEffect, useRef } from "react";
+
+export function ChikyuEarth({ center = "139.7,35.7", look = "thick" }: { center?: string; look?: "line" | "thick" }) {
+  const host = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    // The element needs a browser, so it is imported here, never at the top of the file: a server render never reaches an effect.
+    void import("@johnmorrisdotca/chikyu-earth/element");
+  }, []);
+  return (
+    <div ref={host}>
+      <chikyu-earth center={center} look={look} graticule />
+    </div>
+  );
+}
+```
+
+### Every other way
+
+| How | Where |
+|---|---|
+| A script tag from jsDelivr or unpkg, the realistic Earth from a CDN | [CDN guide](docs/guides/html-and-cdn.md) |
+| An ES module in Vite or webpack | [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) |
+| TypeScript types, an SVG string on a server, Node | [TypeScript and Node guide](docs/guides/typescript-and-node.md) |
+| The web component (`<chikyu-earth>`, `<chikyu-earth-realistic>`) | every one of the above; its attributes are in [The element](#the-element) |
+| Something does not appear | [troubleshooting](docs/guides/troubleshooting.md) |
+
+The guides are also in Japanese (日本語), one language to a page: [docs/guides/ja/](docs/guides/ja/getting-started.md).
+
+## The Earth from space
+
+An optional second look, for a page with room for a real picture: day and night by the real Sun, cities' lights, a sun glint on the sea, a cloud layer and the
+atmosphere at the rim, drawn with three.js through kazoku-ui's shared renderer. It is its own entry point, so the line globe above costs nothing extra.
+
+<p align="center"><img alt="The Earth from space: Asia and the Pacific by day, with clouds and the sun glint" src="docs/images/realistic-desk.png" width="560"></p>
+
+```html
 <script type="module">
-  const earth = document.querySelector("chikyu-earth");
-  document.getElementById("controls").addEventListener("kazoku-viewchange", (event) => {
-    earth.setView(event.detail, event.detail.final);
-  });
+  import "@johnmorrisdotca/chikyu-earth/realistic/element";
 </script>
+<chikyu-earth-realistic center="139.7,35.7" time="2026-06-21T03:00Z" texture-base="/textures/"></chikyu-earth-realistic>
 ```
 
-The globe appears, centred on the reader (the browser asks for their location; until they answer, and if they
-decline, it starts on the Greenwich meridian). The shared control bar turns, tips, zooms and pans it. Auto-turn
-moves at the Earth's own rate: `0.004178` degrees a second, one sidereal day — 23 h 56 min 4.0905 s — per revolution.
+Needs `three` and `@johnmorrisdotca/kazoku-ui` (both optional peers) and the pictures (1.6 MB, from NASA, in `dist/textures/`). It draws nothing while nothing changes,
+at most 30 times a second while it does, in one WebGL context, with textures that grow as you zoom and are freed after. All of it, the budget and the tests:
+[docs/realistic.md](docs/realistic.md).
 
-Centre it yourself instead:
+## The Sun, the Moon and the planets
 
-```html
-<chikyu-earth center="139.7,35.7" style="thick" graticule></chikyu-earth>
+`<chikyu-space>` (`@johnmorrisdotca/chikyu-earth/space/element`) places the Earth, the Moon, the Sun and the planets where they are at a date and time, with the Moon's phase and the Earth's day side
+from the light, a compressed scale you can read (and a true one that shows how empty it is), time that runs forwards or backwards, and a zoom from the Earth to the solar system. Positions are
+computed in the browser by astronomy-engine (MIT), nothing is fetched. [docs/space.md](docs/space.md).
+
+<p align="center"><img alt="The solar system on 2 November 2026 in the compressed scale: orbits round the Sun, the planets named" src="docs/images/space-solar.png" width="420"></p>
+
+## Markers
+
+Mark any place at `[lon, lat]` with a label, colour or icon, in groups you can show or hide, on either look. Chikyu ships no places; yours move with the globe, fade on the far side, make room
+for their labels, gather into clusters when crowded, and fire hover, click and keyboard events with your own data. One canvas pass for thousands, a pool of 24 buttons for the labels. [docs/markers.md](docs/markers.md).
+
+```ts no-run
+import "@johnmorrisdotca/chikyu-earth/element";
+import { attachMarkers } from "@johnmorrisdotca/chikyu-earth/markers";
+
+const markers = attachMarkers(document.querySelector("chikyu-earth")!);
+markers.add({ id: "tokyo", lon: 139.69, lat: 35.69, label: "Tokyo", group: "Cities" });
 ```
 
 ## Controls
@@ -57,12 +159,14 @@ rotate or drag controls.
 <kazoku-view-controls id="controls" for="globe" address controls="advanced" tilt-max="90" speed="0.004178" autoplay></kazoku-view-controls>
 ```
 
-```ts
+```ts no-run
+import "@johnmorrisdotca/chikyu-earth/element";
 import "@johnmorrisdotca/kazoku-ui/view-controls/define";
+import type { ViewChangeDetail } from "@johnmorrisdotca/kazoku-ui/view-controls/element";
 
-const earth = document.querySelector("chikyu-earth");
-document.getElementById("controls").addEventListener("kazoku-viewchange", (event) => {
-  const { yaw, tilt, zoom, panX, panY, final } = event.detail;
+const earth = document.querySelector("chikyu-earth")!;
+document.getElementById("controls")!.addEventListener("kazoku-viewchange", (event) => {
+  const { yaw, tilt, zoom, panX, panY, final } = (event as CustomEvent<ViewChangeDetail>).detail;
   earth.setView({ yaw, tilt, zoom, panX, panY }, final);
 });
 ```
@@ -92,7 +196,7 @@ The rotation is the pair d3-geo's `rotate` takes: `[-longitude, -latitude]` cent
 | --- | --- | --- |
 | `size` | Width and height of the square SVG, in pixels. | `320` |
 | `center` | `"longitude,latitude"` to centre on. Wins over geolocation. | the reader's location, else `0,0` |
-| `style` | `line` or `thick`. | `line` |
+| `look` | `line` or `thick`. (`style` is the older name for it: a framework reads `style` as CSS, so use `look` there.) | `line` |
 | `graticule` | Draw a light graticule under the countries. | off |
 
 `setView(view, final = true)` applies a shared controller's `{ yaw, tilt, zoom, panX, panY }`. Every call updates
@@ -117,6 +221,77 @@ countryList().find((c) => c.alpha2 === "JP"); // { name: "Japan", ja: "日本",
 
 To take newer outlines, update `@johnmorrisdotca/chizu`; there is no data file in this repository.
 
+## The name
+
+Chikyu (地球, ちきゅう) is Japanese for the Earth.
+
+## The family
+
+<!-- family:start (made by scripts/family-readme.mjs from scripts/family-template.mjs; change those, not this) -->
+Chikyu Earth is one of thirty-three packages, each made for the same site, each at
+[github.com/johnmorrisdotca](https://github.com/johnmorrisdotca) or [github.com/spxis](https://github.com/spxis). The code of every one is MIT.
+
+**Games — board**
+
+- [Domino](https://github.com/johnmorrisdotca/domino) (ドミノ): dominoes and Mexican Train. [Demo](https://johnmorrisdotca.github.io/domino/).
+- [Gunjin](https://github.com/johnmorrisdotca/gunjin) (軍人): five hidden-rank strategy games with pass-the-device play. [Demo](https://johnmorrisdotca.github.io/gunjin/).
+- [Narabe](https://github.com/johnmorrisdotca/narabe) (並べ): one rules engine for abstract board games, from gomoku and Reversi to Go and checkers. [Demo](https://johnmorrisdotca.github.io/narabe/).
+- [Sugoroku](https://github.com/johnmorrisdotca/sugoroku) (双六): backgammon and its variants, with the doubling cube and match play. [Demo](https://johnmorrisdotca.github.io/sugoroku/).
+- [Tenka](https://github.com/johnmorrisdotca/tenka) (天下): world conquest for two to six, on a map of the real world. [Demo](https://johnmorrisdotca.github.io/tenka/).
+
+**Games — cards & tiles**
+
+- [Hitotsu](https://github.com/johnmorrisdotca/hitotsu) (一つ): a colour-card shedding game for two to eight, with the house rules people play. [Demo](https://johnmorrisdotca.github.io/hitotsu/).
+- [Jarajara](https://github.com/johnmorrisdotca/jarajara) (ジャラジャラ): mahjong tiles drawn as SVG, stacked layouts, and the matching solitaire Awase. [Demo](https://johnmorrisdotca.github.io/jarajara/).
+- [Kumimoji](https://github.com/johnmorrisdotca/kumimoji) (組み文字): a crossword tile race, in English and Japanese kana. [Demo](https://johnmorrisdotca.github.io/kumimoji/).
+- [Toranpu](https://github.com/johnmorrisdotca/toranpu) (トランプ): a deck of playing cards, card games with computer players, and solitaires. [Demo](https://johnmorrisdotca.github.io/toranpu/).
+
+**Games — puzzles**
+
+- [Houseki](https://github.com/johnmorrisdotca/houseki) (宝石): gem and stone matching puzzles: falling triplets, stone collapse, colour chains and gem swap. [Demo](https://johnmorrisdotca.github.io/houseki/).
+- [Jirai](https://github.com/johnmorrisdotca/jirai) (地雷): minesweeper on shaped grids with verified no-guess boards. [Demo](https://johnmorrisdotca.github.io/jirai/).
+- [Karakuri](https://github.com/johnmorrisdotca/karakuri) (からくり): eight hyper-casual puzzle games, some of them physics: draw a shield, pull pins, cut ropes, slide blocks, pour tubes. [Demo](https://johnmorrisdotca.github.io/karakuri/).
+- [Kazu](https://github.com/johnmorrisdotca/kazu) (数): grid number puzzles: Sudoku and its variants, Futoshiki and Skyscrapers. [Demo](https://johnmorrisdotca.github.io/kazu/).
+- [Kyuubu](https://github.com/johnmorrisdotca/kyuubu) (キューブ): a turning cube for the browser, 2×2 to 7×7, with record solves to replay. [Demo](https://johnmorrisdotca.github.io/kyuubu/).
+- [Meikyuu](https://github.com/johnmorrisdotca/meikyuu) (迷宮): mazes on squares, hexagons, triangles and circles, made from a seed and drawn through with a finger or the mouse. [Demo](https://johnmorrisdotca.github.io/meikyuu/).
+- [Suido](https://github.com/johnmorrisdotca/suido) (水道): a pipe puzzle: turn the pieces until the water reaches every drain. [Demo](https://johnmorrisdotca.github.io/suido/).
+- [Tobiishi](https://github.com/johnmorrisdotca/tobiishi) (飛び石): peg solitaire with nine boards and seeded solvable challenges. [Demo](https://johnmorrisdotca.github.io/tobiishi/).
+- [Tsunagi](https://github.com/johnmorrisdotca/tsunagi) (繋ぎ): a line-joining logic puzzle whose every level has exactly one answer. [Demo](https://johnmorrisdotca.github.io/tsunagi/).
+
+**Games — dice & random**
+
+- [Korokoro](https://github.com/johnmorrisdotca/korokoro) (コロコロ): dice, with notation, exact odds, real sounds and the dice of many games. [Demo](https://johnmorrisdotca.github.io/korokoro/).
+- [Tane](https://github.com/johnmorrisdotca/tane) (種): seeded random numbers and daily seeds, the same in every browser and on every server. [Demo](https://johnmorrisdotca.github.io/tane/).
+
+**Language**
+
+- [Bushu](https://github.com/johnmorrisdotca/bushu) (部首): find a kanji by the parts it is made of. [Demo](https://johnmorrisdotca.github.io/bushu/).
+- [Hikidashi](https://github.com/johnmorrisdotca/hikidashi) (引き出し): a drawer of small Japanese text tools: era dates, kanji numerals, readings and sentence difficulty. [Demo](https://johnmorrisdotca.github.io/hikidashi/).
+- [Kotoba](https://github.com/johnmorrisdotca/kotoba) (言葉): word lists and word-game rules in English, French, German and Japanese. [Demo](https://johnmorrisdotca.github.io/kotoba/).
+
+**Geography & data**
+
+- [address-plus](https://github.com/johnmorrisdotca/address-plus) (アドレスプラス): parse and format addresses in the United States, Canada, Japan, Australia, France, Germany and the United Kingdom. [Demo](https://johnmorrisdotca.github.io/address-plus/).
+- [Chikyu Earth](https://github.com/johnmorrisdotca/chikyu-earth) (地球): a line-drawn globe that turns at the Earth's own rate, with an optional realistic Earth from space and markers for any place. [Demo](https://johnmorrisdotca.github.io/chikyu-earth/).
+- [Chizu](https://github.com/johnmorrisdotca/chizu) (地図): maps of the world and of countries' regions, in English and Japanese, with a quiz and callouts. [Demo](https://johnmorrisdotca.github.io/chizu/).
+- [Hata](https://github.com/johnmorrisdotca/hata) (旗): country and regional flags as SVG, at their true proportions and keyed by ISO code. [Demo](https://johnmorrisdotca.github.io/hata/).
+- [Kuni](https://github.com/johnmorrisdotca/kuni) (国): countries and their regions, with ISO codes and names in English and Japanese. [Demo](https://johnmorrisdotca.github.io/kuni/).
+
+**Sports**
+
+- [Dougu Sports](https://github.com/johnmorrisdotca/dougu-sports) (道具): sports emblems as SVG: trophies, medals, crests, and the ball and gear of every sport, with optional 3D turning. [Demo](https://johnmorrisdotca.github.io/dougu-sports/).
+- [Kyogijo Stadiums](https://github.com/johnmorrisdotca/kyogijo-stadiums) (競技場): sports fields, rinks, courts and ballparks drawn to scale as SVG, with each team and the score on them. [Demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/).
+- [Senshu Jerseys](https://github.com/johnmorrisdotca/senshu-jerseys) (選手): sports jerseys, sweaters, kits, caps, helmets and retired-number banners as SVG, front and back, with optional 2.5D turning. [Demo](https://johnmorrisdotca.github.io/senshu-jerseys/).
+- [Taisen Brackets](https://github.com/johnmorrisdotca/taisen-brackets) (対戦): a sport-agnostic tournament bracket, drawn as SVG, from a list of ties. [Demo](https://johnmorrisdotca.github.io/taisen-brackets/).
+
+**Developer tools**
+
+- [REST in Pieces](https://github.com/spxis/rest-in-pieces) (レスト・イン・ピーシーズ): seeded test data and REST APIs for frontend development, with latency and error drills. [Demo](https://spxis.github.io/rest-in-pieces/).
+
+
+**This package is Chikyu Earth.** The demos of all thirty-three share one header and footer, so each links the rest.
+<!-- family:end -->
+
 ## The rest
 
 [CONTRIBUTING.md](CONTRIBUTING.md) · [docs/](docs/index.md) · [NOTICE.md](NOTICE.md) ·

package/dist/countries.d.ts

@@ -1,3 +1,14 @@
 import type { FeatureCollection, Geometry } from "geojson";
 import type { CountryProps } from "./types.ts";
+/**
+ * Every country the globe draws, as GeoJSON in longitude and latitude (177 features, Antarctica included), each with its English name, its Japanese name and its two-letter code.
+ *
+ * @example
+ * ```ts
+ * import { COUNTRIES } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const japan = COUNTRIES.features.find((feature) => feature.properties.alpha2 === "JP");
+ * console.log(japan?.properties.name, japan?.properties.ja, COUNTRIES.features.length);
+ * ```
+ */
 export declare const COUNTRIES: FeatureCollection<Geometry, CountryProps>;

package/dist/countries.js

@@ -1,6 +1,17 @@
 // The country outlines: chizu's world-geo (Natural Earth 1:110m, WGS84 longitude and latitude) shaped for the globe.
 // Names are chizu's own English and Japanese; the alpha-2 code is its two-letter code, null for the three places with none.
 import WORLD_GEO from "@johnmorrisdotca/chizu/world-geo";
+/**
+ * Every country the globe draws, as GeoJSON in longitude and latitude (177 features, Antarctica included), each with its English name, its Japanese name and its two-letter code.
+ *
+ * @example
+ * ```ts
+ * import { COUNTRIES } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const japan = COUNTRIES.features.find((feature) => feature.properties.alpha2 === "JP");
+ * console.log(japan?.properties.name, japan?.properties.ja, COUNTRIES.features.length);
+ * ```
+ */
 export const COUNTRIES = {
     type: "FeatureCollection",
     features: WORLD_GEO.features.map((feature) => ({

package/dist/element.d.ts

@@ -1,7 +1,25 @@
-import type { GlobeView } from "./types.ts";
+import type { OverlayHost } from "./markers/layer.ts";
+import type { GeoPoint, GlobeView } from "./types.ts";
+/**
+ * The `<chikyu-earth>` custom element: the line globe, drawn as SVG in its shadow root. Importing this entry point registers the tag once. It takes the attributes `size` (pixels, 320 by default), `center` (`"lon,lat"`; wins over the browser's location), `look` (`line` or `thick`; `style` is the older name for it, and a framework that reads `style` as CSS cannot use it) and `graticule`, and a shared view controller's camera through `setView`.
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuEarth } from "@johnmorrisdotca/chikyu-earth/element";
+ *
+ * const earth = document.createElement("chikyu-earth") as ChikyuEarth;
+ * earth.setAttribute("center", "139.7,35.7");
+ * earth.setAttribute("look", "thick");
+ * document.body.append(earth);
+ * ```
+ */
 export declare class ChikyuEarth extends HTMLElement {
     #private;
     static observedAttributes: string[];
+    /** Where the view is centred now: the `center` attribute, else the reader's place once the browser has answered. */
+    get centre(): GeoPoint;
+    /** A box laid over the globe for markers (see `@johnmorrisdotca/chikyu-earth/markers`): where it is, the pose of the last drawing, and a way to hear the next. */
+    get overlay(): OverlayHost;
     connectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
     /**
@@ -10,3 +28,8 @@ export declare class ChikyuEarth extends HTMLElement {
      */
     setView(view: GlobeView, final?: boolean): void;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        "chikyu-earth": ChikyuEarth;
+    }
+}

package/dist/element.js

@@ -2,7 +2,7 @@
 // it opens centred on where you are (the `center` attribute wins over geolocation). Importing registers it once.
 import { globe } from "./globe.js";
 import { cleanStyle } from "./styles.js";
-import { HOME_VIEW } from "./view.js";
+import { globeBaseScale, HOME_VIEW, lookAt } from "./view.js";
 const readCentre = (value) => {
     if (!value)
         return null;
@@ -13,11 +13,43 @@ const readCentre = (value) => {
         return null;
     return { lon, lat };
 };
+/**
+ * The `<chikyu-earth>` custom element: the line globe, drawn as SVG in its shadow root. Importing this entry point registers the tag once. It takes the attributes `size` (pixels, 320 by default), `center` (`"lon,lat"`; wins over the browser's location), `look` (`line` or `thick`; `style` is the older name for it, and a framework that reads `style` as CSS cannot use it) and `graticule`, and a shared view controller's camera through `setView`.
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuEarth } from "@johnmorrisdotca/chikyu-earth/element";
+ *
+ * const earth = document.createElement("chikyu-earth") as ChikyuEarth;
+ * earth.setAttribute("center", "139.7,35.7");
+ * earth.setAttribute("look", "thick");
+ * document.body.append(earth);
+ * ```
+ */
 export class ChikyuEarth extends HTMLElement {
-    static observedAttributes = ["center", "style", "size", "graticule"];
+    static observedAttributes = ["center", "look", "style", "size", "graticule"];
     #centre = { lon: 0, lat: 0 };
     #view = { ...HOME_VIEW };
     #drawn = { ...HOME_VIEW };
+    #listeners = new Set();
+    #overlay;
+    #pose = null;
+    /** Where the view is centred now: the `center` attribute, else the reader's place once the browser has answered. */
+    get centre() {
+        return { ...this.#centre };
+    }
+    /** A box laid over the globe for markers (see `@johnmorrisdotca/chikyu-earth/markers`): where it is, the pose of the last drawing, and a way to hear the next. */
+    get overlay() {
+        this.#ensureShell();
+        return {
+            overlayRoot: this.#overlay,
+            pose: this.#pose,
+            subscribe: (listener) => {
+                this.#listeners.add(listener);
+                return () => this.#listeners.delete(listener);
+            },
+        };
+    }
     connectedCallback() {
         this.#centre = readCentre(this.getAttribute("center")) ?? { lon: 0, lat: 0 };
         this.#render();
@@ -59,14 +91,47 @@ export class ChikyuEarth extends HTMLElement {
         const y = this.#view.panY - this.#drawn.panY;
         svg.style.transformOrigin = "50% 50%";
         svg.style.transform = zoom === 1 && x === 0 && y === 0 ? "" : `translate(${x}px, ${y}px) scale(${zoom})`;
+        this.#publish(svg.style.transform);
+    }
+    /** The shell: the picture's holder and the overlay for markers, made once; a redraw replaces only the picture. */
+    #ensureShell() {
+        const root = this.shadowRoot ?? this.attachShadow({ mode: "open" });
+        if (!this.#overlay || !root.contains(this.#overlay)) {
+            root.innerHTML = `<style>:host{display:block;position:relative}.holder svg{display:block;width:100%;height:auto}.overlay{position:absolute;inset:0;pointer-events:none;transform-origin:50% 50%}</style><div class="holder"></div><div class="overlay"></div>`;
+            this.#overlay = root.querySelector(".overlay");
+        }
+        return root;
+    }
+    #publish(transform) {
+        if (this.#listeners.size === 0) {
+            this.#pose = null;
+            return;
+        }
+        const size = Number(this.getAttribute("size")) || 320;
+        const k = (this.clientWidth || size) / size;
+        const look = lookAt(this.#centre, this.#drawn);
+        const pose = {
+            lon: look.lon,
+            lat: look.lat,
+            radius: globeBaseScale(size) * this.#drawn.zoom * k,
+            cx: (size / 2 + this.#drawn.panX) * k,
+            cy: (size / 2 + this.#drawn.panY) * k,
+            width: size * k,
+            height: size * k,
+            transform,
+        };
+        this.#pose = pose;
+        for (const listener of this.#listeners)
+            listener(pose);
     }
     #render() {
         const size = Number(this.getAttribute("size")) || 320;
-        const style = cleanStyle(this.getAttribute("style"));
+        const style = cleanStyle(this.getAttribute("look") ?? this.getAttribute("style"));
         const svg = globe({ size, style, centre: this.#centre, view: this.#view, graticule: this.hasAttribute("graticule") });
-        const root = this.shadowRoot ?? this.attachShadow({ mode: "open" });
-        root.innerHTML = `<style>:host{display:block}svg{display:block;width:100%;height:auto}</style>${svg}`;
+        const root = this.#ensureShell();
+        root.querySelector(".holder").innerHTML = svg;
         this.#drawn = { ...this.#view };
+        this.#publish("");
     }
 }
 if (typeof customElements !== "undefined" && !customElements.get("chikyu-earth")) {

package/dist/globe.d.ts

@@ -1,3 +1,17 @@
 import type { GlobeOptions } from "./types.ts";
-/** The globe as an SVG string, turned to `rotation` and drawn in `style`, `size` pixels square. */
+/**
+ * The globe as an SVG string, turned to `rotation` and drawn in `style`, `size` pixels square. It is pure: the same options always give the same markup, so it runs on a server, in a test or in a build step with no DOM.
+ *
+ * @param options - Size, turn, look and graticule; every one has a default, so `globe()` draws a 320-pixel globe facing the Greenwich meridian.
+ * @returns One `<svg>` element as text, with the country outlines as paths.
+ *
+ * @example
+ * ```ts
+ * import { globe } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * const svg = globe({ size: 240, rotation: [-139.7, -35.7], style: "line" });
+ * console.log(svg.slice(0, 60));
+ * console.log(svg.length > 10_000);
+ * ```
+ */
 export declare function globe(options?: GlobeOptions): string;