# Where these theme files came from

## The pin

| | |
|---|---|
| Package | `tm-themes` |
| Version | **1.12.10** |
| Registry | `https://registry.npmjs.org/tm-themes` |
| Vendored on | 2026-09-01 |
| Files taken | `themes/*.json`, `NOTICE`, and the metadata in `index.js` |

`tm-themes` is Anthony Fu and Pine Wu's re-distribution of a set of upstream
TextMate/VS Code themes as plain JSON, MIT-licensed itself and carrying each
theme's own licence in its `NOTICE`. It is the same set Shiki bundles, and Shiki
is what Buzz loads its themes through — decision 0018 adapts Buzz's derivation,
so taking Buzz's theme set is what makes the two comparable.

`@shikijs/themes@4.1.0` — the exact version Buzz pins — was installed alongside
and diffed against this set while vendoring. For every one of the 65 themes,
extracting `editor.background`, `editor.foreground`, the comment colour, the
git-decoration colours and the sixteen terminal colours gives byte-identical
results from either package. Shiki's bundles are these files with a wrapper, so
nothing is lost by vendoring the plainer of the two.

## What is here

```
assets/themes/
  SOURCE.md          this file
  NOTICE-THEMES.md   generated: one row per theme, with licence and upstream
  metadata.json      generated: the pinned provenance the generator reads
  licenses/          27 licence texts, split out of tm-themes' NOTICE
  tm-themes/         64 theme files, byte-for-byte as published
```

The JSON files are **unmodified copies**. `metadata.json` records a `sha256` per
file, so the vendored tree can be checked against a fresh download:

```bash
npm pack tm-themes@1.12.10 && tar xf tm-themes-1.12.10.tgz
cd package/themes && sha256sum *.json
```

`metadata.json` also carries each theme's upstream repository, the upstream
commit `sha` the theme was captured at, and the `licenseUrl` and licence file
that cover it. Those fields come from `tm-themes`' own generated metadata, not
from anywhere else, so re-pinning the package refreshes them together.

## What is *not* here, and why

**`aurora-x` is not vendored at all.** It is GPL-3.0, and the research boundary
in `AGENTS.md` says AGPL/GPL sources may be studied but not shipped from this
Apache-2.0 repository. Excluding it at the vendoring step rather than at
generation means no copy of it exists in the tree, which is the only version of
that rule that survives someone later changing the generator. It is the only
GPL theme in the set; the other 64 are 59 MIT and 5 Apache-2.0.

**Three themes are vendored but held back from the catalog**, because their body
text does not reach WCAG AA (4.5:1) against the surface Lumbridge paints under
them. These are measurements, made by `tools/theme-gen` against the files in
this directory, and they are re-made on every run:

| Theme | Measured | Why it measures that |
|---|---|---|
| `horizon-bright` | 1.33:1 | declares no `editor.foreground`, so it inherits the stock `#d4d4d4` and puts near-white text on a near-white background |
| `material-theme-lighter` | 2.48:1 | `#90A4AE` body text on `#FAFAFA` |
| `solarized-light` | 4.13:1 | `#657B83` on `#FDF6E3` — Solarized's own design, and just under the line |

They stay vendored so the measurement can be re-run and argued with rather than
taken on trust. `horizon` (the dark variant) has the same missing
`editor.foreground` and inherits the same stock colour, but at 11.22:1 it is
readable, so it ships.

## Re-pinning

1. `npm pack tm-themes@<version>` into a scratch directory and unpack it.
2. Copy `themes/*.json` here, **skipping every theme whose `license` in
   `index.js` matches GPL or AGPL**, and refresh `metadata.json` from
   `index.js`, adding a `sha256` of each copied file.
3. Split `NOTICE` into `licenses/`, one file per distinct licence text, named
   for the upstream repository and its SPDX id.
4. `cargo run -p theme-gen` to rewrite the catalog and `NOTICE-THEMES.md`.
5. `cargo test -p lumbridge-theme` — the contrast, distinctness and
   golden-vector tests all read the regenerated files.
6. Regenerate the golden vectors only if the derivation itself changed; see
   `tools/theme-gen/reference/`. They need the Buzz checkout, which lives
   outside this repository.

Review the diff at step 4. That is the point of the generator being a binary
rather than a `build.rs`: a colour that moves because an upstream theme moved
should be visible in a pull request.