@ttoss/fsl-theme 1.1.21 → 2.0.0

package/dist/{helpers-CA4Qkxct.mjs → helpers-BXaKe2s3.mjs}

@@ -1,8 +1,19 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 //#region src/roots/helpers.ts
-/** Check if a value is a token reference like `{core.colors.brand.500}` */
+/**
+* Check if a value is a **pure** token reference like `{core.colors.brand.500}`.
+*
+* A pure ref is a single `{path}` with no interior braces. Compound expressions
+* (`clamp({a}, {b})`) and multi-ref strings (`{a} {b}`) are NOT pure refs — they
+* start `{`/end `}` but carry interior braces, and must go through the compound
+* resolution path instead. Without the interior-brace check `{a} {b}` would be
+* mis-parsed as the single path `a} {b`.
+*/
+var hasInteriorBraces = value => {
+  return value.indexOf("{", 1) !== -1 || value.indexOf("}") !== value.length - 1;
+};
 var isTokenRef = value => {
-  return typeof value === "string" && value.length > 2 && value.startsWith("{") && value.endsWith("}");
+  return typeof value === "string" && value.length > 2 && value.startsWith("{") && value.endsWith("}") && !hasInteriorBraces(value);
 };
 /** Extract the inner path from a token reference: `{core.colors.brand.500}` → `core.colors.brand.500` */
 var extractRefPath = ref => {
@@ -24,6 +35,14 @@ var isPlainObject = value => {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 };
 /**
+* Prototype-chain keys that must never be written from override data —
+* `result['__proto__']` reaches the prototype setter, not an own property.
+* Guards `createTheme`'s public `overrides` against prototype pollution.
+*/
+var isUnsafeMergeKey = key => {
+  return key === "__proto__" || key === "constructor" || key === "prototype";
+};
+/**
 * Recursively merges `overrides` into `base`.
 * - Plain objects are merged recursively.
 * - All other values (primitives, arrays) are replaced.
@@ -34,6 +53,7 @@ var deepMerge = (base, overrides) => {
     ...base
   };
   for (const key of Object.keys(overrides)) {
+    if (isUnsafeMergeKey(key)) continue;
     const baseVal = result[key];
     const overVal = overrides[key];
     if (overVal === void 0) continue;
@@ -69,73 +89,6 @@ var flattenTheme = theme => {
   };
 };
 /**
-* Compute the Levenshtein edit distance between two strings.
-* Used exclusively by `validateRefs` to power "did you mean?" suggestions.
-*/
-var levenshtein = (a, b) => {
-  const m = a.length;
-  const n = b.length;
-  const dp = Array.from({
-    length: m + 1
-  }, () => {
-    return Array.from({
-      length: n + 1
-    }, () => {
-      return 0;
-    });
-  });
-  for (let i = 0; i <= m; i++) dp[i][0] = i;
-  for (let j = 0; j <= n; j++) dp[0][j] = j;
-  for (let i = 1; i <= m; i++) for (let j = 1; j <= n; j++) dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
-  return dp[m][n];
-};
-/**
-* Validate that every `{ref}` in the merged theme points to an existing path.
-* Emits `console.warn` for each broken reference with a "did you mean?" suggestion.
-*
-* **DEV-only** — callers gate this behind `process.env.NODE_ENV !== 'production'`
-* so bundlers tree-shake the entire call in production builds.
-*/
-var validateRefs = theme => {
-  const {
-    core,
-    semantic
-  } = flattenTheme(theme);
-  const all = {
-    ...core,
-    ...semantic
-  };
-  const allKeys = Object.keys(all);
-  const findSuggestion = (refPath, candidates) => {
-    if (candidates.length === 0) return "";
-    let bestDist = Infinity;
-    let bestKey = "";
-    for (const candidate of candidates) {
-      const dist = levenshtein(refPath, candidate);
-      if (dist < bestDist) {
-        bestDist = dist;
-        bestKey = candidate;
-      }
-    }
-    if (bestDist <= Math.ceil(refPath.length * .4)) return `\n   Did you mean '{${bestKey}}'?`;
-    return "";
-  };
-  for (const [ownerKey, value] of Object.entries(all)) {
-    if (typeof value !== "string" || !value.includes("{")) continue;
-    let match;
-    const re = new RegExp(COMPOUND_REF_RE.source, COMPOUND_REF_RE.flags);
-    while ((match = re.exec(value)) !== null) {
-      const refPath = match[1];
-      if (all[refPath] !== void 0) continue;
-      const prefix = refPath.split(".")[0];
-      const suggestion = findSuggestion(refPath, allKeys.filter(k => {
-        return k.startsWith(prefix + ".");
-      }));
-      console.warn(`[fsl-theme] Invalid token reference '{${refPath}}' at path '${ownerKey}'.${suggestion}`);
-    }
-  }
-};
-/**
 * Flatten a `ThemeTokens` into a `Record<string, string | number>` with
 * every `{ref}` recursively resolved to its final raw value where possible.
 *
@@ -181,8 +134,8 @@ var toFlatTokens = (theme, options = {}) => {
   /**
   * Resolve all embedded `{path}` refs in a raw string expression.
   *
-  * Handles both pure refs (`{core.space.4}`) and compound expressions
-  * (`clamp({core.space.4}, {core.space.6}, {core.space.12})`).
+  * Handles both pure refs (`{core.spacing.4}`) and compound expressions
+  * (`clamp({core.spacing.4}, {core.spacing.6}, {core.spacing.12})`).
   */
   const resolveInline = (value, seen, ownerKey) => {
     return value.replace(COMPOUND_REF_RE, (_match, path) => {
@@ -195,7 +148,9 @@ var toFlatTokens = (theme, options = {}) => {
         reportUnresolved(ownerKey, path, "circular reference");
         return `{${path}}`;
       }
-      const resolved = resolveRef(target, new Set(seen).add(path), ownerKey);
+      const childSeen = new Set(seen).add(path);
+      const resolved = resolveRef(target, childSeen, ownerKey);
+      if (typeof resolved === "string" && resolved.includes("{")) return resolveInline(resolved, childSeen, ownerKey);
       return String(resolved);
     });
   };
@@ -208,4 +163,4 @@ var toFlatTokens = (theme, options = {}) => {
 };
 
 //#endregion
-export { flattenTheme as a, validateRefs as c, flattenObject as i, SAFE_ID_RE as n, isPlainObject as o, deepMerge as r, toFlatTokens as s, COMPOUND_REF_RE as t };
+export { flattenTheme as a, flattenObject as i, SAFE_ID_RE as n, isPlainObject as o, deepMerge as r, toFlatTokens as s, COMPOUND_REF_RE as t };

package/dist/{index-CsIjfw86.d.cts → index-7YL90Xqs.d.cts}

@@ -1,11 +1,38 @@
 
-import { a as DeepPartial, i as ThemeTokens, r as ThemeBundle, t as ModeOverride } from "./Types-BiBa17RL.cjs";
+import { a as ThemeTokens, i as ThemeBundle, o as DeepPartial, r as ThemeBrief, t as ModeOverride } from "./Types-BkaxtsMv.cjs";
 //#region src/baseTheme.d.ts
 /**
  * **Foundation** — Neutral baseline theme.
  *
  * System fonts, gray palette, and balanced proportions. Serves as the
  * canonical base that all other themes extend via `createTheme`.
+ *
+ * ## Theme brief
+ *
+ * Every value in this file is chosen so that the resolved bundle satisfies
+ * this brief. Changes that contradict the brief belong in a different theme,
+ * not in `baseTheme`.
+ *
+ * ```yaml
+ * name: base
+ * purpose: default built-in foundation for modern product UI
+ * primaryPosture: productive
+ * secondaryPosture: calm
+ * densityProfile: balanced
+ * readingMode: mixed
+ * pointerProfile: hybrid
+ * interactionRisk: medium
+ * surfaceModel: lightly-layered
+ * brandEnergy: quiet
+ * accessibilityTarget: AA+
+ * colorModeStrategy: dark-supported
+ * platformBias: web
+ * ```
+ *
+ * Intended feel: practical, calm, modern, trustworthy, easy to extend.
+ * Avoided feel: flashy, ornamental, cramped, fragile, overly branded.
+ *
+ * @see /docs/website/docs/design/design-system/design-tokens/theme-authoring.md#recommended-base-theme-brief
  */
 declare const baseTheme: ThemeTokens;
 declare const darkAlternate: ModeOverride;
@@ -58,7 +85,8 @@ declare const createTheme: ({
   baseMode,
   base,
   overrides,
-  alternate
+  alternate,
+  brief
 }?: {
   /**
    * Parent bundle to inherit from. `base`, `baseMode`, and `alternate` all
@@ -77,18 +105,14 @@ declare const createTheme: ({
    * Pass `null` to opt out of any alternate (single-mode theme).
    */
   alternate?: ModeOverride | null;
+  /**
+   * Machine-readable design brief. Inherited from `extends.meta` when omitted.
+   * Orthogonal to tokens — never affects DTCG/CSS output.
+   */
+  brief?: ThemeBrief;
 }) => ThemeBundle;
 //#endregion
 //#region src/themes/bruttal.d.ts
 declare const bruttal: ThemeBundle;
 //#endregion
-//#region src/themes/corporate.d.ts
-declare const corporate: ThemeBundle;
-//#endregion
-//#region src/themes/oca.d.ts
-declare const oca: ThemeBundle;
-//#endregion
-//#region src/themes/ventures.d.ts
-declare const ventures: ThemeBundle;
-//#endregion
-export { createTheme as a, bruttal as i, oca as n, baseTheme as o, corporate as r, darkAlternate as s, ventures as t };
+export { darkAlternate as i, createTheme as n, baseTheme as r, bruttal as t };

package/dist/{index-nJrjI0BA.d.mts → index-BmCTIOzh.d.mts}

@@ -1,11 +1,38 @@
 
-import { a as DeepPartial, i as ThemeTokens, r as ThemeBundle, t as ModeOverride } from "./Types-BiBa17RL.mjs";
+import { a as ThemeTokens, i as ThemeBundle, o as DeepPartial, r as ThemeBrief, t as ModeOverride } from "./Types-BkaxtsMv.mjs";
 //#region src/baseTheme.d.ts
 /**
  * **Foundation** — Neutral baseline theme.
  *
  * System fonts, gray palette, and balanced proportions. Serves as the
  * canonical base that all other themes extend via `createTheme`.
+ *
+ * ## Theme brief
+ *
+ * Every value in this file is chosen so that the resolved bundle satisfies
+ * this brief. Changes that contradict the brief belong in a different theme,
+ * not in `baseTheme`.
+ *
+ * ```yaml
+ * name: base
+ * purpose: default built-in foundation for modern product UI
+ * primaryPosture: productive
+ * secondaryPosture: calm
+ * densityProfile: balanced
+ * readingMode: mixed
+ * pointerProfile: hybrid
+ * interactionRisk: medium
+ * surfaceModel: lightly-layered
+ * brandEnergy: quiet
+ * accessibilityTarget: AA+
+ * colorModeStrategy: dark-supported
+ * platformBias: web
+ * ```
+ *
+ * Intended feel: practical, calm, modern, trustworthy, easy to extend.
+ * Avoided feel: flashy, ornamental, cramped, fragile, overly branded.
+ *
+ * @see /docs/website/docs/design/design-system/design-tokens/theme-authoring.md#recommended-base-theme-brief
  */
 declare const baseTheme: ThemeTokens;
 declare const darkAlternate: ModeOverride;
@@ -58,7 +85,8 @@ declare const createTheme: ({
   baseMode,
   base,
   overrides,
-  alternate
+  alternate,
+  brief
 }?: {
   /**
    * Parent bundle to inherit from. `base`, `baseMode`, and `alternate` all
@@ -77,18 +105,14 @@ declare const createTheme: ({
    * Pass `null` to opt out of any alternate (single-mode theme).
    */
   alternate?: ModeOverride | null;
+  /**
+   * Machine-readable design brief. Inherited from `extends.meta` when omitted.
+   * Orthogonal to tokens — never affects DTCG/CSS output.
+   */
+  brief?: ThemeBrief;
 }) => ThemeBundle;
 //#endregion
 //#region src/themes/bruttal.d.ts
 declare const bruttal: ThemeBundle;
 //#endregion
-//#region src/themes/corporate.d.ts
-declare const corporate: ThemeBundle;
-//#endregion
-//#region src/themes/oca.d.ts
-declare const oca: ThemeBundle;
-//#endregion
-//#region src/themes/ventures.d.ts
-declare const ventures: ThemeBundle;
-//#endregion
-export { createTheme as a, bruttal as i, oca as n, baseTheme as o, corporate as r, darkAlternate as s, ventures as t };
+export { darkAlternate as i, createTheme as n, baseTheme as r, bruttal as t };

package/dist/index.cjs

@@ -2,15 +2,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, {
   value: 'Module'
 });
