@johnmorrisdotca/kuni 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -6,6 +6,28 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-10-14
+
+A country and subdivision card with a shared embed builder joins the demo and the package, tables download as Markdown and SQL, and the package has an English and Japanese documentation site with a checked example for every export. The country data, the codes and the lookups are unchanged.
+
+### Added
+
+- Add the bilingual documentation site, checked public examples, full country-resource catalogue, local search and machine-readable pages.
+- Add a country and subdivision card, embed builder and validated storage-free iframe.
+- Add per-place colours and a capital-marker switch to country cards and their builder/frame links. Hosts can receive drawing options in map loaders; capital text fields stay separate.
+- Share a package-independent embed builder for option controls, preview adapters, code tabs and shareable links.
+
+### Changed
+
+- The tests allow thirty seconds each (`vitest.config.js`), because the shared test that measures each entry point's size builds the country data and took longer than five seconds on a slow runner.
+- The API link in the header reads "API" in English, so that the header takes the same number of rows in English and in Japanese on a phone, as the demo's test of a language change asks.
+- Synchronize documentation tooling for repository layouts, generated type references, Node entry points and repository-specific README links.
+- Keep complete resource catalogues on the documentation entry index and the active resource beside core navigation; render valid default imports in HTML and Markdown.
+- Reconcile cards with the released IOC/withdrawn APIs; append optional ioc display while keeping current-country pickers and default fields unchanged.
+- Compose optional Hata flags and Chizu maps, retain dated facts and land-area scope, and expose reflected properties and native load/error events.
+- Group the package family by kind, alphabetize each group, and include the geography packages and REST in Pieces in the shared footer and README.
+- Update the shared family description for addresses in all seven supported countries, including France and Germany.
+
 ## [1.3.0] - 2026-10-09
 
 ### Added

package/README.md

@@ -1,4 +1,4 @@
-<h1 align="center">Kuni <sub>国</sub></h1>
+<h1 align="center">Kuni <sub>国</sub> — Countries, states and provinces</h1>
 
 <p align="center"><strong>Kuni 国: every country and its states, provinces and prefectures, with ISO 3166 codes and names in English and Japanese.</strong><br>
 A typed, zero-dependency dataset from Unicode CLDR and Wikidata, loaded one country at a time, for JavaScript and TypeScript. Look up a country or a region by code or by what somebody typed, in either language, and load only the countries you need.</p>
@@ -11,23 +11,25 @@ A typed, zero-dependency dataset from Unicode CLDR and Wikidata, loaded one coun
   <a href="./LICENSE"><img alt="MIT licence" src="https://img.shields.io/badge/licence-MIT-2f5d4a"></a>
   <img alt="No dependencies" src="https://img.shields.io/badge/dependencies-0-2f5d4a">
   <img alt="TypeScript" src="https://img.shields.io/badge/types-TypeScript-3178c6">
+  <a href="https://johnmorrisdotca.github.io/kuni/docs/api/main/index.html"><img alt="21.4 kB minified and gzipped" src="https://img.shields.io/badge/min%2Bgzip-21.4%20kB-2f5d4a"></a>
+  <a href="https://www.npmjs.com/package/@johnmorrisdotca/kuni#provenance"><img alt="Published with npm provenance" src="https://img.shields.io/badge/npm-provenance-2f5d4a"></a>
 </p>
 
