@k8ordo/color-scheme 0.1.0 → 1.0.0

package/README.md

@@ -1,12 +1,14 @@
 # @k8ordo/color-scheme
 
 The colour-scheme axis of an application, owned. The visitor's preference —
-light, dark, or nothing, which follows the system — lives in localStorage
-through `@k8ordo/state`; one rule resolves it against `prefers-color-scheme`;
-the result is the `dark` class on `<html>`, put there by an inline script
-before the first paint and kept there after hydration. One provider does all
-of that; a hook reads it. `@k8ordo/ui`'s tokens, and Tailwind's own dark
-variant, read the class.
+light, dark, or nothing, which follows the default (the system unless told
+otherwise) — lives in localStorage through `@k8ordo/state`; one rule resolves
+it against `prefers-color-scheme`; the result is the `dark` class on `<html>`,
+put there by an inline script before the first paint and kept there after
+hydration. One provider does all of that; a hook reads it. `@k8ordo/ui`'s
+tokens read the class; Tailwind's `dark:` does too once the stylesheet declares
+`@custom-variant dark (&:where(.dark, .dark *));` — `@k8ordo/ui/tailwind.css`
+already does.
 
 Like every [k8ordo](https://ordo.k8o.me) package it assumes React 19 and Server
 Components, uses only what has reached Baseline newly available, and ships no
@@ -25,12 +27,17 @@ pnpm add @k8ordo/color-scheme @k8ordo/state zod
 
 ## Peer Dependencies
 
-| Package         | Version | Needed for                                 |
-| --------------- | ------- | ------------------------------------------ |
-| `@k8ordo/state` | ≥0.2.0  | where the preference lives (localStorage)  |
-| `react`         | ≥19.3.0 | the provider and the hook                  |
-| `zod`           | ^4.4.3  | the one-field schema `@k8ordo/state` reads |
-| `typescript`    | ≥7.0.2  | the shipped type declarations (optional)   |
+<!-- peers -->
+
+| Package         | Version | Required | Needed for                                 |
+| --------------- | ------- | -------- | ------------------------------------------ |
+| `@k8ordo/state` | ^1.0.0  | yes      | where the preference lives (localStorage)  |
+| `react`         | ≥19.3.0 | yes      | the provider and the hook                  |
+| `zod`           | ^4.4.3  | yes      | the one-field schema `@k8ordo/state` reads |
+| `typescript`    | ≥7.0.0  | optional | the shipped type declarations              |
+| `@types/react`  | ≥19.3.0 | optional | the shipped type declarations              |
+
+<!-- /peers -->
 
 ## Quick Start
 
@@ -38,7 +45,7 @@ The provider goes in the root layout, inside `<body>`, around everything. It
 renders the inline script itself, so nothing goes in `<head>`:
 
 ```tsx
-// routes/layout.tsx — a Server Component
+// src/routes/layout.tsx — a Server Component
 import { ColorSchemeProvider } from '@k8ordo/color-scheme';
 
 export default function RootLayout({ children }) {
@@ -73,18 +80,37 @@ export function SchemeSwitcher() {
 ```
 
 `scheme` is what is on screen; `preference` is what the visitor asked for
-(`'system'` when nothing is stored); `setPreference('system')` clears it.
-`<ColorSchemeProvider defaultPreference="dark">` starts every visitor dark
-until they choose.
+(`'system'` when nothing is stored); `setPreference('system')` stores none, so
+the provider's default applies again. That default is the system unless told
+otherwise: `<ColorSchemeProvider defaultPreference="dark">` starts every
+visitor dark until they choose.
 
 ## AI Agent Documentation
 
-This package ships its documentation so an AI coding assistant reads the exact
-installed version:
+The docs ship **inside the package**, so an agent always reads the exact
+version you installed — there is no snapshot to copy or re-sync on upgrade.
+
+Point your agent at them once by pasting this into your project's `CLAUDE.md` /
+`AGENTS.md`:
+
+```markdown
+Use `@k8ordo/color-scheme` for light and dark mode. Before touching the
+colour scheme, read `node_modules/@k8ordo/color-scheme/docs/GUIDE.md`. One
+`<ColorSchemeProvider>` wraps everything inside the root layout's `<body>`,
+with `suppressHydrationWarning` on `<html>`; components read and change the
+scheme through `useColorScheme()`. Never toggle the `dark` class, query
+`prefers-color-scheme` for the scheme, or write the stored preference
+yourself — the provider owns all three, and `setPreference` is the one way in.
+```
+
+What each surface gives an agent:
 
-- `node_modules/@k8ordo/color-scheme/docs/GUIDE.md` — the design guide
-- `node_modules/@k8ordo/color-scheme/docs/llms.txt` — the index
+| Surface                    | Where                                             |
+| -------------------------- | ------------------------------------------------- |
+| Design guide (entry point) | `node_modules/@k8ordo/color-scheme/docs/GUIDE.md` |
+| Docs index for LLMs        | `docs/llms.txt` · https://ordo.k8o.me/llms.txt    |
+| Markdown twin on the web   | https://ordo.k8o.me/color-scheme/docs/GUIDE.md    |
 
 ## License
 
-MIT
+MIT License - see [LICENSE](https://github.com/k35o/k8ordo/blob/main/LICENSE) for details.

package/dist/index.d.mts

@@ -1,3 +1,3 @@
-import { ColorScheme, ColorSchemePreference, colorSchemeState } from "./scheme.mjs";
+import { ColorScheme, ColorSchemePreference, colorSchemeScriptHash, colorSchemeState } from "./scheme.mjs";
 import { ColorSchemeProvider, ColorSchemeProviderProps, UseColorScheme, useColorScheme } from "./provider.mjs";
-export { type ColorScheme, type ColorSchemePreference, ColorSchemeProvider, type ColorSchemeProviderProps, type UseColorScheme, colorSchemeState, useColorScheme };
+export { type ColorScheme, type ColorSchemePreference, ColorSchemeProvider, type ColorSchemeProviderProps, type UseColorScheme, colorSchemeScriptHash, colorSchemeState, useColorScheme };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { colorSchemeState } from "./scheme.mjs";
+import { colorSchemeScriptHash, colorSchemeState } from "./scheme.mjs";
 import { ColorSchemeProvider, useColorScheme } from "./provider.mjs";
-export { ColorSchemeProvider, colorSchemeState, useColorScheme };
+export { ColorSchemeProvider, colorSchemeScriptHash, colorSchemeState, useColorScheme };

package/dist/provider.d.mts

@@ -1,21 +1,34 @@
 import { ColorScheme, ColorSchemePreference } from "./scheme.mjs";
 import { ReactNode } from "react";
 //#region src/provider.d.ts
-type UseColorScheme = {
-  /** What is on screen: the preference, or the system's answer. */
+export type UseColorScheme = {
+  /**
+   * What is on screen: the preference, the provider's default, or the
+   * system's answer.
+   */
   readonly scheme: ColorScheme;
   /** What the visitor asked for; `'system'` when nothing is stored. */
   readonly preference: ColorSchemePreference;
-  /** Stores a preference, or `'system'` to store none and follow it again. */
+  /**
+   * Stores a preference, or `'system'` to store none, so the provider's
+   * `defaultPreference` applies again.
+   */
   readonly setPreference: (preference: ColorSchemePreference) => void;
 };
-type ColorSchemeProviderProps = {
+export type ColorSchemeProviderProps = {
   /**
    * What applies while the visitor has chosen nothing. `'system'` follows
    * `prefers-color-scheme`; a scheme starts every visitor there until they
    * choose.
    */
   readonly defaultPreference?: ColorSchemePreference;
+  /**
+   * The nonce the page's `Content-Security-Policy` lets inline scripts run
+   * with, put on the inline script — under `@k8ordo/framework`'s server mode,
+   * `nonce()` from `@k8ordo/framework/server`. A policy that allows the script by its hash
+   * instead names `colorSchemeScriptHash()`.
+   */
+  readonly nonce?: string;
   readonly children: ReactNode;
 };
 /**
@@ -24,8 +37,7 @@ type ColorSchemeProviderProps = {
  * that puts the class on `<html>` before the first paint, keeps the class
  * in step afterwards, and hands `useColorScheme` what it reads.
  */
-declare function ColorSchemeProvider({ defaultPreference, children }: ColorSchemeProviderProps): ReactNode;
+export declare function ColorSchemeProvider({ defaultPreference, nonce, children }: ColorSchemeProviderProps): ReactNode;
 /** The visitor's colour scheme and a way to change it, from the provider above. */
-declare function useColorScheme(): UseColorScheme;
-//#endregion
-export { ColorSchemeProvider, ColorSchemeProviderProps, UseColorScheme, useColorScheme };
+export declare function useColorScheme(): UseColorScheme;
+//#endregion

package/dist/provider.mjs

@@ -22,7 +22,7 @@ const useReadsStore = () => useSyncExternalStore(subscribeNever, () => true, ()
 * that puts the class on `<html>` before the first paint, keeps the class
 * in step afterwards, and hands `useColorScheme` what it reads.
 */
-function ColorSchemeProvider({ defaultPreference = "system", children }) {
+function ColorSchemeProvider({ defaultPreference = "system", nonce, children }) {
 	const [{ preference }, update] = useAppState(colorSchemeState);
 	const systemDark = useSyncExternalStore(subscribeSystem, readSystemDark, serverSystemDark);
 	const scheme = resolve(preference, defaultPreference, systemDark);
@@ -43,7 +43,10 @@ function ColorSchemeProvider({ defaultPreference = "system", children }) {
 		preference,
 		setPreference
 	]);
-	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("script", { children: scriptFor(defaultPreference) }), /* @__PURE__ */ jsx(ColorSchemeContext, {
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("script", {
+		nonce,
+		children: scriptFor(defaultPreference)
+	}), /* @__PURE__ */ jsx(ColorSchemeContext, {
 		value,
 		children
 	})] });

package/dist/scheme.d.mts

@@ -1,36 +1,49 @@
 import * as z from "zod/mini";
 //#region src/scheme.d.ts
-type ColorScheme = 'light' | 'dark';
-/** What the visitor asked for: a scheme, or to follow the system. */
-type ColorSchemePreference = ColorScheme | 'system';
+export type ColorScheme = 'light' | 'dark';
+/**
+ * A scheme, or `'system'`. As a visitor's preference, `'system'` is nothing
+ * chosen, so the provider's default applies; as that default, it follows the
+ * system.
+ */
+export type ColorSchemePreference = ColorScheme | 'system';
 /**
  * Where the preference lives: localStorage, under
  * `k8ordo-state:color-scheme`. An absent `preference` is "nothing chosen",
  * so a visitor who never chose is never pinned to what the system said on
  * their first visit.
  */
-declare const colorSchemeState: import("@k8ordo/state").LocalState<z.ZodMiniObject<{
+export declare const colorSchemeState: import("@k8ordo/state").LocalState<z.ZodMiniObject<{
   preference: z.ZodMiniOptional<z.ZodMiniEnum<{
     dark: "dark";
     light: "light";
   }>>;
 }, z.core.$strip>>;
 /** The media query the system answers through. */
-declare const DARK_QUERY = "(prefers-color-scheme: dark)";
-/** The class `@k8ordo/ui` — and Tailwind's own dark variant — read on `<html>`. */
-declare const DARK_CLASS = "dark";
+export declare const DARK_QUERY = "(prefers-color-scheme: dark)";
+/**
+ * The class `@k8ordo/ui` reads on `<html>` (and Tailwind's `dark:` under a
+ * class-based `@custom-variant dark`).
+ */
+export declare const DARK_CLASS = "dark";
 /**
  * The one rule: what the visitor chose wins, then what the provider was
  * told to start from, and `system` — the default's default — asks the
  * system.
  */
-declare const resolve: (preference: ColorScheme | undefined, defaultPreference: ColorSchemePreference, systemDark: boolean) => ColorScheme;
+export declare const resolve: (preference: ColorScheme | undefined, defaultPreference: ColorSchemePreference, systemDark: boolean) => ColorScheme;
 /**
  * The inline script the provider renders before its children: the rule
  * above, run before the first paint. The schema does not run there, so the
  * stored value is checked by hand and anything else reads as nothing
  * chosen — the same salvage the store applies.
  */
-declare const scriptFor: (defaultPreference: ColorSchemePreference) => string;
-//#endregion
-export { ColorScheme, ColorSchemePreference, DARK_CLASS, DARK_QUERY, colorSchemeState, resolve, scriptFor };
+export declare const scriptFor: (defaultPreference: ColorSchemePreference) => string;
+/**
+ * The inline script's hash as a CSP source, `'sha256-…'`, for a policy that
+ * allows it by what it is rather than by a nonce — the static mode's `csp`
+ * option, or a header that names no nonce. Give it the default the provider
+ * is given: the script carries it.
+ */
+export declare const colorSchemeScriptHash: (defaultPreference?: ColorSchemePreference) => Promise<string>;
+//#endregion

package/dist/scheme.mjs

@@ -10,7 +10,10 @@ import * as z from "zod/mini";
 const colorSchemeState = defineLocalState("color-scheme", z.object({ preference: z.optional(z.enum(["light", "dark"])) }));
 /** The media query the system answers through. */
 const DARK_QUERY = "(prefers-color-scheme: dark)";
-/** The class `@k8ordo/ui` — and Tailwind's own dark variant — read on `<html>`. */
+/**
+* The class `@k8ordo/ui` reads on `<html>` (and Tailwind's `dark:` under a
+* class-based `@custom-variant dark`).
+*/
 const DARK_CLASS = "dark";
 /**
 * The one rule: what the visitor chose wins, then what the provider was
@@ -27,5 +30,15 @@ const resolve = (preference, defaultPreference, systemDark) => {
 * chosen — the same salvage the store applies.
 */
 const scriptFor = (defaultPreference) => `(()=>{const s=${colorSchemeState.inlineRead()};const v=s&&s.preference;const p=v==="dark"||v==="light"?v:${JSON.stringify(defaultPreference)};if(p==="dark"||(p!=="light"&&matchMedia(${JSON.stringify(DARK_QUERY)}).matches))document.documentElement.classList.add(${JSON.stringify(DARK_CLASS)})})()`;
+/**
+* The inline script's hash as a CSP source, `'sha256-…'`, for a policy that
+* allows it by what it is rather than by a nonce — the static mode's `csp`
+* option, or a header that names no nonce. Give it the default the provider
+* is given: the script carries it.
+*/
+const colorSchemeScriptHash = async (defaultPreference = "system") => {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(scriptFor(defaultPreference)));
+	return `'sha256-${btoa(String.fromCodePoint(...new Uint8Array(digest)))}'`;
+};
 //#endregion
-export { DARK_CLASS, DARK_QUERY, colorSchemeState, resolve, scriptFor };
+export { DARK_CLASS, DARK_QUERY, colorSchemeScriptHash, colorSchemeState, resolve, scriptFor };

package/docs/GUIDE.md

@@ -6,10 +6,11 @@ A visitor's colour scheme is three things that have to agree: what they
 asked for, what the system says, and what is on screen. This package keeps
 the first in localStorage (through `@k8ordo/state`), reads the second from
 `prefers-color-scheme`, and resolves both into the third — the `dark` class
-on `<html>`, which `@k8ordo/ui`'s tokens and Tailwind's own dark variant
-read. One provider does all of it: it renders the inline script that puts
-the class there before the first paint, keeps it right after hydration, and
-hands a hook what it reads.
+on `<html>`, which `@k8ordo/ui`'s tokens read, and Tailwind's `dark:` too
+once the stylesheet declares `@custom-variant dark (&:where(.dark, .dark *));`
+(`@k8ordo/ui/tailwind.css` already does). One provider does all of it: it
+renders the inline script that puts the class there before the first paint,
+keeps it right after hydration, and hands a hook what it reads.
 
 Like every k8ordo package it assumes React 19 and Server Components, uses
 only what has reached Baseline newly available, and ships no polyfills or
@@ -18,13 +19,26 @@ legacy fallbacks.
 ## What it does not own
 
 - **The colours.** Which colour `dark` means is the stylesheet's business —
-  `@k8ordo/ui`'s tokens, or any other that reads the class.
+  `@k8ordo/ui`'s tokens, or any other that reads the class. So is the CSS
+  `color-scheme` property (form controls, scrollbars): this package never
+  sets it; `@k8ordo/ui`'s stylesheet does, next to its tokens (`light`, and
+  `dark` under `.dark`), and a stylesheet of your own declares it beside its
+  colours. Declare it by the class, not as `light dark`: that lets the
+  browser pick by `prefers-color-scheme`, and the scrollbars would disagree
+  with what the visitor chose.
+- **Contrast.** `prefers-contrast: more` and `forced-colors: active` are
+  settings the visitor makes in the OS, not something an application stores
+  or toggles, so neither is a preference here. `@k8ordo/ui`'s stylesheet
+  follows both on its own, in either scheme — its high-contrast values are
+  declared for `:root` and for `.dark` — so a visitor who chose dark and asks
+  the OS for more contrast gets the dark high-contrast values.
 - **Where the preference lives.** That is `@k8ordo/state`'s
-  `defineLocalState`; this package declares one and reads it, so the key
-  and the JSON envelope are never spelled here.
+  `defineLocalState`; this package declares one and reads and writes
+  through it, so the localStorage key and the row's JSON are never spelled
+  here.
 - **A guess on the server.** No cookie, no header: a server render shows
-  the provider's default, and the inline script is what makes the first
-  paint right.
+  the provider's default (`light`, when that default is `'system'`), and the
+  inline script is what makes the first paint right.
 
 ## The shape of it
 
@@ -42,7 +56,7 @@ and around everything, so the script it renders comes before anything the
 page paints:
 
 ```tsx
-// routes/layout.tsx
+// src/routes/layout.tsx
 import { ColorSchemeProvider } from '@k8ordo/color-scheme';
 import type { ReactNode } from 'react';
 
@@ -65,6 +79,42 @@ never chooses follows the system, in either direction, for as long as the
 page is open. To start every visitor somewhere other than the system, say
 so once: `<ColorSchemeProvider defaultPreference="dark">`.
 
+### Under a Content-Security-Policy
+
+The script is inline, so a policy that restricts scripts has to allow it,
+by nonce or by hash. Blocked, it costs the first paint and nothing else: the
+provider's effect still writes the class after hydration, but until then
+`<html>` has no `dark` class and the page is painted light, so a visitor who
+gets dark — by choice or by a `'dark'` default — sees the flash the script
+exists to prevent. Do not reach for `'unsafe-inline'`, which allows
+every inline script that reaches the page; name this one.
+
+`nonce` puts the answer's nonce on it — in `@k8ordo/framework`'s server
+mode, `nonce()` from `@k8ordo/framework/server`, which the render may read
+(signing a script is not writing the response):
+
+```tsx
+<ColorSchemeProvider nonce={nonce()}>{children}</ColorSchemeProvider>
+```
+
+`colorSchemeScriptHash(defaultPreference?)` resolves to its hash as a CSP
+source, `'sha256-…'`, for a policy that allows it by what it is — the
+`csp` option of its static mode, whose files cannot carry a nonce, or a
+header that names none. Pass it the `defaultPreference` the provider is
+given: the script carries it, so the hash depends on it.
+
+```ts
+// vite.config.ts
+framework({
+  mode: 'static',
+  csp: { 'script-src': ["'self'", await colorSchemeScriptHash()] },
+});
+```
+
+Compute the hash where the policy is written, every time, rather than
+copying its value: the script's text is the installed version's, and an
+update may change it.
+
 ## Reading and changing it
 
 ```tsx
@@ -89,42 +139,84 @@ export function SchemeSwitcher() {
 }
 ```
 
-| Member          | What it is                                                                |
-| --------------- | ------------------------------------------------------------------------- |
-| `scheme`        | `'light' \| 'dark'` — what is on screen.                                  |
-| `preference`    | `'light' \| 'dark' \| 'system'` — what the visitor asked for.             |
-| `setPreference` | Stores a preference; `'system'` stores none and follows the system again. |
+| Member          | What it is                                                                 |
+| --------------- | -------------------------------------------------------------------------- |
+| `scheme`        | `'light' \| 'dark'` — what is on screen.                                   |
+| `preference`    | `'light' \| 'dark' \| 'system'` — what the visitor asked for.              |
+| `setPreference` | Stores a preference; `'system'` stores none, so the default applies again. |
 
 A toggle is `setPreference(scheme === 'dark' ? 'light' : 'dark')`. The hook
 reads the provider and touches nothing else, so a switcher and a preview
 agree because there is one provider deciding.
 
-`colorSchemeState` is the `defineLocalState` definition itself, exported for
-anything that wants the row without the hook — `useAppState(colorSchemeState)`,
-or `colorSchemeState.storageKey` in a test.
+## Where it is stored
+
+`colorSchemeState` is the `defineLocalState` definition itself — key
+`color-scheme`, so the localStorage key is `k8ordo-state:color-scheme`
+(`colorSchemeState.storageKey`) — with one optional field:
+
+```ts
+defineLocalState(
+  'color-scheme',
+  z.object({ preference: z.optional(z.enum(['light', 'dark'])) }),
+);
+```
+
+| When                      | The stored row                    |
+| ------------------------- | --------------------------------- |
+| Never chose               | no row (`getItem` returns `null`) |
+| `setPreference('dark')`   | `{"preference":"dark"}`           |
+| `setPreference('light')`  | `{"preference":"light"}`          |
+| `setPreference('system')` | `{}`                              |
+
+The default is never stored, so changing `defaultPreference` later moves
+every visitor who never chose.
+
+- **Reading it without the hook.** `useAppState(colorSchemeState)` from any
+  client component reads the same store the provider does (`@k8ordo/state`
+  keeps one per key). It returns the stored `preference`
+  (`'light' | 'dark' | undefined`), not the resolved `scheme` — for what is
+  on screen, use `useColorScheme()`.
+- **Before the first paint, in a script of your own.**
+  `colorSchemeState.inlineRead()` is a JavaScript expression that evaluates
+  to the stored object, or `null`. No schema runs there, so check each field.
+- **Other preferences beside it.** A display preference of the
+  application's own is a `defineLocalState` under another key, in a module
+  without `'use client'`. Never define another `'color-scheme'`: stores are
+  shared by key, and the two definitions would fight over one row.
 
 ## What it guarantees
 
 - **No flash.** The script runs before the first paint and reads the same
-  row the provider writes; a dark page loads dark.
-- **Nothing chosen follows the default, and the default follows the
-  system.** A visitor who never chose is never pinned to what the system
-  said on their first visit, and a row an older version wrote, or one that
-  is not JSON, reads as nothing chosen.
-- **The server renders the default**, and the provider corrects itself on
-  hydration without touching the document: the render that hydrates reads
-  the server's guesses and writes nothing, and the render that follows reads
-  the store and writes what the script already put there. Until then the
-  HTML shows the default — a switcher's icon, say — which is the one thing
-  no server can know; a component that must not show it even for a moment
-  says so with React's `use(browser())` under a `<Suspense>`.
+  row the provider writes; a dark page loads dark. It is an inline script,
+  so a Content-Security-Policy that restricts scripts has to allow it (see
+  "Under a Content-Security-Policy").
+- **Nothing chosen follows the default, and a `'system'` default follows
+  the system.** A visitor who never chose is never pinned to what the
+  system said on their first visit, and a row that is not a JSON object, or
+  whose `preference` is not `'light'` or `'dark'`, reads as nothing chosen;
+  no other field in the row is read.
+- **The server renders the default** (`light` when that default is
+  `'system'`: a server has no system to ask), and the provider corrects
+  itself on hydration without touching the document: the render that
+  hydrates reads the server's guesses and writes nothing, and the render
+  that follows reads the store and writes what the script already put
+  there. Until then the HTML shows the default — a switcher's icon, say —
+  which is the one thing no server can know; a component that must not
+  show it even for a moment says so with React's `use(browser())` under a
+  `<Suspense>`.
 - **Tabs agree.** The preference propagates across tabs through the
-  `storage` event, as any `@k8ordo/state` local state does.
+  `storage` event, as any `@k8ordo/state` local state does. That event
+  never reaches the tab that wrote, so a `localStorage.setItem` on the row
+  in the same tab goes unnoticed until a reload: change it through
+  `setPreference`.
 
 ## Testing
 
 Under a browser, `localStorage.clear()`, remove the class from
 `document.documentElement`, and `resetStateRegistry()` from `@k8ordo/state`
 between tests; render the hook under `<ColorSchemeProvider>` (a `wrapper`).
-A client-only mount also runs the script the provider renders — a script
-element React creates executes — which is idempotent with the effect.
+A client-only mount does not run the script the provider renders: React
+never executes an inline `<script>` it creates in the browser (in
+development it logs an error saying so), so the class a test sees is the
+one the provider's effect wrote.

package/docs/llms.txt

@@ -1,13 +1,14 @@
 # @k8ordo/color-scheme
 
 > The colour-scheme axis of an application, owned. The visitor's preference
-> — light, dark, or nothing, which follows the system — lives in
-> localStorage through `@k8ordo/state`; one rule resolves it against
-> `prefers-color-scheme`; the result is the `dark` class on `<html>` (what
-> `@k8ordo/ui` and Tailwind's dark variant read). `<ColorSchemeProvider>` in
-> the root layout renders the inline script that puts the class on before
-> the first paint and keeps it in step afterwards; `useColorScheme()` reads
-> it. The server renders the default.
+> — light, dark, or nothing, which follows the default (the system unless
+> told otherwise) — lives in localStorage through `@k8ordo/state`; one rule
+> resolves it against `prefers-color-scheme`; the result is the `dark` class
+> on `<html>` (what `@k8ordo/ui` reads, and Tailwind's `dark:` with a
+> class-based `@custom-variant dark`). `<ColorSchemeProvider>` in the root
+> layout renders the inline script that puts the class on before the first
+> paint and keeps it in step afterwards; `useColorScheme()` reads it. The
+> server renders the default (`light` when that default is `'system'`).
 >
 > Like every k8ordo package it assumes React 19 and Server Components, uses
 > only what has reached Baseline newly available, and ships no polyfills or
@@ -18,20 +19,30 @@ When installed via npm, these docs live under `node_modules/@k8ordo/color-scheme
 ## Guide
 
 - [Design Guide](GUIDE.md): what the package owns and does not (the class,
-  not the colours; the rule, not the storage), placing the provider in the
-  root layout, reading and changing the preference with the hook, what it
-  guarantees, and testing.
+  not the colours or the `color-scheme` property; the rule, not the storage;
+  no contrast preference — `prefers-contrast` and `forced-colors` are the
+  OS's, which `@k8ordo/ui` follows in either scheme), placing the provider
+  in the root layout, allowing its inline script under a
+  Content-Security-Policy (by nonce or by hash, and what a blocked script
+  costs), reading and changing the preference with the hook, the stored row
+  and reading it without the hook, what it guarantees, and testing.
 
 ## Entry point
 
-- `@k8ordo/color-scheme` — `<ColorSchemeProvider defaultPreference?>`
+- `@k8ordo/color-scheme` — `<ColorSchemeProvider defaultPreference? nonce?>`
   (client; goes inside `<body>` around everything) renders the inline
   `<script>` that puts `dark` on `<html>` before the first paint from the
   stored preference, the default (`'system'` unless told otherwise), or the
-  system, and keeps the class in step. `useColorScheme()` returns
+  system, and keeps the class in step; `nonce` signs that script for a
+  Content-Security-Policy (in `@k8ordo/framework`'s server mode, `nonce()`
+  from `@k8ordo/framework/server`).
+  `colorSchemeScriptHash(defaultPreference?)` resolves to the script's hash
+  as a CSP source (`'sha256-…'`), for a policy that allows it by hash —
+  the `csp` option of `@k8ordo/framework`'s static mode. `useColorScheme()` returns
   `{ scheme, preference, setPreference }`: `scheme` is `'light' | 'dark'`
   on screen, `preference` is `'light' | 'dark' | 'system'`, and
-  `setPreference('system')` clears the stored row. `colorSchemeState` is the
-  `@k8ordo/state` local definition itself (`k8ordo-state:color-scheme`).
+  `setPreference('system')` clears the stored preference, so the default
+  applies again. `colorSchemeState` is the `@k8ordo/state` local definition
+  itself (`k8ordo-state:color-scheme`).
   Types: `ColorScheme`, `ColorSchemePreference`, `ColorSchemeProviderProps`,
   `UseColorScheme`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8ordo/color-scheme",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "The colour-scheme axis of an application, owned: the visitor's light / dark / system preference, kept in localStorage, resolved against the system, put on <html> before the first paint and kept there.",
   "keywords": [
     "color-scheme",
@@ -39,26 +39,26 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
-    "@k8ordo/state": "^0.2.0",
+    "@k8ordo/state": "^1.0.0",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
-    "@vitejs/plugin-react": "6.1.1",
-    "@vitest/browser-playwright": "5.0.0",
-    "publint": "0.3.24",
+    "@vitejs/plugin-react": "6.1.2",
+    "@vitest/browser-playwright": "5.0.3",
+    "publint": "0.3.25",
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "typescript": "7.0.2",
-    "vite": "8.2.2",
-    "vite-plus": "0.3.0",
-    "vitest": "5.0.0",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vite-plus": "1.1.0",
+    "vitest": "5.0.3",
     "vitest-browser-react": "2.3.0",
-    "zod": "4.5.4"
+    "zod": "4.6.5"
   },
   "peerDependencies": {
-    "@k8ordo/state": "^0.2.0",
+    "@k8ordo/state": "^1.0.0",
     "@types/react": ">=19.3.0",
     "react": ">=19.3.0",
-    "typescript": ">=7.0.2",
+    "typescript": ">=7.0.0",
     "zod": "^4.4.3"
   },
   "peerDependenciesMeta": {