@johnmorrisdotca/taisen-brackets 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,33 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-14
+
+### Added
+
+- **`background`**: a poster background under a bracket or a road chart. A preset's name draws one of **twenty-five**, each drawn in code (gradients, radial glows, patterns, bezier bands, markings) in a dark and a light variant, deterministic and at most 6 kB: `midnight`, `crimson`, `royal`, `emerald`, `pitch`, `ice`, `hardwood`, `infield`, `turf`, `ball-panels`, `swirl`, `waves`, `glow`, `floodlights`, `confetti`, `carbon`, `aurora`, `sunburst`, `chevrons`, `halftone`, `argyle`, `contour`, `stardust`, `mesh` and `spotlight`. Five read as the sport's playing surface: soccer's mowing stripes and markings, hockey's scratched ice with its centre circle, lines and faceoff spots, basketball's planks and court, baseball's grass, dirt and base paths, football's turf, yard lines and end zones. The text, lines, boxes, marks and accent take the colours that read over each (4.5 to 1 against the background's dominant colours, a test over every preset, both variants and every size, and over colours of your own, with a veil where a mid-tone ground needs one). With `theme: "auto"` both variants are drawn and the stylesheet shows the one that fits the page. [docs/backgrounds.md](docs/backgrounds.md).
+- **`background: { preset, colors, angle, intensity, seed, theme }`** tunes a preset, and **`background: { image, fit, dim, theme }`** draws a picture of your own as an `<image>` under a veil (`cover` or `contain`, 0 to 1 deep); the address must be http(s), relative or `data:image/…` (anything else throws), and is escaped. An unknown preset or a bad value throws a `RangeError` that names it. `roadToFinal` takes the same option. The default, the look's plain colour, is drawn exactly as before.
+- **`src/family-backgrounds.ts`**, the drawing of the twenty-five as one dependency-free file that other packages of the family copy byte for byte: `backgroundSvg(preset, { width, height, theme, colors, angle, intensity, seed, id }) => { defs, body, ink }`, `BACKGROUND_PRESETS`, `contrastRatio`, `FAMILY_BACKGROUNDS_VERSION`. Its sha256 and version are held by `test/family-backgrounds.test.ts`; it is also the `/backgrounds` entry point. The copy rule is in docs/backgrounds.md.
+- **Seed tags**: `seeds: true` in the road look writes a small tag (`C1`, `WC2`, `P3`) beside each mark, from the new `Matchup.seeds`, else the new `Team.tag`, else the number `Team.seed`; in a box of marks alone it sits above the mark.
+- **`codes`** and **`vs`** for a bracket's road look: a team's three letters under its mark, and a "v" between the two marks of a box of marks alone.
+- **A team with no flag or logo is a tile** in the road look: a rounded square with its abbreviation, filled with the team's `color` (white or near-black letters, whichever reads) or neutral.
+- **`flagHref(code)`**: a flag as an address to load, for pages that cannot afford an inline flag of 80 kB twice; tried where `flags` gives none, written once as a symbol. **Every `mark` address** is now written once as a symbol and used wherever the team appears, instead of a long `<image href>` per use.
+- **`tieClass(tie)`**: a class word for a tie's group, so that a page's own style can highlight or dim ties (a division); only words of letters, digits, `-` and `_` are kept.
+- The demo has a background picker (all twenty-five as swatches, your own colours, an image read in the browser and never uploaded), a gallery of the twenty-five on the sports they suit, and opens every example on the background of its sport. NHL 2024 carries its seed tags.
+- `pnpm images` redoes every picture of `docs/images` in one command, the two grids of the twenty-five included; `pnpm test:readme` checks that every picture the README and the docs name exists. [docs/roadmap.md](docs/roadmap.md) and [docs/references.md](docs/references.md): what is planned (new layouts and a group-stage table for 0.6.0) and the pictures that prompted it, as mood only.
+
+### Fixed
+
+- **Marks, text and round names stuck out of their boxes**, in every size and both looks: in a tall bracket's boxes of marks the score under the marks was not counted when the marks were sized, so the flags crossed the box's top and bottom (Croatia and Japan in the round of 16 on a phone); a shoot-out's score ("1 (3)") crowded the next team's, and now sits beside the score where it fits the column, or under it. A box of marks is laid out as a stack (tag, mark, letters, score, shoot-out) and the marks are made as large as the whole stack allows. Bold text was measured as regular; it is now measured bold, so a name no longer runs under a score or the word "bye".
+- **The names of the rounds met the connector lines.** In a tall bracket the lines now turn at the edge of the box they leave and the names stand on their own strip between the rounds, each moved along it to a place the lines do not cross, set a little smaller and on a snugger pill where the room is tight. (On a phone a round of eight or more boxes across leaves no room: the name then stands over the lines on its own pill.)
+- **Round names were cut with an ellipsis** in a wide column ("Conference Quarterfi…"): a name is set smaller, down to 8, and then on two lines, on a taller pill (road) or two lines of text (classic), and the strip over the boxes grows to hold them. A name is cut only as a last resort.
+- `test/geometry.test.ts` measures every drawing's marks, text, pills and lines from the markup and asserts all of this for every example, size and look.
+
+### Changed
+
+- The demo's default view is the road look on the background that suits each sport. A bracket's classic look is unchanged apart from the fixes above.
+- The README's pictures are regenerated (JPEG, to keep the repository small) with the new backgrounds and the fixed boxes.
+
 ## [0.4.0] - 2026-10-14
 
 ### Added

