@mpxjs/webpack-plugin 2.10.24-beta.1 → 2.10.24-test.1

package/lib/runtime/components/react/utils.tsx

@@ -1,52 +1,62 @@
 import { useEffect, useCallback, useMemo, useRef, ReactNode, ReactElement, isValidElement, useContext, useState, Dispatch, SetStateAction, createElement, MutableRefObject } from 'react'
 import { LayoutChangeEvent, TextStyle, ImageProps, Image } from 'react-native'
-import { isObject, isFunction, isNumber, hasOwn, diffAndCloneA, error, warn } from '@mpxjs/utils'
+import { isObject, isFunction, isNumber, hasOwn, diffAndCloneA, shallowEqual, error, warn } from '@mpxjs/utils'
 import { VarContext, ScrollViewContext, RouteContext, TextPassThroughContext, TextPassThroughContextValue } from './context'
 import { ExpressionParser, parseFunc, ReplaceSource } from './parser'
 import { initialWindowMetrics } from 'react-native-safe-area-context'
 import type { AnyFunc, ExtendedFunctionComponent } from './types/common'
 import { Gesture } from 'react-native-gesture-handler'
 
-export const TEXT_STYLE_MAP: Record<string, boolean> = {
+// ============================================================
+// declare + constants
+// ============================================================
+
+declare const __mpx_mode__: 'ios' | 'android' | 'harmony'
+
+export const percentRegExp = /^\s*-?\d+(\.\d+)?%\s*$/
+export const svgRegExp = /\.svg(?:[?#].*)?$/i
+export const hiddenStyle = {
+  opacity: 0
+}
+export const isIOS = __mpx_mode__ === 'ios'
+export const isAndroid = __mpx_mode__ === 'android'
+export const isHarmony = __mpx_mode__ === 'harmony'
+export const extendObject = Object.assign
+
+const textStyleMap: Record<string, boolean> = {
   color: true,
   letterSpacing: true,
   lineHeight: true,
   includeFontPadding: true,
   writingDirection: true
 }
-export const PERCENT_REGEX = /^\s*-?\d+(\.\d+)?%\s*$/
-export const URL_REGEX = /^\s*url\(["']?(.*?)["']?\)\s*$/
-export const SVG_REGEXP = /\.svg(?:[?#].*)?$/i
-export const BACKGROUND_STYLE_MAP: Record<string, boolean> = {
+const urlRegExp = /^\s*url\(["']?(.*?)["']?\)\s*$/
+const linearGradientRegExp = /^\s*linear-gradient\(.*\)\s*$/
+const digitStartRegExp = /^\d/
+const varDecRegExp = /^--/
+const varUseRegExp = /var\(/
+const unoVarDecRegExp = /^--un-/
+const unoVarUseRegExp = /var\(--un-/
+const lengthValueRegExp = /^(-?(?:\d+(?:\.\d+)?|\.\d+)(?:rpx|px|%|vw|vh)?|hairlineWidth)$/
+// transform: 'rotateX(45deg) ...' 单段拆出 fn 名与括号内值
+const transformFnRegExp = /([/\w]+)\((.+)\)/
+// boxShadow 子值识别 rpx 单位（仅 rpx 需要换算为 px，其它单位保留原样）
+const rpxSuffixRegExp = /\d+rpx$/
+// font-family / font 简写解析时统一去掉单/双引号
+const quoteCharRegExp = /["']/g
+const defaultBoxSizingStyle = {
+  boxSizing: 'content-box'
+}
+const backgroundStyleMap: Record<string, boolean> = {
   backgroundImage: true,
   backgroundSize: true,
   backgroundRepeat: true,
   backgroundPosition: true
 }
-export const TEXT_PROPS_MAP: Record<string, boolean> = {
+const textPropsMap: Record<string, boolean> = {
   ellipsizeMode: true,
   numberOfLines: true
 }
-export const DEFAULT_FONT_SIZE = 16
-export const HIDDEN_STYLE = {
-  opacity: 0
-}
-export const DEFAULT_BOX_SIZING_STYLE = {
-  boxSizing: 'content-box'
-}
-
-declare const __mpx_mode__: 'ios' | 'android' | 'harmony'
-
-export const isIOS = __mpx_mode__ === 'ios'
-export const isAndroid = __mpx_mode__ === 'android'
-export const isHarmony = __mpx_mode__ === 'harmony'
-
-const varDecRegExp = /^--/
-const varUseRegExp = /var\(/
-const unoVarDecRegExp = /^--un-/
-const unoVarUseRegExp = /var\(--un-/
-const calcUseRegExp = /calc\(/
-const envUseRegExp = /env\(/
 const boxSizingAffectingStyleMap: Record<string, boolean> = {
   padding: true,
   paddingTop: true,
@@ -57,47 +67,238 @@ const boxSizingAffectingStyleMap: Record<string, boolean> = {
   borderTopWidth: true,
   borderRightWidth: true,
   borderBottomWidth: true,
-  borderLeftWidth: true
+  borderLeftWidth: true,
+  border: true,
+  borderTop: true,
+  borderRight: true,
+  borderBottom: true,
+  borderLeft: true
+}
+const runtimeAbbreviationMap: Record<string, string[]> = {
+  margin: ['marginTop', 'marginRight', 'marginBottom', 'marginLeft'],
+  padding: ['paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft'],
+  borderRadius: ['borderTopLeftRadius', 'borderTopRightRadius', 'borderBottomRightRadius', 'borderBottomLeftRadius'],
+  borderWidth: ['borderTopWidth', 'borderRightWidth', 'borderBottomWidth', 'borderLeftWidth'],
+  borderColor: ['borderTopColor', 'borderRightColor', 'borderBottomColor', 'borderLeftColor'],
+  border: ['borderWidth', 'borderStyle', 'borderColor'],
+  // RN 不支持单边 border-*-style，统一展开到 borderStyle
+  // 实测 RN 上当 borderStyle 不为 solid 时单边 border-*-color 不生效，
+  // 这里把单边 color 也统一展开到 borderColor 规避（width 不能这样做，否则会覆盖其它三边）
+  borderTop: ['borderTopWidth', 'borderStyle', 'borderColor'],
+  borderRight: ['borderRightWidth', 'borderStyle', 'borderColor'],
+  borderBottom: ['borderBottomWidth', 'borderStyle', 'borderColor'],
+  borderLeft: ['borderLeftWidth', 'borderStyle', 'borderColor'],
+  flexFlow: ['flexDirection', 'flexWrap'],
+  textShadow: ['textShadowOffset.width', 'textShadowOffset.height', 'textShadowRadius', 'textShadowColor'],
+  textDecoration: ['textDecorationLine', 'textDecorationStyle', 'textDecorationColor'],
+  // gap：CSS 2 槽位（row-gap / column-gap），单值复制行列。RN 原生支持但要求 number。
+  // 单值串在 __getStyle 的 transformStyleObj / 编译期 formatValue 已被 __formatValue 换算为 number；
+  // 真正以字符串形态进 transformShorthand 的是多值串（如 '10px 20px'）—— unitRegExp 不命中、原样透传。
+  // 因此进入 runtimeForceExpandCompositeMap，避免「单值透传」捷径放过这类多值串残留。
+  // 百分比（`gap: 50%` / `gap: 10px 50%`）由 transformShorthand 写回阶段就地 resolvePercent 落成 number
+  gap: ['rowGap', 'columnGap'],
+  // inset：4 槽位等价 margin 四值语法；RN inset 长属性非稳定，单值也必须展开到 top/right/bottom/left
+  inset: ['top', 'right', 'bottom', 'left'],
+  // outline: <outline-width> || <outline-style> || <outline-color>，顺序不敏感
+  outline: ['outlineWidth', 'outlineStyle', 'outlineColor']
+}
+const runtimeCompositeStyleMap: Record<string, boolean> = {
+  margin: true,
+  padding: true,
+  borderRadius: true,
+  borderWidth: true,
+  borderColor: true,
+  gap: true,
+  inset: true
+}
+// 即使单值也必须展开（不走「单值透传」捷径）：
+// - inset：RN inset 长属性不稳定，单值透传会留下不可靠的 inset key
+// - gap：RN gap / rowGap / columnGap 严格要求 number；单值串虽已在 __getStyle 阶段被 __formatValue 换算，
+//   但多值串（如 '10px 20px'）会原样透传到这里，需展开后逐 token 再过 __formatValue 才能落成 number；
+//   `%` 在写回阶段由 transformShorthand 调 resolvePercent 落成 number（rowGap 基 parentHeight、columnGap 基 parentWidth）
+const runtimeForceExpandCompositeMap: Record<string, boolean> = {
+  inset: true,
+  gap: true
+}
+const runtimeUnorderedAbbreviationMap: Record<string, boolean> = {
+  border: true,
+  borderTop: true,
+  borderRight: true,
+  borderBottom: true,
+  borderLeft: true,
+  flexFlow: true,
+  textShadow: true,
+  textDecoration: true,
+  // outline 与 border 简写共享同一套缺省值处理
+  outline: true
+}
+const runtimeBorderLikeShorthandMap: Record<string, boolean> = {
+  border: true,
+  borderTop: true,
+  borderRight: true,
+  borderBottom: true,
+  borderLeft: true,
+  outline: true
+}
+// CSS border-width: medium 的实测值（各主流浏览器一致取 3px）
+// 与编译期 wx/index.js 同名常量保持一致；调整需两侧一起改
+const BORDER_MEDIUM_WIDTH = 3
+// 运行时简写槽位缺省值表（与编译期 ShorthandDefaultMap 镜像，仅 CSS quote 形式不同）
+// 值即槽位缺省时追加的补齐值；borderColor / textShadowRadius 因 RN 有内置缺省值不补，不进此表
+// none 清除语义统一保留到 useTransformStyle 末尾处理
+const runtimeShorthandDefaultMap: Record<string, Record<string, any>> = {
+  border: { borderWidth: BORDER_MEDIUM_WIDTH, borderStyle: 'none' },
+  borderTop: { borderTopWidth: BORDER_MEDIUM_WIDTH, borderStyle: 'none' },
+  borderRight: { borderRightWidth: BORDER_MEDIUM_WIDTH, borderStyle: 'none' },
+  borderBottom: { borderBottomWidth: BORDER_MEDIUM_WIDTH, borderStyle: 'none' },
+  borderLeft: { borderLeftWidth: BORDER_MEDIUM_WIDTH, borderStyle: 'none' },
+  // outline 与 border 缺省值完全对齐：缺 width → BORDER_MEDIUM_WIDTH；
+  // 缺 style → outlineStyle: none，末尾统一转换为 outlineWidth: 0
+  outline: { outlineWidth: BORDER_MEDIUM_WIDTH, outlineStyle: 'none' },
+  textShadow: { textShadowColor: '#000' }
+  // textDecoration / flexFlow 暂不配置，与 RN 默认一致
 }
 
+const borderStyleMap: Record<string, boolean> = {
+  // RN 实测仅支持 solid/dotted/dashed；none 作为 CSS 合法值保留到末尾统一转换为 borderWidth: 0
+  solid: true,
+  dotted: true,
+  dashed: true,
+  none: true
+}
+const textDecorationLineMap: Record<string, boolean> = {
+  none: true,
+  underline: true,
+  'line-through': true
+}
+const textDecorationStyleMap: Record<string, boolean> = {
+  solid: true,
+  double: true,
+  dotted: true,
+  dashed: true
+}
+// font 简写 <font-weight> 槽位允许的关键字 / 数值（CSS 子集，与 RN 支持一致）
+const fontWeightMap: Record<string, boolean> = {
+  bold: true,
+  normal: true,
+  100: true,
+  200: true,
+  300: true,
+  400: true,
+  500: true,
+  600: true,
+  700: true,
+  800: true,
+  900: true
+}
+const flexDirectionMap: Record<string, boolean> = {
+  row: true,
+  'row-reverse': true,
+  column: true,
+  'column-reverse': true
+}
+const flexWrapMap: Record<string, boolean> = {
+  wrap: true,
+  nowrap: true,
+  'wrap-reverse': true
+}
 const safeAreaInsetMap: Record<string, 'top' | 'right' | 'bottom' | 'left'> = {
   'safe-area-inset-top': 'top',
   'safe-area-inset-right': 'right',
   'safe-area-inset-bottom': 'bottom',
   'safe-area-inset-left': 'left'
 }
+const radiusPercentRule: Record<string, 'height' | 'width'> = {
+  borderTopLeftRadius: 'width',
+  borderBottomLeftRadius: 'width',
+  borderBottomRightRadius: 'width',
+  borderTopRightRadius: 'width',
+  borderRadius: 'width'
+}
+const selfPercentRule: Record<string, 'height' | 'width'> = extendObject({
+  translateX: 'width',
+  translateY: 'height'
+}, radiusPercentRule)
+const parentHeightPercentRule: Record<string, boolean> = {
+  height: true,
+  minHeight: true,
+  maxHeight: true,
+  top: true,
+  bottom: true,
+  // row-gap 百分比按 CSS 规范基于容器内容区高度；columnGap 不入此表，落默认 parentWidth 分支
+  rowGap: true
+}
+const bgRepeatMap: Record<string, boolean> = {
+  repeat: true,
+  'repeat-x': true,
+  'repeat-y': true,
+  'no-repeat': true
+}
+const bgPositionMap: Record<string, boolean> = {
+  left: true,
+  right: true,
+  top: true,
+  bottom: true,
+  center: true
+}
 
-export const extendObject = Object.assign
+// ============================================================
+// interfaces / types
+// ============================================================
 
-export function getDefaultAllowFontScaling (): boolean {
-  return global.__mpx?.config?.rnConfig?.allowFontScaling ?? false
+interface PercentConfig {
+  fontSize?: number | string
+  width?: number
+  height?: number
+  parentFontSize?: number
+  parentWidth?: number
+  parentHeight?: number
 }
 
-export function transformBoxSizing (style: Record<string, any> = {}, hasBoxSizingAffectingStyle = false) {
-  if (hasBoxSizingAffectingStyle && style.boxSizing === undefined) {
-    style.boxSizing = global.__mpx?.config?.rnConfig?.defaultBoxSizing ?? DEFAULT_BOX_SIZING_STYLE.boxSizing
-  }
-  return style
+interface TransformStyleConfig {
+  enableVar?: boolean
+  parentFontSize?: number
+  parentWidth?: number
+  parentHeight?: number
+  transformRadiusPercent?: boolean
+  defaultStyle?: Record<string, any>
 }
 
-export function isBoxSizingAffectingStyle (key: string) {
-  return hasOwn(boxSizingAffectingStyleMap, key)
+export interface VisitorArg {
+  target: Record<string, any>
+  key: string
+  value: any
+  keyPath: Array<string>
 }
 
-function isTextStyle (key: string) {
-  return hasOwn(TEXT_STYLE_MAP, key) || key.startsWith('font') || key.startsWith('text')
+interface LayoutConfig {
+  props: Record<string, any>
+  hasSelfPercent: boolean
+  setWidth?: Dispatch<SetStateAction<number>>
+  setHeight?: Dispatch<SetStateAction<number>>
+  onLayout?: (event: LayoutChangeEvent) => void
+  nodeRef: React.RefObject<any>
 }
 
-function getSafeAreaInset (name: string, navigation: Record<string, any> | undefined) {
-  const insets = extendObject({}, initialWindowMetrics?.insets, navigation?.insets)
-  return insets[safeAreaInsetMap[name]]
+export interface WrapChildrenConfig {
+  hasVarDec: boolean
+  varContext?: Record<string, any>
+  textPassThrough?: TextPassThroughContextValue | null
 }
 
-export function useNavigation (): Record<string, any> | undefined {
-  const { navigation } = useContext(RouteContext) || {}
-  return navigation
+export interface TextPassThroughValueOptions {
+  enableTextPassThrough?: boolean
+}
+
+export interface GestureHandler {
+  nodeRefs?: Array<{ getNodeInstance: () => { nodeRef: unknown } }>
+  current?: unknown
 }
 
+// ============================================================
+// generic utility functions
+// ============================================================
+
 export function omit<T, K extends string> (obj: T, fields: K[]): Omit<T, K> {
   const shallowCopy: any = extendObject({}, obj)
   for (let i = 0; i < fields.length; i += 1) {
@@ -107,31 +308,9 @@ export function omit<T, K extends string> (obj: T, fields: K[]): Omit<T, K> {
   return shallowCopy
 }
 
-/**
- * 用法等同于 useEffect，但是会忽略首次执行，只在依赖更新时执行
- */
-export const useUpdateEffect = (effect: any, deps: any) => {
-  const isMounted = useRef(false)
-
-  // for react-refresh
-  useEffect(() => {
-    return () => {
-      isMounted.current = false
-    }
-  }, [])
-
-  useEffect(() => {
-    if (!isMounted.current) {
-      isMounted.current = true
-    } else {
-      return effect()
-    }
-  }, deps)
-}
-
 export const parseUrl = (cssUrl = '') => {
   if (!cssUrl) return
-  const match = cssUrl.match(URL_REGEX)
+  const match = cssUrl.match(urlRegExp)
   return match?.[1]
 }
 
@@ -143,6 +322,10 @@ export const getRestProps = (transferProps: any = {}, originProps: any = {}, del
   )
 }
 
+export function getDefaultAllowFontScaling (): boolean {
+  return global.__mpx?.config?.rnConfig?.allowFontScaling ?? false
+}
+
 export function isText (ele: ReactNode): ele is ReactElement {
   if (isValidElement(ele)) {
     const displayName = (ele.type as ExtendedFunctionComponent)?.displayName
@@ -158,19 +341,76 @@ export function isStringChildren (children: ReactNode) {
   return children.every((child) => typeof child === 'string')
 }
 
-type GroupData<T> = Record<string, Partial<T>>
+// 多value解析
+export function parseValues (str: string, char = ' ') {
+  let stack = 0
+  let temp = ''
+  const result = []
+  for (let i = 0; i < str.length; i++) {
+    if (str[i] === '(') {
+      stack++
+    } else if (str[i] === ')') {
+      stack--
+    }
+    // 非括号内 或者 非分隔字符且非空
+    if (stack !== 0 || str[i] !== char) {
+      temp += str[i]
+    }
+    if ((stack === 0 && str[i] === char) || i === str.length - 1) {
+      result.push(temp.trim())
+      temp = ''
+    }
+  }
+  return result
+}
 
-export function groupBy<T extends Record<string, any>> (
-  obj: T,
-  callback: (key: string, val: T[keyof T]) => string,
-  group: GroupData<T> = {}
-): GroupData<T> {
-  Object.entries(obj).forEach(([key, val]) => {
-    const groupKey = callback(key, val)
-    group[groupKey] = group[groupKey] || {}
-    group[groupKey][key as keyof T] = val
-  })
-  return group
+export const debounce = <T extends AnyFunc> (
+  func: T,
+  delay: number
+): ((...args: Parameters<T>) => void) & { clear: () => void } => {
+  let timer: any
+  const wrapper = (...args: ReadonlyArray<any>) => {
+    timer && clearTimeout(timer)
+    timer = setTimeout(() => {
+      func(...args)
+    }, delay)
+  }
+  wrapper.clear = () => {
+    timer && clearTimeout(timer)
+    timer = null
+  }
+  return wrapper
+}
+
+// ============================================================
+// style classification & splitting
+// ============================================================
+
+function isTextStyle (key: string) {
+  return hasOwn(textStyleMap, key) || key.startsWith('font') || key.startsWith('text')
+}
+
+function isColorValue (token: string): boolean {
+  if (token.startsWith('#') || token.startsWith('rgb(') || token.startsWith('rgba(') || token.startsWith('hsl(') || token.startsWith('hsla(')) return true
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  return hasOwn(require('./namedColorSet').default, token.toLowerCase())
+}
+
+function isLengthValue (token: string): boolean {
+  return lengthValueRegExp.test(token)
+}
+
+export function isBoxSizingAffectingStyle (key: string) {
+  return hasOwn(boxSizingAffectingStyleMap, key)
+}
+
+// 仅在调用侧已确认存在 padding / border 等 box-sizing 影响项时调用：
+// 给样式补默认 boxSizing（用户未显式设置时）。是否需要进入由调用侧决定，
+// useTransformStyle / mpx-simple-view / mpx-simple-text 都按 hasBoxSizingAffectingStyle 短路。
+export function transformBoxSizing (style: Record<string, any> = {}) {
+  if (style.boxSizing === undefined) {
+    style.boxSizing = global.__mpx?.config?.rnConfig?.defaultBoxSizing ?? defaultBoxSizingStyle.boxSizing
+  }
 }
 
 export function splitStyle<T extends Record<string, any>> (styleObj: T, sideEffect?: (key: string, val: T[keyof T]) => void): {
@@ -178,52 +418,157 @@ export function splitStyle<T extends Record<string, any>> (styleObj: T, sideEffe
   backgroundStyle?: Partial<T>
   innerStyle?: Partial<T>
 } {
-  return groupBy(styleObj, (key, val) => {
+  const keys = Object.keys(styleObj)
+  let textStyle: Partial<T> | undefined
+  let backgroundStyle: Partial<T> | undefined
+  let innerStyle: Partial<T> | undefined
+  let firstSpecialIdx = -1
+
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]
+    const val = styleObj[key]
     sideEffect && sideEffect(key, val)
+
     if (isTextStyle(key)) {
-      return 'textStyle'
-    } else if (hasOwn(BACKGROUND_STYLE_MAP, key)) {
-      return 'backgroundStyle'
-    } else {
-      return 'innerStyle'
+      if (firstSpecialIdx < 0) firstSpecialIdx = i
+      textStyle = textStyle || {}
+      textStyle[key as keyof T] = val
+    } else if (hasOwn(backgroundStyleMap, key)) {
+      if (firstSpecialIdx < 0) firstSpecialIdx = i
+      backgroundStyle = backgroundStyle || {}
+      backgroundStyle[key as keyof T] = val
+    } else if (firstSpecialIdx >= 0) {
+      innerStyle = innerStyle || {}
+      innerStyle[key as keyof T] = val
     }
-  })
+  }
+
+  if (firstSpecialIdx < 0) return { innerStyle: styleObj }
+
+  if (firstSpecialIdx > 0) {
+    innerStyle = innerStyle || {}
+    for (let i = 0; i < firstSpecialIdx; i++) {
+      const key = keys[i]
+      innerStyle[key as keyof T] = styleObj[key]
+    }
+  }
+  return { textStyle, backgroundStyle, innerStyle }
 }
-const radiusPercentRule: Record<string, 'height' | 'width'> = {
-  borderTopLeftRadius: 'width',
-  borderBottomLeftRadius: 'width',
-  borderBottomRightRadius: 'width',
-  borderTopRightRadius: 'width',
-  borderRadius: 'width'
+
+export function splitProps<T extends Record<string, any>> (props: T): {
+  textProps?: Partial<T>
+  innerProps?: Partial<T>
+} {
+  const keys = Object.keys(props)
+  let textProps: Partial<T> | undefined
+  let innerProps: Partial<T> | undefined
+  let firstTextIdx = -1
+
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]
+    if (hasOwn(textPropsMap, key)) {
+      if (firstTextIdx < 0) firstTextIdx = i
+      textProps = textProps || {}
+      textProps[key as keyof T] = props[key]
+    } else if (firstTextIdx >= 0) {
+      innerProps = innerProps || {}
+      innerProps[key as keyof T] = props[key]
+    }
+  }
+
+  if (firstTextIdx < 0) return { innerProps: props }
+
+  if (firstTextIdx > 0) {
+    innerProps = innerProps || {}
+    for (let i = 0; i < firstTextIdx; i++) {
+      const key = keys[i]
+      innerProps[key as keyof T] = props[key]
+    }
+  }
+  return { textProps, innerProps }
 }
-const selfPercentRule: Record<string, 'height' | 'width'> = extendObject({
-  translateX: 'width',
-  translateY: 'height'
-}, radiusPercentRule)
 
-const parentHeightPercentRule: Record<string, boolean> = {
-  height: true,
-  minHeight: true,
-  maxHeight: true,
-  top: true,
-  bottom: true
+export function pickStyle (styleObj: Record<string, any> = {}, pickedKeys: Array<string>, callback?: (key: string, val: number | string) => number | string) {
+  return pickedKeys.reduce<Record<string, any>>((acc, key) => {
+    if (key in styleObj) {
+      acc[key] = callback ? callback(key, styleObj[key]) : styleObj[key]
+    }
+    return acc
+  }, {})
 }
 
-interface PercentConfig {
-  fontSize?: number | string
-  width?: number
-  height?: number
-  parentFontSize?: number
-  parentWidth?: number
-  parentHeight?: number
+// ============================================================
+// style transform pipeline
+// ============================================================
+
+// --- var ---
+
+function resolveVar (input: string, varContext: Record<string, any>) {
+  const parsed = parseFunc(input, 'var')
+  const replaced = new ReplaceSource(input)
+
+  for (const { start, end, args } of parsed) {
+    // NOTE:
+    // - CSS var() fallback 允许包含空格、逗号等字符（如 font-family 的 fallback）
+    // - parseFunc 会按逗号分割 args，因此这里把 args[1..] 重新 join 回 fallback
+    const varName = args[0]
+    const fallback: string | undefined = args.length > 1 ? args.slice(1).join(',').trim() : undefined
+
+    // 先处理 varValue
+    let varValue = hasOwn(varContext, varName) ? varContext[varName] : undefined
+    if (varValue !== undefined) {
+      varValue = varUseRegExp.test(varValue) ? resolveVar(varValue, varContext) : global.__formatValue(varValue)
+    }
+    // 再处理 fallback
+    if (varValue === undefined && fallback !== undefined) {
+      varValue = varUseRegExp.test(fallback) ? resolveVar(fallback, varContext) : global.__formatValue(fallback)
+    }
+    if (varValue === undefined) return
+    replaced.replace(start, end - 1, varValue)
+  }
+
+  return global.__formatValue(replaced.source())
 }
 
-interface PositionMeta {
-  hasPositionFixed: boolean
+function transformVar (styleObj: Record<string, any>, varKeyPaths: Array<Array<string>>, varContext: Record<string, any>, visitOther: (arg: VisitorArg) => void) {
+  varKeyPaths.forEach((varKeyPath) => {
+    setStyle(styleObj, varKeyPath, ({ target, key, value }) => {
+      const resolved = resolveVar(value, varContext)
+      if (resolved === undefined) {
+        delete target[key]
+        error(`Can not resolve css var at ${varKeyPath.join('.')}:${value}.`)
+        return
+      }
+      target[key] = resolved
+      visitOther({ target, key, value: target[key], keyPath: varKeyPath })
+    })
+  })
+}
+
+// --- env ---
+
+function transformEnv (styleObj: Record<string, any>, envKeyPaths: Array<Array<string>>, navigation: Record<string, any> | undefined) {
+  const insets = extendObject({}, initialWindowMetrics?.insets, navigation?.insets)
+  envKeyPaths.forEach((envKeyPath) => {
+    setStyle(styleObj, envKeyPath, ({ target, key, value }) => {
+      const parsed = parseFunc(value, 'env')
+      const replaced = new ReplaceSource(value)
+      parsed.forEach(({ start, end, args }) => {
+        const name = args[0]
+        const fallback = args[1] || ''
+        const inset = insets[safeAreaInsetMap[name]]
+        const next = '' + (inset ?? global.__formatValue(fallback))
+        replaced.replace(start, end - 1, next)
+      })
+      target[key] = global.__formatValue(replaced.source())
+    })
+  })
 }
 
+// --- percent ---
+
 function resolvePercent (value: string | number | undefined, key: string, percentConfig: PercentConfig): string | number | undefined {
-  if (!(typeof value === 'string' && PERCENT_REGEX.test(value))) return value
+  if (!(typeof value === 'string' && percentRegExp.test(value))) return value
   let base
   let reason
   if (key === 'fontSize') {
@@ -250,71 +595,15 @@ function resolvePercent (value: string | number | undefined, key: string, percen
   }
 }
 
-function transformPercent (styleObj: Record<string, any>, percentKeyPaths: Array<Array<string>>, percentConfig: PercentConfig) {
-  percentKeyPaths.forEach((percentKeyPath) => {
-    setStyle(styleObj, percentKeyPath, ({ target, key, value }) => {
-      target[key] = resolvePercent(value, key, percentConfig)
-    })
-  })
-}
-
-function resolveVar (input: string, varContext: Record<string, any>) {
-  const parsed = parseFunc(input, 'var')
-  const replaced = new ReplaceSource(input)
-
-  for (const { start, end, args } of parsed) {
-    // NOTE:
-    // - CSS var() fallback 允许包含空格、逗号等字符（如 font-family 的 fallback）
-    // - parseFunc 会按逗号分割 args，因此这里把 args[1..] 重新 join 回 fallback
-    const varName = args[0]
-    const fallback: string | undefined = args.length > 1 ? args.slice(1).join(',').trim() : undefined
-
-    // 先处理 varValue
-    let varValue = hasOwn(varContext, varName) ? varContext[varName] : undefined
-    if (varValue !== undefined) {
-      varValue = varUseRegExp.test(varValue) ? resolveVar(varValue, varContext) : global.__formatValue(varValue)
-    }
-    // 再处理 fallback
-    if (varValue === undefined && fallback !== undefined) {
-      varValue = varUseRegExp.test(fallback) ? resolveVar(fallback, varContext) : global.__formatValue(fallback)
-    }
-    if (varValue === undefined) return
-    replaced.replace(start, end - 1, varValue)
-  }
-
-  return global.__formatValue(replaced.source())
-}
-
-function transformVar (styleObj: Record<string, any>, varKeyPaths: Array<Array<string>>, varContext: Record<string, any>, visitOther: (arg: VisitorArg) => void) {
-  varKeyPaths.forEach((varKeyPath) => {
-    setStyle(styleObj, varKeyPath, ({ target, key, value }) => {
-      const resolved = resolveVar(value, varContext)
-      if (resolved === undefined) {
-        delete target[key]
-        error(`Can not resolve css var at ${varKeyPath.join('.')}:${value}.`)
-        return
-      }
-      target[key] = resolved
-      visitOther({ target, key, value: target[key], keyPath: varKeyPath })
+function transformPercent (styleObj: Record<string, any>, percentKeyPaths: Array<Array<string>>, percentConfig: PercentConfig) {
+  percentKeyPaths.forEach((percentKeyPath) => {
+    setStyle(styleObj, percentKeyPath, ({ target, key, value }) => {
+      target[key] = resolvePercent(value, key, percentConfig)
     })
   })
 }
 
-function transformEnv (styleObj: Record<string, any>, envKeyPaths: Array<Array<string>>, navigation: Record<string, any> | undefined) {
-  envKeyPaths.forEach((envKeyPath) => {
-    setStyle(styleObj, envKeyPath, ({ target, key, value }) => {
-      const parsed = parseFunc(value, 'env')
-      const replaced = new ReplaceSource(value)
-      parsed.forEach(({ start, end, args }) => {
-        const name = args[0]
-        const fallback = args[1] || ''
-        const value = '' + (getSafeAreaInset(name, navigation) ?? global.__formatValue(fallback))
-        replaced.replace(start, end - 1, value)
-      })
-      target[key] = global.__formatValue(replaced.source())
-    })
-  })
-}
+// --- calc ---
 
 function transformCalc (styleObj: Record<string, any>, calcKeyPaths: Array<Array<string>>, formatter: (value: string, key: string) => number) {
   calcKeyPaths.forEach((calcKeyPath) => {
@@ -337,6 +626,8 @@ function transformCalc (styleObj: Record<string, any>, calcKeyPaths: Array<Array
   })
 }
 
+// --- misc ---
+
 function transformStringify (styleObj: Record<string, any>) {
   if (isNumber(styleObj.fontWeight)) {
     styleObj.fontWeight = '' + styleObj.fontWeight
@@ -347,34 +638,8 @@ function transformStringify (styleObj: Record<string, any>) {
   }
 }
 
-function transformPosition (styleObj: Record<string, any>, meta: PositionMeta) {
-  if (styleObj.position === 'fixed') {
-    styleObj.position = 'absolute'
-    meta.hasPositionFixed = true
-  }
-}
-// 多value解析
-export function parseValues (str: string, char = ' ') {
-  let stack = 0
-  let temp = ''
-  const result = []
-  for (let i = 0; i < str.length; i++) {
-    if (str[i] === '(') {
-      stack++
-    } else if (str[i] === ')') {
-      stack--
-    }
-    // 非括号内 或者 非分隔字符且非空
-    if (stack !== 0 || str[i] !== char) {
-      temp += str[i]
-    }
-    if ((stack === 0 && str[i] === char) || i === str.length - 1) {
-      result.push(temp.trim())
-      temp = ''
-    }
-  }
-  return result
-}
+// --- transform / shadow ---
+
 // parse string transform, eg: transform: 'rotateX(45deg) rotateZ(0.785398rad)'
 function parseTransform (transformStr: string) {
   const values = parseValues(transformStr)
@@ -382,55 +647,108 @@ function parseTransform (transformStr: string) {
   // Todo 1 transform 排序不一致时，transform动画会闪烁，故这里同样的排序输出 transform
   // values.sort()
   const transform: { [propName: string]: string | number | number[] }[] = []
+  // 与编译期 wx/index.js 同 transform formatter 口径对齐：
+  // 「整条 transform 声明」绝不会因单个子项失败而丢弃，被丢的只有那一个子项，其余 transform 项仍输出。
+  // 因此本 forEach 内所有「丢这一项」的提示一律用 warn（编译期同名分支注释：「仅丢这一 transform 项，其它项仍输出，按规范使用 warn」）。
   values.forEach(item => {
-    const match = item.match(/([/\w]+)\((.+)\)/)
-    if (match && match.length >= 3) {
-      let key = match[1]
-      const val = match[2]
-      switch (key) {
-        case 'translateX':
-        case 'translateY':
-        case 'scaleX':
-        case 'scaleY':
-        case 'rotateX':
-        case 'rotateY':
-        case 'rotateZ':
-        case 'rotate':
-        case 'skewX':
-        case 'skewY':
-        case 'perspective':
-          // rotate 处理成 rotateZ
-          key = key === 'rotate' ? 'rotateZ' : key
-          // 单个值处理
-          transform.push({ [key]: global.__formatValue(val) })
-          break
-        case 'matrix':
-          transform.push({ [key]: parseValues(val, ',').map(val => +val) })
-          break
-        case 'translate':
-        case 'scale':
-        case 'skew':
-        case 'translate3d': // x y 支持 z不支持
-        case 'scale3d': // x y 支持 z不支持
-        {
-          // 2 个以上的值处理
-          key = key.replace('3d', '')
-          const vals = parseValues(val, ',').splice(0, 3)
-          // scale(.5) === scaleX(.5) scaleY(.5)
-          if (vals.length === 1 && key === 'scale') {
-            vals.push(vals[0])
+    const match = item.match(transformFnRegExp)
+    if (!match || match.length < 3) {
+      warn(`Transform value [${item}] is not a valid fn(value) form, dropped.`)
+      return
+    }
+    let key = match[1]
+    const val = match[2]
+    switch (key) {
+      case 'rotateX':
+      case 'rotateY':
+      case 'rotateZ':
+      case 'rotate':
+      case 'skewX':
+      case 'skewY':
+        key = key === 'rotate' ? 'rotateZ' : key
+        transform.push({ [key]: val })
+        break
+      case 'translateX':
+      case 'translateY':
+      case 'scaleX':
+      case 'scaleY':
+      case 'perspective':
+        transform.push({ [key]: global.__formatValue(val) })
+        break
+      case 'matrix': {
+        // parseValues 内部已 trim
+        const matrixValues = parseValues(val, ',').map(v => +v)
+        if (matrixValues.length === 6) {
+          const [a, b, c, d, tx, ty] = matrixValues
+          transform.push({ matrix: [a, b, 0, 0, c, d, 0, 0, 0, 0, 1, 0, tx, ty, 0, 1] })
+        } else {
+          warn(`Transform matrix only supports 6 values in React Native, got ${matrixValues.length}`)
+        }
+        break
+      }
+      case 'matrix3d': {
+        // parseValues 内部已 trim
+        const matrixValues = parseValues(val, ',').map(v => +v)
+        if (matrixValues.length === 16) {
+          transform.push({ matrix: matrixValues })
+        } else {
+          warn(`Transform matrix only supports 16 values in React Native, got ${matrixValues.length}`)
+        }
+        break
+      }
+      case 'translate':
+      case 'scale':
+      case 'skew':
+      case 'translate3d': // x y 支持 z不支持
+      case 'scale3d': // x y 支持 z不支持
+      {
+        // 2 个以上的值处理
+        key = key.replace('3d', '')
+        const vals = parseValues(val, ',').splice(0, 3)
+        // scale(.5) === scaleX(.5) scaleY(.5)
+        if (vals.length === 1 && key === 'scale') {
+          vals.push(vals[0])
+        }
+        const xyz = ['X', 'Y', 'Z']
+        vals.forEach((v, index) => {
+          if (key !== 'rotate' && index > 1) {
+            warn(`Transform [${key}Z] is not supported in React Native, dropped.`)
+            return
           }
-          const xyz = ['X', 'Y', 'Z']
-          transform.push(...vals.map((v, index) => {
-            return { [`${key}${xyz[index] || ''}`]: global.__formatValue(v.trim()) }
-          }))
+          // parseValues 内部已 trim
+          transform.push({ [`${key}${xyz[index] || ''}`]: global.__formatValue(v) })
+        })
+        break
+      }
+      case 'rotate3d': {
+        const parts = parseValues(val, ',')
+        if (parts.length !== 4) {
+          warn(`Transform rotate3d only supports 4 values, got ${parts.length}`)
           break
         }
+        // parseValues 内部已 trim
+        const x = +parts[0]
+        const y = +parts[1]
+        const z = +parts[2]
+        const angle = parts[3]
+        if (x && !y && !z) transform.push({ rotateX: angle })
+        else if (!x && y && !z) transform.push({ rotateY: angle })
+        else if (!x && !y && z) transform.push({ rotateZ: angle })
+        else warn(`Transform rotate3d(${val}) only supports single-axis vector (1,0,0) / (0,1,0) / (0,0,1) in React Native, dropped.`)
+        break
       }
+      case 'translateZ':
+      case 'scaleZ':
+        // RN 不支持 Z 轴 translate/scale，丢该子项；编译期同分支用 warn（unsupportedPropError isError=false）
+        warn(`Transform [${key}] is not supported in React Native, dropped.`)
+        break
+      default:
+        warn(`Transform fn [${key}] is not supported in React Native, dropped.`)
     }
   })
   return transform
 }
+
 // format style transform
 function transformTransform (style: Record<string, any>) {
   if (!style.transform || Array.isArray(style.transform)) return
@@ -440,20 +758,485 @@ function transformTransform (style: Record<string, any>) {
 function transformBoxShadow (styleObj: Record<string, any>) {
   if (!styleObj.boxShadow) return
   styleObj.boxShadow = parseValues(styleObj.boxShadow).reduce((res, i, idx) => {
-    return `${res}${idx === 0 ? '' : ' '}${global.__formatValue(i)}`
+    let formatted: string | number
+    // 需要保留 px 关键字，这里仅处理 rpx 转 px
+    if (rpxSuffixRegExp.test(i)) {
+      formatted = global.__formatValue(i) + 'px'
+    } else {
+      formatted = i
+    }
+    return `${res}${idx === 0 ? '' : ' '}${formatted}`
   }, '')
 }
 
-interface TransformStyleConfig {
-  enableVar?: boolean
-  externalVarContext?: Record<string, any>
-  parentFontSize?: number
-  parentWidth?: number
-  parentHeight?: number
-  transformRadiusPercent?: boolean
+// --- shorthand ---
+
+function expandCompositeValues (values: string[]): string[] {
+  const v = values.slice(0, 4)
+  switch (v.length) {
+    case 1:
+      return [v[0], v[0], v[0], v[0]]
+    case 2:
+      return [v[0], v[1], v[0], v[1]]
+    case 3:
+      return [v[0], v[1], v[2], v[1]]
+    default:
+      return v
+  }
+}
+
+function expandAbbreviation (values: string[], props: string[]): Array<[string, any]> {
+  const result: Array<[string, any]> = []
+  for (let i = 0; i < props.length && i < values.length; i++) {
+    pushExpandedPair(result, props[i], global.__formatValue(values[i]))
+  }
+  return result
+}
+
+function pushExpandedPair (result: Array<[string, any]>, prop: string, value: any) {
+  if (prop.includes('.')) {
+    const [main, sub] = prop.split('.')
+    let entry = result.find(item => item[0] === main)
+    if (!entry) {
+      entry = [main, {}]
+      result.push(entry)
+    }
+    entry[1][sub] = value
+  } else {
+    result.push([prop, value])
+  }
+}
+
+function getUnorderedShorthandProp (key: string, token: string, used: Record<string, boolean>): string | undefined {
+  const props = runtimeAbbreviationMap[key]
+  for (const prop of props) {
+    if (used[prop]) continue
+    if (matchRuntimeShorthandProp(prop, token)) return prop
+  }
+}
+
+function matchRuntimeShorthandProp (prop: string, token: string): boolean {
+  if (prop === 'textShadowOffset.width' || prop === 'textShadowOffset.height' || prop === 'textShadowRadius') return isLengthValue(token)
+  if (prop === 'textShadowColor') return isColorValue(token)
+  if (prop.endsWith('Width')) return isLengthValue(token)
+  if (prop === 'textDecorationStyle') return hasOwn(textDecorationStyleMap, token)
+  if (prop.endsWith('Style')) return hasOwn(borderStyleMap, token)
+  if (prop.endsWith('Color')) return isColorValue(token)
+  if (prop === 'flexDirection') return hasOwn(flexDirectionMap, token)
+  if (prop === 'flexWrap') return hasOwn(flexWrapMap, token)
+  return false
+}
+
+// 通用补齐：扫描完所有 token 后，将 runtimeShorthandDefaultMap 中未被占用（不在 used）的槽位追加到 pairs
+// used 即主循环的占用记录，key 是完整目标 prop 名（含 textShadowOffset.width 这类 dot 路径）
+function applyRuntimeShorthandDefaults (key: string, pairs: Array<[string, any]>, used: Record<string, boolean>): Array<[string, any]> {
+  const defaults = runtimeShorthandDefaultMap[key]
+  if (!defaults) return pairs
+  for (const target in defaults) {
+    if (!used[target]) {
+      pushExpandedPair(pairs, target, defaults[target])
+    }
+  }
+  return pairs
+}
+
+function expandUnorderedAbbreviation (key: string, values: string[]): Array<[string, any]> {
+  const result: Array<[string, any]> = []
+  const used: Record<string, boolean> = {}
+  let hasTextDecorationNone = false
+  let hasUnderline = false
+  let hasLineThrough = false
+  for (const value of values) {
+    if (key === 'textDecoration' && hasOwn(textDecorationLineMap, value)) {
+      switch (value) {
+        case 'underline':
+          hasUnderline = true
+          continue
+        case 'line-through':
+          hasLineThrough = true
+          continue
+        case 'none':
+          hasTextDecorationNone = true
+          continue
+        // textDecorationLineMap 命中但分支未处理的 line token：落到通用 getUnorderedShorthandProp 流程
+      }
+    }
+    const prop = getUnorderedShorthandProp(key, value, used)
+    if (!prop) {
+      // 该 token 与 key 下任何空闲槽位都不匹配（未知类型 / 槽位已占满），静默丢弃可能让用户难以察觉
+      warn(`Token [${value}] in [${key}: ${values.join(' ')}] is not a valid value or has no available slot, dropped.`)
+      continue
+    }
+    used[prop] = true
+    pushExpandedPair(result, prop, global.__formatValue(value))
+  }
+  if (hasUnderline || hasLineThrough) {
+    result.push(['textDecorationLine', hasUnderline && hasLineThrough ? 'underline line-through' : hasUnderline ? 'underline' : 'line-through'])
+  } else if (hasTextDecorationNone) {
+    result.push(['textDecorationLine', 'none'])
+  }
+  // text-shadow 至少需要 offset-x / offset-y；缺省 height 时按 CSS 默认补 0 并发出 warn
+  if (key === 'textShadow') {
+    const offsetEntry = result.find(item => item[0] === 'textShadowOffset')?.[1]
+    if (offsetEntry && offsetEntry.width !== undefined && offsetEntry.height === undefined) {
+      warn(`Value of [textShadow:${values.join(' ')}] is missing offset-y, fallback to 0, please check again!`)
+      offsetEntry.height = 0
+    }
+  }
+  return applyRuntimeShorthandDefaults(key, result, used)
+}
+
+function expandFlex (value: string): Array<[string, any]> | null {
+  const values = parseValues(value)
+  if (values.length === 0) return null
+  if (values.length === 1) {
+    if (values[0] === 'none') {
+      return [['flexGrow', 0], ['flexShrink', 0]]
+    }
+    if (values[0] === 'initial') {
+      return [['flexGrow', 0], ['flexShrink', 1]]
+    }
+  }
+  const result: Array<[string, any]> = []
+  let i = 0
+  const isNum = (v: string) => !isNaN(+v)
+  if (isNum(values[i])) {
+    result.push(['flexGrow', +values[i++]])
+  } else {
+    result.push(['flexGrow', 1])
+  }
+  if (i < values.length && isNum(values[i])) {
+    result.push(['flexShrink', +values[i++]])
+  } else {
+    result.push(['flexShrink', 1])
+  }
+  if (i < values.length) {
+    if (values[i] !== 'auto') {
+      result.push(['flexBasis', global.__formatValue(values[i])])
+    }
+  } else {
+    result.push(['flexBasis', 0])
+  }
+  return result
+}
+
+// font 简写专用 transform，仿 transformFlex 的标志位模式。
+// RN 等效子集语法：font: [ <font-style> ] [ <font-variant-css2> ] [ <font-weight> ] <font-size> [ / <line-height> ] <font-family>
+// - 必填项：font-size 与 font-family；缺其一整条 font 声明丢弃（error）
+// - 非必填 token（font-stretch / 数字型 font-variant-numeric / system 关键字等）：warn 提示并忽略，保留其余槽位
+function transformFont (styleObj: Record<string, any>, percentConfig: PercentConfig) {
+  const value = styleObj.font
+  if (typeof value !== 'string') return
+  const tokens = parseValues(value)
+  let sizeIdx = -1
+  let lineHeight: string | undefined
+  const result: Array<[string, any]> = []
+  // 1. 定位 font-size（第一个 length，可能带 /<line-height>）
+  //    注意：unit-less 数字也命中 length 正则，需要先排除 font-weight 数字（100..900 / bold / normal），
+  //    否则 `font: 500 16px Arial` 会把 500 误判为 fontSize。
+  //    fontSize 自身可能是 %（如 `font: 50% Arial`），就地用 resolvePercent 按 parentFontSize 解析；
+  //    fontSize % 校验通过的是 `isLengthValue`（length 正则含 %），主流程已用 length 分支接住，无需特判
+  for (let i = 0; i < tokens.length; i++) {
+    let t = tokens[i]
+    if (t.endsWith('/') && tokens[i + 1]) {
+      t += tokens[i + 1]
+      tokens.splice(i + 1, 1)
+    } else if (tokens[i + 1] === '/' && tokens[i + 2]) {
+      t += `/${tokens[i + 2]}`
+      tokens.splice(i + 1, 2)
+    } else if (tokens[i + 1]?.startsWith('/') && tokens[i + 1].length > 1) {
+      t += tokens[i + 1]
+      tokens.splice(i + 1, 1)
+    }
+    const [sizePart, lhPart] = parseValues(t, '/')
+    if (hasOwn(fontWeightMap, sizePart)) continue
+    if (isLengthValue(sizePart)) {
+      sizeIdx = i
+      const sizeVal = percentRegExp.test(sizePart)
+        ? resolvePercent(sizePart, 'fontSize', percentConfig)
+        : global.__formatValue(sizePart)
+      result.push(['fontSize', sizeVal])
+      if (lhPart) lineHeight = lhPart
+      break
+    }
+  }
+  if (sizeIdx === -1) {
+    // 缺必填 font-size 整体丢弃；与 transformFlex「Flex shorthand value [...] ..., dropped.」同口径
+    error(`Font shorthand value [${value}] is missing required <font-size>, dropped.`)
+    delete styleObj.font
+    return
+  }
+  // 2. 前导段 font-style / font-variant(small-caps) / font-weight，顺序不敏感
+  for (let i = 0; i < sizeIdx; i++) {
+    const t = tokens[i]
+    if (t === 'normal') continue
+    if (t === 'italic') {
+      result.push(['fontStyle', t])
+    } else if (t === 'small-caps') {
+      // RN processFontVariant 接受字符串，内部 split 归一为数组，与 font-variant 长属性同口径
+      result.push(['fontVariant', t])
+    } else if (hasOwn(fontWeightMap, t)) {
+      result.push(['fontWeight', t])
+    } else {
+      // 其余（font-stretch / 数字型 font-variant-numeric / system 关键字等）→ 非必填：
+      // 与 transformBackground「Token [...] in [background: ...] ..., dropped.」同口径，warn + 忽略该 token、保留其余
+      warn(`Token [${t}] in [font: ${value}] is not supported (only font-style / small-caps / font-weight are valid before <font-size>), dropped.`)
+    }
+  }
+  // 3. line-height：RN lineHeight 不接受百分比字符串，必须当场数值化。
+  //    - unit-less 数字（1.5）→ '150%' 后走 resolvePercent
+  //    - 显式百分比（120%）→ 直接走 resolvePercent
+  //    - 带单位（40px / 40rpx）→ __formatValue
+  //    基数 fontSize 取值（「长属性不覆盖简写」一致）：
+  //    - user 已显式写 fontSize 长属性 → 优先（先经 __formatValue 归一 '24px' → 24）
+  //    - 否则用 font 简写解析出的 fontSize（result[0][1]，已可能是 number / 解析后的 % 值）
+  if (lineHeight !== undefined) {
+    // percentConfig.fontSize 用于 resolvePercent 的 base：
+    // - user 已显式写 fontSize 长属性 → 外层用 normalStyle.fontSize 初始化，已被前置 styleHelperMixin
+    //   的 transformStyleObj 经 __formatValue 归一为 number，可直接用，不覆盖（「长属性优先」一致）
+    // - 否则用 font 简写解析出的 fontSize（result[0][1]，本身已 number 或解析后的 % 值）回填
+    if (percentConfig.fontSize === undefined) percentConfig.fontSize = result[0][1]
+    let lh: string | number | undefined
+    if (percentRegExp.test(lineHeight)) {
+      lh = resolvePercent(lineHeight, 'lineHeight', percentConfig)
+    } else if (!isNaN(+lineHeight)) {
+      lh = resolvePercent(`${+lineHeight * 100}%`, 'lineHeight', percentConfig)
+    } else {
+      lh = global.__formatValue(lineHeight)
+    }
+    // lh 仍是字符串说明 resolvePercent 因 base 非 number 原样返回（已 error 过）或带单位 __formatValue
+    // 未能换算成 number（如 fontSize 是未解析的 var()）。RN lineHeight 不接受字符串，丢弃避免运行时报错
+    if (typeof lh === 'number') {
+      result.push(['lineHeight', lh])
+    } else {
+      warn(`Line-height [${lineHeight}] in [font: ${value}] could not be resolved to a number (font-size unresolved?), dropped.`)
+    }
+  }
+  // 4. font-family（font-size 之后剩余部分；多字体取首值、去引号）
+  const familyStr = tokens.slice(sizeIdx + 1).join(' ').trim()
+  if (!familyStr) {
+    error(`Font shorthand value [${value}] is missing required <font-family>, dropped.`)
+    delete styleObj.font
+    return
+  }
+  // parseValues 内部已 trim
+  const family = parseValues(familyStr.replace(quoteCharRegExp, ''), ',')[0]
+  if (family) result.push(['fontFamily', family])
+  delete styleObj.font
+  for (const [prop, val] of result) {
+    if (!hasOwn(styleObj, prop)) styleObj[prop] = val
+  }
+}
+
+function transformFlex (styleObj: Record<string, any>) {
+  const value = styleObj.flex
+  if (typeof value !== 'string') return
+  delete styleObj.flex
+  const flexResult = expandFlex(value)
+  if (!flexResult) {
+    // expandFlex 仅在 parseValues 出空数组时返回 null（空字符串 / 纯空白），属于明确非法，整段丢弃
+    error(`Flex shorthand value [${value}] is not a valid CSS flex value, dropped.`)
+    return
+  }
+  for (const [prop, val] of flexResult) {
+    if (!hasOwn(styleObj, prop)) styleObj[prop] = val
+  }
+}
+
+export function transformShorthand (styleObj: Record<string, any>, shorthandKeys: string[], percentConfig: PercentConfig) {
+  for (const key of shorthandKeys) {
+    const value = styleObj[key]
+
+    // —— 以下为公共链路（与 textDecoration / flexFlow / textShadow / 四值简写共用）——
+    let values: string[]
+    if (typeof value === 'string') {
+      values = parseValues(value)
+    } else if (value === 0 && hasOwn(runtimeBorderLikeShorthandMap, key)) {
+      values = ['0']
+    } else {
+      continue
+    }
+    const props = runtimeAbbreviationMap[key]
+    if (!props) continue
+    // 单值短路：composite 且单值通常透传（RN 原生支持 margin / padding 单值 DimensionValue）；
+    // 但 inset / gap 必须展开（理由见 runtimeForceExpandCompositeMap 注释）
+    if (
+      hasOwn(runtimeCompositeStyleMap, key) &&
+      values.length === 1 &&
+      !hasOwn(runtimeForceExpandCompositeMap, key)
+    ) continue
+    let expandedValues = values
+    let pairs: Array<[string, any]>
+    if (hasOwn(runtimeCompositeStyleMap, key)) {
+      expandedValues = expandCompositeValues(values)
+    }
+    if (hasOwn(runtimeUnorderedAbbreviationMap, key)) {
+      // expandUnorderedAbbreviation 末尾已内部调用 applyRuntimeShorthandDefaults 补齐
+      pairs = expandUnorderedAbbreviation(key, values)
+    } else {
+      pairs = expandAbbreviation(expandedValues, props)
+    }
+
+    delete styleObj[key]
+    for (const [prop, val] of pairs) {
+      if (hasOwn(styleObj, prop)) continue
+      // gap 简写展开后的 rowGap / columnGap 仍可能是 `%` 字符串（如 `gap: 50%` / `gap: 10px 50%`），
+      // RN 类型严格要求 number，这里就地用 resolvePercent 落成数字（rowGap 基 parentHeight、columnGap 基 parentWidth）
+      if ((prop === 'rowGap' || prop === 'columnGap') && typeof val === 'string' && percentRegExp.test(val)) {
+        styleObj[prop] = resolvePercent(val, prop, percentConfig)
+      } else {
+        styleObj[prop] = val
+      }
+    }
+  }
+}
+
+// --- runtime alignment ---
+
+function transformFontFamily (styleObj: Record<string, any>) {
+  const value = styleObj.fontFamily
+  if (typeof value !== 'string') return
+  const stripped = value.replace(quoteCharRegExp, '').trim()
+  if (!stripped) return
+  const values = parseValues(stripped, ',')
+  // parseValues 内部已 trim
+  styleObj.fontFamily = values[0]
+}
+
+function transformBorderStyleNone (styleObj: Record<string, any>) {
+  if (styleObj.borderStyle === 'none') {
+    delete styleObj.borderStyle
+    delete styleObj.borderTopWidth
+    delete styleObj.borderRightWidth
+    delete styleObj.borderBottomWidth
+    delete styleObj.borderLeftWidth
+    styleObj.borderWidth = 0
+  }
+  if (styleObj.outlineStyle === 'none') {
+    delete styleObj.outlineStyle
+    styleObj.outlineWidth = 0
+  }
+}
+
+function transformPosition (styleObj: Record<string, any>) {
+  if (styleObj.position === 'fixed') {
+    styleObj.position = 'absolute'
+    return true
+  }
+  return false
+}
+
+function transOrderXY (values: string[]) {
+  if (values.length === 2 && ['top', 'bottom'].includes(values[0])) {
+    [values[0], values[1]] = [values[1], values[0]]
+  }
+  return values
+}
+function transformBackground (styleObj: Record<string, any>) {
+  if (typeof styleObj.backgroundSize === 'string') {
+    styleObj.backgroundSize = parseValues(styleObj.backgroundSize)
+  }
+  if (typeof styleObj.backgroundPosition === 'string') {
+    const parts = parseValues(styleObj.backgroundPosition)
+    styleObj.backgroundPosition = transOrderXY(parts.map(v => v === 'center' ? '50%' : v))
+  }
+  const value = styleObj.background
+  if (typeof value !== 'string') return
+  delete styleObj.background
+  if (value === 'none') {
+    styleObj.backgroundImage = 'none'
+    styleObj.backgroundColor = 'transparent'
+    return
+  }
+  const tokens = parseValues(value)
+  const positionValues: string[] = []
+  const sizeValues: string[] = []
+  let isSize = false
+  for (const token of tokens) {
+    if (urlRegExp.test(token)) {
+      styleObj.backgroundImage = token
+    } else if (linearGradientRegExp.test(token)) {
+      styleObj.backgroundImage = token
+    } else if (hasOwn(bgRepeatMap, token)) {
+      styleObj.backgroundRepeat = token
+    } else if (isColorValue(token)) {
+      styleObj.backgroundColor = token
+    } else if (token === '/') {
+      isSize = true
+    } else {
+      const slashParts = parseValues(token, '/')
+      if (slashParts.length > 1) {
+        const posPart = slashParts[0]
+        if (posPart) positionValues.push(posPart === 'center' ? '50%' : posPart)
+        isSize = true
+        for (let i = 1; i < slashParts.length; i++) {
+          if (slashParts[i]) sizeValues.push(slashParts[i])
+        }
+      } else if (isSize) {
+        sizeValues.push(token)
+      } else if (hasOwn(bgPositionMap, token) || percentRegExp.test(token) || digitStartRegExp.test(token)) {
+        positionValues.push(token === 'center' ? '50%' : token)
+      } else {
+        // background-attachment / background-origin / background-clip 及拼写错误等：RN 均不支持，提示用户避免静默丢值
+        warn(`Token [${token}] in [background: ${value}] is not a recognized background sub-value, dropped.`)
+      }
+    }
+  }
+  if (positionValues.length) styleObj.backgroundPosition = transOrderXY(positionValues)
+  if (sizeValues.length) styleObj.backgroundSize = sizeValues
+}
+
+// ============================================================
+// style traversal
+// ============================================================
+
+export function traverseStyle (styleObj: Record<string, any>, visitor: (arg: VisitorArg) => void) {
+  const keyPath: Array<string> = []
+  function traverse<T extends Record<string, any>> (target: T) {
+    if (Array.isArray(target)) {
+      for (let i = 0; i < target.length; i++) {
+        const key = String(i)
+        const value = target[i]
+        keyPath.push(key)
+        visitor({ target, key, value, keyPath })
+        traverse(value)
+        keyPath.pop()
+      }
+    } else if (isObject(target)) {
+      const keys = Object.keys(target)
+      for (let i = 0; i < keys.length; i++) {
+        const key = keys[i]
+        const value = (target as Record<string, any>)[key]
+        keyPath.push(key)
+        visitor({ target, key, value, keyPath })
+        traverse(value)
+        keyPath.pop()
+      }
+    }
+  }
+  traverse(styleObj)
+}
+
+export function setStyle (styleObj: Record<string, any>, keyPath: Array<string>, setter: (arg: VisitorArg) => void) {
+  let target = styleObj
+  const lastKey = keyPath[keyPath.length - 1]
+  for (let i = 0; i < keyPath.length - 1; i++) {
+    target = target[keyPath[i]]
+    if (!target) return
+  }
+  setter({
+    target,
+    key: lastKey,
+    value: target[lastKey],
+    keyPath
+  })
 }
 
-export function useTransformStyle (styleObj: Record<string, any> = {}, { enableVar, transformRadiusPercent, externalVarContext, parentFontSize, parentWidth, parentHeight }: TransformStyleConfig) {
+// ============================================================
+// core style hook
+// ============================================================
+
+export function useTransformStyle (styleObj: Record<string, any> = {}, { enableVar, transformRadiusPercent, parentFontSize, parentWidth, parentHeight, defaultStyle }: TransformStyleConfig) {
   const varStyle: Record<string, any> = {}
   const unoVarStyle: Record<string, any> = {}
   const normalStyle: Record<string, any> = {}
@@ -461,16 +1244,85 @@ export function useTransformStyle (styleObj: Record<string, any> = {}, { enableV
   let hasVarUse = false
   let hasSelfPercent = false
   let hasBoxSizingAffectingStyle = false
+  // 顶层 transform* 标志位：在 styleVisitor 阶段从原始 styleObj 收集，
+  // 调用侧据此决定是否进入对应 transform 函数。
+  let hasTransform = false
+  let hasBoxShadow = false
+  let hasFontFamily = false
+  let hasFlex = false
+  let hasFont = false
+  let needTransformBackground = false
+  let needStringify = false
   const varKeyPaths: Array<Array<string>> = []
   const unoVarKeyPaths: Array<Array<string>> = []
   const percentKeyPaths: Array<Array<string>> = []
   const calcKeyPaths: Array<Array<string>> = []
   const envKeyPaths: Array<Array<string>> = []
+  const shorthandKeys: string[] = []
   const [width, setWidth] = useState(0)
   const [height, setHeight] = useState(0)
   const navigation = useNavigation()
 
-  function varVisitor ({ target, key, value, keyPath }: VisitorArg) {
+  function collectTopLevelFlags (key: string, value: any) {
+    switch (key) {
+      case 'transform':
+        hasTransform = true
+        break
+      case 'boxShadow':
+        hasBoxShadow = true
+        break
+      case 'fontFamily':
+        hasFontFamily = true
+        break
+      case 'flex':
+        hasFlex = true
+        break
+      case 'font':
+        hasFont = true
+        break
+      case 'background':
+      case 'backgroundSize':
+      case 'backgroundPosition':
+        needTransformBackground = true
+        break
+      case 'fontWeight':
+      case 'transformOrigin':
+        needStringify = true
+        break
+    }
+  }
+
+  function visitOther ({ key, value, keyPath }: VisitorArg) {
+    if (typeof value !== 'string') return
+    const hasPercent = value.includes('%')
+    const hasCalc = value.includes('calc(')
+    const hasEnv = value.includes('env(')
+    if (!(hasPercent || hasCalc || hasEnv)) return
+    let resolvedKeyPath: Array<string> | undefined
+    if (hasEnv) {
+      resolvedKeyPath = keyPath.slice()
+      envKeyPaths.push(resolvedKeyPath)
+    }
+    if (hasPercent) {
+      // fixme 去掉 translate & border-radius 的百分比计算
+      // fixme Image 组件 borderRadius 仅支持 number
+      const needRadiusPercent = transformRadiusPercent && hasOwn(radiusPercentRule, key)
+      const needFontPercent = key === 'fontSize' || key === 'lineHeight'
+      // RN gap / rowGap / columnGap 不支持 %，需要运行时换算为 number 喂给 RN
+      const needGapPercent = key === 'rowGap' || key === 'columnGap'
+      if ((needRadiusPercent || needFontPercent || needGapPercent) && percentRegExp.test(value)) {
+        if (needRadiusPercent) hasSelfPercent = true
+        resolvedKeyPath = resolvedKeyPath ?? keyPath.slice()
+        percentKeyPaths.push(resolvedKeyPath)
+      }
+    }
+    if (hasCalc) {
+      resolvedKeyPath = resolvedKeyPath ?? keyPath.slice()
+      calcKeyPaths.push(resolvedKeyPath)
+    }
+  }
+
+  function styleVisitor ({ target, key, value, keyPath }: VisitorArg) {
     if (keyPath.length === 1) {
       if (unoVarDecRegExp.test(key)) {
         unoVarStyle[key] = value
@@ -480,84 +1332,60 @@ export function useTransformStyle (styleObj: Record<string, any> = {}, { enableV
       } else {
         // clone对象避免set值时改写到props
         normalStyle[key] = isObject(value) ? diffAndCloneA(value).clone : value
+        if (!hasBoxSizingAffectingStyle && isBoxSizingAffectingStyle(key)) {
+          hasBoxSizingAffectingStyle = true
+        }
+        if (hasOwn(runtimeAbbreviationMap, key)) {
+          shorthandKeys.push(key)
+        }
+        collectTopLevelFlags(key, value)
       }
     }
-    // 对于var定义中使用的var无需替换值，可以通过resolveVar递归解析出值
-    if (!varDecRegExp.test(key)) {
-      // 一般情况下一个样式属性中不会混用unocss var和普通css var，可分开进行互斥处理
-      if (unoVarUseRegExp.test(value)) {
-        unoVarKeyPaths.push(keyPath.slice())
-      } else if (varUseRegExp.test(value)) {
-        hasVarUse = true
-        varKeyPaths.push(keyPath.slice())
-      } else {
-        visitOther({ target, key, value, keyPath })
-      }
-    }
-  }
-
-  function boxSizingVisitor ({ key, keyPath }: VisitorArg) {
-    if (keyPath.length === 1 && !hasBoxSizingAffectingStyle && isBoxSizingAffectingStyle(key)) {
-      hasBoxSizingAffectingStyle = true
-    }
-  }
-
-  function envVisitor ({ value, keyPath }: VisitorArg) {
-    if (envUseRegExp.test(value)) {
-      envKeyPaths.push(keyPath.slice())
-    }
-  }
-
-  function calcVisitor ({ value, keyPath }: VisitorArg) {
-    if (calcUseRegExp.test(value)) {
-      calcKeyPaths.push(keyPath.slice())
-    }
-  }
-
-  function percentVisitor ({ key, value, keyPath }: VisitorArg) {
-    // fixme 去掉 translate & border-radius 的百分比计算
-    // fixme Image 组件 borderRadius 仅支持 number
-    if (transformRadiusPercent && hasOwn(radiusPercentRule, key) && PERCENT_REGEX.test(value)) {
-      hasSelfPercent = true
-      percentKeyPaths.push(keyPath.slice())
-    } else if ((key === 'fontSize' || key === 'lineHeight') && PERCENT_REGEX.test(value)) {
-      percentKeyPaths.push(keyPath.slice())
-    }
-  }
-
-  function visitOther ({ target, key, value, keyPath }: VisitorArg) {
-    if (typeof value === 'string' && (value.includes('%') || value.includes('calc(') || value.includes('env('))) {
-      [envVisitor, percentVisitor, calcVisitor].forEach(visitor => visitor({ target, key, value, keyPath }))
+    // var 定义中使用的 var 无需替换值，可以通过 resolveVar 递归解析出值
+    if (varDecRegExp.test(key) || typeof value !== 'string') return
+    // 一般情况下一个样式属性中不会混用 unocss var 和普通 css var，可分开互斥处理
+    if (unoVarUseRegExp.test(value)) {
+      unoVarKeyPaths.push(keyPath.slice())
+    } else if (varUseRegExp.test(value)) {
+      hasVarUse = true
+      varKeyPaths.push(keyPath.slice())
+    } else {
+      visitOther({ target, key, value, keyPath })
     }
   }
 
   // traverse var & generate normalStyle
-  traverseStyle(styleObj, [varVisitor, boxSizingVisitor])
-  hasVarDec = hasVarDec || !!externalVarContext
+  traverseStyle(styleObj, styleVisitor)
   enableVar = enableVar || hasVarDec || hasVarUse
   const enableVarRef = useRef(enableVar)
   if (enableVarRef.current !== enableVar) {
     error('css variable use/declare should be stable in the component lifecycle, or you can set [enable-var] with true.')
   }
   // apply css var
-  const varContextRef = useRef({})
+  const varContextRef = useRef<Record<string, any>>({})
   if (enableVarRef.current) {
     // eslint-disable-next-line react-hooks/rules-of-hooks
     const varContext = useContext(VarContext)
-    const newVarContext = extendObject({}, varContext, externalVarContext, varStyle)
-    // 缓存比较newVarContext是否发生变化
-    if (diffAndCloneA(varContextRef.current, newVarContext).diff) {
-      varContextRef.current = newVarContext
+    // 无声明节点：直接用父 varContext 解析，跳过 merge / 比对 / ref 维护。
+    // 有声明节点：浅合并出 newVarContext，仅在内容变化时替换 ref 维持引用稳定，
+    //            供 wrapChildren 的 <VarContext.Provider> 使用。
+    let resolvedVarContext = varContext
+    if (hasVarDec) {
+      const newVarContext = extendObject({}, varContext, varStyle)
+      if (!shallowEqual(varContextRef.current, newVarContext)) {
+        varContextRef.current = newVarContext
+      }
+      resolvedVarContext = varContextRef.current
     }
-    transformVar(normalStyle, varKeyPaths, varContextRef.current, visitOther)
+    if (varKeyPaths.length) transformVar(normalStyle, varKeyPaths, resolvedVarContext, visitOther)
   }
 
   // apply unocss var
-  if (unoVarKeyPaths.length) {
-    transformVar(normalStyle, unoVarKeyPaths, unoVarStyle, visitOther)
-  }
-
-  const percentConfig = {
+  if (unoVarKeyPaths.length) transformVar(normalStyle, unoVarKeyPaths, unoVarStyle, visitOther)
+  // apply env
+  if (envKeyPaths.length) transformEnv(normalStyle, envKeyPaths, navigation)
+  // apply percent / calc
+  const percentConfig: PercentConfig = {
     width,
     height,
     fontSize: normalStyle.fontSize,
@@ -565,43 +1393,57 @@ export function useTransformStyle (styleObj: Record<string, any> = {}, { enableV
     parentHeight,
     parentFontSize
   }
-
-  const positionMeta = {
-    hasPositionFixed: false
-  }
-
-  // apply env
-  transformEnv(normalStyle, envKeyPaths, navigation)
-  // apply percent
-  transformPercent(normalStyle, percentKeyPaths, percentConfig)
-  // apply calc
-  transformCalc(normalStyle, calcKeyPaths, (value: string, key: string) => {
-    if (PERCENT_REGEX.test(value)) {
-      if (hasOwn(selfPercentRule, key)) {
-        hasSelfPercent = true
-      }
-      const resolved = resolvePercent(value, key, percentConfig)
-      return typeof resolved === 'number' ? resolved : 0
-    } else {
-      const formatted = global.__formatValue(value)
-      if (typeof formatted === 'number') {
-        return formatted
+  // transformFont 可能会更新 percentConfig 配置，必须在 transformPercent 之前执行，保证 fontSize / lineHeight 的百分比能被正确解析
+  if (hasFont) transformFont(normalStyle, percentConfig)
+  if (percentKeyPaths.length) transformPercent(normalStyle, percentKeyPaths, percentConfig)
+  if (calcKeyPaths.length) {
+    transformCalc(normalStyle, calcKeyPaths, (value: string, key: string) => {
+      if (percentRegExp.test(value)) {
+        if (hasOwn(selfPercentRule, key)) {
+          hasSelfPercent = true
+        }
+        const resolved = resolvePercent(value, key, percentConfig)
+        return typeof resolved === 'number' ? resolved : 0
       } else {
-        warn('calc() only support number, px, rpx, % temporarily.')
-        return 0
+        const formatted = global.__formatValue(value)
+        if (typeof formatted === 'number') {
+          return formatted
+        } else {
+          warn('calc() only support number, px, rpx, % temporarily.')
+          return 0
+        }
       }
-    }
-  })
+    })
+  }
 
-  // apply position
-  transformPosition(normalStyle, positionMeta)
   // transform number enum stringify
-  transformStringify(normalStyle)
-  // transform rpx to px
-  transformBoxShadow(normalStyle)
-  // transform 字符串格式转化数组格式(先转数组再处理css var)
-  transformTransform(normalStyle)
-  transformBoxSizing(normalStyle, hasBoxSizingAffectingStyle)
+  if (needStringify) transformStringify(normalStyle)
+  // transform unit
+  if (hasBoxShadow) transformBoxShadow(normalStyle)
+  // transform 字符串格式转化数组格式
+  if (hasTransform) transformTransform(normalStyle)
+  // apply runtime style processing alignment
+  if (hasFontFamily) transformFontFamily(normalStyle)
+  if (hasFlex) transformFlex(normalStyle)
+  if (shorthandKeys.length) transformShorthand(normalStyle, shorthandKeys, percentConfig)
+  if (needTransformBackground) transformBackground(normalStyle)
+  // borderStyle / outlineStyle: 'none' 的清除语义放到变量解析、简写展开之后统一处理。
+  transformBorderStyleNone(normalStyle)
+  // transform position: fixed
+  const hasPositionFixed = transformPosition(normalStyle)
+  // 合并组件默认样式：默认样式在 user transform 之后兜底写入，需完全符合 RN style 规范
+  // 命中 user 已存在 key（含简写展开后的长属性）则跳过。
+  // 复用同一次循环顺带补 hasBoxSizingAffectingStyle，避免独立扫一遍 default。
+  if (defaultStyle) {
+    for (const k in defaultStyle) {
+      if (!hasOwn(defaultStyle, k)) continue
+      if (!hasOwn(normalStyle, k)) normalStyle[k] = defaultStyle[k]
+      if (!hasBoxSizingAffectingStyle && isBoxSizingAffectingStyle(k)) {
+        hasBoxSizingAffectingStyle = true
+      }
+    }
+  }
+  if (hasBoxSizingAffectingStyle) transformBoxSizing(normalStyle)
 
   return {
     hasVarDec,
@@ -610,83 +1452,46 @@ export function useTransformStyle (styleObj: Record<string, any> = {}, { enableV
     setHeight,
     normalStyle,
     hasSelfPercent,
-    hasPositionFixed: positionMeta.hasPositionFixed
+    hasPositionFixed
   }
 }
 
-export interface VisitorArg {
-  target: Record<string, any>
-  key: string
-  value: any
-  keyPath: Array<string>
-}
+// ============================================================
+// other React hooks
+// ============================================================
 
-export function traverseStyle (styleObj: Record<string, any>, visitors: Array<(arg: VisitorArg) => void>) {
-  const keyPath: Array<string> = []
-  function traverse<T extends Record<string, any>> (target: T) {
-    if (Array.isArray(target)) {
-      target.forEach((value, index) => {
-        const key = String(index)
-        keyPath.push(key)
-        visitors.forEach(visitor => visitor({ target, key, value, keyPath }))
-        traverse(value)
-        keyPath.pop()
-      })
-    } else if (isObject(target)) {
-      Object.entries(target).forEach(([key, value]) => {
-        keyPath.push(key)
-        visitors.forEach(visitor => visitor({ target, key, value, keyPath }))
-        traverse(value)
-        keyPath.pop()
-      })
-    }
-  }
-  traverse(styleObj)
+export function useNavigation (): Record<string, any> | undefined {
+  const { navigation } = useContext(RouteContext) || {}
+  return navigation
 }
 
-export function setStyle (styleObj: Record<string, any>, keyPath: Array<string>, setter: (arg: VisitorArg) => void) {
-  let target = styleObj
-  const lastKey = keyPath[keyPath.length - 1]
-  for (let i = 0; i < keyPath.length - 1; i++) {
-    target = target[keyPath[i]]
-    if (!target) return
-  }
-  setter({
-    target,
-    key: lastKey,
-    value: target[lastKey],
-    keyPath
-  })
-}
+/**
+ * 用法等同于 useEffect，但是会忽略首次执行，只在依赖更新时执行
+ */
+export const useUpdateEffect = (effect: any, deps: any) => {
+  const isMounted = useRef(false)
 
-export function splitProps<T extends Record<string, any>> (props: T): {
-  textProps?: Partial<T>
-  innerProps?: Partial<T>
-} {
-  return groupBy(props, (key) => {
-    if (hasOwn(TEXT_PROPS_MAP, key)) {
-      return 'textProps'
+  // for react-refresh
+  useEffect(() => {
+    return () => {
+      isMounted.current = false
+    }
+  }, [])
+
+  useEffect(() => {
+    if (!isMounted.current) {
+      isMounted.current = true
     } else {
-      return 'innerProps'
+      return effect()
     }
-  }) as {
-    textProps: Partial<T>
-    innerProps: Partial<T>
-  }
+  }, deps)
 }
 
-interface LayoutConfig {
-  props: Record<string, any>
-  hasSelfPercent: boolean
-  setWidth?: Dispatch<SetStateAction<number>>
-  setHeight?: Dispatch<SetStateAction<number>>
-  onLayout?: (event?: LayoutChangeEvent) => void
-  nodeRef: React.RefObject<any>
-}
 export const useLayout = ({ props, hasSelfPercent, setWidth, setHeight, onLayout, nodeRef }: LayoutConfig) => {
   const layoutRef = useRef({})
   const hasLayoutRef = useRef(false)
-  const layoutStyle = useMemo(() => { return !hasLayoutRef.current && hasSelfPercent ? HIDDEN_STYLE : {} }, [hasLayoutRef.current])
+  // 固定首次 layout 前是否需要隐藏，避免 hasSelfPercent 后续变化时重新隐藏组件
+  const layoutStyle = useMemo(() => { return !hasLayoutRef.current && hasSelfPercent ? hiddenStyle : undefined }, [hasLayoutRef.current])
   const layoutProps: Record<string, any> = {}
   const navigation = useNavigation()
   const enableOffset = props['enable-offset']
@@ -715,37 +1520,35 @@ export const useLayout = ({ props, hasSelfPercent, setWidth, setHeight, onLayout
   }
 }
 
-export interface WrapChildrenConfig {
-  hasVarDec: boolean
-  varContext?: Record<string, any>
-  textPassThrough?: TextPassThroughContextValue | null
-}
-
-export interface TextPassThroughValueOptions {
-  inheritTextProps?: boolean
-  disabled?: boolean
-}
-
-export function useTextPassThroughValue (
+export function useTextPassThrough (
   textStyle?: TextStyle,
   textProps?: Record<string, any>,
-  { inheritTextProps = true, disabled = false }: TextPassThroughValueOptions = {}
+  { enableTextPassThrough = false }: TextPassThroughValueOptions = {}
 ) {
-  const parent = useContext(TextPassThroughContext)
-  const valueRef = useRef<TextPassThroughContextValue | null>(null)
+  const shouldEnableTextPassThrough = (
+    enableTextPassThrough ||
+    !!textStyle ||
+    !!textProps
+  )
+  const enableTextPassThroughRef = useRef(shouldEnableTextPassThrough)
+
+  if (enableTextPassThroughRef.current !== shouldEnableTextPassThrough) {
+    error('[Mpx runtime error]: text style/props use should be stable in the component lifecycle, or you can set [enable-text-pass-through] with true.')
+  }
 
-  if (disabled) return null
+  if (!enableTextPassThroughRef.current) return null
 
-  if (!textStyle && !textProps && (inheritTextProps || !parent?.pendingTextProps)) return null
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const parent = useContext(TextPassThroughContext)
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const valueRef = useRef<TextPassThroughContextValue | null>(null)
 
   const nextTextStyle = textStyle
     ? extendObject({}, parent?.textStyle, textStyle)
     : parent?.textStyle
-  const nextTextProps = inheritTextProps
-    ? textProps
-      ? extendObject({}, parent?.pendingTextProps, textProps)
-      : parent?.pendingTextProps
-    : textProps
+  const nextTextProps = textProps
+    ? extendObject({}, parent?.pendingTextProps, textProps)
+    : parent?.pendingTextProps
   const nextValue = {
     textStyle: nextTextStyle,
     pendingTextProps: nextTextProps
@@ -758,106 +1561,29 @@ export function useTextPassThroughValue (
   return valueRef.current
 }
 
-export function wrapChildren (props: Record<string, any> = {}, { hasVarDec, varContext, textPassThrough }: WrapChildrenConfig) {
-  let { children } = props
-  if (textPassThrough) {
-    children = <TextPassThroughContext.Provider value={textPassThrough} key='textPassThroughWrap'>{children}</TextPassThroughContext.Provider>
-  }
-  if (hasVarDec && varContext) {
-    children = <VarContext.Provider value={varContext} key='varContextWrap'>{children}</VarContext.Provider>
-  }
-  return children
-}
-
-export const debounce = <T extends AnyFunc> (
-  func: T,
-  delay: number
-): ((...args: Parameters<T>) => void) & { clear: () => void } => {
-  let timer: any
-  const wrapper = (...args: ReadonlyArray<any>) => {
-    timer && clearTimeout(timer)
-    timer = setTimeout(() => {
-      func(...args)
-    }, delay)
-  }
-  wrapper.clear = () => {
-    timer && clearTimeout(timer)
-    timer = null
-  }
-  return wrapper
-}
-
-export const useDebounceCallback = <T extends AnyFunc> (
-  func: T,
-  delay: number
-): ((...args: Parameters<T>) => void) & { clear: () => void } => {
-  const debounced = useMemo(() => debounce(func, delay), [func])
-  return debounced
-}
-
-export const useStableCallback = <T extends AnyFunc | null | undefined> (
-  callback: T
-): T extends AnyFunc ? T : () => void => {
-  const ref = useRef<T>(callback)
-  ref.current = callback
-  return useCallback<any>(
-    (...args: any[]) => ref.current?.(...args),
-    []
-  )
-}
-
-export function usePrevious<T> (value: T): T | undefined {
-  const ref = useRef<T | undefined>()
-  const prev = ref.current
-  ref.current = value
-  return prev
-}
-
-export interface GestureHandler {
-  nodeRefs?: Array<{ getNodeInstance: () => { nodeRef: unknown } }>
-  current?: unknown
-  handlerTag?: number
-}
+export function useTextPassThroughText (textStyle?: TextStyle) {
+  const inheritedText = useContext(TextPassThroughContext)
+  const valueRef = useRef<TextPassThroughContextValue | null>(null)
 
-export function flatGesture (gestures: Array<GestureHandler> = []) {
-  return (gestures && gestures.flatMap((gesture: GestureHandler) => {
-    if (gesture && gesture.nodeRefs) {
-      return gesture.nodeRefs
-        .map((item: { getNodeInstance: () => any }) => item.getNodeInstance()?.instance?.gestureRef || {})
+  if (!textStyle) {
+    return {
+      inheritedText,
+      textPassThrough: null
     }
-    if (gesture && (gesture.current || gesture.handlerTag !== undefined)) {
-      return [gesture]
-    }
-    return []
-  })) || []
-}
+  }
 
-export function getCurrentPage (pageId: number | null | undefined) {
-  if (!global.getCurrentPages) return
-  const pages = global.getCurrentPages()
-  return pages.find((page: any) => isFunction(page.getPageId) && page.getPageId() === pageId)
-}
+  const nextValue = {
+    textStyle: extendObject({}, inheritedText?.textStyle, textStyle)
+  }
 
-export function renderImage (
-  imageProps: ImageProps,
-  enableFastImage = true
-) {
-  let Component = Image
-  if (enableFastImage) {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const fastImageModule = require('@d11/react-native-fast-image')
-    Component = fastImageModule.default || fastImageModule
+  if (diffAndCloneA(valueRef.current, nextValue).diff) {
+    valueRef.current = nextValue
   }
-  return createElement(Component, imageProps)
-}
 
-export function pickStyle (styleObj: Record<string, any> = {}, pickedKeys: Array<string>, callback?: (key: string, val: number | string) => number | string) {
-  return pickedKeys.reduce<Record<string, any>>((acc, key) => {
-    if (key in styleObj) {
-      acc[key] = callback ? callback(key, styleObj[key]) : styleObj[key]
-    }
-    return acc
-  }, {})
+  return {
+    inheritedText,
+    textPassThrough: valueRef.current
+  }
 }
 
 export function useHover ({ enableHover, hoverStartTime, hoverStayTime, disabled }: { enableHover: boolean, hoverStartTime: number, hoverStayTime: number, disabled?: boolean }) {
@@ -872,37 +1598,46 @@ export function useHover ({ enableHover, hoverStartTime, hoverStayTime, disabled
   // eslint-disable-next-line react-hooks/rules-of-hooks
   const [isHover, setIsHover] = useState(false)
   // eslint-disable-next-line react-hooks/rules-of-hooks
-  const dataRef = useRef<{
+  const hoverRef = useRef<{
     startTimer?: ReturnType<typeof setTimeout>
     stayTimer?: ReturnType<typeof setTimeout>
-  }>({})
+    hoverStartTime: number
+    hoverStayTime: number
+    disabled?: boolean
+  }>({ hoverStartTime, hoverStayTime, disabled })
+  hoverRef.current.hoverStartTime = hoverStartTime
+  hoverRef.current.hoverStayTime = hoverStayTime
+  hoverRef.current.disabled = disabled
 
   // eslint-disable-next-line react-hooks/rules-of-hooks
   useEffect(() => {
     return () => {
-      dataRef.current.startTimer && clearTimeout(dataRef.current.startTimer)
-      dataRef.current.stayTimer && clearTimeout(dataRef.current.stayTimer)
+      hoverRef.current.startTimer && clearTimeout(hoverRef.current.startTimer)
+      hoverRef.current.stayTimer && clearTimeout(hoverRef.current.stayTimer)
     }
   }, [])
 
-  const setStartTimer = () => {
-    if (disabled) return
-    dataRef.current.startTimer && clearTimeout(dataRef.current.startTimer)
-    dataRef.current.startTimer = setTimeout(() => {
-      setIsHover(true)
-    }, +hoverStartTime)
-  }
-
-  const setStayTimer = () => {
-    if (disabled) return
-    dataRef.current.stayTimer && clearTimeout(dataRef.current.stayTimer)
-    dataRef.current.startTimer && clearTimeout(dataRef.current.startTimer)
-    dataRef.current.stayTimer = setTimeout(() => {
-      setIsHover(false)
-    }, +hoverStayTime)
-  }
   // eslint-disable-next-line react-hooks/rules-of-hooks
   const gesture = useMemo(() => {
+    const setStartTimer = () => {
+      const data = hoverRef.current
+      if (data.disabled) return
+      data.startTimer && clearTimeout(data.startTimer)
+      data.startTimer = setTimeout(() => {
+        setIsHover(true)
+      }, +data.hoverStartTime)
+    }
+
+    const setStayTimer = () => {
+      const data = hoverRef.current
+      if (data.disabled) return
+      data.stayTimer && clearTimeout(data.stayTimer)
+      data.startTimer && clearTimeout(data.startTimer)
+      data.stayTimer = setTimeout(() => {
+        setIsHover(false)
+      }, +data.hoverStayTime)
+    }
+
     return Gesture.Pan()
       .onTouchesDown(() => {
         setStartTimer()
@@ -937,3 +1672,72 @@ export function useRunOnJSCallback (callbackMapRef: MutableRefObject<Record<stri
 
   return invokeCallback
 }
+
+export const useDebounceCallback = <T extends AnyFunc> (
+  func: T,
+  delay: number
+): ((...args: Parameters<T>) => void) & { clear: () => void } => {
+  const debounced = useMemo(() => debounce(func, delay), [func])
+  return debounced
+}
+
+export const useStableCallback = <T extends AnyFunc | null | undefined> (
+  callback: T
+): T extends AnyFunc ? T : () => void => {
+  const ref = useRef<T>(callback)
+  ref.current = callback
+  return useCallback<any>(
+    (...args: any[]) => ref.current?.(...args),
+    []
+  )
+}
+
+export function usePrevious<T> (value: T): T | undefined {
+  const ref = useRef<T | undefined>()
+  const prev = ref.current
+  ref.current = value
+  return prev
+}
+
+// ============================================================
+// component helpers
+// ============================================================
+
+export function wrapChildren (children: ReactNode, { hasVarDec, varContext, textPassThrough }: WrapChildrenConfig) {
+  if (textPassThrough) {
+    children = <TextPassThroughContext.Provider value={textPassThrough} key='textPassThroughWrap'>{children}</TextPassThroughContext.Provider>
+  }
+  if (hasVarDec && varContext) {
+    children = <VarContext.Provider value={varContext} key='varContextWrap'>{children}</VarContext.Provider>
+  }
+  return children
+}
+
+export function renderImage (
+  imageProps: ImageProps,
+  enableFastImage = true
+) {
+  let Component = Image
+  if (enableFastImage) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const fastImageModule = require('@d11/react-native-fast-image')
+    Component = fastImageModule.default || fastImageModule
+  }
+  return createElement(Component, imageProps)
+}
+
+export function flatGesture (gestures: Array<GestureHandler> = []) {
+  return (gestures && gestures.flatMap((gesture: GestureHandler) => {
+    if (gesture && gesture.nodeRefs) {
+      return gesture.nodeRefs
+        .map((item: { getNodeInstance: () => any }) => item.getNodeInstance()?.instance?.gestureRef || {})
+    }
+    return gesture?.current ? [gesture] : []
+  })) || []
+}
+
+export function getCurrentPage (pageId: number | null | undefined) {
+  if (!global.getCurrentPages) return
+  const pages = global.getCurrentPages()
+  return pages.find((page: any) => isFunction(page.getPageId) && page.getPageId() === pageId)
+}