@codenhub/theme 0.1.1 → 0.1.2

package/README.md

@@ -26,22 +26,19 @@ theme.destroy({ revertDom: true });
 ## Documentation
 
 - [Documentation overview](docs/index.md)
-- [API, persistence, DOM, and SSR behavior](docs/reference.md)
+- [Tokens, persistence, and cross-tab sync](docs/tokens-and-persistence.md)
+- [SSR, pre-paint, and Tailwind](docs/ssr-and-pre-paint.md)
+- [API reference](docs/reference/index.md)
 
 ## Requirements
 
-- Browser integration uses `document.documentElement`, `localStorage`,
-  `matchMedia`, `storage` events, and `CustomEvent`.
-- SSR is supported by skipping unavailable browser work and using the configured
-  default theme.
-- Consumers provide CSS selectors, variables, visual tokens, and any pre-paint
-  script needed to prevent a theme flash.
+- Browser integration uses `document.documentElement`, `localStorage`, `matchMedia`, `storage` events, and `CustomEvent`.
+- SSR is supported by skipping unavailable browser work and using the configured default theme.
+- Consumers provide CSS selectors, variables, visual tokens, and any pre-paint script needed to prevent a theme flash.
 
 ## Notes
 
-Construction validates theme names, mappings, attributes, classes, and token
-schemas and throws on invalid configuration. Storage failures are reported to
-the console and treated as unavailable storage.
+Construction validates theme names, mappings, attributes, classes, and token schemas and throws on invalid configuration. Storage failures are reported to the console and treated as unavailable storage.
 
 ## License
 

package/dist/index.d.ts

@@ -94,11 +94,10 @@ interface Theme<TSchema extends Record<string, string> = Record<string, string>>
    */
   set(name: string, tokens?: Partial<Record<keyof TSchema, string>>): ThemeDefinition<TSchema>;
   /**
-   * Switches the theme between the configured system light and dark themes and persists the change.
-   * The next theme is always selected from `systemTheme.light` or `systemTheme.dark` based on the
-   * active theme's `colorScheme`, not by cycling the active theme name. In multi-theme setups where
-   * the active theme is not one of the system themes, `toggle()` still targets `systemTheme.light`
-   * or `systemTheme.dark`.
+   * Switches away from the active theme and persists the change. If the active theme configures a
+   * `pairedTheme`, that theme is activated. Otherwise the next theme is selected from
+   * `systemTheme.light` or `systemTheme.dark` based on the active theme's `colorScheme`, not by
+   * cycling the active theme name.
    *
    * @param tokens - Optional runtime override token values to apply. Active overrides persist across subsequent theme changes unless cleared (by passing new overrides or an empty object).
    * @returns The activated `ThemeDefinition` with merged and resolved tokens.
@@ -140,9 +139,10 @@ interface Theme<TSchema extends Record<string, string> = Record<string, string>>
    */
   getPrePaintScript(): string;
   /**
-   * Cleans up the theme instance by removing all in-process change listeners and the system
-   * preference media query listener. Resets active tokens and the active theme name to the
-   * configured `defaultTheme` so the instance can be safely re-initialized with `init()`.
+   * Cleans up the theme instance by removing all in-process change listeners, the system
+   * preference media query listener, and the cross-tab storage listener. Resets active tokens
+   * and the active theme name to the configured `defaultTheme` so the instance can be safely
+   * re-initialized with `init()`.
    *
    * @param options - Optional cleanup options. Set `revertDom: true` to remove configured DOM attributes, classes, and CSS custom properties applied to `document.documentElement`.
    * @sideEffect Removes event listeners from `window` and clears internal subscriber sets. If `revertDom: true`, removes theme attributes, classes, and custom properties from the DOM root.
@@ -166,7 +166,8 @@ declare const DARK_THEME: ThemeDefinition;
  *
  * @param options - Configuration options for theme definitions, persistence keys, DOM attributes, custom class resolvers, and dynamic token schemas.
  * @returns A `Theme` instance.
- * @throws {Error} If configured theme names are empty, duplicated, invalid for CSS class application, or if the default/system themes are not present in the configured list.
+ * @throws {Error} If configured theme names are empty, duplicated, invalid for CSS class application, have an
+ *   invalid `colorScheme`, or if the default/system themes are not present in the configured list.
  */
 declare function createTheme<TSchema extends Record<string, string> = Record<string, string>>(options?: ThemeOptions<TSchema>): Theme<TSchema>;
 //#endregion

package/docs/changelog/0.1.2.md

