@gusnips/vite 0.8.43 → 0.8.45

package/README.md

@@ -63,6 +63,87 @@ Four rules in there are load-bearing:
   points back at the others, which is why you pass the full list to every page rather than "the
   other two".
 
+## Discovery files
+
+```ts
+import { jsonLd } from "@gusnips/vite";
+
+jsonLd({ "@type": "SoftwareApplication", name: "Example" });
+// A <script type="application/ld+json"> tag containing the object.
+```
+
+Pass the result to `bakeHead` as `headExtra`. `jsonLd` escapes HTML control text while keeping
+valid JSON. `faqJsonLd` uses the same serializer. You supply the schema.org fields, including
+`SoftwareApplication` for an app or `WebAPI` for a public API. A local command is not a public API.
+
+```ts
+import { llmsTxt, mcpDiscoveryJson, writeDist } from "@gusnips/vite";
+
+await writeDist(
+  "dist",
+  "llms.txt",
+  llmsTxt({
+    title: "Example",
+    summary: "Read and update tasks.",
+    sections: [
+      {
+        title: "Reference",
+        links: [{ title: "Connect", url: "https://example.com/docs/mcp" }],
+      },
+    ],
+  }),
+);
+
+await writeDist(
+  "dist",
+  "llms-full.txt",
+  llmsTxt({
+    title: "Example reference",
+    body: referenceMarkdown,
+  }),
+);
+
+await writeDist(
+  "dist",
+  ".well-known/mcp.json",
+  mcpDiscoveryJson({
+    name: "Example",
+    homepage: "https://example.com",
+    documentation: "https://example.com/docs/mcp",
+    llmsTxt: "https://example.com/llms.txt",
+    llmsFullTxt: "https://example.com/llms-full.txt",
+    servers: [
+      {
+        name: "tasks",
+        transport: "streamable-http",
+        url: "https://api.example.com/mcp",
+        authentication: [
+          {
+            type: "oauth2",
+            protectedResourceMetadata:
+              "https://api.example.com/.well-known/oauth-protected-resource/mcp",
+          },
+        ],
+        tools: ["list_tasks", "update_task"],
+      },
+    ],
+  }),
+);
+```
+
+Build `referenceMarkdown` from your existing docs. The formatter adds no content or access rules.
+Each server lists only its own tools, as names or objects with `name`, `title`, `description`,
+`inputSchema` and `annotations`. Supplied schemas and annotations are kept unchanged.
+
+For a local server, use `transport: "stdio"`, `command` and optional `args` instead of `url`.
+`authentication` is a list of accepted methods: `oauth2` with `protectedResourceMetadata`, `api-key`
+with `in` (`header` or `environment`), `name` and optional `prefix`, `session` with a `description`,
+or `none` for public access. Methods can also include `description` and `documentation`.
+
+`/.well-known/mcp.json` is discovery metadata, not a universal MCP standard or a client config.
+It does not replace the live server's `tools/list`. These files do not promise search rankings or
+support in a particular client.
+
 ## Rendering
 
 ```ts
@@ -289,7 +370,8 @@ process.exit(report.problems.some((p) => p.level === "error") ? 1 : 0);
 ```
 
 The tokens package measures the placeholder colours it ships. This measures yours: it compiles
-your entry with the real Tailwind CLI and reads the CSS that comes back.
+your entry with the real Tailwind CLI and reads the CSS that comes back. No Tailwind? The next
+section reads plain CSS custom properties instead.
 
 | It fails when                                                      | Because the reader gets                                   |
 | ------------------------------------------------------------------ | --------------------------------------------------------- |
@@ -308,6 +390,108 @@ not have, or a class built dynamically that no scan can see.
 Pass `allow: [/^bg-brand-/]` for the classes a repo means. Floors take no allow list: a
 measured ratio is not a judgement call.
 
