@userflow-tech/react-native 0.1.0 → 0.2.0

package/lib/typescript/module/src/runtime/flowSessionViewState.d.ts

@@ -4,14 +4,23 @@ import type { FlowSessionFragment, FlowStepFragment } from '@userflow-tech/proto
 export interface FlowSessionViewState {
     session: FlowSessionFragment | null;
     currentStepId: string | null;
+    /**
+     * Bumped on every `goToStep`, including a ForceGoToStep back to the current
+     * step, so tooltip targeting can re-bootstrap when session/step identity
+     * would otherwise be unchanged (draft preview restart).
+     */
+    stepShowNonce: number;
 }
 export declare function initialFlowSessionViewState(session: FlowSessionFragment | null): FlowSessionViewState;
 /**
  * Reduces engine events into view state.
  *
- * Important: `goToStep` updates `currentStepId` without requiring a new
- * `sessionChange` — the engine mutates `session.currentStep` in place and
- * `ForceGoToStep` does not update it at all.
+ * `goToStep` updates `currentStepId` without a new `sessionChange`. A later
+ * same-session SetFlowSession must not snap back to `session.currentStep` —
+ * tracking a button event enqueues `check_sessions`, which can push a stale
+ * current step. Web `FlowApp` `updateSession` keeps the local step for the
+ * same session id (and only falls back if that step was deleted from the
+ * version).
  */
 export declare function reduceFlowSessionViewState(state: FlowSessionViewState, event: FlowSessionEngineEvent): FlowSessionViewState;
 export declare function resolveCurrentStep(session: FlowSessionFragment | null, currentStepId: string | null): FlowStepFragment | null;

package/lib/typescript/module/src/runtime/flowSessionViewState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flowSessionViewState.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/flowSessionViewState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAErF,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAClC,oBAAoB,CAKtB;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,oBAAoB,EAC3B,KAAK,EAAE,sBAAsB,GAC5B,oBAAoB,CAkBtB;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,mBAAmB,GAAG,IAAI,EACnC,aAAa,EAAE,MAAM,GAAG,IAAI,GAC3B,gBAAgB,GAAG,IAAI,CAGzB"}
+{"version":3,"file":"flowSessionViewState.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/flowSessionViewState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAErF,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAClC,oBAAoB,CAMtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,oBAAoB,EAC3B,KAAK,EAAE,sBAAsB,GAC5B,oBAAoB,CAqBtB;AA2BD,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,mBAAmB,GAAG,IAAI,EACnC,aAAa,EAAE,MAAM,GAAG,IAAI,GAC3B,gBAAgB,GAAG,IAAI,CAGzB"}

package/lib/typescript/module/src/runtime/useFlowSessionState.d.ts

@@ -4,6 +4,7 @@ export interface FlowSessionState {
     session: FlowSessionFragment | null;
     currentStepId: string | null;
     currentStep: FlowStepFragment | null;
+    stepShowNonce: number;
 }
 /** Subscribe to a {@link FlowSessionEngine} and derive React-friendly session/step state. */
 export declare function useFlowSessionState(engine: FlowSessionEngine): FlowSessionState;

package/lib/typescript/module/src/runtime/useFlowSessionState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFlowSessionState.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/useFlowSessionState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AASrF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACtC;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,CAkB/E"}
+{"version":3,"file":"useFlowSessionState.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/useFlowSessionState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AASrF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACrC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,CAmB/E"}

package/lib/typescript/module/src/screenTracker.d.ts

@@ -1,19 +1,35 @@
 import type { ClientLocationUpdate } from '@userflow-tech/protocol';
+/** Predefined mobile screen-view event (web analogue: `page_viewed`). */
+export declare const SCREEN_VIEWED_EVENT = "screen_viewed";
 /** Called when a new location is accepted (after enable + dedupe). */
 export type ScreenChangeReporter = (location: ClientLocationUpdate) => void;
+export type HandleScreenChangeOptions = {
+    /** Re-run the reporter even when the location matches the last report. */
+    force?: boolean;
+};
+/** Event attributes for `screen_viewed`, or `null` when the location has no identity. */
+export declare function screenViewedAttributes(location: ClientLocationUpdate): {
+    screen_path: string;
+} | {
+    screen_name: string;
+} | null;
 /**
  * Registers the callback invoked when the active screen/path changes.
  * The React Native facade wires this to `UserflowCore.updateScreen`.
  */
 export declare function setScreenChangeReporter(next: ScreenChangeReporter | null): void;