@@ -0,0 +1,15 @@
+---
+title: 0.1.2
+date: 2026-09-15
+description: A generated API reference and reorganized documentation.
+---
+
+# 0.1.2
+
+## Added
+
+- A generated API reference, `docs/reference/index.md`, covering every exported symbol from its TSDoc directly — regenerated on every release instead of hand-maintained separately, so it can't drift out of sync with the source.
+
+## Changed
+
+- Documentation split from one page, `docs/reference.md`, into three focused ones: `docs/index.md` (setup and configuration), `docs/tokens-and-persistence.md` (token resolution, `skipComputed`, persistence, cross-tab sync), and `docs/ssr-and-pre-paint.md` (`getPrePaintScript()`, SSR fallback, Tailwind's `isTailwindCss`, `shouldApplyClass`, `destroy({ revertDom: true })`), plus the generated reference above. Update any link that pointed at `docs/reference.md`.

package/docs/changelog/index.md

@@ -0,0 +1,9 @@
+---
+title: Changelog
+curated: true
+group: Changelog
+---
+
+# Changelog
+
+- [0.1.2](0.1.2.md)

package/docs/index.md

@@ -4,13 +4,7 @@ title: Overview
 
 # Manage Browser Themes
 
-`@codenhub/theme` resolves stored and system theme preferences, applies theme
-state to the document root, synchronizes browser tabs, exposes change events,
-and maps typed tokens to CSS custom properties.
-
-It fits browser applications that need one owner for theme preference and DOM
-synchronization while keeping selectors, visual design, and CSS in application
-code.
+`@codenhub/theme` owns one thing for a browser application: deciding which theme is active, keeping it in sync with `localStorage` and the OS `prefers-color-scheme` setting, and reflecting it onto the DOM as an attribute, a class, and CSS custom properties. It fits applications that want one place to own that decision instead of scattering `matchMedia` listeners and `localStorage` reads across the codebase, while keeping selectors, visual design, and CSS entirely in application code.
 
 ## Setup
 
@@ -29,24 +23,38 @@ const theme = createTheme().init();
 theme.set("dark");
 ```
 
-Call `destroy()` when the manager's owner is removed. The package persists an
-explicit preference and follows system preference when appropriate.
+`createTheme()` with no arguments configures the built-in `light` and `dark` themes. `init()` resolves the theme to apply — a stored preference if one is valid, otherwise the OS preference — and applies it to `document.documentElement`. Call `destroy()` when the manager's owner is torn down, such as in a framework component's cleanup hook; it stops listening but leaves the DOM and stored preference as they were unless told otherwise (see [Tokens, persistence, and cross-tab sync](tokens-and-persistence.md)).
 
-## Requirements
+### Configuration
+
+Most applications configure at least `themes` and `tokenSchema` up front:
+
+```ts
+import { createTheme } from "@codenhub/theme";
 
-- Browser integration uses `document.documentElement`, `localStorage`,
-  `matchMedia`, `storage` events, and `CustomEvent`.
-- SSR is supported by skipping unavailable browser work and using the configured
-  default theme.
-- Consumers provide CSS selectors, variables, visual tokens, and any pre-paint
-  script needed to prevent a theme flash.
+const theme = createTheme({
+  themes: [
+    { name: "light", colorScheme: "light", tokens: { primary: "#171717" } },
+    { name: "dark", colorScheme: "dark", tokens: { primary: "#f9fafb" } },
+  ],
+  tokenSchema: { primary: "--color-primary" },
+  storageKey: "app-theme-preference",
+  isTailwindCss: true,
+}).init();
+```
+
+`themes` replaces the built-in list entirely — include `light` and `dark` (or whatever names `defaultTheme` and `systemTheme` point at) when defining custom themes. `tokenSchema` maps the typed token names used in `ThemeDefinition.tokens` and `get()` to the CSS custom property each one writes to `document.documentElement`. See [Tokens, persistence, and cross-tab sync](tokens-and-persistence.md) for how token values are resolved and stored, and [SSR, pre-paint, and Tailwind](ssr-and-pre-paint.md) for flash-of-unstyled-content prevention and OS-preference-only applications like `isTailwindCss`.
+
+Construction validates every option and throws on invalid configuration: empty or duplicate theme names, a `defaultTheme` or `systemTheme` name that is not in `themes`, an invalid `colorScheme`, or a `shouldApplyClass` resolver that would produce an empty or whitespace-containing class.
+
+## Requirements
 
-The package cannot produce server HTML attributes or prevent a flash before
-initialization. Applications that need pre-paint consistency must apply matching
-theme logic before rendering.
+- Browser integration uses `document.documentElement`, `localStorage`, `matchMedia`, `storage` events, and `CustomEvent`. Every one of these is read defensively: an unavailable or throwing API is treated as absent rather than crashing the caller.
+- SSR is supported by skipping unavailable browser work and using the configured `defaultTheme`. The package cannot produce server HTML attributes or prevent a flash on its own — see [SSR, pre-paint, and Tailwind](ssr-and-pre-paint.md).
+- Consumers provide CSS selectors, variables, and visual tokens. The package only ever writes an attribute, optional classes, and CSS custom properties — it ships no CSS or token values beyond the built-in `light`/`dark` definitions' names.
 
 ## Next steps
 
-- [API, persistence, DOM, and SSR behavior](reference.md): Complete exports,
-  configuration, tokens, browser synchronization, validation, pre-paint
-  concerns, and cleanup.
+- [Tokens, persistence, and cross-tab sync](tokens-and-persistence.md): How `get()` resolves token values, how preferences persist to `localStorage` and sync across tabs, and how to read or clear the stored preference.
+- [SSR, pre-paint, and Tailwind](ssr-and-pre-paint.md): Preventing a flash of unstyled content before hydration, server-rendering considerations, and toggling Tailwind's `dark` class.
+- [API reference](reference/index.md): Every exported function, type, and interface member with its full signature.

package/docs/reference/index.md

@@ -0,0 +1,381 @@
+---
+title: /
+group: Reference
+---
+
+<!-- Generated by `pnpm generate` from packages/theme/src. Do not edit. -->
+
+# @codenhub/theme
+
+## Functions
+
+### createTheme
+
+```ts
+export declare function createTheme<TSchema extends Record<string, string> = Record<string, string>>(options?: ThemeOptions<TSchema>): Theme<TSchema>;
+```
+
+Factory function that creates and returns a `Theme` instance.
+
+**Parameters**
+
+- `options` — Configuration options for theme definitions, persistence keys, DOM attributes, custom class resolvers, and dynamic token schemas.
+
+**Returns** — A `Theme` instance.
+
+**Throws** — If configured theme names are empty, duplicated, invalid for CSS class application, have an invalid `colorScheme`, or if the default/system themes are not present in the configured list.
+
+### getPrePaintScript
+
+```ts
+export declare function getPrePaintScript<TSchema extends Record<string, string> = Record<string, string>>(options?: ThemeOptions<TSchema>): string;
+```
+
+Generates a synchronous inline IIFE script string to inject into document `<head>`. Prevents Flash of Unstyled Content (FOUC) by applying storage or system theme before render.
+
+**Parameters**
+
+- `options` — Configuration options used to determine storage keys, attributes, default/system themes, custom class resolvers, and token schemas.
+
+**Returns** — Minified JavaScript script string.
+
+## Interfaces
+
+### SystemThemeMap
+
+```ts
+export interface SystemThemeMap
+```
+
+Mapping from OS color-scheme preferences to configured theme names.
+
+#### dark
+
+```ts
+dark: string;
+```
+
+Configured theme name used when the OS preference is dark.
+
+#### light
+
+```ts
+light: string;
+```
+
+Configured theme name used when the OS preference is light or no dark preference is detected.
+
+### Theme
+
+```ts
+export interface Theme<TSchema extends Record<string, string> = Record<string, string>>
+```
+
+Core theme preference handler. Manages initialization, switching themes, persistence to localStorage, synchronizing with the OS prefers-color-scheme preference, dynamic token mapping to CSS Custom Properties, and dispatching change events.
+
+#### clearPreference
+
+```ts
+clearPreference(): ThemeDefinition<TSchema>;
+```
+
+Removes the explicit user theme preference from storage and resets the theme to match the OS system preference.
+
+#### destroy
+
+```ts
+destroy(options?: { revertDom?: boolean; }): void;
+```
+
+Cleans up the theme instance by removing all in-process change listeners, the system preference media query listener, and the cross-tab storage listener. Resets active tokens and the active theme name to the configured `defaultTheme` so the instance can be safely re-initialized with `init()`.
+
+**Parameters**
+
+- `options` — Optional cleanup options. Set `revertDom: true` to remove configured DOM attributes, classes, and CSS custom properties applied to `document.documentElement`.
+
+#### get
+
+```ts
+get(options?: { skipComputed?: boolean; }): ThemeDefinition<TSchema>;
+```
+
+Retrieves the active theme configuration including static and computed tokens.
+
+Token values are merged in this priority order (last wins):
+
+1. CSS computed style — values read from `window.getComputedStyle` for tokens not defined in JS (unless `options.skipComputed` is true).
+2. Theme static tokens — values defined in `ThemeDefinition.tokens` for the active theme.
+3. Runtime overrides — values passed to `init()`, `set()`, `toggle()`, or other methods.
+
+**Parameters**
+
+- `options` — Optional getter options. Set `skipComputed: true` to avoid reading computed styles from the DOM via `window.getComputedStyle`, preventing potential layout reflows.
+
+#### getPrePaintScript
+
+```ts
+getPrePaintScript(): string;
+```
+
+Generates a synchronous inline IIFE script string to inject into document `<head>`. Prevents Flash of Unstyled Content (FOUC) by applying storage or system theme before render.
+
+#### getStored
+
+```ts
+getStored(): string | null;
+```
+
+Retrieves the currently stored theme preference name from `localStorage`.
+
+#### getSystem
+
+```ts
+getSystem(): ThemeDefinition<TSchema>;
+```
+
+Resolves the configured theme that matches the active OS color-scheme preference.
+
+#### init
+
+```ts
+init(tokens?: Partial<Record<keyof TSchema, string>>): this;
+```
+
+Initializes the theme manager. Resolves the active theme (using the stored preference if valid, falling back to the current OS color-scheme preference), applies classes/attributes to the DOM, and registers the media query listener for automatic system preference updates.
+
+**Parameters**
+
+- `tokens` — Optional runtime override token values to merge and apply.
+
+#### set
+
+```ts
+set(name: string, tokens?: Partial<Record<keyof TSchema, string>>): ThemeDefinition<TSchema>;
+```
+
+Activates a configured theme by name and updates the stored preference in `localStorage`.
+
+**Parameters**
+
+- `name` — The name of the configured theme to activate.
+- `tokens` — Optional runtime override token values to apply. Active overrides persist across subsequent theme changes unless cleared (by passing new overrides or an empty object).
+
+#### subscribe
+
+```ts
+subscribe(listener: ThemeChangeListener<TSchema>): () => void;
+```
+
+Registers a callback listener to receive notifications when the theme or its tokens change.
+
+**Parameters**
+
+- `listener` — Callback function invoked on theme changes.
+
+#### toggle
+
+```ts
+toggle(tokens?: Partial<Record<keyof TSchema, string>>): ThemeDefinition<TSchema>;
+```
+
+Switches away from the active theme and persists the change. If the active theme configures a `pairedTheme`, that theme is activated. Otherwise the next theme is selected from `systemTheme.light` or `systemTheme.dark` based on the active theme's `colorScheme`, not by cycling the active theme name.
+
+**Parameters**
+
+- `tokens` — Optional runtime override token values to apply. Active overrides persist across subsequent theme changes unless cleared (by passing new overrides or an empty object).
+
+### ThemeChangeDetail
+
+```ts
+export interface ThemeChangeDetail<TSchema extends Record<string, string> = Record<string, string>>
+```
+
+Payload passed to subscribers and the browser `themechange` event after a theme change.
+
+#### name
+
+```ts
+name: string;
+```
+
+Active theme name after the change.
+
+#### source
+
+```ts
+source: ThemeChangeSource;
+```
+
+Operation or browser signal that caused the change notification.
+
+#### theme
+
+```ts
+theme: ThemeDefinition<TSchema>;
+```
+
+Active theme definition after the change.
+
+### ThemeDefinition
+
+```ts
+export interface ThemeDefinition<TSchema extends Record<string, string> = Record<string, string>>
+```
+
+Theme option stored, applied to the configured DOM attribute, and mapped to the browser color scheme.
+
+#### colorScheme
+
+```ts
+colorScheme: "light" | "dark";
+```
+
+Browser color scheme applied to `document.documentElement.style.colorScheme`.
+
+#### name
+
+```ts
+name: string;
+```
+
+Unique configured theme name used for storage, DOM attributes, and generated default classes.
+
+#### pairedTheme
+
+```ts
+pairedTheme?: string;
+```
+
+Optional theme name activated when calling `toggle()` from this theme.
+
+#### tokens
+
+```ts
+tokens?: Partial<Record<keyof TSchema, string>>;
+```
+
+Optional theme-specific static token values.
+
+### ThemeOptions
+
+```ts
+export interface ThemeOptions<TSchema extends Record<string, string> = Record<string, string>>
+```
+
+Configuration for theme definitions, persistence, DOM application, and system preference mapping.
+
+#### attribute
+
+```ts
+attribute?: string;
+```
+
+Attribute set on `document.documentElement` with the active theme name.
+
+#### defaultTheme
+
+```ts
+defaultTheme?: string;
+```
+
+Configured theme name used before initialization and when browser APIs are unavailable.
+
+#### isTailwindCss
+
+```ts
+isTailwindCss?: boolean;
+```
+
+Whether to toggle Tailwind CSS's `dark` class for themes with `colorScheme: "dark"`.
+
+#### shouldApplyClass
+
+```ts
+shouldApplyClass?: boolean | ThemeClassResolver<TSchema>;
+```
+
+Whether and how to apply a theme-specific class to `document.documentElement`.
+
+#### storageKey
+
+```ts
+storageKey?: string;
+```
+
+`localStorage` key used for explicit user preferences.
+
+#### systemTheme
+
+```ts
+systemTheme?: SystemThemeMap;
+```
+
+Configured theme names selected for OS light and dark color-scheme preferences.
+
+#### themes
+
+```ts
+themes?: readonly ThemeDefinition<TSchema>[];
+```
+
+Available themes. Names must be unique, non-empty, and valid default class tokens when `shouldApplyClass` is `true`.
+
+#### tokenSchema
+
+```ts
+tokenSchema?: TSchema;
+```
+
+Schema mapping theme token names to their corresponding CSS Custom Property names.
+
+## Type aliases
+
+### ThemeChangeListener
+
+```ts
+export type ThemeChangeListener<TSchema extends Record<string, string> = Record<string, string>> = (detail: ThemeChangeDetail<TSchema>) => void;
+```
+
+In-process callback registered with `Theme.subscribe()` for applied theme changes.
+
+### ThemeChangeSource
+
+```ts
+export type ThemeChangeSource = "init" | "set" | "toggle" | "clearPreference" | "system";
+```
+
+Reason a theme change notification was emitted.
+
+### ThemeClassResolver
+
+```ts
+export type ThemeClassResolver<TSchema extends Record<string, string> = Record<string, string>> = (theme: ThemeDefinition<TSchema>) => string;
+```
+
+Resolves the single DOM class token applied for a theme when custom class application is enabled.
+
+## Variables
+
+### DARK_THEME
+
+```ts
+export declare const DARK_THEME: ThemeDefinition;
+```
+
+Built-in dark theme used by default and available for custom theme lists.
+
+### LIGHT_THEME
+
+```ts
+export declare const LIGHT_THEME: ThemeDefinition;
+```
+
+Built-in light theme used by default and available for custom theme lists.
+
+### THEME_CHANGE_EVENT
+
+```ts
+export declare const THEME_CHANGE_EVENT = "themechange";
+```
+
+Window event name dispatched with `ThemeChangeDetail` after a theme change is applied in browser environments.

package/docs/ssr-and-pre-paint.md

@@ -0,0 +1,46 @@
+---
+title: SSR, Pre-Paint, and Tailwind
+---
+
+# SSR, Pre-Paint, and Tailwind
+
+## Preventing a flash of unstyled content
+
+A client-side `init()` call runs after the page has already painted once, which is visible as a flash from the default theme to the resolved one. `getPrePaintScript()` — available as a method on an existing manager, or as the standalone `getPrePaintScript(options)` export when no manager exists yet — returns a synchronous, minified inline IIFE string that duplicates the same stored-preference-then-system-preference resolution, and applies the configured attribute, classes, and any static tokens before the browser paints:
+
+```ts
+import { getPrePaintScript } from "@codenhub/theme";
+
+const script = getPrePaintScript({ storageKey: "app-theme-preference" });
+```
+
+Inject the returned string into a blocking `<script>` in the document `<head>`, before any stylesheet or content that depends on the theme:
+
+```html
+<head>
+  <script>
+    /* inline the string returned by getPrePaintScript() here */
+  </script>
+</head>
+```
+
+Pass the same `themes`, `tokenSchema`, `defaultTheme`, `systemTheme`, `storageKey`, `attribute`, `shouldApplyClass`, and `isTailwindCss` options used to construct the manager, so the pre-paint script and the later `init()` call resolve to the same theme. `getPrePaintScript()` only serializes **static** tokens from each theme's `ThemeDefinition.tokens` — and only when `tokenSchema` is passed to it — runtime overrides passed to `init(tokens)` are applied after hydration, during client-side execution, and cannot be part of a script that runs before any application code.
+
+## Server-side rendering
+
+Without browser APIs, `Theme` methods skip storage reads/writes, DOM updates, and listener registration; `getSystem()` falls back to `defaultTheme`. Every method call remains safe to make during SSR — nothing throws for a missing `window`, `document`, or `localStorage` — but the package cannot produce server-rendered HTML attributes on its own. To avoid a flash on a server-rendered page, either:
+
+- Render the server markup with the same attribute/class the pre-paint script would apply (requiring the server to read the same cookie or header a real theme service would use), or
+- Rely on the pre-paint script above to correct the DOM before first paint, accepting that server-rendered markup itself does not carry theme state.
+
+Keep any server-side resolution logic — stored names, system mapping, storage key, attribute, classes, color scheme — aligned with the options passed to `createTheme()` and `getPrePaintScript()`; a mismatch reintroduces the flash it exists to prevent.
+
+## Tailwind's `dark` class
+
+Set `isTailwindCss: true` to toggle Tailwind CSS's `dark` class on `document.documentElement` alongside the configured attribute, for every theme whose `colorScheme` is `"dark"`. This is independent of `shouldApplyClass` (below) — a Tailwind app commonly wants both the `dark` class for Tailwind's `dark:` variant and, when `shouldApplyClass` is left at its default, a `theme-${name}` class for custom per-theme CSS.
+
+## Classes and cleanup
+
+`shouldApplyClass` controls whether and how a class is applied to `document.documentElement` alongside the attribute: `true` (the default) applies `theme-${name}`, `false` applies no class, and a `ThemeClassResolver` function receives the active `ThemeDefinition` and returns one custom class token — throwing if it returns an empty or whitespace-containing string.
+
+`destroy(options?)` removes the media-query and storage listeners and clears in-process subscribers and runtime tokens, leaving the instance safe to `init()` again. By default it does **not** touch the DOM or stored preference. Pass `{ revertDom: true }` to also remove the configured attribute, classes, and CSS custom properties from `document.documentElement` — useful when unmounting a scoped theme manager that should leave no trace, such as in a component test or a preview pane.

package/docs/tokens-and-persistence.md

@@ -0,0 +1,51 @@
+---
+title: Tokens, Persistence, and Cross-Tab Sync
+---
+
+# Tokens, Persistence, and Cross-Tab Sync
+
+## Token resolution
+
+`tokenSchema` maps typed token names to the CSS custom property each one writes, such as `{ primary: "--color-primary" }`. Once configured, `get()` returns the active `ThemeDefinition` with every schema key resolved from three sources, in this priority order (last wins):
+
+1. **Computed style** — for a token not defined in JS, the value is read from `window.getComputedStyle(document.documentElement)` in browser environments.
+2. **Theme static tokens** — values set on the active theme's own `ThemeDefinition.tokens`.
+3. **Runtime overrides** — values passed to `init()`, `set()`, or `toggle()`.
+
+```ts
+const theme = createTheme({
+  themes: [{ name: "brand", colorScheme: "light", tokens: { accent: "#ff6600" } }],
+  tokenSchema: { accent: "--color-accent" },
+}).init();
+
+theme.set("brand", { accent: "#00c853" }); // runtime override wins over the static "#ff6600"
+theme.get().tokens?.accent; // "#00c853"
+```
+
+Reading computed values can force a synchronous layout reflow. Pass `{ skipComputed: true }` to `get()` to skip that source and avoid the reflow when only the JS-known values are needed.
+
+Runtime overrides persist across subsequent theme changes until explicitly replaced — pass a new object, including `{}`, to `init()`, `set()`, or `toggle()` to clear or replace them. Passing a token key that is not in `tokenSchema` throws.
+
+## Persistence
+
+An explicit preference set through `set()` or `toggle()` is written to `localStorage` under `storageKey` (default `"app-theme-preference"`). `getStored()` returns that value when it names a currently configured theme, or `null` when it is unset, invalid, or storage is unavailable (for example during SSR). `clearPreference()` removes the stored value and re-applies whichever theme `getSystem()` currently resolves to.
+
+Storage reads, writes, and removals that throw — a full quota, a disabled storage API, a private-browsing restriction — are logged with `console.error` and treated the same as unavailable storage; they never throw out of `Theme` methods.
+
+## Cross-tab sync
+
+Every tab running `createTheme().init()` against the same `storageKey` stays in sync: a `storage` event fires in every other tab when one tab writes a new preference, and each one applies the change if it names a valid configured theme. A tab with its own runtime token overrides keeps them — only the active theme name changes from cross-tab sync, not tokens passed in-process.
+
+The OS `prefers-color-scheme` media query applies automatically only while no valid stored preference exists. Once a tab (or a previous session) has stored an explicit preference, later system-preference changes are ignored until `clearPreference()` runs.
+
+## Reacting to changes
+
+`subscribe(listener)` registers a callback invoked after every applied change — from `init()`, `set()`, `toggle()`, `clearPreference()`, or an accepted `system` or cross-tab update — and returns an unsubscribe function:
+
+```ts
+const unsubscribe = theme.subscribe(({ name, source }) => {
+  console.log(`theme is now "${name}" (${source})`);
+});
+```
+
+A subscriber that throws is logged and does not stop other subscribers from running. Browsers also receive a `window` `CustomEvent` named by the exported `THEME_CHANGE_EVENT` constant (`"themechange"`) carrying the same detail, for code that prefers DOM events over `subscribe()`.

package/llms-full.txt

@@ -1,204 +1,213 @@
-<!-- Source: README.md -->
-
-# @codenhub/theme
-
-Zero-dependency browser theme preference, persistence, DOM, and token manager.
-
-## Installation
-
-```sh
-pnpm add @codenhub/theme
-```
-
-## Usage
-
-```ts
-import { createTheme, getPrePaintScript } from "@codenhub/theme";
-
-const theme = createTheme().init();
-theme.set("dark");
-
-// Get inline IIFE script string for <head> to prevent FOUC:
-const script = theme.getPrePaintScript(); // or standalone getPrePaintScript()
-
-// Remove media-query/storage listeners and subscribers on teardown.
-theme.destroy({ revertDom: true });
-```
-
-## Documentation
-
-- [Documentation overview](docs/index.md)
-- [API, persistence, DOM, and SSR behavior](docs/reference.md)
-
-## Requirements
-
-- Browser integration uses `document.documentElement`, `localStorage`,
-  `matchMedia`, `storage` events, and `CustomEvent`.
-- SSR is supported by skipping unavailable browser work and using the configured
-  default theme.
-- Consumers provide CSS selectors, variables, visual tokens, and any pre-paint
-  script needed to prevent a theme flash.
-
-## Notes
-
-Construction validates theme names, mappings, attributes, classes, and token
-schemas and throws on invalid configuration. Storage failures are reported to
-the console and treated as unavailable storage.
-
-## License
-
-Licensed under Apache-2.0.
-
-<!-- Source: docs/index.md -->
-
-# Manage Browser Themes
-
-`@codenhub/theme` resolves stored and system theme preferences, applies theme
-state to the document root, synchronizes browser tabs, exposes change events,
-and maps typed tokens to CSS custom properties.
-
-It fits browser applications that need one owner for theme preference and DOM
-synchronization while keeping selectors, visual design, and CSS in application
-code.
-
-## Setup
-
-### Installation
-
-```sh
-pnpm add @codenhub/theme
-```
-
-### Quick start
-
-```ts
-import { createTheme } from "@codenhub/theme";
-
-const theme = createTheme().init();
-theme.set("dark");
-```
-
-Call `destroy()` when the manager's owner is removed. The package persists an
-explicit preference and follows system preference when appropriate.
-
-## Requirements
-
-- Browser integration uses `document.documentElement`, `localStorage`,
-  `matchMedia`, `storage` events, and `CustomEvent`.
-- SSR is supported by skipping unavailable browser work and using the configured
-  default theme.
-- Consumers provide CSS selectors, variables, visual tokens, and any pre-paint
-  script needed to prevent a theme flash.
-
-The package cannot produce server HTML attributes or prevent a flash before
-initialization. Applications that need pre-paint consistency must apply matching
-theme logic before rendering.
-
-## Next steps
-
-- [API, persistence, DOM, and SSR behavior](docs/reference.md): Complete exports,
-  configuration, tokens, browser synchronization, validation, pre-paint
-  concerns, and cleanup.
-
-<!-- Source: docs/reference.md -->
-
-# Theme API, Persistence, DOM, and SSR Behavior
-
-## Create and Initialize
-
-`createTheme<TSchema>(options?): Theme<TSchema>` validates configuration and
-creates a manager. `ThemeOptions` contains:
-
-- `themes`: definitions, defaulting to `LIGHT_THEME` and `DARK_THEME`.
-- `defaultTheme`: pre-init and SSR fallback, default `"light"`.
-- `systemTheme`: configured names for light/dark OS preference.
-- `storageKey`: `localStorage` key, default `"app-theme-preference"`.
-- `attribute`: document-root attribute, default `"data-theme"`.
-- `isTailwindCss`: toggle the root `dark` class, default `false`.
-- `shouldApplyClass`: add `theme-${name}` by default, disable classes, or return
-  one custom class token with a `ThemeClassResolver`.
-- `tokenSchema`: maps typed token names to CSS custom-property names.
-
-`ThemeDefinition` has a unique `name`, `colorScheme` (`light` or `dark`),
-optional static tokens, and optional `pairedTheme` target for `toggle()`.
-`SystemThemeMap` maps OS light and dark preferences.
-
-`init(tokens?)` is idempotent until `destroy()`. It registers media-query and
-cross-tab storage listeners, selects valid stored preference before system
-preference, applies the theme, and emits an `"init"` change.
-
-## Theme Operations
-
-- `get(options?)` returns the active definition. Tokens merge computed CSS values,
-  static theme values, then runtime overrides. Reading computed values can force
-  style calculation; pass `{ skipComputed: true }` to bypass reading computed DOM styles.
-- `set(name, tokens?)` applies and persists a configured theme; unknown names
-  throw.
-- `toggle(tokens?)` switches to `pairedTheme` if defined on the active theme, or
-  otherwise by active `colorScheme` between the names in `systemTheme`, then
-  persists the choice.
-- `clearPreference()` removes storage and applies the current system theme.
-- `getStored()` returns a valid configured stored name or `null`.
-- `getSystem()` returns the mapped system theme, or `defaultTheme` when media
-  queries are unavailable.
-- `getPrePaintScript()` returns a synchronous inline IIFE script string to inject
-  into document `<head>` to prevent flash of unstyled content (FOUC). Supports custom
-  class resolvers and static token custom properties. Also available as standalone export
-  `getPrePaintScript(options?)`.
-
-Runtime token overrides persist across theme changes. Passing a new object,
-including `{}`, replaces them. Tokens require a schema and unknown token keys
-throw.
-
-## DOM, Persistence, and Events
-
-Applying a theme sets the configured root attribute and
-`document.documentElement.style.colorScheme`, updates configured theme classes,
-toggles Tailwind's `dark` class when enabled, and writes mapped token values as
-CSS custom properties. The package supplies no CSS or token values beyond the
-built-in light/dark definitions.
-
-Explicit preferences use `localStorage`. `storage` events synchronize valid
-changes from other tabs. OS preference changes apply only while no valid stored
-preference exists. Storage read/write/remove failures are logged with
-`console.error` and treated as unavailable.
-
-`subscribe(ThemeChangeListener)` returns an unsubscribe function. Subscribers
-receive `ThemeChangeDetail` with `name`, `theme`, and `ThemeChangeSource`:
-`"init"`, `"set"`, `"toggle"`, `"clearPreference"`, or `"system"`. Subscriber
-errors are logged and do not stop later listeners. Browsers also receive a
-window `CustomEvent` named by `THEME_CHANGE_EVENT` (`"themechange"`).
-
-## Validation and Cleanup
-
-Creation throws for invalid attributes/storage keys, malformed or duplicate
-themes, invalid color schemes/classes/token schemas, and missing default/system
-theme names. Applying a custom class resolver can throw if it returns an empty
-or whitespace-containing class. Runtime token calls throw without a matching
-schema.
-
-`destroy(options?)` removes media-query and storage listeners, clears
-in-process subscribers and runtime tokens, and resets internal active state.
-By default, it does not remove persisted preference or revert attributes,
-classes, custom properties, or `colorScheme` already applied to the document;
-pass `{ revertDom: true }` to remove configured DOM attributes, classes, and
-CSS custom properties from `document.documentElement`.
-
-## SSR and Pre-Paint Behavior
-
-Without browser APIs, storage, DOM, events, and listeners are skipped;
-`getSystem()` uses `defaultTheme`. Calls remain usable but cannot produce server
-HTML attributes. To avoid a flash, applications must apply equivalent validated
-storage/system logic in a blocking pre-paint script or render matching server
-markup. Keep that logic aligned with custom names, mappings, storage key,
-attribute, classes, and color scheme. Note that `getPrePaintScript()` serializes
-static tokens defined on configured theme definitions (`ThemeDefinition.tokens`);
-runtime token overrides passed to `init(tokens)` or `set(name, tokens)` are applied
-during client-side execution after hydration.
-
-## Public Exports
-
-The root exports `createTheme`, `getPrePaintScript`, `THEME_CHANGE_EVENT`,
-`LIGHT_THEME`, and `DARK_THEME`, plus `Theme`, `ThemeDefinition`, `SystemThemeMap`,
-`ThemeClassResolver`, `ThemeChangeSource`, `ThemeChangeDetail`,
-`ThemeChangeListener`, and `ThemeOptions` types.
+<!-- Source: README.md -->
+
+# @codenhub/theme
+
+Zero-dependency browser theme preference, persistence, DOM, and token manager.
+
+## Installation
+
+```sh
+pnpm add @codenhub/theme
+```
+
+## Usage
+
+```ts
+import { createTheme, getPrePaintScript } from "@codenhub/theme";
+
+const theme = createTheme().init();
+theme.set("dark");
+
+// Get inline IIFE script string for <head> to prevent FOUC:
+const script = theme.getPrePaintScript(); // or standalone getPrePaintScript()
+
+// Remove media-query/storage listeners and subscribers on teardown.
+theme.destroy({ revertDom: true });
+```
+
+## Documentation
+
+- [Documentation overview](docs/index.md)
+- [Tokens, persistence, and cross-tab sync](docs/tokens-and-persistence.md)
+- [SSR, pre-paint, and Tailwind](docs/ssr-and-pre-paint.md)
+- [API reference](docs/reference/index.md)
+
+## Requirements
+
+- Browser integration uses `document.documentElement`, `localStorage`, `matchMedia`, `storage` events, and `CustomEvent`.
+- SSR is supported by skipping unavailable browser work and using the configured default theme.
+- Consumers provide CSS selectors, variables, visual tokens, and any pre-paint script needed to prevent a theme flash.
+
+## Notes
+
+Construction validates theme names, mappings, attributes, classes, and token schemas and throws on invalid configuration. Storage failures are reported to the console and treated as unavailable storage.
+
+## License
+
+Licensed under Apache-2.0.
+
+<!-- Source: docs/index.md -->
+
+# Manage Browser Themes
+
+`@codenhub/theme` owns one thing for a browser application: deciding which theme is active, keeping it in sync with `localStorage` and the OS `prefers-color-scheme` setting, and reflecting it onto the DOM as an attribute, a class, and CSS custom properties. It fits applications that want one place to own that decision instead of scattering `matchMedia` listeners and `localStorage` reads across the codebase, while keeping selectors, visual design, and CSS entirely in application code.
+
+## Setup
+
+### Installation
+
+```sh
+pnpm add @codenhub/theme
+```
+
+### Quick start
+
+```ts
+import { createTheme } from "@codenhub/theme";
+
+const theme = createTheme().init();
+theme.set("dark");
+```
+
+`createTheme()` with no arguments configures the built-in `light` and `dark` themes. `init()` resolves the theme to apply — a stored preference if one is valid, otherwise the OS preference — and applies it to `document.documentElement`. Call `destroy()` when the manager's owner is torn down, such as in a framework component's cleanup hook; it stops listening but leaves the DOM and stored preference as they were unless told otherwise (see [Tokens, persistence, and cross-tab sync](docs/tokens-and-persistence.md)).
+
+### Configuration
+
+Most applications configure at least `themes` and `tokenSchema` up front:
+
+```ts
+import { createTheme } from "@codenhub/theme";
+
+const theme = createTheme({
+  themes: [
+    { name: "light", colorScheme: "light", tokens: { primary: "#171717" } },
+    { name: "dark", colorScheme: "dark", tokens: { primary: "#f9fafb" } },
+  ],
+  tokenSchema: { primary: "--color-primary" },
+  storageKey: "app-theme-preference",
+  isTailwindCss: true,
+}).init();
+```
+
+`themes` replaces the built-in list entirely — include `light` and `dark` (or whatever names `defaultTheme` and `systemTheme` point at) when defining custom themes. `tokenSchema` maps the typed token names used in `ThemeDefinition.tokens` and `get()` to the CSS custom property each one writes to `document.documentElement`. See [Tokens, persistence, and cross-tab sync](docs/tokens-and-persistence.md) for how token values are resolved and stored, and [SSR, pre-paint, and Tailwind](docs/ssr-and-pre-paint.md) for flash-of-unstyled-content prevention and OS-preference-only applications like `isTailwindCss`.
+
+Construction validates every option and throws on invalid configuration: empty or duplicate theme names, a `defaultTheme` or `systemTheme` name that is not in `themes`, an invalid `colorScheme`, or a `shouldApplyClass` resolver that would produce an empty or whitespace-containing class.
+
+## Requirements
+
+- Browser integration uses `document.documentElement`, `localStorage`, `matchMedia`, `storage` events, and `CustomEvent`. Every one of these is read defensively: an unavailable or throwing API is treated as absent rather than crashing the caller.
+- SSR is supported by skipping unavailable browser work and using the configured `defaultTheme`. The package cannot produce server HTML attributes or prevent a flash on its own — see [SSR, pre-paint, and Tailwind](docs/ssr-and-pre-paint.md).
+- Consumers provide CSS selectors, variables, and visual tokens. The package only ever writes an attribute, optional classes, and CSS custom properties — it ships no CSS or token values beyond the built-in `light`/`dark` definitions' names.
+
+## Next steps
+
+- [Tokens, persistence, and cross-tab sync](docs/tokens-and-persistence.md): How `get()` resolves token values, how preferences persist to `localStorage` and sync across tabs, and how to read or clear the stored preference.
+- [SSR, pre-paint, and Tailwind](docs/ssr-and-pre-paint.md): Preventing a flash of unstyled content before hydration, server-rendering considerations, and toggling Tailwind's `dark` class.
+- [API reference](docs/reference/index.md): Every exported function, type, and interface member with its full signature.
+
+<!-- Source: docs/ssr-and-pre-paint.md -->
+
+# SSR, Pre-Paint, and Tailwind
+
+## Preventing a flash of unstyled content
+
+A client-side `init()` call runs after the page has already painted once, which is visible as a flash from the default theme to the resolved one. `getPrePaintScript()` — available as a method on an existing manager, or as the standalone `getPrePaintScript(options)` export when no manager exists yet — returns a synchronous, minified inline IIFE string that duplicates the same stored-preference-then-system-preference resolution, and applies the configured attribute, classes, and any static tokens before the browser paints:
+
+```ts
+import { getPrePaintScript } from "@codenhub/theme";
+
+const script = getPrePaintScript({ storageKey: "app-theme-preference" });
+```
+
+Inject the returned string into a blocking `<script>` in the document `<head>`, before any stylesheet or content that depends on the theme:
+
+```html
+<head>
+  <script>
+    /* inline the string returned by getPrePaintScript() here */
+  </script>
+</head>
+```
+
+Pass the same `themes`, `tokenSchema`, `defaultTheme`, `systemTheme`, `storageKey`, `attribute`, `shouldApplyClass`, and `isTailwindCss` options used to construct the manager, so the pre-paint script and the later `init()` call resolve to the same theme. `getPrePaintScript()` only serializes **static** tokens from each theme's `ThemeDefinition.tokens` — and only when `tokenSchema` is passed to it — runtime overrides passed to `init(tokens)` are applied after hydration, during client-side execution, and cannot be part of a script that runs before any application code.
+
+## Server-side rendering
+
+Without browser APIs, `Theme` methods skip storage reads/writes, DOM updates, and listener registration; `getSystem()` falls back to `defaultTheme`. Every method call remains safe to make during SSR — nothing throws for a missing `window`, `document`, or `localStorage` — but the package cannot produce server-rendered HTML attributes on its own. To avoid a flash on a server-rendered page, either:
+
+- Render the server markup with the same attribute/class the pre-paint script would apply (requiring the server to read the same cookie or header a real theme service would use), or
+- Rely on the pre-paint script above to correct the DOM before first paint, accepting that server-rendered markup itself does not carry theme state.
+
+Keep any server-side resolution logic — stored names, system mapping, storage key, attribute, classes, color scheme — aligned with the options passed to `createTheme()` and `getPrePaintScript()`; a mismatch reintroduces the flash it exists to prevent.
+
+## Tailwind's `dark` class
+
+Set `isTailwindCss: true` to toggle Tailwind CSS's `dark` class on `document.documentElement` alongside the configured attribute, for every theme whose `colorScheme` is `"dark"`. This is independent of `shouldApplyClass` (below) — a Tailwind app commonly wants both the `dark` class for Tailwind's `dark:` variant and, when `shouldApplyClass` is left at its default, a `theme-${name}` class for custom per-theme CSS.
+
+## Classes and cleanup
+
+`shouldApplyClass` controls whether and how a class is applied to `document.documentElement` alongside the attribute: `true` (the default) applies `theme-${name}`, `false` applies no class, and a `ThemeClassResolver` function receives the active `ThemeDefinition` and returns one custom class token — throwing if it returns an empty or whitespace-containing string.
+
+`destroy(options?)` removes the media-query and storage listeners and clears in-process subscribers and runtime tokens, leaving the instance safe to `init()` again. By default it does **not** touch the DOM or stored preference. Pass `{ revertDom: true }` to also remove the configured attribute, classes, and CSS custom properties from `document.documentElement` — useful when unmounting a scoped theme manager that should leave no trace, such as in a component test or a preview pane.
+
+<!-- Source: docs/tokens-and-persistence.md -->
+
+# Tokens, Persistence, and Cross-Tab Sync
+
+## Token resolution
+
+`tokenSchema` maps typed token names to the CSS custom property each one writes, such as `{ primary: "--color-primary" }`. Once configured, `get()` returns the active `ThemeDefinition` with every schema key resolved from three sources, in this priority order (last wins):
+
+1. **Computed style** — for a token not defined in JS, the value is read from `window.getComputedStyle(document.documentElement)` in browser environments.
+2. **Theme static tokens** — values set on the active theme's own `ThemeDefinition.tokens`.
+3. **Runtime overrides** — values passed to `init()`, `set()`, or `toggle()`.
+
+```ts
+const theme = createTheme({
+  themes: [{ name: "brand", colorScheme: "light", tokens: { accent: "#ff6600" } }],
+  tokenSchema: { accent: "--color-accent" },
+}).init();
+
+theme.set("brand", { accent: "#00c853" }); // runtime override wins over the static "#ff6600"
+theme.get().tokens?.accent; // "#00c853"
+```
+
+Reading computed values can force a synchronous layout reflow. Pass `{ skipComputed: true }` to `get()` to skip that source and avoid the reflow when only the JS-known values are needed.
+
+Runtime overrides persist across subsequent theme changes until explicitly replaced — pass a new object, including `{}`, to `init()`, `set()`, or `toggle()` to clear or replace them. Passing a token key that is not in `tokenSchema` throws.
+
+## Persistence
+
+An explicit preference set through `set()` or `toggle()` is written to `localStorage` under `storageKey` (default `"app-theme-preference"`). `getStored()` returns that value when it names a currently configured theme, or `null` when it is unset, invalid, or storage is unavailable (for example during SSR). `clearPreference()` removes the stored value and re-applies whichever theme `getSystem()` currently resolves to.
+
+Storage reads, writes, and removals that throw — a full quota, a disabled storage API, a private-browsing restriction — are logged with `console.error` and treated the same as unavailable storage; they never throw out of `Theme` methods.
+
+## Cross-tab sync
+
+Every tab running `createTheme().init()` against the same `storageKey` stays in sync: a `storage` event fires in every other tab when one tab writes a new preference, and each one applies the change if it names a valid configured theme. A tab with its own runtime token overrides keeps them — only the active theme name changes from cross-tab sync, not tokens passed in-process.
+
+The OS `prefers-color-scheme` media query applies automatically only while no valid stored preference exists. Once a tab (or a previous session) has stored an explicit preference, later system-preference changes are ignored until `clearPreference()` runs.
+
+## Reacting to changes
+
+`subscribe(listener)` registers a callback invoked after every applied change — from `init()`, `set()`, `toggle()`, `clearPreference()`, or an accepted `system` or cross-tab update — and returns an unsubscribe function:
+
+```ts
+const unsubscribe = theme.subscribe(({ name, source }) => {
+  console.log(`theme is now "${name}" (${source})`);
+});
+```
+
+A subscriber that throws is logged and does not stop other subscribers from running. Browsers also receive a `window` `CustomEvent` named by the exported `THEME_CHANGE_EVENT` constant (`"themechange"`) carrying the same detail, for code that prefers DOM events over `subscribe()`.
+
+<!-- Source: docs/changelog/0.1.2.md -->
+
+# 0.1.2
+
+## Added
+
+- A generated API reference, `docs/reference/index.md`, covering every exported symbol from its TSDoc directly — regenerated on every release instead of hand-maintained separately, so it can't drift out of sync with the source.
+
+## Changed
+
+- Documentation split from one page, `docs/reference.md`, into three focused ones: `docs/index.md` (setup and configuration), `docs/tokens-and-persistence.md` (token resolution, `skipComputed`, persistence, cross-tab sync), and `docs/ssr-and-pre-paint.md` (`getPrePaintScript()`, SSR fallback, Tailwind's `isTailwindCss`, `shouldApplyClass`, `destroy({ revertDom: true })`), plus the generated reference above. Update any link that pointed at `docs/reference.md`.

package/llms.txt

@@ -1,13 +1,19 @@
-# @codenhub/theme
-
-> Zero-dependency browser theme preference, persistence, DOM, cross-tab, event,
-> and token manager with SSR-safe fallbacks.
-
-Call `init()` in the browser, keep pre-paint logic aligned with configuration,
-and call `destroy()` to release media-query/storage listeners and subscribers.
-
-## Documentation
-
-- [Documentation overview](docs/index.md): Purpose, status, and starting points.
-- [API, persistence, DOM, and SSR behavior](docs/reference.md): Complete exports,
-  configuration, tokens, listeners, failures, pre-paint behavior, and cleanup.
+# @codenhub/theme
+
+> Zero-dependency browser theme preference, persistence, DOM, cross-tab, event,
+> and token manager with SSR-safe fallbacks.
+
+Call `init()` in the browser, keep pre-paint logic aligned with configuration,
+and call `destroy()` to release media-query/storage listeners and subscribers.
+
+## Documentation
+
+- [Documentation overview](docs/index.md): Purpose, status, and starting points.
+- [Tokens, persistence, and cross-tab sync](docs/tokens-and-persistence.md): Token
+  resolution priority, `localStorage` persistence, and cross-tab sync.
+- [SSR, pre-paint, and Tailwind](docs/ssr-and-pre-paint.md): FOUC prevention, SSR
+  fallbacks, and Tailwind `dark` class toggling.
+
+## Optional
+
+- [API reference](docs/reference/index.md): Generated per-symbol signatures and prose.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codenhub/theme",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "description": "Zero-dependency browser theme preference helper for TypeScript apps.",
   "homepage": "https://github.com/codenhub/codenhub/tree/main/packages/theme",
@@ -29,32 +29,35 @@
   "publishConfig": {
     "access": "public"
   },
-  "devDependencies": {
-    "@playwright/test": "^1.61.1",
-    "jsdom": "^29.1.1",
-    "tsdown": "^0.22.3",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.10",
-    "@codenhub/styles": "0.1.0",
-    "@codenhub/vite-plugin-icons": "0.0.1"
-  },
-  "codenhub": {
-    "docs": {
-      "label": "Theme",
-      "status": "active"
-    }
-  },
   "scripts": {
     "dev": "pnpm --filter=@codenhub/theme-dev dev",
     "debug": "pnpm build && pnpm --filter=@codenhub/theme-debug dev",
     "build": "tsdown src/index.ts --format esm --dts --clean --no-fixed-extension --minify",
+    "prepublishOnly": "pnpm build && pnpm typecheck",
     "status:npm": "npm view @codenhub/theme version dist-tags time --json && npm dist-tag ls @codenhub/theme && npm access get status @codenhub/theme",
-    "status:pack": "npm pack --dry-run",
-    "test": "vitest run && pnpm build && pnpm test:visual",
+    "status:pack": "npm pack --dry-run --ignore-scripts",
+    "test": "vitest run",
+    "test:browser": "playwright test",
+    "test:browser:watch": "playwright test --ui",
     "test:coverage": "vitest run --coverage",
-    "test:visual": "playwright test",
     "test:watch": "vitest",
-    "test:visual:watch": "playwright test --ui",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc -b"
+  },
+  "devDependencies": {
+    "@playwright/test": "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "jsdom": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "codenhub": {
+    "docs": {
+      "label": "ThemeSystem",
+      "status": "active",
+      "reference": {
+        "prose": true
+      }
+    }
   }
-}
+}

package/docs/reference.md

@@ -1,104 +0,0 @@
----
-title: Reference
----
-
-# Theme API, Persistence, DOM, and SSR Behavior
-
-## Create and Initialize
-
-`createTheme<TSchema>(options?): Theme<TSchema>` validates configuration and
-creates a manager. `ThemeOptions` contains:
-
-- `themes`: definitions, defaulting to `LIGHT_THEME` and `DARK_THEME`.
-- `defaultTheme`: pre-init and SSR fallback, default `"light"`.
-- `systemTheme`: configured names for light/dark OS preference.
-- `storageKey`: `localStorage` key, default `"app-theme-preference"`.
-- `attribute`: document-root attribute, default `"data-theme"`.
-- `isTailwindCss`: toggle the root `dark` class, default `false`.
-- `shouldApplyClass`: add `theme-${name}` by default, disable classes, or return
-  one custom class token with a `ThemeClassResolver`.
-- `tokenSchema`: maps typed token names to CSS custom-property names.
-
-`ThemeDefinition` has a unique `name`, `colorScheme` (`light` or `dark`),
-optional static tokens, and optional `pairedTheme` target for `toggle()`.
-`SystemThemeMap` maps OS light and dark preferences.
-
-`init(tokens?)` is idempotent until `destroy()`. It registers media-query and
-cross-tab storage listeners, selects valid stored preference before system
-preference, applies the theme, and emits an `"init"` change.
-
-## Theme Operations
-
-- `get(options?)` returns the active definition. Tokens merge computed CSS values,
-  static theme values, then runtime overrides. Reading computed values can force
-  style calculation; pass `{ skipComputed: true }` to bypass reading computed DOM styles.
-- `set(name, tokens?)` applies and persists a configured theme; unknown names
-  throw.
-- `toggle(tokens?)` switches to `pairedTheme` if defined on the active theme, or
-  otherwise by active `colorScheme` between the names in `systemTheme`, then
-  persists the choice.
-- `clearPreference()` removes storage and applies the current system theme.
-- `getStored()` returns a valid configured stored name or `null`.
-- `getSystem()` returns the mapped system theme, or `defaultTheme` when media
-  queries are unavailable.
-- `getPrePaintScript()` returns a synchronous inline IIFE script string to inject
-  into document `<head>` to prevent flash of unstyled content (FOUC). Supports custom
-  class resolvers and static token custom properties. Also available as standalone export
-  `getPrePaintScript(options?)`.
-
-Runtime token overrides persist across theme changes. Passing a new object,
-including `{}`, replaces them. Tokens require a schema and unknown token keys
-throw.
-
-## DOM, Persistence, and Events
-
-Applying a theme sets the configured root attribute and
-`document.documentElement.style.colorScheme`, updates configured theme classes,
-toggles Tailwind's `dark` class when enabled, and writes mapped token values as
-CSS custom properties. The package supplies no CSS or token values beyond the
-built-in light/dark definitions.
-
-Explicit preferences use `localStorage`. `storage` events synchronize valid
-changes from other tabs. OS preference changes apply only while no valid stored
-preference exists. Storage read/write/remove failures are logged with
-`console.error` and treated as unavailable.
-
-`subscribe(ThemeChangeListener)` returns an unsubscribe function. Subscribers
-receive `ThemeChangeDetail` with `name`, `theme`, and `ThemeChangeSource`:
-`"init"`, `"set"`, `"toggle"`, `"clearPreference"`, or `"system"`. Subscriber
-errors are logged and do not stop later listeners. Browsers also receive a
-window `CustomEvent` named by `THEME_CHANGE_EVENT` (`"themechange"`).
-
-## Validation and Cleanup
-
-Creation throws for invalid attributes/storage keys, malformed or duplicate
-themes, invalid color schemes/classes/token schemas, and missing default/system
-theme names. Applying a custom class resolver can throw if it returns an empty
-or whitespace-containing class. Runtime token calls throw without a matching
-schema.
-
-`destroy(options?)` removes media-query and storage listeners, clears
-in-process subscribers and runtime tokens, and resets internal active state.
-By default, it does not remove persisted preference or revert attributes,
-classes, custom properties, or `colorScheme` already applied to the document;
-pass `{ revertDom: true }` to remove configured DOM attributes, classes, and
-CSS custom properties from `document.documentElement`.
-
-## SSR and Pre-Paint Behavior
-
-Without browser APIs, storage, DOM, events, and listeners are skipped;
-`getSystem()` uses `defaultTheme`. Calls remain usable but cannot produce server
-HTML attributes. To avoid a flash, applications must apply equivalent validated
-storage/system logic in a blocking pre-paint script or render matching server
-markup. Keep that logic aligned with custom names, mappings, storage key,
-attribute, classes, and color scheme. Note that `getPrePaintScript()` serializes
-static tokens defined on configured theme definitions (`ThemeDefinition.tokens`);
-runtime token overrides passed to `init(tokens)` or `set(name, tokens)` are applied
-during client-side execution after hydration.
-
-## Public Exports
-
-The root exports `createTheme`, `getPrePaintScript`, `THEME_CHANGE_EVENT`,
-`LIGHT_THEME`, and `DARK_THEME`, plus `Theme`, `ThemeDefinition`, `SystemThemeMap`,
-`ThemeClassResolver`, `ThemeChangeSource`, `ThemeChangeDetail`,
-`ThemeChangeListener`, and `ThemeOptions` types.