-<p align="center"><a href="https://johnmorrisdotca.github.io/kuni/"><strong>Try it →</strong></a> · <a href="https://johnmorrisdotca.github.io/kuni/api.html">API reference</a></p>
+<p align="center"><a href="https://johnmorrisdotca.github.io/kuni/"><strong>Try it →</strong></a> · <a href="https://johnmorrisdotca.github.io/kuni/docs/">Documentation</a> · <a href="https://johnmorrisdotca.github.io/kuni/docs/guides/getting-started.html">Getting started</a> · <a href="https://johnmorrisdotca.github.io/kuni/api.html">API reference</a></p>
 
 <table align="center">
 <tr>
 <td align="center" valign="top">
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-desk-dark.webp">
-<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-desk-light.webp" alt="The demo on a desk, in English: the header with its language chooser, the API reference link, five cloth patches and the Help switch, then a row of views (Look up, Country, Compare, All countries, Groupings, Quiz, Form widget, Data quality) and the Look up view's panels. Find a country shows ドイツ typed in and its answer: the German flag, DE, DEU and 276, Germany, ドイツ, Deutschland, Europe, Berlin, +49, EUR, .de, two time zones, and 16 states. Subdivisions of a country shows Japan picked and a table of its prefectures with code, English and Japanese name, from JP-01 Hokkaidō 北海道, and the line 47 subdivisions; the main kind is prefecture. Look up a code begins below with JP-13 typed in." width="600">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-desk-light.webp" alt="The demo on a desk, in English: the header with its language chooser, the Docs and API reference links, five cloth patches and the Help switch, then a row of views (Look up, Country, Compare, All countries, Groupings, Quiz, Form widget, Data quality) and the Look up view's panels. Find a country shows ドイツ typed in and its answer: the German flag, DE, DEU and 276, Germany, ドイツ, Deutschland, Europe, Berlin, +49, EUR, .de, two time zones, and 16 states. Subdivisions of a country shows Japan picked and a table of its prefectures with code, English and Japanese name, from JP-01 Hokkaidō 北海道, and the line 47 subdivisions; the main kind is prefecture. Look up a code begins below with JP-13 typed in." width="600">
 </picture>
 <br><em>The demo on a desk: a country found by its Japanese name, and Japan's prefectures loaded on demand.</em>
 </td>
 <td align="center" valign="top">
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-phone-dark.webp">
-<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-phone-light.webp" alt="The demo on a phone, in Japanese: the header, its language chooser, patches and buttons, then the first panel, 国を探す, with ドイツ typed in, its row of examples, and the start of its answer, the German flag and DE, DEU, 276, under the row of views" width="190">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-phone-light.webp" alt="The demo on a phone, in Japanese: the header, its language chooser, patches and buttons, then the first panel, 国を探す, with ドイツ typed in below the view choices and the Docs/API navigation" width="190">
 </picture>
 <br><em>On a phone, in Japanese, in the device's light or dark.</em>
 </td>
@@ -84,6 +86,8 @@ Install the scoped name: the unscoped `kuni` on npm is somebody else's package.
 
 ## Features
 
+### What's in it
+
 - **Every country.** The 249 ISO 3166-1 codes and Kosovo (XK, user-assigned), each with alpha-2, alpha-3 and numeric codes, its flag, continent, UN M49 subregion, calling code, currencies, top-level domain, capital, time zones and languages.
 - **Every subdivision.** 5,050 ISO 3166-2 codes in 200 countries: 3,594 at the first level and 1,456 below it (France's departments in its regions, England's councils in England), each with its level and parent.
 - **English and Japanese names** from Unicode CLDR 48.2, with CLDR's short forms (UK, アメリカ) and variants (Ivory Coast, 象牙海岸). Japanese names for 3,527 of the 3,594 first-level subdivisions, and `null` for the rest, never a guess.
@@ -95,13 +99,26 @@ Install the scoped name: the unscoped `kuni` on npm is somebody else's package.
 - **Withdrawn countries** (`/withdrawn`): the 31 entries of ISO 3166-3 (SU, YU, CS, DD, ZR, TP, AN, BU and the rest), each with the four-letter code, the alpha-2, alpha-3 and numeric codes it held, its name in English and Japanese, the years the code was in force and the codes ISO lists for what came after it. They are never in `countries()`, so a picker does not offer the Soviet Union; a lookup by an old code says what it was.
 - **Olympic codes**: `country(code).ioc` is the International Olympic Committee's three-letter code ("JPN", "GER" for Germany, "SUI" for Switzerland) for the 209 countries that have one.
 - **Groupings** (`/groupings`): the seven continents, the 30 UN M49 areas, 23 international bodies (the UN, the EU, the euro area, Schengen, NATO, the G7 and G20, ASEAN and more) with the days members joined and left, 16 informal groupings (the Middle East, the Balkans, Scandinavia, the Sahel) each with the definition it follows, and regions inside a country (Japan's 地方, the US Census regions, Canada's regions).
