@ttoss/fsl-theme 1.1.22 → 2.1.0

package/dist/{react-BKLEzIN8.cjs → react-DQErMGJz.cjs}

@@ -26,14 +26,76 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-const require_helpers = require('./helpers-CIqeJ8yd.cjs');
+const require_helpers = require('./helpers-BU40JvFA.cjs');
 const require_css = require('./css.cjs');
-const require_ssrScript = require('./ssrScript-D3mYscp1.cjs');
+const require_ssrScript = require('./ssrScript-D73WcrCM.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"}`;
+};
+/**
+* DEV-only registry of injected theme CSS per hoisted-style `href`.
+* React dedups hoisted `<style>` tags by `href`, so two providers with
+* *different* themes but the same `href` silently drop the second theme's
+* CSS. This registry detects that mismatch and warns.
+*/
+var injectedThemeCss = /* @__PURE__ */new Map();
+/**
+* Runs on the client before paint; falls back to `useEffect` on the server
+* so SSR renders never warn. Used for the runtime-creation effect so
+* `data-tt-*` attributes land before first paint in CSR apps (less mode flash).
+*/
+var useIsomorphicLayoutEffect = typeof window !== "undefined" ? react.useLayoutEffect : react.useEffect;
+var resolveRootElement = root => {
+  if (!root) return void 0;
+  if (root instanceof HTMLElement) return root;
+  return root.current ?? void 0;
+};
+/**
+* The OS-preference CSS fallback only makes sense when the app follows the
+* OS. A fixed `'light'`/`'dark'` default must not let `prefers-color-scheme`
+* override it on first paint.
+*/
+var shouldEmitSystemFallback = defaultMode => {
+  return (defaultMode ?? "system") === "system";
+};
+/**
+* DEV-only: warn when two providers with different themes share the same
+* hoisted-style `href` — React dedups by href, so the second theme's CSS is
+* silently dropped. Distinct `themeId`s give distinct hrefs and coexist.
+*/
+var useDedupMismatchWarning = (cssContent, themeId) => {
+  react.useEffect(() => {
+    if (process.env.NODE_ENV === "production" || !cssContent) return;
+    const href = themeStyleHref(themeId);
+    const entry = injectedThemeCss.get(href);
+    if (entry && entry.css !== cssContent) console.warn(`[fsl-theme] Two <ThemeProvider>s with different themes share the same style key "${href}". React dedups hoisted <style> tags by href, so only the first theme's CSS is injected. Give each theme a distinct themeId: <ThemeProvider theme={...} themeId="my-theme">.`);
+    const next = entry ?? {
+      css: cssContent,
+      count: 0
+    };
+    next.count += 1;
+    injectedThemeCss.set(href, next);
+    return () => {
+      const current = injectedThemeCss.get(href);
+      if (!current) return;
+      current.count -= 1;
+      if (current.count <= 0) injectedThemeCss.delete(href);
+    };
+  }, [cssContent, themeId]);
+};
 var COARSE_QUERY = "(any-pointer: coarse)";
 /**
 * Subscribe to coarse-pointer media query changes.
@@ -116,20 +178,26 @@ var ThemeProvider = ({
   children
 }) => {
   const runtimeRef = react.useRef(null);
-  const initDefaultMode = react.useRef(defaultMode);
-  const initStorageKey = react.useRef(storageKey);
+  const [initialDefaultMode] = react.useState(defaultMode);
+  const [initialStorageKey] = react.useState(storageKey);
   const [state, setState] = react.useState(() => {
     return {
       mode: defaultMode ?? "system",
       resolvedMode: (defaultMode ?? "system") === "system" ? "light" : defaultMode
     };
   });
-  react.useEffect(() => {
+  const [rootRetry, setRootRetry] = react.useState(0);
+  useIsomorphicLayoutEffect(() => {
+    if (root !== void 0 && !(root instanceof HTMLElement) && root.current === null && rootRetry === 0) {
+      setRootRetry(1);
+      return;
+    }
+    if (process.env.NODE_ENV !== "production" && root && !themeId) console.warn("[fsl-theme] `root` was passed without `themeId`. Without a themeId, the generated CSS targets `:root`/`:root[data-tt-mode=\"dark\"]` on <html>, but mode attributes are written to the `root` element — the alternate mode CSS will never match. Pass a `themeId` so CSS is scoped to `[data-tt-theme=\"<id>\"]` selectors that match the `root` element.");
     const runtime = require_ssrScript.createThemeRuntime({
       defaultTheme: themeId,
-      defaultMode: initDefaultMode.current,
-      storageKey: initStorageKey.current,
-      root
+      defaultMode: initialDefaultMode,
+      storageKey: initialStorageKey,
+      root: resolveRootElement(root)
     });
     runtimeRef.current = runtime;
     setState(runtime.getState());
@@ -139,7 +207,7 @@ var ThemeProvider = ({
       runtime.destroy();
       runtimeRef.current = null;
     };
-  }, [root, themeId]);
+  }, [root, themeId, rootRetry]);
   const setMode = react.useCallback(mode => {
     runtimeRef.current?.setMode(mode);
   }, []);
@@ -158,8 +226,11 @@ var ThemeProvider = ({
     return applyCoarseHitOverrides(result, theme.base, isCoarse);
   }, [theme, semanticTokens, isCoarse]);
   const cssContent = react.useMemo(() => {
-    return theme ? require_css.getThemeStylesContent(theme, themeId) : null;
+    return theme ? require_css.getThemeStylesContent(theme, themeId, {
+      systemModeFallback: shouldEmitSystemFallback(initialDefaultMode)
+    }) : null;
   }, [theme, themeId]);
+  useDedupMismatchWarning(cssContent, themeId);
   const onModeChangeRef = react.useRef(onModeChange);
   react.useEffect(() => {
     onModeChangeRef.current = onModeChange;
@@ -188,6 +259,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, {
@@ -219,11 +291,11 @@ var useColorMode = () => {
 * inline styles produces silently broken rendering:
 *
 * ```tsx
-* // ✗ WRONG — tokens.colors.brand.main is '{core.colors.brand.main}', not '#FF0000'
-* <div style={{ color: tokens.colors.brand.main }} />
+* // ✗ WRONG — the leaf is '{core.colors.neutral.1000}' (a ref string), not a CSS color
+* <div style={{ color: tokens.colors.action.primary.text.default }} />
 *
 * // ✓ CSS consumers — use vars:
-* <div style={{ color: 'var(--tt-color-brand-main)' }} />
+* <div style={{ color: 'var(--tt-colors-action-primary-text-default)' }} />
 *
 * // ✓ Non-CSS consumers (React Native, canvas) — use useResolvedTokens():
 * const resolved = useResolvedTokens();
@@ -238,8 +310,8 @@ var useColorMode = () => {
 *
 * const Button = () => {
 *   const tokens = useTokens(); // introspection only
-*   // tokens.colors.action.primary.background.default → '{core.colors.brand.500}'
-*   return <button style={{ background: 'var(--tt-action-primary-background-default)' }} />;
+*   // tokens.colors.action.primary.background.default → '{core.colors.neutral.1000}'
+*   return <button style={{ background: 'var(--tt-colors-action-primary-background-default)' }} />;
 * };
 * ```
 */