+## Check your contrast without Tailwind
+
+If your colours are plain CSS custom properties, there is no `@theme` to compile. Name the file,
+the selector of the dark block, and the pairs that must stay readable:
+
+```ts
+// scripts/check-contrast.ts
+import { checkTokenPairs, formatContrastReport } from "@gusnips/vite/contrast";
+
+const report = await checkTokenPairs([
+  {
+    name: "site",
+    css: "src/tokens.css",
+    dark: ':root[data-theme="dark"]',
+    textPairs: [["--ground", "--ink"]],
+  },
+]);
+
+console.log(formatContrastReport(report));
+process.exit(report.problems.some((p) => p.level === "error") ? 1 : 0);
+```
+
+It reads the colours in `:root { … }` as the light theme and the colours in your dark block as the
+dark one. If `--ink` on `--ground` is under 4.5:1 in either, it prints the line and exits 1:
+
+```
+site
+  ✖ floor: src/tokens.css:8 dark: --ink (#3a3a3a) on --ground (#121212) is 1.65:1, under the 4.5:1 floor for text (WCAG 1.4.3)
+✖ contrast: 1 error(s)
+```
+
+Nothing is compiled, so it needs no Tailwind and no other peer. It returns the same report as
+`checkContrast`, so the formatter is the same, and you can join the two before you exit:
+`report.problems.push(...other.problems)`.
+
+| It fails when                                                           | Because the reader gets                          |
+| ----------------------------------------------------------------------- | ------------------------------------------------ |
+| a pair is under its floor in the light or the dark theme                | text or a border some people cannot see          |
+| a colour is in one theme and not the other                              | one mode keeping, or lacking, a colour           |
+| a pair names a token that no block declares                             | a typo that looks like a pair that passes        |
+| a pair holds a colour that is not hex                                   | a floor nobody is keeping                        |
+| the system block differs from the dark block, or is not in the `@media` | a page with no saved choice that looks different |
+
+`textPairs` are held to 4.5:1 and `nonTextPairs` (borders, focus rings, icons) to 3:1. Change
+them with `textFloor` and `nonTextFloor`. A pair is `[background, foreground]`; the ratio is the
+same either way round, so the order only decides how the message reads. Write the names as the CSS
+does, with the `--`. The light block is `:root` unless you set `light`.
+
+**The system block.** A page that has not chosen a theme follows the system, so many apps write
+the dark colours twice: once for the chosen theme and once for everyone else.
+
+```css
+:root {
+  --ground: #ffffff;
+  --ink: #1a1a1a;
+}
+
+:root[data-theme="dark"] {
+  --ground: #121212;
+  --ink: #f2f2f2;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]) {
+    --ground: #121212;
+    --ink: #f2f2f2;
+  }
+}
+```
+
+Pass `system: ":root:not([data-theme])"` and the check holds the second block to the first: the
+same tokens, the same colours (`#FFF` and `#ffffff` are the same colour), and inside
+`@media (prefers-color-scheme: dark)`. Either dark block can sit inside `@media screen { … }`.
+
+**Your own checks.** `loadTokenThemes` hands back the two palettes as hex, with the same file and
+selectors:
+
+```ts
+import { loadTokenThemes } from "@gusnips/vite/contrast";
+
+const { light, dark } = await loadTokenThemes({
+  css: "src/tokens.css",
+  dark: ':root[data-theme="dark"]',
+});
+light.get("--ground"); // "#ffffff"
+```
+
+Use it for what only your app knows: that the browser's toolbar colour is the page's ground in
+each theme, for example. It throws, and says what is missing, if the file or a block is not there.
+
+**What it does not read.** It reads text, not CSS, and there is no CSS parser behind it.
+
+- Only hex colours (`#fff` or `#ffffff`) are measured. A token in a pair that holds `rgb()`,
+  `oklch()` or `var()` fails as one it cannot measure. Tokens no pair uses, like `--radius`, are
+  left alone.
+- A block is found by its selector text, inside any `@media`, and must hold declarations only. A
+  block with another rule inside it (nested CSS) is not read, and the check says it found no
+  block.
+- A media query is read, not run. A `@media print` block with your dark selector counts as that
+  selector. If one selector is written twice, the later token wins, as it does in CSS.
+- Light and dark need different selectors.
+
 ## The vite preset
 
 ```ts

package/dist/contrast.d.ts

@@ -12,7 +12,7 @@ export interface CheckContrastOptions {
     /** What `entry` and `sources` are relative to. Default: the working directory. */
     root?: string;
 }
-export type ContrastRule = "load" | "floor" | "retune" | "rebind" | "untokened" | "hover" | "dead";
+export type ContrastRule = "load" | "floor" | "retune" | "rebind" | "untokened" | "hover" | "dead" | "missing" | "mirror";
 export interface ContrastProblem {
     rule: ContrastRule;
     /** A warning is shown and does not fail the gate. */
@@ -40,4 +40,63 @@ export declare function checkContrast(bundles: readonly ContrastBundle[], option
 /** The report as lines for a terminal: one per problem, grouped by bundle, and a last line that
  *  says whether the gate passed. */
 export declare function formatContrastReport(report: ContrastReport): string;
+/** Two custom properties, `[background, foreground]`, written as the CSS names them:
+ *  `["--ground", "--ink"]`. The ratio is the same either way round; the order only decides how a
+ *  problem reads. */
+export type TokenPair = readonly [background: string, foreground: string];
+export interface TokenPairsBundle {
+    /** Shown beside every problem: `"apps/site"`. */
+    name: string;
+    /** The stylesheet holding the colour blocks, relative to `root`. */
+    css: string;
+    /** The selector of the light block. Default `":root"`. It must differ from `dark`. */
+    light?: string;
+    /** The selector of the dark block: `':root[data-theme="dark"]'`. */
+    dark: string;
+    /**
+     * The selector of the system fallback: the dark colours again, for a page that has chosen no
+     * theme, inside `@media (prefers-color-scheme: dark)`: `":root:not([data-theme])"`. It must
+     * hold exactly the dark block's tokens and values. Leave it off when there is none.
+     */
+    system?: string;
+    /** Pairs read as text. Held to `textFloor`. */
+    textPairs?: readonly TokenPair[];
+    /** Pairs that are not text: borders, focus rings, icons. Held to `nonTextFloor`. */
+    nonTextPairs?: readonly TokenPair[];
+    /** Default 4.5 (WCAG 1.4.3). */
+    textFloor?: number;
+    /** Default 3 (WCAG 1.4.11). */
+    nonTextFloor?: number;
+}
+/** The hex colours of each theme, `--ground` → `#ffffff`, for a check of your own. */
+export interface TokenThemes {
+    light: Map<string, string>;
+    dark: Map<string, string>;
+}
+/**
+ * The two palettes of a bundle as hex maps, for a check of your own that needs the colours
+ * (the browser's toolbar colour should be the page's ground, in each theme):
+ *
+ * ```ts
+ * const { light, dark } = await loadTokenThemes({ css: "src/tokens.css", dark: '[data-theme="dark"]' });
+ * light.get("--ground"); // "#ffffff"
+ * ```
+ *
+ * Throws, saying what is missing, when the file or one of the two blocks is not there.
+ */
+export declare function loadTokenThemes(bundle: Pick<TokenPairsBundle, "css" | "light" | "dark">, options?: CheckContrastOptions): Promise<TokenThemes>;
+/**
+ * The plain-CSS gate: for each stylesheet, the contrast of every pair in both themes, a token
+ * both themes have, and a system fallback that matches the dark block. Returns what it found,
+ * the same report `checkContrast` returns, so `formatContrastReport` prints either and a repo
+ * can join the two (`report.problems.push(...other.problems)`) and fail CI once.
+ *
+ * ```ts
+ * const report = await checkTokenPairs([
+ *   { name: "site", css: "src/tokens.css", dark: ':root[data-theme="dark"]', textPairs: [["--ground", "--ink"]] },
+ * ]);
+ * console.log(formatContrastReport(report));
+ * ```
+ */
+export declare function checkTokenPairs(bundles: readonly TokenPairsBundle[], options?: CheckContrastOptions): Promise<ContrastReport>;
 //# sourceMappingURL=contrast.d.ts.map

