@rootnative/inertia 0.0.3 → 0.0.4

package/dist/{types-G1dBU2IQ.d.ts → types-37pN82yh.d.ts}

@@ -1,5 +1,5 @@
 import { ComponentType, ComponentProps, Ref, ReactElement } from 'react';
-import { StyleProp } from 'react-native';
+import { StyleProp, BoxShadowValue } from 'react-native';
 
 /**
  * A single animation step's destination, optionally overriding the transition
@@ -154,6 +154,36 @@ type AnimatableTransformExtras = {
     rotateX?: AnimatableValue<number>;
     rotateY?: AnimatableValue<number>;
 };
+/**
+ * Target shape for the `boxShadow` key on `animate` / `initial` / `exit`: a
+ * CSS `box-shadow` string, or RN's own array-of-layers form.
+ *
+ * Both endpoints of a `boxShadow` animation are normalized to a common layer
+ * count on the JS thread, so a two-layer shadow can animate to a one-layer one
+ * (the short side is padded with a transparent layer, as CSS transitions do).
+ * A layer that is `inset` on one side and not the other is not interpolable
+ * and throws.
+ */
+type BoxShadowInput = string | ReadonlyArray<BoxShadowValue>;
+/**
+ * Keys whose animatable form deliberately departs from the generic
+ * `AnimatableValue<S[K]>` mapping.
+ *
+ * `boxShadow` is the only member. Its natural value is already an array, which
+ * collides head-on with `AnimatableValue`'s keyframe-sequence form — nothing
+ * distinguishes `[layerA, layerB]` (one two-layer shadow) from a two-step
+ * sequence. The array slot is given to layers, which is the shape RN itself
+ * uses and by far the common case, and sequences are unsupported on this key.
+ * This mirrors the single-value-only contract `shadowOffset` has carried since
+ * `0.0.1`. Per-property transitions are unaffected: `transition={{ boxShadow:
+ * { type: 'timing' } }}` works as it does for every other key.
+ *
+ * Conditional on `S` so the key only appears where the underlying style
+ * actually has it, rather than being bolted onto every primitive.
+ */
+type AnimatableStructuredExtras<S> = 'boxShadow' extends keyof S ? {
+    boxShadow?: BoxShadowInput;
+} : {};
 /**
  * The animation state shape inferred from the underlying component's style
  * prop. We narrow to the value side of `style` so consumers see ViewStyle on
@@ -168,9 +198,9 @@ type AnimatableTransformExtras = {
 type _StyleValue<T> = Exclude<T, (...args: any[]) => any>;
 type AnimateStyle<C> = C extends {
     style?: infer Raw;
-} ? _StyleValue<Raw> extends StyleProp<infer S> ? {
+} ? _StyleValue<Raw> extends StyleProp<infer S> ? Omit<{
     [K in keyof S]?: AnimatableValue<S[K]>;
-} & AnimatableTransformExtras : never : never;
+}, 'boxShadow'> & AnimatableTransformExtras & AnimatableStructuredExtras<S> : never : never;
 interface AnimationCallbackInfo<S> {
     /**
      * The animatable key that just settled — typically a `keyof S` (e.g.
@@ -339,19 +369,24 @@ interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
      * recorded rect to its natural position via a FLIP transform stack.
      *
      * Reanimated 4 removed the `sharedTransitionTag` API — `layoutId` is the
-     * Inertia-side measure-based replacement. Rects are recorded in
-     * parent-relative coordinates (from `onLayout`), which composes when the
-     * source and target screens share an outer content container (the common
-     * stack-navigator case); nested-parent layouts need the v2
-     * window-coordinate path.
+     * Inertia-side measure-based replacement. Rects are recorded in **window**
+     * coordinates wherever the host can be measured synchronously (Fabric),
+     * which is what lets a source and target sit under containers at different
+     * screen offsets; elsewhere both fall back to the parent-relative
+     * coordinates `onLayout` reports. A source and target that ended up in
+     * different spaces skip the animation rather than play a wrong one.
      *
      * The same `transition` prop drives the FLIP animation (spring by
      * default; `'timing'` honored; `'decay'` downgrades to spring; reduced
-     * motion skips the transition). Out of scope for the first iteration:
-     * style-prop interpolation (border radius, colors, etc.) — only the
-     * rect-to-rect transform is animated. Two simultaneously-mounted
-     * primitives sharing the same `layoutId` are undefined behavior; pick a
-     * primitive per id at a time.
+     * motion skips the transition). Alongside the rect, a fixed set of style
+     * keys is carried from the source and crossfaded out on that same
+     * transition: `opacity`, `borderRadius`, `backgroundColor`, `borderColor`,
+     * `color`, `tintColor`. Transform keys are not carried — the FLIP owns
+     * them — and a key only participates when the element already has a value
+     * for it, from a record or from its static `style`.
+     *
+     * Two simultaneously-mounted primitives sharing the same `layoutId` are
+     * undefined behavior; pick a primitive per id at a time.
      */
     layoutId?: string;
     /**
@@ -385,4 +420,4 @@ interface MotionComponent<C extends ComponentType<any>> {
     displayName?: string;
 }
 
-export type { AnimatableValue as A, DecayTransition as D, EasingInput as E, GestureLayerTransitions as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionConfig as T, VariantController as V, TransitionInput as a, TransitionName as b, AnimateStyle as c, AnimationCallbackInfo as d, EasingFunction as e, EasingFunctionFactory as f, GestureSubStates as g, MotionProps as h, NoAnimationTransition as i, RepeatConfig as j, SequenceStep as k, TimingTransition as l, Transition as m, VariantsMap as n };
+export type { AnimatableValue as A, BoxShadowInput as B, DecayTransition as D, EasingInput as E, GestureLayerTransitions as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionConfig as T, VariantController as V, TransitionInput as a, TransitionName as b, AnimateStyle as c, AnimationCallbackInfo as d, EasingFunction as e, EasingFunctionFactory as f, GestureSubStates as g, MotionProps as h, NoAnimationTransition as i, RepeatConfig as j, SequenceStep as k, TimingTransition as l, Transition as m, VariantsMap as n };

package/dist/{useGesture-D1e4ixJo.d.ts → useGesture-Cl4uzZIr.d.ts}

@@ -1,5 +1,5 @@
 import { SharedValue } from 'react-native-reanimated';
-import { a as TransitionInput, G as GestureLayerTransitions } from './types-G1dBU2IQ.js';
+import { a as TransitionInput, G as GestureLayerTransitions } from './types-37pN82yh.js';
 
 /**
  * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the

package/dist/{useGesture-RFY6kTL3.d.mts → useGesture-_IKkS8Dv.d.mts}

@@ -1,5 +1,5 @@
 import { SharedValue } from 'react-native-reanimated';
-import { a as TransitionInput, G as GestureLayerTransitions } from './types-G1dBU2IQ.mjs';
+import { a as TransitionInput, G as GestureLayerTransitions } from './types-37pN82yh.mjs';
 
 /**
  * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the

package/llms.txt

@@ -140,7 +140,9 @@ Color: `backgroundColor`, `borderColor`, `color`, `tintColor` (Image only), `sha
 
 Nested object: `shadowOffset: { width, height }`. The only nested-object style on the surface — internally decomposes into two synthetic axis SVs that the worklet recomposes into a single `shadowOffset` prop. `0.0.1` supports the **single-value form only** (`{ width: 0, height: 4 }`); sequences / array keyframes / per-axis transition splits are out of scope, drop to `useMotionValue` for those.
 
-Auto-layout transitions ship via the `layout` prop (`true` / `TransitionConfig`) on every `Motion.*` primitive — see Layout. Shared element transitions ship via the `layoutId` prop: pair the same id on a source and target `Motion.*` and Inertia FLIPs between them on mount (parent-relative coords, rect-only animation, 1s TTL).
+Structured: `boxShadow` — the cross-platform CSS shadow form, as a CSS string (`'0px 4px 8px rgba(0,0,0,0.3)'`, px lengths only) or RN's `BoxShadowValue[]`. Endpoints are normalized on the JS thread and padded to a common layer count (CSS-transition semantics), so layer counts may differ between `initial` and `animate`; every length and color interpolates per layer. `inset` is carried as a static per-layer flag, not interpolated — a layer inset on one side only throws. **No sequences on this key** (the array slot means layers, not keyframes) and **not accepted in `gesture` sub-states** (dev-warns and is ignored; drive it from `animate`, or interpolate manually with `useShadow`). Don't animate it alongside the native `shadow*` keys on one element — two shadow systems at once; Inertia dev-warns.
+
+Auto-layout transitions ship via the `layout` prop (`true` / `TransitionConfig`) on every `Motion.*` primitive — see Layout. Shared element transitions ship via the `layoutId` prop: pair the same id on a source and target `Motion.*` and Inertia FLIPs between them on mount (1s TTL). Alongside the rect, a fixed set of style keys is carried from the source and crossfaded out on the same transition — `opacity`, `borderRadius`, `backgroundColor`, `borderColor`, `color`, `tintColor` — but only for keys the element already has a value for, from a record or its static `style`; transform keys are not carried because the FLIP owns them. Rects are measured in **window** coordinates via `measureInWindow` where the host resolves it synchronously (Fabric), which is what lets source and target sit under differently-offset parents; elsewhere both fall back to parent-relative `onLayout` coords. A source and target in different coordinate spaces skip the animation rather than play a wrong one. A still-mounted source is re-measured when the target lays out, so an ancestor scroll (which never fires `onLayout`) doesn't offset the transition.
 
 ## Optional adapter packages
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootnative/inertia",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Declarative animation primitives for React Native, built on react-native-reanimated.",
   "license": "MIT",
   "author": "RootNative",

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * `@rootnative/inertia` — declarative animation primitives for React Native.
  *
- * v0.1 surface: `Motion.View` / `Motion.Text` / `Motion.Image` /
+ * Public surface: `Motion.View` / `Motion.Text` / `Motion.Image` /
  * `Motion.Pressable` / `Motion.ScrollView`, with `initial` / `animate` /
  * `exit` / `transition` / `variants` / `gesture` / `controller` /
  * `onAnimationEnd` props. Sequences, repeats (single-value and
@@ -82,6 +82,7 @@ export type {
   AnimatableValue,
   AnimateStyle,
   AnimationCallbackInfo,
+  BoxShadowInput,
   DecayTransition,
   EasingFunction,
   EasingFunctionFactory,

package/src/internal/boxShadow.ts

@@ -144,17 +144,24 @@ export function parseBoxShadow(input: string): ResolvedBoxShadowLayer[] {
   })
 }
 
-/** Resolve either input form (CSS string or structured layers) to layers. */
+/**
+ * Resolve either input form (CSS string or structured layers) to layers.
+ *
+ * Lengths may arrive as numbers (what `useShadow`'s `BoxShadowLayer` declares)
+ * or as px strings (what RN's own `BoxShadowValue` permits, so what the
+ * `animate` surface has to accept). `coerceLength` normalizes both and rejects
+ * anything else, so downstream only ever sees concrete numbers.
+ */
 export function resolveBoxShadowInput(
-  input: string | readonly BoxShadowLayer[] | undefined,
+  input: BoxShadowInput | undefined,
 ): ResolvedBoxShadowLayer[] {
   if (input === undefined) return []
   if (typeof input === 'string') return parseBoxShadow(input)
   return input.map((layer) => ({
-    offsetX: layer.offsetX,
-    offsetY: layer.offsetY,
-    blurRadius: layer.blurRadius ?? 0,
-    spreadDistance: layer.spreadDistance ?? 0,
+    offsetX: coerceLength(layer.offsetX, 'offsetX'),
+    offsetY: coerceLength(layer.offsetY, 'offsetY'),
+    blurRadius: coerceLength(layer.blurRadius, 'blurRadius'),
+    spreadDistance: coerceLength(layer.spreadDistance, 'spreadDistance'),
     color: layer.color ?? 'black',
     inset: layer.inset ?? false,
   }))
@@ -202,3 +209,167 @@ function invisibleLayer(inset: boolean): ResolvedBoxShadowLayer {
     inset,
   }
 }