@@ -264,13 +336,21 @@ var useTokens = () => {
 *
 * ```tsx
 * // ✓ CSS (browser)
-* <div style={{ color: 'var(--tt-color-informational-primary-default)' }} />
+* <div style={{ color: 'var(--tt-colors-informational-primary-text-default)' }} />
 *
 * // ✓ Non-CSS (React Native, canvas)
 * const resolved = useResolvedTokens();
 * <View style={{ backgroundColor: resolved['semantic.colors.action.primary.background.default'] }} />
 * ```
 *
+* ### ⚠ CSS-coupled tokens stay unresolved
+* A registered set of dimensional tokens (model.md §8 — spacing steps, fluid
+* `text.*.fontSize`, `sizing.hit.*`, `sizing.viewport.*`, `sizing.measure.reading`,
+* `spacing.gutter.*`) carry CSS-only constructs (`var()`, `calc()`, `clamp()`,
+* `cqi`, `dvh`, `ch`). This hook returns those **as-is** — they are not usable
+* outside a CSS engine. Colors, opacity, z-index, font weights/leading and
+* other scalar tokens resolve to plain raw values and are safe everywhere.
+*
 * Requires `<ThemeProvider theme={...}>`.
 *
 * @example
@@ -344,6 +424,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
@@ -377,12 +461,15 @@ var ThemeScript = ({
 var ThemeStyles = ({
   theme,
   themeId,
-  nonce
+  nonce,
+  systemModeFallback
 }) => {
   return /* @__PURE__ */(0, react_jsx_runtime.jsx)("style", {
     nonce,
     dangerouslySetInnerHTML: {
-      __html: require_css.getThemeStylesContent(theme, themeId)
+      __html: require_css.getThemeStylesContent(theme, themeId, {
+        systemModeFallback
+      })
     }
   });
 };
@@ -445,7 +532,8 @@ var ThemeHead = ({
     }), /* @__PURE__ */(0, react_jsx_runtime.jsx)(ThemeStyles, {
       theme,
       themeId,
-      nonce
+      nonce,
+      systemModeFallback: shouldEmitSystemFallback(defaultMode)
     })]
   });
 };

