@tamagui/web 3.0.0-beta.922.1 → 3.0.0

package/src/types.tsx

@@ -4,6 +4,7 @@ import type {
   TransformAccumulator,
 } from '@tamagui/style-grammar/runtime'
 import type { Properties } from 'csstype'
+import type { UnprefixedCSSProperties } from './dom/styleTypes'
 import type {
   CSSProperties,
   ComponentType,
@@ -18,16 +19,23 @@ import type {
   SetStateAction,
 } from 'react'
 import type {
+  FontVariant,
   PressableProps,
-  Text as RNText,
+  TextInstance as RNText,
   TextStyle as RNTextStyle,
   TextProps as ReactTextProps,
-  View,
+  ViewInstance as View,
   ViewProps,
   ViewStyle,
-} from 'react-native'
+} from '@tamagui/react-native-types'
 
 import type { NativeStyleEngineLinkHandle } from './helpers/nativeStyleEngine'
+import type {
+  AnimatedTextChannel,
+  NativeTextContext,
+  NativeTextMetrics,
+} from './helpers/nativeTextMetrics'
+export type { AnimatedTextChannel, NativeTextMetrics } from './helpers/nativeTextMetrics'
 import type { StyleFrontend } from './helpers/styleFrontend'
 import type { CSSColorNames } from './interfaces/CSSColorNames'
 import type { RNOnlyProps } from './interfaces/RNExclusiveTypes'