package/dist/contrast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contrast.d.ts","sourceRoot":"","sources":["../src/contrast.ts"],"names":[],"mappings":"AA0CA,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,kGAAkG;IAClG,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAEnG,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IACnB,qDAAqD;IACrD,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAyYD;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,cAAc,CAAC,CAIzB;AAED;oCACoC;AACpC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAoBnE"}
+{"version":3,"file":"contrast.d.ts","sourceRoot":"","sources":["../src/contrast.ts"],"names":[],"mappings":"AAqDA,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,kGAAkG;IAClG,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,YAAY,GACtB,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEjG,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IACnB,qDAAqD;IACrD,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AA2YD;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,cAAc,CAAC,CAIzB;AAED;oCACoC;AACpC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAoBnE;AAYD;;qBAEqB;AACrB,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACjC,oFAAoF;IACpF,YAAY,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACpC,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3B;AAmID;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC,EACxD,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,WAAW,CAAC,CAGtB;AA2ID;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,cAAc,CAAC,CAIzB"}

package/dist/contrast.js

@@ -30,9 +30,20 @@
  * - **dead**: a class that compiles to no rule at all — a token Tailwind does not have, or a
  *   name the scanner caught half of. A warning: dynamic construction reads the same way.
  *
+ * `checkContrast` is the Tailwind reading. `checkTokenPairs` (further down) is the other one, for
+ * an app whose colours are plain CSS custom properties: it reads a light block and a dark block as
+ * text, holds a list of pairs to a floor in both, and reports through the same problems and the
+ * same formatter. It adds two rules:
+ *
+ * - **missing**: a colour one theme declares and the other does not, or a pair that names a token
+ *   neither declares. A typo in a pair would otherwise read as a pair that passes.
+ * - **mirror**: the system fallback (the dark colours repeated under `prefers-color-scheme` for a
+ *   page that has chosen no theme) differs from the dark block, or sits outside that query.
+ *
  * Runs on node and bun: `fs.promises.glob`, never Bun's `Glob`, and no `import.meta.dir`.