-const require_createTheme = require('./createTheme-JOu16Shb.cjs');
+const require_createTheme = require('./createTheme--UFgVlEn.cjs');
 const require_themes_bruttal = require('./themes/bruttal.cjs');
-const require_themes_corporate = require('./themes/corporate.cjs');
-const require_themes_oca = require('./themes/oca.cjs');
-const require_themes_ventures = require('./themes/ventures.cjs');
 exports.baseTheme = require_createTheme.baseTheme;
 exports.bruttal = require_themes_bruttal.bruttal;
-exports.corporate = require_themes_corporate.corporate;
 exports.createTheme = require_createTheme.createTheme;
-exports.darkAlternate = require_createTheme.darkAlternate;
-exports.oca = require_themes_oca.oca;
-exports.ventures = require_themes_ventures.ventures;
+exports.darkAlternate = require_createTheme.darkAlternate;

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 
-import { a as DeepPartial, i as ThemeTokens, n as SemanticTokens, r as ThemeBundle, t as ModeOverride } from "./Types-BiBa17RL.cjs";
-import { a as createTheme, i as bruttal, n as oca, o as baseTheme, r as corporate, s as darkAlternate, t as ventures } from "./index-CsIjfw86.cjs";
+import { a as ThemeTokens, i as ThemeBundle, n as SemanticTokens, o as DeepPartial, r as ThemeBrief, t as ModeOverride } from "./Types-BkaxtsMv.cjs";
+import { i as darkAlternate, n as createTheme, r as baseTheme, t as bruttal } from "./index-7YL90Xqs.cjs";
 import { o as ThemeMode } from "./ssrScript-BVysxDws.cjs";