-- **Small where it matters.** The countries and lookups are about 57 KB (19 KB gzipped); one country's subdivisions are their own entry (Japan's 47, 2.9 KB) or a dynamic import.
+- **Small where it matters.** The countries and lookups are 21.4 kB minified and gzipped; one country's subdivisions are their own entry (Japan's 47, measured separately) or a dynamic import.
 - **Typed, frozen, pure and the same everywhere.** ESM and CommonJS, types for both, no dependencies, no network and no `Intl`. Every export carries a doc comment with a runnable example, which an editor shows on hover and the tests run.
 - **A demo to use, not just to read.** A page for each country, two countries compared, every country in a sortable table, the groupings explorer, three seeded quizzes, a country and region form widget with its code to copy, and the data's quality in the open, each at an address of its own and downloadable as CSV, JSON, text, a Markdown table or SQL: [the demo](https://johnmorrisdotca.github.io/kuni/).
 - **Never a guess.** A value no source gives is `null`, with the reason written down (`docs/facts.md`, `docs/subdivision-facts.md`, `docs/ja-gaps.md`), never a plausible filler.
 
+[Build a country or subdivision card](https://johnmorrisdotca.github.io/kuni/builder.html). The [embed guide](docs/embeds.md) covers its fields, properties and messages. Cards support per-place `colors` and `capital="off"` for the native Chizu map; capital text stays separate. [Map colours and markers](docs/embeds.md#map-colours-and-markers).
+
 ## Use it in your project
 
+### Install under another name
+
+```sh
+npm install countries@npm:@johnmorrisdotca/kuni
+```
+
+```ts no-check
+import { country } from "countries";
+console.log(country("JP")?.name.en);
+```
+
 ### Install
 
 ```sh
@@ -114,18 +131,20 @@ It ships ES modules and CommonJS, with types for both and `sideEffects: false`.
 
 ### The entry points
 
-| Entry | What it carries | Size (ESM) |
+| Entry | What it carries | Size (minified + gzip) |
 | --- | --- | --- |
-| `@johnmorrisdotca/kuni` | The 250 countries and the country lookups | 64 KB, 22 KB gzipped |
-| `@johnmorrisdotca/kuni/codes` | The 250 codes and `isCountryCode`, nothing else | 2 KB |
-| `@johnmorrisdotca/kuni/subdivisions/<code>` | One country's subdivisions, every level (`/subdivisions/jp`, `/subdivisions/us`, lower case) | 1 to 13 KB; Japan 2.9 KB |
-| `@johnmorrisdotca/kuni/load` | `loadSubdivisions(code)`, one dynamic import per country | 11 KB, then the country's own file |
-| `@johnmorrisdotca/kuni/subdivisions` | All 5,050 subdivisions and the subdivision lookups | 216 KB, 85 KB gzipped |
-| `@johnmorrisdotca/kuni/facts` | Every country's population, area, coordinates, borders, driving side and conventions | 25 KB, 9 KB gzipped |
-| `@johnmorrisdotca/kuni/subdivision-facts` | `loadSubdivisionFacts(code)`, one dynamic import per country | 12 KB, then the country's own file |
-| `@johnmorrisdotca/kuni/subdivision-facts/<code>` | One country's subdivision facts (`/subdivision-facts/jp`) | 1 to 16 KB; Japan 4.9 KB |
-| `@johnmorrisdotca/kuni/groupings` | The 107 groupings and their lookups | 84 KB, 16 KB gzipped |
-| `@johnmorrisdotca/kuni/withdrawn` | The 31 withdrawn countries (ISO 3166-3) and `withdrawn(code)` | 8 KB, 2.4 KB gzipped |
+| `@johnmorrisdotca/kuni` | The 250 countries and the country lookups | 21.4 kB min+gzip |
+| `@johnmorrisdotca/kuni/element` | `KuniCard`, `defineCard`, `KUNI_CARD_FIELDS`, `KUNI_CARD_OPTION_KEYS`, `readCardColors`; `KuniCardOptions` | 290.5 kB min+gzip |
+| `@johnmorrisdotca/kuni/element/define` | registers the tag and re-exports the element API | 290.5 kB min+gzip |
+| `@johnmorrisdotca/kuni/codes` | The 250 codes and `isCountryCode`, nothing else | 0.6 kB min+gzip |
+| `@johnmorrisdotca/kuni/subdivisions/<code>` | One country's subdivisions, every level (`/subdivisions/jp`, `/subdivisions/us`, lower case) | 0.4–5.0 kB; Japan 1.5 kB |
+| `@johnmorrisdotca/kuni/load` | `loadSubdivisions(code)`, one dynamic import per country | 97.6 kB min+gzip |
+| `@johnmorrisdotca/kuni/subdivisions` | All 5,050 subdivisions and the subdivision lookups | 88.4 kB min+gzip |
+| `@johnmorrisdotca/kuni/facts` | Every country's population, area, coordinates, borders, driving side and conventions | 8.6 kB min+gzip |
+| `@johnmorrisdotca/kuni/subdivision-facts` | `loadSubdivisionFacts(code)`, one dynamic import per country | 161.1 kB min+gzip |
+| `@johnmorrisdotca/kuni/subdivision-facts/<code>` | One country's subdivision facts (`/subdivision-facts/jp`) | 0.4–7.3 kB; Japan 2.4 kB |
+| `@johnmorrisdotca/kuni/groupings` | The 107 groupings and their lookups | 15.9 kB min+gzip |
+| `@johnmorrisdotca/kuni/withdrawn` | The 31 withdrawn countries (ISO 3166-3) and `withdrawn(code)` | 2.1 kB min+gzip |
 
 ### 1. The countries
 
@@ -235,6 +254,33 @@ The 31 are the entries of ISO 3166-3, whose codes, years and successors are the
 </script>
 ```
 
+### A card in a framework
+
+React 19:
+
+```jsx
+import "@johnmorrisdotca/kuni/element/define";
+export function Japan() { return <kuni-card code="JP" fields="name flag map capital" />; }
+```
+
+Configure Vue's template compiler with `isCustomElement: tag => tag.startsWith("kuni-")`:
+
+```vue
+<script setup>
+import "@johnmorrisdotca/kuni/element/define";
+</script>
+<template><kuni-card code="JP" /></template>
+```
+
+```svelte
+<script>
+  import "@johnmorrisdotca/kuni/element/define";
+</script>
+<kuni-card code="JP" fields="name codes capital"></kuni-card>
+```
+
+The `@johnmorrisdotca/kuni/element` entry exports the class and `defineCard(tag?)`; `@johnmorrisdotca/kuni/element/define` registers the tag. Both are safe to import on a server. The builder also supplies plain HTML, Vue, Svelte, Angular and iframe examples.
+
 ## Examples
 
 ### A country select, in either language
@@ -280,9 +326,51 @@ subdivisionsByName("Punjab").map((one) => one.code); // ["IN-PB", "PK-PB"]
 subdivisionByName("Punjab", { country: "PK" })?.code; // "PK-PB"
 ```
 
+
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/find-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/find-desk-light.webp" alt="The find panel showing a country found by its Japanese name and its native codes and fields" width="600">
+</picture>
+<br><em>The find panel shows a country found by its Japanese name and its native codes and fields.</em>
+
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/list-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/list-desk-light.webp" alt="The list panel showing Japan’s prefectures loaded as a native subdivision table" width="600">
+</picture>
+<br><em>The list panel shows Japan’s prefectures loaded as a native subdivision table.</em>
+
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/code-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/code-desk-light.webp" alt="The code panel showing a full subdivision code resolved to its native record" width="600">
+</picture>
+<br><em>The code panel shows a full subdivision code resolved to its native record.</em>
+
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/search-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/search-desk-light.webp" alt="The search panel showing all countries using the typed calling code, currency or domain" width="600">
+</picture>
+<br><em>The search panel shows all countries using the typed calling code, currency or domain.</em>
+
+### Validate an exact country code
+
+```ts
+import { isCountryCode } from "@johnmorrisdotca/kuni/codes";
+console.log(isCountryCode("JP"),isCountryCode("jp"));
+```
+
+### Read a dated country figure
+
+```ts
+import { facts,FACTS_READ } from "@johnmorrisdotca/kuni/facts";
+const japan=facts("JP");
+console.log(FACTS_READ,japan?.population,japan?.populationYear);
+```
+
 ## API
 
-The [API reference](https://johnmorrisdotca.github.io/kuni/api.html) lists every export of every entry point with its signature and its comment. It is made from the source by `pnpm site`, so it cannot fall behind the code.
+The [documentation](https://johnmorrisdotca.github.io/kuni/docs/) provides paired guides, local search and checked examples. The [complete country-resource catalogue](docs/guides/country-resources.md) names every existing per-country import, including subdivisions and their facts.
+
+The [API reference](https://johnmorrisdotca.github.io/kuni/api.html) lists every export of every entry point with its signature and its comment. `pnpm docs:site` retains the index anchors and builds individual reference pages from source, so the documentation stays with the code.
 
 | Entry | Exports |
 | --- | --- |
@@ -443,26 +531,7 @@ Left out on purpose: geometry (see [Chizu](https://github.com/johnmorrisdotca/ch
 
 ## Architecture
 
-```text
-src/
-├── index.ts            the main entry: the countries and their lookups
-├── codes.ts            the "/codes" entry: the codes alone
-├── subdivisions.ts     the "/subdivisions" entry: every subdivision and its lookups
-├── load.ts             the "/load" entry: one country's subdivisions by dynamic import
-├── facts.ts            the "/facts" entry: population, area, coordinates, borders and conventions
-├── subdivision-facts.ts  the "/subdivision-facts" entry: one country's subdivision facts by dynamic import
-├── groupings.ts        the "/groupings" entry: continents, UN M49, bodies, informal groupings, regions
-├── withdrawn.ts        the "/withdrawn" entry: the countries ISO 3166-3 lists as withdrawn, and the codes they held
-├── fold.ts             folding what somebody typed: case, accents, width, kana
-├── rows.ts             turning the data's compact rows into objects
-├── types.ts            the shapes of a country and a subdivision, and the kinds of place
-├── version.ts          the package's version
-├── data/               written by scripts/build-data.ts: countries, codes, facts, groupings, and files per country
-├── subdivisions/       written by scripts/build-data.ts: the "/subdivisions/<code>" entries
-└── subdivision-facts/  written by scripts/build-data.ts: the "/subdivision-facts/<code>" entries
-```
-
-`scripts/build-data.ts` (`pnpm data`) makes `src/data/` from the inputs in `data-sources/` and three npm packages, with no network, and checks every input's SHA-256 first; run twice, it leaves the tree as it was. `scripts/data-config.ts`, `scripts/facts-config.ts`, `scripts/groupings-config.ts` and `scripts/withdrawn-config.ts` hold the few things written by hand, each with its reason; `scripts/facts.ts`, `scripts/subdivision-facts.ts`, `scripts/groupings.ts` and `scripts/withdrawn.ts` apply the rules written at their tops. Tests sit beside the code (`*.test.ts`). `scripts/` also builds the demo and its API page and checks the package as npm packs it; `demo/` is the page and `e2e/` its browser tests.
+The [architecture guide](docs/guides/architecture.md) retains the complete original source tree and explanation of data generation, lazy loading and public boundaries. Each native country resource keeps its existing file and runtime data.
 
 ## Data and licences
 
@@ -499,41 +568,80 @@ Using Kuni in something else? Open an *Add my project* issue and we will add you
 
 ### The family
 
-Kuni is not yet in the family's shared list (the template every demo's header and footer read), which is changed in every repository at once; until it is, its demo adds itself at the end. The list as it will be:
+<!-- family:start (made by scripts/family-readme.mjs from scripts/family-template.mjs; change those, not this) -->
+Kuni is one of thirty-two 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.
 
-Kuni is one of twenty-five packages, each made for the same site, each at
-[github.com/johnmorrisdotca](https://github.com/johnmorrisdotca). The code of every one is MIT.
+**Games — board**
 
-- [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/).
-- [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/).
-- [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/).
-- [Toranpu](https://github.com/johnmorrisdotca/toranpu) (トランプ): a deck of playing cards, card games with computer players, and solitaires. [Demo](https://johnmorrisdotca.github.io/toranpu/).
-- [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/).
+- [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/).
-- [Kumimoji](https://github.com/johnmorrisdotca/kumimoji) (組み文字): a crossword tile race, in English and Japanese kana. [Demo](https://johnmorrisdotca.github.io/kumimoji/).
-- [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 — 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/).
-- [Suido](https://github.com/johnmorrisdotca/suido) (水道): a pipe puzzle: turn the pieces until the water reaches every drain. [Demo](https://johnmorrisdotca.github.io/suido/).
-- [Domino](https://github.com/johnmorrisdotca/domino) (ドミノ): dominoes and Mexican Train. [Demo](https://johnmorrisdotca.github.io/domino/).
-- [Kotoba](https://github.com/johnmorrisdotca/kotoba) (言葉): word lists and word-game rules in English, French, German and Japanese. [Demo](https://johnmorrisdotca.github.io/kotoba/).
-- [Sugoroku](https://github.com/johnmorrisdotca/sugoroku) (双六): backgammon and its variants, with the doubling cube and match play. [Demo](https://johnmorrisdotca.github.io/sugoroku/).
+- [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/).
 - [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/).
-- [Bushu](https://github.com/johnmorrisdotca/bushu) (部首): find a kanji by the parts it is made of. [Demo](https://johnmorrisdotca.github.io/bushu/).
-- [Tobiishi](https://github.com/johnmorrisdotca/tobiishi) (飛び石): peg solitaire with nine boards and seeded solvable challenges. [Demo](https://johnmorrisdotca.github.io/tobiishi/).
-- [Jirai](https://github.com/johnmorrisdotca/jirai) (地雷): minesweeper on shaped grids with verified no-guess boards. [Demo](https://johnmorrisdotca.github.io/jirai/).
-- [Gunjin](https://github.com/johnmorrisdotca/gunjin) (軍人): five hidden-rank strategy games with pass-the-device play. [Demo](https://johnmorrisdotca.github.io/gunjin/).
-- [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/).
-- [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/).
-- [Kuni](https://github.com/johnmorrisdotca/kuni) (国): every country and its subdivisions, with ISO 3166 codes and names in English and Japanese. [Demo](https://johnmorrisdotca.github.io/kuni/).
+- [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**
 
-**This package is Kuni.** The demos of all twenty-five share one header and footer, so each links the rest.
+- [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 Kuni.** The demos of all thirty-two share one header and footer, so each links the rest.
+<!-- family:end -->
 
 ## Development
 
+```sh
+pnpm docs:site
+pnpm docs:check
+pnpm size --write
+```
+
+The shared generator checks real imports and guide examples. `pnpm docs:make` also refreshes the country-resource catalogue and the original language reference. `node scripts/build-data.ts --docs-only` refreshes stored generated examples without fetching or changing source data.
+
 ```sh
 pnpm install
 pnpm check                # lint, types, build, every test (sizes included), and the packed package
@@ -553,7 +661,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md); the commands are under [Development](#
 
 ## Changes
 
-See [CHANGELOG.md](./CHANGELOG.md). The latest release, 1.3.0, adds each country's IOC code and the 31 withdrawn countries of ISO 3166-3 (Yugoslavia, the Soviet Union, Zaire and the rest) in a list of their own, with their years and the codes that replaced them.
+See [CHANGELOG.md](./CHANGELOG.md). The latest release, 1.4.0, adds the country card with the standard embed attributes, the shared embed builder, and the documentation site with a checked example for every export.
 
 ## Licence
 

package/dist/codes.d.cts

@@ -5,12 +5,19 @@
  * ```ts
  * import { COUNTRY_CODES } from "@johnmorrisdotca/kuni/codes";
  *
- * COUNTRY_CODES.length;   // 250
- * COUNTRY_CODES[0];       // "AD"
+ * console.log(COUNTRY_CODES.length);   // 250
+ * console.log(COUNTRY_CODES[0]);       // "AD"
  * ```
  */
 declare const COUNTRY_CODES: readonly ["AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW"];
-/** One of the 250 country codes, as a type: "JP" | "US" | ... */
+/** One of the 250 country codes, as a type: "JP" | "US" | ...
+ * @example
+ * ```ts
+ * import type { CountryCode } from "@johnmorrisdotca/kuni/codes";
+ * const code: CountryCode = "JP";
+ * console.log(code);
+ * ```
+ */
 type CountryCode = (typeof COUNTRY_CODES)[number];
 
 /**
@@ -23,9 +30,9 @@ type CountryCode = (typeof COUNTRY_CODES)[number];
  * ```ts
  * import { isCountryCode } from "@johnmorrisdotca/kuni/codes";
  *
- * isCountryCode("JP");   // true
- * isCountryCode("jp");   // false
- * isCountryCode("XX");   // false
+ * console.log(isCountryCode("JP"));   // true
+ * console.log(isCountryCode("jp"));   // false
+ * console.log(isCountryCode("XX"));   // false
  * ```
  */
 declare const isCountryCode: (value: unknown) => value is CountryCode;

package/dist/codes.d.ts

@@ -5,12 +5,19 @@
  * ```ts
  * import { COUNTRY_CODES } from "@johnmorrisdotca/kuni/codes";
  *
- * COUNTRY_CODES.length;   // 250
- * COUNTRY_CODES[0];       // "AD"
+ * console.log(COUNTRY_CODES.length);   // 250
+ * console.log(COUNTRY_CODES[0]);       // "AD"
  * ```
  */
 declare const COUNTRY_CODES: readonly ["AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW"];
-/** One of the 250 country codes, as a type: "JP" | "US" | ... */
+/** One of the 250 country codes, as a type: "JP" | "US" | ...
+ * @example
+ * ```ts
+ * import type { CountryCode } from "@johnmorrisdotca/kuni/codes";
+ * const code: CountryCode = "JP";
+ * console.log(code);
+ * ```
+ */
 type CountryCode = (typeof COUNTRY_CODES)[number];
 
 /**
@@ -23,9 +30,9 @@ type CountryCode = (typeof COUNTRY_CODES)[number];
  * ```ts
  * import { isCountryCode } from "@johnmorrisdotca/kuni/codes";
  *
- * isCountryCode("JP");   // true
- * isCountryCode("jp");   // false
- * isCountryCode("XX");   // false
+ * console.log(isCountryCode("JP"));   // true
+ * console.log(isCountryCode("jp"));   // false
+ * console.log(isCountryCode("XX"));   // false
  * ```
  */
 declare const isCountryCode: (value: unknown) => value is CountryCode;

package/dist/element-define.cjs

@@ -0,0 +1,26 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/element-define.ts
+var element_define_exports = {};
+module.exports = __toCommonJS(element_define_exports);
+var import_element = require("./element.cjs");
+__reExport(element_define_exports, require("./element.cjs"), module.exports);
+(0, import_element.defineCard)();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("./element.cjs")
+});

package/dist/element-define.d.cts

@@ -0,0 +1 @@
+export { KUNI_CARD_FIELDS, KUNI_CARD_OPTION_KEYS, KuniCard, KuniCardOptions, defineCard, readCardColors } from './element.cjs';

package/dist/element-define.d.ts

@@ -0,0 +1 @@
+export { KUNI_CARD_FIELDS, KUNI_CARD_OPTION_KEYS, KuniCard, KuniCardOptions, defineCard, readCardColors } from './element.js';

package/dist/element-define.js

@@ -0,0 +1,4 @@
+// src/element-define.ts
+import { defineCard } from "./element.js";
+export * from "./element.js";
+defineCard();