- * Needs `@tailwindcss/cli` installed where it runs (an optional peer, reachable only from
- * `@gusnips/vite/contrast`), because the fixture is compiled, not guessed.
+ * `checkContrast` needs `@tailwindcss/cli` installed where it runs (an optional peer, reachable
+ * only from `@gusnips/vite/contrast`), because the fixture is compiled, not guessed.
+ * `checkTokenPairs` compiles nothing and needs no peer.
  */
 import { spawnSync } from "node:child_process";
 import { glob, mkdir, readFile, rm, writeFile } from "node:fs/promises";
@@ -101,6 +112,14 @@ function measured(value, map) {
 const ATTR = /\bclass(?:Name)?\s*=\s*(?:"([^"]*)"|'([^']*)'|`((?:[^`$]|\$(?!\{))*)`)/g;
 const HELPER = /\b(?:cn|clsx|cva|twMerge|twJoin)\s*\(([^)]*)\)/g;
 const STR = /"([^"]*)"|'([^']*)'/g;
+/** The 1-based line a character offset falls on. */
+function lineAt(source, index) {
+    let line = 1;
+    for (let i = 0; i < index; i++)
+        if (source.charCodeAt(i) === 10)
+            line++;
+    return line;
+}
 const skipped = (file) => /(?:^|\/)__tests__\//.test(file) || /\.(test|spec)\.[tj]sx?$/.test(file);
 /** Every class string the sources use, with the first `file:line` that uses it. */
 async function scanSources(root, patterns) {
@@ -112,13 +131,6 @@ async function scanSources(root, patterns) {
                 files.add(file);
         }
     }
