@tamagui/web 2.7.7 → 3.0.0-beta.643.1

package/src/helpers/registerCSSVariable.ts

@@ -1,9 +1,42 @@
+import { normalizeCSSColor } from '@tamagui/normalize-css-color'
 import { createCSSVariable, getVariableValue } from '../createVariable'
 import type { Variable, VariableVal } from '../types'
 
+/**
+ * The dedupe key for a declared value. Equivalent color spellings are one
+ * declaration, so `#333`, `hsl(0, 0%, 20%)` and `hsla(0, 0%, 20%, 1)` share a
+ * variable and the artifact carries the color once. Non-colors key on
+ * themselves, and a canonical key is written as `#rrggbbaa`, which is itself a
+ * color spelling and therefore can never be a non-color raw value.
+ *
+ * Only the key is canonical. The emitted declaration keeps the spelling the
+ * config author wrote, so nothing here rewrites bytes into a longer form.
+ *
+ * This runs where CSS is generated, so a build that owns its CSS artifact
+ * drops it with the rest of the generator.
+ */
+const variableKey = (val: Variable | VariableVal) => {
+  if (typeof val !== 'string') return val
+  const color = normalizeCSSColor(val)
+  return color == null ? val : `#${color.toString(16).padStart(8, '0')}`
+}
+
+/**
+ * Bumped whenever anything the emitted CSS derives from the shared value map
+ * changes: a token registering (which can re-point a value another config
+ * already resolved) or an auto variable being created. `getCSS` caches its
+ * configuration-static half against this, so it must move for both.
+ */
+let variableGeneration = 0
+export const getVariableGeneration = () => variableGeneration
+
 export const registerCSSVariable = (v: Variable | VariableVal) => {
   if (!process.env.TAMAGUI_DID_OUTPUT_CSS) {
-    tokensValueToVariable.set(getVariableValue(v), v)
+    const key = variableKey(getVariableValue(v))
+    if (tokensValueToVariable.has(key) || tokensValueToVariable.size < 10_000) {
+      tokensValueToVariable.set(key, v)
+      variableGeneration++
+    }
   }
 }
 
