colorsbymax 0.1.0 → 0.1.1

package/README.md

@@ -1,138 +1,164 @@
-# colorsbymax™
-
-**by mrmaxdesigns**
-
-A floating theme switcher for websites. Visitors (or the site's owner) can re-colour the whole site instantly: pick one of the site's own themes, a hand-tuned pick, or one of 715 library themes in 14 categories; build and share custom palettes; or override single colours. Every theme is checked against the Web Content Accessibility Guidelines (WCAG) contrast rules, with one-click fixes.
-
-## Features
-
-- **Site themes first.** The panel opens on a group named after the site, holding its own colours. If those fail contrast, an accessible version is generated automatically.
-- **Scan the site.** Press "Scan site" and colorsbymax reads the colours actually painted on the page (ignoring any theme it has applied, and including gradients). It works out the page background, surfaces, text and brand colours, then adds themes named after the site: Scanned (as found), Accessible, Soft, Bold, Complementary, and the closest library matches. Scans run only when asked, and the results are remembered.
-- **Max’s picks and library.** 5 hand-tuned picks, plus 715 library themes (Bright, Fun, Pastel, Earth tones, Summer, Autumn, Winter, Spring, Ocean, Warm, Nature, Moody, Monochrome, Eclectic) with search and "Surprise me". The library loads only when the panel opens.
-- **Custom palettes, single-colour overrides, JSON import/export.**
-- **Palettes from images and PDFs.** In Import / export, upload or drop a mood board, screenshot, photo or brand guide. colorsbymax picks out its main colours (hex codes written in a PDF take priority), lets you leave any out, previews the palette it builds around them and saves it as a custom palette. Nothing leaves the browser; PDFs are read with [PDF.js](https://mozilla.github.io/pdf.js/), downloaded only when a PDF is picked.
-- **Contrast checks.** Problems show as a badge on the theme; the breakdown offers per-item fixes or "Fix all automatically", which changes lightness only.
-- **No flash on reload.** An inline pre-paint script applies the saved theme before the page draws.
-- **Works on any site.** The panel carries its own stylesheet inside a shadow root, so it needs no Tailwind or other CSS from the site, and the site's CSS can't restyle it.
-- **Movable colour button.** The floating button starts in the corner; visitors can drag it anywhere (mouse or touch; a tooltip says so on hover, and the panel closes while it moves) and it stays there, remembered across reloads. The panel then opens beside it, on whichever side has room. Its dot cycles through the current theme's colours.
-- **Light and dark mode.** Every built-in theme is designed light; dark mode lists a generated dark twin of each (dark surfaces, light text, brand colours lifted to read on dark, then contrast-fixed) and switches the current theme to its twin. The panel turns dark with it. Custom palettes stay as they were made.
-- **Visitor settings.** The gear in the panel header opens settings: theme mode (Light, Dark, Auto), panel size (Compact, Standard, Large), which groups and sections to show, whether the button can be dragged or its dot animates, and moving the button back to its corner. Saved per site.
-- **Resizable panel.** Drag the panel's free edges or corner (the ones away from the colour button) to any size, or pick a size in settings; double-click an edge to reset it. The layout follows the panel's width, so a large panel shows three theme cards a row.
-- **Clear groups and feedback.** The site's own group (globe), Max’s picks (paintbrush) and Yours (person) sit in their own row, apart from the library's categories. Toasts confirm what just happened; saving, importing or building a palette says it went to Yours and offers "Show" to jump straight to it. Tooltips are drawn in the panel's colours.
-- **Themed scrollbars.** The page's scrollbars and the panel's slim one take the selected theme's primary colour. Turn the page's off with `scrollbars: false`.
-- **Accessible panel.** A labelled dialog with focus trap, Escape, the colour button or an outside click to close, keyboard operable, and reduced-motion support.
-
-## How it works
-
-Every colour is one of 35 tokens (`primary`, `surface`, `ink`, `data-1`…), exposed as `--color-<token>` CSS variables. Applying a theme just sets those variables on `<html>`, so anything the site paints with `var(--color-primary)` (directly, or through Tailwind CSS v4 utilities like `bg-primary`) changes instantly. There's no rebuild and no re-render.
-
-The switcher renders into a `<colorsbymax-root>` element on `<body>` with its own shadow root and stylesheet. Only the `--color-*` variables cross into it. With reduced motion, the colour button's dot holds still on the theme's primary colour.
-
-## Try the demo
-
-```bash
-npm install
-npm run dev
-```
-
-This serves `demo/`: colorsbymax's own landing page, built with Tailwind, where every colour is a token (it uses every token group, and a strip shows the live values), and `/plain.html`, a plain-CSS bakery site with deliberately careless global styles to show they don't reach the panel.
-
-## Add it to a site
-
-colorsbymax needs React 18 or 19:
-
-```bash
-npm install colorsbymax
-```
-
-It ships as plain JavaScript (`dist/`), so Vite, Next.js, webpack and other bundlers use it without extra setup. Installing changes nothing on its own; these steps add the colour button:
-
-1. **Paint the site with the token variables.** Use `var(--color-<token>)` wherever the site sets a colour, with your own colours as the starting values.
-
-   With Tailwind CSS v4, import the defaults, override them, and use the token utilities (`bg-primary`, `text-ink`, …) instead of hard-coded colours:
-
-   ```css
-   @import "tailwindcss";
-   @import "colorsbymax/tokens.css";
-
-   @theme static {
-     --color-primary: #c67cde; /* your colours */
-   }
-   ```
-
-   With plain CSS, define the variables yourself (`demo/plain.html` shows this):
-
-   ```css
-   :root {
-     --color-primary: #c67cde;
-   }
-   .button {
-     background: var(--color-primary);
-   }
-   ```
-
-2. **Wrap the app and render the switcher:**
-
-   ```jsx
-   import { ThemeProvider, ThemeSwitcher } from 'colorsbymax'
-
-   <ThemeProvider config={config}>
-     <App />
-     <ThemeSwitcher />
-   </ThemeProvider>
-   ```
-
-   The switcher needs React but not a React site: `demo/plain.jsx` mounts it on its own next to a static page.
-
-3. **Add the pre-paint script** to `<head>`, as a classic inline `<script>`, using the same storage key. `prePaintScript(storageKey)` returns its source, and `demo/index.html` shows it in place.
-
-Without a `siteName`, the site group is named from the page's `og:site_name`, its title or its host name.
-
-### Config
-
-```js
-{
-  siteName: 'Tsungi',               // name of the first theme group
-  storageKey: 'tsungi-theme',       // localStorage key (match the pre-paint script)
-  defaultTheme: { name, tokens },   // the site's own colours; missing tokens are filled in
-  themes: [{ id, name, tokens }],   // optional extra themes made for the site
-  usage: { primary: 'Buttons…' },   // optional notes shown in the colour editors
-  scrollbars: true,                 // colour the page's scrollbars from the theme (default)
-}
-```
-
-`examples/tsungi.config.js` is a complete example for tsungi.online, the first site to use colorsbymax.
-
-## Building the package
-
-`src/` is the source; `dist/` is what sites install: plain JavaScript with the JSX compiled away. `dist/` is committed so installs straight from GitHub work even when npm skips install scripts, so rebuild it before committing changes to `src/`. `npm publish` also rebuilds it first:
-
-```bash
-npm run build
-```
-
-## Panel styles
-
-The panel is styled with Tailwind classes in `src/ThemePanel.jsx` and `src/ThemeSwitcher.jsx`. `scripts/build-css.mjs` compiles them, with `src/panel.css`, into `src/panel-css.generated.js`. The demo server does this automatically as you edit; otherwise run:
-
-```bash
-npm run css
-```
-
-## Regenerating the library
-
-```bash
-npm run presets
-```
-
-`scripts/generate-presets.mjs` turns each source palette into a full theme, auto-fixes contrast, drops anything that still fails or duplicates another theme, names it and tags its categories. Adjust the category rules at the top of the script.
-
-## Notices
-
-The library palettes come from [nice-color-palettes](https://github.com/Jam3/nice-color-palettes) (MIT). Its licence notice is in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and must ship with every copy.
-
-PDF reading uses [pdfjs-dist](https://github.com/mozilla/pdf.js) (Apache-2.0), installed as a dependency rather than bundled into colorsbymax.
-
-## Licence
-
-colorsbymax is released under the [MIT Licence](LICENSE). The names colorsbymax™ and mrmaxdesigns are marks of Max Muyalwa and aren't covered by the code licence.
+# colorsbymax™
+
+**by mrmaxdesigns**
+
+A floating theme switcher for websites. Visitors (or the site's owner) can re-colour the whole site instantly: pick one of the site's own themes, a hand-tuned pick, or one of 715 library themes in 14 categories; build and share custom palettes; or override single colours. Every theme is checked against the Web Content Accessibility Guidelines (WCAG) contrast rules, with one-click fixes.
+
+**At a glance**
+
+- **React 18 or 19.** `npm install colorsbymax`, then wrap your app (see [Add it to a site](#add-it-to-a-site)).
+- **Tailwind optional.** The panel carries its own styles, so it works with Tailwind v4, older Tailwind or plain CSS. Your site only needs to paint its colours with `var(--color-…)` variables. The optional `colorsbymax/tokens.css` helper is for Tailwind v4 (`@theme` syntax); without Tailwind v4, define the variables yourself.
+- **TypeScript types included.**
+- **No runtime dependencies** besides React. PDF uploads are opt-in and need `pdfjs-dist` (see [PDF uploads](#pdf-uploads)).
+- **ESM only.** Import it from a bundler or `import()`; `require('colorsbymax')` from CommonJS isn't supported.
+- **The colour tools work on their own too.** `contrastRatio`, `checkTheme`, `suggestFix`, `fixAll`, `themeFromPalette`, `darkTokens` and the rest are plain functions with no UI.
+
+## Features
+
+- **Site themes first.** The panel opens on a group named after the site, holding its own colours. If those fail contrast, an accessible version is generated automatically.
+- **Scan the site.** Press "Scan site" and colorsbymax reads the colours actually painted on the page (ignoring any theme it has applied, and including gradients). It works out the page background, surfaces, text and brand colours, then adds themes named after the site: Scanned (as found), Accessible, Soft, Bold, Complementary, and the closest library matches. Scans run only when asked, and the results are remembered.
+- **Max’s picks and library.** 5 hand-tuned picks, plus 715 library themes (Bright, Fun, Pastel, Earth tones, Summer, Autumn, Winter, Spring, Ocean, Warm, Nature, Moody, Monochrome, Eclectic) with search and "Surprise me". The library loads only when the panel opens.
+- **Custom palettes, single-colour overrides, JSON import/export.**
+- **Palettes from images and PDFs.** In Import / export, upload or drop a mood board, screenshot or photo. colorsbymax picks out its main colours, lets you leave any out, previews the palette it builds around them and saves it as a custom palette. Nothing leaves the browser. PDFs, such as brand guides, work where the site [turns them on](#pdf-uploads); hex codes written in a PDF take priority.
+- **Contrast checks.** Problems show as a badge on the theme; the breakdown offers per-item fixes or "Fix all automatically", which changes lightness only.
+- **No flash on reload.** An inline pre-paint script applies the saved theme before the page draws.
+- **Works on any site.** The panel carries its own stylesheet inside a shadow root, so it needs no Tailwind or other CSS from the site, and the site's CSS can't restyle it.
+- **Movable colour button.** The floating button starts in the corner; visitors can drag it anywhere (mouse or touch; a tooltip says so on hover, and the panel closes while it moves) and it stays there, remembered across reloads. The panel then opens beside it, on whichever side has room. Its dot cycles through the current theme's colours.
+- **Light and dark mode.** Every built-in theme is designed light; dark mode lists a generated dark twin of each (dark surfaces, light text, brand colours lifted to read on dark, then contrast-fixed) and switches the current theme to its twin. The panel turns dark with it. Custom palettes stay as they were made.
+- **Visitor settings.** The gear in the panel header opens settings: theme mode (Light, Dark, Auto), panel size (Compact, Standard, Large), which groups and sections to show, whether the button can be dragged or its dot animates, and moving the button back to its corner. Saved per site.
+- **Resizable panel.** Drag the panel's free edges or corner (the ones away from the colour button) to any size, or pick a size in settings; double-click an edge to reset it. The layout follows the panel's width, so a large panel shows three theme cards a row.
+- **Clear groups and feedback.** The site's own group (globe), Max’s picks (paintbrush) and Yours (person) sit in their own row, apart from the library's categories. Toasts confirm what just happened; saving, importing or building a palette says it went to Yours and offers "Show" to jump straight to it. Tooltips are drawn in the panel's colours.
+- **Themed scrollbars.** The page's scrollbars and the panel's slim one take the selected theme's primary colour. Turn the page's off with `scrollbars: false`.
+- **Accessible panel.** A labelled dialog with focus trap, Escape, the colour button or an outside click to close, keyboard operable, and reduced-motion support.
+
+## How it works
+
+Every colour is one of 35 tokens (`primary`, `surface`, `ink`, `data-1`…), exposed as `--color-<token>` CSS variables. Applying a theme just sets those variables on `<html>`, so anything the site paints with `var(--color-primary)` (directly, or through Tailwind CSS v4 utilities like `bg-primary`) changes instantly. There's no rebuild and no re-render.
+
+The switcher renders into a `<colorsbymax-root>` element on `<body>` with its own shadow root and stylesheet. Only the `--color-*` variables cross into it. With reduced motion, the colour button's dot holds still on the theme's primary colour.
+
+## Try the demo
+
+```bash
+npm install
+npm run dev
+```
+
+This serves `demo/`: colorsbymax's own landing page, built with Tailwind, where every colour is a token (it uses every token group, and a strip shows the live values), and `/plain.html`, a plain-CSS bakery site with deliberately careless global styles to show they don't reach the panel.
+
+## Add it to a site
+
+colorsbymax needs React 18 or 19:
+
+```bash
+npm install colorsbymax
+```
+
+It ships as plain JavaScript with TypeScript types, so Vite, Next.js, webpack and other bundlers use it without extra setup. Installing changes nothing on its own; these steps add the colour button:
+
+1. **Paint the site with the token variables.** Use `var(--color-<token>)` wherever the site sets a colour, with your own colours as the starting values.
+
+   With Tailwind CSS v4, import the defaults (`colorsbymax/tokens.css` is Tailwind v4 syntax), override them, and use the token utilities (`bg-primary`, `text-ink`, …) instead of hard-coded colours:
+
+   ```css
+   @import "tailwindcss";
+   @import "colorsbymax/tokens.css";
+
+   @theme static {
+     --color-primary: #c67cde; /* your colours */
+   }
+   ```
+
+   With plain CSS, or Tailwind before v4, define the variables yourself (`demo/plain.html` shows this):
+
+   ```css
+   :root {
+     --color-primary: #c67cde;
+   }
+   .button {
+     background: var(--color-primary);
+   }
+   ```
+
+2. **Wrap the app and render the switcher:**
+
+   ```jsx
+   import { ThemeProvider, ThemeSwitcher } from 'colorsbymax'
+
+   <ThemeProvider config={config}>
+     <App />
+     <ThemeSwitcher />
+   </ThemeProvider>
+   ```
+
+   The switcher needs React but not a React site: `demo/plain.jsx` mounts it on its own next to a static page.
+
+3. **Add the pre-paint script** to `<head>`, as a classic inline `<script>`, using the same storage key. `prePaintScript(storageKey)` returns its source, and `demo/index.html` shows it in place.
+
+Without a `siteName`, the site group is named from the page's `og:site_name`, its title or its host name.
+
+### Config
+
+```js
+{
+  siteName: 'Tsungi',               // name of the first theme group
+  storageKey: 'tsungi-theme',       // localStorage key (match the pre-paint script)
+  defaultTheme: { name, tokens },   // the site's own colours; missing tokens are filled in
+  themes: [{ id, name, tokens }],   // optional extra themes made for the site
+  usage: { primary: 'Buttons…' },   // optional notes shown in the colour editors
+  scrollbars: true,                 // colour the page's scrollbars from the theme (default)
+  pdf: loadPdf,                     // optional: allow PDF uploads (see below)
+}
+```
+
+### PDF uploads
+
+Building a palette from an image works out of the box. PDFs, such as brand guides, need [PDF.js](https://mozilla.github.io/pdf.js/), which is large, so it's opt-in: install it and pass the loader from `colorsbymax/pdf`.
+
+```bash
+npm install pdfjs-dist
+```
+
+```jsx
+import { loadPdf } from 'colorsbymax/pdf'
+
+<ThemeProvider config={{ ...config, pdf: loadPdf }}>
+```
+
+PDF.js still downloads only when a visitor picks a PDF. Sites that don't opt in never install or bundle it, and the upload offers images only.
+
+`examples/tsungi.config.js` is a complete example for tsungi.online, the first site to use colorsbymax.
+
+## Building the package
+
+`src/` is the source; `dist/` is what sites install: plain JavaScript with the JSX compiled away. `types/` holds the hand-written TypeScript declarations; `npm run typecheck` compiles `types/check.tsx` against them and checks they match the built exports. The panel's icons are copied from Lucide into `src/icons.jsx` by `npm run icons`. `dist/` is committed so installs straight from GitHub work even when npm skips install scripts, so rebuild it before committing changes to `src/`. `npm publish` also rebuilds it first:
+
+```bash
+npm run build
+```
+
+## Panel styles
+
+The panel is styled with Tailwind classes in `src/ThemePanel.jsx` and `src/ThemeSwitcher.jsx`. `scripts/build-css.mjs` compiles them, with `src/panel.css`, into `src/panel-css.generated.js`. The demo server does this automatically as you edit; otherwise run:
+
+```bash
+npm run css
+```
+
+## Regenerating the library
+
+```bash
+npm run presets
+```
+
+`scripts/generate-presets.mjs` turns each source palette into a full theme, auto-fixes contrast, drops anything that still fails or duplicates another theme, names it and tags its categories. Adjust the category rules at the top of the script.
+
+## Notices
+
+The library palettes come from [nice-color-palettes](https://github.com/Jam3/nice-color-palettes) (MIT). Its licence notice is in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and must ship with every copy.
+
+PDF reading uses [pdfjs-dist](https://github.com/mozilla/pdf.js) (Apache-2.0), installed as a dependency rather than bundled into colorsbymax.
+
+## Licence
+
+colorsbymax is released under the [MIT Licence](LICENSE). The names colorsbymax™ and mrmaxdesigns are marks of Max Muyalwa and aren't covered by the code licence.

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-party notices
 
-colorsbymax™ includes material from the following project. Its licence requires this notice to ship with every copy of the product.
+colorsbymax™ includes material from the following projects. Their licences require these notices to ship with every copy of the product.
 
 ## nice-color-palettes
 
@@ -29,3 +29,49 @@ OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
 OR OTHER DEALINGS IN THE SOFTWARE.
 
 ```
+
+## Lucide
+
+The switcher's icons (`src/icons.jsx`) are copied from [Lucide](https://lucide.dev), generated from lucide-react by `scripts/build-icons.mjs`. Some Lucide icons derive from [Feather](https://feathericons.com); of those used here, that's arrow-left, check, chevron-right, download, monitor, moon, trash, upload and x, covered by the MIT notice below.
+
+```
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```
+
+```
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/dist/index.js

@@ -1,7 +1,6 @@
-import { createContext, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { createContext, createElement, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { createPortal } from "react-dom";
-import { AlertTriangle, ArrowLeft, Check, CheckCircle2, ChevronRight, Copy, Download, Globe, ImageUp, Loader2, Monitor, Moon, Paintbrush, Palette, RotateCcw, ScanLine, Settings, Shuffle, Sun, Trash2, Upload, UserRound, Wand2, X } from "lucide-react";
 //#region src/color.js
 var HEX_RE = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i;
 /** Normalises "#abc", "abc", "#AABBCC" to "#aabbcc"; returns null for anything else. */
@@ -1062,6 +1061,9 @@ function createColorParser() {
 * colours. Everything happens synchronously, so nothing repaints in between.
 */
 function withoutAppliedTheme(fn) {
+	const freeze = document.createElement("style");
+	freeze.textContent = "*,*::before,*::after{transition:none!important}";
+	document.head.appendChild(freeze);
 	const style = document.documentElement.style;
 	const saved = [];
 	for (let i = style.length - 1; i >= 0; i--) {
@@ -1075,6 +1077,9 @@ function withoutAppliedTheme(fn) {
 		return fn();
 	} finally {
 		for (const [prop, value] of saved) style.setProperty(prop, value);
+		getComputedStyle(document.documentElement).color;
+		document.body.offsetHeight;
+		freeze.remove();
 	}
 }
 /**
@@ -1423,6 +1428,7 @@ var newId = () => `custom-${Date.now().toString(36)}-${Math.random().toString(36
 * @property {Partial<Record<import('./tokens.js').TokenKey, string>>} [usage]
 *   Where each token is used on this site, shown in the editors
 * @property {boolean} [scrollbars]  Colour the page's scrollbars from the theme (default true)
+* @property {() => Promise<any>} [pdf]  Enables PDF uploads: pass `loadPdf` from 'colorsbymax/pdf'
 */
 /** Resolves a config into the site theme group. The shipped default always comes first. */
 function resolveSite(config) {
@@ -1529,6 +1535,7 @@ function ThemeProvider({ config = {}, children }) {
 		storageKey,
 		siteName,
 		usage: config.usage ?? {},
+		loadPdf: config.pdf ?? null,
 		siteThemes,
 		defaultTheme,
 		presets: PRESETS,
@@ -1683,6 +1690,193 @@ function useTheme() {
 	if (!ctx) throw new Error("useTheme must be used inside <ThemeProvider>");
 	return ctx;
 }
+//#endregion
+//#region src/icons.jsx
+/** A Lucide-style icon: 24×24, drawn with currentColor strokes, sized by className. */
+function icon(slug, shapes) {
+	const Icon = ({ className = "", ...props }) => /* @__PURE__ */ jsx("svg", {
+		xmlns: "http://www.w3.org/2000/svg",
+		width: "24",
+		height: "24",
+		viewBox: "0 0 24 24",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		className: `lucide lucide-${slug} ${className}`.trim(),
+		...props,
+		children: shapes.map(([tag, attrs], i) => createElement(tag, {
+			key: i,
+			...attrs
+		}))
+	});
+	Icon.displayName = slug;
+	return Icon;
+}
+var AlertTriangle = icon("triangle-alert", [
+	["path", { "d": "m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" }],
+	["path", { "d": "M12 9v4" }],
+	["path", { "d": "M12 17h.01" }]
+]);
+var ArrowLeft = icon("arrow-left", [["path", { "d": "m12 19-7-7 7-7" }], ["path", { "d": "M19 12H5" }]]);
+var Check = icon("check", [["path", { "d": "M20 6 9 17l-5-5" }]]);
+var CheckCircle2 = icon("circle-check", [["circle", {
+	"cx": "12",
+	"cy": "12",
+	"r": "10"
+}], ["path", { "d": "m16 9-5.5 5.5L8 12" }]]);
+var ChevronRight = icon("chevron-right", [["path", { "d": "m9 18 6-6-6-6" }]]);
+var Copy = icon("copy", [["rect", {
+	"width": "14",
+	"height": "14",
+	"x": "8",
+	"y": "8",
+	"rx": "2",
+	"ry": "2"
+}], ["path", { "d": "M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" }]]);
+var Download = icon("download", [
+	["path", { "d": "M12 15V3" }],
+	["path", { "d": "M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" }],
+	["path", { "d": "m7 10 5 5 5-5" }]
+]);
+var Globe = icon("globe", [
+	["circle", {
+		"cx": "12",
+		"cy": "12",
+		"r": "10"
+	}],
+	["path", { "d": "M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20" }],
+	["path", { "d": "M2 12h20" }]
+]);
+var ImageUp = icon("image-up", [
+	["path", { "d": "M10.3 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2v10l-3.1-3.1a2 2 0 0 0-2.814.014L6 21" }],
+	["path", { "d": "m14 19.5 3-3 3 3" }],
+	["path", { "d": "M17 22v-5.5" }],
+	["circle", {
+		"cx": "9",
+		"cy": "9",
+		"r": "2"
+	}]
+]);
+var Loader2 = icon("loader-circle", [["path", { "d": "M21 12a9 9 0 1 1-6.219-8.56" }]]);
+var Monitor = icon("monitor", [
+	["rect", {
+		"width": "20",
+		"height": "14",
+		"x": "2",
+		"y": "3",
+		"rx": "2"
+	}],
+	["line", {
+		"x1": "8",
+		"x2": "16",
+		"y1": "21",
+		"y2": "21"
+	}],
+	["line", {
+		"x1": "12",
+		"x2": "12",
+		"y1": "17",
+		"y2": "21"
+	}]
+]);
+var Moon = icon("moon", [["path", { "d": "M20.985 12.486a9 9 0 1 1-9.473-9.472c.405-.022.617.46.402.803a6 6 0 0 0 8.268 8.268c.344-.215.825-.004.803.401" }]]);
+var Paintbrush = icon("paintbrush", [
+	["path", { "d": "m14.622 17.897-10.68-2.913" }],
+	["path", { "d": "M18.376 2.622a1 1 0 1 1 3.002 3.002L17.36 9.643a.5.5 0 0 0 0 .707l.944.944a2.41 2.41 0 0 1 0 3.408l-.944.944a.5.5 0 0 1-.707 0L8.354 7.348a.5.5 0 0 1 0-.707l.944-.944a2.41 2.41 0 0 1 3.408 0l.944.944a.5.5 0 0 0 .707 0z" }],
+	["path", { "d": "M9 8c-1.804 2.71-3.97 3.46-6.583 3.948a.507.507 0 0 0-.302.819l7.32 8.883a1 1 0 0 0 1.185.204C12.735 20.405 16 16.792 16 15" }]
+]);
+var Palette = icon("palette", [
+	["path", { "d": "M12 22a1 1 0 0 1 0-20 10 9 0 0 1 10 9 5 5 0 0 1-5 5h-2.25a1.75 1.75 0 0 0-1.4 2.8l.3.4a1.75 1.75 0 0 1-1.4 2.8z" }],
+	["circle", {
+		"cx": "13.5",
+		"cy": "6.5",
+		"r": ".5",
+		"fill": "currentColor"
+	}],
+	["circle", {
+		"cx": "17.5",
+		"cy": "10.5",
+		"r": ".5",
+		"fill": "currentColor"
+	}],
+	["circle", {
+		"cx": "6.5",
+		"cy": "12.5",
+		"r": ".5",
+		"fill": "currentColor"
+	}],
+	["circle", {
+		"cx": "8.5",
+		"cy": "7.5",
+		"r": ".5",
+		"fill": "currentColor"
+	}]
+]);
+var RotateCcw = icon("rotate-ccw", [["path", { "d": "M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8" }], ["path", { "d": "M3 3v5h5" }]]);
+var ScanLine = icon("scan-line", [
+	["path", { "d": "M3 7V5a2 2 0 0 1 2-2h2" }],
+	["path", { "d": "M17 3h2a2 2 0 0 1 2 2v2" }],
+	["path", { "d": "M21 17v2a2 2 0 0 1-2 2h-2" }],
+	["path", { "d": "M7 21H5a2 2 0 0 1-2-2v-2" }],
+	["path", { "d": "M7 12h10" }]
+]);
+var Settings = icon("settings", [["path", { "d": "M9.671 4.136a2.34 2.34 0 0 1 4.659 0 2.34 2.34 0 0 0 3.319 1.915 2.34 2.34 0 0 1 2.33 4.033 2.34 2.34 0 0 0 0 3.831 2.34 2.34 0 0 1-2.33 4.033 2.34 2.34 0 0 0-3.319 1.915 2.34 2.34 0 0 1-4.659 0 2.34 2.34 0 0 0-3.32-1.915 2.34 2.34 0 0 1-2.33-4.033 2.34 2.34 0 0 0 0-3.831A2.34 2.34 0 0 1 6.35 6.051a2.34 2.34 0 0 0 3.319-1.915" }], ["circle", {
+	"cx": "12",
+	"cy": "12",
+	"r": "3"
+}]]);
+var Shuffle = icon("shuffle", [
+	["path", { "d": "m18 14 4 4-4 4" }],
+	["path", { "d": "m18 2 4 4-4 4" }],
+	["path", { "d": "M2 18h1.973a4 4 0 0 0 3.3-1.7l5.454-8.6a4 4 0 0 1 3.3-1.7H22" }],
+	["path", { "d": "M2 6h1.972a4 4 0 0 1 3.6 2.2" }],
+	["path", { "d": "M22 18h-6.041a4 4 0 0 1-3.3-1.8l-.359-.45" }]
+]);
+var Sun = icon("sun", [
+	["circle", {
+		"cx": "12",
+		"cy": "12",
+		"r": "4"
+	}],
+	["path", { "d": "M12 2v2" }],
+	["path", { "d": "M12 20v2" }],
+	["path", { "d": "m4.93 4.93 1.41 1.41" }],
+	["path", { "d": "m17.66 17.66 1.41 1.41" }],
+	["path", { "d": "M2 12h2" }],
+	["path", { "d": "M20 12h2" }],
+	["path", { "d": "m6.34 17.66-1.41 1.41" }],
+	["path", { "d": "m19.07 4.93-1.41 1.41" }]
+]);
+var Trash2 = icon("trash", [
+	["path", { "d": "M10 11v6" }],
+	["path", { "d": "M14 11v6" }],
+	["path", { "d": "M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6" }],
+	["path", { "d": "M3 6h18" }],
+	["path", { "d": "M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2" }]
+]);
+var Upload = icon("upload", [
+	["path", { "d": "M12 3v12" }],
+	["path", { "d": "m17 8-5-5-5 5" }],
+	["path", { "d": "M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" }]
+]);
+var UserRound = icon("user-round", [["circle", {
+	"cx": "12",
+	"cy": "8",
+	"r": "5"
+}], ["path", { "d": "M20 21a8 8 0 0 0-16 0" }]]);
+var Wand2 = icon("wand-sparkles", [
+	["path", { "d": "m21.64 3.64-1.28-1.28a1.21 1.21 0 0 0-1.72 0L2.36 18.64a1.21 1.21 0 0 0 0 1.72l1.28 1.28a1.2 1.2 0 0 0 1.72 0L21.64 5.36a1.2 1.2 0 0 0 0-1.72" }],
+	["path", { "d": "m14 7 3 3" }],
+	["path", { "d": "M5 6v4" }],
+	["path", { "d": "M19 14v4" }],
+	["path", { "d": "M10 2v2" }],
+	["path", { "d": "M7 8H3" }],
+	["path", { "d": "M21 16h-4" }],
+	["path", { "d": "M11 3H9" }]
+]);
+var X = icon("x", [["path", { "d": "M18 6 6 18" }], ["path", { "d": "m6 6 12 12" }]]);
 /** Images are scaled down to at most this many pixels on their longest side before sampling. */
 var SAMPLE_SIZE = 200;
 /** PDF pages read, from the first. */
@@ -1698,12 +1892,16 @@ var hslOf = (hex) => rgbToHsl(hexToRgb(hex));
 /**
 * The main colours in an image or PDF, most important first.
 * @param {File} file
+* @param {{ loadPdf?: (() => Promise<any>) | null }} [options]  PDF support, from 'colorsbymax/pdf'
 * @returns {Promise<{ colours: string[], from: 'image' | 'pdf-text' | 'pdf' }>}
 */
-async function coloursFromFile(file) {
+async function coloursFromFile(file, { loadPdf = null } = {}) {
 	if (file.size > 26214400) throw new Error("That file is over 25 MB. Try a smaller one.");
-	if (file.type === "application/pdf" || /\.pdf$/i.test(file.name)) return coloursFromPdf(file);
-	if (!file.type.startsWith("image/")) throw new Error("Choose an image (PNG, JPG, WebP, SVG…) or a PDF.");
+	if (file.type === "application/pdf" || /\.pdf$/i.test(file.name)) {
+		if (!loadPdf) throw new Error("PDFs aren’t supported on this site. Try an image of the palette instead.");
+		return coloursFromPdf(file, loadPdf);
+	}
+	if (!file.type.startsWith("image/")) throw new Error(`Choose an image (PNG, JPG, WebP, SVG…)${loadPdf ? " or a PDF" : ""}.`);
 	const bitmap = await loadImage(file);
 	return {
 		colours: dominantColours([pixelsOf(bitmap, bitmap.width, bitmap.height)]),
@@ -1789,11 +1987,10 @@ function isEdgeBlend(m, kept) {
 	}
 	return false;
 }
-async function coloursFromPdf(file) {
+async function coloursFromPdf(file, loadPdf) {
 	let pdfjs;
 	try {
-		pdfjs = await import("pdfjs-dist");
-		await import("pdfjs-dist/build/pdf.worker.min.mjs");
+		pdfjs = await loadPdf();
 	} catch {
 		throw new Error("Couldn’t load the PDF reader. Check your connection and try again.");
 	}
@@ -2847,7 +3044,7 @@ function PresetGrid() {
 				children: loadError ? "Couldn’t load the theme library. Check your connection and reopen the panel." : "Loading themes…"
 			}) : visible.length === 0 && !q && category === "yours" ? /* @__PURE__ */ jsx("p", {
 				className: "rounded-xl border border-dashed border-zinc-300 px-4 py-5 text-center text-xs text-zinc-600",
-				children: "Nothing here yet. Palettes you create in Custom palettes, import, or build from an image or PDF in Import / export are saved here."
+				children: "Nothing here yet. Palettes you create in Custom palettes, import, or build from a file in Import / export are saved here."
 			}) : visible.length === 0 ? /* @__PURE__ */ jsxs("p", {
 				className: "py-6 text-center text-xs text-zinc-600",
 				role: "status",
@@ -3296,9 +3493,10 @@ var FROM_NOTE = {
 	pdf: "Picked from the colours on the first pages.",
 	"pdf-text": "Found colour codes written in the PDF."
 };
-/** Builds a custom palette from the colours in an uploaded image or PDF. */
+/** Builds a custom palette from the colours in an uploaded image, or a PDF where the site allows it. */
 function PaletteFromFile() {
-	const { addPalette } = useTheme();
+	const { addPalette, loadPdf } = useTheme();
+	const kinds = loadPdf ? "image or PDF" : "image";
 	const savedToYours = useSavedToYours();
 	const [busy, setBusy] = useState(false);
 	const [error, setError] = useState(null);
@@ -3315,7 +3513,7 @@ function PaletteFromFile() {
 		setBusy(true);
 		setError(null);
 		try {
-			const { colours, from } = await coloursFromFile(file);
+			const { colours, from } = await coloursFromFile(file, { loadPdf });
 			if (!colours.length) throw new Error("Couldn’t find any colours in that file.");
 			setFound({
 				fileName: file.name,
@@ -3339,9 +3537,9 @@ function PaletteFromFile() {
 	return /* @__PURE__ */ jsxs("div", {
 		className: "space-y-1.5",
 		children: [
-			/* @__PURE__ */ jsx("p", {
+			/* @__PURE__ */ jsxs("p", {
 				className: "text-xs font-medium text-zinc-700",
-				children: "Palette from an image or PDF"
+				children: ["Palette from an ", kinds]
 			}),
 			/* @__PURE__ */ jsxs("div", {
 				onDragOver: (e) => {
@@ -3368,16 +3566,20 @@ function PaletteFromFile() {
 						}) : /* @__PURE__ */ jsx(ImageUp, {
 							className: "w-3.5 h-3.5",
 							"aria-hidden": "true"
-						}), busy ? "Reading colours…" : "Choose image or PDF…"]
+						}), busy ? "Reading colours…" : `Choose ${kinds}…`]
 					}),
-					/* @__PURE__ */ jsx("p", {
+					/* @__PURE__ */ jsxs("p", {
 						className: "mt-1.5 text-[11px] text-zinc-600",
-						children: "or drop one here. A mood board, screenshot, photo or brand guide works."
+						children: [
+							"or drop one here. A mood board, screenshot or photo",
+							loadPdf ? ", or a brand guide PDF," : "",
+							" works."
+						]
 					}),
 					/* @__PURE__ */ jsx("input", {
 						ref: fileRef,
 						type: "file",
-						accept: "image/*,application/pdf,.pdf",
+						accept: loadPdf ? "image/*,application/pdf,.pdf" : "image/*",
 						className: "sr-only",
 						tabIndex: -1,
 						"aria-hidden": "true",

package/dist/pdf.js

@@ -0,0 +1,9 @@
+//#region src/pdf.js
+/** Loads PDF.js, running it on the page so there's no separate worker file to host. */
+async function loadPdf() {
+	const pdfjs = await import("pdfjs-dist");
+	await import("pdfjs-dist/build/pdf.worker.min.mjs");
+	return pdfjs;
+}
+//#endregion
+export { loadPdf };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "colorsbymax",
-  "version": "0.1.0",
-  "description": "colorsbymax™ by mrmaxdesigns: a runtime theme switcher with presets, a 715-theme library, custom palettes and WCAG contrast checks.",
+  "version": "0.1.1",
+  "description": "A live theme switcher for any website: site themes, 700+ palettes, for light/dark modes and WCAG contrast checks.",
   "keywords": [
     "theme",
     "theme-switcher",
@@ -25,19 +25,38 @@
     "url": "https://github.com/MaxMuyalwa/colorsbymax/issues"
   },
   "type": "module",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./types/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "pdf": [
+        "./types/pdf.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
+      "types": "./types/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./pdf": {
+      "types": "./types/pdf.d.ts",
+      "import": "./dist/pdf.js",
+      "default": "./dist/pdf.js"
+    },
     "./tokens.css": "./src/tokens.css",
     "./package.json": "./package.json"
   },
   "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
   "files": [
     "dist",
+    "types/index.d.ts",
+    "types/pdf.d.ts",
     "src/tokens.css",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md"
@@ -45,27 +64,36 @@
   "scripts": {
     "dev": "vite",
     "build": "node scripts/build-css.mjs && vite build --config vite.lib.config.js",
-    "prepare": "vite build --config vite.lib.config.js",
+    "typecheck": "tsc -p types && node scripts/check-types.mjs",
+    "prepublishOnly": "npm run build && npm run typecheck",
     "build:demo": "vite build",
     "css": "node scripts/build-css.mjs",
+    "icons": "node scripts/build-icons.mjs",
     "presets": "node scripts/generate-presets.mjs"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",
-    "react-dom": "^18.2.0 || ^19.0.0"
+    "react-dom": "^18.2.0 || ^19.0.0",
+    "pdfjs-dist": ">=4"
   },
-  "dependencies": {
-    "lucide-react": "^1.48.0",
-    "pdfjs-dist": "^6.3.289"
+  "peerDependenciesMeta": {
+    "pdfjs-dist": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@tailwindcss/cli": "^4.3.3",
     "@tailwindcss/vite": "^4.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@vitejs/plugin-react": "^6.1.1",
+    "lucide-react": "^1.48.0",
     "nice-color-palettes": "^4.0.0",
+    "pdfjs-dist": "^6.3.289",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "tailwindcss": "^4.3.3",
+    "typescript": "^5.9.3",
     "vite": "^8.3.1"
   },
   "license": "MIT"

package/types/index.d.ts

@@ -0,0 +1,271 @@
+// Type declarations for colorsbymax. The package is written in JavaScript; these describe its
+// public API and are checked against real usage by types/check.tsx (npm run typecheck).
+
+import type { ReactElement, ReactNode } from 'react'
+
+// ---------------------------------------------------------------- tokens and themes
+
+/** Every themeable colour. Each is exposed to CSS as `--color-<key>`. */
+export type TokenKey =
+  | 'primary' | 'primary-dark' | 'primary-alt' | 'on-primary'
+  | 'background' | 'surface' | 'secondary' | 'on-secondary' | 'accent' | 'on-accent' | 'border' | 'shadow'
+  | 'ink' | 'ink-secondary' | 'ink-muted'
+  | 'success' | 'warning' | 'danger' | 'info'
+  | 'data-1' | 'data-2' | 'data-3' | 'data-4' | 'data-5' | 'data-6' | 'data-7' | 'data-8'
+  | 'app-background' | 'app-input' | 'app-border' | 'app-primary' | 'app-shadow-dark' | 'app-shadow-light' | 'app-ink' | 'app-ink-muted'
+
+/** Token key → `"#rrggbb"`. */
+export type ThemeTokens = Record<TokenKey, string>
+
+export interface Theme {
+  id: string
+  name: string
+  tokens: ThemeTokens
+  /** A palette the visitor created or imported. */
+  custom?: boolean
+  /** From the generated library. */
+  library?: boolean
+  /** One of the host site's own themes (including scan suggestions). */
+  site?: boolean
+  /** Suggested by a site scan. */
+  scanned?: boolean
+  /** A generated dark twin of a light theme. */
+  derived?: boolean
+  /** Library categories, for library themes. */
+  tags?: string[]
+}
+
+export interface TokenGroup {
+  group: string
+  tokens: { key: TokenKey; label: string; usage: string }[]
+}
+
+export const TOKEN_GROUPS: TokenGroup[]
+export const TOKEN_KEYS: TokenKey[]
+/** The neutral default theme's tokens (Slate). */
+export const BASE_TOKENS: ThemeTokens
+/** The hand-tuned themes shown as "Max's picks". */
+export const PRESETS: Theme[]
+
+/** Fills missing tokens from `base` (the neutral default unless given), deriving the secondary-area ones. */
+export function completeTokens(partial: Partial<ThemeTokens>, base?: ThemeTokens): ThemeTokens
+/** Derives the secondary-area (`app-*`) tokens from a theme's main palette. */
+export function deriveAppTokens(tokens: ThemeTokens): Pick<ThemeTokens, Extract<TokenKey, `app-${string}`>>
+
+// ---------------------------------------------------------------- React API
+
+export interface ColorsByMaxConfig {
+  /** Name of the first theme group, e.g. "Tsungi". Detected from the page if left out. */
+  siteName?: string
+  /** localStorage key; must match the pre-paint script. Defaults to "colorsbymax". */
+  storageKey?: string
+  /** The site's own colours. Missing tokens are filled in. */
+  defaultTheme?: { name: string; tokens: Partial<ThemeTokens> }
+  /** Extra themes made for the site. */
+  themes?: { id: string; name: string; tokens: Partial<ThemeTokens> }[]
+  /** Where each token is used on the site, shown in the colour editors. */
+  usage?: Partial<Record<TokenKey, string>>
+  /** Colour the page's scrollbars from the theme. Default true. */
+  scrollbars?: boolean
+  /** Enables PDF uploads: pass `loadPdf` from 'colorsbymax/pdf' (needs pdfjs-dist installed). */
+  pdf?: () => Promise<unknown>
+}
+
+export interface ThemeProviderProps {
+  config?: ColorsByMaxConfig
+  children?: ReactNode
+}
+
+/** Applies the saved or chosen theme to the page and provides it to the switcher and useTheme(). */
+export function ThemeProvider(props: ThemeProviderProps): ReactElement
+
+/** The floating colour button and panel. Render it once, inside ThemeProvider. */
+export function ThemeSwitcher(): ReactElement | null
+
+export interface ScanResult {
+  at: number
+  palette: string[]
+  themes: Theme[]
+}
+
+export interface ThemeState {
+  activeId: string
+  overrides: Partial<ThemeTokens>
+  customs: Theme[]
+  snapshot: Pick<Theme, 'id' | 'name' | 'tokens'> | null
+  scanned: ScanResult | null
+}
+
+export interface ThemeApi {
+  state: ThemeState
+  storageKey: string
+  siteName: string
+  usage: Partial<Record<TokenKey, string>>
+  loadPdf: (() => Promise<unknown>) | null
+  /** The site's own themes, then any scan suggestions. */
+  siteThemes: Theme[]
+  defaultTheme: Theme
+  presets: Theme[]
+  customs: Theme[]
+  /** Site themes, presets and custom palettes (not the library). */
+  themes: Theme[]
+  /** The applied theme. */
+  active: Theme
+  /** The applied colours: the active theme plus any overrides. */
+  tokens: ThemeTokens
+  /** Contrast problems in the applied colours. */
+  issues: ContrastIssue[]
+
+  /** Selects a theme by id; pass the theme itself for library themes and dark twins. */
+  selectTheme(id: string, theme?: Theme): void
+  /** Creates a custom palette from the current colours and applies it. Returns its id. */
+  createCustom(name: string): string
+  updateCustomToken(id: string, key: TokenKey, value: string): void
+  renameCustom(id: string, name: string): void
+  deleteCustom(id: string): void
+  /** Adds tokens as a new custom palette and applies it. Returns its id. */
+  addPalette(name: string, tokens: Partial<ThemeTokens>): string
+
+  setOverride(key: TokenKey, value: string): void
+  clearOverride(key: TokenKey): void
+  clearOverrides(): void
+  resetToDefault(): void
+
+  scanned: ScanResult | null
+  /** Reads the page's colours and adds themes built around them. Resolves to counts for the UI. */
+  runScan(): Promise<{ colours: number; themes: number }>
+  clearScan(): void
+
+  /** Fixes one issue by adjusting lightness. Returns false if no single change could. */
+  fixIssue(issue: ContrastIssue): boolean
+  fixAllIssues(): void
+
+  /** The applied theme as `{ name, tokens }` JSON. */
+  exportTheme(): string
+  /** Imports `{ name, tokens }` JSON as a custom palette. Returns an error message, or null. */
+  importTheme(json: string): string | null
+}
+
+/** The theme state and actions. Must be called inside ThemeProvider. */
+export function useTheme(): ThemeApi
+
+/** Writes each token to `--color-<key>` on `<html>`. */
+export function applyTokens(tokens: ThemeTokens): void
+
+// ---------------------------------------------------------------- pre-paint and settings
+
+export const DEFAULT_STORAGE_KEY: 'colorsbymax'
+/** Source of an inline `<script>` for `<head>` that applies the saved theme before first paint. */
+export function prePaintScript(storageKey?: string): string
+
+export interface PanelSettings {
+  mode: 'light' | 'dark' | 'system'
+  showPicks: boolean
+  showLibrary: boolean
+  showCustom: boolean
+  showOverrides: boolean
+  showImportExport: boolean
+  draggable: boolean
+  animateDot: boolean
+  panelWidth: number | null
+  panelHeight: number | 'full' | null
+  libraryCollapsed: boolean
+}
+/** The visitor settings the panel starts with. */
+export const DEFAULT_SETTINGS: PanelSettings
+
+// ---------------------------------------------------------------- contrast
+
+export type PairingKind = 'text' | 'large-text' | 'non-text'
+
+export interface Pairing {
+  id: string
+  label: string
+  kind: PairingKind
+  fg(tokens: ThemeTokens): string
+  bg(tokens: ThemeTokens): string
+  /** Tokens auto-fix may adjust, in preference order. */
+  fixable: TokenKey[]
+}
+
+export interface ContrastIssue {
+  pairing: Pairing
+  ratio: number
+  required: number
+  /** e.g. "Primary text on background: 2.7:1 — text will be hard to read (needs 4.5:1)" */
+  message: string
+}
+
+/** Every foreground/background pairing colorsbymax checks. */
+export const PAIRINGS: Pairing[]
+export const MIN_CONTRAST_TEXT: number
+export const MIN_CONTRAST_LARGE_TEXT: number
+export const MIN_CONTRAST_NON_TEXT: number
+export const MIN_RAMP_STEP_DELTA_E: number
+
+/** Every failing pairing in a theme. */
+export function checkTheme(tokens: ThemeTokens): ContrastIssue[]
+/** The smallest lightness change to one token that makes a pairing pass, or null. */
+export function suggestFix(pairing: Pairing, tokens: ThemeTokens): { key: TokenKey; value: string } | null
+/** Fixes failing pairings until the theme passes or nothing more helps. Returns the changed tokens. */
+export function fixAll(tokens: ThemeTokens): Partial<ThemeTokens>
+/** Problems with an ordered colour ramp drawn on `surface`, as sentences. */
+export function checkRamp(colors: string[], surface: string): string[]
+
+// ---------------------------------------------------------------- colour helpers
+
+/** WCAG 2 contrast ratio between two hex colours, 1–21. */
+export function contrastRatio(a: string, b: string): number
+/** "#abc", "abc" or "#AABBCC" → "#aabbcc"; null for anything else. */
+export function normalizeHex(input: unknown): string | null
+
+// ---------------------------------------------------------------- light and dark
+
+/** True when a theme's page background is dark. */
+export function isDarkTheme(tokens: ThemeTokens): boolean
+/** Dark versions of a light theme's tokens, adjusted to pass contrast. */
+export function darkTokens(tokens: ThemeTokens): ThemeTokens
+/** The dark twin of a light theme (themes that are already dark come back unchanged). */
+export function toDark<T extends Theme>(theme: T): T
+
+// ---------------------------------------------------------------- site scan
+
+export interface ColourTally {
+  hex: string
+  /** Area painted as a background. */
+  bg: number
+  /** Weighted amount of text in this colour. */
+  text: number
+  /** Border length in this colour. */
+  border: number
+}
+
+export type Roles = Partial<Record<TokenKey, string>>
+
+/** The page's painted colours, ignoring any applied theme. `exclude` is a selector to skip. */
+export function collectColors(options?: { exclude?: string }): ColourTally[]
+/** Works out token roles from collected colours. */
+export function inferRoles(colors: ColourTally[]): { roles: Roles; palette: string[] }
+/** A complete theme from detected roles, deriving whatever wasn't found. */
+export function themeFromRoles(
+  roles: Roles,
+  variant?: { softness?: number; boldness?: number; complementary?: boolean },
+): ThemeTokens
+/** Themes suggested for a scanned site, named after it, plus the closest library themes. */
+export function suggestThemes(scan: { roles: Roles }, siteName: string, library?: Theme[]): Theme[]
+/** Best guess at the site's name: og:site_name, then the title, then the host. */
+export function detectSiteName(doc?: Document): string
+
+// ---------------------------------------------------------------- palettes from files
+
+/** The main colours in an image (or a PDF, with `loadPdf`), most important first. */
+export function coloursFromFile(
+  file: File,
+  options?: { loadPdf?: (() => Promise<unknown>) | null },
+): Promise<{ colours: string[]; from: 'image' | 'pdf-text' | 'pdf' }>
+/** The dominant colours in sets of RGBA pixels, edge blends removed. */
+export function dominantColours(pixelSets: Uint8ClampedArray[]): string[]
+/** Assigns a palette's colours to theme roles. */
+export function rolesFromPalette(colours: string[]): Roles
+/** A complete, contrast-checked theme built around a palette. */
+export function themeFromPalette(colours: string[]): ThemeTokens

package/types/pdf.d.ts

@@ -0,0 +1,7 @@
+// Type declarations for 'colorsbymax/pdf'.
+
+/**
+ * Loads PDF.js for PDF uploads. Pass it as `pdf` in the ThemeProvider config; needs the
+ * pdfjs-dist package installed. PDF.js downloads only when a visitor picks a PDF.
+ */
+export function loadPdf(): Promise<unknown>