-    const lineAt = (source, index) => {
-        let line = 1;
-        for (let i = 0; i < index; i++)
-            if (source.charCodeAt(i) === 10)
-                line++;
-        return line;
-    };
     const keep = (raw, file, index, source) => {
         for (const cls of raw.split(/\s+/).filter(Boolean)) {
             // A token that would break the fixture's quoting is skipped rather than escaped:
@@ -426,4 +438,260 @@ export function formatContrastReport(report) {
         : `✖ contrast: ${errors} error(s)${warnings > 0 ? `, ${warnings} warning(s)` : ""}`);
     return lines.join("\n");
 }
+const PREFERS_DARK = /\(\s*prefers-color-scheme\s*:\s*dark\s*\)/;
+/** `:root[data-theme='dark']` and `:root[data-theme="dark"]` are the same selector. */
+const selectorOf = (text) => text.replace(/\s+/g, " ").replace(/'/g, '"').trim();
+/** The comparable form of a value: `#FFF` and `#ffffff` are one colour. */
+const canonical = (value) => normalizeHex(value) ?? value.replace(/\s+/g, " ").toLowerCase();
+/**
+ * Every innermost `selector { … }` block with the at-rules around it, and the custom properties
+ * it declares. Text, not syntax: a brace or semicolon inside a string or `url()` is not understood.
+ */
+function leafRules(css) {
+    // Comments become spaces, so a `{` in one is not a block and every offset still names its line.
+    const source = css.replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, " "));
+    const rules = [];
+    const open = [];
+    let preludeFrom = 0;
+    for (let i = 0; i < source.length; i++) {
+        const char = source[i];
+        if (char === "{") {
+            const parent = open.at(-1);
+            if (parent !== undefined)
+                parent.nested = true;
+            open.push({ prelude: source.slice(preludeFrom, i).trim(), bodyAt: i + 1, nested: false });
+            preludeFrom = i + 1;
+        }
+        else if (char === "}") {
+            const block = open.pop();
+            preludeFrom = i + 1;
+            if (block === undefined || block.nested || block.prelude.startsWith("@"))
+                continue;
+            const tokens = new Map();
+            for (const match of source.slice(block.bodyAt, i).matchAll(/(--[\w-]+)\s*:\s*([^;]*)/g)) {
+                tokens.set(match[1] ?? "", {
+                    value: (match[2] ?? "").trim(),
+                    line: lineAt(source, block.bodyAt + match.index),
+                });
+            }
+            rules.push({
+                selectors: block.prelude.split(",").map(selectorOf),
+                within: open
+                    .map((parent) => parent.prelude)
+                    .filter((prelude) => prelude.startsWith("@"))
+                    .join(" "),
+                tokens,
+            });
+        }
+        else if (char === ";") {
+            preludeFrom = i + 1;
+        }
+    }
+    return rules;
+}
+/** Every block written with this selector, merged: a later token wins, as it does in CSS. */
+function blockOf(rules, selector) {
+    const wanted = selectorOf(selector);
+    const found = rules.filter((rule) => rule.selectors.includes(wanted));
+    if (found.length === 0)
+        return null;
+    const tokens = new Map();
+    for (const rule of found)
+        for (const [name, decl] of rule.tokens)
+            tokens.set(name, decl);
+    return { tokens, within: found.map((rule) => rule.within) };
+}
+/** Throws when the file or a block the bundle names is not there. The system block may be absent:
+ *  whether that is a problem is the check's question, not the loader's. */
+async function readTokenBlocks(bundle, root) {
+    const css = await readFile(resolve(root, bundle.css), "utf8").catch(() => null);
+    // A stylesheet that does not load reads as one with no tokens, which would pass every rule
+    // below. It fails instead, the same reason `checkContrast` has a load rule.
+    if (css === null)
+        throw new Error(`${bundle.css} could not be read`);
+    const rules = leafRules(css);
+    const required = (label, selector) => {
+        const block = blockOf(rules, selector);
+        if (block === null) {
+            throw new Error(`${bundle.css} has no \`${selector}\` block for the ${label} colours. A block is found by ` +
+                `its selector text, inside any @media, and holds declarations only`);
+        }
+        return block;
+    };
+    const lightSelector = bundle.light ?? ":root";
+    if (selectorOf(lightSelector) === selectorOf(bundle.dark)) {
+        throw new Error(`the light and dark selectors are both \`${lightSelector}\`; they must differ`);
+    }
+    return {
+        light: required("light", lightSelector),
+        dark: required("dark", bundle.dark),
+        system: bundle.system === undefined ? null : blockOf(rules, bundle.system),
+    };
+}
+/** The tokens whose value is a hex colour, as `#rrggbb`. Type and geometry are left out. */
+function hexTokens(tokens) {
+    const hex = new Map();
+    for (const [name, { value }] of tokens) {
+        const colour = normalizeHex(value);
+        if (colour !== null)
+            hex.set(name, colour);
+    }
+    return hex;
+}
+/**
+ * The two palettes of a bundle as hex maps, for a check of your own that needs the colours
+ * (the browser's toolbar colour should be the page's ground, in each theme):
+ *
+ * ```ts
+ * const { light, dark } = await loadTokenThemes({ css: "src/tokens.css", dark: '[data-theme="dark"]' });
+ * light.get("--ground"); // "#ffffff"
+ * ```
+ *
+ * Throws, saying what is missing, when the file or one of the two blocks is not there.
+ */
+export async function loadTokenThemes(bundle, options = {}) {
+    const { light, dark } = await readTokenBlocks(bundle, options.root ?? process.cwd());
+    return { light: hexTokens(light.tokens), dark: hexTokens(dark.tokens) };
+}
+async function checkTokenBundle(bundle, options, report) {
+    const problem = (p) => {
+        report.problems.push({ bundle: bundle.name, level: "error", ...p });
+    };
+    const at = (decl) => decl === undefined ? bundle.css : `${bundle.css}:${String(decl.line)}`;
+    let blocks;
+    try {
+        blocks = await readTokenBlocks(bundle, options.root ?? process.cwd());
+    }
+    catch (error) {
+        problem({ rule: "load", message: error instanceof Error ? error.message : String(error) });
+        return;
+    }
+    const { light, dark, system } = blocks;
+    const themes = [
+        ["light", light.tokens],
+        ["dark", dark.tokens],
+    ];
+    const textPairs = bundle.textPairs ?? [];
+    const nonTextPairs = bundle.nonTextPairs ?? [];
+    // ── Every colour has both themes, and every pair names a real token ──
+    const wanted = new Set([
+        ...hexTokens(light.tokens).keys(),
+        ...hexTokens(dark.tokens).keys(),
+        ...[...textPairs, ...nonTextPairs].flat(),
+    ]);
+    for (const token of wanted) {
+        const inLight = light.tokens.get(token);
+        const inDark = dark.tokens.get(token);
+        if (inLight !== undefined && inDark !== undefined)
+            continue;
+        if (inLight === undefined && inDark === undefined) {
+            problem({
+                rule: "missing",
+                at: bundle.css,
+                message: `a pair names \`${token}\`, which neither the light nor the dark block declares` +
+                    (token.startsWith("--") ? "" : ". Custom property names start with --"),
+            });
+            continue;
+        }
+        const [have, lack] = inLight === undefined ? ["dark", "light"] : ["light", "dark"];
+        problem({
+            rule: "missing",
+            at: at(inLight ?? inDark),
+            message: `\`${token}\` is in the ${have} block but not in the ${lack} block. Declare it in both, ` +
+                `even when the colour is the same, so each theme says what it means`,
+        });
+    }
+    // ── The pairs, on the values that ship in each theme ──
+    // A token missing from a theme was reported above, so its pairs are skipped here, not repeated.
+    const unmeasurable = new Set();
+    const cannotMeasure = (mode, token, decl) => {
+        if (unmeasurable.has(`${mode}:${token}`))
+            return;
+        unmeasurable.add(`${mode}:${token}`);
+        problem({
+            rule: "floor",
+            at: at(decl),
+            message: `${mode}: cannot measure ${token} (${decl.value}), because it is not a hex colour. ` +
+                `Keep the values hex, or teach this check the new notation; ` +
+                `do not let a pair go unmeasured.`,
+        });
+    };
+    const measure = (pairs, floor, why) => {
+        for (const [background, foreground] of pairs) {
+            for (const [mode, tokens] of themes) {
+                const bg = tokens.get(background);
+                const fg = tokens.get(foreground);
+                if (bg === undefined || fg === undefined)
+                    continue;
+                const bgHex = normalizeHex(bg.value);
+                const fgHex = normalizeHex(fg.value);
+                if (bgHex === null || fgHex === null) {
+                    if (bgHex === null)
+                        cannotMeasure(mode, background, bg);
+                    if (fgHex === null)
+                        cannotMeasure(mode, foreground, fg);
+                    continue;
+                }
+                const ratio = contrast(fgHex, bgHex);
+                if (ratio < floor) {
+                    problem({
+                        rule: "floor",
+                        at: at(fg),
+                        message: `${mode}: ${foreground} (${fgHex}) on ${background} (${bgHex}) is ` +
+                            `${ratio.toFixed(2)}:1, under the ${floor}:1 floor for ${why}`,
+                    });
+                }
+            }
+        }
+    };
+    measure(textPairs, bundle.textFloor ?? 4.5, "text (WCAG 1.4.3)");
+    measure(nonTextPairs, bundle.nonTextFloor ?? 3, "a control or icon (WCAG 1.4.11)");
+    // ── The system fallback says what the dark block says ──
+    if (bundle.system === undefined)
+        return;
+    const mirror = (decl, message) => problem({ rule: "mirror", at: at(decl), message });
+    if (system === null) {
+        mirror(undefined, `no \`${bundle.system}\` block for the system fallback. Without it a page that has ` +
+            `chosen no theme stays light on a dark system`);
+        return;
+    }
+    if (!system.within.every((within) => PREFERS_DARK.test(within))) {
+        mirror([...system.tokens.values()][0], `\`${bundle.system}\` is not inside @media (prefers-color-scheme: dark), so it paints ` +
+            `the dark colours for everyone who has chosen no theme`);
+    }
+    for (const token of new Set([...dark.tokens.keys(), ...system.tokens.keys()])) {
+        const chosen = dark.tokens.get(token);
+        const followed = system.tokens.get(token);
+        if (chosen !== undefined && followed !== undefined) {
+            if (canonical(chosen.value) !== canonical(followed.value)) {
+                mirror(followed, `\`${token}\` is ${chosen.value} in the dark block but ${followed.value} in the system block`);
+            }
+        }
+        else if (chosen !== undefined) {
+            mirror(chosen, `\`${token}\` is in the dark block but not in the system block`);
+        }
+        else {
+            mirror(followed, `\`${token}\` is in the system block but not in the dark block`);
+        }
+    }
+}
+/**
+ * The plain-CSS gate: for each stylesheet, the contrast of every pair in both themes, a token
+ * both themes have, and a system fallback that matches the dark block. Returns what it found,
+ * the same report `checkContrast` returns, so `formatContrastReport` prints either and a repo
+ * can join the two (`report.problems.push(...other.problems)`) and fail CI once.
+ *
+ * ```ts
+ * const report = await checkTokenPairs([
+ *   { name: "site", css: "src/tokens.css", dark: ':root[data-theme="dark"]', textPairs: [["--ground", "--ink"]] },
+ * ]);
+ * console.log(formatContrastReport(report));
+ * ```
+ */
+export async function checkTokenPairs(bundles, options = {}) {
+    const report = { problems: [] };
+    for (const bundle of bundles)
+        await checkTokenBundle(bundle, options, report);
+    return report;
+}
 //# sourceMappingURL=contrast.js.map