@userflow-tech/react-native 0.1.1 → 0.2.0

package/lib/typescript/commonjs/src/surfaces/cardTransition.d.ts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import { Animated } from 'react-native';
+/** Outgoing card leaves fast; the incoming one gets web's `opacity 250ms` feel. */
+export declare const CARD_EXIT_MS = 120;
+export declare const CARD_ENTER_MS = 200;
+export type CardTransitionPhase = 'entering' | 'exiting';
+export declare const CardTransitionProvider: React.Provider<CardTransitionPhase | null>;
+/**
+ * Phase of the surrounding step transition, or `null` outside one.
+ *
+ * Surfaces use this to hold side effects while they fade out: an exiting card is
+ * still mounted for `CARD_EXIT_MS`, and anything it measures or arms in that
+ * window belongs to a step the user has already left.
+ */
+export declare function useCardTransitionPhase(): CardTransitionPhase | null;
+/**
+ * Fade for a surface's card chrome, so step swaps move the card alone and leave
+ * the backdrop and cutout steady (same as web, where `FlowChrome` animates the
+ * bubble alone).
+ *
+ * Each card owns its value and starts the fade from its own mount rather than
+ * sharing one animation across the swap. Cards can appear well after the step
+ * changes — `TooltipSurface` renders nothing until its anchor measures — and a
+ * shared animation would already have finished by then, leaving the card at the
+ * stale JS value of 0 forever, since native-driven animations never write back
+ * to JS.
+ *
+ * Returns `null` outside a flow transition (unit tests), leaving opacity alone.
+ */
+export declare function useCardOpacity(): Animated.Value | null;
+//# sourceMappingURL=cardTransition.d.ts.map

package/lib/typescript/commonjs/src/surfaces/cardTransition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardTransition.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/cardTransition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,mFAAmF;AACnF,eAAO,MAAM,YAAY,MAAM,CAAC;AAChC,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,SAAS,CAAC;AAIzD,eAAO,MAAM,sBAAsB,4CAAiC,CAAC;AAErE;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,mBAAmB,GAAG,IAAI,CAEnE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,IAAI,QAAQ,CAAC,KAAK,GAAG,IAAI,CA4BtD"}

package/lib/typescript/commonjs/src/surfaces/resolveHighlightChrome.d.ts

@@ -0,0 +1,44 @@
+import type { ThemeFragment } from '@userflow-tech/protocol';
+export type HighlightType = 'OUTSIDE' | 'INSIDE';
+/**
+ * Mobile highlight corner radius when the target's own radius is unknown.
+ * Web copies `getComputedStyle(target).borderRadius`; RN measure cannot.
+ * 8 matches typical controls and the mobile tooltip mockup.
+ */
+export declare const HIGHLIGHT_CORNER_RADIUS = 8;
+/** Crisp focus-ring stroke — the mockup's inner blue line. */
+export declare const HIGHLIGHT_STROKE_WIDTH = 2;
+/** Web theme default (`themes.backdrop_highlight_radius`) — halo thickness. */
+export declare const HIGHLIGHT_RADIUS_DEFAULT = 4;
+/** Web theme default (`themes.backdrop_highlight_spread`) — placement gap only. */
+export declare const HIGHLIGHT_SPREAD_DEFAULT = 0;
+/** Cap the painted halo so it stays a wash, not a second solid stroke. */
+export declare const HIGHLIGHT_HALO_ALPHA_MAX = 0.32;
+export interface HighlightChrome {
+    /** Opaque stroke color (mockup's crisp ring). */
+    color: string;
+    /** Same color at the painted halo alpha. */
+    glowColor: string;
+    opacity: number;
+    /** Halo thickness — web `backdropHighlightRadius`. */
+    radius: number;
+    /** Placement gap only — web `backdropHighlightSpread`. Not stroke width. */
+    spread: number;
+    strokeWidth: number;
+    type: HighlightType;
+    borderRadius: number;
+}
+/**
+ * Web tooltip-backdrop highlight as a mobile focus ring: thin brand stroke +
+ * a single soft halo. Web's default white highlight is treated as unset so it
+ * does not paint a thick white frame on the dimmed cutout.
+ */
+export declare function resolveHighlightChrome(theme: ThemeFragment, backdropPadding?: number): HighlightChrome;
+export declare function isHighlightVisible(chrome: HighlightChrome): boolean;
+/**
+ * Extra pixels an OUTSIDE ring extends past the hole: theme spread plus the
+ * painted stroke and halo. Used so the tooltip notch aims at the outer edge
+ * of the focus ring, not the cutout.
+ */
+export declare function outsideHighlightOutset(chrome: HighlightChrome): number;
+//# sourceMappingURL=resolveHighlightChrome.d.ts.map