package/NOTICE.md

@@ -25,3 +25,5 @@ The code of this package is under the MIT licence (see [LICENSE](LICENSE)). The
 The flags in the demo are for the nations of the World Cups of 2022 and 2026: `AR AT AU BA BE BR CA CD CH CI CO CV DE DZ EC EG ES FR GB-ENG GH HR JP KR MA MX NL NO PL PT PY SE SN US ZA`. The package itself ships no flag, no logo and no data of the leagues.
 
 No code, text or picture was taken from the bracket libraries compared in [docs/compare.md](docs/compare.md); that page records what each says of itself.
+
+**Backgrounds.** The twenty-five backgrounds (`src/family-backgrounds.ts`) are drawn in code from gradients, patterns and paths and are original work, MIT-licensed with the package; none is traced from, or copies, anyone's artwork, logo, trophy or photograph, and no image file is used. The pictures of other brackets that inspired the design are listed, as mood only, in docs/references.md; nothing of them is in the package. The NHL 2024 seed tags in the demo (C1, WC2, P3, A1, M2 and so on) are the divisional places and wild cards of that season's playoff field, as the league names them.

package/README.md

@@ -11,22 +11,22 @@ Give it the games, series, two-legged ties or replays of a tournament and it wor
   <img alt="TypeScript" src="https://img.shields.io/badge/types-TypeScript-3178c6">
 </p>
 
-<p align="center"><a href="https://johnmorrisdotca.github.io/taisen-brackets/"><strong>Open the demo →</strong></a> · <a href="./docs/layout.md">Layout</a> · <a href="./docs/drawing.md">Drawing</a> · <a href="./docs/road.md">Road to the final</a> · <a href="./docs/formats.md">Formats</a> · <a href="./docs/compare.md">How it compares</a></p>
+<p align="center"><a href="https://johnmorrisdotca.github.io/taisen-brackets/"><strong>Open the demo →</strong></a> · <a href="./docs/layout.md">Layout</a> · <a href="./docs/drawing.md">Drawing</a> · <a href="./docs/road.md">Road to the final</a> · <a href="./docs/backgrounds.md">Backgrounds</a> · <a href="./docs/formats.md">Formats</a> · <a href="./docs/compare.md">How it compares</a></p>
 
 <p align="center">
 <picture>
-<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/hero-desk-dark.png">
-<img alt="The 2022 World Cup knockout: two halves of eight teams meeting at the final in the centre, with Argentina's round flag and the word Champion above it and the third-place match below. Each box has both teams' round flags, abbreviations and scores, with penalties in brackets." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/hero-desk-light.png" width="720">
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/hero-desk-dark.jpg">
+<img alt="The 2022 World Cup knockout: two halves of eight teams meeting at the final in the centre, with Argentina's round flag and the word Champion above it and the third-place match below. Each box has both teams' round flags, abbreviations and scores, with penalties in brackets." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/hero-desk-light.jpg" width="720">
 </picture>
 </p>
 
 <table align="center">
 <tr>
 <td align="center" valign="top">
-<img alt="The poster look: the 2026 World Cup knockout of 32 nations as round flags on dark navy joined by gold lines, Spain's flag in the centre above the word Champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/poster-desk.png" width="470"><br><em>The poster look: flags only, gold on navy (the 2026 World Cup).</em>
+<img alt="The poster look: the 2026 World Cup knockout of 32 nations as round flags on dark navy joined by gold lines, Spain's flag in the centre above the word Champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/poster-desk.jpg" width="470"><br><em>The poster look: flags only, gold on navy (the 2026 World Cup).</em>
 </td>
 <td align="center" valign="top">
-<img alt="The 2022 World Cup on a phone: the champion at the top, then the rounds as rows, the first round at the top and at the bottom, the final in the middle, and the third-place match at the foot." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/phone-light.png" width="190"><br><em>On a phone the rounds are rows.</em>
+<img alt="The 2022 World Cup on a phone: the champion at the top, then the rounds as rows, the first round at the top and at the bottom, the final in the middle, and the third-place match at the foot." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/phone-light.jpg" width="190"><br><em>On a phone the rounds are rows.</em>
 </td>
 </tr>
 </table>