@@ -484,6 +492,12 @@ export type ThemeState = {
   isNew?: boolean
   parentId?: string
   scheme?: 'light' | 'dark'
+  // true when a `<Theme name="light_blue">` at or above this state named its
+  // scheme outright, rather than inheriting the scheme from the root. Only such
+  // a state may emit the scheme-qualified `t_light_blue` class; everything else
+  // stays scheme-relative so server output renders correctly under either root
+  // scheme. Cumulative: once an ancestor pins, descendants stay pinned.
+  schemeAuthored?: boolean
 }
 
 export interface Variable<A = any> {
@@ -613,14 +627,12 @@ export type ComponentSetStateShallow = React.Dispatch<
 
 export type ComponentSetState = Dispatch<SetStateAction<TamaguiComponentState>>
 
-export type ComponentContextI = {
+export type ComponentContextI = NativeTextContext & {
   disableSSR?: boolean
   inText: boolean
   language: LanguageContextType | null
   animationDriver: AnimationDriver | null
   setParentFocusState: ComponentSetStateShallow | null
-  mediaEmit?: (state: UseMediaState) => void
-  mediaEmitListeners?: Set<(state: UseMediaState) => void>
   insets?: { top: number; right: number; bottom: number; left: number } | null
 }
 
@@ -630,6 +642,12 @@ export type TamaguiComponentStateRef = {
 
   host?: TamaguiElement
   composedRef?: (x: TamaguiElement) => void
+  // the forwarded ref composedRef writes to right now, read at attach time so the
+  // cached callback never pins the first render's ref
+  composedForwardedRef?: React.Ref<TamaguiElement>
+  // the forwarded ref composedRef last handed the host to, so a swap can be
+  // detected without a render-phase "previous" pointer (see createComponent)
+  attachedForwardedRef?: React.Ref<TamaguiElement>
   willHydrate?: boolean
   hasMeasured?: boolean
   hasAnimated?: boolean
@@ -641,6 +659,9 @@ export type TamaguiComponentStateRef = {
   hasEverResetPresence?: boolean
   hasHadEvents?: boolean
   hasRealPressEvents?: boolean
+  // previous render's press-plumbing presence, so a detach mid-press can drop
+  // the in-flight press instead of latching it (see createComponent)
+  hadAttachPress?: boolean
   isListeningToTheme?: boolean
   unPress?: Function
   setStateShallow?: ComponentSetStateShallow
@@ -665,8 +686,11 @@ export type TamaguiComponentStateRef = {
   // per-render animatedBy prop; hooks gated on it must keep a stable count)
   avoidReRenders?: boolean
 
-  // cleanup function for media emit listener
-  mediaEmitCleanup?: () => void
+  // avoidReRenders: this instance's useMedia emits media changes here instead
+  // of re-rendering
+  mediaEmit?: (state: UseMediaState) => void
+  // a restyle from mediaEmit is queued for this event turn
+  mediaEmitQueued?: boolean
 
   // previous pseudo state for detecting enter vs exit transitions
   prevPseudoState?: {
@@ -701,6 +725,10 @@ export type TamaguiComponentStateRef = {
   // but absent from the next push are sent as null (reset-to-default),
   // matching what a real re-render's style diff would do
   nativePushedKeys?: Set<string>
+
+  // native style stability: the most recently resolved style object, reused
+  // when the next render's resolved values are identical (see getSplitStyles)
+  prevStyle?: Record<string, any> | null
 }
 
 export type ComponentGroupEmitter = {
@@ -717,6 +745,7 @@ export type WidthHeight = {
 export type ChildGroupState = {
   pseudo?: PseudoGroupState
   media?: Record<MediaQueryKey extends number ? never : MediaQueryKey, boolean>
+  layout?: WidthHeight
 }
 
 export type ComponentGroupState = {
@@ -899,6 +928,7 @@ export type CreateTamaguiConfig<
   E extends GenericAnimations = GenericAnimations,
   F extends GenericFonts = GenericFonts,
   H extends GenericTamaguiSettings = GenericTamaguiSettings,
+  S extends GenericSizing = GenericSizing,
   // preserve the raw animation driver keys ('default' | 'css' | etc)
   // defaults to string so generic TamaguiInternalConfig accepts any driver keys
   AnimDriverKeys extends string = string,
@@ -923,6 +953,7 @@ export type CreateTamaguiConfig<
   // phantom type for preserving driver keys - never set at runtime, only for type inference
   animationDriverKeys?: AnimDriverKeys
   settings: H
+  sizing: S
 }
 
 type GetLanguagePostfix<Set> = Set extends string
@@ -949,7 +980,7 @@ type GetLanguagePostfixes<F extends GenericFonts> = GetLanguagePostfix<keyof F>
 //   body_en: any
 // }>['fonts']
 
-type ConfProps<A, B, C, D, E, F, I, V = undefined> = {
+type ConfProps<A, B, C, D, E, F, I, S, V = undefined> = {
   tokens?: A
   themes?: B
   shorthands?: C
@@ -957,6 +988,7 @@ type ConfProps<A, B, C, D, E, F, I, V = undefined> = {
   animations?: E
   fonts?: F
   settings?: I
+  sizing?: S
   variables?: V
 }
 
@@ -1022,6 +1054,7 @@ export type InferTamaguiConfig<Conf> =
     infer E,
     infer F,
     infer H,
+    infer S,
     infer V
   >
     ? TamaguiInternalConfig<
@@ -1032,6 +1065,7 @@ export type InferTamaguiConfig<Conf> =
         ExtractAnimationConfig<E>,
         F extends GenericFonts ? F : EmptyFonts,
         H extends GenericTamaguiSettings ? H : EmptyTamaguiSettings,
+        S extends GenericSizing ? S : GenericSizing,
         ExtractAnimationDriverKeys<E>
       >
     : unknown
@@ -1204,8 +1238,9 @@ export interface GenericTamaguiSettings {
    * controls style semantics where React Native/Yoga and CSS differ.
    *
    * - "legacy": preserves Tamagui v1 flex expansion.
-   * - "react-native": follows React Native/Yoga flex and raw numeric lineHeight semantics.
-   * - "web": follows CSS flex and unitless numeric lineHeight semantics.
+   * - "react-native": follows React Native/Yoga flex expansion.
+   * - "web": follows CSS flex expansion.
+   * numeric Tamagui lineHeight values are ratios in every mode.
    *
    * @default "web"
    */
@@ -1299,6 +1334,18 @@ export interface GenericTamaguiSettings {
    */
   onlyAllowShorthands?: boolean | undefined
 
+  /**
+   * Restrict conditional style values to one syntax. Flat values accept both
+   * the string form (`bg="red hover:blue"`) and the object form
+   * (`bg={{ base: 'red', hover: 'blue' }}`); set this to keep one of them,
+   * which narrows the types, makes the runtime warn on the other in
+   * development, and tells `tamagui generate-prompt` and the skills to only
+   * show that form.
+   *
+   * @default undefined - both forms are allowed
+   */
+  styleValueSyntax?: 'string' | 'object' | undefined
+
   /**
    * Define a default font, for better types and default font on Text
    */
@@ -1383,6 +1430,56 @@ export interface GenericTamaguiSettings {
   onlyShorthandStyleProps?: boolean
 }
 
+/** one rung of the control ladder: token keys, plus optional pinned geometry */
+export type SizeRecipe = {
+  fontSize: string
+  /**
+   * the type-scale key the square controls (checkbox, radio, switch) size
+   * from. Usually the rung's own name, but text deliberately steps down at
+   * `md`/`lg` so buttons are not chunky while the squares stay on-scale.
+   */
+  controlFontSize: string
+  paddingInline: string
+  paddingBlock: string
+  gap: string
+  radius: string
+  /**
+   * explicit rung geometry, skipping derivation. For scales whose keys
+   * cannot derive the ladder (v5's numeric scales pin the frozen heights
+   * here so v5 apps never resize).
+   */
+  px?: {
+    height: number
+    icon: number
+    square: number
+  }
+}
+
+/**
+ * the user-configurable control ladder. Rung names become the accepted
+ * `size` values (see ComponentSize); the px derivations in resolveSizing are
+ * fixed formulas over the rung's tokens.
+ */
+export type GenericSizing = {
+  default: string
+  sizes: Record<string, SizeRecipe>
+}
+
+/**
+ * the config's control size names: the default ladder plus any custom rungs
+ * from `sizing.sizes`. Stays the five literals (never `string`) when no
+ * custom config is registered.
+ */
+export type ComponentSize =
+  | 'xs'
+  | 'sm'
+  | 'md'
+  | 'lg'
+  | 'xl'
+  | (string extends keyof TamaguiConfig['sizing']['sizes']
+      ? never
+      : Extract<keyof TamaguiConfig['sizing']['sizes'], string>)
+
 export type TamaguiSettings = TamaguiConfig['settings']
 
 export type BaseStyleProps = {
@@ -1436,12 +1533,11 @@ export type CreateTamaguiProps = {
   settings?: Partial<GenericTamaguiSettings>
 
   /**
-   * Web-only: define text-selection CSS
+   * the control size ladder: rung names become the accepted `size` values.
+   * Spread `defaultSizing` and override `sizes` to add or retune rungs; the
+   * px derivations are fixed formulas over each rung's tokens.
    */
-  selectionStyles?: (theme: Record<string, string>) => null | {
-    backgroundColor?: any
-    color?: any
-  }
+  sizing?: GenericSizing
 }
 
 export type GetCSS = (opts?: {
@@ -1459,11 +1555,12 @@ export type TamaguiInternalConfig<
   E extends GenericAnimations = GenericAnimations,
   F extends GenericFonts = GenericFonts,
   G extends GenericTamaguiSettings = GenericTamaguiSettings,
+  S extends GenericSizing = GenericSizing,
   // preserve the raw animation driver keys ('default' | 'css' | etc)
   // defaults to string so generic TamaguiInternalConfig accepts any driver keys
   AnimDriverKeys extends string = string,
 > = Omit<CreateTamaguiProps, keyof GenericTamaguiConfig> &
-  Omit<CreateTamaguiConfig<A, B, C, D, E, F, G, AnimDriverKeys>, 'tokens'> & {
+  Omit<CreateTamaguiConfig<A, B, C, D, E, F, G, S, AnimDriverKeys>, 'tokens'> & {
     // TODO need to make it this but this breaks types, revisit
     // animations: E //AnimationDriver<E>
     tokens: Tokenify<A>
@@ -1478,6 +1575,7 @@ export type TamaguiInternalConfig<
     reactNative?: any
     fontSizeTokens: Set<string>
     settings: Omit<GenericTamaguiSettings, keyof G> & G
+    sizing: Omit<GenericSizing, keyof S> & S
     defaultFont?: string
     defaultFontToken: `${string}`
     // multi-driver animation config (e.g., { default: motionDriver, css: cssDriver })
@@ -1496,7 +1594,7 @@ type GenericFontKey = string | number | symbol
 export type GenericFont<Key extends GenericFontKey = GenericFontKey> = {
   size: { [key in Key]: number | Variable }
   family?: string | Variable
-  lineHeight?: Partial<{ [key in Key]: number | Variable }> | undefined
+  lineHeight?: Partial<{ [key in Key]: number | Px | `${number}` | Variable }> | undefined
   letterSpacing?: Partial<{ [key in Key]: number | Variable }> | undefined
   weight?: Partial<{ [key in Key]: number | string | Variable }> | undefined
   style?: Partial<{ [key in Key]: RNTextStyle['fontStyle'] | Variable }> | undefined
@@ -1553,75 +1651,90 @@ export type MatchMedia = (query: string) => MediaQueryList
 
 // createComponent props helpers
 
-// transition="bouncy"
-// transition={['bouncy', {  }]}
-// { all: 'name' }
-
 // TODO can override for better types
 export type AnimationConfigType = any
 
 /**
- * Spring configuration parameters that can override preset defaults.
- * Use with array syntax: transition={['bouncy', { stiffness: 1000, damping: 70 }]}
+ * Low-level spring physics. A projection of `duration` + `bounce`, not a second
+ * way to configure a spring: whichever you author, the other is derived, and
+ * every driver ends up with the same motion.
+ *
+ * Reach for this only when you are porting a config you already tuned.
  */
 export type TransitionSpringConfig = {
   stiffness?: number
   damping?: number
   mass?: number
-  tension?: number
-  friction?: number
   velocity?: number
   overshootClamping?: boolean
-  duration?: number
-  bounciness?: number
-  speed?: number
+  restDisplacementThreshold?: number
+  restSpeedThreshold?: number
 }
 
 /**
- * A transition value: the name of a configured driver animation, or a raw CSS
- * transition string such as `200ms` or `200ms hover:400ms`. The runtime accepts
- * both — a name that is not a configured preset is treated as CSS — so the type
- * must too. `(string & {})` keeps the preset names in autocomplete instead of
- * collapsing the union to plain `string`.
+ * A transition value: the name of a configured driver animation, or a CSS
+ * transition string such as `200ms`, `200ms ease-out`, or
+ * `opacity 150ms, transform 300ms`.
+ *
+ * Springs get a CSS-shaped function of their own: `spring(300ms, 0.4)` is a
+ * 300ms spring with a bounce of 0.4. It works everywhere a timing function
+ * does, including on the web, where it compiles to a `linear()` easing.
+ *
+ * A bare string that exactly matches a configured animation name is that
+ * preset; everything else is CSS. `(string & {})` keeps preset names in
+ * autocomplete instead of collapsing the union to plain `string`.
  */
 export type TransitionValue = TransitionKeys | (string & {})
 
+/**
+ * The settings half of a transition object. Anything else in the object is a
+ * style property name carrying its own transition.
+ */
+export type TransitionConfig = {
+  /** a configured animation to start from */
+  preset?: TransitionKeys
+  /** milliseconds, or a CSS time like `'200ms'` */
+  duration?: number | string
+  /**
+   * Makes it a spring. `0` is critically damped (no overshoot), approaching
+   * `1` is loose and oscillating, negative is sluggish. `duration` stays the
+   * perceptual "how fast does this feel" number either way.
+   */
+  bounce?: number
+  /** any CSS timing function. Mutually exclusive with `bounce`. */
+  easing?: string
+  /** milliseconds, or a CSS time */
+  delay?: number | string
+  behavior?: 'normal' | 'allow-discrete'
+  /** the CSS `transition-property` list these settings apply to */
+  properties?: string
+  spring?: TransitionSpringConfig
+  /** the transition to use while mounting, if it differs */
+  enter?: TransitionProp
+  /** the transition to use while unmounting, if it differs */
+  exit?: TransitionProp
+}
+
+/**
+ * `transition` accepts a string or an object, and nothing else.
+ *
+ * ```tsx
+ * transition="bouncy"                                  // a configured preset
+ * transition="200ms ease-out"                          // css
+ * transition="opacity 150ms, transform spring(300ms, 0.4)"
+ * transition={{ duration: 200, bounce: 0.15 }}
+ * transition={{ preset: 'bouncy', opacity: '150ms' }}  // per-property override
+ * ```
+ *
+ * Per-property keys are later CSS entries, so they win for that property and
+ * inherit nothing from the base, exactly as
+ * `transition: all 200ms, opacity 150ms` behaves in a stylesheet.
+ */
 export type TransitionProp =
   | TransitionValue
-  | ({
-      default?: TransitionValue
-      enter?: TransitionValue
-      exit?: TransitionValue
-      delay?: number
-    } & TransitionSpringConfig & {
-        [key: string]:
-          | TransitionValue
-          | {
-              type: TransitionValue
-              [key: string]: any
-            }
-          | number
-          | boolean
-          | undefined
-      })
-  | [
-      TransitionValue,
-      {
-        delay?: number
-        enter?: TransitionValue
-        exit?: TransitionValue
-      } & TransitionSpringConfig & {
-          [key: string]:
-            | TransitionValue
-            | {
-                type?: TransitionValue
-                [key: string]: any
-              }
-            | number
-            | boolean
-            | undefined
-        },
-    ]
+  | (TransitionConfig & {
+      [property: string]: TransitionValue | TransitionConfig | unknown
+    })
 
 /**
  * Emitted by the animation driver at the start and end of a transition.
@@ -1661,6 +1774,11 @@ export type SomewhatSpecificColorValue =
   | (`#${string}` & {})
 
 type WebOnlySizeValue =
+  | `${number}px`
+  | `${number}em`
+  | `${number}ch`
+  | `${number}vmin`
+  | `${number}vmax`
   | `${number}vw`
   | `${number}dvw`
   | `${number}lvw`
@@ -1672,6 +1790,7 @@ type WebOnlySizeValue =
   | `calc(${string})`
   | `min(${string})`
   | `max(${string})`
+  | `clamp(${string})`
   | 'max-content'
   | 'min-content'
 
@@ -1680,6 +1799,37 @@ type UserAllowedStyleValuesSetting = Exclude<
   undefined
 >
 
+/**
+ * A flat value string that carries a clause (`red hover:blue`, `dark:red`)
+ * or a multi-token payload (`1px solid red`). Its grammar is validated by the
+ * language service and the runtime, not by the type system. With
+ * `styleValueSyntax: 'object'` the `:` arm is dropped, so a clause-only
+ * string like `hover:red` is a type error (a clause after a space still
+ * passes through the multi-token arm).
+ */
+export type FlatClauseString =
+  | `${string} ${string}`
+  | (StyleValueSyntaxSetting extends 'object' ? never : `${string}:${string}`)
+
+type StyleValueSyntaxSetting = TamaguiSettings extends { styleValueSyntax: infer S }
+  ? S
+  : undefined
+
+/**
+ * The open string arm every style value carries. With no `allowedStyleValues`
+ * setting (or a boolean one) it is `string & {}`, so any string is accepted.
+ * With a strictness setting, a single-token string (no space, no `:`) has to
+ * be a token, theme value, or a value the setting allows, so a typo like
+ * `bg="backgroun"` is a type error; only clause strings stay open.
+ */
+export type OpenStyleString = TamaguiSettings extends {
+  allowedStyleValues: infer Setting
+}
+  ? Setting extends boolean
+    ? UnionableString
+    : FlatClauseString
+  : UnionableString
+
 export type GetThemeValueSettingForCategory<
   Cat extends keyof AllowedStyleValuesSettingPerCategory,
 > = UserAllowedStyleValuesSetting extends AllowedValueSettingBase | undefined
@@ -1774,7 +1924,7 @@ export type GetTokenString<A> = A extends string | number ? `${A}` : string
 export type Size =
   | ThemeValueFallbackSize
   | GetTokenString<keyof Tokens['size']>
-  | (string & {})
+  | OpenStyleString
   | true
 
 export type SizeTokens = Size
@@ -1799,7 +1949,7 @@ export type Color =
   | TokenWithOpacity
   // clause-bearing values are intentionally open-ended; the language service
   // validates the grammar without materializing a combinatorial type union
-  | (string & {})
+  | OpenStyleString
 
 export type ColorTokens = Color
 
@@ -1862,6 +2012,8 @@ export type FontSizeTokens = FontSize
 export type FontLineHeightTokens =
   | GetTokenString<GetTokenFontKeysFor<'lineHeight'>>
   | number
+  | Px
+  | `${number}`
   | RemString
 export type FontWeightValues =
   | `${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}00`
@@ -1938,6 +2090,14 @@ export type LineHeightKeys = 'lineHeight'
 export type ZIndexKeys = 'zIndex'
 export type OpacityKeys = 'opacity'
 
+type FontStyleValueFallback = GetThemeValueFallbackFor<
+  AllowedValueSettingSize,
+  never,
+  never,
+  never,
+  WebStyleValueUniversal | `${number}%`
+>
+
 export type ThemeValueGet<K extends string | number | symbol> = K extends 'theme'
   ? ThemeTokens
   : K extends SizeKeys
@@ -1945,7 +2105,7 @@ export type ThemeValueGet<K extends string | number | symbol> = K extends 'theme
     : K extends FontKeys
       ? FontTokens
       : K extends FontSizeKeys
-        ? FontSizeTokens
+        ? FontSizeTokens | FontStyleValueFallback
         : K extends `${`border${string | ''}Radius`}`
           ? RadiusTokens
           : K extends SpaceKeys
@@ -1957,7 +2117,7 @@ export type ThemeValueGet<K extends string | number | symbol> = K extends 'theme
               : K extends ZIndexKeys
                 ? ZIndexTokens
                 : K extends LineHeightKeys
-                  ? FontLineHeightTokens
+                  ? FontLineHeightTokens | FontStyleValueFallback
                   : K extends FontWeightKeys
                     ? FontWeightTokens
                     : K extends FontLetterSpacingKeys
@@ -2047,22 +2207,25 @@ type FlatClauseName =
  * string members ('unset', a fallback union) stop being assignable across
  * package boundaries.
  */
-export type FlatStyleObject<T> = { default?: T | (string & {}) } & {
-  [K in FlatClauseName]?: T | (string & {})
+export type FlatStyleObject<T> = { default?: T | OpenStyleString } & {
+  [K in FlatClauseName]?: T | OpenStyleString
 }
 
 /**
- * The string arm stays at base values only: `(string & {})` admits every
+ * The string arm stays at base values only: `OpenStyleString` admits every
  * clause string, and structured clause completion comes from the object
  * form's keys (and the language-service plugin for strings). A per-prop
  * `${modifier}:` prefix union used to ride along for first-prefix
  * completion; it multiplied across the whole component prop graph and the
  * object form made it redundant.
  */
-export type FlatStyleValue<T> = T | FlatStyleObject<T> | (string & {})
+export type FlatStyleValue<T> =
+  | T
+  | (StyleValueSyntaxSetting extends 'string' ? never : FlatStyleObject<T>)
+  | OpenStyleString
 
 export type WithThemeValues<T extends object> = {
-  [K in keyof T]:
+  -readonly [K in keyof T]:
     | (ThemeValueGet<K> extends never
         ? K extends keyof ExtraBaseProps
           ? T[K]
@@ -2129,10 +2292,10 @@ export type WithThemeAndShorthands<
   A extends object,
   Variants = {},
 > = OnlyAllowShorthands extends true
-  ? WithThemeValues<MaybeOmitLonghands<Omit<A, Longhands>>> &
+  ? WithThemeValues<MaybeOmitLonghands<Omit<A, Longhands | keyof Variants>>> &
       WithFlatVariantValues<Variants> &
       WithShorthands<WithThemeValues<A>>
-  : WithThemeValues<MaybeOmitLonghands<A>> &
+  : WithThemeValues<MaybeOmitLonghands<Omit<A, keyof Variants>>> &
       WithFlatVariantValues<Variants> &
       WithShorthands<WithThemeValues<A>>
 
@@ -2150,13 +2313,13 @@ type TwoValueTransformOrigin = `${PxOrPct | 'left' | 'center' | 'right'} ${
 
 export interface TransformStyleProps {
   /**
-   * Maps to translateX
+   * Maps to translateX. A percent string is relative to the element's own width.
    */
-  x?: number
+  x?: number | `${number}%`
   /**
-   * Maps to translateY
+   * Maps to translateY. A percent string is relative to the element's own height.
    */
-  y?: number
+  y?: number | `${number}%`
   perspective?: number
   scale?: number
   scaleX?: number
@@ -2284,15 +2447,27 @@ interface ExtraStyleProps {
    * backgroundColor and drops url()/gradient/multi-part values it can't express.
    *
    * The v6 shorthands map `bg` here rather than to `backgroundColor`, because
-   * the background family splits a value like `url(x.png) color1` across
+   * the background family splits a value like `url(x.png) color-1` across
    * backgroundImage and backgroundColor. Color tokens lead the union so `bg`
-   * completes them; `Properties['background']` keeps the CSS shorthand
-   * keywords. Adding this key to `ColorKeys` instead would erase that second
-   * arm, since that path runs the value type through `Exclude<T[K], string>`.
-   */
-  background?: ColorTokens | Properties['background']
-  /**
-   * Web-only style property. Will be omitted on native.
+   * completes them; the CSS keywords and the function forms (`url()`,
+   * gradients) keep the CSS shorthand, and multi-part values reach
+   * `OpenStyleString` through their spaces. Adding this key to `ColorKeys`
+   * instead would erase the CSS arm, since that path runs the value type
+   * through `Exclude<T[K], string>`.
+   */
+  background?:
+    | ColorTokens
+    | Exclude<ThemeValueFallbackColor, number>
+    | 'none'
+    | 'inherit'
+    | 'initial'
+    | 'unset'
+    | 'revert'
+    | `${string}(${string})`
+    | OpenStyleString
+  /**
+   * css background image. native maps supported linear gradients to
+   * experimental_backgroundImage and drops values it cannot represent.
    */
   backgroundImage?: Properties['backgroundImage']
   /**
@@ -2347,6 +2522,8 @@ interface ExtraStyleProps {
    * Web-only style property. Will be omitted on native.
    */
   resize?: Properties['resize']
+  /** react-native stops at visible/hidden/scroll; web also accepts auto and clip */
+  overflow?: 'visible' | 'hidden' | 'scroll' | 'auto' | 'clip'
   /**
    * Web-only style property. Will be omitted on native.
    */
@@ -2601,6 +2778,7 @@ interface ExtraStyleProps {
   borderInlineWidth?: SpaceTokens | number
   borderInlineStartWidth?: SpaceTokens | number
   borderInlineEndWidth?: SpaceTokens | number
+  borderStyle?: ViewStyle['borderStyle'] | 'none' | 'hidden'
   borderBlockStyle?: ViewStyle['borderStyle']
   borderBlockStartStyle?: ViewStyle['borderStyle']
   borderBlockEndStyle?: ViewStyle['borderStyle']
@@ -2640,12 +2818,6 @@ interface ExtraBaseProps {
    */
   transition?: TransitionProp | null
 
-  /**
-   * Pass an array of strings containing the long style property names
-   * which will be exclusively transitioned.
-   */
-  animateOnly?: string[]
-
   /**
    * If you'd like this component to not attach to the nearest parent AnimatePresence,
    * set this to `false` and it will pass through to the next animated child.
@@ -2672,16 +2844,54 @@ interface ExtendedBaseProps
     ExtendBaseStackProps,
     ExtraStyleProps,
     ExtraBaseProps {
-  display?: 'inherit' | 'none' | 'inline' | 'block' | 'contents' | 'flex' | 'inline-flex'
+  display?:
+    | 'inherit'
+    | 'none'
+    | 'inline'
+    | 'block'
+    | 'inline-block'
+    | 'contents'
+    | 'flex'
+    | 'inline-flex'
+    | 'grid'
+    | 'inline-grid'
   // extends RN's position to include 'fixed' (converted to 'absolute' on native)
   position?: 'absolute' | 'relative' | 'fixed' | 'static' | 'sticky'
 }
 
 export interface StackStyleBase
-  extends Omit<ViewStyle, keyof ExtendedBaseProps | 'elevation'>, ExtendedBaseProps {}
+  extends
+    Omit<ViewStyle, keyof ExtendedBaseProps | 'elevation'>,
+    ExtendedBaseProps,
+    Omit<
+      UnprefixedCSSProperties,
+      keyof ViewStyle | keyof ExtendedBaseProps | keyof TamaguiComponentPropsBaseBase
+    > {}
 
 export interface TextStylePropsBase
-  extends Omit<RNTextStyle, keyof ExtendedBaseProps>, ExtendedBaseProps {
+  extends
+    Omit<
+      RNTextStyle,
+      keyof ExtendedBaseProps | 'fontVariant' | 'lineHeight' | 'includeFontPadding'
+    >,
+    ExtendedBaseProps,
+    Omit<
+      UnprefixedCSSProperties,
+      | keyof RNTextStyle
+      | keyof ExtendedBaseProps
+      | keyof TamaguiComponentPropsBaseBase
+      | 'textShadow'
+      | 'textDecoration'
+      | 'font'
+    > {
+  lineHeight?: number | Px | `${number}`
+  /**
+   * react-native types this as a mutable `FontVariant[]`, which an `as const` variant
+   * definition can't satisfy — and a variants object that misses its constraint is
+   * silently discarded whole, taking every variant on the component with it (#2787).
+   * react-native types `transform` as readonly for the same reason.
+   */
+  fontVariant?: readonly FontVariant[]
   ellipsis?: boolean
   numberOfLines?: number
   textDecorationDistance?: number
@@ -2699,8 +2909,7 @@ export interface TextStylePropsBase
    */
   textDecoration?: string
   /**
-   * CSS font shorthand string ("italic bold 16px/1.5 Inter").
-   * Splits by the CSS micro-syntax; ambiguous forms stay unparsed.
+   * css font shorthand string, browser-only and dropped on native.
    */
   font?: string
 }
@@ -2731,7 +2940,7 @@ export interface StackNonStyleProps
       | 'pointerEvents'
       | 'display'
       | 'children'
-      | keyof TamaguiComponentPropsBaseBase
+      | keyof TamaguiComponentPropsBase
       // these are added back in by core
       | RNOnlyProps
       | keyof ExtendBaseStackProps
@@ -2761,7 +2970,7 @@ export interface TextNonStyleProps
     Omit<
       ReactTextProps,
       | 'children'
-      | keyof WebOnlyPressEvents
+      | keyof TamaguiComponentPropsBase
       // these are added back in by core
       | RNOnlyProps
       | keyof ExtendBaseTextProps
@@ -2802,11 +3011,18 @@ export type StyledHOCMergedProps<Props, CustomProps> = keyof CustomProps extends
   ? Props
   : Omit<Props, keyof CustomProps> & CustomProps
 
+// declared receiver props keep their type when a new css name joins the style
+// surface. variants remain the explicit owner over either source.
 export type GetFinalProps<NonStyleProps, StylePropsBase, Variants> = Omit<
   NonStyleProps,
-  keyof StylePropsBase | keyof Variants
+  keyof Variants
 > &
-  (StylePropsBase extends object ? WithThemeAndShorthands<StylePropsBase, Variants> : {})
+  (StylePropsBase extends object
+    ? Omit<
+        WithThemeAndShorthands<StylePropsBase, Variants>,
+        Exclude<keyof NonStyleProps, keyof Variants>
+      >
+    : {})
 
 export type TamaguiComponent<
   Props = any,
@@ -2967,6 +3183,7 @@ export type GetStyleState = {
   conf: TamaguiInternalConfig
   avoidMergeTransform?: boolean
   fontFamily?: string
+  nativeLineHeight?: unknown
   debug?: DebugProp
   transformAccumulator?: TransformAccumulator
   // direct flat-value scan context and its subscription output
@@ -3091,6 +3308,8 @@ export type StaticConfigPublic = {
 }
 
 type StaticConfigBase = StaticConfigPublic & {
+  // native DOM primitives own text inheritance and receive semantic metrics separately.
+  isDOM?: boolean
   Component?: FunctionComponent<any> & StaticComponentObject<any, any, any, any, any, any>
 
   displayName?: string
@@ -3195,6 +3414,7 @@ export type StyledDynamicEnv = {
   fonts: TamaguiConfig['fonts']
   tokens: TokensParsed
   theme: Themes extends { [key: string]: infer B } ? B : unknown
+  sizing: GenericSizing
   fontFamily?: FontFamilyTokens
   font?: Font
 }
@@ -3233,39 +3453,74 @@ export type VariantDefinitions<
   }
     ? S
     : {},
-  MyProps extends object = Partial<
-    GetVariantProps<
-      Parent,
-      StaticConfig['isText'] extends true
-        ? true
-        : StaticConfig['isInput'] extends true
-          ? true
-          : false
-    >
-  >,
+  MyProps extends object = VariantStyleProps<Parent, StaticConfig>,
   Val = any,
 > = VariantDefinitionFromProps<MyProps, Val> & {
   _isEmpty?: 1
 }
 
+// the color style props only an input takes (runtime stylePropsInput)
+export type InputColorStyleProps = {
+  placeholderTextColor?: ColorStyleProp
+  selectionColor?: ColorStyleProp
+  cursorColor?: ColorStyleProp
+  selectionHandleColor?: ColorStyleProp
+}
+
+export type VariantStyleProps<
+  Parent extends StylableComponent,
+  StaticConfig extends StaticConfigPublic,
+> = Partial<
+  GetVariantProps<
+    Parent,
+    StaticConfig['isText'] extends true
+      ? true
+      : StaticConfig['isInput'] extends true
+        ? true
+        : false
+  >
+> &
+  (GetStaticConfig<Parent, StaticConfig>['isInput'] extends true
+    ? InputColorStyleProps
+    : {})
+
+/**
+ * the exact-key check styled() runs on the variants it infers: a key that is
+ * not a style, shorthand, aria/data attribute, or variant of the component is
+ * `never`, since inference alone never flags extra keys.
+ */
+export type StyleOnlyVariants<Variants, AllowedKeys extends PropertyKey> = {
+  [Name in keyof Variants]: Variants[Name] extends StyledDynamic<any, any>
+    ? Variants[Name]
+    : {
+        [Value in keyof Variants[Name]]: Variants[Name][Value] extends object
+          ? {
+              [Key in keyof Variants[Name][Value]]: Key extends
+                | AllowedKeys
+                | keyof Variants
+                | `aria-${string}`
+                | `data-${string}`
+                ? Variants[Name][Value][Key]
+                : never
+            }
+          : Variants[Name][Value]
+      }
+}
+
 export type StaticStyleInput = string
 
+// variants are styles only: a variant value holds style props and the parent's
+// variants, never a non-style prop such as theme. a component that changes
+// theme with a variant does it one level up, as a theme prop.
 export type GetVariantProps<
   A extends StylableComponent,
   IsText extends boolean | undefined,
 > = A extends {
-  __tama: [
-    infer Props,
-    any,
-    infer NonStyledProps,
-    infer BaseStyles,
-    infer VariantProps,
-    any,
-  ]
+  __tama: [any, any, any, infer BaseStyles, infer VariantProps, any]
 }
-  ? Props extends TamaDefer
-    ? GetFinalProps<NonStyledProps, BaseStyles, VariantProps>
-    : Props
+  ? BaseStyles extends object
+    ? WithThemeAndShorthands<BaseStyles, VariantProps>
+    : {}
   : WithThemeAndShorthands<IsText extends true ? TextStylePropsBase : StackStyleBase>
 
 export type VariantDefinitionFromProps<MyProps, Val> = MyProps extends object
@@ -3319,6 +3574,10 @@ export type SplitStyleProps = {
   canPlatformPseudo?: boolean
   isAnimated: boolean
   isExiting?: boolean
+  // native style stability: previous render's resolved style object, used to
+  // return the same reference when the resolved values haven't changed (avoids
+  // React Native's diffNestedProperty + cloneNodeWithNewProps on every re-render)
+  prevStyle?: Record<string, any> | null
 }
 
 // Presence
@@ -3405,6 +3664,19 @@ type AnimationDriverBase<A extends AnimationConfig = AnimationConfig> = {
   animations: A
   View?: any
   Text?: any
+  useTextMetrics?: (input: {
+    inheritedText?: AnimatedTextChannel | null
+    lineHeight?: NativeTextMetrics['lineHeight']
+  }) => {
+    textChannel: AnimatedTextChannel | null
+  } & (
+    | { style: null }
+    | {
+        style: Record<string, unknown>
+        Text: ComponentType<any>
+        TextInput: ComponentType<any>
+      }
+  )
 }
 
 export type AnimationDriver<A extends AnimationConfig = AnimationConfig> =
@@ -3445,11 +3717,13 @@ type UseStyleListener = (
   // true while a self pseudo (hover/press/focus) is active. lets avoidReRenders drivers know
   // the emitted style is a transient pseudo override that a real re-render must not be allowed
   // to reconcile away, vs the no-pseudo base which renders own again.
-  pseudoActive?: boolean
+  pseudoActive?: boolean,
+  nativeTextMetrics?: NativeTextMetrics
 ) => void
 export type UseStyleEmitter = (cb: UseStyleListener) => void
 
 export type UseAnimationHook = (props: {
+  inheritedText?: AnimatedTextChannel | null
   style: Record<string, any>
   props: Record<string, any>
   styleState?: GetStyleResult | null
@@ -3464,24 +3738,29 @@ export type UseAnimationHook = (props: {
   onTransition?: OnTransition
   delay?: number
 }) => null | {
+  textChannel?: AnimatedTextChannel | null
   style?: unknown
   className?: string
   ref?: any
 }
 
 export type GestureReponderEvent =
-  Exclude<View['props']['onResponderMove'], void> extends (event: infer Event) => void
+  Exclude<ViewProps['onResponderMove'], void> extends (event: infer Event) => void
     ? Event
     : never
 
 export type RulesToInsert = Record<string, StyleObject>
 
 export type GetStyleResult = {
-  style: ViewStyle | null
+  style: { -readonly [K in keyof ViewStyle]: ViewStyle[K] } | null
   classNames: ClassNamesObject
   rulesToInsert: RulesToInsert
-  viewProps: (StackNonStyleProps & StackStyle) & Record<string, any>
+  viewProps: {
+    -readonly [K in keyof (StackNonStyleProps & StackStyle)]: (StackNonStyleProps &
+      StackStyle)[K]
+  } & Record<string, any>
   fontFamily: string | undefined
+  nativeTextMetrics?: NativeTextMetrics
   space?: any // SpaceTokens?
   hasMedia: boolean | Set<string>
   pseudoGroups?: Set<string>
@@ -3560,8 +3839,9 @@ export type StyleProp<T> =
   | T
   | StylePiece
   | RegisteredStyle<T>
-  | RecursiveArray<T | StylePiece | RegisteredStyle<T> | Falsy>
+  | ReadonlyArray<StyleProp<T>>
   | Falsy
+  | void
 
 export type FillInFont<A extends GenericFont, DefaultKeys extends string | number> = {
   family: string