-import { c as ThemeStylesProps, n as ThemeHeadProps } from "./react-CGa6FlNL.cjs";
-export { type DeepPartial, type ModeOverride, type SemanticTokens, type ThemeBundle, type ThemeHeadProps, type ThemeMode, type ThemeStylesProps, type ThemeTokens, baseTheme, bruttal, corporate, createTheme, darkAlternate, oca, ventures };
+import { c as ThemeStylesProps, n as ThemeHeadProps } from "./react-Dt7vGAVG.cjs";
+export { type DeepPartial, type ModeOverride, type SemanticTokens, type ThemeBrief, type ThemeBundle, type ThemeHeadProps, type ThemeMode, type ThemeStylesProps, type ThemeTokens, baseTheme, bruttal, createTheme, darkAlternate };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 
-import { a as DeepPartial, i as ThemeTokens, n as SemanticTokens, r as ThemeBundle, t as ModeOverride } from "./Types-BiBa17RL.mjs";
-import { a as createTheme, i as bruttal, n as oca, o as baseTheme, r as corporate, s as darkAlternate, t as ventures } from "./index-nJrjI0BA.mjs";
+import { a as ThemeTokens, i as ThemeBundle, n as SemanticTokens, o as DeepPartial, r as ThemeBrief, t as ModeOverride } from "./Types-BkaxtsMv.mjs";
+import { i as darkAlternate, n as createTheme, r as baseTheme, t as bruttal } from "./index-BmCTIOzh.mjs";
 import { o as ThemeMode } from "./ssrScript-BVysxDws.mjs";