@@ -37,22 +37,22 @@ One layout draws them all, each from real results: the demo has a picker for the
 
 <table>
 <tr>
-<td align="center" valign="top"><img alt="The 2024 NHL playoffs: Western and Eastern conferences, best-of-seven series, Florida Panthers as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/nhl-desk-light.png" width="360"><br><em>NHL 2024, series</em></td>
-<td align="center" valign="top"><img alt="The 1984 Stanley Cup playoffs: the Campbell and Wales conferences, a best-of-five first round, Edmonton Oilers as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/nhl1984-desk-light.png" width="360"><br><em>NHL 1984, an older era</em></td>
-<td align="center" valign="top"><img alt="The 2024 NBA playoffs: sixteen teams in two conferences, Boston Celtics as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/nba-desk-light.png" width="360"><br><em>NBA 2024</em></td>
+<td align="center" valign="top"><img alt="The 2024 NHL playoffs: Western and Eastern conferences, best-of-seven series, Florida Panthers as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/nhl-desk-light.jpg" width="360"><br><em>NHL 2024, series</em></td>
+<td align="center" valign="top"><img alt="The 1984 Stanley Cup playoffs: the Campbell and Wales conferences, a best-of-five first round, Edmonton Oilers as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/nhl1984-desk-light.jpg" width="360"><br><em>NHL 1984, an older era</em></td>
+<td align="center" valign="top"><img alt="The 2024 NBA playoffs: sixteen teams in two conferences, Boston Celtics as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/nba-desk-light.jpg" width="360"><br><em>NBA 2024</em></td>
 </tr>
 <tr>
-<td align="center" valign="top"><img alt="The 2022 MLB postseason: byes for the top two seeds of each league, Houston Astros as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/byes-desk-light.png" width="360"><br><em>MLB 2022, byes</em></td>
-<td align="center" valign="top"><img alt="The playoffs of the 2024 NFL season: single games, byes for the top seed of each conference, the Super Bowl at the centre, Philadelphia Eagles as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/nfl-desk-light.png" width="360"><br><em>NFL 2024 season, the Super Bowl</em></td>
-<td align="center" valign="top"><img alt="The 2024 CFL playoffs: division semi-finals and finals, byes, the Grey Cup at the centre, Toronto Argonauts as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/cfl-desk-light.png" width="360"><br><em>CFL 2024, the Grey Cup</em></td>
+<td align="center" valign="top"><img alt="The 2022 MLB postseason: byes for the top two seeds of each league, Houston Astros as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/byes-desk-light.jpg" width="360"><br><em>MLB 2022, byes</em></td>
+<td align="center" valign="top"><img alt="The playoffs of the 2024 NFL season: single games, byes for the top seed of each conference, the Super Bowl at the centre, Philadelphia Eagles as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/nfl-desk-light.jpg" width="360"><br><em>NFL 2024 season, the Super Bowl</em></td>
+<td align="center" valign="top"><img alt="The 2024 CFL playoffs: division semi-finals and finals, byes, the Grey Cup at the centre, Toronto Argonauts as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/cfl-desk-light.jpg" width="360"><br><em>CFL 2024, the Grey Cup</em></td>
 </tr>
 <tr>
-<td align="center" valign="top"><img alt="The 2022 World Cup knockout stage." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/hero-desk-light.png" width="360"><br><em>World Cup 2022</em></td>
-<td align="center" valign="top"><img alt="The 1938 World Cup: replays." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/replays-desk-light.png" width="360"><br><em>World Cup 1938, replays</em></td>
-<td align="center" valign="top"><img alt="The 2026 World Cup as a flags-only poster, in Japanese." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/poster-desk-ja.png" width="360"><br><em>World Cup 2026 poster, in Japanese</em></td>
+<td align="center" valign="top"><img alt="The 2022 World Cup knockout stage." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/hero-desk-light.jpg" width="360"><br><em>World Cup 2022</em></td>
+<td align="center" valign="top"><img alt="The 1938 World Cup: replays." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/replays-desk-light.jpg" width="360"><br><em>World Cup 1938, replays</em></td>
+<td align="center" valign="top"><img alt="The 2026 World Cup as a flags-only poster, in Japanese." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/poster-desk-ja.jpg" width="360"><br><em>World Cup 2026 poster, in Japanese</em></td>
 </tr>
 <tr>
-<td align="center" valign="top"><img alt="The 2024 MLS Cup Playoffs: a wild card match, a best-of-three round one, then single matches to the MLS Cup, LA Galaxy as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/mls-desk-light.png" width="360"><br><em>MLS 2024, best of three</em></td>
+<td align="center" valign="top"><img alt="The 2024 MLS Cup Playoffs: a wild card match, a best-of-three round one, then single matches to the MLS Cup, LA Galaxy as champion." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/mls-desk-light.jpg" width="360"><br><em>MLS 2024, best of three</em></td>
 <td></td>
 <td></td>
 </tr>