package/lib/typescript/commonjs/src/surfaces/resolveHighlightChrome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveHighlightChrome.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/resolveHighlightChrome.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAI7D,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,8DAA8D;AAC9D,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AA0CD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,aAAa,EACpB,eAAe,GAAE,MAAU,GAC1B,eAAe,CAwBjB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAGtE"}

package/lib/typescript/commonjs/src/surfaces/resolveModalLayout.d.ts

@@ -15,7 +15,7 @@ export declare function resolveModalCenterPadding(insets: {
     bottom: number;
     left: number;
     right: number;
-}): {
+}, previewBannerHeight?: number, previewBottomInset?: number): {
     paddingTop: number;
     paddingBottom: number;
     paddingLeft: number;

package/lib/typescript/commonjs/src/surfaces/resolveModalLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveModalLayout.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/resolveModalLayout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,mEAAmE;AACnE,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAElD,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAiB/C;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,WAAW,EAAE,MAAM,GAClB,MAAM,CAKR;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,GAAG;IACF,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB,CAOA;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAC3D,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,MAAM,GAClB,iBAAiB,CAMnB"}
+{"version":3,"file":"resolveModalLayout.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/resolveModalLayout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,mEAAmE;AACnE,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAElD,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAiB/C;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,WAAW,EAAE,MAAM,GAClB,MAAM,CAKR;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE;IACN,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,EACD,mBAAmB,SAAI,EACvB,kBAAkB,SAAI,GACrB;IACD,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB,CAWA;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAC3D,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,MAAM,GAClB,iBAAiB,CAMnB"}

package/lib/typescript/commonjs/src/surfaces/resolveTooltipLayout.d.ts

@@ -1,7 +1,6 @@
 import type { ThemeFragment } from '@userflow-tech/protocol';
 import type { ViewStyle } from 'react-native';
 import type { JustifyContent } from '../content/types';
-import { resolveModalCenterPadding } from './resolveModalLayout';
 /** Screen margin for anchored tooltips (mobile design spec: 24px). */
 export declare const TOOLTIP_VIEWPORT_PADDING = 24;
 /**
@@ -11,12 +10,6 @@ export declare const TOOLTIP_VIEWPORT_PADDING = 24;
 export declare function resolveTooltipCardMaxWidth(theme: ThemeFragment, stepWidth: number | null | undefined, windowWidth: number): number;
 /** Mobile spec: nearly full-width card with screen margins on narrow viewports. */
 export declare function resolveTooltipCardLayout(cardMaxWidth: number, windowWidth: number): Pick<ViewStyle, 'maxWidth' | 'width'>;
-export declare function resolveTooltipCenterPadding(insets: {
-    top: number;
-    bottom: number;
-    left: number;
-    right: number;
-}): ReturnType<typeof resolveModalCenterPadding>;
 /**
  * Web `--userflow-buttons-bubble-justify-content` (bubble + tooltip): default is end.
  */

package/lib/typescript/commonjs/src/surfaces/resolveTooltipLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveTooltipLayout.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/resolveTooltipLayout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAGL,yBAAyB,EAC1B,MAAM,sBAAsB,CAAC;AAE9B,sEAAsE;AACtE,eAAO,MAAM,wBAAwB,KAAyB,CAAC;AAiB/D;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,WAAW,EAAE,MAAM,GAClB,MAAM,CAKR;AAED,mFAAmF;AACnF,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,CAKvC;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,UAAU,CAAC,OAAO,yBAAyB,CAAC,CAE/C;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,CAK/E"}
+{"version":3,"file":"resolveTooltipLayout.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/resolveTooltipLayout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIvD,sEAAsE;AACtE,eAAO,MAAM,wBAAwB,KAAyB,CAAC;AAiB/D;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,WAAW,EAAE,MAAM,GAClB,MAAM,CAKR;AAED,mFAAmF;AACnF,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,CAKvC;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,CAK/E"}

package/lib/typescript/commonjs/src/surfaces/surfaceInteractionConfig.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether flow surfaces (modals, tooltips) intercept taps on the host app
+ * underneath. Default-on; integrators can restore the legacy pass-through
+ * tooltip backdrop via {@link setSurfaceInteractionBlocking}.
+ */
+/**
+ * When true (default), tooltip cutout bands and crossfade exit block host taps.
+ * Surfaces read this flag at render time — toggling mid-flow applies on the next
+ * re-render of the active surface tree (same as {@link setScrollPadding}).
+ */
+export declare function setSurfaceInteractionBlocking(enabled: boolean | null | undefined): void;
+export declare function getSurfaceInteractionBlocking(): boolean;
+/** Test helper — reset to default (blocking enabled). */
+export declare function resetSurfaceInteractionConfig(): void;
+//# sourceMappingURL=surfaceInteractionConfig.d.ts.map

package/lib/typescript/commonjs/src/surfaces/surfaceInteractionConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceInteractionConfig.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/surfaceInteractionConfig.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAEvF;AAED,wBAAgB,6BAA6B,IAAI,OAAO,CAEvD;AAED,yDAAyD;AACzD,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD"}

package/lib/typescript/commonjs/src/surfaces/surfaceLayoutInsets.d.ts

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import { type EdgeInsets } from './safeArea';
+export type SurfaceLayoutPadding = {
+    paddingTop: number;
+    paddingBottom: number;
+    paddingLeft: number;
+    paddingRight: number;
+};
+/** Independent writers so preview and picker chrome cannot clobber each other. */
+export type AuthoringChromeInsetSlot = 'preview' | 'picker';
+/**
+ * Holds measured authoring chrome heights so modal/tooltip layout can clear
+ * them. The overlay stays full-screen; only card padding grows.
+ *
+ * Preview and picker report into separate slots on each edge. The picker slot
+ * wins while it is non-zero (the preview bar is suppressed for that stretch).
+ */
+export declare function SurfaceLayoutInsetsProvider({ children, }: {
+    children: React.ReactNode;
+}): React.ReactElement;
+/**
+ * Report an authoring top bar's laid-out height (0 when that bar is hidden).
+ * Defaults to the preview slot; the picker must pass `'picker'`.
+ */
+export declare function useReportPreviewBannerHeight(slot?: AuthoringChromeInsetSlot): (height: number) => void;
+/**
+ * Report an authoring bottom sheet's laid-out height (0 when that sheet is hidden).
+ * Defaults to the preview slot; the picker must pass `'picker'`.
+ */
+export declare function useReportAuthoringBottomHeight(slot?: AuthoringChromeInsetSlot): (height: number) => void;
+/**
+ * Padding that keeps flow cards inside the screen: safe area, 24px margin,
+ * and authoring chrome when it is mounted.
+ */
+export declare function useSurfaceLayoutInsets(): SurfaceLayoutPadding;
+/** @internal */
+export declare function paddingAsEdgeInsets(padding: SurfaceLayoutPadding): EdgeInsets;
+//# sourceMappingURL=surfaceLayoutInsets.d.ts.map

package/lib/typescript/commonjs/src/surfaces/surfaceLayoutInsets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceLayoutInsets.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/surfaceLayoutInsets.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAAE,KAAK,UAAU,EAA6B,MAAM,YAAY,CAAC;AAExE,MAAM,MAAM,oBAAoB,GAAG;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,kFAAkF;AAClF,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,QAAQ,CAAC;AA2B5D;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,EAC1C,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,GAAG,KAAK,CAAC,YAAY,CA+BrB;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,GAAE,wBAAoC,GACzC,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAQ1B;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,GAAE,wBAAoC,GACzC,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAQ1B;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,oBAAoB,CAI7D;AAED,gBAAgB;AAChB,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU,CAO7E"}

package/lib/typescript/commonjs/src/surfaces/themeChrome.d.ts

@@ -1,13 +1,15 @@
 import type { ThemeFragment } from '@userflow-tech/protocol';
 import type { ViewStyle } from 'react-native';
 export type BubbleChromeKind = 'modal' | 'tooltip';
+/** Mobile modal/tooltip inset — tighter than web `modalPadding` (default 40). */
+export declare const BUBBLE_CONTENT_PADDING = 24;
 export interface BubbleChrome {
     backgroundColor: string;
     borderRadius: number;
     borderWidth: number;
     borderColor: string;
     notchSize: number;
-    /** Inner content padding (modal: theme `modalPadding` or 32; tooltip/bubble 24). */
+    /** Inner content padding ({@link BUBBLE_CONTENT_PADDING}). */
     contentPadding: number;
     /**
      * Outer shell — shadow + overflow. Tooltips keep overflow visible so the

package/lib/typescript/commonjs/src/surfaces/themeChrome.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"themeChrome.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/themeChrome.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEnD,MAAM,WAAW,YAAY;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,SAAS,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,SAAS,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,WAAW,EAAE,SAAS,CAAC;CACxB;AAiBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,aAAa,EACpB,IAAI,GAAE,gBAA0B,GAC/B,YAAY,CAsEd"}
+{"version":3,"file":"themeChrome.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/themeChrome.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEnD,iFAAiF;AACjF,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,SAAS,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,SAAS,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,WAAW,EAAE,SAAS,CAAC;CACxB;AAiBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,aAAa,EACpB,IAAI,GAAE,gBAA0B,GAC/B,YAAY,CAqEd"}

package/lib/typescript/commonjs/src/surfaces/tooltip/TooltipBubble.d.ts

@@ -8,16 +8,31 @@ export interface TooltipBubbleProps {
     style?: StyleProp<ViewStyle>;
     onLayout?: (event: LayoutChangeEvent) => void;
     children: React.ReactNode;
+    /** Pixel cap for the fill so tall content scrolls instead of painting past the viewport. */
+    maxHeight?: number;
+    /**
+     * Hide the pointer when the clamped card is no longer adjacent to the
+     * target. Defaults to true so isolated chrome tests keep the diamond.
+     */
+    showNotch?: boolean;
 }
 /**
  * Tooltip chrome shell: diamond notch + card fill sharing one shadow family.
  *
  * Web draws card and notch as a single silhouette under `filter: drop-shadow`.
- * RN has no silhouette filter, so the card uses a dedicated shadow layer and
- * `elevation` on the fill (Android). The notch itself is not shadowed — a
- * second blurred shadow on the rotated square leaves a gray band at the pointer
- * base when it points up into the anchor. An inset fill diamond on top erases
- * that seam (and bordered stroke gaps) without clipping the outer tip.
+ * RN has no silhouette filter — on both platforms a view's shadow is derived
+ * from that view's own bounds, and the notch hangs at a negative offset
+ * *outside* the card's bounds. No shadow cast by the card or by the shell can
+ * ever reach it, so the diamond has to cast its own, and the two shadows
+ * together trace the card + tip outline.
+ *
+ * The order is what keeps that honest. A shadow is painted with its own layer,
+ * so only a layer drawn *before* the notch may cast a card-sized shadow —
+ * otherwise it lands on the exposed tip as a gray band. Hence: shadow layer,
+ * then notch, then the fill and seam cover, both silent.
+ *
+ * iOS gets `shadow*` on the notch (`elevation` is inert there); Android gets
+ * `elevation`, which is the only shadow it honors on a rotated view.
  */
-export declare function TooltipBubble({ chrome, notchPosition, style, onLayout, children, }: TooltipBubbleProps): React.ReactElement;
+export declare function TooltipBubble({ chrome, notchPosition, style, onLayout, children, maxHeight, showNotch: showNotchProp, }: TooltipBubbleProps): React.ReactElement;
 //# sourceMappingURL=TooltipBubble.d.ts.map

package/lib/typescript/commonjs/src/surfaces/tooltip/TooltipBubble.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TooltipBubble.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/TooltipBubble.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAGtB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC9C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,aAAa,EACb,KAAK,EACL,QAAQ,EACR,QAAQ,GACT,EAAE,kBAAkB,GAAG,KAAK,CAAC,YAAY,CA4DzC"}
+{"version":3,"file":"TooltipBubble.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/TooltipBubble.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAItB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC9C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,aAAa,EACb,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,SAAS,EAAE,aAAoB,GAChC,EAAE,kBAAkB,GAAG,KAAK,CAAC,YAAY,CAgIzC"}

package/lib/typescript/commonjs/src/surfaces/tooltip/TooltipCutout.d.ts

@@ -6,26 +6,34 @@ export interface HighlightRect {
     height: number;
 }
 export interface TooltipCutoutProps {
-    targetRect: HighlightRect;
+    /** `null` until the target is measured — dims the screen with no hole yet. */
+    targetRect: HighlightRect | null;
     backdropColor: string;
     backdropOpacity: number;
     /**
-     * When true, a transparent capture layer covers only the highlight hole so
-     * the tooltip target cannot be pressed. Dim bands stay visual-only either way.
+     * When true, a transparent capture layer covers the highlight hole so the
+     * tooltip target cannot be pressed (used with surface interaction blocking).
      */
     targetBlocked: boolean;
 }
 /**
  * Four-block dimmed cutout around the padded target (web tooltip backdrop).
  *
- * Dim bands use `pointerEvents="none"` so touches reach the app — React Native
- * cannot block taps while allowing scroll the way web's `mousedown`-only
- * swallow does. When `targetBlocked`, only the hole (target) is covered with a
- * transparent `pointerEvents="auto"` layer.
+ * When surface interaction blocking is enabled (default), dim bands use
+ * `pointerEvents="auto"` so taps outside the hole are swallowed. The target
+ * hole stays open for guided-tour taps unless `targetBlocked` seals it.
  *
- * MVP note: each block uses its own translucent opacity. That matches non-overlapping
- * tiles well, but can look slightly uneven vs web’s single shadow-hole when other
- * translucent overlays stack. Acceptable for Phase 3; a single masked layer can come later.
+ * When blocking is disabled (`Userflow.setSurfaceInteractionBlocking(false)`),
+ * bands revert to `pointerEvents="none"` so the host app stays scrollable and
+ * tappable — legacy pass-through behavior. The `targetBlocked` hole seal is
+ * unchanged and still mounts when set.
+ *
+ * The bands are opaque and share one translucent parent, so the dim is composited
+ * once. Per-band opacity looks identical while the tiles truly abut, but any frame
+ * where two of them overlap darkens twice: going from no hole to a measured one
+ * grows the top band while the bottom band still covers the screen, which painted a
+ * doubled rectangle over the upper screen until the geometry settled. Group opacity
+ * makes overlap invisible instead of relying on the four rects always agreeing.
  */
 export declare function TooltipCutout({ targetRect, backdropColor, backdropOpacity, targetBlocked, }: TooltipCutoutProps): React.ReactElement;
 //# sourceMappingURL=TooltipCutout.d.ts.map

package/lib/typescript/commonjs/src/surfaces/tooltip/TooltipCutout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TooltipCutout.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/TooltipCutout.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,aAAa,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,EAC5B,UAAU,EACV,aAAa,EACb,eAAe,EACf,aAAa,GACd,EAAE,kBAAkB,GAAG,KAAK,CAAC,YAAY,CA+DzC"}
+{"version":3,"file":"TooltipCutout.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/TooltipCutout.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAM/B,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,UAAU,EAAE,aAAa,GAAG,IAAI,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;CACxB;AA+BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,EAC5B,UAAU,EACV,aAAa,EACb,eAAe,EACf,aAAa,GACd,EAAE,kBAAkB,GAAG,KAAK,CAAC,YAAY,CAkFzC"}

package/lib/typescript/commonjs/src/surfaces/tooltip/TooltipHighlight.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+import { type HighlightChrome } from '../resolveHighlightChrome';
+import type { HighlightRect } from './TooltipCutout';
+export interface TooltipHighlightProps {
+    targetRect: HighlightRect;
+    chrome: HighlightChrome;
+}
+interface Ring {
+    testID: string;
+    style: StyleProp<ViewStyle>;
+}
+/**
+ * Mobile focus ring for the tooltip hole (mockup: thin brand stroke + soft
+ * halo). Web uses one CSS `box-shadow`; RN approximates that with a 2px
+ * stroke, one translucent band, and a real blur where the platform can
+ * paint a colored shadow (`shadow*` on iOS, `boxShadow` on RN 0.76+).
+ *
+ * Ring chrome is passed as a style array so `StyleSheet.create` numeric IDs
+ * are not object-spread (that drops `position: 'absolute'` on device).
+ */
+export declare function TooltipHighlight({ targetRect, chrome, }: TooltipHighlightProps): React.ReactElement | null;
+export declare function buildHighlightRings(rect: HighlightRect, chrome: HighlightChrome): Ring[];
+export {};
+//# sourceMappingURL=TooltipHighlight.d.ts.map

package/lib/typescript/commonjs/src/surfaces/tooltip/TooltipHighlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TooltipHighlight.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/TooltipHighlight.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAA8B,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAE1F,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAErF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,aAAa,CAAC;IAC1B,MAAM,EAAE,eAAe,CAAC;CACzB;AAED,UAAU,IAAI;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,UAAU,EACV,MAAM,GACP,EAAE,qBAAqB,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAanD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,EAAE,CA4CxF"}

package/lib/typescript/commonjs/src/surfaces/tooltip/computeTooltipPosition.d.ts

@@ -5,9 +5,21 @@ export interface NotchPosition {
     left?: number;
     right?: number;
 }
+export interface ViewportInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
 export interface TooltipLayout {
     cardPosition: Position;
     notchPosition: NotchPosition;
+    /**
+     * False when the clamped card is no longer adjacent to the target, or the
+     * target's centre on the cross axis has left the card's span. Callers should
+     * hide the pointer rather than aim it at empty space.
+     */
+    showNotch: boolean;
     /** Padded target rect used for the cutout hole. */
     targetHighlightRect: {
         top: number;
@@ -35,9 +47,20 @@ export declare function computeTooltipPosition(opts: {
     placement: TooltipPlacementSide;
     notchSize: number;
     backdropPadding?: number;
+    /**
+     * Extra placement inset when the highlight ring is outside the hole
+     * (`backdropHighlightType: OUTSIDE`). Includes theme spread plus the painted
+     * stroke and halo so the notch aims at the ring's outer edge.
+     */
+    outsideHighlightSpread?: number;
     windowSize: WindowSize;
     bubbleBorderRadius: number;
     bubbleBorderWidth?: number;
     viewportPadding?: number;
+    /**
+     * Per-edge screen margin. When omitted, {@link viewportPadding} is used on
+     * every side so ABOVE/BELOW keep the same 24px gap as LEFT/RIGHT.
+     */
+    viewportInsets?: Partial<ViewportInsets>;
 }): TooltipLayout;
 //# sourceMappingURL=computeTooltipPosition.d.ts.map

package/lib/typescript/commonjs/src/surfaces/tooltip/computeTooltipPosition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"computeTooltipPosition.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/computeTooltipPosition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,oBAAoB,EACpB,UAAU,EACX,MAAM,yBAAyB,CAAC;AAGjC,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,QAAQ,CAAC;IACvB,aAAa,EAAE,aAAa,CAAC;IAC7B,mDAAmD;IACnD,mBAAmB,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACnF;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,MAAM,EAAE,IAAI,CAAC;IACb,UAAU,EAAE,IAAI,CAAC;IACjB,SAAS,EAAE,oBAAoB,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,aAAa,CA2EhB"}
+{"version":3,"file":"computeTooltipPosition.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/computeTooltipPosition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,oBAAoB,EACpB,UAAU,EACX,MAAM,yBAAyB,CAAC;AAGjC,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,QAAQ,CAAC;IACvB,aAAa,EAAE,aAAa,CAAC;IAC7B;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,mBAAmB,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACnF;AAiDD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,MAAM,EAAE,IAAI,CAAC;IACb,UAAU,EAAE,IAAI,CAAC;IACjB,SAAS,EAAE,oBAAoB,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,UAAU,EAAE,UAAU,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CAC1C,GAAG,aAAa,CA0FhB"}

package/lib/typescript/commonjs/src/surfaces/tooltip/inferTooltipPlacement.d.ts

@@ -19,16 +19,62 @@ export interface WindowSize {
     height: number;
 }
 export declare const VIEWPORT_PADDING = 24;
+/** Per-edge screen margin; each omitted edge falls back to `viewportPadding`. */
+export interface TooltipViewportInsets {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+export interface TooltipPlacementFitsOpts {
+    target: Rect;
+    bubbleSize: Size;
+    notchSize: number;
+    windowSize: WindowSize;
+    placement: TooltipPlacementSide;
+    viewportPadding?: number;
+    /**
+     * Per-edge screen margin. When omitted, `viewportPadding` is used on every
+     * side so this agrees with `computeTooltipPosition`'s clamp.
+     */
+    viewportInsets?: TooltipViewportInsets;
+    /**
+     * When set, ABOVE/BELOW compare against `min(height, minHeight)` so a
+     * scrollable card that can shrink is allowed to fit. Omit to keep the
+     * historical full-height check used by {@link inferTooltipPlacement}.
+     */
+    minHeight?: number;
+}
+/**
+ * Whether `placement` has room beside `target` for `bubbleSize`.
+ *
+ * Inclusive: a card that exactly fills the remaining gap (LEFT/RIGHT after
+ * side-narrowing) still fits. Every side reserves the matching edge margin so
+ * this agrees with the clamp in `computeTooltipPosition`; when the two
+ * disagree, a placement passes here and is then drawn somewhere else.
+ */
+export declare function tooltipPlacementFits({ target, bubbleSize, notchSize, windowSize, placement, viewportPadding, viewportInsets, minHeight, }: TooltipPlacementFitsOpts): boolean;
 /**
  * Port of web FlowChrome `inferTooltipPlacement` with distance-sorted flip
  * (not the prototype's fixed BELOW→ABOVE→RIGHT→LEFT priority).
+ *
+ * When no side fits, returns `desiredPlacement` (or BELOW) as a last resort —
+ * callers must check {@link tooltipPlacementFits} on the result to tell a real
+ * fit from that fallback.
  */
-export declare function inferTooltipPlacement({ target, bubbleSize, notchSize, windowSize, currentPlacement, desiredPlacement, }: {
+export declare function inferTooltipPlacement({ target, bubbleSize, notchSize, windowSize, currentPlacement, desiredPlacement, viewportPadding, viewportInsets, minHeight, }: {
     target: Rect;
     bubbleSize: Size;
     notchSize: number;
     windowSize: WindowSize;
     currentPlacement: TooltipPlacementSide | null;
     desiredPlacement: TooltipPlacementSide | null;
+    viewportPadding?: number;
+    /**
+     * Per-edge screen margin. When omitted, `viewportPadding` is used on every
+     * side so infer agrees with `computeTooltipPosition`'s clamp.
+     */
+    viewportInsets?: TooltipViewportInsets;
+    minHeight?: number;
 }): TooltipPlacementSide;
 //# sourceMappingURL=inferTooltipPlacement.d.ts.map

package/lib/typescript/commonjs/src/surfaces/tooltip/inferTooltipPlacement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inferTooltipPlacement.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/inferTooltipPlacement.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAExE,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,eAAO,MAAM,gBAAgB,KAA2B,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,MAAM,EACN,UAAU,EACV,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,EAAE;IACD,MAAM,EAAE,IAAI,CAAC;IACb,UAAU,EAAE,IAAI,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,gBAAgB,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC9C,gBAAgB,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC/C,GAAG,oBAAoB,CA6DvB"}
+{"version":3,"file":"inferTooltipPlacement.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/inferTooltipPlacement.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAExE,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,eAAO,MAAM,gBAAgB,KAA2B,CAAC;AAEzD,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,IAAI,CAAC;IACb,UAAU,EAAE,IAAI,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,oBAAoB,CAAC;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,MAAM,EACN,UAAU,EACV,SAAS,EACT,UAAU,EACV,SAAS,EACT,eAAkC,EAClC,cAAc,EACd,SAAS,GACV,EAAE,wBAAwB,GAAG,OAAO,CAmCpC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,MAAM,EACN,UAAU,EACV,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAkC,EAClC,cAAc,EACd,SAAS,GACV,EAAE;IACD,MAAM,EAAE,IAAI,CAAC;IACb,UAAU,EAAE,IAAI,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,gBAAgB,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC9C,gBAAgB,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,oBAAoB,CAsDvB"}

package/lib/typescript/commonjs/src/surfaces/tooltip/placementDiagnostics.d.ts

@@ -0,0 +1,39 @@
+import type { TooltipPlacementSide } from './inferTooltipPlacement';
+/** Sink for placement diagnostics. Injected in tests. */
+export type PlacementLogger = (message: string) => void;
+export declare const defaultPlacementLogger: PlacementLogger;
+/**
+ * A Builder-requested LEFT/RIGHT side could not be drawn at all: the room
+ * beside the target is smaller than the card's own chrome, so no width is left
+ * to lay content out in. Draft/preview and `__DEV__` only.
+ *
+ * The caller must not emit this when the side was honored at a reduced width —
+ * shrinking is the expected outcome now, and whether it looks good is the
+ * author's call — nor for keyboard / off-screen vertical flips, whose cause is
+ * not the room beside the target.
+ */
+export declare function tooltipSidePlacementDroppedMessage(opts: {
+    requested: 'LEFT' | 'RIGHT';
+    used: TooltipPlacementSide;
+    availableGap: number;
+    minWidth: number;
+}): string;
+export declare function warnTooltipSidePlacementDropped(opts: {
+    requested: 'LEFT' | 'RIGHT';
+    used: TooltipPlacementSide;
+    availableGap: number;
+    minWidth: number;
+}, log?: PlacementLogger): void;
+/**
+ * No side had room for the card — including the authored LEFT/RIGHT — so
+ * {@link inferTooltipPlacement} returned the requested side as a last resort.
+ * Draft/preview and `__DEV__` only. Distinct from
+ * {@link tooltipSidePlacementDroppedMessage}, which reports a successful flip.
+ */
+export declare function tooltipPlacementUnanchoredMessage(opts: {
+    requested: TooltipPlacementSide;
+}): string;
+export declare function warnTooltipPlacementUnanchored(opts: {
+    requested: TooltipPlacementSide;
+}, log?: PlacementLogger): void;
+//# sourceMappingURL=placementDiagnostics.d.ts.map

package/lib/typescript/commonjs/src/surfaces/tooltip/placementDiagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placementDiagnostics.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/placementDiagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAIpE,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAExD,eAAO,MAAM,sBAAsB,EAAE,eAGpC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CAAC,IAAI,EAAE;IACvD,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,CAQT;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE;IACJ,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,EACD,GAAG,GAAE,eAAwC,GAC5C,IAAI,CAEN;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACtD,SAAS,EAAE,oBAAoB,CAAC;CACjC,GAAG,MAAM,CAKT;AAED,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE;IAAE,SAAS,EAAE,oBAAoB,CAAA;CAAE,EACzC,GAAG,GAAE,eAAwC,GAC5C,IAAI,CAEN"}

package/lib/typescript/commonjs/src/surfaces/tooltip/rect.d.ts

@@ -1,4 +1,6 @@
 import type { Rect, WindowSize } from './inferTooltipPlacement';
+/** Grow or shrink `rect` by `padding` on every side. */
+export declare function expandRect(rect: Rect, padding: number): Rect;
 /** True when two rects are identical (used to avoid redundant setState). */
 export declare function rectsEqual(a: Rect | null, b: Rect | null): boolean;
 /** Fully outside the window (no intersection). Kept for callers that need it. */

package/lib/typescript/commonjs/src/surfaces/tooltip/rect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rect.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/rect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEhE,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAIlE;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAO3E;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CASnF;AAED,sEAAsE;AACtE,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,MAAM,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACxE,iBAAiB,CAWnB"}
+{"version":3,"file":"rect.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/rect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEhE,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAQ5D;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAIlE;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAO3E;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CASnF;AAED,sEAAsE;AACtE,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,MAAM,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACxE,iBAAiB,CAWnB"}

package/lib/typescript/commonjs/src/surfaces/tooltip/resolveSideCardWidth.d.ts

@@ -0,0 +1,76 @@
+import type { Rect } from './inferTooltipPlacement';
+/**
+ * Narrowest a side card may get: the width it spends on its own chrome, so
+ * content padding on both edges plus the border. Below this there is nothing
+ * left to lay text out in, and React Native overflows the card instead of
+ * shrinking it — the preview would stop showing the author what ships.
+ *
+ * Deliberately structural, not a readability judgment. How narrow is *too*
+ * narrow to read is the author's call, made against the device preview.
+ */
+export declare function tooltipMinSideCardWidth(opts: {
+    contentPadding: number;
+    borderWidth?: number;
+    cardMaxWidth: number;
+}): number;
+/**
+ * Horizontal room beside an expanded target for a LEFT/RIGHT tooltip.
+ *
+ * Reserves `viewportPadding` on the screen edge the card grows toward, matching
+ * the LEFT/RIGHT clamp in `computeTooltipPosition`. Web clamps side placements
+ * to the raw edge instead; RN keeps the screen margin because an edge-to-edge
+ * card reads as broken on a phone-width viewport.
+ */
+export declare function tooltipSideGap(opts: {
+    placement: 'LEFT' | 'RIGHT';
+    target: Rect;
+    windowWidth: number;
+    notchSize: number;
+    viewportPadding?: number;
+}): number;
+/**
+ * Width a LEFT/RIGHT tooltip may use: the room beside the target, capped at the
+ * theme width. The card takes whatever is left and grows taller to compensate.
+ * Null when not even {@link tooltipMinSideCardWidth} fits, so placement falls
+ * back to the vertical flip.
+ *
+ * `target` must already be expanded by backdrop padding and outside highlight
+ * spread — the same rect passed to `inferTooltipPlacement`.
+ */
+export declare function resolveTooltipSideCardWidth(opts: {
+    placement: 'LEFT' | 'RIGHT';
+    target: Rect;
+    windowWidth: number;
+    notchSize: number;
+    cardMaxWidth: number;
+    minWidth: number;
+    viewportPadding?: number;
+}): number | null;
+/**
+ * Shortest a card may get: the height it spends on its own chrome, so
+ * content padding on both edges plus the border. Mirrors
+ * {@link tooltipMinSideCardWidth} on the vertical axis.
+ */
+export declare function tooltipMinCardHeight(opts: {
+    contentPadding: number;
+    borderWidth?: number;
+    cardMaxHeight: number;
+}): number;
+/**
+ * Vertical room above or below an expanded target for an ABOVE/BELOW tooltip.
+ *
+ * Reserves the matching viewport inset on the edge the card grows toward,
+ * matching the ABOVE/BELOW clamp in `computeTooltipPosition`.
+ */
+export declare function tooltipVerticalGap(opts: {
+    placement: 'ABOVE' | 'BELOW';
+    target: Rect;
+    windowHeight: number;
+    notchSize: number;
+    viewportPadding?: number;
+    viewportInsets?: {
+        top?: number;
+        bottom?: number;
+    };
+}): number;
+//# sourceMappingURL=resolveSideCardWidth.d.ts.map

package/lib/typescript/commonjs/src/surfaces/tooltip/resolveSideCardWidth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveSideCardWidth.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/resolveSideCardWidth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAGpD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAaT;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,MAAM,EAAE,IAAI,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,MAAM,CAMT;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,MAAM,EAAE,IAAI,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,MAAM,GAAG,IAAI,CAKhB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,MAAM,CAWT;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC;IAC7B,MAAM,EAAE,IAAI,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD,GAAG,MAAM,CAQT"}