+/** Latest screen/path the SDK has recorded, or `null` before the first report. */
+export declare function getCurrentScreenLocation(): ClientLocationUpdate | null;
 /** Activates screen-change tracking after a successful {@link Userflow.init}. */
 export declare function enableScreenTracking(): void;
 /** Deactivates screen-change tracking and clears the last known screen. */
 export declare function disableScreenTracking(): void;
 /**
  * Records a navigation to `location` when tracking is enabled.
- * Duplicate consecutive locations are ignored. On change, notifies the reporter
- * so the SDK can push `UpdateClientContext` to the backend.
+ * Duplicate consecutive locations are ignored unless `{ force: true }` (used
+ * after overlay dismiss, AppState resume, and first identify). On change,
+ * notifies the reporter so the SDK can push `UpdateClientContext` and
+ * `screen_viewed`.
  *
  * Locations observed before {@link enableScreenTracking} are remembered and
  * flushed when tracking is enabled (so init-after-mount still picks up the
@@ -22,7 +38,9 @@ export declare function disableScreenTracking(): void;
  * - Expo Router: `{ path: "/settings/billing" }` → wire `screenPath`
  * - React Navigation / manual: `{ screen: "BillingSettings" }` → wire `screenName`
  */
-export declare function handleScreenChange(location: ClientLocationUpdate | undefined): void;
+export declare function handleScreenChange(location: ClientLocationUpdate | undefined, options?: HandleScreenChangeOptions): void;
+/** Re-report the current screen, bypassing consecutive dedupe (resume / identify). */
+export declare function reportCurrentScreen(): void;
 /** @internal Resets tracker state between tests. Does not clear the reporter. */
 export declare function resetScreenTrackerForTests(): void;
 //# sourceMappingURL=screenTracker.d.ts.map

