@johnmorrisdotca/dougu-sports 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project are written here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.0.1] - 2026-10-14
+
+First preview: the name, the API and two sample emblems. The full set of trophies, medals, crests, balls and gear follows.
+
+### Added
+
+- The scaffold: `renderEmblem(id, { style, size, tint, theme })` with the three styles `metal`, `line` and `color`; `emblemFrame` and `ballFrame` for turning; the `EmblemId` union and the groups `award`, `trophy`, `medal`, `crest`, `ball`, `gear` and `sport`; the thirty-three sports' names; one module per item under `./award/*`, `./ball/*` and `./gear/*`, so a bundler takes one emblem and leaves the rest.
+- Two sample emblems that stand in for the art: `award:medal` (a flat emblem that flips like a coin) and `ball:soccer` (a ball that rolls).
+- Tests for the drawing, the ids, the turns and the bundle size of one item; a package check that installs the packed tarball and bundles one item from it.
+- The demo (a playground with a turn slider, and a gallery page), `docs/layout.md`, `docs/turning.md`, `docs/gallery.md`, the family header and footer, the CI, Pages and Release workflows, and `LICENSES/` and `NOTICE.md` ready for third-party art.
+
+[Unreleased]: https://github.com/johnmorrisdotca/dougu-sports/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/johnmorrisdotca/dougu-sports/releases/tag/v0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Morris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSES/Apache-2.0.txt

@@ -0,0 +1,55 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/ 
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/LICENSES/CC-BY-3.0.md

