@tamagui/web 2.7.7 → 3.0.0-beta.1093.1

package/src/hooks/useThemeState.ts

@@ -8,6 +8,7 @@ import {
   useRef,
   type MutableRefObject,
 } from 'react'
+import { getThemeScheme as getScheme } from '@tamagui/helpers'
 import { getConfig, getSetting } from '../config'
 import { MISSING_THEME_MESSAGE } from '../constants/constants'
 import type {
@@ -16,6 +17,7 @@ import type {
   ThemeState,
   UseThemeWithStateProps,
 } from '../types'
+import type { ThemeUpdateState } from '../helpers/themeUpdateState'
 
 type ID = string
 
@@ -27,7 +29,6 @@ const HasRenderedOnce = new WeakMap<object, boolean>()
 const HadTheme = new WeakMap<object, boolean>()
 const PendingUpdate = new Map<any, boolean | 'force'>()
 
-// TODO this will gain memory over time but its not going to be a ton
 const states: Map<ID, ThemeState | undefined> = new Map()
 const localStates: Map<ID, ThemeState | undefined> = new Map()
 
@@ -41,9 +42,31 @@ export const forceUpdateThemes = () => {
 
 export const getThemeState = (id: ID) => states.get(id)
 
-let cacheVersion = 0
+const themeUpdateLayers = new Map<ID, ThemeUpdateState>()
+const themeProviderParents = new Map<ID, ID>()
+
+export const getThemeUpdateLayer = (id: ID) => themeUpdateLayers.get(id)
+export const getThemeProviderParent = (id: ID) => themeProviderParents.get(id)
+
+export const getThemeProviderChainSizes = () => ({
+  layers: themeUpdateLayers.size,
+  parents: themeProviderParents.size,
+})
+
+const registerThemeProviderChain = (
+  id: ID,
+  parentId: ID,
+  props: UseThemeWithStateProps
+) => {
+  themeProviderParents.set(id, parentId)
+  if (props._themeUpdate) {
+    themeUpdateLayers.set(id, props._themeUpdate)
+  } else {
+    themeUpdateLayers.delete(id)
+  }
+}
 
-// cache for getNewThemeName - invalidated on cacheVersion change
+let cacheVersion = 0
 const themeNameCache = new Map<string, string | null>()
 let themeNameCacheVer = -1
 
@@ -52,11 +75,8 @@ let themes: Record<string, ThemeParsed> | null = null
 let rootThemeState: ThemeState | null = null
 export const getRootThemeState = () => rootThemeState
 
-// extracts base name without scheme: "light_red_surface1" -> "red_surface1"
 const getThemeBaseName = (name: string) => name.replace(/^(light|dark)_/, '')
 
-// useReducer-based force-update; cheaper than useSyncExternalStore's internal
-// useState+useLayoutEffect+useEffect+useDebugValue chain on Hermes.
 const incReducer = (c: number): number => c + 1
 
 export const useThemeState = (
@@ -64,13 +84,8 @@ export const useThemeState = (
   isRoot = false,
   keys: MutableRefObject<Set<string> | null>,
   schemeKeys?: MutableRefObject<Set<string> | null>,
-  // when true, install the propsKey-watching useIsomorphicLayoutEffect that
-  // schedules descendant updates via listenersByParent[id]. Only <Theme>
-  // providers actually push their themeState.id into ThemeStateContext, so
-  // only they can have descendants subscribed under their id. Leaf styled
-  // components pass false (the default) and save one hook slot per mount.
-  // Stable per call-site (rule of hooks satisfied).
-  cascadeOnChange = false
+  cascadeOnChange = false,
+  optimizeForFirstRender = false
 ): ThemeState => {
   'use no memo'
 
@@ -80,9 +95,7 @@ export const useThemeState = (
   if (!parentId && !isRoot) {
     throw new Error(
       process.env.NODE_ENV === 'development'
-        ? `${MISSING_THEME_MESSAGE}
-
-Looked for theme${props.name ? ` "${props.name}"` : ''}${props.componentName ? ` (component: ${props.componentName})` : ''}, but no parent theme context was found (parentId: ${parentId}).`
+        ? `${MISSING_THEME_MESSAGE}\n\nLooked for theme${props.name ? ` "${props.name}"` : ''}, but no parent theme context was found (parentId: ${parentId}).`
         : MISSING_THEME_MESSAGE
     )
   }
@@ -93,72 +106,53 @@ Looked for theme${props.name ? ` "${props.name}"` : ''}${props.componentName ? `
         id: '',
         name: 'light',
         theme: getConfig().themes.light,
-        // inverses: 0,
       }
     )
   }
 
-  // useId keeps theme-provider ids tied to the React tree. A process-wide
-  // counter can let children observe a provider context id whose matching
-  // states Map entry was never populated in multi-root/native surfaces.
   const id = useId()
   const propsKey = getPropsKey(props)
 
-  // stable ref-bag for render inputs and the optional subscription cleanup.
-  // lastSnap caches the last getSnapshot result for the subscription bailout.
-  const ref = useRef<ThemeStateRef>(null as any)
-  if (!ref.current) {
-    ref.current = {
-      id,
-      parentId,
-      props,
-      propsKey,
-      isRoot,
-      keys,
-      schemeKeys,
-      renderVersion: 0,
-    }
-  } else {
-    // refresh latest values for the stable closures to read
-    ref.current.props = props
-    ref.current.propsKey = propsKey
-    ref.current.isRoot = isRoot
-    ref.current.keys = keys
-    ref.current.schemeKeys = schemeKeys
-    ref.current.parentId = parentId
+  if (cascadeOnChange) {
+    registerThemeProviderChain(id, parentId, props)
   }
-  ref.current.renderVersion++
 
-  if (process.env.NODE_ENV === 'development' && globalThis.time)
-    globalThis.time`theme-prep-uses`
+  const ref = useRef<ThemeStateRef>(null as any)
+  const r = (ref.current ||= {
+    id,
+    parentId,
+    props,
+    propsKey,
+    isRoot,
+    keys,
+    schemeKeys,
+    optimizeForFirstRender,
+    renderVersion: 0,
+  })
+  r.props = props
+  r.propsKey = propsKey
+  r.isRoot = isRoot
+  r.keys = keys
+  r.schemeKeys = schemeKeys
+  r.parentId = parentId
+  r.renderVersion++
 
-  // manual subscription replaces useSyncExternalStore: same granular bailout
-  // (getSnapshot returning the same ref → React doesn't re-render), fewer
-  // React-internal hook slots on Hermes. We don't need tearing prevention
-  // here: theme/media updates are event-driven, not transition-driven, and
-  // useReducer in normal mode already gives same-tick batching.
   const [, forceUpdate] = useReducer(incReducer, 0)
-  const state = getSnapshotImpl(ref.current)
-  ref.current.lastSnap = state
+  const state = getSnapshotImpl(r)
+  r.lastSnap = state
 
   useEffect(() => {
-    const r = ref.current
     const renderVersion = r.renderVersion
 
-    // strict-mode dev double-invokes effects: cleanup runs between the two
-    // invocations with no render in between, so the "unchanged renderVersion
-    // means unmount" check below false-positives and deletes this component's
-    // registered theme state mid-lifecycle. the registry is only re-populated
-    // on this component's next render, so until then children resolve a
-    // missing parent and fall back to the root theme state (isNew: true) —
-    // which flips getThemedChildren to wrap and re-parents/remounts their
-    // hosts, losing focus (keyboard dismiss on first Input tap). per react's
-    // strict-mode contract, setup restores whatever cleanup tore down.
     if (r.lastSnap && !states.has(r.id)) {
       states.set(r.id, r.lastSnap)
       localStates.set(r.id, r.lastSnap)
     }
 
+    if (cascadeOnChange && !themeProviderParents.has(r.id)) {
+      registerThemeProviderChain(r.id, r.parentId, r.props)
+    }
+
     if (r.unsubscribe && r.subscribedParentId !== r.parentId) {
       cleanupThemeSubscription(r)
     }
@@ -167,19 +161,22 @@ Looked for theme${props.name ? ` "${props.name}"` : ''}${props.componentName ? `
       if (!r.unsubscribe) {
         const pid = r.parentId
         const sid = r.id
-        const cb = () => {
+        const cb = (forced?: boolean) => {
           const next = getSnapshotImpl(r)
           if (next !== r.lastSnap) {
             r.lastSnap = next
+            if (!forced && r.props.nativeUpdate?.(next)) {
+              return
+            }
             forceUpdate()
           }
         }
 
-        listenersByParent[pid] = listenersByParent[pid] || new Set()
-        listenersByParent[pid].add(sid)
+        ;(listenersByParent[pid] ||= new Set()).add(sid)
         allListeners.set(sid, () => {
-          PendingUpdate.set(sid, shouldForce ? 'force' : true)
-          cb()
+          const forced = shouldForce
+          PendingUpdate.set(sid, forced ? 'force' : true)
+          cb(forced)
         })
         r.subscribedParentId = pid
         r.unsubscribe = () => {
@@ -197,9 +194,6 @@ Looked for theme${props.name ? ` "${props.name}"` : ''}${props.componentName ? `
     }
 
     return () => {
-      // react runs passive cleanup before the next effect as well as on unmount.
-      // a newer render bumps renderVersion before that cleanup, so equality here
-      // means this is the final unmount cleanup.
       if (r.renderVersion === renderVersion) {
         cleanupThemeState(r)
       }
@@ -215,15 +209,11 @@ Looked for theme${props.name ? ` "${props.name}"` : ''}${props.componentName ? `
       }
       if (!propsKey) {
         if (HadTheme.get(keys)) {
-          // we're removing the last theme, make sure to notify
           scheduleUpdate(id)
         }
         HadTheme.set(keys, false)
         return
       }
-      if (process.env.NODE_ENV === 'development' && props.debug === 'verbose') {
-        console.warn(` · useTheme(${id}) scheduleUpdate`, propsKey, states.get(id)?.name)
-      }
       scheduleUpdate(id)
       HadTheme.set(keys, true)
     }, [keys, propsKey])
@@ -240,6 +230,7 @@ type SnapshotRef = {
   isRoot: boolean
   keys: MutableRefObject<Set<string> | null>
   schemeKeys?: MutableRefObject<Set<string> | null>
+  optimizeForFirstRender: boolean
 }
 
 type ThemeStateRef = SnapshotRef & {
@@ -250,11 +241,14 @@ type ThemeStateRef = SnapshotRef & {
 }
 
 const shouldSubscribeToTheme = (r: ThemeStateRef, cascadeOnChange: boolean): boolean =>
-  r.isRoot ||
-  cascadeOnChange ||
-  hasThemeUpdatingProps(r.props) ||
-  !!r.keys.current?.size ||
-  !!r.props.needsUpdate?.()
+  Boolean(
+    r.optimizeForFirstRender ||
+    r.isRoot ||
+    cascadeOnChange ||
+    hasThemeUpdatingProps(r.props) ||
+    r.keys.current?.size ||
+    r.props.needsUpdate?.()
+  )
 
 function cleanupThemeSubscription(r: ThemeStateRef) {
   r.unsubscribe?.()
@@ -268,26 +262,37 @@ function cleanupThemeState(r: ThemeStateRef) {
     states.delete(r.id)
     PendingUpdate.delete(r.id)
   }
+  themeUpdateLayers.delete(r.id)
+  themeProviderParents.delete(r.id)
 }
 
 const getSnapshotImpl = (r: SnapshotRef): ThemeState => {
-  const { id, parentId, props, propsKey, isRoot, keys, schemeKeys } = r
+  const {
+    id,
+    parentId,
+    props,
+    propsKey,
+    isRoot,
+    keys,
+    schemeKeys,
+    optimizeForFirstRender,
+  } = r
   let local = localStates.get(id)
   const parentState = states.get(parentId)
 
-  // fast path: nothing changed since last snapshot
   if (local && !PendingUpdate.has(id)) {
     if (
       parentState &&
       (local as any)._parentName === parentState.name &&
+      (local as any)._parentSchemeAuthored === parentState.schemeAuthored &&
       (local as any)._propsKey === propsKey
     ) {
       return local
     }
   }
 
-  // check if this is a scheme-only change (light↔dark) where DynamicColorIOS handles it
   const isSchemeOnlyChange =
+    !optimizeForFirstRender &&
     process.env.TAMAGUI_TARGET === 'native' &&
     supportsDynamicColorIOS &&
     getSetting('fastSchemeChange') &&
@@ -296,26 +301,27 @@ const getSnapshotImpl = (r: SnapshotRef): ThemeState => {
     local.scheme !== parentState.scheme &&
     getThemeBaseName(local.name) === getThemeBaseName(parentState.name)
 
-  // all tracked keys are scheme-optimized = can skip re-render for scheme changes
-  const keysSize = keys?.current?.size ?? 0
-  const schemeKeysSize = schemeKeys?.current?.size ?? 0
-  const allKeysSchemeOptimized = schemeKeysSize === keysSize && keysSize > 0
+  const allKeysSchemeOptimized =
+    !optimizeForFirstRender &&
+    Boolean(keys.current?.size && schemeKeys?.current?.size === keys.current.size)
 
-  const canSkipForSchemeChange = isSchemeOnlyChange && allKeysSchemeOptimized
+  const canSkipForSchemeChange = Boolean(isSchemeOnlyChange && allKeysSchemeOptimized)
 
   const needsUpdate = props.passThrough
     ? false
-    : isRoot || props.name === 'light' || props.name === 'dark' || props.name === null
+    : optimizeForFirstRender
       ? true
-      : !HasRenderedOnce.get(keys)
+      : isRoot || props.name === 'light' || props.name === 'dark' || props.name === null
         ? true
-        : canSkipForSchemeChange
-          ? false // skip re-render for scheme-only changes with DynamicColorIOS
-          : keys?.current?.size
-            ? true
-            : props.needsUpdate?.()
-
-  const [rerender, next] = getNextState(
+        : !HasRenderedOnce.get(keys)
+          ? true
+          : canSkipForSchemeChange
+            ? false
+            : keys?.current?.size
+              ? true
+              : props.needsUpdate?.()
+
+  const [rerender, nextRaw] = getNextState(
     local,
     props,
     propsKey,
@@ -326,39 +332,29 @@ const getSnapshotImpl = (r: SnapshotRef): ThemeState => {
     PendingUpdate.get(id)
   )
 
+  let next = nextRaw
+  if (props._themeUpdate && nextRaw?.theme) {
+    const parentTheme = states.get(parentId)?.theme || nextRaw.theme
+    const merged = props._themeUpdate.getTheme(parentTheme, nextRaw.name, getConfig())
+    if (merged !== nextRaw.theme) {
+      next = { ...nextRaw, theme: merged as ThemeParsed }
+    }
+  }
+
   PendingUpdate.delete(id)
 
-  // we always create a new localState for every component
-  // that way we can use it to de-opt and avoid renders granularly
-  // we always return the localState object in each component
-  // the global state (states) should always be up to date with the latest
   if (!local || rerender) {
     local = { ...next }
     localStates.set(id, local)
   }
 
-  if (process.env.NODE_ENV === 'development' && props.debug === 'verbose') {
-    console.groupCollapsed(` ${id} getSnapshot ${rerender}`, local.name, '>', next.name)
-    console.info({
-      props,
-      propsKey,
-      isRoot,
-      parentId,
-      local,
-      next,
-      needsUpdate,
-      isSchemeOnlyChange,
-      allKeysSchemeOptimized,
-      canSkipForSchemeChange,
-    })
-    console.groupEnd()
-  }
-
   if (next !== local) {
     Object.assign(local, next)
     local.id = id
   }
   ;(local as any)._parentName = parentState?.name
+  // scheme intent can change while the resolved name stays the same.
+  ;(local as any)._parentSchemeAuthored = parentState?.schemeAuthored
   ;(local as any)._propsKey = propsKey
   states.set(id, next)
 
@@ -375,59 +371,55 @@ const getNextState = (
   needsUpdate: boolean | undefined,
   pendingUpdate: boolean | 'force' | undefined
 ): [boolean, ThemeState] => {
-  const { debug } = props
   const parentState = states.get(parentId)
 
   if (props.passThrough) {
     return [false, lastState || parentState || ({ name: '' } as any)]
   }
 
-  if (!themes) {
-    themes = getConfig().themes
-  }
+  themes ||= getConfig().themes
 
   const name =
-    !propsKey && (!lastState || !lastState?.isNew)
+    !propsKey && (!lastState || !lastState.isNew)
       ? null
       : getNewThemeName(
           parentState?.name,
           props,
           pendingUpdate === 'force' ? true : !!needsUpdate
         )
-  const isSameAsParent = parentState && (!name || name === parentState.name)
+  // explicit schemes pin even when resolution reuses the parent's theme name.
+  const authoredName = props.name
+  const parentSchemeAuthored = !!parentState?.schemeAuthored
+  const schemeAuthored = isRoot
+    ? !!props.forceClassName
+    : parentSchemeAuthored ||
+      !!(authoredName && getScheme(authoredName) && authoredName in themes)
+  const intentChanged = schemeAuthored !== parentSchemeAuthored
+  const resolvedName = name || parentState?.name
+  const sameAsLast =
+    lastState &&
+    lastState.name === resolvedName &&
+    !!lastState.schemeAuthored === schemeAuthored
+
+  const isSameAsParent = Boolean(
+    parentState && resolvedName === parentState.name && !intentChanged
+  )
   const shouldRerender = Boolean(
     pendingUpdate === 'force' ||
-    (needsUpdate && (pendingUpdate || lastState?.name !== parentState?.name))
+    (needsUpdate &&
+      (pendingUpdate ||
+        lastState?.name !== parentState?.name ||
+        !!lastState?.schemeAuthored !== schemeAuthored))
   )
 
-  if (process.env.NODE_ENV === 'development' && debug === 'verbose') {
-    const message = ` · useTheme(${id}) getNextState => ${name} needsUpdate ${needsUpdate} shouldRerender ${shouldRerender}`
-    if (process.env.TAMAGUI_TARGET === 'native') {
-      console.info(message)
-    } else {
-      console.groupCollapsed(message)
-      console.trace({ name, lastState, parentState, props, propsKey, id, isSameAsParent })
-      console.groupEnd()
-    }
-  }
-
   if (isSameAsParent) {
-    if (!shouldRerender && lastState && lastState.name === parentState!.name) {
+    if (!shouldRerender && sameAsLast) {
       return [false, lastState]
     }
-    return [shouldRerender, { ...parentState, isNew: false }]
+    return [shouldRerender, { ...parentState!, isNew: false }]
   }
 
-  if (!name) {
-    // parentState can be transiently missing when a consumer renders in a
-    // separate sync flush (a portal/Toast viewport, or a native multi-root
-    // surface) before its provider has populated the module-level `states` map.
-    // that's recoverable — the next render resolves it — so fall back to the
-    // root theme (or a light stub) instead of throwing. the "no parent context"
-    // throw above still catches a genuinely missing provider. going back to
-    // useSyncExternalStore would avoid the race but force every themed node out
-    // of concurrent rendering, so we keep the manual store and tolerate the
-    // ordering here.
+  if (!resolvedName) {
     const next = lastState ??
       parentState ??
       rootThemeState ?? {
@@ -437,62 +429,36 @@ const getNextState = (
       }
 
     if (shouldRerender) {
-      const updated = { ...(parentState || lastState || next)! }
-      return [true, updated]
+      return [true, { ...(parentState || lastState || next) }]
     }
 
     return [false, next]
   }
 
-  const scheme = getScheme(name)
+  // a same-name pin still introduces its own scope.
+  const scheme = getScheme(resolvedName)
   const parentInverses = parentState?.inverses ?? 0
-  const isInverse = parentState && scheme !== parentState.scheme
-  // cumulative from the root: once any level flips scheme, every descendant is
-  // considered inverted vs the OS, even sub-themes that match their immediate
-  // parent (dark_blue under dark). gates the DynamicColorIOS optimization below.
+  const isInverse = Boolean(parentState && scheme !== parentState.scheme)
   const inverses = parentInverses + (isInverse ? 1 : 0)
 
-  const nextState = {
+  const nextState: ThemeState = {
     id,
-    name,
-    theme: themes[name],
+    name: resolvedName,
+    theme: themes[resolvedName],
     scheme,
     parentId,
     parentName: parentState?.name,
     inverses,
     isInverse,
+    schemeAuthored,
     isNew: true,
-  } satisfies ThemeState
+  }
 
   if (isRoot) {
     rootThemeState = nextState
   }
 
-  if (pendingUpdate !== 'force' && lastState && lastState.name === name) {
-    return [false, nextState]
-  }
-
-  const shouldAvoidRerender =
-    pendingUpdate !== 'force' &&
-    lastState &&
-    !needsUpdate &&
-    nextState.name === lastState.name
-
-  if (process.env.NODE_ENV === 'development' && debug === 'verbose') {
-    console.groupCollapsed(
-      ` · useTheme(${id}) ⏭️ ${name} shouldAvoidRerender: ${shouldAvoidRerender}`
-    )
-    console.info({ lastState, needsUpdate, nextState, pendingUpdate })
-    console.groupEnd()
-  }
-
-  // we still update the state (not changing identity), that way children can properly resolve the right state
-  // but this one wont trigger an update
-  if (shouldAvoidRerender) {
-    return [false, nextState]
-  }
-
-  return [true, nextState]
+  return [pendingUpdate === 'force' || !sameAsLast, nextState]
 }
 
 function scheduleUpdate(id: string) {
@@ -513,38 +479,18 @@ function scheduleUpdate(id: string) {
   }
 
   visited.forEach((childId) => {
-    const cb = allListeners.get(childId)
-    cb?.()
+    allListeners.get(childId)?.()
   })
 }
 
-const validSchemes = {
-  light: 'light',
-  dark: 'dark',
-} as const
-
-function getScheme(name: string) {
-  return validSchemes[name.split('_')[0]]
-}
-
-function getNewThemeName(
+export function getNewThemeName(
   parentName = '',
   props: UseThemeWithStateProps,
   forceUpdate = false
 ): string | null {
-  const { name, reset } = props
-  const componentName = props.unstyled ? undefined : props.componentName
+  const { name } = props
 
-  if (name && reset) {
-    throw new Error(
-      process.env.NODE_ENV === 'production'
-        ? `❌004`
-        : 'Cannot reset and set a new name at the same time.'
-    )
-  }
-
-  // check cache
-  const cacheKey = `${parentName}|${name || ''}|${componentName || ''}|${reset ? 1 : 0}|${forceUpdate ? 1 : 0}`
+  const cacheKey = `${parentName}|${name || ''}|${forceUpdate ? 1 : 0}`
   if (themeNameCacheVer !== cacheVersion) {
     themeNameCache.clear()
     themeNameCacheVer = cacheVersion
@@ -553,149 +499,56 @@ function getNewThemeName(
     if (cached !== undefined) return cached
   }
 
-  const { themes } = getConfig()
-
-  if (reset) {
-    // For reset, we need to go back to the grandparent theme
-    // If parentName is just a scheme (like "dark" or "light"),
-    // we should return the opposite scheme or a default
-    const isSchemeOnly = parentName === 'light' || parentName === 'dark'
-    if (isSchemeOnly) {
-      // If parent is just a scheme, go to the opposite scheme
-      const result = parentName === 'light' ? 'dark' : 'light'
-      themeNameCache.set(cacheKey, result)
-      return result
-    }
-
-    // For compound themes like "dark_blue", extract the scheme
-    const lastPartIndex = parentName.lastIndexOf('_')
-    // parentName will have format light_{name} or dark_{name}
-    const name = lastPartIndex <= 0 ? parentName : parentName.slice(lastPartIndex)
-    const scheme = parentName.slice(0, lastPartIndex)
-    const result = themes[name] ? name : scheme
-    themeNameCache.set(cacheKey, result)
-    return result
-  }
-
-  const parentParts = parentName.split('_')
-
-  // always remove component theme if it exists, we never sub a component theme
-  const lastName = parentParts[parentParts.length - 1]
-  if (lastName && lastName[0].toLowerCase() !== lastName[0]) {
-    parentParts.pop()
+  const result = resolveThemeName(
+    parentName,
+    name ?? undefined,
+    getConfig().themes,
+    forceUpdate
+  )
+  if (themeNameCache.size >= 10_000) {
+    themeNameCache.clear()
   }
+  themeNameCache.set(cacheKey, result)
+  return result
+}
 
-  const subNames = [
-    name && componentName ? `${name}_${componentName}` : undefined,
-    name,
-    componentName,
-  ].filter(Boolean) as string[]
+export const getThemeNameCacheSize = () => themeNameCache.size
 
+export function resolveThemeName(
+  parentName: string,
+  name: string | undefined,
+  themes: Record<string, any>,
+  forceUpdate = false
+): string | null {
+  const parentParts = parentName ? parentName.split('_') : []
   let found: string | null = null
 
-  // If name is provided, try it as a standalone theme first (both with and without scheme)
-  // This allows explicit theme overrides like:
-  // - <Theme name="blue"><Button theme="dark_green"> → finds "dark_green_Button"
-  // - <Theme name="blue"><Button theme="green"> → finds "light_green_Button"
-  // - <Theme name="blue"><Button theme="green_active"> → finds "light_green_active_Button"
   if (name) {
-    // First try the exact name as-is, but only if it already has a scheme prefix
-    // This prevents "green" from matching before we try "light_green_Button"
     const nameHasScheme = getScheme(name)
-
-    if (nameHasScheme) {
-      // Name has scheme (like "dark_green"), try as-is with priority to component theme
-      for (const subName of subNames) {
-        if (subName in themes) {
-          found = subName
-          break
-        }
-      }
+    if (nameHasScheme && name in themes) {
+      found = name
     }
-
-    // If not found and name doesn't have a scheme, try adding parent's scheme
     if (!found && !nameHasScheme) {
-      const parentScheme = getScheme(parentName)
-
-      if (parentScheme) {
-        // Try progressively shorter parent bases to preserve color context
-        // For parent "light_blue_surface1" + name "surface3":
-        //   Try: light_blue_surface1_surface3, light_blue_surface3, light_surface3
-        // This ensures color context (blue) is preserved before falling back to scheme-only
-
-        // Build list of potential bases from most specific to least specific
-        const potentialBases: string[] = []
-        for (let i = parentParts.length; i >= 1; i--) {
-          potentialBases.push(parentParts.slice(0, i).join('_'))
-        }
-
-        outer: for (const base of potentialBases) {
-          // Try with componentName first, then without
-          const candidates = [
-            componentName ? `${base}_${name}_${componentName}` : undefined,
-            `${base}_${name}`,
-          ].filter(Boolean) as string[]
-
-          for (const potential of candidates) {
-            if (potential in themes) {
-              found = potential
-              break outer
-            }
-          }
-        }
-      }
-    }
-  }
-
-  // If not found, fall back to the original search algorithm combining with parent
-  if (!found) {
-    // If we're only adding componentName (no explicit name prop), don't backtrack through parent parts
-    // This preserves sub-themes like "light_red_surface1" when adding Button component
-    if (!name && componentName) {
-      // Just try adding component to full parent
-      const potential = `${parentParts.join('_')}_${componentName}`
-      if (potential in themes) {
-        found = potential
-      }
-      // If not found, don't add component theme - return null to keep parent theme
-    } else {
-      // Original backtracking search for when explicit name is provided
-      const max = parentParts.length
-
-      for (let i = 0; i <= max; i++) {
-        const base = (i === 0 ? parentParts : parentParts.slice(0, -i)).join('_')
-
-        for (const subName of subNames) {
-          const potential = base ? `${base}_${subName}` : subName
-
-          if (potential in themes) {
-            found = potential
-            break
-          }
+      for (let i = parentParts.length; i >= 0; i--) {
+        const base = parentParts.slice(0, i).join('_')
+        const potential = base ? `${base}_${name}` : name
+        if (potential in themes) {
+          found = potential
+          break
         }
-
-        if (found) break
       }
     }
   }
 
-  if (
-    !forceUpdate &&
-    found === parentName &&
-    // if its a scheme only sub-theme, we always consider it "new" because it likely inverses
-    // and we want to avoid reparenting
-    !validSchemes[found]
-  ) {
-    themeNameCache.set(cacheKey, null)
+  if (!forceUpdate && found === parentName && found !== 'light' && found !== 'dark') {
     return null
   }
 
-  themeNameCache.set(cacheKey, found)
   return found
 }
 
-const getPropsKey = ({ name, reset, forceClassName, componentName }: ThemeProps) =>
-  `${name || ''}${reset || ''}${forceClassName || ''}${componentName || ''}`
+const getPropsKey = ({ name, forceClassName, _themeUpdate }: UseThemeWithStateProps) =>
+  `${name || ''}${forceClassName || ''}${_themeUpdate?.key || ''}`
 
-export const hasThemeUpdatingProps = (props: ThemeProps) =>
-  'name' in props || 'reset' in props || 'forceClassName' in props
+export const hasThemeUpdatingProps = (props: UseThemeWithStateProps) =>
+  'name' in props || 'forceClassName' in props || '_themeUpdate' in props