@johnmorrisdotca/dougu-sports 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -6,6 +6,34 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-21
+
+The pickleballs get real holes: cut through the shell, with the inside of the ball behind them, and the page showing through where two holes line up.
+
+### Changed
+
+- **`ball:pickleball-outdoor` and `ball:pickleball-indoor` have real holes** (new module `src/emblems/ball/ball.holes.ts`, taken only by the pickleballs). Each hole on the near side is cut out of the shell by a mask, so its shading, highlight and grain are cut with it; behind it is the inside of the hollow ball (the far shell's inner surface, darker, lit low and to the right) with the far holes cut out of it, so where a near hole and a far hole line up the SVG is transparent and the page shows through, on any background. A hole is a cylinder along the line to the centre: near the edge it is a thin ellipse and the bore's wall shows as a crescent, toned by the light, and the cut edge carries a soft shadow and a thin lit rim (the thickness of the shell). It turns with `ballFrame`, `emblemFrame` and `bindTurn`; every turn has ids of its own. The line style still draws a mark for each hole, and the hole counts and sizes are unchanged (40 small, 26 large). A pickleball's drawing is about 8 kB where it was 3.7 kB (about 1.7 to 2 kB gzipped); its bundle is 8.0 kB gzipped (the other balls' are unchanged).
+- Every other ball with round marks (a golf ball's and a field hockey ball's dimples, a squash ball's dots) is drawn exactly as before: `BallSpec` gained an optional `holes` function that only the pickleballs set, and `test/holes.test.ts` holds the drawings of 0.14.0 by hash.
+
+### Added
+
+- **`docs/pickleball.md`**, with pictures of both balls at rest and turned, light and dark, and a turning picture (`pnpm animations`, scene `pickleball-turn`; `pnpm screenshots`, sheet `pickleball`). The README shows the still picture under "The best of it", and the balls sheet is redrawn with the new hole.
+- **`e2e/holes.demo.ts`**: in a real browser, a pixel seen through a near hole and the far hole behind it is transparent and equals the page's own on four page colours; the shell round a hole is solid; a turned ball shows the dark inside; a turning pickleball has open holes at some angle and a golf ball never does.
+
+## [0.14.0] - 2026-10-21
+
+The auto-turn can go either way, and the pictures and the demo are slower and wait for the pointer.
+
+### Added
+
+- **`direction` for the auto-turn**: `bindTurn(container, emblem, { direction: "clockwise" })` (seen from above; the default, `"counterclockwise"`, is how it has always turned, the front swinging to the viewer's right). `controller.setDirection(direction)` changes it while it turns without stopping it, `controller.direction()` reads it, and `turnDirection(value)` is the check the option goes through (exported from `./turn` and the main entry, with the `TurnDirection` type). `update` keeps the direction unless it names one. A drag, the keys and `setAngles` are not reversed. Tests: `test/turn-control.test.ts` and the demo's.
+
+### Changed
+
+- **README: it opens on the still pictures again** (the balls, the vintage balls, the trophies, the famous trophies and the gear, with the turned and phone pictures), as before 0.12.1. The turning pictures sit lower, each beside its own point of "The best of it" (the famous trophies, the balls, the medals and crests), never stacked.
+- **The turning pictures run at half the speed** (`pnpm animations` shows each frame 140 ms, it was 70; `DELAY=70` for the old pace).
+- **Demo: the emblem waits still and turns while the mouse is over it.** Leaving stops it where it is; a tap on a phone turns it and a second tap holds it (a drag turns it by hand as before). Auto-turn keeps it going wherever the pointer is, and `?turn=1` starts it with the page. The speed buttons are Slow 9, Medium 18 (the default, half of the old 36) and Fast 45 degrees a second; addresses with `speed=18`, `36` or `90` still mean those speeds. A **Reverse** button (`逆回転`, "reverse rotation", with the label `逆向きに回す`, "Turn the other way") turns it the other way, kept in the address as `dir=cw`. The trophy case waits still too and turns an emblem while the pointer is over it or after a tap, at 22 degrees a second (it was 45). A reader who prefers reduced motion is never turned for by the pointer. The package's own default speed (36) is unchanged.
+
 ## [0.13.0] - 2026-10-20
 
 Four combat sports get their pictograms, so a page that lists MMA, boxing, wrestling or professional wrestling no longer borrows the judo or karate suit.

package/README.md

@@ -15,29 +15,25 @@ The ball and the gear of every sport, trophies, medals, crests and the icon of e
 
 <p align="center">
 <picture>
-<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/trophies-turn-dark.webp">
-<img alt="Five famous trophies turning in 3D on royal purple, each a little behind the one before: the Stanley Cup first, then the FIFA World Cup, the Lombardi Trophy, the Larry O'Brien trophy and the Webb Ellis Cup. Each keeps its outline while its light and its handles move." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/trophies-turn-light.webp" 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 under floodlights, 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, and last 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/balls-turn-dark.webp">
-<img alt="Seven balls rolling under floodlights: a soccer ball, a basketball, a baseball, a rugby ball, a volleyball, a tennis ball and a golf ball, each turned a little differently so that the seams and panels travel across them." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/balls-turn-light.webp" width="760">
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/vintage-desk-dark.webp">
+<img alt="Eighteen more balls on a warm sunburst, in two rows of nine: five vintage leather soccer balls (hand-stitched, laced, 18 strips, 12 panels, 32 panels), a lemon-peel baseball, two baseballs stitched in two colours and an aged baseball, then nine soccer balls in the style of an era, with patterns of pentagons, leaves, a rosette, a star, a pinwheel and kites, a double border and plain white panels." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/vintage-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/flips-turn-dark.webp">
-<img alt="A gold and a silver medal, a championship banner, a crest, a hockey skate and a baseball glove flipping like coins on royal purple: each shows its face, then its edge, then its plain back." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/flips-turn-light.webp" width="760">
+<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>
 
-## The best of it
-
-- **47 famous trophies**, each a close likeness measured on a photograph and carrying no lettering, logo or mark: the Stanley Cup, the FIFA World Cup, the Lombardi Trophy, the Larry O'Brien trophy, the Grey Cup and the rest ([famous trophies](./docs/famous-trophies.md)).
-
 <p align="center">
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/famous-desk-dark.webp">
@@ -45,41 +41,66 @@ The ball and the gear of every sport, trophies, medals, crests and the icon of e
 </picture>
 </p>
 
-- **117 balls and implements in 3D**, from the 32-panel soccer ball to the pucks and the curling stone, that roll as they turn ([gallery](./docs/gallery.md), [vintage and era-style balls](./docs/vintage-balls.md)).
+<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 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.webp" width="470"><br><em>Turned: a ball rolls, a medal flips</em>
+</td>
+<td align="center" valign="top">
+<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>
+
+## The best of it
+
+- **47 famous trophies**, each a close likeness measured on a photograph and carrying no lettering, logo or mark: the Stanley Cup, the FIFA World Cup, the Lombardi Trophy, the Larry O'Brien trophy, the Grey Cup and the rest ([famous trophies](./docs/famous-trophies.md)).
 
 <p align="center">
 <picture>
-<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 under floodlights, 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, and last 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">
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/trophies-turn-dark.webp">
+<img alt="Five famous trophies turning in 3D on royal purple, each a little behind the one before: the Stanley Cup first, then the FIFA World Cup, the Lombardi Trophy, the Larry O'Brien trophy and the Webb Ellis Cup. Each keeps its outline while its light and its handles move." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/trophies-turn-light.webp" width="760">
 </picture>
 </p>
 
-- **Trophies, medals, crests and the icon of every sport**, in metal, one line or flat colour, light and dark.
+- **117 balls and implements in 3D**, from the 32-panel soccer ball to the pucks and the curling stone, that roll as they turn ([gallery](./docs/gallery.md), [vintage and era-style balls](./docs/vintage-balls.md)).
 
 <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">
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/balls-turn-dark.webp">
+<img alt="Seven balls rolling under floodlights: a soccer ball, a basketball, a baseball, a rugby ball, a volleyball, a tennis ball and a golf ball, each turned a little differently so that the seams and panels travel across them." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/balls-turn-light.webp" width="760">
 </picture>
 </p>
 
-- **70 pieces of gear**, among them the Japanese sports and budo ([Japanese sports](./docs/japanese-sports.md)).
+- **Pickleballs with real holes**: the holes are cut through the shell, so you see the dark inside of the ball and, where a near hole and a far one line up, the page itself ([pickleballs](./docs/pickleball.md)).
 
 <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">
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/pickleball-dark.webp">
+<img alt="Two pickleballs, the yellow outdoor ball with its 40 small holes above and the white indoor ball with its 26 large ones below, each at rest and at three turns: through each hole the dark inside of the ball shows, and where a hole in the near side lines up with one in the far side the background shows through." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/pickleball-light.webp" width="760">
 </picture>
 </p>
 
-- **On a phone**, and **turned by hand**: drag, arrow keys or the automatic turn ([turning](./docs/turning.md)).
+- **Trophies, medals, crests and the icon of every sport**, in metal, one line or flat colour, light and dark.
 
 <p align="center">
 <picture>
-<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">
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/flips-turn-dark.webp">
+<img alt="A gold and a silver medal, a championship banner, a crest, a hockey skate and a baseball glove flipping like coins on royal purple: each shows its face, then its edge, then its plain back." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/flips-turn-light.webp" width="760">
 </picture>
 </p>
 
+- **70 pieces of gear**, among them the Japanese sports and budo ([Japanese sports](./docs/japanese-sports.md)).
+
+- **On a phone**, and **turned by hand**: drag, arrow keys or the automatic turn ([turning](./docs/turning.md)).
+
 > **Status: preview.** 325 emblems: 71 trophies, 6 awards, 6 medals, 4 crests, a pictogram for each of the 42 sports, 117 balls and implements drawn in 3D, 8 printed pucks ([docs/pucks.md](./docs/pucks.md)), 70 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
@@ -394,9 +415,10 @@ import { TROPHY_TENNIS_CUP } from "@johnmorrisdotca/dougu-sports/trophy/tennis-c
 
 const turner = bindTurn(document.getElementById("cup"), TROPHY_TENNIS_CUP, { size: 160, speed: 36 });
 document.getElementById("spin").onclick = () => turner.togglePlay();
+turner.setDirection("clockwise"); // seen from above: the other way (the default, `"counterclockwise"`, swings the front to the viewer's right)
 ```
 
-A drag turns it, the arrow keys turn it, Space starts and stops an auto-turn, and nothing moves until you ask. Pass the emblem itself and the page carries the turning and that one emblem and nothing else (a cup and the turning are about 9 kB gzipped); pass an id, `"trophy:tennis-cup"`, and the registry is loaded when it is needed. See [docs/turning.md](./docs/turning.md).
+`direction` is `"counterclockwise"` (how it has always turned) or `"clockwise"`, and `turnDirection(value)` is the check it goes through (anything but `"clockwise"` is counterclockwise). A drag turns it, the arrow keys turn it, Space starts and stops an auto-turn, and nothing moves until you ask. Pass the emblem itself and the page carries the turning and that one emblem and nothing else (a cup and the turning are about 9 kB gzipped); pass an id, `"trophy:tennis-cup"`, and the registry is loaded when it is needed. See [docs/turning.md](./docs/turning.md).
 
 ### In React, Vue and the rest
 
@@ -645,7 +667,7 @@ Bug reports and ideas go in the [issues](https://github.com/johnmorrisdotca/doug
 
 ## Changes
 
-See [CHANGELOG.md](./CHANGELOG.md). 0.13.0 adds a pictogram for each of four combat sports, MMA (a cage), boxing (a glove), wrestling (two wrestlers on the mat) and professional wrestling (a ring with ropes), in the three styles (325 emblems); 0.12.0 adds forty-seven named trophies, each a close likeness measured on a photograph (321 emblems); 0.11.0 gives the era soccer balls neutral ids (the old ones stay as aliases), new looks and a second 1980s ball (274 emblems); 0.10.0 adds a standalone ribbon and the nets and posts of sepak takraw, netball and teqball from their rulebooks' sizes (273 emblems); 0.9.0 lets the baseball, the softball and the classic soccer balls be painted and printed: solid and two-tone colours, a logo of your own wrapped onto the ball, stamped text, an original cursive word and a small mark, all turning with the ball ([docs/custom-balls.md](./docs/custom-balls.md)); 0.8.0 makes `bindTurn` light: it takes an emblem object and then needs no registry, so a turnable cup is about 9.4 kB gzipped instead of about 81 kB, and an id loads the registry on demand; 0.7.3 turns the build, docs and picture scripts, the browser tests and the demo's source from JavaScript into TypeScript, with no change to the package; 0.7.2 makes every docs page single-language (a page in Japanese beside each page that had Japanese words in it, and a test that holds them apart), with no change to the pictures; 0.7.1 puts real countries (Canada, Japan) in the crest and puck examples in place of made-up teams, with no change to the code; 0.7.0 gives the national volleyballs layouts that tell them apart (Japan a crimson band, Poland white above and red below, the USA a navy field), strengthens the 2010-style grooved soccer ball, and adds six pictures of how the judo belt is tied, `gear:obi-step-1` to `gear:obi-step-6` (269 emblems: [docs/obi-steps.md](./docs/obi-steps.md)); 0.6.0 gives the judo suit and the karate suit their sleeves (a judogi has no short ones: they reach the wrist) and adds the judogi seen from behind with the IJF-style back number, a family name and a country code on a patch, with a `backnumber` option (269 emblems: [docs/judogi-back.md](./docs/judogi-back.md)); 0.5.1 redraws the judo suit, the belt and the football pictograms and adds the blue and folded suits and the belts of every grade (261 emblems: [docs/japanese-sports.md](./docs/japanese-sports.md)); 0.5.0 adds fifty balls: vintage leather soccer balls, era-style and shop-wall soccer balls, baseballs of other threads and volleyballs in national colours, with a `colors` option (244 emblems: [docs/vintage-balls.md](./docs/vintage-balls.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.
+See [CHANGELOG.md](./CHANGELOG.md). 0.15.0 gives the pickleballs real holes, cut through the shell and drawn with the inside of the ball behind them, so the page shows through where two holes line up ([docs/pickleball.md](./docs/pickleball.md)); 0.14.0 lets the auto-turn go either way (`direction: "clockwise"` or `"counterclockwise"`, `setDirection()`); 0.13.0 adds a pictogram for each of four combat sports, MMA (a cage), boxing (a glove), wrestling (two wrestlers on the mat) and professional wrestling (a ring with ropes), in the three styles (325 emblems); 0.12.0 adds forty-seven named trophies, each a close likeness measured on a photograph (321 emblems); 0.11.0 gives the era soccer balls neutral ids (the old ones stay as aliases), new looks and a second 1980s ball (274 emblems); 0.10.0 adds a standalone ribbon and the nets and posts of sepak takraw, netball and teqball from their rulebooks' sizes (273 emblems); 0.9.0 lets the baseball, the softball and the classic soccer balls be painted and printed: solid and two-tone colours, a logo of your own wrapped onto the ball, stamped text, an original cursive word and a small mark, all turning with the ball ([docs/custom-balls.md](./docs/custom-balls.md)); 0.8.0 makes `bindTurn` light: it takes an emblem object and then needs no registry, so a turnable cup is about 9.4 kB gzipped instead of about 81 kB, and an id loads the registry on demand; 0.7.3 turns the build, docs and picture scripts, the browser tests and the demo's source from JavaScript into TypeScript, with no change to the package; 0.7.2 makes every docs page single-language (a page in Japanese beside each page that had Japanese words in it, and a test that holds them apart), with no change to the pictures; 0.7.1 puts real countries (Canada, Japan) in the crest and puck examples in place of made-up teams, with no change to the code; 0.7.0 gives the national volleyballs layouts that tell them apart (Japan a crimson band, Poland white above and red below, the USA a navy field), strengthens the 2010-style grooved soccer ball, and adds six pictures of how the judo belt is tied, `gear:obi-step-1` to `gear:obi-step-6` (269 emblems: [docs/obi-steps.md](./docs/obi-steps.md)); 0.6.0 gives the judo suit and the karate suit their sleeves (a judogi has no short ones: they reach the wrist) and adds the judogi seen from behind with the IJF-style back number, a family name and a country code on a patch, with a `backnumber` option (269 emblems: [docs/judogi-back.md](./docs/judogi-back.md)); 0.5.1 redraws the judo suit, the belt and the football pictograms and adds the blue and folded suits and the belts of every grade (261 emblems: [docs/japanese-sports.md](./docs/japanese-sports.md)); 0.5.0 adds fifty balls: vintage leather soccer balls, era-style and shop-wall soccer balls, baseballs of other threads and volleyballs in national colours, with a `colors` option (244 emblems: [docs/vintage-balls.md](./docs/vintage-balls.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.engine.d.ts

@@ -1,4 +1,5 @@
 import { type Piece, type PieceSize, type PrintOptions, type PrintRenderer, type ResolvedOptions, type ResolvedPaint } from "./ball.core.ts";
+import type { HoleLayers } from "./ball.holes.ts";
 import { type M3, type V3 } from "./ball.math.ts";
 /** How a ball takes the light. */
 export interface Material {
@@ -121,6 +122,11 @@ export interface BallSpec {
     at?: V3;
     /** The fraction of the box's radius the ball takes (1 by default): a hammer's head is small, to leave room for its wire. */
     fit?: number;
+    /**
+     * A ball with real holes (a pickleball), drilled through its shell: each near hole is cut out and shows the inside of the ball, and where a near and a far hole line up the page shows through.
+     * It is a function (`drillHoles` in ball.holes.ts, bound to the hole centres) so that a ball without holes does not carry the code. The line style does not call it (a `draw` that wants marks there draws them).
+     */
+    holes?: (s: Surface, id: string, base: string, shape: (attrs: string) => string, minWidth: number) => HoleLayers;
     /** What is attached to the ball and sticks out of it (a hammer's wire and handle): drawn behind the ball or in front of it, by what is nearer to you. */
     attach?: (s: Surface, base: string) => {
         behind: string;

package/dist/emblems/ball/ball.engine.js

@@ -363,11 +363,13 @@ export function drawBall(title, key, spec, opts, turn, turning) {
         (gr === undefined
             ? ""
             : grainDef(id, gr.f, gr.a, gr.seed));
-    const inner = `<g clip-path="url(#${id}c)"${gr === undefined ? "" : ` filter="url(#${id}n)"`}>${shape(`fill="${ground ?? spec.ground ?? base}"`)}${layers}</g>`;
+    const hol = spec.holes?.(surface, id, base, shape, minWidth);
+    const inner = `<g clip-path="url(#${id}c)"${gr === undefined ? "" : ` filter="url(#${id}n)"`}>${shape(`fill="${ground ?? spec.ground ?? base}"`)}${layers}${hol?.edge ?? ""}</g>`;
     const metal = m.metal === true ? shape(`fill="url(#${id}m)"`) : "";
     const overlays = shape(`fill="url(#${id}d)"`) + metal + shape(`fill="url(#${id}b)"`) + shape(`fill="url(#${id}h)"`);
     const at = spec.attach?.(surface, base);
-    return wrapPiece({ title, size: opts.size, theme: opts.theme, defs: defs + metalDef(id, m.metal === true), body: `${at?.behind ?? ""}${inner}${overlays}${at?.front ?? ""}` });
+    const shell = hol?.mask === undefined ? `${inner}${overlays}` : `<g mask="url(#${hol.mask})">${inner}${overlays}</g>`;
+    return wrapPiece({ title, size: opts.size, theme: opts.theme, defs: defs + (hol?.defs ?? "") + metalDef(id, m.metal === true), body: `${at?.behind ?? ""}${hol?.behind ?? ""}${shell}${at?.front ?? ""}` });
 }
 /** A ball's label area as a surface sees it: the middle, the right-hand and the upward direction, orthogonal, and how far it reaches. */
 function homeOf(spec) {

package/dist/emblems/ball/ball.family.dotted.d.ts

@@ -2,6 +2,7 @@ import { type BallDef } from "./ball.engine.ts";
 import { type V3 } from "./ball.math.ts";
 import type { Piece } from "./ball.core.ts";
 import type { BallSpec } from "./ball.engine.ts";
+import type { Drill } from "./ball.holes.ts";
 export interface DottedOptions {
     id: string;
     en: string;
@@ -19,6 +20,8 @@ export interface DottedOptions {
     mark?: string;
     /** A lit rim on each mark (not for a dimple pattern of two hundred, which is large enough already). */
     light?: boolean;
+    /** Real holes through the shell, not marks on it (`holeLayers` from ball.holes.ts, taken by the pickleball only): the near ones are cut out and show the inside of the ball, and where two line up the page shows through. The line style still draws marks. */
+    hollow?: Drill;
     /** Turns the spread, so a ball does not show its spiral's pole straight on. */
     phase?: number;
 }

package/dist/emblems/ball/ball.family.dotted.js

@@ -13,8 +13,11 @@ export function dottedBall(o) {
         mat: o.mat,
         draw: (s, base) => {
             const mark = o.mark ?? mix(base, -0.55);
+            if (o.hollow !== undefined && !s.line)
+                return "";
             return s.dots(centres, o.radius, mark, { opacity: o.depth ?? 0.55, ink: true, light: o.light ?? true });
         },
+        holes: o.hollow === undefined ? undefined : (s, id, base, shape, minWidth) => o.hollow(s, id, { centres, radius: o.radius }, base, shape, minWidth),
     };
     return defineBall({ id: o.id, en: o.en, ja: o.ja, spec, size: o.size });
 }

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

@@ -0,0 +1,18 @@
+import type { Surface } from "./ball.engine.ts";
+import { type V3 } from "./ball.math.ts";
+/** Where a ball is drilled: the hole centres on the unit sphere, a hole's radius as the angle of its cap in radians, and the shell's thickness as a fraction of the ball's radius (0.05 by default). */
+export interface Holes {
+    centres: readonly V3[];
+    radius: number;
+    wall?: number;
+}
+/** What `holeLayers` makes: the definitions, the inside of the ball (drawn first), the edges drawn on the shell, and the mask that cuts the near holes out of everything on the shell, if there is one. */
+export interface HoleLayers {
+    defs: string;
+    behind: string;
+    edge: string;
+    mask: string | undefined;
+}
+/** The signature of `holeLayers`, which a ball is handed so that its own module is the only one that carries the code. */
+export type Drill = (s: Surface, id: string, holes: Holes, base: string, shape: (attrs: string) => string, minWidth: number) => HoleLayers;
+export declare const holeLayers: Drill;

package/dist/emblems/ball/ball.holes.js

@@ -0,0 +1,88 @@
+import { hashOf, mix, num } from "./ball.core.js";
+import { basis, ellipseOf, mul } from "./ball.math.js";
+/** The circle of the hole's bore at `depth` below the surface (0 on the outside), as the ellipse it makes on the screen; undefined where it is too thin to draw. */
+function bore(s, m, radius, depth) {
+    const [t1, t2] = basis(m);
+    const sr = Math.sin(radius), cr = Math.cos(radius) - depth;
+    const c = s.project(mul(m, cr));
+    const o = s.project([0, 0, 0]);
+    const pa = s.project(mul(t1, sr));
+    const pb = s.project(mul(t2, sr));
+    const da = [pa[0] - o[0], pa[1] - o[1]];
+    const db = [pb[0] - o[0], pb[1] - o[1]];
+    const { rx, ry, angle } = ellipseOf([[da[0], db[0], 0], [da[1], db[1], 0]]);
+    if (rx < 0.05)
+        return undefined;
+    return { x: c[0], y: c[1], rx, ry: Math.max(ry, 0.05), deg: (angle * 180) / Math.PI, ax: Math.cos(angle) * rx, ay: Math.sin(angle) * rx, facing: s.facing(m) };
+}
+const ellipse = (e) => {
+    const arcs = `a${num(e.rx)} ${num(e.ry)} ${num(e.deg, 0)} 1 0`;
+    return `M${num(e.x + e.ax)} ${num(e.y + e.ay)}${arcs}${num(-2 * e.ax)} ${num(-2 * e.ay)}${arcs}${num(2 * e.ax)} ${num(2 * e.ay)}`;
+};
+/** The light comes from the upper left, as it does everywhere else in the engine. */
+const LIGHT = [-0.62, -0.78];
+/** The tones a wall is drawn in, darkest first, as amounts of the ball's colour mixed toward black. */
+const TONES = [-0.6, -0.45, -0.3, -0.15];
+export const holeLayers = (s, id, holes, base, shape, minWidth) => {
+    const thick = holes.wall ?? 0.05;
+    const front = [];
+    const backOut = [];
+    const backIn = [];
+    for (const m of holes.centres) {
+        const f = s.facing(m);
+        if (f >= 0.08) {
+            const out = bore(s, m, holes.radius, 0);
+            if (out !== undefined)
+                front.push({ out, inn: bore(s, m, holes.radius, thick) });
+        }
+        else if (f <= -0.08) {
+            const out = bore(s, m, holes.radius, 0);
+            const inn = bore(s, m, holes.radius, thick);
+            if (out !== undefined && inn !== undefined) {
+                backOut.push(out);
+                backIn.push(inn);
+            }
+        }
+    }
+    if (front.length === 0 && backOut.length === 0)
+        return { defs: "", behind: "", edge: "", mask: undefined };
+    const frontPath = front.map((h) => ellipse(h.out)).join("");
+    const backOutPath = backOut.map(ellipse).join("");
+    const backInPath = backIn.map(ellipse).join("");
+    const key = hashOf(frontPath + "|" + backOutPath + "|" + backInPath);
+    // The inside of the ball: lit a little where the light that comes through the near holes lands (low and to the right), dark toward the edge.
+    let defs = `<radialGradient id="${id}i" cx=".62" cy=".66" r=".62"><stop offset="0" stop-color="${mix(base, -0.36)}"/><stop offset="1" stop-color="${mix(base, -0.72)}"/></radialGradient>`;
+    let disc = shape(`fill="url(#${id}i)"`);
+    if (backOut.length > 0) {
+        // A far hole is open where its inner opening and its outer opening overlap: the bore leans away from you, so a hole near the far edge is a slit.
+        defs += `<clipPath id="${id}o${key}"><path d="${backOutPath}"/></clipPath><mask id="${id}b${key}" maskUnits="userSpaceOnUse" x="0" y="0" width="100" height="100"><rect width="100" height="100" fill="#fff"/><path d="${backInPath}" fill="#000" clip-path="url(#${id}o${key})"/></mask>`;
+        disc = shape(`fill="url(#${id}i)" mask="url(#${id}b${key})"`);
+    }
+    // The wall of each near hole: what is inside the outer opening and outside the inner one (the part of the bore that faces you), toned by whether it faces the light and how near the edge it is.
+    const o = s.project([0, 0, 0]);
+    const buckets = TONES.map(() => []);
+    for (const h of front) {
+        if (h.inn === undefined)
+            continue;
+        const dx = h.out.x - o[0], dy = h.out.y - o[1];
+        const d = Math.hypot(dx, dy) || 1;
+        // The wall you see is the one on the far side of the hole, facing the middle of the ball on the screen.
+        const lit = (-dx / d) * LIGHT[0] + (-dy / d) * LIGHT[1];
+        const k = -0.3 + 0.2 * lit - 0.25 * (1 - h.out.facing);
+        let best = 0;
+        for (let i = 1; i < TONES.length; i++)
+            if (Math.abs(TONES[i] - k) < Math.abs(TONES[best] - k))
+                best = i;
+        buckets[best].push(ellipse(h.out) + ellipse(h.inn));
+    }
+    const walls = buckets.map((b, i) => (b.length === 0 ? "" : `<path d="${b.join("")}" fill="${mix(base, TONES[i])}" fill-rule="evenodd"/>`)).join("");
+    const behind = `<g clip-path="url(#${id}c)">${disc}${walls}</g>`;
+    if (front.length === 0)
+        return { defs, behind, edge: "", mask: undefined };
+    // The outline of the near holes is written once and used three times.
+    defs += `<path id="${id}f${key}" d="${frontPath}"/><mask id="${id}k${key}" maskUnits="userSpaceOnUse" x="0" y="0" width="100" height="100"><rect width="100" height="100" fill="#fff"/><use href="#${id}f${key}" fill="#000"/></mask>`;
+    // On the shell, round each cut: a soft shadow where the plastic turns in, and a thin lit edge (the cut face of the shell). Half of each stroke lies inside the cut and is masked away.
+    const edge = `<use href="#${id}f${key}" fill="none" stroke="${mix(base, -0.6)}" stroke-width="${num(Math.max(1.1, minWidth * 0.8), 2)}" opacity=".22"/>` +
+        `<use href="#${id}f${key}" fill="none" stroke="${mix(base, 0.5)}" stroke-width="${num(Math.max(0.3, minWidth * 0.3), 2)}" opacity=".5"/>`;
+    return { defs, behind, edge, mask: `${id}k${key}` };
+};

package/dist/emblems/ball/ball.pickleball.js

@@ -1,5 +1,6 @@
 // Pickleball: a perforated plastic ball. The outdoor ball has 40 small holes; the indoor ball has 26 larger ones (the rulebook gives 26 to 40 holes; the split is how balls are sold).
 import { dottedBall } from "./ball.family.dotted.js";
+import { holeLayers } from "./ball.holes.js";
 export const BALL_PICKLEBALL_OUTDOOR = /* @__PURE__ */ dottedBall({
     id: "ball:pickleball-outdoor",
     en: "Pickleball, outdoor",
@@ -11,6 +12,7 @@ export const BALL_PICKLEBALL_OUTDOOR = /* @__PURE__ */ dottedBall({
     mat: { gloss: 0.55, shade: "#4a5008", grain: { f: 1.4, a: 0.1 } },
     mark: "#454b0e",
     depth: 0.75,
+    hollow: holeLayers,
 });
 export const BALL_PICKLEBALL_INDOOR = /* @__PURE__ */ dottedBall({
     id: "ball:pickleball-indoor",
@@ -23,4 +25,5 @@ export const BALL_PICKLEBALL_INDOOR = /* @__PURE__ */ dottedBall({
     mat: { gloss: 0.6, shade: "#3a3a40", grain: { f: 1.4, a: 0.08 } },
     mark: "#3d3d44",
     depth: 0.7,
+    hollow: holeLayers,
 });

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export * from "./emblems-entry.ts";
 export { ballFrame, emblemFrame } from "./emblems/emblem.api.ts";
 export { bindTurn } from "./turn-full.ts";
-export type { TurnAngles, TurnContainer, TurnControlOptions, TurnController, TurnEvent } from "./turn-control.ts";
+export { turnDirection } from "./turn-control.ts";
+export type { TurnAngles, TurnContainer, TurnControlOptions, TurnController, TurnDirection, TurnEvent } from "./turn-control.ts";
 export { EMBLEM_TABLE } from "./emblems/emblem.registry.ts";
 export { AWARD_MEDAL } from "./emblems/award/medal.ts";
 export { AWARD_BADGE } from "./emblems/award/badge.ts";

package/dist/index.js

@@ -3,6 +3,7 @@
 export * from "./emblems-entry.js";
 export { ballFrame, emblemFrame } from "./emblems/emblem.api.js";
 export { bindTurn } from "./turn-full.js";
+export { turnDirection } from "./turn-control.js";
 export { EMBLEM_TABLE } from "./emblems/emblem.registry.js";
 export { AWARD_MEDAL } from "./emblems/award/medal.js";
 export { AWARD_BADGE } from "./emblems/award/badge.js";

package/dist/turn-control.d.ts

@@ -8,6 +8,13 @@ export interface TurnRegistry {
     renderEmblem(ref: EmblemRef, options?: FrameOptions): string;
     emblemFrame(ref: EmblemRef, options?: FrameOptions): string;
 }
+/**
+ * Which way the auto-turn goes, seen from above. `"counterclockwise"` is how it has always turned: the front swings to the viewer's right. `"clockwise"` is the other way: the front swings to the viewer's left.
+ * A drag, the arrow keys and `setAngles` are not reversed.
+ */
+export type TurnDirection = "clockwise" | "counterclockwise";
+/** A direction from anything: `"clockwise"` is clockwise, and everything else is the default, `"counterclockwise"`. */
+export declare function turnDirection(value: unknown): TurnDirection;
 /** The three angles of a turn, in degrees. */
 export interface TurnAngles {
     /** About the vertical axis, from -180 (excluded) to 180. */
@@ -34,6 +41,8 @@ export interface TurnControlOptions extends FrameOptions {
     autoPlay?: boolean | "force";
     /** Degrees of yaw each second the auto-turn advances (36 by default; negative turns the other way). */
     speed?: number;
+    /** Which way the auto-turn goes (`"counterclockwise"`, the way it has always turned, by default). `update` keeps the direction unless it names one; a negative `speed` reverses it. */
+    direction?: TurnDirection;
     /** When true (the default), a drag holds the auto-turn while the pointer is down, and an arrow key, Home or `setAngles` pauses it. When false nothing but `pause()` stops it. */
     pauseOnInteract?: boolean;
     /** Called with `true` when the auto-turn starts and `false` when it stops, whatever stopped it. */
@@ -60,6 +69,10 @@ export interface TurnController {
     play(): boolean;
     /** Stops the auto-turn. */
     pause(): void;
+    /** Which way the auto-turn goes. */
+    direction(): TurnDirection;
+    /** Changes which way the auto-turn goes, at once and without stopping it. */
+    setDirection(direction: TurnDirection): void;
     /** Starts or stops the auto-turn and gives the new state; `false` for an emblem that cannot turn. */
     togglePlay(): boolean;
     /** Removes the listeners and the attributes and styles `bindTurn` added; the last drawing stays. */

package/dist/turn-control.js

@@ -1,3 +1,7 @@
+/** A direction from anything: `"clockwise"` is clockwise, and everything else is the default, `"counterclockwise"`. */
+export function turnDirection(value) {
+    return value === "clockwise" ? "clockwise" : "counterclockwise";
+}
 const WORDS = {
     en: { role: "turnable emblem", hint: "Drag, or use the arrow keys, to turn it. Space starts and stops the turning." },
     ja: { role: "回せるエンブレム", hint: "ドラッグするか矢印キーで回せます。スペースキーで自動回転を始めたり止めたりできます。" },
@@ -63,6 +67,7 @@ export function bindTurnWith(registry, container, ref, options = {}) {
     let range = [-60, 60];
     let keyStep = 5;
     let speed = 36;
+    let way = turnDirection(options.direction);
     let pauseOnInteract = true;
     let locale = "en";
     let onTurn;
@@ -86,12 +91,14 @@ export function bindTurnWith(registry, container, ref, options = {}) {
         range = low <= high ? [low, high] : [high, low];
         keyStep = clamp(finite(o.keyStep, 5), 0.5, 90);
         speed = clamp(finite(o.speed, 36), -720, 720);
+        if (o.direction !== undefined)
+            way = turnDirection(o.direction);
         pauseOnInteract = o.pauseOnInteract !== false;
         locale = o.locale === "ja" ? "ja" : "en";
         onTurn = typeof o.onTurn === "function" ? o.onTurn : undefined;
         onPlayChange = typeof o.onPlayChange === "function" ? o.onPlayChange : undefined;
         const rest = { ...o };
-        for (const name of ["sensitivity", "pitchRange", "keyStep", "onTurn", "autoPlay", "speed", "pauseOnInteract", "onPlayChange", "yaw", "pitch", "roll"])
+        for (const name of ["sensitivity", "pitchRange", "keyStep", "onTurn", "autoPlay", "speed", "direction", "pauseOnInteract", "onPlayChange", "yaw", "pitch", "roll"])
             delete rest[name];
         frame = rest;
     };
@@ -156,7 +163,7 @@ export function bindTurnWith(registry, container, ref, options = {}) {
         const dt = last === undefined ? 0 : clamp((time - last) / 1000, 0, 0.1);
         last = time;
         if (!held && dt > 0) {
-            place({ yaw: angles.yaw + speed * dt });
+            place({ yaw: angles.yaw + (way === "clockwise" ? -1 : 1) * speed * dt });
             draw();
             onTurn?.(copy());
         }
@@ -378,6 +385,12 @@ export function bindTurnWith(registry, container, ref, options = {}) {
             if (pending === undefined)
                 draw();
         },
+        direction() {
+            return way;
+        },
+        setDirection(next) {
+            way = turnDirection(next);
+        },
         play() {
             if (!turnable || destroyed)
                 return false;

package/dist/turn-entry.d.ts

@@ -1,4 +1,4 @@
 export { ballFrame, emblemFrame } from "./emblems/emblem.api.ts";
 export type { FrameOptions } from "./emblems/emblem.core.ts";
-export { bindTurn } from "./turn-control.ts";
-export type { TurnAngles, TurnContainer, TurnControlOptions, TurnController, TurnEvent } from "./turn-control.ts";
+export { bindTurn, turnDirection } from "./turn-control.ts";
+export type { TurnAngles, TurnContainer, TurnControlOptions, TurnController, TurnDirection, TurnEvent } from "./turn-control.ts";

package/dist/turn-entry.js

@@ -1,4 +1,4 @@
 // The turning entry point: an emblem at an angle. `emblemFrame` turns any emblem about its vertical axis and tilts it; `ballFrame` rolls a ball. Each frame is plain SVG, so a turn is a loop over
 // the angle, drawn by the caller (a slider, a requestAnimationFrame, a CSS-free animation).
 export { ballFrame, emblemFrame } from "./emblems/emblem.api.js";
-export { bindTurn } from "./turn-control.js";
+export { bindTurn, turnDirection } from "./turn-control.js";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.13.0";
+export declare const VERSION = "0.15.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.13.0";
+export const VERSION = "0.15.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/dougu-sports",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Dougu Sports 道具, sports emblems as SVG strings: trophies, medals, crests, sport icons, and the ball and gear of every sport, in metal, line or flat colour, with optional 3D turning. Light and dark, accessible, tree-shakeable. Zero dependencies.",
   "keywords": [
     "sports",