+
+/* ------------------------------------------------------------------ *
+ * Declarative `animate={{ boxShadow }}` support
+ *
+ * The `useShadow` path above interpolates two endpoints itself, by
+ * progress. The `animate` path instead hands the target to Reanimated's
+ * own animation drivers, which have their own rules — the helpers below
+ * exist to satisfy them on the JS thread so the worklet never does string
+ * or structural work at frame time (Principle 8).
+ * ------------------------------------------------------------------ */
+
+/**
+ * The interpolable half of a box-shadow layer: every field Reanimated can
+ * drive, and nothing it can't.
+ *
+ * `inset` is deliberately absent. `withTiming` / `withSpring` recurse into
+ * arrays and objects and animate each leaf, and a boolean leaf falls through
+ * to the plain numeric path — `false + (false - false) * p` evaluates to `0`,
+ * so an in-flight frame hands the native shadow a number where it expects a
+ * boolean. Inset is instead carried alongside as a static per-layer flag (see
+ * `SplitBoxShadow.insets`) and reattached when the style is emitted.
+ */
+export interface AnimatedBoxShadowLayer {
+  offsetX: number
+  offsetY: number
+  blurRadius: number
+  spreadDistance: number
+  color: string
+}
+
+/**
+ * Resolved layers split into the part Reanimated animates and the part it
+ * must not touch.
+ *
+ * `insets` is `null` — not an array of `false` — when no layer is inset, which
+ * is the overwhelmingly common case. That lets the emitting worklet skip
+ * reassembly entirely and pass the animated array straight through with zero
+ * per-frame allocation.
+ */
+export interface SplitBoxShadow {
+  layers: AnimatedBoxShadowLayer[]
+  insets: boolean[] | null
+}
+
+/**
+ * Accepted target shape on the `animate` surface: a CSS string or RN's own
+ * `BoxShadowValue[]`, whose lengths may be numbers or px strings.
+ *
+ * Structurally this is RN's `boxShadow` style value. It is restated here
+ * rather than imported so this module stays dependency-free and testable as a
+ * pure function; `types.ts` is where the public-facing alias lives.
+ */
+export type BoxShadowInput =
+  | string
+  | ReadonlyArray<{
+      offsetX: number | string
+      offsetY: number | string
+      // `unknown` because RN types this as `ColorValue | number` — a quirk of
+      // its own declarations rather than a real capability. Coerced (and
+      // rejected) by `coerceLength` like every other length.
+      blurRadius?: unknown
+      spreadDistance?: number | string | undefined
+      color?: string | undefined
+      inset?: boolean | undefined
+    }>
+
+/**
+ * Coerce one RN length field to a number. RN's `BoxShadowValue` types its
+ * lengths as `number | string` so `{ offsetX: '4px' }` is legal input; the
+ * animated slot needs a plain number to interpolate. Unit handling matches
+ * `parseBoxShadow` — px and unitless only, and anything else throws rather
+ * than silently animating from a `NaN`.
+ */
+function coerceLength(value: unknown, field: string): number {
+  if (value === undefined) return 0
+  if (typeof value === 'number') return value
+  const trimmed = typeof value === 'string' ? value.trim() : ''
+  if (!LENGTH.test(trimmed)) {
+    throw new Error(
+      `[inertia] boxShadow: ${field} must be a number or a px length, got ` +
+        `${JSON.stringify(value)}.`,
+    )
+  }
+  return parseFloat(trimmed)
+}
+
+/** Drop `inset`, leaving only the fields Reanimated may drive. */
+function strip(layer: ResolvedBoxShadowLayer): AnimatedBoxShadowLayer {
+  const { inset: _inset, ...rest } = layer
+  return rest
+}
+
+/**
+ * Record layer `i` as inset, materializing the flag list on first use so the
+ * common all-outset case keeps `null` and costs the worklet nothing.
+ */
+function markInset(
+  insets: boolean[] | null,
+  i: number,
+  count: number,
+): boolean[] {
+  const list = insets ?? new Array<boolean>(count).fill(false)
+  list[i] = true
+  return list
+}
+
+/**
+ * Normalize a target into the shared-value seed shape. Used when the slot is
+ * first populated (mount seed, static-style resting value).
+ */
+export function normalizeBoxShadow(input: BoxShadowInput): SplitBoxShadow {
+  const resolved = resolveBoxShadowInput(input)
+  const layers: AnimatedBoxShadowLayer[] = []
+  let insets: boolean[] | null = null
+  for (let i = 0; i < resolved.length; i++) {
+    const layer = resolved[i]!
+    layers.push(strip(layer))
+    if (layer.inset) insets = markInset(insets, i, resolved.length)
+  }
+  return { layers, insets }
+}
+
+/**
+ * Prepare a from/to pair for a Reanimated-driven `boxShadow` animation.
+ *
+ * Both sides come back padded to the same layer count, because Reanimated's
+ * `arrayOnStart` walks the **current** value's indices and reads `toValue[i]`
+ * for each — a target with fewer layers leaves the surplus leaves with
+ * `toValue: undefined`, and a target with more never animates the extras at
+ * all. `pairBoxShadowLayers` supplies the padding (a transparent zero layer,
+ * matching CSS transition semantics) and rejects a genuine inset mismatch.
+ *
+ * The returned `from` is only meaningful when it differs from what the slot
+ * already holds; callers snap the slot to it before starting the animation so
+ * the interpolation has a same-shaped base to run from.
+ */
+export function prepareBoxShadowAnimation(
+  current: SplitBoxShadow,
+  target: BoxShadowInput,
+): {
+  from: AnimatedBoxShadowLayer[]
+  to: AnimatedBoxShadowLayer[]
+  insets: boolean[] | null
+} {
+  const pairs = pairBoxShadowLayers(
+    current.layers.map((layer, i) => ({
+      ...layer,
+      inset: current.insets?.[i] ?? false,
+    })),
+    resolveBoxShadowInput(target),
+  )
+  const from: AnimatedBoxShadowLayer[] = []
+  const to: AnimatedBoxShadowLayer[] = []
+  let insets: boolean[] | null = null
+  for (let i = 0; i < pairs.length; i++) {
+    const pair = pairs[i]!
+    from.push(strip(pair.from))
+    to.push(strip(pair.to))
+    // `pairBoxShadowLayers` has already established that the two sides agree
+    // on inset, so reading either describes the pair.
+    if (pair.to.inset) insets = markInset(insets, i, pairs.length)
+  }
+  return { from, to, insets }
+}

