@johnmorrisdotca/chikyu-earth 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # 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.

package/NOTICE.md

@@ -33,6 +33,17 @@ material, so no other licence applies. This package is not endorsed by NASA and
 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,

package/README.md

@@ -9,43 +9,106 @@ 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
 ```
 
-```html
-<script type="module">
-  import "@johnmorrisdotca/kazoku-ui/view-controls/define";
-  import "@johnmorrisdotca/chikyu-earth/element";
-</script>
+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.
 
-<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>
+### In a plain HTML page
 
-<script type="module">
-  const earth = document.querySelector("chikyu-earth");
-  document.getElementById("controls").addEventListener("kazoku-viewchange", (event) => {
-    earth.setView(event.detail, event.detail.final);
-  });
-</script>
+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
+<!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>
 ```
 
-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.
+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`.
 
-Centre it yourself instead:
+### 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
-<chikyu-earth center="139.7,35.7" style="thick" graticule></chikyu-earth>
+<!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
@@ -64,12 +127,21 @@ Needs `three` and `@johnmorrisdotca/kazoku-ui` (both optional peers) and the pic
 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).
 
+## The Sun, the Moon and the planets
+
+`<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
+```ts no-run
+import "@johnmorrisdotca/chikyu-earth/element";
 import { attachMarkers } from "@johnmorrisdotca/chikyu-earth/markers";
 
 const markers = attachMarkers(document.querySelector("chikyu-earth")!);