@@ -64,17 +64,53 @@ One layout draws them all, each from real results: the demo has a picker for the
 
 <table>
 <tr>
-<td align="center" valign="top"><img alt="The 2022 World Cup in the road look, wide: large round flags, big bold scores, the loser quiet, the rounds on pills, and Argentina's path to the final as a dotted line." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/path-desk-light.png" width="460"><br><em>The road look, wide, with Argentina's path.</em></td>
-<td align="center" valign="top"><img alt="The 2022 World Cup in the road look on a card, 1080 by 1350: the champion at the top, then the rounds as rows." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/card-light.png" width="260"><br><em>A card, 1080 by 1350.</em></td>
-<td align="center" valign="top"><img alt="The road to the final of the 2022 World Cup on a phone in the dark: Argentina and France as large flags, and each one's matches with the score between the two flags." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/road-phone-dark.png" width="190"><br><em>The road to the final, on a phone.</em></td>
+<td align="center" valign="top"><img alt="The 2022 World Cup in the road look, wide: large round flags, big bold scores, the loser quiet, the rounds on pills, and Argentina's path to the final as a dotted line." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/path-desk-light.jpg" width="460"><br><em>The road look, wide, with Argentina's path.</em></td>
+<td align="center" valign="top"><img alt="The 2022 World Cup in the road look on a card, 1080 by 1350: the champion at the top, then the rounds as rows." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/card-light.jpg" width="260"><br><em>A card, 1080 by 1350.</em></td>
+<td align="center" valign="top"><img alt="The road to the final of the 2022 World Cup on a phone in the dark: Argentina and France as large flags, and each one's matches with the score between the two flags." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/road-phone-dark.jpg" width="190"><br><em>The road to the final, on a phone.</em></td>
 </tr>
 <tr>
-<td align="center" valign="top"><img alt="The same bracket in the classic look, which stays the default." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/classic-desk-light.png" width="460"><br><em>The classic look, still the default.</em></td>
-<td align="center" valign="top"><img alt="The road to the final of the 2024 Stanley Cup playoffs: Florida and Edmonton, each one's three series with the games won between the two logos." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/road-wide-nhl-light.png" width="460"><br><em>The road to the final, a play-off (NHL 2024).</em></td>
-<td align="center" valign="top"><img alt="The road to the final of the 2022 World Cup on a card." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/road-card-light.png" width="260"><br><em>The road to the final, a card.</em></td>
+<td align="center" valign="top"><img alt="The same bracket in the classic look, which stays the default." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/classic-desk-light.jpg" width="460"><br><em>The classic look, still the default.</em></td>
+<td align="center" valign="top"><img alt="The road to the final of the 2024 Stanley Cup playoffs: Florida and Edmonton, each one's three series with the games won between the two logos." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/road-wide-nhl-light.jpg" width="460"><br><em>The road to the final, a play-off (NHL 2024).</em></td>
+<td align="center" valign="top"><img alt="The road to the final of the 2022 World Cup on a card." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/road-card-light.jpg" width="260"><br><em>The road to the final, a card.</em></td>
 </tr>
 </table>
 