@@ -19,36 +52,73 @@ export const variableToCSS = (v: Variable, unitless = false) => {
 
 export const tokensValueToVariable = new Map<any, any>()
 
-// auto-generated vars for theme values not in tokens
+// auto-generated vars for theme values not in tokens. this CSS session owns at
+// most 10,000 variable declarations. later values stay literal, because
+// evicting or renaming a variable could invalidate CSS that still references it.
 let autoVarId = 0
 export const autoVariables: Variable[] = []
 
+const serializeVariables = (variables: Variable[]) =>
+  variables.map((v) => `--${v.name}:${v.val}`).join(';')
+
+export const getAutoVariableCSS = () => serializeVariables(autoVariables)
+
 export const getOrCreateVariable = (val: any): Variable => {
-  if (tokensValueToVariable.has(val)) {
-    return tokensValueToVariable.get(val)!
+  const key = variableKey(val)
+  if (tokensValueToVariable.has(key)) {
+    return tokensValueToVariable.get(key)!
+  }
+  if (tokensValueToVariable.size >= 10_000) {
+    return { val, name: '', variable: String(val) } as Variable
   }
   const name = `t${autoVarId++}`
   const variable = `var(--${name})`
   const v = { val, name, variable } as Variable
-  tokensValueToVariable.set(val, v)
+  tokensValueToVariable.set(key, v)
   autoVariables.push(v)
+  variableGeneration++
   return v
 }
 
-// For mutated themes (runtime theme changes like in /theme builder)
-// Uses same 't' prefix but starts at 10000 to avoid conflicts with SSR-generated vars
+// for runtime theme changes, use a disjoint 10,000-id range. like normal auto
+// variables, later values stay literal instead of recycling a live name.
 let mutatedVarId = 10000
 export const mutatedAutoVariables: Variable[] = []
 const mutatedTokensValueToVariable = new Map<any, any>()
 
+export const getMutatedAutoVariableCSS = () => serializeVariables(mutatedAutoVariables)
+
 export const getOrCreateMutatedVariable = (val: any): Variable => {
-  if (mutatedTokensValueToVariable.has(val)) {
-    return mutatedTokensValueToVariable.get(val)!
+  const key = variableKey(val)
+  if (mutatedTokensValueToVariable.has(key)) {
+    return mutatedTokensValueToVariable.get(key)!
+  }
+  if (mutatedTokensValueToVariable.size >= 10_000) {
+    return { val, name: '', variable: String(val) } as Variable
   }
   const name = `t${mutatedVarId++}`
   const variable = `var(--${name})`
   const v = { val, name, variable } as Variable
-  mutatedTokensValueToVariable.set(val, v)
+  mutatedTokensValueToVariable.set(key, v)
   mutatedAutoVariables.push(v)
   return v
 }
+
+/** cache-generation sizes for development diagnostics and behavior probes */
+export const getCSSVariableCacheStats = () => ({
+  auto: tokensValueToVariable.size,
+  autoDeclarations: autoVariables.length,
+  mutated: mutatedTokensValueToVariable.size,
+  mutatedDeclarations: mutatedAutoVariables.length,
+  autoRetainedBytes: [...tokensValueToVariable].reduce((bytes, [key, value]) => {
+    const variable = value as Partial<Variable>
+    return (
+      bytes +
+      String(key).length +
+      String(variable.val ?? '').length +
+      String(variable.name ?? '').length +
+      String(variable.variable ?? '').length
+    )
+  }, 0),
+  autoCSSBytes: getAutoVariableCSS().length,
+})

package/src/helpers/resolveAnimationDriver.ts

@@ -1,23 +1,26 @@
-import type { AnimationDriver } from '../types'
+import type { AnimationDriverLike } from '../types'
+
+function isAnimationDriver(value: unknown): value is AnimationDriverLike {
+  if (typeof value !== 'object' || value === null) return false
+  if ('isStub' in value && value.isStub === true) return true
+  return 'useAnimations' in value && typeof value.useAnimations === 'function'
+}
 
 /**
- * Resolves a value that might be an AnimationDriver or a multi-driver config object
- * like { default: motionDriver, css: cssDriver } into an actual AnimationDriver.
+ * Resolves a value that might be an animation driver or a multi-driver config
+ * object like { default: motionDriver, css: cssDriver } into a driver.
  */
 export function resolveAnimationDriver(
-  driver: AnimationDriver | Record<string, AnimationDriver> | null | undefined
-): AnimationDriver | null {
+  driver: AnimationDriverLike | Record<string, AnimationDriverLike> | null | undefined
+): AnimationDriverLike | null {
   if (!driver) return null
-  // valid driver
-  if (typeof (driver as any).useAnimations === 'function') {
-    return driver as AnimationDriver
+  // valid driver, including an explicit unsupported stub
+  if (isAnimationDriver(driver)) {
+    return driver
   }
   // multi-driver object - extract default
-  if (
-    'default' in driver &&
-    typeof (driver as any).default?.useAnimations === 'function'
-  ) {
-    return (driver as any).default
+  if ('default' in driver && isAnimationDriver(driver.default)) {
+    return driver.default
   }
   return null
 }

package/src/helpers/resolveSafeArea.native.ts

@@ -1,18 +1,98 @@
-const safeAreaEdges: Record<string, 'top' | 'bottom' | 'left' | 'right'> = {
-  $safeAreaTop: 'top',
-  $safeAreaBottom: 'bottom',
-  $safeAreaLeft: 'left',
-  $safeAreaRight: 'right',
+// safe-area value resolution (native).
+//
+// reads insets from the global state set up by @tamagui/native/setup-safe-area
+// (which keeps react-native-safe-area-context's provider snapshot in
+// globalThis.__tamagui_safe_area__).
+//
+// access is via the global rather than a direct import to avoid a circular
+// dependency between @tamagui/core and @tamagui/native.
+
+type Edge = 'top' | 'bottom' | 'left' | 'right'
+
+const propEdges: Record<string, Edge | Edge[]> = {
+  padding: ['top', 'right', 'bottom', 'left'],
+  paddingTop: 'top',
+  paddingBottom: 'bottom',
+  paddingLeft: 'left',
+  paddingRight: 'right',
+  paddingHorizontal: ['left', 'right'],
+  paddingVertical: ['top', 'bottom'],
+  paddingStart: 'left',
+  paddingEnd: 'right',
+  paddingBlock: ['top', 'bottom'],
+  paddingInline: ['left', 'right'],
+  paddingBlockStart: 'top',
+  paddingBlockEnd: 'bottom',
+  paddingInlineStart: 'left',
+  paddingInlineEnd: 'right',
+  margin: ['top', 'right', 'bottom', 'left'],
+  marginTop: 'top',
+  marginBottom: 'bottom',
+  marginLeft: 'left',
+  marginRight: 'right',
+  marginHorizontal: ['left', 'right'],
+  marginVertical: ['top', 'bottom'],
+  marginStart: 'left',
+  marginEnd: 'right',
+  marginBlock: ['top', 'bottom'],
+  marginInline: ['left', 'right'],
+  marginBlockStart: 'top',
+  marginBlockEnd: 'bottom',
+  marginInlineStart: 'left',
+  marginInlineEnd: 'right',
+  inset: ['top', 'right', 'bottom', 'left'],
+  top: 'top',
+  bottom: 'bottom',
+  left: 'left',
+  right: 'right',
+  start: 'left',
+  end: 'right',
+}
+
+const edgeToPascal: Record<Edge, string> = {
+  top: 'Top',
+  bottom: 'Bottom',
+  left: 'Left',
+  right: 'Right',
 }
 
-export function resolveSafeAreaValue(value: string): number | undefined {
-  const edge = safeAreaEdges[value]
-  if (!edge) return undefined
+const baseKeyForExpansion: Record<string, string> = {
+  padding: 'padding',
+  paddingHorizontal: 'padding',
+  paddingVertical: 'padding',
+  paddingBlock: 'padding',
+  paddingInline: 'padding',
+  margin: 'margin',
+  marginHorizontal: 'margin',
+  marginVertical: 'margin',
+  marginBlock: 'margin',
+  marginInline: 'margin',
+  inset: '',
+}
 
+function getInsetForEdge(edge: Edge): number {
   const g = globalThis as any
-  const state = g.__tamagui_native_safe_area_state__
+  // matches createGlobalState('safe_area', ...) in @tamagui/native
+  const state = g.__tamagui_safe_area__
   if (state?.enabled && state.initialMetrics) {
-    return state.initialMetrics.insets[edge]
+    return state.initialMetrics.insets[edge] ?? 0
   }
   return 0
 }
+
+export function isSafeAreaKey(key: string): boolean {
+  return key in propEdges
+}
+
+export function expandSafeAreaValue(key: string): Array<[string, number]> | undefined {
+  const edges = propEdges[key]
+  if (!edges) return undefined
+  if (typeof edges === 'string') {
+    return [[key, getInsetForEdge(edges)]]
+  }
+  const base = baseKeyForExpansion[key]
+  if (base === '') {
+    return edges.map((e) => [e, getInsetForEdge(e)])
+  }
+  return edges.map((e) => [`${base}${edgeToPascal[e]}`, getInsetForEdge(e)])
+}

package/src/helpers/resolveSafeArea.ts

@@ -1,10 +1,116 @@
-const safeAreaTokens: Record<string, string> = {
-  $safeAreaTop: 'env(safe-area-inset-top)',
-  $safeAreaBottom: 'env(safe-area-inset-bottom)',
-  $safeAreaLeft: 'env(safe-area-inset-left)',
-  $safeAreaRight: 'env(safe-area-inset-right)',
+// safe-area value resolution.
+//
+// when a user writes e.g. <View pt="safe" /> or <View padding="safe" />,
+// this maps the value to env(safe-area-inset-*) on web, and to numeric
+// insets on native (see resolveSafeArea.native.ts).
+//
+
+type Edge = 'top' | 'bottom' | 'left' | 'right'
+
+// map prop name -> which edge(s) it covers.
+// single-edge props map to one edge; multi-edge props (padding, inset, ...)
+// map to multiple edges and get expanded.
+//
+// keys here are AFTER shorthand expansion (pt -> paddingTop, etc).
+const propEdges: Record<string, Edge | Edge[]> = {
+  // padding
+  padding: ['top', 'right', 'bottom', 'left'],
+  paddingTop: 'top',
+  paddingBottom: 'bottom',
+  paddingLeft: 'left',
+  paddingRight: 'right',
+  paddingHorizontal: ['left', 'right'],
+  paddingVertical: ['top', 'bottom'],
+  paddingStart: 'left',
+  paddingEnd: 'right',
+  paddingBlock: ['top', 'bottom'],
+  paddingInline: ['left', 'right'],
+  paddingBlockStart: 'top',
+  paddingBlockEnd: 'bottom',
+  paddingInlineStart: 'left',
+  paddingInlineEnd: 'right',
+  // margin
+  margin: ['top', 'right', 'bottom', 'left'],
+  marginTop: 'top',
+  marginBottom: 'bottom',
+  marginLeft: 'left',
+  marginRight: 'right',
+  marginHorizontal: ['left', 'right'],
+  marginVertical: ['top', 'bottom'],
+  marginStart: 'left',
+  marginEnd: 'right',
+  marginBlock: ['top', 'bottom'],
+  marginInline: ['left', 'right'],
+  marginBlockStart: 'top',
+  marginBlockEnd: 'bottom',
+  marginInlineStart: 'left',
+  marginInlineEnd: 'right',
+  // inset
+  inset: ['top', 'right', 'bottom', 'left'],
+  top: 'top',
+  bottom: 'bottom',
+  left: 'left',
+  right: 'right',
+  start: 'left',
+  end: 'right',
+}
+
+const envForEdge: Record<Edge, string> = {
+  top: 'env(safe-area-inset-top)',
+  bottom: 'env(safe-area-inset-bottom)',
+  left: 'env(safe-area-inset-left)',
+  right: 'env(safe-area-inset-right)',
+}
+
+// is this prop key safe-area-aware?
+export function isSafeAreaKey(key: string): boolean {
+  return key in propEdges
+}
+
+// resolve key="safe" -> array of [edge-key, value] pairs.
+// returns undefined if key isn't safe-area-aware.
+export function expandSafeAreaValue(key: string): Array<[string, string]> | undefined {
+  const edges = propEdges[key]
+  if (!edges) return undefined
+  if (typeof edges === 'string') {
+    return [[key, envForEdge[edges]]]
+  }
+  // multi-edge: expand to per-side keys.
+  // for padding/margin: padding + edgePascal = paddingTop etc.
+  // for inset: emit bare top/right/bottom/left (the actual CSS sides).
+  const base = baseKeyForExpansion[key]
+  if (base === '') {
+    return edges.map((e) => [edgeToSideKey[e], envForEdge[e]])
+  }
+  return edges.map((e) => [`${base}${edgeToPascal[e]}`, envForEdge[e]])
+}
+
+const edgeToPascal: Record<Edge, string> = {
+  top: 'Top',
+  bottom: 'Bottom',
+  left: 'Left',
+  right: 'Right',
+}
+
+const edgeToSideKey: Record<Edge, string> = {
+  top: 'top',
+  bottom: 'bottom',
+  left: 'left',
+  right: 'right',
 }
 
-export function resolveSafeAreaValue(value: string): string | undefined {
-  return safeAreaTokens[value]
+// for each multi-edge prop, what's the base name to prepend Top/Bottom/etc?
+// '' = no prefix (use bare edge names like 'top', 'left')
+const baseKeyForExpansion: Record<string, string> = {
+  padding: 'padding',
+  paddingHorizontal: 'padding',
+  paddingVertical: 'padding',
+  paddingBlock: 'padding',
+  paddingInline: 'padding',
+  margin: 'margin',
+  marginHorizontal: 'margin',
+  marginVertical: 'margin',
+  marginBlock: 'margin',
+  marginInline: 'margin',
+  inset: '',
 }

package/src/helpers/resolveSafeAreaVariable.native.ts

@@ -0,0 +1,28 @@
+import { getSafeArea } from '@tamagui/native'
+
+let didWarnMissingSetup = false
+
+export function resolveSafeAreaVariable(name: string): number | undefined {
+  const edge = name.startsWith('safe-area-') ? name.slice(10) : ''
+  if (edge !== 'top' && edge !== 'right' && edge !== 'bottom' && edge !== 'left') {
+    return
+  }
+
+  const safeArea = getSafeArea()
+  const state = safeArea.state
+  if (!state.didSetup) {
+    if (process.env.NODE_ENV !== 'production' && !didWarnMissingSetup) {
+      didWarnMissingSetup = true
+      console.warn(
+        '[tamagui] safe-area variables on native require importing @tamagui/native/setup-safe-area and wrapping the app in the SafeAreaProvider from react-native-safe-area-context.'
+      )
+    }
+    return 0
+  }
+
+  return state.enabled ? (state.initialMetrics?.insets[edge] ?? 0) : 0
+}
+
+export function subscribeToSafeArea(listener: () => void): () => void {
+  return getSafeArea().subscribe(listener)
+}

package/src/helpers/resolveSafeAreaVariable.ts

@@ -0,0 +1,10 @@
+export function resolveSafeAreaVariable(name: string): string | undefined {
+  const edge = name.startsWith('safe-area-') ? name.slice(10) : ''
+  return edge === 'top' || edge === 'right' || edge === 'bottom' || edge === 'left'
+    ? `env(safe-area-inset-${edge})`
+    : undefined
+}
+
+export function subscribeToSafeArea(_listener: () => void): (() => void) | undefined {
+  return undefined
+}

package/src/helpers/resolveVariableValue.ts

@@ -0,0 +1,31 @@
+import { isVariable } from '../createVariable'
+import type { ResolveVariableAs, Variable } from '../types'
+
+export function resolveVariableValue(
+  key: string,
+  valOrVar: Variable | any,
+  resolveValues?: ResolveVariableAs
+) {
+  if (resolveValues === 'none') {
+    return valOrVar
+  }
+  if (isVariable(valOrVar)) {
+    if (resolveValues === 'value') {
+      return valOrVar.val
+    }
+
+    // @ts-expect-error dynamic variables may expose a platform-aware getter
+    const get = valOrVar?.get
+
+    // shadowColor doesn't support dynamic style
+    if (process.env.TAMAGUI_TARGET !== 'native' || key !== 'shadowColor') {
+      if (typeof get === 'function') {
+        const resolveDynamicFor = resolveValues === 'web' ? 'web' : undefined
+        return get(resolveDynamicFor)
+      }
+    }
+
+    return process.env.TAMAGUI_TARGET === 'native' ? valOrVar.val : valOrVar.variable
+  }
+  return valOrVar
+}

package/src/helpers/skipProps.ts

@@ -10,13 +10,15 @@ export const skipProps = {
   space: 1,
   animateOnly: 1,
   animatedBy: 1,
+  displayName: 1,
   disableClassName: 1,
   debug: 1,
-  componentName: 1,
   disableOptimization: 1,
+  disableNativeStyle: 1,
   render: 1,
-  style: 1, // handled after loop so pseudos set usedKeys and override it if necessary
+  style: 1, // handled after the prop loop to preserve authored order
   group: 1,
+  container: 1,
   animatePresence: 1,
 }
 
@@ -24,6 +26,10 @@ if (process.env.NODE_ENV === 'test') {
   skipProps['data-test-renders'] = 1
 }
 
+if (process.env.NODE_ENV === 'development') {
+  skipProps['__tamaguiStyleDebugReceipt'] = 1
+}
+
 // Skip web-only props on native
 if (process.env.TAMAGUI_TARGET === 'native') {
   Object.assign(skipProps, webPropsToSkip)

package/src/helpers/styleFrontend.ts

@@ -0,0 +1,104 @@
+import type { GrammarSourceConfig } from '@tamagui/style-grammar/runtime'
+import type { FunctionComponent } from 'react'
+
+/**
+ * The configuration a style frontend reads. It is the shared grammar's own
+ * dependency-free projection, narrowed so `media` and `themes` are the name-keyed
+ * records a frontend classifies modifiers against. A real `TamaguiInternalConfig`
+ * satisfies it structurally, and declaring a frontend never pulls core's config or
+ * style-prop type graph in.
+ */
+export type StyleFrontendConfig = Omit<GrammarSourceConfig, 'media' | 'themes'> & {
+  media?: Readonly<Record<string, unknown>>
+  themes?: Readonly<Record<string, unknown>>
+}
+
+/**
+ * The parts of a component's static configuration a frontend authors or rewrites.
+ * Everything else on the real `StaticConfig` is the shared runtime's and passes
+ * through untouched, which is why `normalizeStaticConfig` is generic in the config
+ * it is handed.
+ */
+export type FrontendStaticConfig = {
+  /** frontend-specific static style input, e.g. a Tailwind class string base */
+  baseClassName?: string
+  baseStyle?: Record<string, any>
+  /**
+   * Classes from `baseClassName` that the frontend did not claim. They stay a raw
+   * class string so the app's own CSS still applies them, and they are kept out of
+   * `baseStyle` because that object holds styles only.
+   */
+  passthroughClassName?: string
+  variants?: Record<string, Record<string, any>>
+  compoundVariants?: readonly Record<string, any>[]
+  styleFrontend?: StyleFrontend
+}
+
+/**
+ * What the internal View/Text factory and a frontend-bound `styled()` hand back: an
+ * opaque component object carrying its static config. Deliberately not core's
+ * `TamaguiComponent`, so a frontend's declarations never gain the regular style prop
+ * graph. The frontend re-types it with its own public props.
+ */
+export type FrontendComponent = FunctionComponent<any> & {
+  staticConfig: FrontendStaticConfig
+}
+
+/**
+ * A component's authoring syntax. It is chosen by the package the component was
+ * imported from and frozen onto its static config when the component is created:
+ * there is no global setting, no registry, and no runtime lookup.
+ *
+ * Regular `@tamagui/core` components carry no descriptor and use
+ * `regularStyleFrontend`. `@tamagui/tailwind` builds its components with its own
+ * descriptor, which owns class-string tokenization and candidate adaptation.
+ *
+ * The renderer below the descriptor is shared: property/value program parsing,
+ * contribution, merging, web lowering, and native evaluation all stay in core.
+ */
+export type StyleFrontend = {
+  /**
+   * Turns authored props into the neutral props the shared renderer consumes.
+   * Runs once per render in `createComponent`, before component state is derived,
+   * because reconstructed enter/exit, pseudo, media and related state props must
+   * exist before the animation and state machinery reads them.
+   */
+  preprocessProps: (
+    props: Record<string, any>,
+    config: StyleFrontendConfig
+  ) => Record<string, any>
+
+  /**
+   * Resolves frontend-specific static style input (a class-string base, string
+   * variant values, string compound-variant styles) into ordinary style objects.
+   * Called once per (staticConfig, config) pair; implementations memoize.
+   */
+  normalizeStaticConfig?: <Config extends FrontendStaticConfig>(
+    staticConfig: Config,
+    config: StyleFrontendConfig
+  ) => Config
+}
+
+/**
+ * Marks props that already went through `preprocessProps`, so the style split does
+ * not tokenize a second time. A Symbol key is invisible to the `for..in` prop loop,
+ * so it never leaks into style processing.
+ */
+export const STYLE_FRONTEND_PREPROCESSED: unique symbol = Symbol(
+  'tamaguiStyleFrontendPreprocessed'
+)
+
+/**
+ * Internal ordered-prop channel for raw CSS classes a frontend does not own.
+ * Numbered keys let passthrough segments keep their exact position among claimed
+ * style contributions while the shared renderer still handles them as className.
+ */
+export const STYLE_FRONTEND_PASSTHROUGH_PREFIX = '__tamagui_frontend_passthrough_'
+
+/**
+ * The regular Tamagui frontend: props are already the renderer's input shape, so
+ * preprocessing is identity and costs one property read plus one call.
+ */
+export const regularStyleFrontend: StyleFrontend = {
+  preprocessProps: (props) => props,
+}

package/src/helpers/styleProvenance.ts

@@ -4,7 +4,7 @@
 //
 // this is a pure inspection side channel. it records, per resolved style key,
 // which token produced the value and the full theme name that resolved it
-// (e.g. { backgroundColor: { token: '$background', theme: 'light_accent' } }).
+// (e.g. { backgroundColor: { token: 'background', theme: 'light_accent' } }).
 // a literal value produces NO entry, which is how a literal that happens to
 // equal a token value stays distinguishable from the token.
 //
@@ -24,7 +24,7 @@ export const STYLE_TOKEN_PROVENANCE_KEY = 'tamagui.styleTokenProvenance'
 const provenanceSymbol = /* @__PURE__ */ Symbol.for(STYLE_TOKEN_PROVENANCE_KEY)
 
 export type StyleTokenBinding = {
-  /** original token string before resolution, e.g. '$background' or '$color9' */
+  /** original token string before resolution, e.g. 'background' or 'color9' */
   token: string
   /** full resolved theme name that produced the value, e.g. 'light_accent' */
   theme: string
@@ -32,6 +32,21 @@ export type StyleTokenBinding = {
 
 export type StyleTokenProvenance = Record<string, StyleTokenBinding>
 
+export type StyleDebugTier = 'lowered' | 'flattened' | 'styled' | 'bailed'
+
+export type StyleDebugReceipt = {
+  component: string
+  tiers: StyleDebugTier[]
+  why: string
+  styles: {
+    prop: string
+    tier: StyleDebugTier
+    why: string
+    dropped?: true
+    runtime?: true
+  }[]
+}
+
 export function setStyleTokenProvenance(style: object, provenance: StyleTokenProvenance) {
   Object.defineProperty(style, provenanceSymbol, {
     value: provenance,