colorsbymax 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+What changed in each colorsbymax release. Update with `npm install colorsbymax@latest`.
+
+## 0.2.0 (2026-09-25)
+
+**Upgrading from 0.1.x:** the colour button moves to the bottom-right corner; add `position: 'top-right'` to keep it where it was. If your site doesn't use colorsbymax's `--color-*` variables, themes now re-colour it automatically; to keep the old behaviour (themes set only the variables), pass `recolour: false` in the config.
+
+- **One-line setup.** `import 'colorsbymax/auto'` puts the colour button on the page with no wrapping or config. `autoMount(config)` from the same entry takes settings.
+- **Re-colours any site.** Sites with hard-coded colours are re-coloured by swapping the colours actually on the page for the chosen theme's, including gradients, borders and SVG icons, and content that appears later. Sites that use the colour variables work exactly as before.
+- **The colour button now starts in the bottom-right corner**, where chat and help widgets usually sit, and the panel opens above it. `position` picks another corner; `position: 'top-right'` keeps 0.1's spot just under a floating nav bar. Visitors can still drag it anywhere.
+- The site's own group shows its original colours ("… original") when colorsbymax is re-colouring it.
+
+## 0.1.1 (2026-09-25)
+
+**Upgrading from 0.1.0:** nothing to change for most sites. The one exception: PDF uploads are now opt-in. To keep them, install `pdfjs-dist` and pass the loader in your config:
+
+```bash
+npm install pdfjs-dist
+```
+
+```jsx
+import { loadPdf } from 'colorsbymax/pdf'
+
+<ThemeProvider config={{ ...config, pdf: loadPdf }}>
+```
+
+Without it, "Palette from an image" still works; it just takes images only. If you call `coloursFromFile` yourself, pass `{ loadPdf }` as its second argument for PDFs.
+
+- **TypeScript types included.** No more "Could not find a declaration file for module 'colorsbymax'" (TS7016) in strict projects; `useTheme()`, the config and the colour helpers are fully typed.
+- **Much smaller install.** No runtime dependencies besides React: about 440 KB instead of 44 MB. The panel's icons are built in, so it no longer adds a second copy of `lucide-react` next to your own, and PDF.js is no longer installed unless you opt in.
+- **No install scripts**, so npm has nothing to ask you to approve for colorsbymax.
+- Site scans ignore colour transitions, so sites that animate colour changes scan their own colours rather than the applied theme's.
+- README: an "At a glance" section (Tailwind is optional, ESM only, types included) and PDF opt-in docs.
+
+## 0.1.0 (2026-09-25)
+
+First release: the floating colour button and panel, site themes and scan, Max's picks and the 715-theme library, custom palettes, overrides, JSON import/export, palettes from images and PDFs, light and dark mode, visitor settings, and WCAG contrast checks with one-click fixes.

package/README.md

@@ -6,7 +6,8 @@ A floating theme switcher for websites. Visitors (or the site's owner) can re-co
 
 **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)).
+- **Two steps.** `npm install colorsbymax`, then `import 'colorsbymax/auto'` once. The colour button appears and visitors can re-colour the site, even if its colours are hard-coded (see [Quick start](#quick-start)).
+- **React 18 or 19.**
 - **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)).
@@ -44,17 +45,37 @@ 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.
+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); `/plain.html`, a plain-CSS bakery site with deliberately careless global styles to show they don't reach the panel; and `/unwired.html`, a coffee shop with only hard-coded colours whose whole setup is `import 'colorsbymax/auto'`.
 
-## Add it to a site
-
-colorsbymax needs React 18 or 19:
+## Quick start
 
 ```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:
+Then add one line anywhere in your site's code, for example `main.jsx`:
+
+```js
+import 'colorsbymax/auto'
+```
+
+That's all. The colour button appears in the bottom-right corner once the page has loaded, and visitors can start swapping the site's colours. (npm doesn't let a package change your site on install, so this one line is the only step.)
+
+- **Any site's colours.** If your site doesn't use colorsbymax's colour variables, colorsbymax reads the colours actually on the page (backgrounds, text, borders, gradients and icons) and swaps each for its counterpart in the chosen theme: greys follow the theme's background and text, brand shades follow its brand colour, and success and error colours keep their meaning. Content added later is re-coloured too, and picking the site's own theme brings back the exact original.
+- **Settings.** Use `autoMount` instead of the plain import:
+
+  ```js
+  import { autoMount } from 'colorsbymax/auto'
+  autoMount({ siteName: 'My site', storageKey: 'my-site-theme' })
+  ```
+
+- **Where automatic re-colouring falls short:** images keep their colours, hover and focus colours keep the site's own, and colours drawn by `::before`/`::after` aren't swapped. For full control, use the colour variables below; colorsbymax then applies themes to them directly, with no page reading at all.
+
+Already installed it? Get the newest version with `npm install colorsbymax@latest` (see [Updating](#updating)).
+
+## Add it to a site
+
+This is the full setup, for sites that want exact control over which colour goes where. colorsbymax needs React 18 or 19, and ships as plain JavaScript with TypeScript types, so Vite, Next.js, webpack and other bundlers use it without extra setup:
 
 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.
 
@@ -108,6 +129,10 @@ Without a `siteName`, the site group is named from the page's `og:site_name`, it
   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)
+  recolour: 'auto',                 // re-colour hard-coded colours: 'auto' (only if the site has
+                                    // no --color-* variables, the default), true or false
+  position: 'bottom-right',         // where the button starts: bottom-right (default), bottom-left,
+                                    // top-left, or top-right (just under a floating nav bar)
 }
 ```
 
@@ -129,6 +154,16 @@ PDF.js still downloads only when a visitor picks a PDF. Sites that don't opt in
 
 `examples/tsungi.config.js` is a complete example for tsungi.online, the first site to use colorsbymax.
 
+## Updating
+
+```bash
+npm install colorsbymax@latest
+```
+
+This moves you to the newest release and records it in your `package.json`. `npm update` alone isn't enough while colorsbymax is below 1.0: with the usual `^0.1.0` range, npm treats 0.2.0 as a breaking change and stays on 0.1.x. Check which version you have with `npm ls colorsbymax`.
+
+What changed in each release, and anything you need to do when upgrading, is in [CHANGELOG.md](CHANGELOG.md).
+
 ## 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: