@molecule/app-theme-css-variables 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,212 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-09-13T23:39:58.618Z
+-->
+
+# @molecule/app-theme-css-variables
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+CSS custom properties theme provider for molecule.dev.
+
+Provides a framework-agnostic ThemeProvider implementation that applies
+theme tokens as CSS custom properties (variables) to the document root.
+Works with any framework -- React, Vue, Svelte, Angular, Solid, or vanilla JS.
+
+## Quick Start
+
+```typescript
+import {
+  createCSSVariablesThemeProvider,
+  lightTheme,
+  darkTheme,
+} from '@molecule/app-theme-css-variables'
+import { setProvider } from '@molecule/app-theme'
+
+const provider = createCSSVariablesThemeProvider({
+  themes: [lightTheme, darkTheme],
+  defaultTheme: 'light',
+  persistKey: 'molecule-theme',
+})
+
+setProvider(provider)
+```
+
+Then use CSS variables in your stylesheets:
+
+```css
+.button {
+  background-color: var(--mol-color-primary);
+  color: var(--mol-color-text-inverse);
+  padding: var(--mol-spacing-sm) var(--mol-spacing-md);
+  border-radius: var(--mol-radius-md);
+  transition: background-color var(--mol-transition-fast);
+}
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/app-theme-css-variables @molecule/app-theme
+```
+
+## API
+
+### Interfaces
+
+#### `CSSVariablesThemeConfig`
+
+Configuration for css variables theme.
+
+```typescript
+interface CSSVariablesThemeConfig {
+  /** Available themes. */
+  themes: Theme[]
+  /** Name of the default theme to use. */
+  defaultTheme?: string
+  /** CSS variable prefix (default: 'mol'). */
+  prefix?: string
+  /** Whether to auto-apply CSS variables to :root (default: true). */
+  applyToDocument?: boolean
+  /**
+   * Key for persisting the selected theme name across reloads. When `storage`
+   * is omitted, persistence falls back to `window.localStorage` in browser
+   * environments; in SSR / non-browser environments persistence is skipped.
+   */
+  persistKey?: string
+  /**
+   * Storage adapter for persisting theme preference. Optional — when omitted
+   * and `persistKey` is set, `window.localStorage` is used when available.
+   * Provide an adapter for React Native (AsyncStorage wrapper) or custom stores.
+   */
+  storage?: ThemeStorageAdapter
+  /**
+   * With no persisted choice, start on the theme whose `mode` matches the
+   * OS preference (`prefers-color-scheme`) instead of `defaultTheme`.
+   * Browser-only: a render without a window — a server, a build-time
+   * prerender — starts on `defaultTheme`, which `getServerTheme()` reports
+   * so a hydrating client renders the markup it was sent before switching.
+   * Default: false.
+   */
+  systemDefault?: boolean
+}
+```
+
+#### `ThemeStorageAdapter`
+
+Minimal storage adapter for theme persistence. Compatible with
+localStorage, sessionStorage, or any custom implementation
+(e.g., React Native AsyncStorage wrapper, SSR no-op).
+
+```typescript
+interface ThemeStorageAdapter {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+}
+```
+
+### Functions
+
+#### `createCSSVariablesThemeProvider(config)`
+
+Creates a framework-agnostic ThemeProvider that applies theme tokens
+as CSS custom properties on the document root element.
+
+```typescript
+function createCSSVariablesThemeProvider(config: CSSVariablesThemeConfig): ThemeProvider
+```
+
+- `config` — Theme provider configuration (available themes, default theme, CSS variable prefix, persistence).
+
+**Returns:** A ThemeProvider that applies themes as CSS custom properties on the document root.
+
+### Constants
+
+#### `darkTheme`
+
+Default dark theme.
+
+Dark backgrounds (#0f172a, #1e293b), light text, blue primary (#60a5fa).
+
+```typescript
+const darkTheme: Theme
+```
+
+#### `lightTheme`
+
+Default light theme.
+
+Near-white backgrounds (#f6f6f6 background, #ffffff surface), dark text,
+blue primary (#4070e0).
+
+```typescript
+const lightTheme: Theme
+```
+
+#### `provider`
+
+Default CSS variables theme provider with light and dark themes.
+
+```typescript
+const provider: ThemeProvider
+```
+
+## Core Interface
+
+Implements `@molecule/app-theme` interface.
+
+## Bond Wiring
+
+Setup function to register this provider with the core interface:
+
+```typescript
+import { setProvider } from '@molecule/app-theme'
+import { provider } from '@molecule/app-theme-css-variables'
+
+export function setupThemeCssVariables(): void {
+  setProvider(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/app-theme` ^1.0.1
+
+### Runtime Dependencies
+
+- `@molecule/app-theme`
+
+Recoloring a scaffolded app — where the palette actually lives:
+
+This bond writes `--mol-color-*` variables and toggles light/dark via a
+`data-mol-mode` attribute. In `@molecule/app-ui-tailwind`'s `base.css` the
+Tailwind `@theme` reads each core token as
+`--color-primary: var(--mol-color-primary, <default>)`, so for a CUSTOM build
+(no per-app `theme.css`) this bond's `Theme` objects ARE the palette — edit
+`colors` here to recolor.
+
+BUT template-based apps ship `app/src/theme.css` that hardcodes `--color-*` on
+`:root` / `[data-mol-mode='dark']`. Those have the same `:root` specificity and
+load last, so they SHADOW the `var(--mol-color-*)` reference — the visible
+colors come only from `theme.css`. When `theme.css` defines colors, editing
+this bond has NO visible effect; recolor by editing `app/src/theme.css`. This
+bond still drives light/dark mode and is the palette for non-Tailwind targets
+(e.g. React Native). Precedence: `theme.css` > this bond > base defaults.
+
+The provider also toggles a `.dark` class on `<html>` (alongside the
+`data-mol-mode` attribute) so Tailwind `dark:` variants react to theme
+toggles — if `dark:` utilities aren't switching, check that this bond is
+wired and applying to the document.

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAS,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAG/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAmHzD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,uBAAuB,GAAG,aAAa,CAqF9F;AAED,uEAAuE;AACvE,eAAO,MAAM,QAAQ,EAAE,aAGrB,CAAA"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAS,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAG/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAmHzD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,uBAAuB,GAAG,aAAa,CAiH9F;AAED,uEAAuE;AACvE,eAAO,MAAM,QAAQ,EAAE,aAGrB,CAAA"}

package/dist/provider.js

@@ -135,7 +135,7 @@ function applyThemeToDocument(themes, activeTheme, prefix) {
  * @returns A ThemeProvider that applies themes as CSS custom properties on the document root.
  */
 export function createCSSVariablesThemeProvider(config) {
-    const { themes, defaultTheme, prefix = 'mol', applyToDocument = true, persistKey } = config;
+    const { themes, defaultTheme, prefix = 'mol', applyToDocument = true, persistKey, systemDefault = false, } = config;
     // If a persistKey is set without an explicit storage adapter, fall back to
     // window.localStorage. The previous behavior — persistKey but no storage =
     // silent no-op — was the source of "I toggled dark mode and it reset on
@@ -157,13 +157,29 @@ export function createCSSVariablesThemeProvider(config) {
                 },
             }
             : undefined);
-    let currentTheme = themes.find((t) => t.name === defaultTheme) || themes[0];
+    // What a render without a browser starts on — no storage, no media query.
+    const serverTheme = themes.find((t) => t.name === defaultTheme) || themes[0];
+    let currentTheme = serverTheme;
     const listeners = new Set();
     // Try to restore from storage adapter
+    let restored = false;
     if (persistKey && storage) {
         const saved = storage.getItem(persistKey);
         if (saved) {
             const found = themes.find((t) => t.name === saved);
+            if (found) {
+                currentTheme = found;
+                restored = true;
+            }
+        }
+    }
+    // Nothing persisted: follow the OS preference when asked to (browser only).
+    if (!restored && systemDefault) {
+        const matchMedia = globalThis
+            .matchMedia;
+        if (typeof matchMedia === 'function') {
+            const mode = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+            const found = themes.find((t) => t.mode === mode);
             if (found)
                 currentTheme = found;
         }
@@ -204,6 +220,9 @@ export function createCSSVariablesThemeProvider(config) {
         getThemes() {
             return themes;
         },
+        getServerTheme() {
+            return serverTheme;
+        },
     };
     return provider;
 }

package/dist/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGnD;;;;GAIG;AACH,SAAS,YAAY,CAAC,GAAW;IAC/B,OAAO,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAA;AAC5D,CAAC;AAED;;GAEG;AACH,SAAS,iBAAiB,CAAC,KAAY,EAAE,MAAc;IACrD,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QACxD,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,UAAU,YAAY,CAAC,GAAG,CAAC,KAAK,KAAK,GAAG,CAAC,CAAA;IACnE,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACzD,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,YAAY,GAAG,KAAK,KAAK,GAAG,CAAC,CAAA;IACvD,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9D,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,WAAW,GAAG,KAAK,KAAK,GAAG,CAAC,CAAA;IACtD,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACzD,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,WAAW,GAAG,KAAK,KAAK,GAAG,CAAC,CAAA;IACtD,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACvE,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,SAAS,GAAG,KAAK,KAAK,GAAG,CAAC,CAAA;IACpD,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrE,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,SAAS,GAAG,KAAK,KAAK,GAAG,CAAC,CAAA;IACpD,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACvE,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,gBAAgB,GAAG,KAAK,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACnE,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACvE,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,YAAY,GAAG,KAAK,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC/D,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7D,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,eAAe,YAAY,CAAC,GAAG,CAAC,KAAK,KAAK,GAAG,CAAC,CAAA;IACxE,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7D,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,eAAe,GAAG,KAAK,KAAK,GAAG,CAAC,CAAA;IAC1D,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QACxD,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,MAAM,GAAG,KAAK,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACzD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAS,oBAAoB,CAAC,MAAe,EAAE,WAAkB,EAAE,MAAc;IAC/E,IAAI,OAAO,QAAQ,KAAK,WAAW;QAAE,OAAM;IAE3C,MAAM,IAAI,GAAG,QAAQ,CAAC,eAAe,CAAA;IACrC,MAAM,OAAO,GAAG,GAAG,MAAM,aAAa,CAAA;IAEtC,gFAAgF;IAChF,IAAI,KAAK,GAAG,QAAQ,CAAC,cAAc,CAAC,OAAO,CAA4B,CAAA;IACvE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;QACvC,KAAK,CAAC,EAAE,GAAG,OAAO,CAAA;QAClB,yEAAyE;QACzE,mEAAmE;QACnE,yDAAyD;QACzD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,eAAe,CAAA;QACtD,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;IAC3C,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,gFAAgF;IAChF,gDAAgD;IAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAA;IACpE,IAAI,QAAQ,EAAE,CAAC;QACb,KAAK,CAAC,IAAI,CAAC,oBAAoB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IAC1E,CAAC;IACD,gEAAgE;IAChE,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,gBAAgB,MAAM,UAAU,CAAC,CAAC,IAAI,UAAU,iBAAiB,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IAC/F,CAAC;IACD,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAEtC,wCAAwC;IACxC,IAAI,CAAC,YAAY,CAAC,QAAQ,MAAM,QAAQ,EAAE,WAAW,CAAC,IAAI,CAAC,CAAA;IAC3D,IAAI,CAAC,YAAY,CAAC,QAAQ,MAAM,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,CAAA;IAE1D,wEAAwE;IACxE,4DAA4D;IAC5D,qEAAqE;IACrE,yEAAyE;IACzE,2CAA2C;IAC3C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI,KAAK,MAAM,CAAC,CAAA;AAC5D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,+BAA+B,CAAC,MAA+B;IAC7E,MAAM,EACJ,MAAM,EACN,YAAY,EACZ,MAAM,GAAG,KAAK,EACd,eAAe,GAAG,IAAI,EACtB,UAAU,EACV,aAAa,GAAG,KAAK,GACtB,GAAG,MAAM,CAAA;IAEV,2EAA2E;IAC3E,2EAA2E;IAC3E,wEAAwE;IACxE,uEAAuE;IACvE,4CAA4C;IAC5C,mEAAmE;IACnE,sEAAsE;IACtE,+CAA+C;IAC/C,MAAM,cAAc,GAAI,UAAkD,CAAC,YAAY,CAAA;IACvF,MAAM,OAAO,GACX,MAAM,CAAC,OAAO;QACd,CAAC,cAAc;YACf,OAAO,cAAc,CAAC,OAAO,KAAK,UAAU;YAC5C,OAAO,cAAc,CAAC,OAAO,KAAK,UAAU;YAC1C,CAAC,CAAC;gBACE,OAAO,EAAE,CAAC,GAAW,EAAiB,EAAE,CACrC,cAAc,CAAC,OAAwC,CAAC,GAAG,CAAC;gBAC/D,OAAO,EAAE,CAAC,GAAW,EAAE,KAAa,EAAQ,EAAE;oBAC5C,CAAC;oBAAC,cAAc,CAAC,OAA0C,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;gBACzE,CAAC;aACF;YACH,CAAC,CAAC,SAAS,CAAC,CAAA;IAEhB,0EAA0E;IAC1E,MAAM,WAAW,GAAU,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAA;IACnF,IAAI,YAAY,GAAU,WAAW,CAAA;IAErC,MAAM,SAAS,GAAG,IAAI,GAAG,EAA0B,CAAA;IAEnD,sCAAsC;IACtC,IAAI,QAAQ,GAAG,KAAK,CAAA;IACpB,IAAI,UAAU,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;QACzC,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,CAAA;YAClD,IAAI,KAAK,EAAE,CAAC;gBACV,YAAY,GAAG,KAAK,CAAA;gBACpB,QAAQ,GAAG,IAAI,CAAA;YACjB,CAAC;QACH,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,IAAI,CAAC,QAAQ,IAAI,aAAa,EAAE,CAAC;QAC/B,MAAM,UAAU,GAAI,UAAuE;aACxF,UAAU,CAAA;QACb,IAAI,OAAO,UAAU,KAAK,UAAU,EAAE,CAAC;YACrC,MAAM,IAAI,GAAG,UAAU,CAAC,8BAA8B,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAA;YAClF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;YACjD,IAAI,KAAK;gBAAE,YAAY,GAAG,KAAK,CAAA;QACjC,CAAC;IACH,CAAC;IAED,sBAAsB;IACtB,IAAI,eAAe,EAAE,CAAC;QACpB,oBAAoB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,CAAA;IACpD,CAAC;IAED,MAAM,QAAQ,GAAkB;QAC9B,QAAQ;YACN,OAAO,YAAY,CAAA;QACrB,CAAC;QAED,QAAQ,CAAC,KAAqB;YAC5B,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;YACzF,IAAI,CAAC,QAAQ;gBAAE,OAAM;YAErB,YAAY,GAAG,QAAQ,CAAA;YAEvB,IAAI,eAAe,EAAE,CAAC;gBACpB,oBAAoB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,CAAA;YACpD,CAAC;YAED,IAAI,UAAU,IAAI,OAAO,EAAE,CAAC;gBAC1B,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,YAAY,CAAC,IAAI,CAAC,CAAA;YAChD,CAAC;YAED,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAA;QAC7C,CAAC;QAED,UAAU;YACR,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAA;YACnE,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAA;YAC1D,IAAI,QAAQ;gBAAE,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;QAC3C,CAAC;QAED,SAAS,CAAC,QAAgC;YACxC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACvB,OAAO,GAAG,EAAE;gBACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;YAC5B,CAAC,CAAA;QACH,CAAC;QAED,SAAS;YACP,OAAO,MAAM,CAAA;QACf,CAAC;QAED,cAAc;YACZ,OAAO,WAAW,CAAA;QACpB,CAAC;KACF,CAAA;IAED,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,uEAAuE;AACvE,MAAM,CAAC,MAAM,QAAQ,GAAkB,+BAA+B,CAAC;IACrE,MAAM,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,YAAY,EAAE,OAAO;CACtB,CAAC,CAAA"}

package/dist/types.d.ts

@@ -37,5 +37,14 @@ export interface CSSVariablesThemeConfig {
      * Provide an adapter for React Native (AsyncStorage wrapper) or custom stores.
      */
     storage?: ThemeStorageAdapter;
+    /**
+     * With no persisted choice, start on the theme whose `mode` matches the
+     * OS preference (`prefers-color-scheme`) instead of `defaultTheme`.
+     * Browser-only: a render without a window — a server, a build-time
+     * prerender — starts on `defaultTheme`, which `getServerTheme()` reports
+     * so a hydrating client renders the markup it was sent before switching.
+     * Default: false.
+     */
+    systemDefault?: boolean;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAEhD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACnC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,wBAAwB;IACxB,MAAM,EAAE,KAAK,EAAE,CAAA;IACf,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oEAAoE;IACpE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAC9B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAEhD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACnC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,wBAAwB;IACxB,MAAM,EAAE,KAAK,EAAE,CAAA;IACf,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oEAAoE;IACpE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAA;IAC7B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-theme-css-variables",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "CSS custom properties theme provider for molecule.dev",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -30,10 +31,10 @@
   "devDependencies": {
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "peerDependencies": {
-    "@molecule/app-theme": "^1.0.0"
+    "@molecule/app-theme": "^1.0.1"
   },
   "repository": {
     "type": "git",