-import { c as ThemeStylesProps, n as ThemeHeadProps } from "./react-DnKxR2gK.mjs";
-export { type DeepPartial, type ModeOverride, type SemanticTokens, type ThemeBundle, type ThemeHeadProps, type ThemeMode, type ThemeStylesProps, type ThemeTokens, baseTheme, bruttal, corporate, createTheme, darkAlternate, oca, ventures };
+import { c as ThemeStylesProps, n as ThemeHeadProps } from "./react-C8JrZf-b.mjs";
+export { type DeepPartial, type ModeOverride, type SemanticTokens, type ThemeBrief, type ThemeBundle, type ThemeHeadProps, type ThemeMode, type ThemeStylesProps, type ThemeTokens, baseTheme, bruttal, createTheme, darkAlternate };

package/dist/index.mjs

@@ -1,7 +1,4 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { i as darkAlternate, n as createTheme, r as baseTheme } from "./createTheme-DzLnsknT.mjs";
+import { a as darkAlternate, i as baseTheme, n as createTheme } from "./createTheme-B6tVIikC.mjs";
 import { bruttal } from "./themes/bruttal.mjs";
-import { corporate } from "./themes/corporate.mjs";
-import { oca } from "./themes/oca.mjs";
-import { ventures } from "./themes/ventures.mjs";
-export { baseTheme, bruttal, corporate, createTheme, darkAlternate, oca, ventures };
+export { baseTheme, bruttal, createTheme, darkAlternate };