package/dist/{react-BXqSYnmk.d.cts → react-Drr-QSuX.d.cts}

@@ -1,9 +1,17 @@
 
-import { n as SemanticTokens, r as ThemeBundle } from "./Types-BiBa17RL.cjs";
+import { i as ThemeBundle, n as SemanticTokens } from "./Types-a_sfpbha.cjs";
 import { a as ResolvedMode, o as ThemeMode, t as ThemeScriptConfig } from "./ssrScript-BVysxDws.cjs";
 import * as React from "react";
 
 //#region src/react.d.ts
+/**
+ * Accepted shapes for the `root` prop: a concrete element, or a ref object.
+ * Prefer the ref form — refs are populated before layout effects run, so the
+ * runtime attaches directly to the target element with no transient attach
+ * to `<html>` on the first render (the element form is `null` during the
+ * first render when read from `ref.current`).
+ */
+type ThemeRootInput = HTMLElement | React.RefObject<HTMLElement | null>;
 /**
  * Props for the `ThemeProvider` component.
  */
@@ -24,7 +32,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
@@ -75,25 +91,32 @@ interface ThemeProviderProps {
   onModeChange?: (mode: ThemeMode, resolvedMode: ResolvedMode) => void;
   /**
    * Root element to anchor `data-tt-theme` / `data-tt-mode` attributes.
-   * Defaults to `document.documentElement`. Pass a container element for
-   * Storybook isolation or micro-frontend use cases.
+   * Defaults to `document.documentElement`. Pass a container for Storybook
+   * isolation or micro-frontend use cases.
    *
-   * Because the element is often `null` on the first render when passed via
-   * `ref.current`, `root` is reactive: the runtime is recreated once when
-   * it transitions from `undefined` to the actual element.
+   * **Must be paired with `themeId`.** Without a `themeId`, the generated CSS
+   * targets `:root` / `:root[data-tt-mode="dark"]` (the `<html>` element),
+   * while the attributes are written to this element — the alternate mode CSS
+   * would never match. A dev-mode warning fires on this combination.
+   *
+   * **Prefer passing the ref object itself** (`root={rootRef}`): refs are
+   * populated before layout effects, so the runtime attaches directly to the
+   * element. Passing `rootRef.current ?? undefined` also works, but the value
+   * is `null` on the first render, causing one transient attach to `<html>`
+   * before the runtime is recreated on the element.
    *
    * @example
    * ```tsx
    * // Storybook decorator — isolates each story from <html>
    * const rootRef = React.useRef<HTMLDivElement>(null);
    * <div ref={rootRef}>
-   *   <ThemeProvider theme={myTheme} root={rootRef.current ?? undefined}>
+   *   <ThemeProvider theme={myTheme} themeId="story" root={rootRef}>
    *     <Story />
    *   </ThemeProvider>
    * </div>
    * ```
    */
-  root?: HTMLElement;
+  root?: ThemeRootInput;
   children: React.ReactNode;
 }
 /**
@@ -170,11 +193,11 @@ declare const useColorMode: () => UseColorModeResult;
  * inline styles produces silently broken rendering:
  *
  * ```tsx
- * // ✗ WRONG — tokens.colors.brand.main is '{core.colors.brand.main}', not '#FF0000'
- * <div style={{ color: tokens.colors.brand.main }} />
+ * // ✗ WRONG — the leaf is '{core.colors.neutral.1000}' (a ref string), not a CSS color
+ * <div style={{ color: tokens.colors.action.primary.text.default }} />
  *
  * // ✓ CSS consumers — use vars:
- * <div style={{ color: 'var(--tt-color-brand-main)' }} />
+ * <div style={{ color: 'var(--tt-colors-action-primary-text-default)' }} />
  *
  * // ✓ Non-CSS consumers (React Native, canvas) — use useResolvedTokens():
  * const resolved = useResolvedTokens();
@@ -189,8 +212,8 @@ declare const useColorMode: () => UseColorModeResult;
  *
  * const Button = () => {
  *   const tokens = useTokens(); // introspection only
- *   // tokens.colors.action.primary.background.default → '{core.colors.brand.500}'
- *   return <button style={{ background: 'var(--tt-action-primary-background-default)' }} />;
+ *   // tokens.colors.action.primary.background.default → '{core.colors.neutral.1000}'
+ *   return <button style={{ background: 'var(--tt-colors-action-primary-background-default)' }} />;
  * };
  * ```
  */