@@ -87,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);
 });
 ```
@@ -122,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
@@ -147,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,5 +1,18 @@
 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[];
@@ -15,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

@@ -13,8 +13,21 @@ 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 };
@@ -113,7 +126,7 @@ export class ChikyuEarth extends HTMLElement {
     }
     #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.#ensureShell();
         root.querySelector(".holder").innerHTML = svg;

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;

package/dist/globe.js

@@ -5,7 +5,21 @@ import { COUNTRIES } from "./countries.js";
 import { cleanStyle, STYLES } from "./styles.js";
 import { projectionView } from "./view.js";
 const SPHERE = { type: "Sphere" };
-/** 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 function globe(options = {}) {
     const size = options.size ?? 320;
     const style = STYLES[cleanStyle(options.style)];

package/dist/index.d.ts

@@ -5,5 +5,16 @@ export { centreRotation, DEGREES_PER_MS, rotationAt, SIDEREAL_DAY_MS, spinAt } f
 export { globeBaseScale, HOME_VIEW, projectionView, type ProjectionView } from "./view.ts";
 export type { CountryProps, GeoPoint, GlobeOptions, GlobeView, Rotation } from "./types.ts";
 import type { CountryProps } from "./types.ts";
-/** Every country the globe draws, with its kuni name and code. */
+/**
+ * Every country the globe draws, with its kuni name and code.
+ *
+ * @returns A list of English name, Japanese name (or `null`) and two-letter code (or `null` where a place has none).
+ *
+ * @example
+ * ```ts
+ * import { countryList } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(countryList().find((country) => country.alpha2 === "JP"));
+ * ```
+ */
 export declare const countryList: () => CountryProps[];

package/dist/index.js

@@ -4,5 +4,16 @@ export { cleanStyle, DEFAULT_STYLE, STYLE_NAMES, STYLES } from "./styles.js";
 export { centreRotation, DEGREES_PER_MS, rotationAt, SIDEREAL_DAY_MS, spinAt } from "./rotate.js";
 export { globeBaseScale, HOME_VIEW, projectionView } from "./view.js";
 import { COUNTRIES } from "./countries.js";
-/** Every country the globe draws, with its kuni name and code. */
+/**
+ * Every country the globe draws, with its kuni name and code.
+ *
+ * @returns A list of English name, Japanese name (or `null`) and two-letter code (or `null` where a place has none).
+ *
+ * @example
+ * ```ts
+ * import { countryList } from "@johnmorrisdotca/chikyu-earth";
+ *
+ * console.log(countryList().find((country) => country.alpha2 === "JP"));
+ * ```
+ */
 export const countryList = () => COUNTRIES.features.map((f) => f.properties);

package/dist/markers/cluster.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Several points gathered into one on the screen: where it is drawn and which points are in it.
+ *
+ * @example
+ * ```ts
+ * import { clusterPoints, type Cluster } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const clusters: Cluster[] = clusterPoints([0, 1], 2, [10, 12], [10, 11], 28);
+ * console.log(clusters[0]?.members);
+ * ```
+ */
 export interface Cluster {
     x: number;
     y: number;
@@ -7,5 +18,21 @@ export interface Cluster {
 /**
  * Group the points `indices` (into `xs` and `ys`) by the grid cell they fall in. A cell with one point is that point alone; with more it is one cluster at their
  * average. Order is stable: clusters come in the order their first member was seen.
+ *
+ * @param indices - Which points to group: indices into `xs` and `ys`.
+ * @param count - How many of `indices` to read.
+ * @param xs - Every point's x on the screen, in pixels.
+ * @param ys - Every point's y on the screen, in pixels.
+ * @param cell - The side of a grid cell in pixels; points in one cell join.
+ * @returns The clusters, each with the indices of its members; a lone point is a cluster of one.
+ *
+ * @example
+ * ```ts
+ * import { clusterPoints } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const xs = [10, 14, 200];
+ * const ys = [10, 12, 200];
+ * console.log(clusterPoints([0, 1, 2], 3, xs, ys, 28).map((cluster) => cluster.members));
+ * ```
  */
 export declare function clusterPoints(indices: ArrayLike<number>, count: number, xs: ArrayLike<number>, ys: ArrayLike<number>, cell: number): Cluster[];

package/dist/markers/cluster.js

@@ -2,6 +2,22 @@
 /**
  * Group the points `indices` (into `xs` and `ys`) by the grid cell they fall in. A cell with one point is that point alone; with more it is one cluster at their
  * average. Order is stable: clusters come in the order their first member was seen.
+ *
+ * @param indices - Which points to group: indices into `xs` and `ys`.
+ * @param count - How many of `indices` to read.
+ * @param xs - Every point's x on the screen, in pixels.
+ * @param ys - Every point's y on the screen, in pixels.
+ * @param cell - The side of a grid cell in pixels; points in one cell join.
+ * @returns The clusters, each with the indices of its members; a lone point is a cluster of one.
+ *
+ * @example
+ * ```ts
+ * import { clusterPoints } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const xs = [10, 14, 200];
+ * const ys = [10, 12, 200];
+ * console.log(clusterPoints([0, 1, 2], 3, xs, ys, 28).map((cluster) => cluster.members));
+ * ```
  */
 export function clusterPoints(indices, count, xs, ys, cell) {
     const cells = new Map();

package/dist/markers/labels.d.ts

@@ -1,3 +1,14 @@
+/**
+ * One label to place: its dot's centre and radius, its box's size and its priority.
+ *
+ * @example
+ * ```ts
+ * import type { LabelItem } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const label: LabelItem = { x: 100, y: 100, r: 4, w: 60, h: 20, priority: 1 };
+ * console.log(label.w);
+ * ```
+ */
 export interface LabelItem {
     /** The dot's centre and radius. */
     x: number;
@@ -9,6 +20,17 @@ export interface LabelItem {
     /** Higher is placed first. */
     priority: number;
 }
+/**
+ * Where one label goes: which item it is and its box's top-left corner.
+ *
+ * @example
+ * ```ts
+ * import { placeLabels, type Placement } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const placed: Placement[] = placeLabels([{ x: 100, y: 100, r: 4, w: 60, h: 20, priority: 1 }], 300, 300, 10);
+ * console.log(placed[0]);
+ * ```
+ */
 export interface Placement {
     /** Index into the items given. */
     item: number;
@@ -20,5 +42,23 @@ export interface Placement {
  * Place up to `max` labels inside `width` x `height`. Each label is tried to the right of its dot, then to the left, above and below; the first spot that is inside
  * and free of the labels already placed wins. Items are taken highest priority first (a tie keeps the order given). The cost is the number of items times at most
  * four tries against a grid of what is placed.
+ *
+ * @param items - The dots and the size of each one's label.
+ * @param width - The width of the area the labels must stay inside, in pixels.
+ * @param height - The height of that area, in pixels.
+ * @param max - The most labels to place.
+ * @param cell - The side of the grid cell used to find overlaps, in pixels.
+ * @returns A placement for each label that fits; the others are left out.
+ *
+ * @example
+ * ```ts
+ * import { placeLabels } from "@johnmorrisdotca/chikyu-earth/markers";
+ *
+ * const items = [
+ *   { x: 100, y: 100, r: 4, w: 60, h: 20, priority: 1 },
+ *   { x: 110, y: 104, r: 4, w: 60, h: 20, priority: 9 },
+ * ];
+ * console.log(placeLabels(items, 300, 300, 10).map((place) => place.item));
+ * ```
  */
 export declare function placeLabels(items: readonly LabelItem[], width: number, height: number, max: number, cell?: number): Placement[];