package/dist/{react-DnKxR2gK.d.mts → react-C8JrZf-b.d.mts}

@@ -1,5 +1,5 @@
 
-import { n as SemanticTokens, r as ThemeBundle } from "./Types-BiBa17RL.mjs";
+import { i as ThemeBundle, n as SemanticTokens } from "./Types-BkaxtsMv.mjs";
 import { a as ResolvedMode, o as ThemeMode, t as ThemeScriptConfig } from "./ssrScript-BVysxDws.mjs";
 import * as React from "react";
 
@@ -24,7 +24,15 @@ interface ThemeProviderProps {
    *
    * Passing `theme` enables `useTokens()` and `useResolvedTokens()` for all
    * descendants, and automatically injects the CSS Custom Properties `<style>`
-   * tag into the document head (React 19 hoisting).
+   * tag into the document head (React 19 hoisting, deduped by `href`).
+   *
+   * **React version:** auto-injection into `<head>` requires **React 19** style
+   * hoisting. On React 18 the `<style>` renders inline where the provider sits
+   * (not hoisted); use `<ThemeHead>` / `<ThemeStyles>` in your `<head>` for
+   * explicit injection there — but do not also pass `theme` here, since the
+   * href-less `<ThemeHead>`/`<ThemeStyles>` tag does not dedup against this
+   * provider's href-keyed one. The stable `href` only collapses multiple themed
+   * `<ThemeProvider>`s sharing a `themeId` into one tag on 19.
    *
    * @example
    * ```tsx
@@ -47,6 +55,21 @@ interface ThemeProviderProps {
    * `resolvedMode` (actual: `'light' | 'dark'`), covering all integration
    * needs in one callback.
    *
+   * **System mode:** when `mode` is `'system'`, this callback fires whenever
+   * the OS `prefers-color-scheme` changes (e.g. automatic dark mode at sunset)
+   * — without any user interaction. Avoid side-effects that should only happen
+   * on explicit user action (e.g. API calls, toast notifications):
+   *
+   * ```tsx
+   * onModeChange={(mode, resolvedMode) => {
+   *   // ✓ safe for system-triggered changes
+   *   analytics.track('modeChanged', { mode, resolvedMode });
+   *
+   *   // ✗ guard explicit user actions
+   *   if (mode !== 'system') showToast('Theme updated');
+   * }}
+   * ```
+   *
    * @example
    * ```tsx
    * <ThemeProvider
@@ -286,6 +309,10 @@ interface ThemeStylesProps {
  * `dangerouslySetInnerHTML` is safe: content comes exclusively from
  * `toCssVars()` (a pure internal function) — no user input is interpolated.
  *
+ * Renders a plain inline `<style>` where you place it (put it in `<head>`).
+ * Do **not** also pass `theme` to `<ThemeProvider>` — that injects a second
+ * copy; pass `theme` to the head component only (see README SSR section).
+ *
  * @example
  * ```tsx
  * // SSR escape hatch — no themeId needed for canonical 1-theme model
@@ -337,6 +364,12 @@ interface ThemeHeadProps extends ThemeStylesProps {
  * Use in SSR frameworks (Next.js, Remix) where you need explicit `<head>`
  * injection. In CSR apps, `<ThemeProvider theme={...}>` handles everything.
  *
+ * **`storageKey` invariant:** `ThemeHead` forwards `storageKey` to `ThemeScript`,
+ * which reads localStorage before the first paint. `ThemeProvider` reads the
+ * same key at runtime. If you pass a custom `storageKey`, pass the **same value**
+ * to both `<ThemeHead>` and `<ThemeProvider>` — a mismatch causes a theme flash
+ * exactly in the scenario this component was designed to prevent.
+ *
  * @example
  * ```tsx
  * // Next.js app/layout.tsx
@@ -358,6 +391,14 @@ interface ThemeHeadProps extends ThemeStylesProps {
  *   );
  * }
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom storageKey — must be identical on both sides
+ * <ThemeHead theme={myTheme} storageKey="my-app-theme" />
+ * // ...
+ * <ThemeProvider theme={myTheme} storageKey="my-app-theme">{children}</ThemeProvider>
+ * ```
  */
 declare const ThemeHead: ({
   theme,

package/dist/{react-CoWIQYx_.cjs → react-DLB8nrXQ.cjs}

@@ -26,14 +26,25 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-const require_helpers = require('./helpers-C29fy-Ad.cjs');
+const require_helpers = require('./helpers-BU40JvFA.cjs');
 const require_css = require('./css.cjs');
-const require_ssrScript = require('./ssrScript-DOpLExaG.cjs');
+const require_ssrScript = require('./ssrScript-MF5SIONH.cjs');
 let react = require("react");
 react = __toESM(react);
 let react_jsx_runtime = require("react/jsx-runtime");
 
 //#region src/react.tsx
+/**
+* Stable `href` for the theme's hoistable `<style>` tag. React 19 keys style
+* hoisting **and dedup** on `href` + `precedence`, so re-renders and multiple
+* `<ThemeProvider>`s sharing a `themeId` collapse to a single tag, while
+* distinct `themeId`s coexist (micro-frontends). Note: `ThemeStyles` /
+* `ThemeHead` render an href-less inline `<style>`, so they do **not** dedup
+* against this hoisted tag — don't combine them with a themed `ThemeProvider`.
+*/
+var themeStyleHref = themeId => {
+  return `tt-theme-${themeId ?? "root"}`;
+};
 var COARSE_QUERY = "(any-pointer: coarse)";
 /**
 * Subscribe to coarse-pointer media query changes.
@@ -188,6 +199,7 @@ var ThemeProvider = ({
   });
   if (theme) return /* @__PURE__ */(0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, {
     children: [/* @__PURE__ */(0, react_jsx_runtime.jsx)("style", {
+      href: themeStyleHref(themeId),
       precedence: "default",
       children: cssContent
     }), /* @__PURE__ */(0, react_jsx_runtime.jsx)(ResolvedTokensCtx.Provider, {
@@ -344,6 +356,10 @@ var ThemeScript = ({
 * `dangerouslySetInnerHTML` is safe: content comes exclusively from
 * `toCssVars()` (a pure internal function) — no user input is interpolated.
 *
+* Renders a plain inline `<style>` where you place it (put it in `<head>`).
+* Do **not** also pass `theme` to `<ThemeProvider>` — that injects a second
+* copy; pass `theme` to the head component only (see README SSR section).
+*
 * @example
 * ```tsx
 * // SSR escape hatch — no themeId needed for canonical 1-theme model
@@ -393,6 +409,12 @@ var ThemeStyles = ({
 * Use in SSR frameworks (Next.js, Remix) where you need explicit `<head>`
 * injection. In CSR apps, `<ThemeProvider theme={...}>` handles everything.
 *
+* **`storageKey` invariant:** `ThemeHead` forwards `storageKey` to `ThemeScript`,
+* which reads localStorage before the first paint. `ThemeProvider` reads the
+* same key at runtime. If you pass a custom `storageKey`, pass the **same value**
+* to both `<ThemeHead>` and `<ThemeProvider>` — a mismatch causes a theme flash
+* exactly in the scenario this component was designed to prevent.
+*
 * @example
 * ```tsx
 * // Next.js app/layout.tsx
@@ -414,6 +436,14 @@ var ThemeStyles = ({
 *   );
 * }
 * ```
+*
+* @example
+* ```tsx
+* // Custom storageKey — must be identical on both sides
+* <ThemeHead theme={myTheme} storageKey="my-app-theme" />
+* // ...
+* <ThemeProvider theme={myTheme} storageKey="my-app-theme">{children}</ThemeProvider>
+* ```
 */
 var ThemeHead = ({
   theme,

package/dist/{react-CGa6FlNL.d.cts → react-Dt7vGAVG.d.cts}

@@ -1,5 +1,5 @@
 
-import { n as SemanticTokens, r as ThemeBundle } from "./Types-BiBa17RL.cjs";
+import { i as ThemeBundle, n as SemanticTokens } from "./Types-BkaxtsMv.cjs";
 import { a as ResolvedMode, o as ThemeMode, t as ThemeScriptConfig } from "./ssrScript-BVysxDws.cjs";
 import * as React from "react";
 
@@ -24,7 +24,15 @@ interface ThemeProviderProps {
    *
    * Passing `theme` enables `useTokens()` and `useResolvedTokens()` for all
    * descendants, and automatically injects the CSS Custom Properties `<style>`
-   * tag into the document head (React 19 hoisting).
+   * tag into the document head (React 19 hoisting, deduped by `href`).
+   *
+   * **React version:** auto-injection into `<head>` requires **React 19** style
+   * hoisting. On React 18 the `<style>` renders inline where the provider sits
+   * (not hoisted); use `<ThemeHead>` / `<ThemeStyles>` in your `<head>` for
+   * explicit injection there — but do not also pass `theme` here, since the
+   * href-less `<ThemeHead>`/`<ThemeStyles>` tag does not dedup against this
+   * provider's href-keyed one. The stable `href` only collapses multiple themed
+   * `<ThemeProvider>`s sharing a `themeId` into one tag on 19.
    *
    * @example
    * ```tsx
@@ -47,6 +55,21 @@ interface ThemeProviderProps {
    * `resolvedMode` (actual: `'light' | 'dark'`), covering all integration
    * needs in one callback.
    *
+   * **System mode:** when `mode` is `'system'`, this callback fires whenever
+   * the OS `prefers-color-scheme` changes (e.g. automatic dark mode at sunset)
+   * — without any user interaction. Avoid side-effects that should only happen
+   * on explicit user action (e.g. API calls, toast notifications):
+   *
+   * ```tsx
+   * onModeChange={(mode, resolvedMode) => {
+   *   // ✓ safe for system-triggered changes
+   *   analytics.track('modeChanged', { mode, resolvedMode });
+   *
+   *   // ✗ guard explicit user actions
+   *   if (mode !== 'system') showToast('Theme updated');
+   * }}
+   * ```
+   *
    * @example
    * ```tsx
    * <ThemeProvider
@@ -286,6 +309,10 @@ interface ThemeStylesProps {
  * `dangerouslySetInnerHTML` is safe: content comes exclusively from
  * `toCssVars()` (a pure internal function) — no user input is interpolated.
  *
+ * Renders a plain inline `<style>` where you place it (put it in `<head>`).
+ * Do **not** also pass `theme` to `<ThemeProvider>` — that injects a second
+ * copy; pass `theme` to the head component only (see README SSR section).
+ *
  * @example
  * ```tsx
  * // SSR escape hatch — no themeId needed for canonical 1-theme model
@@ -337,6 +364,12 @@ interface ThemeHeadProps extends ThemeStylesProps {
  * Use in SSR frameworks (Next.js, Remix) where you need explicit `<head>`
  * injection. In CSR apps, `<ThemeProvider theme={...}>` handles everything.
  *
+ * **`storageKey` invariant:** `ThemeHead` forwards `storageKey` to `ThemeScript`,
+ * which reads localStorage before the first paint. `ThemeProvider` reads the
+ * same key at runtime. If you pass a custom `storageKey`, pass the **same value**
+ * to both `<ThemeHead>` and `<ThemeProvider>` — a mismatch causes a theme flash
+ * exactly in the scenario this component was designed to prevent.
+ *
  * @example
  * ```tsx
  * // Next.js app/layout.tsx
@@ -358,6 +391,14 @@ interface ThemeHeadProps extends ThemeStylesProps {
  *   );
  * }
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom storageKey — must be identical on both sides
+ * <ThemeHead theme={myTheme} storageKey="my-app-theme" />
+ * // ...
+ * <ThemeProvider theme={myTheme} storageKey="my-app-theme">{children}</ThemeProvider>
+ * ```
  */
 declare const ThemeHead: ({
   theme,

package/dist/react.cjs

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, {
   value: 'Module'
 });
-const require_react = require('./react-CoWIQYx_.cjs');
+const require_react = require('./react-DLB8nrXQ.cjs');
 exports.ThemeHead = require_react.ThemeHead;
 exports.ThemeProvider = require_react.ThemeProvider;
 exports.ThemeScript = require_react.ThemeScript;

package/dist/react.d.cts

@@ -1,4 +1,4 @@
 
 import { a as ResolvedMode, o as ThemeMode } from "./ssrScript-BVysxDws.cjs";
-import { a as ThemeScript, c as ThemeStylesProps, d as useResolvedTokens, f as useTokens, i as ThemeProviderProps, l as UseColorModeResult, n as ThemeHeadProps, o as ThemeScriptProps, r as ThemeProvider, s as ThemeStyles, t as ThemeHead, u as useColorMode } from "./react-CGa6FlNL.cjs";
+import { a as ThemeScript, c as ThemeStylesProps, d as useResolvedTokens, f as useTokens, i as ThemeProviderProps, l as UseColorModeResult, n as ThemeHeadProps, o as ThemeScriptProps, r as ThemeProvider, s as ThemeStyles, t as ThemeHead, u as useColorMode } from "./react-Dt7vGAVG.cjs";
 export { type ResolvedMode, ThemeHead, ThemeHeadProps, type ThemeMode, ThemeProvider, ThemeProviderProps, ThemeScript, ThemeScriptProps, ThemeStyles, ThemeStylesProps, UseColorModeResult, useColorMode, useResolvedTokens, useTokens };

package/dist/react.d.mts

@@ -1,4 +1,4 @@
 
 import { a as ResolvedMode, o as ThemeMode } from "./ssrScript-BVysxDws.mjs";
-import { a as ThemeScript, c as ThemeStylesProps, d as useResolvedTokens, f as useTokens, i as ThemeProviderProps, l as UseColorModeResult, n as ThemeHeadProps, o as ThemeScriptProps, r as ThemeProvider, s as ThemeStyles, t as ThemeHead, u as useColorMode } from "./react-DnKxR2gK.mjs";
+import { a as ThemeScript, c as ThemeStylesProps, d as useResolvedTokens, f as useTokens, i as ThemeProviderProps, l as UseColorModeResult, n as ThemeHeadProps, o as ThemeScriptProps, r as ThemeProvider, s as ThemeStyles, t as ThemeHead, u as useColorMode } from "./react-C8JrZf-b.mjs";
 export { type ResolvedMode, ThemeHead, ThemeHeadProps, type ThemeMode, ThemeProvider, ThemeProviderProps, ThemeScript, ThemeScriptProps, ThemeStyles, ThemeStylesProps, UseColorModeResult, useColorMode, useResolvedTokens, useTokens };