@johnmorrisdotca/dougu-sports 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,30 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-14
+
+Printed pucks: eight souvenir pucks with a print on the top face that turns with the puck, and a `face` option that takes any picture, emblem or flag code. 194 emblems.
+
+### Added
+
+- **Eight printed pucks** ([docs/pucks.md](docs/pucks.md), [日本語](docs/pucks.ja.md)), a new group `puck:*`: `puck:canada` (our own flag of the Canadian pattern with CANADA under it in wide letters, in a ring of words), `puck:canada-red` (a red face with a big white leaf), `puck:canada-white` (a white face with red bands and a red leaf), `puck:usa` (a disc of stars and stripes with USA lettered across it), `puck:usa-navy` (a navy face, a red ring between white hairlines, stars and USA), `puck:player` (a made-up surname and a big number, like a jersey), `puck:signed` (the navy puck with a made-up gold signature) and `puck:souvenir` (a generic one with ring text from the caller). Each is the same puck as `ball:puck` (76.2 by 25.4 mm), in true 3D: the print sits on the top face and turns with the puck, foreshortens as it tips, and is gone when the top is turned away; the grip shows on the rim. `ball:puck` itself stays plain.
+- **A `face` option** on every puck (`renderEmblem`, `emblemFrame`, `ballFrame`): `design`, `image` (any SVG, made safe first), `emblem` (a dougu id), `flag` (`"ca"` and `"us"` are drawn here; any other code goes through the caller's `flags(code, { shape, size, theme })`, the shape of the renderer hata exports), `text`, `ringText`, `number`, `name`, `signature` (a seed, or `false`) and `colors`. `ball:puck` given a face is drawn as `puck:souvenir` with it. New exports: `PUCK_IDS`, the `PUCK_*` constants and the types `PuckFace`, `PuckDesign`, `FaceColors`, `FlagRenderer` and `PuckId`; `isBallId`, `ballFrame` and `lineup` take the puck ids.
+- **Our own lettering**: a stroke alphabet (adapted from senshu-jerseys, no font file), wide, heavy and leaning a little, set on a line or on an arc for the ring, with a made-up signature drawn by a seeded pen (the same seed, the same stroke, never a real hand) and our own eleven-point maple leaf, flags and stars.
+- **A safe image path**: an outside SVG is taken apart and put back through a strict allow-list (shapes, gradients and clip paths; no script, style, text, image, use, foreignObject, filter, link or event handler), with its ids renamed under the puck's own prefix.
+- A "Print a puck" section in the demo, both gallery pages list the eight, and tests for the face, escaping, the signature, the safe image, the turn box and the proportions (the printed pucks are measured against the rule like the plain one).
+
+### Changed
+
+- The stack renderer has an `overlay` that is drawn over the grain when the top face is toward you, and the puck's drawing is shared (`puckSpec`), so the plain puck's output is unchanged.
+
+## [0.3.2] - 2026-10-14
+
+The README pictures fill their frames: balls first, then trophies, then gear, each a full grid.
+
+### Changed
+
+- **README pictures are full grids.** The opening picture is now thirty-six balls and pucks in four full rows of nine, followed by one of trophies, medals and crests and one of gear (each light and dark), then a turn strip of four rows of seven and a phone shot of twelve emblems. No row is ragged and there is no empty band. They are webp (made in the browser by `pnpm screenshots`, about 60 to 400 kB each) instead of png.
+
 ## [0.3.1] - 2026-10-14
 
 Nothing is cut off when an emblem turns: every cup and the pieces that were clipped at rest now draw inside their box at every angle.
@@ -108,7 +132,9 @@ First preview: the name, the API and two sample emblems. The full set of trophie
 - 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.3.1...HEAD
+[Unreleased]: https://github.com/johnmorrisdotca/dougu-sports/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/johnmorrisdotca/dougu-sports/compare/v0.3.2...v0.4.0
+[0.3.2]: https://github.com/johnmorrisdotca/dougu-sports/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/johnmorrisdotca/dougu-sports/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/johnmorrisdotca/dougu-sports/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/johnmorrisdotca/dougu-sports/compare/v0.2.0...v0.2.1

package/NOTICE.md

@@ -8,6 +8,7 @@ No emblem carries the name, mark or logo of a league, a team, a federation or an
 
 - The trophies, medals, crests, awards and sport pictograms are drawn in SVG by hand in a simplified, generic form. No real trophy, medal, logo, mark or engraving was copied or traced, and no photograph was traced (photographs were looked at, never copied).
 - The balls (`src/emblems/ball/`) are drawn by this package's own code: a rotation, a projection and our own geometry (a seam curve, the truncated icosahedron, a layout of curved panels, a fitted basketball channel).
+- The printed pucks (`puck:*`, `src/emblems/ball/ball.puck.print.ts`) are our own drawings: the maple leaf, the flags of the Canadian and United States patterns and the stars are drawn from simple geometry, the lettering is a stroke alphabet adapted from the block letters of the author's own senshu-jerseys (same author, same MIT licence, no font file), and the signature is made by a seeded pen, so it is no real person's. Photographs of souvenir pucks were looked at for what such a puck shows (a flag, a name, a number, a signature, a ring of words) and nothing was copied or traced. No team's or league's logo or wordmark, no maker's mark and no real player's name is used.
 - The gear (`src/emblems/gear/`) is drawn by us from a list of parts (a path, a colour, how it reads as a line); the bow, the arrow and the other tapering shapes are made by a small function of ours (`swell`), and the rest are paths written for this package.
 - The Japanese words for the Japanese items are the ones the sports' governing bodies use in their own rules and equipment lists (kendo, judo, kyudo and karate federations and the sumo association); the bodies' names and marks are not used in any id, title or drawing.
 

package/README.md

@@ -1,7 +1,7 @@
 <h1 align="center">Dougu Sports <sub>道具</sub></h1>
 
 <p align="center"><strong>Sports emblems as SVG strings, with optional 3D turning.</strong><br>
-Trophies, medals, crests, the icon of every sport, and the ball and gear of the sports, each one a function that returns SVG: in polished 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 trophy takes one trophy. MIT, with no dependencies.</p>
+The ball and the gear of every sport, trophies, medals, crests and the icon of every sport, each one a function that returns SVG: in polished 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 trophy takes one trophy. 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>
@@ -15,23 +15,37 @@ Trophies, medals, crests, the icon of every sport, and the ball and gear of the
 
 <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="Ten trophies drawn in metal, each a generic form that stands for a league's cup: a tall banded silver cup, a ring of gold pennants round a baseball, a football on a three-sided stand, a basketball over a net, a wide two-handled bowl on a tall base, a globe held up by spiral figures, a gilt dish, a lidded cup with a pineapple, a terracotta urn and a gilded lidded cup. Below them gold, silver and bronze medals, crests, a rosette, a wreath and a belt, and one cup in the three styles." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/hero-desk-light.png" width="760">
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/balls-desk-dark.webp">
+<img alt="Thirty-six balls and pucks drawn in 3D, in four rows of nine: soccer balls of several constructions and colours, then basketball, the 3x3 ball, baseball, softball, a football, a rugby ball, an Australian football and two volleyballs, then tennis, padel, pickleball with its holes, squash with its two dots, racquetball, golf, red and pink cricket and water polo, then sepak takraw, a shuttlecock, a puck, a curling stone, lacrosse, handball, table tennis, a sliotar and a roundnet ball." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/balls-desk-light.webp" width="760">
+</picture>
+</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.webp">
+<img alt="Trophies, medals and crests, in four rows of nine: nine famous cups, then a gilded cup, a phoenix-handle cup, a soccer ball trophy, a wreath, a rosette, a belt, a banner, a ring and a plaque, then three medals, three place badges and three crests, and last three cups each in metal, line and colour." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/hero-desk-light.webp" width="760">
+</picture>
+</p>
+
+<p align="center">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/gear-desk-dark.webp">
+<img alt="Thirty-six pieces of gear in four rows of nine: hockey stick and skate, a goalie mask, field hockey, lacrosse and hurling sticks, a cricket bat and wicket, a baseball bat and glove, a football helmet and goalposts, a basketball hoop, a volleyball net, rackets and paddles, a curling broom, skates, swim goggles, starting blocks, a baton, a javelin, a hurdle, and the kendo, sumo, judo, kyudo and karate gear of Japan." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/gear-desk-light.webp" width="760">
 </picture>
 </p>
 
 <table align="center">
 <tr>
 <td align="center" valign="top">
-<img alt="A two-handled cup, a banded cup, a medal and a soccer ball each turned through five angles: the cups keep their outline and move their light and handles, the medal flips like a coin to show its plain back, and the ball rolls." 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>
+<img alt="A two-handled cup, a medal, a soccer ball and a championship banner each turned through seven angles: the cup keeps its outline and moves its light and handles, the medal and the banner flip like a coin to show their plain backs, and the ball rolls." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/turn-desk-light.webp" 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>
+<img alt="Cups, a medal, balls and gear on a phone, three to a row." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/phone-light.webp" width="200"><br><em>On a phone</em>
 </td>
 </tr>
 </table>
 
-> **Status: preview.** 186 emblems: 24 trophies, 5 awards, 6 medals, 4 crests, a pictogram for each of the 38 sports, 66 balls and implements drawn in 3D, 42 pieces of gear (among them the Japanese sports and budo, [docs/japanese-sports.md](./docs/japanese-sports.md)) and a championship pennant; [docs/layout.md](./docs/layout.md) says where each goes. All of it is drawn for this package: no art is copied from another project.
+> **Status: preview.** 194 emblems: 24 trophies, 5 awards, 6 medals, 4 crests, a pictogram for each of the 38 sports, 66 balls and implements drawn in 3D, 8 printed pucks ([docs/pucks.md](./docs/pucks.md)), 42 pieces of gear (among them the Japanese sports and budo, [docs/japanese-sports.md](./docs/japanese-sports.md)) and a championship pennant; [docs/layout.md](./docs/layout.md) says where each goes. All of it is drawn for this package: no art is copied from another project.
 
 ## In 30 seconds
 
@@ -59,6 +73,7 @@ Put the string in a page (`element.innerHTML = svg`), write it to a file, or sen
 
 ## Features
 
+- **Equipment first (道具 is the word for it)**: 66 balls and implements drawn in 3D, from the 32-panel soccer ball to the 26, 18, 14, 12 and 6 panel constructions, futsal, beach soccer and the pucks and stones, each with its official size, 8 printed pucks (a flag, a leaf, stars and stripes, a player's number, a made-up signature, your own picture: [docs/pucks.md](./docs/pucks.md)), and 42 pieces of gear (sticks, rackets, helmets, skates, nets, and the Japanese budo kit) drawn to match; see [docs/gallery.md](./docs/gallery.md).
 - **Three styles** for every emblem: `metal` (polished metal: a gradient, a highlight and a soft rim of reflected light, edged in a darker tone of its own metal, with no heavy outline), `line` (one clean outline in the page's text colour, made to read at 14 pixels) and `color` (flat fills); see [Theming](#theming).
 - **Size, tint, accent and theme** as options: a tint recolours the main part (a medal's metal, a crest's colour, a ball's patches), an accent the second colour (a ribbon, a crest's band, the pennants), a theme sets the ink for light, dark or either.
 - **Turning**: `emblemFrame` and `ballFrame` return the emblem at an angle, in plain SVG: every emblem turns, a ball rolls, a cup keeps its outline and moves its light, and everything flat (gear, a bat, a crown, a sport's icon) flips like a coin; `bindTurn` lets a drag, the arrow keys or an auto-turn do the turning in a page; see [docs/turning.md](./docs/turning.md).
@@ -78,8 +93,8 @@ Put the string in a page (`element.innerHTML = svg`), write it to a file, or sen
 
 <table>
 <tr>
-<td align="center" valign="top"><img alt="Ten trophies, medals and crests, and one cup in the three styles." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/hero-desk-light.png" width="360"><br><em>Trophies, medals and crests, and one cup in three styles</em></td>
-<td align="center" valign="top"><img alt="Cups, a medal and a ball 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>
+<td align="center" valign="top"><img alt="Balls and pucks in four rows of nine." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/balls-desk-light.webp" width="360"><br><em>Balls and pucks, trophies, medals and gear</em></td>
+<td align="center" valign="top"><img alt="A cup, a medal, a ball and a banner turned through seven angles." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/turn-desk-light.webp" width="360"><br><em>Turned through seven angles</em></td>
 </tr>
 </table>
 
@@ -276,7 +291,7 @@ console.log(emblemName("medal:gold", "ja")); // 金メダル
 ```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 pennant
+console.log(Object.keys(EMBLEM_GROUPS).join(" ")); // award trophy medal crest ball puck gear sport pennant
 console.log(EMBLEM_IDS.includes("ball:soccer")); // true
 console.log(SPORT_NAMES.length); // 38
 ```
@@ -393,6 +408,7 @@ An emblem is a small object: `id`, `en` and `ja` names, a `source` (who drew it)
 | `medal` | Gold, silver and bronze medals on a ribbon of five stripes, and a badge for each of the first three places | `src/emblems/medal/` |
 | `crest` | Four generic crests, tinted by a team's colours, with its letters | `src/emblems/crest/` |
 | `ball` | 66 balls and implements, in 3D, each with its official size: soccer (in 32, 26, 18, 14, 12 and 6 panels, in three colourways, with futsal and beach soccer; [docs/soccer-balls.md](./docs/soccer-balls.md)), basketball, baseball, tennis, rugby, the footballs, golf, the puck, the curling stone and the rest | `src/emblems/ball/` |
+| `puck` | 8 printed pucks: the same puck with a print on its top face that turns with it (a flag and CANADA, a red leaf, stars and stripes, a player's name and number, a made-up signature, a souvenir), and a `face` option for any picture, emblem or flag code; [docs/pucks.md](./docs/pucks.md) | `src/emblems/ball/ball.puck.print.ts` |
 | `gear` | 42 pieces of equipment: sticks, rackets, skates, a glove, a helmet, nets and posts, a javelin, starting blocks, and for the Japanese sports a war fan, a sumo belt, a bamboo sword, a kendo helmet, a judo suit, a belt, a long bow, an arrow and a karate suit | `src/emblems/gear/` |
 | `sport` | One pictogram for each of the thirty-eight sports | `src/emblems/sport/` |
 | `pennant` | A felt championship pennant on a dowel, with a stitched edge, lettered with its words and its year | `src/emblems/pennant/` |
@@ -426,7 +442,7 @@ The thirty-eight sports the ball, gear and sport emblems are made for are `SPORT
 | `EMBLEM_TABLE` | Every emblem object, by id |
 | `TROPHY_HOCKEY_CUP`, `MEDAL_GOLD`, `CREST_SHIELD`, `SPORT_NHL`, `BALL_SOCCER`, `GEAR_HURLEY`... | Each emblem as a constant, named by its id in capitals (`trophy:hockey-cup`); [docs/gallery.md](./docs/gallery.md) ([日本語](./docs/gallery.ja.md)) lists every emblem and states the rule for its constant and the module that takes it alone |
 | `EMBLEM_IDS`, `EMBLEM_GROUPS`, `EMBLEM_FOLDERS`, `EMBLEM_ALIASES` | Every id, the groups, the folder of each group's art, and the short names (`cup` for `trophy:cup`) |
-| `AWARD_IDS`, `TROPHY_IDS`, `MEDAL_IDS`, `CREST_IDS`, `BALL_IDS`, `GEAR_IDS`, `SPORT_IDS`, `PENNANT_IDS` | The ids of each group |
+| `AWARD_IDS`, `TROPHY_IDS`, `MEDAL_IDS`, `CREST_IDS`, `BALL_IDS`, `PUCK_IDS`, `GEAR_IDS`, `SPORT_IDS`, `PENNANT_IDS` | The ids of each group |
 | `MEDAL_KINDS`, `CREST_SHAPES` | The kinds of medal, and the shapes of crest |
 | `SPORT_NAMES` | The thirty-eight sports |
 | `JAPANESE_IDS` | The ids of the Japanese sports and budo, together: sumo, kendo, judo, kyudo and karate, with their trophies and gear ([docs/japanese-sports.md](./docs/japanese-sports.md)) |
@@ -577,7 +593,7 @@ Bug reports and ideas go in the [issues](https://github.com/johnmorrisdotca/doug
 
 ## Changes
 
-See [CHANGELOG.md](./CHANGELOG.md). 0.3.0 adds nineteen soccer balls (26, 18, 14, 12 and 6 panels, winter orange and high-visibility yellow, futsal and beach soccer: 186 emblems); 0.2.1 draws every ball and implement to the rulebook's proportions; 0.2.0 is 167 emblems, every one drawn here, with the Japanese sports, engraving, a turn for every emblem and the compose helpers; 0.1.0 brought the first full set of 148; 0.0.1 was the first preview.
+See [CHANGELOG.md](./CHANGELOG.md). 0.4.0 adds eight printed pucks and a `face` option (194 emblems: [docs/pucks.md](./docs/pucks.md)); 0.3.0 adds nineteen soccer balls (26, 18, 14, 12 and 6 panels, winter orange and high-visibility yellow, futsal and beach soccer: 186 emblems); 0.2.1 draws every ball and implement to the rulebook's proportions; 0.2.0 is 167 emblems, every one drawn here, with the Japanese sports, engraving, a turn for every emblem and the compose helpers; 0.1.0 brought the first full set of 148; 0.0.1 was the first preview.
 
 ## Credits
 

package/dist/emblems/ball/ball.art.d.ts

@@ -0,0 +1,24 @@
+/** A maple leaf with a stem, as a path about the origin: the blade spans -1 to 1 across and from -1 down to about 0.6, the stem to 1. */
+export declare const LEAF_PATH: string;
+/** A maple leaf: centre (`cx`, `cy`), the width of the blade `w`, and a fill. */
+export declare function leaf(cx: number, cy: number, w: number, fill: string): string;
+/** A five-point star, as a polygon's points, with the given outer radius, centred on (`cx`, `cy`), pointing up (turned by `deg`). */
+export declare function starPoints(cx: number, cy: number, r: number, deg?: number): string;
+export declare const star: (cx: number, cy: number, r: number, fill: string, deg?: number) => string;
+/** The colours of the two flags: a red and a white, a navy and a red. Plain values of the flags' colours; the caller may replace them. */
+export declare const FLAG: {
+    readonly red: "#d52b1e";
+    readonly white: "#ffffff";
+    readonly navy: "#0a3161";
+    readonly usRed: "#b31942";
+};
+/** A flag of Canada's pattern, 2 wide and 1 tall about the origin scaled to the width `w`: red, white, red, with the leaf on the white. */
+export declare function canadaFlag(cx: number, cy: number, w: number, red?: "#d52b1e", white?: "#ffffff"): string;
+/**
+ * The stars and stripes as a rectangle about the origin, `w` wide and `h` tall: thirteen stripes across, a canton of stars in the upper left (`canton` wide, seven stripes tall), and the stars in staggered rows, four
+ * and three to a row, which is what reads at a puck's size (the flag has fifty, in nine rows). A star whose centre lies farther than `reach` from the origin is left out, so a disc cut from the field has no
+ * half stars at its edge.
+ */
+export declare function starsAndStripes(w: number, h: number, canton: number, reach?: number, red?: string, white?: string, blue?: string): string;
+/** A flag of the United States' pattern, 2 wide about the origin scaled to the width `w` (it is 1.9 to 1): stripes and a canton of stars. */
+export declare function usaFlag(cx: number, cy: number, w: number): string;

package/dist/emblems/ball/ball.art.js

@@ -0,0 +1,67 @@
+// The small drawings a printed puck is made of, all our own: an eleven-point maple leaf, a five-point star, a Canadian-style flag (red, white, red, with that leaf) and the stars and stripes. Each is a string of SVG in
+// a unit box (the leaf's blade is 2 wide and 2 tall about the origin) that the face scales and places; the flags take the width they are drawn at. Imports only the core's number writer.
+import { num } from "./ball.core.js";
+/** The right half of the leaf, from the top tip down to the stem: eleven points in all with the left half mirrored (a tip, then a notch, five times over). y runs down. */
+const LEAF_HALF = [
+    [0, -1], [0.15, -0.6], [0.36, -0.7], [0.33, -0.36], [0.67, -0.5], [0.55, -0.2], [1, -0.12], [0.74, 0.12], [0.86, 0.36], [0.4, 0.3], [0.42, 0.56], [0.06, 0.42],
+];
+/** A maple leaf with a stem, as a path about the origin: the blade spans -1 to 1 across and from -1 down to about 0.6, the stem to 1. */
+export const LEAF_PATH = (() => {
+    const right = LEAF_HALF.slice(1);
+    const left = [...LEAF_HALF.slice(1)].reverse().map(([x, y]) => [-x, y]);
+    const pts = [LEAF_HALF[0], ...right, [0.06, 0.92], [-0.06, 0.92], ...left];
+    return `M${pts.map(([x, y]) => `${num(x, 3)} ${num(y, 3)}`).join("L")}Z`;
+})();
+/** A maple leaf: centre (`cx`, `cy`), the width of the blade `w`, and a fill. */
+export function leaf(cx, cy, w, fill) {
+    const k = w / 2;
+    return `<path d="${LEAF_PATH}" transform="translate(${num(cx, 3)} ${num(cy, 3)}) scale(${num(k, 4)})" fill="${fill}"/>`;
+}
+/** A five-point star, as a polygon's points, with the given outer radius, centred on (`cx`, `cy`), pointing up (turned by `deg`). */
+export function starPoints(cx, cy, r, deg = 0) {
+    const pts = [];
+    for (let i = 0; i < 10; i++) {
+        const a = ((deg + i * 36) * Math.PI) / 180;
+        const rr = i % 2 === 0 ? r : r * 0.382;
+        pts.push(`${num(cx + rr * Math.sin(a), 3)} ${num(cy - rr * Math.cos(a), 3)}`);
+    }
+    return pts.join(" ");
+}
+export const star = (cx, cy, r, fill, deg = 0) => `<polygon points="${starPoints(cx, cy, r, deg)}" fill="${fill}"/>`;
+/** The colours of the two flags: a red and a white, a navy and a red. Plain values of the flags' colours; the caller may replace them. */
+export const FLAG = { red: "#d52b1e", white: "#ffffff", navy: "#0a3161", usRed: "#b31942" };
+/** A flag of Canada's pattern, 2 wide and 1 tall about the origin scaled to the width `w`: red, white, red, with the leaf on the white. */
+export function canadaFlag(cx, cy, w, red = FLAG.red, white = FLAG.white) {
+    const k = w / 2;
+    const t = `translate(${num(cx, 3)} ${num(cy, 3)}) scale(${num(k, 4)})`;
+    return `<g transform="${t}"><rect x="-1" y="-.5" width="2" height="1" fill="${white}"/><rect x="-1" y="-.5" width=".5" height="1" fill="${red}"/><rect x=".5" y="-.5" width=".5" height="1" fill="${red}"/><path d="${LEAF_PATH}" transform="translate(0 -.03) scale(.3)" fill="${red}"/></g>`;
+}
+/**
+ * The stars and stripes as a rectangle about the origin, `w` wide and `h` tall: thirteen stripes across, a canton of stars in the upper left (`canton` wide, seven stripes tall), and the stars in staggered rows, four
+ * and three to a row, which is what reads at a puck's size (the flag has fifty, in nine rows). A star whose centre lies farther than `reach` from the origin is left out, so a disc cut from the field has no
+ * half stars at its edge.
+ */
+export function starsAndStripes(w, h, canton, reach = Infinity, red = FLAG.usRed, white = FLAG.white, blue = FLAG.navy) {
+    const x0 = -w / 2, y0 = -h / 2, sh = h / 13;
+    let out = `<rect x="${num(x0, 3)}" y="${num(y0, 3)}" width="${num(w, 3)}" height="${num(h, 3)}" fill="${white}"/>`;
+    for (let i = 0; i < 13; i += 2)
+        out += `<rect x="${num(x0, 3)}" y="${num(y0 + i * sh, 3)}" width="${num(w, 3)}" height="${num(sh, 3)}" fill="${red}"/>`;
+    const ch = sh * 7;
+    out += `<rect x="${num(x0, 3)}" y="${num(y0, 3)}" width="${num(canton, 3)}" height="${num(ch, 3)}" fill="${blue}"/>`;
+    const r = Math.min(canton / 9.5, ch / 15);
+    for (let row = 0; row < 7; row++) {
+        const n = row % 2 === 0 ? 4 : 3;
+        for (let c = 0; c < n; c++) {
+            const x = x0 + canton * ((row % 2 === 0 ? c + 0.5 : c + 1) / 4);
+            const y = y0 + ch * ((row + 0.5) / 7);
+            if (Math.hypot(x, y) <= reach)
+                out += star(x, y, r, white);
+        }
+    }
+    return out;
+}
+/** A flag of the United States' pattern, 2 wide about the origin scaled to the width `w` (it is 1.9 to 1): stripes and a canton of stars. */
+export function usaFlag(cx, cy, w) {
+    const k = w / 2;
+    return `<g transform="translate(${num(cx, 3)} ${num(cy, 3)}) scale(${num(k, 4)})">${starsAndStripes(2, 2 / 1.9, 0.8)}</g>`;
+}

package/dist/emblems/ball/ball.core.d.ts

@@ -1,3 +1,4 @@
+import type { PuckFace } from "./ball.face.ts";
 /** `metal` (also written `colour`): full colour, with shading. `line`: one outline in `currentColor`. */
 export type PieceStyle = "metal" | "colour" | "color" | "line";
 /** `inherit` (the default): the page's text colour. `auto`: dark ink on a light device and pale ink on a dark one. `light` and `dark` force one. */
@@ -18,6 +19,8 @@ export interface PieceOptions {
     locale?: "en" | "ja";
     /** A string is the `<title>` (escaped); `false` drops it and marks the drawing `aria-hidden="true"`. */
     title?: string | false;
+    /** A puck: the print on its top face (see `PuckFace`). The printed pucks (`puck:*`) take it, and so does `ball:puck` through `renderEmblem`, `emblemFrame` and `ballFrame`. Anything else ignores it. */
+    face?: PuckFace;
 }
 /** A turn: `yaw` degrees about the vertical axis (0 is the default view), `pitch` the tilt toward you, `roll` the turn about the line of sight. */
 export interface BallFrameOptions extends PieceOptions {
@@ -85,6 +88,9 @@ export interface ResolvedOptions {
     tint: string | undefined;
     accent: string | undefined;
     grain: boolean | undefined;
+    face: PuckFace | undefined;
+    /** A string that tells two faces apart, for the ids of a drawing. */
+    faceKey: string;
 }
 export declare function resolveOptions(o: PieceOptions | undefined): ResolvedOptions;
 /** The ink of a drawing when a theme sets it, and the page it is made to read on. */

package/dist/emblems/ball/ball.core.js

@@ -42,12 +42,23 @@ export function hashOf(text) {
         h = Math.imul(h ^ text.charCodeAt(i), 16777619);
     return (h >>> 0).toString(36);
 }
+/** What tells one face from another: its plain data (a renderer is a function, and only its name goes in). */
+function faceKeyOf(face) {
+    if (typeof face !== "object" || face === null)
+        return "";
+    try {
+        return JSON.stringify(face, (k, v) => (typeof v === "function" ? `fn:${v.name}` : v)) ?? "";
+    }
+    catch {
+        return "?";
+    }
+}
 export function resolveOptions(o) {
     const size = typeof o?.size === "number" && Number.isFinite(o.size) && o.size > 0 ? Math.min(Math.round(o.size * 100) / 100, 4096) : 64;
     const theme = o?.theme === "auto" || o?.theme === "light" || o?.theme === "dark" ? o.theme : "inherit";
     const tint = readColour(o?.tint);
     const accent = readColour(o?.accent);
-    return { style: o?.style === "line" ? "line" : "colour", size, theme, tint: tint === undefined ? undefined : hexOf(tint), accent: accent === undefined ? undefined : hexOf(accent), grain: typeof o?.grain === "boolean" ? o.grain : undefined };
+    return { style: o?.style === "line" ? "line" : "colour", size, theme, tint: tint === undefined ? undefined : hexOf(tint), accent: accent === undefined ? undefined : hexOf(accent), grain: typeof o?.grain === "boolean" ? o.grain : undefined, face: typeof o?.face === "object" && o.face !== null ? o.face : undefined, faceKey: faceKeyOf(o?.face) };
 }
 /** The ink of a drawing when a theme sets it, and the page it is made to read on. */
 export const PIECE_INK = { light: "#20262d", dark: "#eef1f3" };

package/dist/emblems/ball/ball.face.d.ts

@@ -0,0 +1,54 @@
+/** The designs a face starts from. */
+export type PuckDesign = "canada" | "canada-red" | "canada-white" | "usa" | "usa-navy" | "player" | "souvenir";
+/** What the renderer a caller supplies for a flag is asked: the code, the shape (`"4:3"`, `"1:1"` or `"round"`, the shapes hata draws), a size in pixels and the theme. It returns an SVG document. */
+export type FlagRenderer = (code: string, options: {
+    shape: "4:3" | "1:1" | "round";
+    size: number;
+    theme: "light" | "dark" | "auto" | "inherit";
+}) => string;
+/** The colours of a face, by name. The array form is the same list in this order: field, ring, ink, accent, signature. */
+export interface FaceColors {
+    /** The disc's own colour. */
+    field?: string;
+    /** The ring round the edge, where the face has one. */
+    ring?: string;
+    /** The lettering on the ring, and the main lettering on a dark face. */
+    ink?: string;
+    /** The second colour: the leaf, a number's fill, the stars. */
+    accent?: string;
+    /** The marker of a signature. */
+    signature?: string;
+}
+/**
+ * The print on a puck's top face. Everything is optional, and what is not given comes from the design (the puck's own id says which, or `design`). Text is cleaned (no control characters, 24 letters a line) and
+ * drawn in our own vector lettering, so any letter, digit or `- . , ' / : &` is available and any other character is left out.
+ */
+export interface PuckFace {
+    /** The design to start from. A puck with an id of its own already has one; `puck:souvenir` and `ball:puck` take it from here. */
+    design?: PuckDesign;
+    /** Any SVG: a logo, a crest, a drawing. Made safe first (see `safeImage`): shapes, gradients and clip paths only. It is fitted into the middle of the face and replaces the design's own picture. */
+    image?: string;
+    /** A country code (`"ca"` and `"us"` are drawn by this package; another needs `flags`). It replaces the design's own picture. */
+    flag?: string;
+    /** A renderer for the flag codes this package does not draw: `(code, { shape, size, theme }) => svg`, the shape of the function hata exports. */
+    flags?: FlagRenderer;
+    /** The id of a dougu emblem (`"trophy:cup"`, `"sport:nhl"`), drawn small in the middle. Resolved by `renderEmblem`, `emblemFrame` and `ballFrame`. */
+    emblem?: string;
+    /** The words under the picture (`"CANADA"`), one line. */
+    text?: string;
+    /** The words round the edge. A string is set on the top; a pair is the top and the bottom; `false` leaves the ring out. */
+    ringText?: string | readonly [string, string] | false;
+    /** A big number, like a jersey's. Up to three characters. */
+    number?: string | number;
+    /** A surname, set on the ring like a jersey's name. */
+    name?: string;
+    /** A seed for a made-up signature, or `false` for none. A number or any text; the same seed always draws the same squiggle, and no seed is a real person's hand. */
+    signature?: number | string | false;
+    /** The colours: by name, or as an array in the order field, ring, ink, accent, signature. A colour is `#rgb`, `#rrggbb` or `rgb()`; anything else is ignored. */
+    colors?: FaceColors | readonly (string | undefined)[];
+}
+/** The face of a design, in the face's units (a disc of radius 1, up is up): its definitions and its drawing. `prefix` makes every id unique to this puck. */
+export declare function faceMarkup(face: PuckFace | undefined, design: PuckDesign, own: PuckFace | undefined, prefix: string): {
+    defs: string;
+    body: string;
+};