package/src/internal/nonWorkletWarning.ts

@@ -1,3 +1,5 @@
+import { __resetWarnOnceForTests, warnOnce } from './warnOnce'
+
 declare const __DEV__: boolean
 
 // The core package intentionally has no Node types — declare the minimal
@@ -5,8 +7,6 @@ declare const __DEV__: boolean
 // environments without `process` are fine).
 declare const process: { env?: Record<string, string | undefined> } | undefined
 
-const warned = new Set<string>()
-
 /**
  * Dev-only, once-per-key warning for plain (non-worklet) functions handed to
  * surfaces that need real worklets — `useTransform` transformers and custom
@@ -30,12 +30,10 @@ const warned = new Set<string>()
 export function warnNonWorkletOnce(key: string, message: string): void {
   if (!__DEV__) return
   if (typeof process !== 'undefined' && process.env?.JEST_WORKER_ID) return
-  if (warned.has(key)) return
-  warned.add(key)
-  console.warn(message)
+  warnOnce(key, message)
 }
 
 /** @internal — test-only hook to reset the once-per-key state. */
 export function __resetNonWorkletWarningsForTests(): void {
-  warned.clear()
+  __resetWarnOnceForTests()
 }

package/src/internal/warnOnce.ts

@@ -0,0 +1,28 @@
+declare const __DEV__: boolean
+
+const warned = new Set<string>()
+
+/**
+ * Dev-only warning that fires at most once per `key` for the lifetime of the
+ * module.
+ *
+ * Inertia's warnings mostly fire from render or from a per-frame-adjacent
+ * resolver, so an unguarded `console.warn` would repeat on every render and
+ * bury the signal. Keying the guard (rather than using a single boolean)
+ * keeps two genuinely different misconfigurations from silencing each other.
+ *
+ * Unlike `warnNonWorkletOnce`, this is **not** suppressed under Jest — these
+ * warnings describe consumer-authored prop combinations, which a test suite
+ * should be able to assert on.
+ */
+export function warnOnce(key: string, message: string): void {
+  if (!__DEV__) return
+  if (warned.has(key)) return
+  warned.add(key)
+  console.warn(message)
+}
+
+/** @internal — test-only hook to reset the once-per-key state. */
+export function __resetWarnOnceForTests(): void {
+  warned.clear()
+}