@@ -210,13 +233,21 @@ declare const useTokens: () => SemanticTokens;
  *
  * ```tsx
  * // ✓ CSS (browser)
- * <div style={{ color: 'var(--tt-color-informational-primary-default)' }} />
+ * <div style={{ color: 'var(--tt-colors-informational-primary-text-default)' }} />
  *
  * // ✓ Non-CSS (React Native, canvas)
  * const resolved = useResolvedTokens();
  * <View style={{ backgroundColor: resolved['semantic.colors.action.primary.background.default'] }} />
  * ```
  *
+ * ### ⚠ CSS-coupled tokens stay unresolved
+ * A registered set of dimensional tokens (model.md §8 — spacing steps, fluid
+ * `text.*.fontSize`, `sizing.hit.*`, `sizing.viewport.*`, `sizing.measure.reading`,
+ * `spacing.gutter.*`) carry CSS-only constructs (`var()`, `calc()`, `clamp()`,
+ * `cqi`, `dvh`, `ch`). This hook returns those **as-is** — they are not usable
+ * outside a CSS engine. Colors, opacity, z-index, font weights/leading and
+ * other scalar tokens resolve to plain raw values and are safe everywhere.
+ *
  * Requires `<ThemeProvider theme={...}>`.
  *
  * @example
@@ -288,6 +319,13 @@ interface ThemeStylesProps {
   themeId?: string;
   /** CSP nonce for the inline style tag. */
   nonce?: string;
+  /**
+   * Emit the `@media (prefers-color-scheme)` fallback block (themeId-less
+   * bundles only). Default `true`. Set `false` when the app's `defaultMode`
+   * is a fixed `'light'`/`'dark'` rather than `'system'` — `<ThemeHead>`
+   * derives this automatically from its `defaultMode`.
+   */
+  systemModeFallback?: boolean;
 }
 /**
  * Renders an inline `<style>` tag with all CSS Custom Properties for a theme
@@ -301,6 +339,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
@@ -334,7 +376,8 @@ interface ThemeStylesProps {
 declare const ThemeStyles: ({
   theme,
   themeId,
-  nonce
+  nonce,
+  systemModeFallback
 }: ThemeStylesProps) => any;
 /**
  * Props for the `ThemeHead` component.

package/dist/react.cjs

@@ -1,8 +1,10 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+'use client';
+
 Object.defineProperty(exports, Symbol.toStringTag, {
   value: 'Module'
 });
-const require_react = require('./react-BKLEzIN8.cjs');
+const require_react = require('./react-DQErMGJz.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-BXqSYnmk.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-Drr-QSuX.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-D2J482kx.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-BwsjWKmo.mjs";
 export { type ResolvedMode, ThemeHead, ThemeHeadProps, type ThemeMode, ThemeProvider, ThemeProviderProps, ThemeScript, ThemeScriptProps, ThemeStyles, ThemeStylesProps, UseColorModeResult, useColorMode, useResolvedTokens, useTokens };

package/dist/react.mjs

@@ -1,11 +1,75 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { r as deepMerge, s as toFlatTokens } from "./helpers-Dz7NfNK6.mjs";
+'use client';
+
+import { r as deepMerge, s as toFlatTokens } from "./helpers-BXaKe2s3.mjs";
 import { getThemeStylesContent } from "./css.mjs";
-import { i as createThemeRuntime, t as getThemeScriptContent } from "./ssrScript-DfmopH-w.mjs";
+import { i as createThemeRuntime, t as getThemeScriptContent } from "./ssrScript-zDK1dqXr.mjs";
 import * as React from "react";
 import { Fragment, jsx, jsxs } from "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"}`;
+};
+/**
+* DEV-only registry of injected theme CSS per hoisted-style `href`.
+* React dedups hoisted `<style>` tags by `href`, so two providers with
+* *different* themes but the same `href` silently drop the second theme's
+* CSS. This registry detects that mismatch and warns.
+*/
+var injectedThemeCss = /* @__PURE__ */new Map();
+/**
+* Runs on the client before paint; falls back to `useEffect` on the server
+* so SSR renders never warn. Used for the runtime-creation effect so
+* `data-tt-*` attributes land before first paint in CSR apps (less mode flash).
+*/
+var useIsomorphicLayoutEffect = typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect;
+var resolveRootElement = root => {
+  if (!root) return void 0;
+  if (root instanceof HTMLElement) return root;
+  return root.current ?? void 0;
+};
+/**
+* The OS-preference CSS fallback only makes sense when the app follows the
+* OS. A fixed `'light'`/`'dark'` default must not let `prefers-color-scheme`
+* override it on first paint.
+*/
+var shouldEmitSystemFallback = defaultMode => {
+  return (defaultMode ?? "system") === "system";
+};
+/**
+* DEV-only: warn when two providers with different themes share the same
+* hoisted-style `href` — React dedups by href, so the second theme's CSS is
+* silently dropped. Distinct `themeId`s give distinct hrefs and coexist.
+*/
+var useDedupMismatchWarning = (cssContent, themeId) => {
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === "production" || !cssContent) return;
+    const href = themeStyleHref(themeId);
+    const entry = injectedThemeCss.get(href);
+    if (entry && entry.css !== cssContent) console.warn(`[fsl-theme] Two <ThemeProvider>s with different themes share the same style key "${href}". React dedups hoisted <style> tags by href, so only the first theme's CSS is injected. Give each theme a distinct themeId: <ThemeProvider theme={...} themeId="my-theme">.`);
+    const next = entry ?? {
+      css: cssContent,
+      count: 0
+    };
+    next.count += 1;
+    injectedThemeCss.set(href, next);
+    return () => {
+      const current = injectedThemeCss.get(href);
+      if (!current) return;
+      current.count -= 1;
+      if (current.count <= 0) injectedThemeCss.delete(href);
+    };
+  }, [cssContent, themeId]);
+};
 var COARSE_QUERY = "(any-pointer: coarse)";
 /**
 * Subscribe to coarse-pointer media query changes.
@@ -88,20 +152,26 @@ var ThemeProvider = ({
   children
 }) => {
   const runtimeRef = React.useRef(null);
-  const initDefaultMode = React.useRef(defaultMode);
-  const initStorageKey = React.useRef(storageKey);
+  const [initialDefaultMode] = React.useState(defaultMode);
+  const [initialStorageKey] = React.useState(storageKey);
   const [state, setState] = React.useState(() => {
     return {
       mode: defaultMode ?? "system",
       resolvedMode: (defaultMode ?? "system") === "system" ? "light" : defaultMode
     };
   });
-  React.useEffect(() => {
+  const [rootRetry, setRootRetry] = React.useState(0);
+  useIsomorphicLayoutEffect(() => {
+    if (root !== void 0 && !(root instanceof HTMLElement) && root.current === null && rootRetry === 0) {
+      setRootRetry(1);
+      return;
+    }
+    if (process.env.NODE_ENV !== "production" && root && !themeId) console.warn("[fsl-theme] `root` was passed without `themeId`. Without a themeId, the generated CSS targets `:root`/`:root[data-tt-mode=\"dark\"]` on <html>, but mode attributes are written to the `root` element — the alternate mode CSS will never match. Pass a `themeId` so CSS is scoped to `[data-tt-theme=\"<id>\"]` selectors that match the `root` element.");
     const runtime = createThemeRuntime({
       defaultTheme: themeId,
-      defaultMode: initDefaultMode.current,
-      storageKey: initStorageKey.current,
-      root
+      defaultMode: initialDefaultMode,
+      storageKey: initialStorageKey,
+      root: resolveRootElement(root)
     });
     runtimeRef.current = runtime;
     setState(runtime.getState());
@@ -111,7 +181,7 @@ var ThemeProvider = ({
       runtime.destroy();
       runtimeRef.current = null;
     };
-  }, [root, themeId]);
+  }, [root, themeId, rootRetry]);
   const setMode = React.useCallback(mode => {
     runtimeRef.current?.setMode(mode);
   }, []);
@@ -130,8 +200,11 @@ var ThemeProvider = ({
     return applyCoarseHitOverrides(result, theme.base, isCoarse);
   }, [theme, semanticTokens, isCoarse]);
   const cssContent = React.useMemo(() => {
-    return theme ? getThemeStylesContent(theme, themeId) : null;
+    return theme ? getThemeStylesContent(theme, themeId, {
+      systemModeFallback: shouldEmitSystemFallback(initialDefaultMode)
+    }) : null;
   }, [theme, themeId]);
+  useDedupMismatchWarning(cssContent, themeId);
   const onModeChangeRef = React.useRef(onModeChange);
   React.useEffect(() => {
     onModeChangeRef.current = onModeChange;
@@ -160,6 +233,7 @@ var ThemeProvider = ({
   });
   if (theme) return /* @__PURE__ */jsxs(Fragment, {
     children: [/* @__PURE__ */jsx("style", {
+      href: themeStyleHref(themeId),
       precedence: "default",
       children: cssContent
     }), /* @__PURE__ */jsx(ResolvedTokensCtx.Provider, {
@@ -191,11 +265,11 @@ var useColorMode = () => {
 * inline styles produces silently broken rendering:
 *
 * ```tsx
-* // ✗ WRONG — tokens.colors.brand.main is '{core.colors.brand.main}', not '#FF0000'
-* <div style={{ color: tokens.colors.brand.main }} />
+* // ✗ WRONG — the leaf is '{core.colors.neutral.1000}' (a ref string), not a CSS color
+* <div style={{ color: tokens.colors.action.primary.text.default }} />
 *
 * // ✓ CSS consumers — use vars:
-* <div style={{ color: 'var(--tt-color-brand-main)' }} />
+* <div style={{ color: 'var(--tt-colors-action-primary-text-default)' }} />
 *
 * // ✓ Non-CSS consumers (React Native, canvas) — use useResolvedTokens():
 * const resolved = useResolvedTokens();
@@ -210,8 +284,8 @@ var useColorMode = () => {
 *
 * const Button = () => {
 *   const tokens = useTokens(); // introspection only
-*   // tokens.colors.action.primary.background.default → '{core.colors.brand.500}'
-*   return <button style={{ background: 'var(--tt-action-primary-background-default)' }} />;
+*   // tokens.colors.action.primary.background.default → '{core.colors.neutral.1000}'
+*   return <button style={{ background: 'var(--tt-colors-action-primary-background-default)' }} />;
 * };
 * ```
 */
@@ -236,13 +310,21 @@ var useTokens = () => {
 *
 * ```tsx
 * // ✓ CSS (browser)
-* <div style={{ color: 'var(--tt-color-informational-primary-default)' }} />
+* <div style={{ color: 'var(--tt-colors-informational-primary-text-default)' }} />
 *
 * // ✓ Non-CSS (React Native, canvas)
 * const resolved = useResolvedTokens();
 * <View style={{ backgroundColor: resolved['semantic.colors.action.primary.background.default'] }} />
 * ```
 *
+* ### ⚠ CSS-coupled tokens stay unresolved
+* A registered set of dimensional tokens (model.md §8 — spacing steps, fluid
+* `text.*.fontSize`, `sizing.hit.*`, `sizing.viewport.*`, `sizing.measure.reading`,
+* `spacing.gutter.*`) carry CSS-only constructs (`var()`, `calc()`, `clamp()`,
+* `cqi`, `dvh`, `ch`). This hook returns those **as-is** — they are not usable
+* outside a CSS engine. Colors, opacity, z-index, font weights/leading and
+* other scalar tokens resolve to plain raw values and are safe everywhere.
+*
 * Requires `<ThemeProvider theme={...}>`.
 *
 * @example
@@ -316,6 +398,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
@@ -349,12 +435,15 @@ var ThemeScript = ({
 var ThemeStyles = ({
   theme,
   themeId,
-  nonce
+  nonce,
+  systemModeFallback
 }) => {
   return /* @__PURE__ */jsx("style", {
     nonce,
     dangerouslySetInnerHTML: {
-      __html: getThemeStylesContent(theme, themeId)
+      __html: getThemeStylesContent(theme, themeId, {
+        systemModeFallback
+      })
     }
   });
 };
@@ -417,7 +506,8 @@ var ThemeHead = ({
     }), /* @__PURE__ */jsx(ThemeStyles, {
       theme,
       themeId,
-      nonce
+      nonce,
+      systemModeFallback: shouldEmitSystemFallback(defaultMode)
     })]
   });
 };

package/dist/runtime-entry.cjs

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, {
   value: 'Module'
 });
-const require_ssrScript = require('./ssrScript-D3mYscp1.cjs');
+const require_ssrScript = require('./ssrScript-D73WcrCM.cjs');
 exports.DATA_MODE_ATTR = require_ssrScript.DATA_MODE_ATTR;
 exports.DATA_THEME_ATTR = require_ssrScript.DATA_THEME_ATTR;
 exports.createThemeRuntime = require_ssrScript.createThemeRuntime;

package/dist/runtime-entry.mjs

@@ -1,3 +1,3 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { i as createThemeRuntime, n as DATA_MODE_ATTR, r as DATA_THEME_ATTR, t as getThemeScriptContent } from "./ssrScript-DfmopH-w.mjs";
+import { i as createThemeRuntime, n as DATA_MODE_ATTR, r as DATA_THEME_ATTR, t as getThemeScriptContent } from "./ssrScript-zDK1dqXr.mjs";
 export { DATA_MODE_ATTR, DATA_THEME_ATTR, createThemeRuntime, getThemeScriptContent };