@kushagradhawan/kookie-ui 0.3.21 → 0.3.23

package/src/components/shell.tsx

@@ -36,6 +36,7 @@ import { omitPaneProps, extractPaneDomProps, mapResponsiveBooleanToPaneMode } fr
 import { Sidebar } from './_internal/shell-sidebar.js';
 import { Bottom } from './_internal/shell-bottom.js';
 import { Inspector } from './_internal/shell-inspector.js';
+import { _BREAKPOINTS } from './shell.types.js';
 import type { PresentationValue, ResponsivePresentation, PaneMode, SidebarMode, PaneSizePersistence, Breakpoint, PaneTarget, Responsive, PaneBaseProps, CSSPropertiesWithVars } from './shell.types.js';
 import { normalizeToPx } from '../helpers/normalize-to-px.js';
 import { useBreakpoint } from '../hooks/use-breakpoint.js';
@@ -222,114 +223,143 @@ interface ShellRootProps extends React.ComponentPropsWithoutRef<'div'> {
   height?: 'full' | 'auto' | string | number;
 }
 
-const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, children, height = 'full', ...props }, ref) => {
-  const { breakpoint: currentBreakpoint, ready: currentBreakpointReady } = useBreakpoint();
-
-  // Store hasPanelDefaultOpen for use in passthrough props (computed once during lazy init)
-  const hasPanelDefaultOpenRef = React.useRef<boolean>(false);
+/**
+ * Read the pane modes a set of Shell children asks for.
+ *
+ * Runs once at mount, for the reducer's initial state, and again whenever a
+ * pane family enters after mount. Pure - it only reads the children's props.
+ */
+/**
+ * Pick the entry of a responsive map that applies at `breakpoint`, falling
+ * back down the scale the way useResponsiveValue does. With no breakpoint it
+ * takes `initial`, which is what the mount path has always done.
+ */
+function pickResponsive<T>(map: Partial<Record<Breakpoint, T>>, breakpoint?: Breakpoint): T | undefined {
+  if (breakpoint === undefined) return (map.initial ?? Object.values(map)[0]) as T | undefined;
+  if (map[breakpoint] !== undefined) return map[breakpoint];
+
+  const bpKeys = Object.keys(_BREAKPOINTS) as Array<keyof typeof _BREAKPOINTS>;
+  const order: Breakpoint[] = ([...bpKeys].reverse() as Breakpoint[]).concat('initial' as Breakpoint);
+  for (let i = order.indexOf(breakpoint) + 1; i < order.length; i++) {
+    if (map[order[i]] !== undefined) return map[order[i]];
+  }
+  return undefined;
+}
 
-  // Pane state management via reducer with lazy initialization
-  // This computation only runs once on mount, not on every render
-  const [paneState, dispatchPane] = React.useReducer(paneReducer, children, (initialChildren) => {
-    const childArray = React.Children.toArray(initialChildren) as React.ReactElement[];
+function readPaneStateFromChildren(initialChildren: React.ReactNode, breakpoint?: Breakpoint): PaneState & { hasPanelDefaultOpen: boolean } {
+  const childArray = React.Children.toArray(initialChildren) as React.ReactElement[];
 
-    // Compute initial defaults from immediate children (one-time, uncontrolled defaults)
-    const hasPanelDefaultOpen = childArray.some(
-      (el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Panel' && Boolean((el as any).props?.defaultOpen),
-    );
-    // Store for use in passthrough props
-    hasPanelDefaultOpenRef.current = hasPanelDefaultOpen;
+  // Compute initial defaults from immediate children (one-time, uncontrolled defaults)
+  const hasPanelDefaultOpen = childArray.some(
+    (el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Panel' && Boolean((el as any).props?.defaultOpen),
+  );
 
-    // Rail defaults to open (true) unless explicitly set to false
-    // Supports responsive objects: { initial: false, md: true }
-    const railEl = childArray.find((el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Rail');
-    const railDefaultOpen = railEl ? (railEl as any).props?.defaultOpen : undefined;
-    const hasRailDefaultOpen = (() => {
-      if (!railEl) return false;
-      if (railDefaultOpen === undefined) return true; // Default to open
-      if (typeof railDefaultOpen === 'boolean') return railDefaultOpen;
-      // Responsive object - use 'initial' value, or first defined value, or default true
-      if (typeof railDefaultOpen === 'object') {
-        return railDefaultOpen.initial ?? Object.values(railDefaultOpen)[0] ?? true;
-      }
-      return true;
-    })();
+  // Rail defaults to open (true) unless explicitly set to false
+  // Supports responsive objects: { initial: false, md: true }
+  const railEl = childArray.find((el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Rail');
+  const railDefaultOpen = railEl ? (railEl as any).props?.defaultOpen : undefined;
+  const hasRailDefaultOpen = (() => {
+    if (!railEl) return false;
+    if (railDefaultOpen === undefined) return true; // Default to open
+    if (typeof railDefaultOpen === 'boolean') return railDefaultOpen;
+    // Responsive object - use 'initial' value, or first defined value, or default true
+    if (typeof railDefaultOpen === 'object') {
+      return railDefaultOpen.initial ?? Object.values(railDefaultOpen)[0] ?? true;
+    }
+    return true;
+  })();
 
-    const hasInspectorDefaultOpen = childArray.some(
-      (el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Inspector' && Boolean((el as any).props?.defaultOpen),
-    );
-    const hasInspectorOpenControlled = childArray.some(
-      (el) =>
-        React.isValidElement(el) &&
-        (el as any).type?.displayName === 'Shell.Inspector' &&
-        typeof (el as any).props?.open !== 'undefined' &&
-        Boolean((el as any).props?.open),
-    );
+  const hasInspectorDefaultOpen = childArray.some(
+    (el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Inspector' && Boolean((el as any).props?.defaultOpen),
+  );
+  const hasInspectorOpenControlled = childArray.some(
+    (el) =>
+      React.isValidElement(el) &&
+      (el as any).type?.displayName === 'Shell.Inspector' &&
+      typeof (el as any).props?.open !== 'undefined' &&
+      Boolean((el as any).props?.open),
+  );
 
-    // Detect Panel controlled open state for initial reducer state
-    const hasPanelOpenControlled = childArray.some((el) => {
-      if (!React.isValidElement(el) || (el as any).type?.displayName !== 'Shell.Panel') return false;
-      const openProp = (el as any).props?.open;
-      if (typeof openProp === 'undefined') return false;
-      if (typeof openProp === 'boolean') return openProp;
-      // Responsive object - check 'initial' or first truthy value
-      if (typeof openProp === 'object' && openProp !== null) {
-        return openProp.initial ?? Object.values(openProp)[0] ?? false;
-      }
-      return false;
-    });
+  // Detect Panel controlled open state for initial reducer state
+  const hasPanelOpenControlled = childArray.some((el) => {
+    if (!React.isValidElement(el) || (el as any).type?.displayName !== 'Shell.Panel') return false;
+    const openProp = (el as any).props?.open;
+    if (typeof openProp === 'undefined') return false;
+    if (typeof openProp === 'boolean') return openProp;
+    // Responsive object - check 'initial' or first truthy value
+    if (typeof openProp === 'object' && openProp !== null) {
+      return openProp.initial ?? Object.values(openProp)[0] ?? false;
+    }
+    return false;
+  });
 
-    // Detect Sidebar initial state from props
-    const getSidebarInitialState = (): SidebarMode => {
-      const sidebarEl = childArray.find((el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Sidebar');
-      if (!sidebarEl) return 'expanded';
-      const sidebarProps = (sidebarEl as any).props;
-      // Check controlled state first
-      if (typeof sidebarProps?.state !== 'undefined') {
-        if (typeof sidebarProps.state === 'string') return sidebarProps.state as SidebarMode;
-        // Responsive object - use 'initial' breakpoint or first defined value
-        if (typeof sidebarProps.state === 'object') {
-          return (sidebarProps.state.initial ?? Object.values(sidebarProps.state)[0] ?? 'expanded') as SidebarMode;
-        }
+  // Detect Sidebar initial state from props
+  const getSidebarInitialState = (): SidebarMode => {
+    const sidebarEl = childArray.find((el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Sidebar');
+    if (!sidebarEl) return 'expanded';
+    const sidebarProps = (sidebarEl as any).props;
+    // Check controlled state first
+    if (typeof sidebarProps?.state !== 'undefined') {
+      if (typeof sidebarProps.state === 'string') return sidebarProps.state as SidebarMode;
+      // Responsive object - use 'initial' breakpoint or first defined value
+      if (typeof sidebarProps.state === 'object') {
+        return (pickResponsive<SidebarMode>(sidebarProps.state, breakpoint) ?? 'expanded') as SidebarMode;
       }
-      // Check defaultState
-      if (typeof sidebarProps?.defaultState !== 'undefined') {
-        if (typeof sidebarProps.defaultState === 'string') return sidebarProps.defaultState as SidebarMode;
-        if (typeof sidebarProps.defaultState === 'object') {
-          return (sidebarProps.defaultState.initial ?? Object.values(sidebarProps.defaultState)[0] ?? 'expanded') as SidebarMode;
-        }
+    }
+    // Check defaultState
+    if (typeof sidebarProps?.defaultState !== 'undefined') {
+      if (typeof sidebarProps.defaultState === 'string') return sidebarProps.defaultState as SidebarMode;
+      if (typeof sidebarProps.defaultState === 'object') {
+        return (pickResponsive<SidebarMode>(sidebarProps.defaultState, breakpoint) ?? 'expanded') as SidebarMode;
       }
-      return 'expanded';
-    };
+    }
+    return 'expanded';
+  };
 
-    // Detect Bottom initial state from props
-    const getBottomInitialState = (): PaneMode => {
-      const bottomEl = childArray.find((el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Bottom');
-      if (!bottomEl) return 'collapsed';
-      const bottomProps = (bottomEl as any).props;
-      // Check controlled open first
-      if (typeof bottomProps?.open !== 'undefined') {
-        if (typeof bottomProps.open === 'boolean') return bottomProps.open ? 'expanded' : 'collapsed';
-        // Responsive object - use 'initial' breakpoint or first defined value
-        if (typeof bottomProps.open === 'object') {
-          const val = bottomProps.open.initial ?? Object.values(bottomProps.open)[0];
-          return val ? 'expanded' : 'collapsed';
-        }
+  // Detect Bottom initial state from props
+  const getBottomInitialState = (): PaneMode => {
+    const bottomEl = childArray.find((el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Bottom');
+    if (!bottomEl) return 'collapsed';
+    const bottomProps = (bottomEl as any).props;
+    // Check controlled open first
+    if (typeof bottomProps?.open !== 'undefined') {
+      if (typeof bottomProps.open === 'boolean') return bottomProps.open ? 'expanded' : 'collapsed';
+      // Responsive object - use 'initial' breakpoint or first defined value
+      if (typeof bottomProps.open === 'object') {
+        const val = bottomProps.open.initial ?? Object.values(bottomProps.open)[0];
+        return val ? 'expanded' : 'collapsed';
       }
-      // Check defaultOpen
-      if (typeof bottomProps?.defaultOpen !== 'undefined') {
-        return bottomProps.defaultOpen ? 'expanded' : 'collapsed';
-      }
-      return 'collapsed';
-    };
+    }
+    // Check defaultOpen
+    if (typeof bottomProps?.defaultOpen !== 'undefined') {
+      return bottomProps.defaultOpen ? 'expanded' : 'collapsed';
+    }
+    return 'collapsed';
+  };
 
-    return {
-      leftMode: hasPanelDefaultOpen || hasPanelOpenControlled || hasRailDefaultOpen ? 'expanded' : ('collapsed' as PaneMode),
-      panelMode: hasPanelDefaultOpen || hasPanelOpenControlled ? 'expanded' : ('collapsed' as PaneMode),
-      sidebarMode: getSidebarInitialState(),
-      inspectorMode: hasInspectorDefaultOpen || hasInspectorOpenControlled ? 'expanded' : ('collapsed' as PaneMode),
-      bottomMode: getBottomInitialState(),
-    };
+  return {
+    hasPanelDefaultOpen,
+    leftMode: hasPanelDefaultOpen || hasPanelOpenControlled || hasRailDefaultOpen ? 'expanded' : ('collapsed' as PaneMode),
+    panelMode: hasPanelDefaultOpen || hasPanelOpenControlled ? 'expanded' : ('collapsed' as PaneMode),
+    sidebarMode: getSidebarInitialState(),
+    inspectorMode: hasInspectorDefaultOpen || hasInspectorOpenControlled ? 'expanded' : ('collapsed' as PaneMode),
+    bottomMode: getBottomInitialState(),
+  };
+}
+
+const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, children, height = 'full', ...props }, ref) => {
+  const { breakpoint: currentBreakpoint, ready: currentBreakpointReady } = useBreakpoint();
+
+  // Store hasPanelDefaultOpen for use in passthrough props (computed once during lazy init)
+  const hasPanelDefaultOpenRef = React.useRef<boolean>(false);
+
+  // Pane state management via reducer with lazy initialization
+  // This computation only runs once on mount, not on every render
+  const [paneState, dispatchPane] = React.useReducer(paneReducer, children, (initialChildren) => {
+    const { hasPanelDefaultOpen, ...modes } = readPaneStateFromChildren(initialChildren);
+    // Store for use in passthrough props
+    hasPanelDefaultOpenRef.current = hasPanelDefaultOpen;
+    return modes;
   });
   const setLeftMode = React.useCallback((mode: PaneMode) => dispatchPane({ type: 'SET_LEFT_MODE', mode }), []);
   const setPanelMode = React.useCallback((mode: PaneMode) => dispatchPane({ type: 'SET_PANEL_MODE', mode }), []);
@@ -381,6 +411,47 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
     return childArray.some((el) => isShellComponentType(el, Sidebar));
   }, [children]);
 
+  // Re-read the defaults when a pane family enters after mount.
+  //
+  // The initial modes are computed once, from the children present at mount.
+  // That is right until an app swaps families at runtime - a Sidebar giving
+  // way to Rail+Panel on one route, and back on the next. The entering pane
+  // then renders against the mode left behind by the family that just went:
+  // a Rail mounting 'collapsed', at width 0, with its content faded out, put
+  // right one layout effect later. The reader sees a flicker in place where
+  // the pane should have been there already.
+  //
+  // Adjusting state during render keeps this out of the paint: React re-runs
+  // Root before the children render, so the entering pane never sees the
+  // mode of the family it replaced. The ref guard is what makes the update
+  // terminate - it fires only on the edge, never on a steady render.
+  const enteredFamilyRef = React.useRef({ left: hasLeftChildren, sidebar: hasSidebarChildren });
+  if (enteredFamilyRef.current.left !== hasLeftChildren || enteredFamilyRef.current.sidebar !== hasSidebarChildren) {
+    const leftEntered = hasLeftChildren && !enteredFamilyRef.current.left;
+    const sidebarEntered = hasSidebarChildren && !enteredFamilyRef.current.sidebar;
+    enteredFamilyRef.current = { left: hasLeftChildren, sidebar: hasSidebarChildren };
+
+    if (leftEntered || sidebarEntered) {
+      // The live breakpoint, not the mount default: a responsive
+      // defaultState like { initial: 'collapsed', md: 'expanded' } must be
+      // read for the width the reader is on. Taking `initial` would send a
+      // desktop sidebar in collapsed and let its own start-up effect open it
+      // again after the paint, which is the blink this whole block exists to
+      // remove.
+      const { hasPanelDefaultOpen, ...modes } = readPaneStateFromChildren(children, currentBreakpoint as Breakpoint);
+      if (leftEntered) {
+        hasPanelDefaultOpenRef.current = hasPanelDefaultOpen;
+        // Only when the mode actually differs, so a family that enters
+        // already in the right mode dispatches nothing.
+        if (modes.leftMode !== paneState.leftMode) dispatchPane({ type: 'SET_LEFT_MODE', mode: modes.leftMode });
+        if (modes.panelMode !== paneState.panelMode) dispatchPane({ type: 'SET_PANEL_MODE', mode: modes.panelMode });
+      }
+      if (sidebarEntered && modes.sidebarMode !== paneState.sidebarMode) {
+        dispatchPane({ type: 'SET_SIDEBAR_MODE', mode: modes.sidebarMode });
+      }
+    }
+  }
+
   // Keep a ref to sidebar mode so togglePane doesn't depend on it,
   // preventing ActionsContext churn on every sidebar mode change
   const sidebarModeRef = React.useRef(paneState.sidebarMode);

package/src/components/slider.css

@@ -20,7 +20,7 @@
    */
   :where([data-panel-background='translucent'], [data-material='translucent']) & {
     backdrop-filter: var(--backdrop-filter-components);
-    --backdrop-filter-components: blur(var(--backdrop-blur-components));
+    --backdrop-filter-components: var(--backdrop-filter-components-enabled);
   }
 
   /* Prevent backdrop-filter stacking with parent elements */
@@ -37,7 +37,7 @@
   
   &:where([data-panel-background='translucent'], [data-material='translucent']) {
     backdrop-filter: var(--backdrop-filter-components);
-    --backdrop-filter-components: blur(var(--backdrop-blur-components));
+    --backdrop-filter-components: var(--backdrop-filter-components-enabled);
   }
 
   &:where([data-orientation='horizontal']) {

package/src/components/switch.css

@@ -20,7 +20,7 @@
    */
   :where([data-panel-background='translucent'], [data-material='translucent']) & {
     backdrop-filter: var(--backdrop-filter-components);
-    --backdrop-filter-components: blur(var(--backdrop-blur-components));
+    --backdrop-filter-components: var(--backdrop-filter-components-enabled);
   }
 
   /* Prevent backdrop-filter stacking with parent elements */
@@ -37,7 +37,7 @@
   
   &:where([data-panel-background='translucent'], [data-material='translucent']) {
     backdrop-filter: var(--backdrop-filter-components);
-    --backdrop-filter-components: blur(var(--backdrop-blur-components));
+    --backdrop-filter-components: var(--backdrop-filter-components-enabled);
   }
 
   &::before {

package/src/components/table.css

@@ -121,6 +121,13 @@
 /* surface */
 
 .rt-TableRoot:where(.rt-variant-surface) {
+  /*
+   * This surface blurs its own backdrop, which makes it the backdrop root for
+   * everything inside it. A component nested here would re-blur an already
+   * blurred, already flat surface for the full cost of another blur pass, so
+   * switch the component filter off for the subtree. See tokens/blur.css.
+   */
+  --backdrop-filter-components-enabled: none;
   box-sizing: border-box;
   border: 1px solid var(--gray-a5);
   border-radius: var(--table-border-radius);

package/src/components/text-area.css

@@ -47,7 +47,7 @@
   /* Theme-level translucent override */
   :where([data-panel-background='translucent'], [data-material='translucent']) & {
     backdrop-filter: var(--backdrop-filter-components);
-    --backdrop-filter-components: blur(var(--backdrop-blur-components));
+    --backdrop-filter-components: var(--backdrop-filter-components-enabled);
   }
 
   /* Prevent backdrop-filter stacking with parents */
@@ -61,7 +61,7 @@
   
   &:where([data-panel-background='translucent'], [data-material='translucent']) {
     backdrop-filter: var(--backdrop-filter-components);
-    --backdrop-filter-components: blur(var(--backdrop-blur-components));
+    --backdrop-filter-components: var(--backdrop-filter-components-enabled);
   }
 
   &:where(:focus-within) {

package/src/components/text-field.css

@@ -12,7 +12,7 @@
     /* Theme-level translucent override */
     :where([data-panel-background='translucent'], [data-material='translucent']) & {
       backdrop-filter: var(--backdrop-filter-components);
-      --backdrop-filter-components: blur(var(--backdrop-blur-components));
+      --backdrop-filter-components: var(--backdrop-filter-components-enabled);
     }
 
   /* Prevent backdrop-filter stacking with parents */
@@ -26,7 +26,7 @@
   
   &:where([data-panel-background='translucent'], [data-material='translucent']) {
     backdrop-filter: var(--backdrop-filter-components);
-    --backdrop-filter-components: blur(var(--backdrop-blur-components));
+    --backdrop-filter-components: var(--backdrop-filter-components-enabled);
   }
 
   @supports selector(:has(*)) {

package/src/components/theme.tsx

@@ -3,8 +3,11 @@
 import * as React from 'react';
 import classNames from 'classnames';
 import { Direction, Slot, Tooltip as TooltipPrimitive } from 'radix-ui';
+import { useComposedRefs, useLayoutEffect } from 'radix-ui/internal';
 
 import { getMatchingGrayColor } from '../helpers/get-matching-gray-color.js';
+import { usePropSyncedState } from '../hooks/use-prop-synced-state.js';
+import { useDeprecatedPanelBackgroundWarning } from '../helpers/use-deprecation-warning.js';
 import { themePropDefs } from './theme.props.js';
 
 import type { ThemeOwnProps } from './theme.props.js';
@@ -104,42 +107,27 @@ const ThemeRoot = React.forwardRef<ThemeImplElement, ThemeImplPublicProps>(
       ...rootProps
     } = props;
 
-    // Show deprecation warning for panelBackground when used
-    React.useEffect(() => {
-      if (props.panelBackground !== undefined) {
-        console.warn(
-          'Warning: The `panelBackground` prop is deprecated and will be removed in a future version. Use `material` prop instead.',
-        );
-      }
-    }, [props.panelBackground]);
+    useDeprecatedPanelBackgroundWarning(props.panelBackground);
 
-    const [appearance, setAppearance] = React.useState(appearanceProp);
-    React.useEffect(() => setAppearance(appearanceProp), [appearanceProp]);
-
-    const [accentColor, setAccentColor] = React.useState(accentColorProp);
-    React.useEffect(() => setAccentColor(accentColorProp), [accentColorProp]);
-
-    const [grayColor, setGrayColor] = React.useState(grayColorProp);
-    React.useEffect(() => setGrayColor(grayColorProp), [grayColorProp]);
+    // Each of these follows its prop but stays independently settable, so
+    // `ThemePanel` can change the theme at runtime. Syncing during render
+    // rather than in an effect matters here: an effect would commit the old
+    // theme first and re-render every consumer of the context a second time.
+    const [appearance, setAppearance] = usePropSyncedState(appearanceProp);
+    const [accentColor, setAccentColor] = usePropSyncedState(accentColorProp);
+    const [grayColor, setGrayColor] = usePropSyncedState(grayColorProp);
 
     // Material takes precedence over panelBackground
     const effectiveMaterial =
       materialProp !== themePropDefs.material.default ? materialProp : panelBackgroundProp;
-    const [material, setMaterial] = React.useState(effectiveMaterial);
-    React.useEffect(() => setMaterial(effectiveMaterial), [effectiveMaterial]);
+    const [material, setMaterial] = usePropSyncedState(effectiveMaterial);
 
     // Keep panelBackground in sync with material for backward compatibility
-    const [panelBackground, setPanelBackground] = React.useState(panelBackgroundProp);
-    React.useEffect(() => setPanelBackground(material), [material]);
-
-    const [radius, setRadius] = React.useState(radiusProp);
-    React.useEffect(() => setRadius(radiusProp), [radiusProp]);
-
-    const [scaling, setScaling] = React.useState(scalingProp);
-    React.useEffect(() => setScaling(scalingProp), [scalingProp]);
+    const [panelBackground, setPanelBackground] = usePropSyncedState(material);
 
-    const [fontFamily, setFontFamily] = React.useState(fontFamilyProp);
-    React.useEffect(() => setFontFamily(fontFamilyProp), [fontFamilyProp]);
+    const [radius, setRadius] = usePropSyncedState(radiusProp);
+    const [scaling, setScaling] = usePropSyncedState(scalingProp);
+    const [fontFamily, setFontFamily] = usePropSyncedState(fontFamilyProp);
 
     return (
       <ThemeImpl
@@ -223,10 +211,24 @@ const ThemeImpl = React.forwardRef<ThemeImplElement, ThemeImplProps>((props, for
   const hasBackground =
     hasBackgroundProp === undefined ? isRoot || isExplicitAppearance : hasBackgroundProp;
 
-  const [clientOS, setClientOS] = React.useState<ReturnType<typeof getClientOS>>(undefined);
-  React.useEffect(() => {
-    if (isRoot) setClientOS(getClientOS());
-  }, [isRoot]);
+  // `data-os` can only be resolved on the client. Writing it straight to the
+  // DOM keeps it out of the server markup — so hydration still matches — without
+  // spending a render pass, and a state update here would re-render the whole
+  // application on mount.
+  const rootRef = React.useRef<ThemeImplElement>(null);
+  const composedRef = useComposedRefs(forwardedRef, rootRef);
+  const hasExplicitOS = 'data-os' in themeProps;
+
+  useLayoutEffect(() => {
+    if (!isRoot || hasExplicitOS) return;
+    const node = rootRef.current;
+    if (!node) return;
+
+    const os = getClientOS();
+    if (!os) return;
+    node.setAttribute('data-os', os);
+    return () => node.removeAttribute('data-os');
+  }, [isRoot, hasExplicitOS]);
 
   return (
     <ThemeContext.Provider
@@ -284,8 +286,7 @@ const ThemeImpl = React.forwardRef<ThemeImplElement, ThemeImplProps>((props, for
         data-radius={radius}
         data-scaling={scaling}
         data-font-family={fontFamily}
-        data-os={isRoot ? clientOS : undefined}
-        ref={forwardedRef}
+        ref={composedRef}
         {...themeProps}
         className={classNames(
           'radix-themes',

package/src/helpers/compile-prop-defs.ts

@@ -0,0 +1,121 @@
+import type { PropDef } from '../props/prop-def.js';
+
+/**
+ * A prop def pre-processed into the exact shape `extractProps` needs at render
+ * time. Everything that can be derived from the static prop def — enum
+ * membership sets, whether the def is responsive, whether it carries a default
+ * — is computed once here instead of on every render.
+ */
+interface CompiledPropDef {
+  key: string;
+  type: PropDef['type'];
+  default: unknown;
+  hasDefault: boolean;
+  responsive: boolean;
+  className?: string;
+  customProperties?: `--${string}`[];
+  parseValue?: (value: string) => string | undefined;
+  /** The prop def's own enum values, kept for the responsive class name helpers. */
+  values: readonly string[];
+  /** O(1) membership for `values`. */
+  valueSet: ReadonlySet<string>;
+  /**
+   * `values` plus the default, used to coerce invalid enum values back to the
+   * default. Only present for `type: 'enum'` — `'enum | string'` props accept
+   * arbitrary strings and must not be coerced.
+   */
+  enumValueSet?: ReadonlySet<unknown>;
+}
+
+interface CompiledPropDefs {
+  /** Defs that contribute a class name and/or custom properties. */
+  styling: CompiledPropDef[];
+  /**
+   * Defs that pass through to the element but still need a default applied or
+   * an invalid enum value coerced. Defs that can do neither are omitted
+   * entirely — they are already correct as passed.
+   */
+  passthrough: CompiledPropDef[];
+  /** Keys consumed by `styling`, so they can be skipped when copying props. */
+  stylingKeys: ReadonlySet<string>;
+}
+
+const EMPTY_VALUES: readonly string[] = [];
+const EMPTY_SET: ReadonlySet<string> = new Set();
+
+function compile(propDefs: readonly Record<string, PropDef>[]): CompiledPropDefs {
+  const merged: Record<string, PropDef> = Object.assign({}, ...propDefs);
+  const styling: CompiledPropDef[] = [];
+  const passthrough: CompiledPropDef[] = [];
+  const stylingKeys = new Set<string>();
+
+  for (const key in merged) {
+    // The PropDef union is narrowed per-field below; reading the optional
+    // members off the union directly is what the runtime actually needs.
+    const def = merged[key] as PropDef & {
+      default?: unknown;
+      values?: readonly string[];
+      className?: string;
+      customProperties?: `--${string}`[];
+      parseValue?: (value: string) => string | undefined;
+      responsive?: true;
+    };
+
+    const values = def.values ?? EMPTY_VALUES;
+    const compiled: CompiledPropDef = {
+      key,
+      type: def.type,
+      default: def.default,
+      hasDefault: def.default !== undefined,
+      responsive: 'responsive' in def,
+      className: def.className,
+      customProperties: def.customProperties,
+      parseValue: def.parseValue,
+      values,
+      valueSet: values.length > 0 ? new Set(values) : EMPTY_SET,
+      enumValueSet: def.type === 'enum' ? new Set<unknown>([def.default, ...values]) : undefined,
+    };
+
+    if (def.className) {
+      styling.push(compiled);
+      stylingKeys.add(key);
+    } else if (compiled.hasDefault || def.type === 'enum') {
+      // Anything else is copied through untouched, so there is nothing to do.
+      passthrough.push(compiled);
+    }
+  }
+
+  return { styling, passthrough, stylingKeys };
+}
+
+interface CacheNode {
+  children: WeakMap<object, CacheNode>;
+  compiled?: CompiledPropDefs;
+}
+
+const cacheRoot: CacheNode = { children: new WeakMap() };
+
+/**
+ * Compiles a set of prop defs, memoized on the identity of the prop def objects
+ * themselves. Components always pass the same module-level constants, so after
+ * the first render of a given component this is a couple of WeakMap lookups
+ * instead of merging 50-odd prop defs into a fresh object.
+ */
+function getCompiledPropDefs(propDefs: readonly Record<string, PropDef>[]): CompiledPropDefs {
+  let node = cacheRoot;
+
+  for (let i = 0; i < propDefs.length; i++) {
+    const propDef = propDefs[i];
+    let child = node.children.get(propDef);
+    if (child === undefined) {
+      child = { children: new WeakMap() };
+      node.children.set(propDef, child);
+    }
+    node = child;
+  }
+
+  return (node.compiled ??= compile(propDefs));
+}
+
+export { getCompiledPropDefs };
+export type { CompiledPropDef, CompiledPropDefs };