package/lib/typescript/module/src/screenTracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenTracker.d.ts","sourceRoot":"","sources":["../../../../src/screenTracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEpE,sEAAsE;AACtE,MAAM,MAAM,oBAAoB,GAAG,CAAC,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAY5E;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAE/E;AAOD,iFAAiF;AACjF,wBAAgB,oBAAoB,IAAI,IAAI,CAS3C;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI,CAgBnF;AAED,iFAAiF;AACjF,wBAAgB,0BAA0B,IAAI,IAAI,CAIjD"}
+{"version":3,"file":"screenTracker.d.ts","sourceRoot":"","sources":["../../../../src/screenTracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEpE,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AAEnD,sEAAsE;AACtE,MAAM,MAAM,oBAAoB,GAAG,CAAC,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAE5E,MAAM,MAAM,yBAAyB,GAAG;IACtC,0EAA0E;IAC1E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAcF,yFAAyF;AACzF,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,oBAAoB,GAC7B;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAO1D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAE/E;AAQD,kFAAkF;AAClF,wBAAgB,wBAAwB,IAAI,oBAAoB,GAAG,IAAI,CAEtE;AAED,iFAAiF;AACjF,wBAAgB,oBAAoB,IAAI,IAAI,CAS3C;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,IAAI,IAAI,CAK5C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,OAAO,CAAC,EAAE,yBAAyB,GAClC,IAAI,CAgBN;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,IAAI,IAAI,CAI1C;AAED,iFAAiF;AACjF,wBAAgB,0BAA0B,IAAI,IAAI,CAKjD"}

package/lib/typescript/module/src/surfaces/CardFade.d.ts

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import { Animated } from 'react-native';
+export type CardFadeProps = React.ComponentProps<typeof Animated.View>;
+/**
+ * Card chrome root that fades itself through step transitions.
+ *
+ * This has to wrap the card view itself, not sit higher up in a surface: the
+ * fade starts from this component's mount, and a tooltip's surface renders long
+ * before its card does.
+ */
+export declare function CardFade({ style, ...rest }: CardFadeProps): React.ReactElement;
+//# sourceMappingURL=CardFade.d.ts.map

package/lib/typescript/module/src/surfaces/CardFade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CardFade.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/CardFade.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAIxC,MAAM,MAAM,aAAa,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;AAEvE;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE,aAAa,GAAG,KAAK,CAAC,YAAY,CAG9E"}

package/lib/typescript/module/src/surfaces/CloseButton.d.ts

@@ -1,8 +1,14 @@
 import * as React from 'react';
+export declare const CLOSE_BUTTON_SIZE = 24;
+export declare const CLOSE_BUTTON_INSET = 8;
 export interface CloseButtonProps {
     onPress: () => void;
     color: string;
+    /** Distance from the top of the positioned parent. Default {@link CLOSE_BUTTON_INSET}. */
+    top?: number;
+    /** Distance from the trailing edge. Default {@link CLOSE_BUTTON_INSET}. */
+    right?: number;
 }
-/** Web close control: 24×24 hit target, 8px from the top-trailing corner. Pass muted color from {@link resolveCloseButtonColor}. */
-export declare function CloseButton({ onPress, color }: CloseButtonProps): React.ReactElement;
+/** Web close control: 24×24 hit target. Pass muted color from {@link resolveCloseButtonColor}. */
+export declare function CloseButton({ onPress, color, top, right, }: CloseButtonProps): React.ReactElement;
 //# sourceMappingURL=CloseButton.d.ts.map

package/lib/typescript/module/src/surfaces/CloseButton.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CloseButton.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/CloseButton.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oIAAoI;AACpI,wBAAgB,WAAW,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,gBAAgB,GAAG,KAAK,CAAC,YAAY,CAapF"}
+{"version":3,"file":"CloseButton.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/CloseButton.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,kGAAkG;AAClG,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,KAAK,EACL,GAAwB,EACxB,KAA0B,GAC3B,EAAE,gBAAgB,GAAG,KAAK,CAAC,YAAY,CAavC"}

package/lib/typescript/module/src/surfaces/MadeWithUserflow.d.ts

@@ -5,7 +5,7 @@ export interface MadeWithUserflowProps {
     /** Theme main foreground (`fontColor`) — matches web `--userflow-main-foreground-color`. */
     color: string;
     /**
-     * Bubble content inset (modal 40 / tooltip 24). Applied as horizontal + bottom
+     * Bubble content inset (modal 24 / tooltip 24). Applied as horizontal + bottom
      * padding so the legend aligns with the step body, matching the modal mockup.
      */
     contentPadding: number;

package/lib/typescript/module/src/surfaces/ModalSurface.d.ts

@@ -11,7 +11,7 @@ export interface ModalSurfaceProps {
 }
 /**
  * Modal chrome: full-screen backdrop + centered themed card with TreeDoc body.
- * Also used as a temporary fallback for BUBBLE/HIDDEN until dedicated surfaces.
+ * Also used as a temporary fallback for BUBBLE until a dedicated surface.
  *
  * Touch model: backdrop is a full-screen Pressable; the centering wrapper is
  * `box-none` so taps outside the card hit the backdrop, while the card itself

package/lib/typescript/module/src/surfaces/ModalSurface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModalSurface.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/ModalSurface.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAEV,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAkBxD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,mBAAmB,CAAC;IAC7B,WAAW,EAAE,gBAAgB,CAAC;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,eAAe,EAAE,eAAe,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EACN,OAAO,EACP,WAAW,EACX,KAAK,EACL,eAAe,GAChB,EAAE,iBAAiB,GAAG,KAAK,CAAC,YAAY,CAqIxC"}
+{"version":3,"file":"ModalSurface.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/ModalSurface.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAEV,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAkBxD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,mBAAmB,CAAC;IAC7B,WAAW,EAAE,gBAAgB,CAAC;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,eAAe,EAAE,eAAe,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EACN,OAAO,EACP,WAAW,EACX,KAAK,EACL,eAAe,GAChB,EAAE,iBAAiB,GAAG,KAAK,CAAC,YAAY,CA+IxC"}

package/lib/typescript/module/src/surfaces/TooltipSurface.d.ts

@@ -8,10 +8,21 @@ export interface TooltipSurfaceProps {
     currentStep: FlowStepFragment;
     theme: ThemeFragment;
     lookupAttribute: LookupAttribute;
+    /**
+     * Bumped on preview restart and every goToStep, including a ForceGoToStep
+     * back to the current step, so targeting re-bootstraps when session/step
+     * identity is unchanged.
+     */
+    resetNonce?: number;
 }
+/**
+ * One-frame delay before the first resolve after a step/reset so dialog
+ * teardown cannot arm the missing-target timer with a 0-size measure.
+ */
+export declare const FIRST_RESOLVE_DELAY_MS = 16;
 /**
  * Anchored tooltip chrome: measure manual / fiber anchor, place with web flip/shift,
  * optional cutout backdrop, missing-target report + theme fallbacks.
  */
-export declare function TooltipSurface({ engine, session, currentStep, theme, lookupAttribute, }: TooltipSurfaceProps): React.ReactElement | null;
+export declare function TooltipSurface({ engine, session, currentStep, theme, lookupAttribute, resetNonce, }: TooltipSurfaceProps): React.ReactElement | null;
 //# sourceMappingURL=TooltipSurface.d.ts.map

package/lib/typescript/module/src/surfaces/TooltipSurface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TooltipSurface.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/TooltipSurface.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAEV,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAsB/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AA4BxD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,mBAAmB,CAAC;IAC7B,WAAW,EAAE,gBAAgB,CAAC;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,eAAe,EAAE,eAAe,CAAC;CAClC;AAkCD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EACN,OAAO,EACP,WAAW,EACX,KAAK,EACL,eAAe,GAChB,EAAE,mBAAmB,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CA2lBjD"}
+{"version":3,"file":"TooltipSurface.d.ts","sourceRoot":"","sources":["../../../../../src/surfaces/TooltipSurface.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAEV,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA4B/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AA4CxD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,mBAAmB,CAAC;IAC7B,WAAW,EAAE,gBAAgB,CAAC;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,eAAe,EAAE,eAAe,CAAC;IACjC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAQD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAuCzC;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EACN,OAAO,EACP,WAAW,EACX,KAAK,EACL,eAAe,EACf,UAAc,GACf,EAAE,mBAAmB,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CA42BjD"}

package/lib/typescript/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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/module/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