+## Backgrounds
+
+`background` draws a poster background under the bracket: a gradient, a glow, a pattern or the markings of a playing surface, all drawn in code, each in a dark and a light variant. The text, the lines, the boxes and the marks take the colours that read over it. The plain colour stays the default.
+
+<p align="center">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/backgrounds-dark.jpg">
+<img alt="The twenty-five backgrounds in a grid of five by five, each behind a different bracket: midnight, crimson, royal, emerald, pitch, ice, hardwood, infield, turf, ball-panels, swirl, waves, glow, floodlights, confetti, carbon, aurora, sunburst, chevrons, halftone, argyle, contour, stardust, mesh and spotlight." src="https://raw.githubusercontent.com/johnmorrisdotca/taisen-brackets/main/docs/images/backgrounds-light.jpg" width="900">
+</picture>
+</p>
+
+The twenty-five: `midnight`, `crimson`, `royal`, `emerald`, `pitch` (soccer), `ice` (hockey), `hardwood` (basketball), `infield` (baseball), `turf` (football), `ball-panels`, `swirl`, `waves`, `glow`, `floodlights`, `confetti`, `carbon`, `aurora`, `sunburst`, `chevrons`, `halftone`, `argyle`, `contour`, `stardust`, `mesh` and `spotlight`. [docs/backgrounds.md](./docs/backgrounds.md) says what each is.
+
+```js
+import { drawBracket } from "@johnmorrisdotca/taisen-brackets";
+
+const ties = [
+  { sides: ["VAN", "NSH"], score: [4, 3], round: 1, seeds: ["P1", "WC2"] },
+  { sides: ["EDM", "LAK"], score: [1, 2], round: 1, seeds: ["P2", "P3"] },
+  { sides: ["VAN", "LAK"], score: [2, 1], round: 2 },
+];
+
+// A preset by name; with `theme: "auto"` (the default) both variants are drawn and the page's own light or dark shows the right one.
+const ice = drawBracket(ties, { look: "road", background: "ice", seeds: true });
+
+// A preset, tuned: your own colours, the angle, how strong the pattern is, a seed for the scattered parts.
+const mine = drawBracket(ties, { look: "road", theme: "dark", background: { preset: "swirl", colors: ["#10203a", "#3a1060", "#ff7ac8", "#6ae0ff"], angle: 135, intensity: 0.8 } });
+
+// Your own picture, under a veil (http(s), relative or data:image/ only).
+const photo = drawBracket(ties, { look: "road", theme: "dark", background: { image: "stadium.jpg", fit: "cover", dim: 0.55 } });
+
+console.log(ice.includes("tb-bgd"), mine.includes("#ff7ac8"), photo.includes('<image href="stadium.jpg"')); // true true true
+```
+
+In the road look, `seeds: true` writes a small tag (`P1`, `WC2`) beside each team's mark, `codes: true` its three letters under the mark in a box of marks, `vs: true` a "v" between the two marks, and a team with no flag or logo is a tile with its letters. [docs/backgrounds.md](./docs/backgrounds.md) has the options, the contrast rules and the module the other packages of the family share.
+
 ## In 30 seconds
 
 ```sh
@@ -110,6 +146,9 @@ Put the string in a page (`element.innerHTML = svg`), write it to a file, or sen
 - **Wide, square, card, phone**: 1200 by 675, 1080 by 1080, 1080 by 1350 (a tall post), or 390 wide and as tall as it needs; the rounds are columns, or rows on a phone and a card. Boxes show names and scores, abbreviations, or only the marks, whichever fits.
 - **The road look**: `look: "road"` draws large round flags or crests, big bold scores with the loser's quiet, the rounds named on pills, and, for one team, its path through the bracket as a dotted line. It is the look of the road-to-the-final chart below, and every other option works with it.
 - **The road to the final**: `roadToFinal` draws the two finalists of the tournament you already have, with the ties each played on the way and the score between their flags, on a card, a square, wide or a phone.
+- **Poster backgrounds**: twenty-five, drawn in code, each in a dark and a light variant, among them the playing surfaces of hockey, basketball, baseball, football and soccer; your own colours, or your own picture; and the text, lines and boxes take the colours that read over them (4.5 to 1, held by a test).
+- **Seed tags, codes and a "vs"** in the road look, and a team with no picture drawn as a tile with its letters, so that nothing looks missing.
+- **Nothing sticks out**: marks, text and round names stay inside their boxes and off the connector lines, in every size and both looks, held by a geometry test.
 - **A link on every box**: `href: (tie, side?) => address` makes each tie's box (or each team's row) a real `<a>` in the SVG with an accessible name.
 - **Flags from a plug-in**: a team's `flag` code is drawn by the `flags` function you pass (Hata's round flags are one line), with no dependency added.
 - **Light, dark, poster**: every colour is a CSS custom property with a fallback, so the drawing follows the page's `prefers-color-scheme` or `data-theme` and can be restyled from outside.
@@ -131,7 +170,7 @@ npm install @johnmorrisdotca/taisen-brackets
 # or: yarn add @johnmorrisdotca/taisen-brackets
 ```
 
-It is ESM, and `require` works on Node 22.12 and later. It needs no DOM: the functions return strings. Four entry points: `@johnmorrisdotca/taisen-brackets` (everything), `/layout` (the layout and the helpers, no drawing), `/presets` (the formats) and `/road` (the road to the final).
+It is ESM, and `require` works on Node 22.12 and later. It needs no DOM: the functions return strings. Five entry points: `@johnmorrisdotca/taisen-brackets` (everything), `/layout` (the layout and the helpers, no drawing), `/presets` (the formats), `/road` (the road to the final) and `/backgrounds` (the twenty-five backgrounds on their own).
 
 ## Examples
 
@@ -465,7 +504,7 @@ The string is built from your data, with every name escaped; do not put untruste
 
 Everything is exported from `@johnmorrisdotca/taisen-brackets`; the layout part from `/layout`, the formats from `/presets`. The types are in the package; each function's doc comment has its details.
 