@@ -0,0 +1,15 @@
+# Creative Commons Attribution 3.0 Unported
+
+The icons of [game-icons.net](https://game-icons.net/) are under this licence, each by its own author. The full legal code is at
+<https://creativecommons.org/licenses/by/3.0/legalcode>, and the summary a reader can follow is at
+<https://creativecommons.org/licenses/by/3.0/>.
+
+What the licence asks of this package, and what it does:
+
+- **Credit the author**: every emblem made from a game-icons.net icon has a row in [NOTICE.md](../NOTICE.md) naming the icon, its
+  author and its page on game-icons.net, and the README and the demo point to that file.
+- **Link to the licence**: the row names the licence and links to it.
+- **Say that the icon was changed**: the row says how it was changed (recoloured to the three styles, scaled, its path simplified).
+
+No emblem uses a game-icons.net icon yet. The legal code is linked and not copied here: the text a reader needs to check is the one
+the Creative Commons publishes.

package/LICENSES/MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Morris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSES/README.md

@@ -0,0 +1,13 @@
+# Licences
+
+The code of this package is under the MIT licence: [MIT.txt](MIT.txt), the same text as [../LICENSE](../LICENSE).
+
+Art taken from another project keeps its own licence, and that licence's text is kept in this folder, named for the licence, as soon as an emblem that uses it ships. [../NOTICE.md](../NOTICE.md) says which emblem comes from which source, under which licence, and what credit it asks for.
+
+| File | Licence | Covers |
+| --- | --- | --- |
+| [MIT.txt](MIT.txt) | MIT | The code of the package, and the art drawn for it (`source: "ours"`) |
+| [Apache-2.0.txt](Apache-2.0.txt) | Apache License 2.0 | Material Symbols (Google), the Noto emoji and Noto fonts' shapes (Google), Pictogrammers Material Design Icons, where an emblem is taken from them |
+| [CC-BY-3.0.md](CC-BY-3.0.md) | Creative Commons Attribution 3.0 | game-icons.net icons, each credited to its author in NOTICE.md |
+
+A source that is not in the table is not used: a new one is added here and to NOTICE.md in the same change as the emblem that needs it.

package/NOTICE.md

@@ -0,0 +1,29 @@
+# Notice: where the art comes from
+
+The code of this package is under the MIT licence (see [LICENSE](LICENSE) and [LICENSES/MIT.txt](LICENSES/MIT.txt)). Every emblem is either drawn for this package (`source: "ours"` in `emblemInfo`) or made from one of the sources below, and each emblem made from a source has a row in the second table. The licence text of each source is in [LICENSES/](LICENSES/).
+
+No emblem carries the name, mark or logo of a league, a team, a federation or an event: the trophies, crests and balls are descriptive and generic.
+
+## The sources the art may come from
+
+| Source | What it is | Licence | Text kept in | Credit it asks for |
+| --- | --- | --- | --- | --- |
+| Material Symbols, Google (https://fonts.google.com/icons) | Icons as paths | Apache License 2.0 | [LICENSES/Apache-2.0.txt](LICENSES/Apache-2.0.txt) | None required; named here |
+| Noto Emoji and Noto Color Emoji, Google (https://github.com/googlefonts/noto-emoji) | Emoji drawings | Apache License 2.0 (the emoji; the fonts are under the SIL OFL 1.1, and none is used) | [LICENSES/Apache-2.0.txt](LICENSES/Apache-2.0.txt) | None required; named here |
+| Material Design Icons, Pictogrammers (https://pictogrammers.com/library/mdi/) | Icons as paths | Apache License 2.0 | [LICENSES/Apache-2.0.txt](LICENSES/Apache-2.0.txt) | None required; named here |
+| game-icons.net (https://game-icons.net/) | Icons by many authors | Creative Commons Attribution 3.0 | [LICENSES/CC-BY-3.0.md](LICENSES/CC-BY-3.0.md) | The author of each icon, with a link to the licence, and a note that it was changed |
+| Drawn for this package | Everything marked `ours` | MIT | [LICENSES/MIT.txt](LICENSES/MIT.txt) | None |
+
+## The emblems made from a source
+
+None yet: the two emblems the package has so far, `award:medal` and `ball:soccer`, are drawn for it, from nothing but circles, a star and the corners of an icosahedron. A row is added in the same change as the emblem, in this form:
+
+| Emblem | Made from | Author | How it was changed | Licence |
+| --- | --- | --- | --- | --- |
+
+## The demo and the docs
+
+| What | Made from | Terms |
+| --- | --- | --- |
+| The demo's page | Written for this package, with the family stylesheet `demo/family.css` | MIT |
+| The README's pictures (`docs/images`) | Taken by `scripts/screenshots.mjs` from the demo, which draws the package's own emblems | MIT |

package/README.md

@@ -1,3 +1,416 @@
-# Temporary Holding Version
+<h1 align="center">Dougu Sports <sub>道具</sub></h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center"><strong>Sports emblems as SVG strings, with optional 3D turning.</strong><br>
+Trophies, medals, crests, and the ball and gear of every sport, each one a function that returns SVG: in metal, in one line, or in flat colour, light and dark, any size, any tint. Turn one about its axis and it is another string. Each emblem is its own module, so a page that wants one ball takes one ball. MIT, with no dependencies.</p>
+
+<p align="center">
+  <a href="https://github.com/johnmorrisdotca/dougu-sports/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/johnmorrisdotca/dougu-sports/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.npmjs.com/package/@johnmorrisdotca/dougu-sports"><img alt="npm" src="https://img.shields.io/npm/v/@johnmorrisdotca/dougu-sports?color=2f5d4a"></a>
+  <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">
+</p>
+
+<p align="center"><a href="https://johnmorrisdotca.github.io/dougu-sports/"><strong>Open the demo →</strong></a> · <a href="https://johnmorrisdotca.github.io/dougu-sports/gallery.html">Gallery</a> · <a href="./docs/gallery.md">Every id</a> · <a href="./docs/turning.md">Turning</a> · <a href="./docs/layout.md">Layout</a></p>
+
+<p align="center">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/hero-desk-dark.png">
+<img alt="The package's two sample emblems, each in the three styles: a gold medal on a red ribbon, and a soccer ball, drawn in metal with gradients, as one outline, and in flat colour." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/hero-desk-light.png" width="760">
+</picture>
+</p>
+
+<table align="center">
+<tr>
+<td align="center" valign="top">
+<img alt="A soccer ball and a medal turned through five angles: the ball rolls, and the medal flips like a coin to show its plain back." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/turn-desk-light.png" width="470"><br><em>Turned: a ball rolls, a medal flips</em>
+</td>
+<td align="center" valign="top">
+<img alt="The same emblems on a phone, light." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/phone-light.png" width="200"><br><em>On a phone</em>
+</td>
+</tr>
+</table>
+
+> **Status: scaffold.** The package so far holds the machinery and two sample emblems, `award:medal` and `ball:soccer`, that stand in for the art. The trophies, medals, crests and the ball and gear of 33 sports arrive group by group ([docs/layout.md](./docs/layout.md) says where each goes), and the README's counts are read from the code, so they grow with it. Not on npm yet.
+
+## In 30 seconds
+
+```sh
+npm install @johnmorrisdotca/dougu-sports
+```
+
+```js
+import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
+
+const svg = renderEmblem("ball:soccer", { style: "color", size: 48 });
+
+console.log(svg.startsWith("<svg")); // true
+console.log(svg.includes("<title>Soccer ball</title>")); // true
+```
+
+Put the string in a page (`element.innerHTML = svg`), write it to a file, or send it from a server: it is plain SVG, with no script, no font and no network. The outline takes the page's text colour, so an emblem follows light and dark mode as the text does.
+
+## Who it is for
+
+- **Sports sites** that mark a champion, a result or a list with a trophy, a medal or a crest, without licensing a logo.
+- **Scoreboards and brackets** that want a generic emblem for a team that has no logo, tinted in the team's colour.
+- **Anyone building a game or a card** who needs a ball or a piece of gear for a sport, in one style that matches the rest.
+- **Pages that care about weight**: one emblem is one module and about 2 kB gzipped, and the package says `"sideEffects": false`.
+
+## Features
+
+- **Three styles** for every emblem: `metal` (full colour with gradients), `line` (one outline in the page's text colour) and `color` (flat fills); see [Theming](#theming).
+- **Size, tint and theme** as options: a tint recolours the main part (a medal's metal, a ball's patches), a theme sets the outline for light, dark or either.
+- **Turning**: `emblemFrame` and `ballFrame` return the emblem at an angle, in plain SVG; see [docs/turning.md](./docs/turning.md).
+- **One module per item**, so a bundler takes only what is imported; see [Use it in your project](#use-it-in-your-project).
+- **Typed ids**: `EmblemId` is a union of `award:*`, `trophy:*`, `medal:*`, `crest:*`, `ball:*`, `gear:*` and `sport:*` ids.
+- **Generic by design**: no emblem carries a league's, a team's or a federation's name or mark.
+- **Accessible**: every drawing is `role="img"` with a `<title>`; see [Accessibility](#accessibility).
+- **Deterministic**: the same id and options give the same string; a gradient's id comes from its colour.
+- **No dependencies**, ESM with types.
+
+### What's in it
+
+<table>
+<tr>
+<td align="center" valign="top"><img alt="A gold medal on a red ribbon with a star on its face, in metal, line and color." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/hero-desk-light.png" width="360"><br><em><code>award:medal</code> and <code>ball:soccer</code>, each in three styles</em></td>
+<td align="center" valign="top"><img alt="A soccer ball and a medal turned through five angles." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/turn-desk-light.png" width="360"><br><em>Turned through five angles</em></td>
+</tr>
+</table>
+
+The list of every emblem, with its names, kind, source and the import that takes it alone, is [docs/gallery.md](./docs/gallery.md), made from the built package.
+
+## Use it in your project
+
+### Install
+
+```sh
+npm install @johnmorrisdotca/dougu-sports
+# or: pnpm add @johnmorrisdotca/dougu-sports
+# or: yarn add @johnmorrisdotca/dougu-sports
+```
+
+It is ESM, and `require` works on Node 22.12 and later. It needs no DOM: the functions return strings.
+
+### Install under another name
+
+```sh
+npm install emblems@npm:@johnmorrisdotca/dougu-sports
+```
+
+```ts no-check
+import { renderEmblem } from "emblems/emblems";
+```
+
+The alias is a name in your `package.json` only: the same package, the same code.
+
+### Entry points
+
+| Import | What it holds |
+| --- | --- |
+| `@johnmorrisdotca/dougu-sports` | The full registry: every emblem by id, the functions, and each emblem as a constant |
+| `@johnmorrisdotca/dougu-sports/emblems` | `renderEmblem`, the ids and the types, with no single drawing imported by name |
+| `@johnmorrisdotca/dougu-sports/turn` | `emblemFrame` and `ballFrame` |
+| `@johnmorrisdotca/dougu-sports/award/<name>` | One award, trophy, medal, crest or sport emblem, alone (`award/medal`) |
+| `@johnmorrisdotca/dougu-sports/ball/<name>` | One ball, alone (`ball/soccer`) |
+| `@johnmorrisdotca/dougu-sports/gear/<name>` | One piece of gear, alone |
+
+### One emblem and nothing else
+
+```js
+import { BALL_SOCCER } from "@johnmorrisdotca/dougu-sports/ball/soccer";
+
+console.log(BALL_SOCCER.id); // ball:soccer
+console.log(BALL_SOCCER.svg({ size: 24 }).includes('width="24"')); // true
+```
+
+A bundler that imports this module takes the soccer ball and the small renderer for balls, and no other emblem: the package says `"sideEffects": false` and each constant is marked pure. `test/size.test.ts` bundles one item with esbuild and holds it under 3 kB gzipped; `pnpm test:package` does the same from the packed tarball.
+
+### In a page
+
+```html
+<span id="trophy"></span>
+<script type="module">
+  import { renderEmblem } from "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/dougu-sports@0/emblems";
+  document.getElementById("trophy").innerHTML = renderEmblem("award:medal", { size: 40 });
+</script>
+```
+
+### On a server
+
+```js no-run
+import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
+import { writeFileSync } from "node:fs";
+
+writeFileSync("medal.svg", renderEmblem("award:medal", { size: 256, theme: "light" }));
+```
+
+## Examples
+
+### Draw an emblem by its id
+
+An id is `<group>:<name>`. `renderEmblem` takes an id, or an id with a style after a slash.
+
+```js
+import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
+
+console.log(renderEmblem("award:medal/line") === renderEmblem("award:medal", { style: "line" })); // true
+console.log(renderEmblem("award:medal") === renderEmblem("award:medal", { style: "metal" })); // true
+```
+
+### Tint an emblem in a team's colour
+
+```js
+import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
+
+const svg = renderEmblem("ball:soccer", { style: "color", tint: "#0b6e4f" });
+console.log(svg.includes('fill="#0b6e4f"')); // true
+console.log(renderEmblem("ball:soccer", { tint: "not a colour" }) === renderEmblem("ball:soccer")); // true
+```
+
+A tint is `#rgb`, `#rrggbb` or `rgb(r, g, b)`; anything else is ignored, so a colour that comes from outside cannot reach the markup.
+
+### Choose the outline for a theme
+
+```js
+import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
+
+console.log(renderEmblem("award:medal", { theme: "dark" }).includes('color="#eef1f3"')); // true
+console.log(renderEmblem("award:medal", { theme: "light" }).includes('color="#20262d"')); // true
+console.log(renderEmblem("award:medal").includes(" color=")); // false
+```
+
+### Turn an emblem
+
+```js
+import { ballFrame, emblemFrame } from "@johnmorrisdotca/dougu-sports/turn";
+import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
+
+console.log(emblemFrame("award:medal", { yaw: 0 }) === renderEmblem("award:medal")); // true
+console.log(ballFrame("ball:soccer", { yaw: 90 }) === ballFrame("ball:soccer", { yaw: 450 })); // true
+```
+
+More in [docs/turning.md](./docs/turning.md).
+
+### Read what an emblem is
+
+```js
+import { emblemInfo, emblemName } from "@johnmorrisdotca/dougu-sports";
+
+console.log(emblemInfo("award:medal").kind); // flat
+console.log(emblemName("award:medal", "ja")); // メダル
+```
+
+### List the emblems
+
+```js
+import { EMBLEM_GROUPS, EMBLEM_IDS, SPORT_NAMES } from "@johnmorrisdotca/dougu-sports";
+
+console.log(Object.keys(EMBLEM_GROUPS).join(" ")); // award trophy medal crest ball gear sport
+console.log(EMBLEM_IDS.includes("ball:soccer")); // true
+console.log(SPORT_NAMES.length); // 33
+```
+
+### Check a string from outside
+
+```js
+import { isEmblemId, parseEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
+
+console.log(isEmblemId("ball:soccer")); // true
+console.log(parseEmblem("ball:soccer/line")?.style); // line
+console.log(parseEmblem("ball:nonesuch")); // undefined
+```
+
+### In React, Vue and the rest
+
+The functions return strings, so a framework puts them where it puts any markup: `dangerouslySetInnerHTML={{ __html: renderEmblem("award:medal") }}` in React, `v-html` in Vue, `{@html …}` in Svelte. The string holds no script and no external reference.
+
+```ts no-check
+const Medal = () => <span dangerouslySetInnerHTML={{ __html: renderEmblem("award:medal", { size: 32 }) }} />;
+```
+
+## The emblems
+
+An emblem is a small object: `id`, `en` and `ja` names, a `source` (who drew it), a `kind`, the `model` it is drawn from, and two functions, `svg(options)` and `frame(options)`.
+
+| Kind | What it is | A turn |
+| --- | --- | --- |
+| `flat` | A front and a back drawn from paths: a medal, a plaque, a rosette | Flips like a coin |
+| `ball` | Marks on a sphere: a ball | Rolls |
+| `lathe` | A body of revolution: a cup, a bowl, an urn | Keeps its outline, moves its light |
+| `icon` | One path | Is not turned |
+
+Only `flat` and `ball` exist so far; the others are named here because the art that is coming needs them.
+
+### The groups
+
+| Group | What it holds | Folder |
+| --- | --- | --- |
+| `award` | Awards: a medal on a ribbon, a crown, a star, a badge | `src/emblems/award/` |
+| `trophy` | Cups, bowls, plaques, belts, wreaths | `src/emblems/award/` |
+| `medal` | Gold, silver and bronze, and the places | `src/emblems/award/` |
+| `crest` | Generic crests, tinted by a team's colour | `src/emblems/award/` |
+| `ball` | The ball of each sport | `src/emblems/ball/` |
+| `gear` | The gear of each sport: a stick, a racket, a helmet | `src/emblems/gear/` |
+| `sport` | An icon for the sport itself | `src/emblems/award/` |
+
+The thirty-three sports the ball, gear and sport emblems are made for are `SPORT_NAMES`: NFL, CFL, IFAF, NHL, NBA, MLB, soccer, curling, tennis, volleyball, badminton, pickleball, table tennis, padel, squash, racquetball, sepak takraw, teqball, roundnet, netball, swimming, water polo, diving, artistic swimming, lacrosse, rugby, Australian football, Gaelic games, cricket, field hockey, handball, athletics and skating.
+
+## API
+
+| Function or value | What it does |
+| --- | --- |
+| `renderEmblem(ref, options?)` | An emblem as SVG. `ref` is an id, an id with a style (`"award:medal/line"`), or an emblem |
+| `emblemSvg` | The same as `renderEmblem` |
+| `emblemFrame(ref, options?)` | An emblem turned by `yaw` and `pitch` degrees |
+| `ballFrame(id, options?)` | A ball rolled; an id that is not a ball is an error |
+| `parseEmblem(value)` | The id and style a string names, or `undefined` |
+| `isEmblemId(value)`, `isBallId(value)` | Whether a value is the id of an emblem, or of a ball |
+| `emblemOf(ref)` | The emblem object a reference names |
+| `emblemInfo(id)`, `emblemName(id, language?)`, `emblemModel(id)` | What an emblem is: its names, kind and source, and the data it is drawn from |
+| `EMBLEMS` | Every emblem as markup in the metal style at 64 pixels, by id |
+| `EMBLEM_TABLE` | Every emblem object, by id |
+| `AWARD_MEDAL`, `BALL_SOCCER` | The two emblems so far, as constants |
+| `EMBLEM_IDS`, `EMBLEM_GROUPS`, `EMBLEM_FOLDERS` | Every id, the groups, and the folder of each group's art |
+| `AWARD_IDS`, `TROPHY_IDS`, `MEDAL_IDS`, `CREST_IDS`, `BALL_IDS`, `GEAR_IDS`, `SPORT_IDS` | The ids of each group |
+| `SPORT_NAMES` | The thirty-three sports |
+| `EMBLEM_STYLES`, `EMBLEM_INK`, `EMBLEM_PAGE`, `METALS` | The styles, the ink and page colours the themes use, and the metals |
+| `VERSION` | The package's version |
+
+### Options
+
+| Option | Values | Default |
+| --- | --- | --- |
+| `style` | `"metal"`, `"line"`, `"color"` | `"metal"` |
+| `size` | A number of pixels, 4096 at most | `64` |
+| `tint` | `#rgb`, `#rrggbb` or `rgb(r, g, b)` | the emblem's own colour |
+| `theme` | `"inherit"`, `"auto"`, `"light"`, `"dark"` | `"inherit"` |
+| `yaw`, `pitch` (turning only) | Degrees from the resting view | `0` |
+
+The types are `EmblemId`, `EmblemRef`, `EmblemOptions`, `FrameOptions`, `EmblemStyle`, `EmblemTheme`, `Emblem`, `EmblemInfo`, `EmblemKind`, `EmblemSource`, `EmblemGroup`, `SportName`, and the id types of each group.
+
+## Theming
+
+Every emblem is drawn with its outline in `currentColor`, so it takes the colour of the text around it. The `theme` option changes that when the SVG is used where it cannot inherit (an `<img>`, a data address):
+
+| `theme` | The outline |
+| --- | --- |
+| `inherit` | The page's text colour (`currentColor`): the default for markup put in a page |
+| `auto` | Dark ink on a light device and pale ink on a dark one, by `prefers-color-scheme` |
+| `light` | `#20262d`, made to read on `#ffffff` |
+| `dark` | `#eef1f3`, made to read on `#14181c` |
+
+The metals are `METALS` (gold `#d9a620`, silver `#aeb6c0`, bronze `#b8733a`). The `line` style has no fill, so it takes only the outline's colour.
+
+## Limits
+
+- Two sample emblems exist so far; the rest of the art is on its way (see the status note above).
+- A turn is drawn in plain SVG, not in 3D: a flat emblem is squeezed, and a ball's patches are projected points, not a lit mesh. A patch round a ball's edge is flattened against it rather than clipped to the sphere.
+- A tint is one colour. A second colour (a ribbon, a crest's band) is not an option yet.
+- The size is a number of pixels up to 4096; the drawing is a vector at any size.
+- No emblem carries a real league's, team's or federation's mark.
+
+## Accessibility
+
+- Every emblem is `role="img"` with a `<title>` that names it in English ("Medal", "Soccer ball"). `emblemName(id, "ja")` gives the Japanese name for a caller that writes its own label.
+- Where an emblem is only decoration next to text that says the same, hide it from a screen reader with `aria-hidden="true"` on the element that holds it.
+- Colour is never the only carrier of meaning: the `line` style has no colour at all.
+- The outline reads at 4.5 to 1 against the page the `light` and `dark` themes name; the tests hold the pair.
+- Nothing moves by itself: turning happens when the caller asks for a frame, and the demo's sliders are 44 pixels tall.
+
+## Browser and runtime support
+
+Any current browser, and Node 22 or later. The package is plain strings, so it also runs in Deno, Bun, a worker and an edge function. CI tests Node 22 and 24 on Linux, macOS and Windows, and the demo in Chromium and WebKit at a phone's width and a desk's.
+
+## Languages
+
+The package's own words are the emblems' names, in English (`en`) and Japanese (`ja`), read with `emblemName(id, language)`. The `<title>` inside a drawing is English. The demo's header and footer come in English and Japanese.
+
+## Roadmap
+
+- The art: trophies, medals, crests, then the ball and the gear of each of the 33 sports, group by group.
+- Bodies of revolution (`lathe`), so a cup turns with its outline kept.
+- A second colour as an option.
+- Deliberately not: logos of real leagues and teams, a canvas or WebGL renderer, and a runtime dependency.
+
+## Architecture
+
+The code is `src/emblems/`: the core (options, colours, the wrapper), the id lists, the registry, the two renderers (flat and ball) and one module per emblem; [docs/layout.md](./docs/layout.md) has the folders and how to add one. The package has no state and no clock: every function is a pure function of its arguments.
+
+## The name
+
+Dougu (道具, *dōgu*, どうぐ) is Japanese for a tool or a piece of equipment: the things a task is done with. The package is the equipment of sport, as pictures.
+
+## Where it comes from, and where it is used
+
+The emblems are drawn for this package or made from the open sources listed in [NOTICE.md](./NOTICE.md), each with its licence in [LICENSES/](./LICENSES/). It is made for [spxn.com](https://spxn.com), the historical record of the NHL, NBA, MLB, NFL and CFL, and for the other packages of the family that draw sport.
+
+### Used by
+
+[Kyogijo Stadiums](https://github.com/johnmorrisdotca/kyogijo-stadiums) draws the same kind of emblems today, inside itself; they move here, and Kyogijo then imports them.
+
+### The family
+
+<!-- family:start (made by scripts/family-readme.mjs from scripts/family-template.mjs; change those, not this) -->
+Dougu Sports is one of twenty-seven packages, each made for the same site, each at
+[github.com/johnmorrisdotca](https://github.com/johnmorrisdotca). The code of every one is MIT.
+
+- [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/).
+- [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/).
+- [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/).
+- [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/).
+- [Kazu](https://github.com/johnmorrisdotca/kazu) (数): grid number puzzles: Sudoku and its variants, Futoshiki and Skyscrapers. [Demo](https://johnmorrisdotca.github.io/kazu/).
+- [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/).
+- [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/).
+- [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/).
+- [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/).
+- [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/).
+- [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/). Not on npm yet.
+
+**This package is Dougu Sports.** The demos of all twenty-seven share one header and footer, so each links the rest.
+<!-- family:end -->
+
+## Development
+
+```sh
+pnpm install
+pnpm check          # lint, types, tests, the build and the packed package
+pnpm dev            # the demo on http://127.0.0.1:7200/
+pnpm test:demo      # the demo in a real browser
+pnpm test:readme    # the README's and the docs' examples, and docs/gallery.md
+pnpm screenshots    # retake the README's pictures
+```
+
+This package owns local ports 7200 to 7299 (see [CONTRIBUTING.md](./CONTRIBUTING.md)).
+
+## Contributing
+
+Bug reports and ideas go in the [issues](https://github.com/johnmorrisdotca/dougu-sports/issues); read [CONTRIBUTING.md](./CONTRIBUTING.md) first, and [docs/layout.md](./docs/layout.md) before adding an emblem.
+
+## Changes
+
+See [CHANGELOG.md](./CHANGELOG.md). 0.0.1 is the first preview: the name, the API and two sample emblems; the full set follows.
+
+## Credits
+
+The medal and the soccer ball are drawn for this package. Every other source is credited in [NOTICE.md](./NOTICE.md).
+
+## Licence
+
+The code, and the art drawn for this package, are [MIT](./LICENSE). Art taken from another project keeps its own licence, named in [NOTICE.md](./NOTICE.md), with its text in [LICENSES/](./LICENSES/).

package/dist/emblems/award/medal.d.ts

@@ -0,0 +1,2 @@
+/** A medal on a ribbon. Turned, it flips like a coin and shows its plain back. */
+export declare const AWARD_MEDAL: import("../emblem.core.ts").Emblem<import("../emblem.shapes.ts").FlatModel>;