package/src/layout/index.ts

@@ -8,10 +8,20 @@ export {
   SHARED_LAYOUT_TTL_MS,
   __setSharedLayoutClock,
   __sharedRegistrySize,
+  type CoordinateSpace,
+  type SharedLayoutSource,
   type SharedRect,
+  type SharedStyleSnapshot,
 } from './sharedRegistry'
+export {
+  __setSharedLayoutMeasurer,
+  measureWindowRect,
+  type MeasuredRect,
+  type WindowMeasurer,
+} from './measureWindow'
 export {
   useSharedLayout,
   type SharedLayoutBindings,
+  type SharedLayoutStyleValues,
   type SharedLayoutValues,
 } from './useSharedLayout'

package/src/layout/measureWindow.ts

@@ -0,0 +1,135 @@
+import { type CoordinateSpace, type SharedRect } from './sharedRegistry'
+
+/**
+ * Window-coordinate measurement for shared-element rects.
+ *
+ * ## Synchronous or not at all
+ *
+ * `measureInWindow` is callback-shaped but not reliably asynchronous, and the
+ * difference decides this module's design:
+ *
+ * - **Fabric** (the default from RN 0.76, and our 0.81+ baseline) resolves it
+ *   through a synchronous JSI call — the callback runs before
+ *   `measureInWindow` returns.
+ * - **Paper** goes over the bridge, so the callback lands a tick later.
+ * - **A detached node calls back never at all.** Not an edge case and not a
+ *   platform quirk: `ReactFabricHostComponent.measureInWindow` looks the node
+ *   up and simply returns when it is missing. The Jest host mock behaves the
+ *   same way.
+ *
+ * So this module reads the result **synchronously or treats it as
+ * unavailable**, and ignores a callback that arrives late. That is not a
+ * limitation to work around — it is what keeps the coordinate space coherent.
+ * An implementation that awaited the callback would put Fabric in window space
+ * and Paper in parent space *for the same element at different moments*, and
+ * since the two spaces aren't comparable, a source stored in one and a target
+ * measured in the other silently skips the transition. Better to be
+ * consistently parent-relative on a platform that can't measure synchronously —
+ * which is exactly how this worked before window coordinates existed.
+ *
+ * Net effect: nested-parent shared elements are fixed on Fabric, and on Paper
+ * the behavior is unchanged rather than intermittently broken.
+ *
+ * ## Why the result is validated rather than trusted
+ *
+ * A node that is off-screen or laid out to nothing reports zeros (or `NaN` on
+ * some platforms) instead of failing. Feeding that into a FLIP would fling the
+ * element in from the top-left corner — far worse than not animating. Anything
+ * unusable is reported as `undefined` so the caller falls back to the
+ * parent-relative rect it already has.
+ */
+
+/** Raw measurement, before it is tagged with a coordinate space. */
+export interface MeasuredRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/**
+ * Measures `node` in window coordinates, or returns `undefined` when it can't
+ * be measured synchronously. Swappable for tests via
+ * `__setSharedLayoutMeasurer`.
+ */
+export type WindowMeasurer = (node: unknown) => MeasuredRect | undefined
+
+type MeasureInWindowNode = {
+  measureInWindow?: (
+    callback: (x: number, y: number, width: number, height: number) => void,
+  ) => void
+}
+
+const defaultMeasurer: WindowMeasurer = (node) => {
+  const measure = (node as MeasureInWindowNode | null)?.measureInWindow
+  if (typeof measure !== 'function') return undefined
+
+  let result: MeasuredRect | undefined
+  let returned = false
+  try {
+    measure.call(node, (x, y, width, height) => {
+      // A callback that arrives after we've returned is Paper's asynchronous
+      // bridge answering too late to use. Dropping it is deliberate: accepting
+      // it would upgrade this element to window space while its counterpart
+      // stays parent-relative, and mixed spaces cancel the transition.
+      if (returned) return
+      result = { x, y, width, height }
+    })
+  } catch {
+    // Some hosts throw rather than no-op on a detached node.
+    returned = true
+    return undefined
+  }
+  returned = true
+  return result
+}
+
+let measurer: WindowMeasurer = defaultMeasurer
+
+function usable(rect: MeasuredRect): boolean {
+  const { x, y, width, height } = rect
+  for (const v of [x, y, width, height]) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) return false
+  }
+  // Zero-sized means "not really measurable" in practice — detached, or laid
+  // out to nothing. Either way there is no FLIP to compute from it.
+  return width !== 0 || height !== 0
+}
+
+/**
+ * Measure `node` in window coordinates and tag the result, or return
+ * `undefined` when no usable synchronous measurement is available.
+ *
+ * Validation lives here rather than in the default measurer so a swapped-in
+ * measurer is held to the same contract — an unusable rect can never reach a
+ * FLIP, however it was produced.
+ */
+export function measureWindowRect(node: unknown): SharedRect | undefined {
+  const measured = measurer(node)
+  if (!measured || !usable(measured)) return undefined
+  return toSharedRect(measured, 'window')
+}
+
+/** Tag a raw measurement with its coordinate space. */
+export function toSharedRect(
+  rect: MeasuredRect,
+  space: CoordinateSpace,
+): SharedRect {
+  return { ...rect, space }
+}
+
+/**
+ * Test hook: swap the measurement implementation. Pass `undefined` to restore
+ * the real `measureInWindow` path. Not exported from the package root —
+ * reachable only from inside the workspace.
+ *
+ * Needed because the Jest host mock's `measureInWindow` never invokes its
+ * callback, so without an override every test would exercise only the
+ * parent-relative fallback — which is also, deliberately, what a consumer's
+ * test suite sees.
+ */
+export function __setSharedLayoutMeasurer(
+  fn: WindowMeasurer | undefined,
+): void {
+  measurer = fn ?? defaultMeasurer
+}