-- `drawBracket(input, options?)`: the SVG string. `input` is a list of matchups, `{ matchups, teams }` or a layout. Options: `size`, `orientation`, `shape`, `detail`, `theme`, `background`, `title`, `subtitle`, `roundNames`, `roundLabels`, `scores`, `seeds`, `markShape`, `champion`, `trophy`, `emblems`, `emblemStyle`, `emblemTint`, `thirdPlace`, `winnerHighlight`, `look`, `href`, `highlightPath`, `flags`, `locale`, `words`, `teamName`, `groupOrder`, `id`, `className`.
+- `drawBracket(input, options?)`: the SVG string. `input` is a list of matchups, `{ matchups, teams }` or a layout. Options: `size`, `orientation`, `shape`, `detail`, `theme`, `background` (a preset's name, a tuned preset or your own picture), `vs`, `codes`, `title`, `subtitle`, `roundNames`, `roundLabels`, `scores`, `seeds`, `markShape`, `champion`, `trophy`, `emblems`, `emblemStyle`, `emblemTint`, `thirdPlace`, `winnerHighlight`, `look`, `href`, `tieClass`, `highlightPath`, `flags`, `flagHref`, `locale`, `words`, `teamName`, `groupOrder`, `id`, `className`.
 - `roadToFinal(input, options?)`: the road to the final of a tournament or of two finalists: `{ options, title, summary, totals, draw(extra?), table(options?) }`. `input` is what `drawBracket` takes, or the two finalists with their paths. Options: `team`, `title`, `subtitle`, `final`, `labels`, `groupLabel`, `size`, `winner`, `codes`, `endnote`, and `locale`, `words`, `teamName`, `roundNames`, `markShape`, `flags`, `theme`, `background`, `id`, `className` as for `drawBracket`. The types `RoadChart`, `RoadFinalist`, `RoadMatch`, `RoadOptions` and the rest are exported too; it is also the one export of `/road`.
 - `layoutBracket(input, options?)`: the rounds, halves, rows, byes and results, without drawing. `shape: "ltr"` and `groupOrder` are its options.
 - `bracketTable(input, options?)`: the HTML table.
@@ -478,6 +517,7 @@ Everything is exported from `@johnmorrisdotca/taisen-brackets`; the layout part
 - `roundName(remaining)`, `roundNamesFor(count)`, `roundLabel(layout, round, names, words)`: round names.
 - `LOCALES`, `LOCALE_CODES`, `defineLocale`, `localeOf`, `voiceOf`, `countryName`: the languages (see Languages), a language of your own, the formats and the names of countries from `Intl`. `localizedLayout(layout, voice)` is a layout with the team names in a language.
 - `SIZES`, `THEMES`, `ROAD_THEMES`, `WORDS`, `VERSION`: the sizes (`wide`, `square`, `card`, `phone`), the looks' colours, the road look's extra colours, the English words, the version.
+- `BACKGROUND_PRESETS`, `backgroundSvg(preset, options)`, `contrastRatio(a, b)`, `resolveBackground(option, theme, width, height, prefix)`, `FAMILY_BACKGROUNDS_VERSION`: the twenty-five backgrounds, one drawn on its own with the ink that reads over it, the contrast of two colours, the `background` option read, and the version of the file shared with the family (see "Backgrounds"). Also its own entry point, `/backgrounds`.
 - `cleanSvg(markup)`, `safeUrl(url)`, `safeHref(url)`, `abbreviate(name)`: the rules for marks and for the addresses of links, and the short name made from a name. The types `FlagRenderer`, `FlagRequest` and `FlagShape` are the flags plug-in's (see "Flags from a plug-in").
 
 ## Languages
@@ -566,6 +606,7 @@ Any current browser, and Node 22 or later. The package makes no network request
 - More languages (Portuguese, Italian, Korean, Chinese), and native review of the Spanish and German words.
 - A custom element and a React helper, as in the other packages of the family.
 - A PNG renderer (through an optional peer).
+- Planned for 0.6.0: new layouts (`rows`, `shields`, `update`, `columns`, `play-in`, a series card, conference headers) and a group-stage table drawing, which John Morris asked for; and a lone final centred, and one stylesheet for several drawings. See [docs/roadmap.md](./docs/roadmap.md); the pictures that prompted them are listed in [docs/references.md](./docs/references.md).
 
 ## The name
 

package/dist/background.d.ts

@@ -0,0 +1,19 @@
+import type { BackgroundInks } from "./theme.ts";
+import type { ThemeName } from "./types.ts";
+export interface ResolvedBackground {
+    /** For the drawing's `<defs>`. */
+    defs: string;
+    /** Drawn over the plain `.tb-bg` rectangle, under everything else. */
+    body: string;
+    /** The colours to draw over it: one for a look that is light or dark, both for `auto`. */
+    inks: BackgroundInks;
+    /** Both pictures are in the drawing and the stylesheet shows the one that fits. */
+    auto: boolean;
+}
+/** Whether an option asks for more than the plain colour: a preset, a tuned preset or an image. */
+export declare function hasBackground(option: unknown): boolean;
+/**
+ * Reads the `background` option for a drawing `width` by `height` in the look `theme`, with `prefix` for the ids. Returns `null` when the option is `true`, `false` or left out
+ * (a plain colour, or none). An unknown preset, a bad colour list or an image address that is not http(s), relative or `data:image/…` throws a `RangeError`.
+ */
+export declare function resolveBackground(option: unknown, theme: ThemeName, width: number, height: number, prefix: string): ResolvedBackground | null;

package/dist/background.js

@@ -0,0 +1,66 @@
+// The `background` option: a preset's name, a preset tuned, or the caller's own picture, turned into the SVG to draw under everything and the colours to draw over it.
+// The drawing of the presets is `family-backgrounds.ts`, which is shared with the other packages of the family; this file only reads the option and writes the picture's frame.
+import { BACKGROUND_PRESETS, backgroundSvg } from "./family-backgrounds.js";
+import { safeUrl } from "./marks.js";
+import { esc, num } from "./text.js";
+const isPreset = (name) => typeof name === "string" && BACKGROUND_PRESETS.includes(name);
+/** Whether an option asks for more than the plain colour: a preset, a tuned preset or an image. */
+export function hasBackground(option) {
+    return typeof option === "string" || (typeof option === "object" && option !== null);
+}
+const fail = (message) => {
+    throw new RangeError(`taisen-brackets: ${message}`);
+};
+/** The ink for a picture of the caller's own: a plain dark or pale ground, since the image under the veil is not known. */
+function inkForImage(theme, id) {
+    const colors = theme === "dark" ? ["#12161c", "#12161c", "#c9d2e0", "#c9d2e0"] : ["#f4f4f1", "#f4f4f1", "#4a5568", "#4a5568"];
+    return backgroundSvg("midnight", { width: 8, height: 8, theme, colors, id }).ink;
+}
+/**
+ * Reads the `background` option for a drawing `width` by `height` in the look `theme`, with `prefix` for the ids. Returns `null` when the option is `true`, `false` or left out
+ * (a plain colour, or none). An unknown preset, a bad colour list or an image address that is not http(s), relative or `data:image/…` throws a `RangeError`.
+ */
+export function resolveBackground(option, theme, width, height, prefix) {
+    if (option === undefined || typeof option === "boolean" || option === null)
+        return null;
+    const spec = typeof option === "string" ? { preset: option } : option;
+    if (typeof option !== "string" && typeof option !== "object")
+        return fail(`background is a preset's name or an object, not ${typeof option}`);
+    const image = spec.image;
+    if (image === undefined && spec.preset !== undefined && !isPreset(spec.preset))
+        fail(`unknown background "${String(spec.preset)}": use one of ${BACKGROUND_PRESETS.join(", ")}`);
+    if (spec.colors !== undefined && (!Array.isArray(spec.colors) || spec.colors.some((c) => typeof c !== "string")))
+        fail("background.colors is a list of colours as text");
+    for (const key of ["angle", "intensity", "seed", "dim"])
+        if (spec[key] !== undefined && !Number.isFinite(spec[key]))
+            fail(`background.${key} is a number`);
+    // Which pictures to draw: the one the look is, or the one asked for; `auto` draws both.
+    const want = spec.theme ? [spec.theme] : theme === "light" ? ["light"] : theme === "dark" || theme === "poster" || theme === "none" ? ["dark"] : ["light", "dark"];
+    const auto = want.length === 2;
+    const parts = want.map((t) => {
+        const id = auto ? `${prefix}${t === "light" ? "l" : "d"}` : `${prefix}b`;
+        if (image !== undefined) {
+            if (typeof image !== "string" || !safeUrl(image))
+                return fail("background.image must be an http(s) address, a relative path or a data:image/ address");
+            const dim = Math.min(1, Math.max(0, spec.dim ?? 0.5));
+            const fitName = spec.fit === "contain" ? "meet" : "slice";
+            return {
+                t,
+                defs: "",
+                body: `<image href="${esc(image)}" x="0" y="0" width="${num(width)}" height="${num(height)}" preserveAspectRatio="xMidYMid ${fitName}"/><rect width="${num(width)}" height="${num(height)}" fill="${t === "dark" ? "#000" : "#fff"}" opacity="${num(dim)}"/>`,
+                ink: inkForImage(t, id),
+            };
+        }
+        const made = backgroundSvg(spec.preset ?? "midnight", { width, height, theme: t, colors: spec.colors, angle: spec.angle, intensity: spec.intensity, seed: spec.seed, id });
+        return { t, ...made };
+    });
+    const inks = {};
+    for (const p of parts)
+        inks[p.t] = p.ink;
+    return {
+        defs: parts.map((p) => p.defs).join(""),
+        body: auto ? parts.map((p) => `<g class="${p.t === "light" ? "tb-bgl" : "tb-bgd"}">${p.body}</g>`).join("") : parts[0].body,
+        inks,
+        auto,
+    };
+}

package/dist/backgrounds-entry.d.ts

@@ -0,0 +1,2 @@
+export { BACKGROUND_PRESETS, FAMILY_BACKGROUNDS_VERSION, backgroundSvg, contrastRatio, luminance, parseColor, toHex } from "./family-backgrounds.ts";
+export type { BackgroundInk, BackgroundPresetName, BackgroundSvg, BackgroundSvgOptions } from "./family-backgrounds.ts";

package/dist/backgrounds-entry.js

@@ -0,0 +1 @@
+export { BACKGROUND_PRESETS, FAMILY_BACKGROUNDS_VERSION, backgroundSvg, contrastRatio, luminance, parseColor, toHex } from "./family-backgrounds.js";

package/dist/family-backgrounds.d.ts

@@ -0,0 +1,61 @@
+export declare const FAMILY_BACKGROUNDS_VERSION = "1.0.0";
+/** The presets, by name. The five that end in a playing surface read as one: pitch (soccer), ice (hockey), hardwood (basketball), infield (baseball) and turf (football). */
+export declare const BACKGROUND_PRESETS: readonly ["midnight", "crimson", "royal", "emerald", "pitch", "ice", "hardwood", "infield", "turf", "ball-panels", "swirl", "waves", "glow", "floodlights", "confetti", "carbon", "aurora", "sunburst", "chevrons", "halftone", "argyle", "contour", "stardust", "mesh", "spotlight"];
+export type BackgroundPresetName = (typeof BACKGROUND_PRESETS)[number];
+export interface BackgroundSvgOptions {
+    width: number;
+    height: number;
+    /** `dark` (the default) or `light`: which of the preset's two palettes. With your own `colors`, the ink follows what they are. */
+    theme?: "dark" | "light";
+    /** Your own colours, as hex (`#0b1230`) or `rgb()`: the first two make the ground, the third and fourth the glow and the pattern. Fewer than four keep the preset's for the rest. */
+    colors?: readonly string[];
+    /** The angle of the ground's gradient and of the pattern over it, in degrees as CSS has it (180 is top to bottom). The preset's own by default; a playing surface keeps its lines straight. */
+    angle?: number;
+    /** How strong the pattern and glow are, 0 to 1. Default 0.6. */
+    intensity?: number;
+    /** Moves the scattered parts (confetti, stars, scratches, contours). Default 1. */
+    seed?: number;
+    /** The prefix of the ids the background writes. Default: a hash of its options. */
+    id?: string;
+}
+/** The colours to draw over a background. Every text colour is checked against `dominant`, the colours the background mostly is, for a contrast of 4.5 to 1 (3 to 1 for `muted`). */
+export interface BackgroundInk {
+    /** The plain colour to fill the picture with before `body`: the ground's first colour. */
+    base: string;
+    /** Whether the ground is dark (so the text is light). */
+    dark: boolean;
+    text: string;
+    muted: string;
+    /** The connecting lines. */
+    line: string;
+    /** The fill and edge of a box laid on the picture; both are `rgba()`. */
+    box: string;
+    edge: string;
+    /** The pill behind a round's name, a team's plain disc, the ring round a mark, the dotted road and the accent for a winner, a champion and a highlight. */
+    panel: string;
+    plain: string;
+    ring: string;
+    spine: string;
+    accent: string;
+    /** The colours the picture is mostly, worst cases included: the ground's two colours and each blended with the glow at its strongest. */
+    dominant: string[];
+}
+export interface BackgroundSvg {
+    defs: string;
+    body: string;
+    ink: BackgroundInk;
+}
+type Rgb = readonly [number, number, number];
+/** A colour as three channels, or `null` when it is not hex or `rgb()`. */
+export declare function parseColor(text: string): Rgb | null;
+export declare const toHex: (c: Rgb) => string;
+/** The relative luminance of a colour, as WCAG defines it. */
+export declare function luminance(c: Rgb): number;
+/** The WCAG contrast ratio of two colours, 1 to 21. */
+export declare function contrastRatio(a: Rgb, b: Rgb): number;
+/**
+ * One background: `defs` for the drawing's `<defs>`, `body` for what goes over a plain `ink.base` rectangle, and `ink`, the colours to draw text, lines and boxes in. The same preset and options
+ * always give the same markup; every id starts with `options.id`. An unknown preset throws.
+ */
+export declare function backgroundSvg(preset: BackgroundPresetName, options: BackgroundSvgOptions): BackgroundSvg;
+export {};