@userflow-tech/react-native 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (328) hide show
  1. package/README.md +65 -33
  2. package/docs/custom-fonts.md +36 -0
  3. package/docs/troubleshooting.md +45 -44
  4. package/expo-plugin/hostDependencyWarnings.d.ts +5 -5
  5. package/expo-plugin/hostDependencyWarnings.js +7 -7
  6. package/expo-plugin/hostDependencyWarnings.js.map +1 -1
  7. package/lib/commonjs/anchors/AnchorRegistry.js +5 -0
  8. package/lib/commonjs/anchors/AnchorRegistry.js.map +1 -1
  9. package/lib/commonjs/anchors/ScrollContainerRegistry.js +8 -0
  10. package/lib/commonjs/anchors/ScrollContainerRegistry.js.map +1 -1
  11. package/lib/commonjs/anchors/fiber/FiberScanRootStore.js +8 -0
  12. package/lib/commonjs/anchors/fiber/FiberScanRootStore.js.map +1 -1
  13. package/lib/commonjs/anchors/fiber/detectAppFontFamily.js +341 -0
  14. package/lib/commonjs/anchors/fiber/detectAppFontFamily.js.map +1 -0
  15. package/lib/commonjs/anchors/fiber/presentedModal.js +215 -0
  16. package/lib/commonjs/anchors/fiber/presentedModal.js.map +1 -0
  17. package/lib/commonjs/anchors/fiber/touchTargetFiber.js +1 -0
  18. package/lib/commonjs/anchors/fiber/touchTargetFiber.js.map +1 -1
  19. package/lib/commonjs/anchors/fiber/visibleRect.js +12 -3
  20. package/lib/commonjs/anchors/fiber/visibleRect.js.map +1 -1
  21. package/lib/commonjs/anchors/fiber/visibleScreens.js +6 -0
  22. package/lib/commonjs/anchors/fiber/visibleScreens.js.map +1 -1
  23. package/lib/commonjs/anchors/useUserflowAnchor.js.map +1 -1
  24. package/lib/commonjs/anchors/useUserflowScrollContainer.js.map +1 -1
  25. package/lib/commonjs/authoring/ElementPickerOverlay.js +197 -138
  26. package/lib/commonjs/authoring/ElementPickerOverlay.js.map +1 -1
  27. package/lib/commonjs/authoring/hitTest.js +67 -10
  28. package/lib/commonjs/authoring/hitTest.js.map +1 -1
  29. package/lib/commonjs/authoring/hostAtPoint.js +45 -21
  30. package/lib/commonjs/authoring/hostAtPoint.js.map +1 -1
  31. package/lib/commonjs/content/BannerStepButton.js +2 -1
  32. package/lib/commonjs/content/BannerStepButton.js.map +1 -1
  33. package/lib/commonjs/content/RichContentRenderer.js +27 -9
  34. package/lib/commonjs/content/RichContentRenderer.js.map +1 -1
  35. package/lib/commonjs/content/StepButton.js +2 -1
  36. package/lib/commonjs/content/StepButton.js.map +1 -1
  37. package/lib/commonjs/content/resolveContentFontFamily.js +96 -0
  38. package/lib/commonjs/content/resolveContentFontFamily.js.map +1 -0
  39. package/lib/commonjs/deepLinking.js.map +1 -1
  40. package/lib/commonjs/deviceContext.js +39 -19
  41. package/lib/commonjs/deviceContext.js.map +1 -1
  42. package/lib/commonjs/index.js +13 -5
  43. package/lib/commonjs/index.js.map +1 -1
  44. package/lib/commonjs/installCheck.js +3 -3
  45. package/lib/commonjs/installCheck.js.map +1 -1
  46. package/lib/commonjs/lifecycle.js +2 -0
  47. package/lib/commonjs/lifecycle.js.map +1 -1
  48. package/lib/commonjs/pairing/PairingController.js.map +1 -1
  49. package/lib/commonjs/runtime/BannerHost.js +3 -3
  50. package/lib/commonjs/runtime/BannerHost.js.map +1 -1
  51. package/lib/commonjs/runtime/UserflowOverlay.js +17 -13
  52. package/lib/commonjs/runtime/UserflowOverlay.js.map +1 -1
  53. package/lib/commonjs/runtime/WindowOverlayHost.js +83 -0
  54. package/lib/commonjs/runtime/WindowOverlayHost.js.map +1 -0
  55. package/lib/commonjs/runtime/pushBannerLayoutContext.js +11 -8
  56. package/lib/commonjs/runtime/pushBannerLayoutContext.js.map +1 -1
  57. package/lib/commonjs/runtime/userflowCore.js +9 -2
  58. package/lib/commonjs/runtime/userflowCore.js.map +1 -1
  59. package/lib/commonjs/surfaces/BannerSurface.js +2 -6
  60. package/lib/commonjs/surfaces/BannerSurface.js.map +1 -1
  61. package/lib/commonjs/surfaces/ProgressBar.js +2 -1
  62. package/lib/commonjs/surfaces/ProgressBar.js.map +1 -1
  63. package/lib/commonjs/surfaces/TooltipSurface.js +114 -51
  64. package/lib/commonjs/surfaces/TooltipSurface.js.map +1 -1
  65. package/lib/commonjs/surfaces/bannerWebView/BannerWebViewBar.js +6 -4
  66. package/lib/commonjs/surfaces/bannerWebView/BannerWebViewBar.js.map +1 -1
  67. package/lib/commonjs/surfaces/bannerWebView/bannerNeedsWebView.js +3 -33
  68. package/lib/commonjs/surfaces/bannerWebView/bannerNeedsWebView.js.map +1 -1
  69. package/lib/commonjs/surfaces/bannerWebView/bannerThemeStyles.js +2 -1
  70. package/lib/commonjs/surfaces/bannerWebView/bannerThemeStyles.js.map +1 -1
  71. package/lib/commonjs/surfaces/bannerWebView/bannerWebViewHeight.js +33 -0
  72. package/lib/commonjs/surfaces/bannerWebView/bannerWebViewHeight.js.map +1 -0
  73. package/lib/commonjs/surfaces/bannerWebView/buildCustomBannerHtml.js +45 -12
  74. package/lib/commonjs/surfaces/bannerWebView/buildCustomBannerHtml.js.map +1 -1
  75. package/lib/commonjs/surfaces/tooltip/TooltipHighlight.js +6 -6
  76. package/lib/commonjs/surfaces/tooltip/TooltipHighlight.js.map +1 -1
  77. package/lib/commonjs/surfaces/tooltip/targetOrigin.js +74 -0
  78. package/lib/commonjs/surfaces/tooltip/targetOrigin.js.map +1 -0
  79. package/lib/commonjs/version.js +1 -1
  80. package/lib/module/anchors/AnchorRegistry.js +5 -0
  81. package/lib/module/anchors/AnchorRegistry.js.map +1 -1
  82. package/lib/module/anchors/ScrollContainerRegistry.js +8 -0
  83. package/lib/module/anchors/ScrollContainerRegistry.js.map +1 -1
  84. package/lib/module/anchors/fiber/FiberScanRootStore.js +8 -0
  85. package/lib/module/anchors/fiber/FiberScanRootStore.js.map +1 -1
  86. package/lib/module/anchors/fiber/detectAppFontFamily.js +330 -0
  87. package/lib/module/anchors/fiber/detectAppFontFamily.js.map +1 -0
  88. package/lib/module/anchors/fiber/presentedModal.js +206 -0
  89. package/lib/module/anchors/fiber/presentedModal.js.map +1 -0
  90. package/lib/module/anchors/fiber/touchTargetFiber.js +1 -0
  91. package/lib/module/anchors/fiber/touchTargetFiber.js.map +1 -1
  92. package/lib/module/anchors/fiber/visibleRect.js +12 -3
  93. package/lib/module/anchors/fiber/visibleRect.js.map +1 -1
  94. package/lib/module/anchors/fiber/visibleScreens.js +5 -0
  95. package/lib/module/anchors/fiber/visibleScreens.js.map +1 -1
  96. package/lib/module/anchors/useUserflowAnchor.js.map +1 -1
  97. package/lib/module/anchors/useUserflowScrollContainer.js.map +1 -1
  98. package/lib/module/authoring/ElementPickerOverlay.js +199 -140
  99. package/lib/module/authoring/ElementPickerOverlay.js.map +1 -1
  100. package/lib/module/authoring/hitTest.js +67 -11
  101. package/lib/module/authoring/hitTest.js.map +1 -1
  102. package/lib/module/authoring/hostAtPoint.js +45 -21
  103. package/lib/module/authoring/hostAtPoint.js.map +1 -1
  104. package/lib/module/content/BannerStepButton.js +2 -1
  105. package/lib/module/content/BannerStepButton.js.map +1 -1
  106. package/lib/module/content/RichContentRenderer.js +27 -9
  107. package/lib/module/content/RichContentRenderer.js.map +1 -1
  108. package/lib/module/content/StepButton.js +2 -1
  109. package/lib/module/content/StepButton.js.map +1 -1
  110. package/lib/module/content/resolveContentFontFamily.js +89 -0
  111. package/lib/module/content/resolveContentFontFamily.js.map +1 -0
  112. package/lib/module/deepLinking.js.map +1 -1
  113. package/lib/module/deviceContext.js +38 -17
  114. package/lib/module/deviceContext.js.map +1 -1
  115. package/lib/module/index.js +13 -5
  116. package/lib/module/index.js.map +1 -1
  117. package/lib/module/installCheck.js +3 -3
  118. package/lib/module/installCheck.js.map +1 -1
  119. package/lib/module/lifecycle.js +2 -0
  120. package/lib/module/lifecycle.js.map +1 -1
  121. package/lib/module/pairing/PairingController.js.map +1 -1
  122. package/lib/module/runtime/BannerHost.js +3 -3
  123. package/lib/module/runtime/BannerHost.js.map +1 -1
  124. package/lib/module/runtime/UserflowOverlay.js +18 -14
  125. package/lib/module/runtime/UserflowOverlay.js.map +1 -1
  126. package/lib/module/runtime/WindowOverlayHost.js +76 -0
  127. package/lib/module/runtime/WindowOverlayHost.js.map +1 -0
  128. package/lib/module/runtime/pushBannerLayoutContext.js +11 -8
  129. package/lib/module/runtime/pushBannerLayoutContext.js.map +1 -1
  130. package/lib/module/runtime/userflowCore.js +9 -2
  131. package/lib/module/runtime/userflowCore.js.map +1 -1
  132. package/lib/module/surfaces/BannerSurface.js +2 -6
  133. package/lib/module/surfaces/BannerSurface.js.map +1 -1
  134. package/lib/module/surfaces/ProgressBar.js +2 -1
  135. package/lib/module/surfaces/ProgressBar.js.map +1 -1
  136. package/lib/module/surfaces/TooltipSurface.js +114 -51
  137. package/lib/module/surfaces/TooltipSurface.js.map +1 -1
  138. package/lib/module/surfaces/bannerWebView/BannerWebViewBar.js +6 -4
  139. package/lib/module/surfaces/bannerWebView/BannerWebViewBar.js.map +1 -1
  140. package/lib/module/surfaces/bannerWebView/bannerNeedsWebView.js +3 -31
  141. package/lib/module/surfaces/bannerWebView/bannerNeedsWebView.js.map +1 -1
  142. package/lib/module/surfaces/bannerWebView/bannerThemeStyles.js +2 -1
  143. package/lib/module/surfaces/bannerWebView/bannerThemeStyles.js.map +1 -1
  144. package/lib/module/surfaces/bannerWebView/bannerWebViewHeight.js +29 -0
  145. package/lib/module/surfaces/bannerWebView/bannerWebViewHeight.js.map +1 -0
  146. package/lib/module/surfaces/bannerWebView/buildCustomBannerHtml.js +45 -12
  147. package/lib/module/surfaces/bannerWebView/buildCustomBannerHtml.js.map +1 -1
  148. package/lib/module/surfaces/tooltip/TooltipHighlight.js +6 -6
  149. package/lib/module/surfaces/tooltip/TooltipHighlight.js.map +1 -1
  150. package/lib/module/surfaces/tooltip/targetOrigin.js +67 -0
  151. package/lib/module/surfaces/tooltip/targetOrigin.js.map +1 -0
  152. package/lib/module/version.js +1 -1
  153. package/lib/typescript/commonjs/src/anchors/AnchorRegistry.d.ts +7 -0
  154. package/lib/typescript/commonjs/src/anchors/AnchorRegistry.d.ts.map +1 -1
  155. package/lib/typescript/commonjs/src/anchors/ScrollContainerRegistry.d.ts +11 -2
  156. package/lib/typescript/commonjs/src/anchors/ScrollContainerRegistry.d.ts.map +1 -1
  157. package/lib/typescript/commonjs/src/anchors/fiber/FiberScanRootStore.d.ts +5 -0
  158. package/lib/typescript/commonjs/src/anchors/fiber/FiberScanRootStore.d.ts.map +1 -1
  159. package/lib/typescript/commonjs/src/anchors/fiber/detectAppFontFamily.d.ts +30 -0
  160. package/lib/typescript/commonjs/src/anchors/fiber/detectAppFontFamily.d.ts.map +1 -0
  161. package/lib/typescript/commonjs/src/anchors/fiber/presentedModal.d.ts +45 -0
  162. package/lib/typescript/commonjs/src/anchors/fiber/presentedModal.d.ts.map +1 -0
  163. package/lib/typescript/commonjs/src/anchors/fiber/visibleRect.d.ts +5 -2
  164. package/lib/typescript/commonjs/src/anchors/fiber/visibleRect.d.ts.map +1 -1
  165. package/lib/typescript/commonjs/src/anchors/fiber/visibleScreens.d.ts +2 -0
  166. package/lib/typescript/commonjs/src/anchors/fiber/visibleScreens.d.ts.map +1 -1
  167. package/lib/typescript/commonjs/src/anchors/useUserflowAnchor.d.ts +2 -2
  168. package/lib/typescript/commonjs/src/anchors/useUserflowAnchor.d.ts.map +1 -1
  169. package/lib/typescript/commonjs/src/anchors/useUserflowScrollContainer.d.ts +3 -2
  170. package/lib/typescript/commonjs/src/anchors/useUserflowScrollContainer.d.ts.map +1 -1
  171. package/lib/typescript/commonjs/src/authoring/ElementPickerOverlay.d.ts +4 -0
  172. package/lib/typescript/commonjs/src/authoring/ElementPickerOverlay.d.ts.map +1 -1
  173. package/lib/typescript/commonjs/src/authoring/hitTest.d.ts +25 -2
  174. package/lib/typescript/commonjs/src/authoring/hitTest.d.ts.map +1 -1
  175. package/lib/typescript/commonjs/src/authoring/hostAtPoint.d.ts +6 -1
  176. package/lib/typescript/commonjs/src/authoring/hostAtPoint.d.ts.map +1 -1
  177. package/lib/typescript/commonjs/src/content/BannerStepButton.d.ts.map +1 -1
  178. package/lib/typescript/commonjs/src/content/RichContentRenderer.d.ts.map +1 -1
  179. package/lib/typescript/commonjs/src/content/StepButton.d.ts.map +1 -1
  180. package/lib/typescript/commonjs/src/content/resolveContentFontFamily.d.ts +35 -0
  181. package/lib/typescript/commonjs/src/content/resolveContentFontFamily.d.ts.map +1 -0
  182. package/lib/typescript/commonjs/src/deepLinking.d.ts +1 -1
  183. package/lib/typescript/commonjs/src/deepLinking.d.ts.map +1 -1
  184. package/lib/typescript/commonjs/src/deviceContext.d.ts +14 -5
  185. package/lib/typescript/commonjs/src/deviceContext.d.ts.map +1 -1
  186. package/lib/typescript/commonjs/src/index.d.ts +11 -5
  187. package/lib/typescript/commonjs/src/index.d.ts.map +1 -1
  188. package/lib/typescript/commonjs/src/installCheck.d.ts +2 -2
  189. package/lib/typescript/commonjs/src/installCheck.d.ts.map +1 -1
  190. package/lib/typescript/commonjs/src/lifecycle.d.ts +1 -0
  191. package/lib/typescript/commonjs/src/lifecycle.d.ts.map +1 -1
  192. package/lib/typescript/commonjs/src/pairing/PairingController.d.ts +1 -1
  193. package/lib/typescript/commonjs/src/pairing/PairingController.d.ts.map +1 -1
  194. package/lib/typescript/commonjs/src/runtime/UserflowOverlay.d.ts.map +1 -1
  195. package/lib/typescript/commonjs/src/runtime/WindowOverlayHost.d.ts +34 -0
  196. package/lib/typescript/commonjs/src/runtime/WindowOverlayHost.d.ts.map +1 -0
  197. package/lib/typescript/commonjs/src/runtime/pushBannerLayoutContext.d.ts +5 -0
  198. package/lib/typescript/commonjs/src/runtime/pushBannerLayoutContext.d.ts.map +1 -1
  199. package/lib/typescript/commonjs/src/runtime/userflowCore.d.ts.map +1 -1
  200. package/lib/typescript/commonjs/src/surfaces/BannerSurface.d.ts +1 -4
  201. package/lib/typescript/commonjs/src/surfaces/BannerSurface.d.ts.map +1 -1
  202. package/lib/typescript/commonjs/src/surfaces/ProgressBar.d.ts.map +1 -1
  203. package/lib/typescript/commonjs/src/surfaces/TooltipSurface.d.ts.map +1 -1
  204. package/lib/typescript/commonjs/src/surfaces/bannerWebView/BannerWebViewBar.d.ts.map +1 -1
  205. package/lib/typescript/commonjs/src/surfaces/bannerWebView/bannerNeedsWebView.d.ts +3 -12
  206. package/lib/typescript/commonjs/src/surfaces/bannerWebView/bannerNeedsWebView.d.ts.map +1 -1
  207. package/lib/typescript/commonjs/src/surfaces/bannerWebView/bannerThemeStyles.d.ts.map +1 -1
  208. package/lib/typescript/commonjs/src/surfaces/bannerWebView/bannerWebViewHeight.d.ts +13 -0
  209. package/lib/typescript/commonjs/src/surfaces/bannerWebView/bannerWebViewHeight.d.ts.map +1 -0
  210. package/lib/typescript/commonjs/src/surfaces/bannerWebView/buildCustomBannerHtml.d.ts.map +1 -1
  211. package/lib/typescript/commonjs/src/surfaces/tooltip/targetOrigin.d.ts +26 -0
  212. package/lib/typescript/commonjs/src/surfaces/tooltip/targetOrigin.d.ts.map +1 -0
  213. package/lib/typescript/commonjs/src/version.d.ts +1 -1
  214. package/lib/typescript/module/src/anchors/AnchorRegistry.d.ts +7 -0
  215. package/lib/typescript/module/src/anchors/AnchorRegistry.d.ts.map +1 -1
  216. package/lib/typescript/module/src/anchors/ScrollContainerRegistry.d.ts +11 -2
  217. package/lib/typescript/module/src/anchors/ScrollContainerRegistry.d.ts.map +1 -1
  218. package/lib/typescript/module/src/anchors/fiber/FiberScanRootStore.d.ts +5 -0
  219. package/lib/typescript/module/src/anchors/fiber/FiberScanRootStore.d.ts.map +1 -1
  220. package/lib/typescript/module/src/anchors/fiber/detectAppFontFamily.d.ts +30 -0
  221. package/lib/typescript/module/src/anchors/fiber/detectAppFontFamily.d.ts.map +1 -0
  222. package/lib/typescript/module/src/anchors/fiber/presentedModal.d.ts +45 -0
  223. package/lib/typescript/module/src/anchors/fiber/presentedModal.d.ts.map +1 -0
  224. package/lib/typescript/module/src/anchors/fiber/visibleRect.d.ts +5 -2
  225. package/lib/typescript/module/src/anchors/fiber/visibleRect.d.ts.map +1 -1
  226. package/lib/typescript/module/src/anchors/fiber/visibleScreens.d.ts +2 -0
  227. package/lib/typescript/module/src/anchors/fiber/visibleScreens.d.ts.map +1 -1
  228. package/lib/typescript/module/src/anchors/useUserflowAnchor.d.ts +2 -2
  229. package/lib/typescript/module/src/anchors/useUserflowAnchor.d.ts.map +1 -1
  230. package/lib/typescript/module/src/anchors/useUserflowScrollContainer.d.ts +3 -2
  231. package/lib/typescript/module/src/anchors/useUserflowScrollContainer.d.ts.map +1 -1
  232. package/lib/typescript/module/src/authoring/ElementPickerOverlay.d.ts +4 -0
  233. package/lib/typescript/module/src/authoring/ElementPickerOverlay.d.ts.map +1 -1
  234. package/lib/typescript/module/src/authoring/hitTest.d.ts +25 -2
  235. package/lib/typescript/module/src/authoring/hitTest.d.ts.map +1 -1
  236. package/lib/typescript/module/src/authoring/hostAtPoint.d.ts +6 -1
  237. package/lib/typescript/module/src/authoring/hostAtPoint.d.ts.map +1 -1
  238. package/lib/typescript/module/src/content/BannerStepButton.d.ts.map +1 -1
  239. package/lib/typescript/module/src/content/RichContentRenderer.d.ts.map +1 -1
  240. package/lib/typescript/module/src/content/StepButton.d.ts.map +1 -1
  241. package/lib/typescript/module/src/content/resolveContentFontFamily.d.ts +35 -0
  242. package/lib/typescript/module/src/content/resolveContentFontFamily.d.ts.map +1 -0
  243. package/lib/typescript/module/src/deepLinking.d.ts +1 -1
  244. package/lib/typescript/module/src/deepLinking.d.ts.map +1 -1
  245. package/lib/typescript/module/src/deviceContext.d.ts +14 -5
  246. package/lib/typescript/module/src/deviceContext.d.ts.map +1 -1
  247. package/lib/typescript/module/src/index.d.ts +11 -5
  248. package/lib/typescript/module/src/index.d.ts.map +1 -1
  249. package/lib/typescript/module/src/installCheck.d.ts +2 -2
  250. package/lib/typescript/module/src/installCheck.d.ts.map +1 -1
  251. package/lib/typescript/module/src/lifecycle.d.ts +1 -0
  252. package/lib/typescript/module/src/lifecycle.d.ts.map +1 -1
  253. package/lib/typescript/module/src/pairing/PairingController.d.ts +1 -1
  254. package/lib/typescript/module/src/pairing/PairingController.d.ts.map +1 -1
  255. package/lib/typescript/module/src/runtime/UserflowOverlay.d.ts.map +1 -1
  256. package/lib/typescript/module/src/runtime/WindowOverlayHost.d.ts +34 -0
  257. package/lib/typescript/module/src/runtime/WindowOverlayHost.d.ts.map +1 -0
  258. package/lib/typescript/module/src/runtime/pushBannerLayoutContext.d.ts +5 -0
  259. package/lib/typescript/module/src/runtime/pushBannerLayoutContext.d.ts.map +1 -1
  260. package/lib/typescript/module/src/runtime/userflowCore.d.ts.map +1 -1
  261. package/lib/typescript/module/src/surfaces/BannerSurface.d.ts +1 -4
  262. package/lib/typescript/module/src/surfaces/BannerSurface.d.ts.map +1 -1
  263. package/lib/typescript/module/src/surfaces/ProgressBar.d.ts.map +1 -1
  264. package/lib/typescript/module/src/surfaces/TooltipSurface.d.ts.map +1 -1
  265. package/lib/typescript/module/src/surfaces/bannerWebView/BannerWebViewBar.d.ts.map +1 -1
  266. package/lib/typescript/module/src/surfaces/bannerWebView/bannerNeedsWebView.d.ts +3 -12
  267. package/lib/typescript/module/src/surfaces/bannerWebView/bannerNeedsWebView.d.ts.map +1 -1
  268. package/lib/typescript/module/src/surfaces/bannerWebView/bannerThemeStyles.d.ts.map +1 -1
  269. package/lib/typescript/module/src/surfaces/bannerWebView/bannerWebViewHeight.d.ts +13 -0
  270. package/lib/typescript/module/src/surfaces/bannerWebView/bannerWebViewHeight.d.ts.map +1 -0
  271. package/lib/typescript/module/src/surfaces/bannerWebView/buildCustomBannerHtml.d.ts.map +1 -1
  272. package/lib/typescript/module/src/surfaces/tooltip/targetOrigin.d.ts +26 -0
  273. package/lib/typescript/module/src/surfaces/tooltip/targetOrigin.d.ts.map +1 -0
  274. package/lib/typescript/module/src/version.d.ts +1 -1
  275. package/package.json +5 -4
  276. package/src/anchors/AnchorRegistry.ts +8 -0
  277. package/src/anchors/ScrollContainerRegistry.ts +15 -3
  278. package/src/anchors/fiber/FiberScanRootStore.ts +8 -0
  279. package/src/anchors/fiber/detectAppFontFamily.ts +400 -0
  280. package/src/anchors/fiber/presentedModal.ts +203 -0
  281. package/src/anchors/fiber/touchTargetFiber.ts +2 -1
  282. package/src/anchors/fiber/visibleRect.ts +12 -3
  283. package/src/anchors/fiber/visibleScreens.ts +5 -0
  284. package/src/anchors/useUserflowAnchor.ts +4 -5
  285. package/src/anchors/useUserflowScrollContainer.ts +5 -4
  286. package/src/authoring/ElementPickerOverlay.tsx +242 -166
  287. package/src/authoring/hitTest.ts +88 -13
  288. package/src/authoring/hostAtPoint.ts +67 -21
  289. package/src/content/BannerStepButton.tsx +2 -1
  290. package/src/content/RichContentRenderer.tsx +16 -9
  291. package/src/content/StepButton.tsx +2 -1
  292. package/src/content/resolveContentFontFamily.ts +119 -0
  293. package/src/deepLinking.ts +2 -1
  294. package/src/deviceContext.ts +50 -14
  295. package/src/index.ts +13 -5
  296. package/src/installCheck.ts +3 -3
  297. package/src/lifecycle.ts +2 -1
  298. package/src/pairing/PairingController.ts +2 -1
  299. package/src/runtime/BannerHost.tsx +3 -3
  300. package/src/runtime/UserflowOverlay.tsx +29 -21
  301. package/src/runtime/WindowOverlayHost.tsx +95 -0
  302. package/src/runtime/pushBannerLayoutContext.tsx +14 -9
  303. package/src/runtime/userflowCore.ts +8 -2
  304. package/src/surfaces/BannerSurface.tsx +2 -6
  305. package/src/surfaces/ProgressBar.tsx +2 -1
  306. package/src/surfaces/TooltipSurface.tsx +118 -47
  307. package/src/surfaces/bannerWebView/BannerWebViewBar.tsx +6 -4
  308. package/src/surfaces/bannerWebView/bannerNeedsWebView.ts +4 -36
  309. package/src/surfaces/bannerWebView/bannerThemeStyles.ts +2 -1
  310. package/src/surfaces/bannerWebView/bannerWebViewHeight.ts +32 -0
  311. package/src/surfaces/bannerWebView/buildCustomBannerHtml.ts +48 -12
  312. package/src/surfaces/tooltip/TooltipHighlight.tsx +3 -5
  313. package/src/surfaces/tooltip/targetOrigin.ts +74 -0
  314. package/src/version.ts +1 -1
  315. package/vendor/core/dist/engine/UserflowCore.d.ts +7 -0
  316. package/vendor/core/dist/engine/UserflowCore.d.ts.map +1 -1
  317. package/vendor/core/dist/engine/UserflowCore.js +3 -2
  318. package/vendor/core/dist/engine/UserflowCore.js.map +1 -1
  319. package/vendor/core/dist/transport/phoenix.d.ts +12 -2
  320. package/vendor/core/dist/transport/phoenix.d.ts.map +1 -1
  321. package/vendor/core/dist/transport/phoenix.js +7 -6
  322. package/vendor/core/dist/transport/phoenix.js.map +1 -1
  323. package/vendor/core/dist/version.d.ts +1 -1
  324. package/vendor/core/dist/version.js +1 -1
  325. package/vendor/core/package.json +1 -1
  326. package/vendor/protocol/dist/flows.d.ts +2 -0
  327. package/vendor/protocol/dist/flows.d.ts.map +1 -1
  328. package/vendor/protocol/package.json +1 -1
package/README.md CHANGED
@@ -18,10 +18,9 @@ mobile from a single place.
18
18
  Declared minimums: React `>=18.2.0`, React Native `>=0.76.0`. React Native
19
19
  0.74 and 0.75 cannot install this SDK: `react-native-view-shot` 5.x, which
20
20
  Builder element selection needs, requires React Native 0.76 or later. The SDK
21
- is tested on React Native 0.81 / React 19.1 and on Expo SDK 57 / React Native
22
- 0.86. Expo SDK 58 is not supported yet: it bundles `react-native-webview` 14
23
- and `react-native-view-shot` 6, which are outside the peer ranges below. Expo
24
- Go is not supported.
21
+ is tested on React Native 0.81 / React 19.1, on Expo SDK 57 / React Native
22
+ 0.86, and on Expo SDK 58 / React Native 0.88 / React 19.3. Expo Go is not
23
+ supported.
25
24
 
26
25
  `@react-native-async-storage/async-storage` is the only native module this
27
26
  package depends on, so npm installs it. `react-native-webview` and
@@ -41,11 +40,12 @@ the ranges below.
41
40
  | `react`, `react-native` `>=0.76.0` | Required peers | Host runtime. | The app cannot load the SDK. React Native older than 0.76 fails install (`ERESOLVE`) because view-shot 5.x requires it. |
42
41
  | `@react-native-async-storage/async-storage` `>=1.23 <3` | Dependency | Anonymous user id and the pairing device id. | `identifyAnonymous()` throws. Pairing keeps a device id in memory for the session. A dev-only warning is logged from `Userflow.init`. |
43
42
  | `react-native-device-info` `>=11 <16` | Optional peer, bare React Native | Host app `app_version` / `app_build`. Expo reads `expo-application` / `expo-constants` instead. | Those attributes are omitted. A dev-only warning is logged on bare React Native. |
44
- | `react-native-view-shot` `^5.0.0` | Required peer | Builder element-selection screenshots. | The picker has no screenshot. A dev-only warning is logged from `Userflow.init`. Version 6.x is outside the tested range and requires React Native 0.80 or later. |
45
- | `react-native-webview` `>=13.8.0 <14` | Required peer | Evaluate JavaScript and WebView banners. | Those surfaces do not run. A dev-only warning is logged from `Userflow.init`. |
43
+ | `react-native-view-shot` `^5.0.0 \|\| ^6.0.0` | Required peer | Builder element-selection screenshots. | The picker has no screenshot. A dev-only warning is logged from `Userflow.init`. Version 6.x requires React Native 0.80 or later. |
44
+ | `react-native-webview` `>=13.8.0 <15` | Required peer | Evaluate JavaScript and WebView banners. | Those surfaces do not run. A dev-only warning is logged from `Userflow.init`. |
46
45
  | `react-native-safe-area-context` `>=4 <6` | Optional peer | Insets for banners, flow cards, and Builder bars. | In development, `Userflow.init` warns once. Those surfaces draw under the status bar and home indicator. With the package installed but no `<SafeAreaProvider>`, cards use the device's initial insets and log a separate warning. |
47
46
  | `@react-navigation/native` | Optional peer | Screen tracking and NAVIGATE routing (React Navigation). | Report screens yourself with `updateScreen` / `useUserflowScreen`. |
48
47
  | `expo-router` | Optional peer | Screen tracking and NAVIGATE routing (Expo Router). | Report screens yourself with `updateScreen` / `useUserflowScreen`. |
48
+ | `react-native-screens` | Used when installed, iOS | Draws the Builder element picker above native modal screens. | The picker is drawn under native modal screens and cannot be used on them. Expo Router and React Navigation's native stack already include it. |
49
49
  | `@react-native-community/netinfo` `>=11 <13` | Optional peer | Instant offline→online reconnect. | Recovery still runs on the heartbeat and when the app returns to the foreground. If the JavaScript package is installed but `RNCNetInfo` is not in the binary, the SDK skips it instead of showing a red screen. |
50
50
  | `expo-secure-store` | Optional peer | Persist the Builder pairing JWT in Keychain/Keystore. | The pairing token stays in memory and is lost when the process ends. The SDK loads it only when the `ExpoSecureStore` native module is registered. |
51
51
 
@@ -55,8 +55,8 @@ package managers do not warn if you skip them.
55
55
  A clean npm install prints no warning about optional peers, so install
56
56
  `react-native-safe-area-context` and NetInfo yourself when you want the behavior
57
57
  in the table. An app that already depends
58
- on an older major (view-shot 4.0.3, NetInfo 9.x, safe-area 3.x, WebView 13.6.x
59
- or 14.x) fails install with `ERESOLVE`.
58
+ on an older major (view-shot 4.0.3, NetInfo 9.x, safe-area 3.x, WebView 13.6.x)
59
+ fails install with `ERESOLVE`.
60
60
 
61
61
  ### Expo Go is not supported
62
62
 
@@ -75,38 +75,40 @@ needed with any package manager.
75
75
  ### Packages
76
76
 
77
77
  ```bash
78
- # Expo SDK 56–57 (dev build)
78
+ # Expo SDK 56–58 (dev build)
79
79
  npx expo install @userflow-tech/react-native @react-native-async-storage/async-storage react-native-webview react-native-view-shot
80
80
 
81
81
  # Expo SDK 55 and older (dev build): pin view-shot, see below
82
82
  npx expo install @userflow-tech/react-native @react-native-async-storage/async-storage react-native-webview react-native-view-shot@^5.0.0
83
83
 
84
84
  # Bare React Native
85
- npm install @userflow-tech/react-native '@react-native-async-storage/async-storage@^2' 'react-native-device-info@<16' 'react-native-webview@>=13.8.0 <14' 'react-native-view-shot@^5.0.0'
85
+ npm install @userflow-tech/react-native '@react-native-async-storage/async-storage@^2' 'react-native-device-info@<16' 'react-native-webview@>=13.8.0 <15' 'react-native-view-shot@^5.0.0'
86
86
  cd ios && pod install
87
87
  ```
88
88
 
89
89
  Keep the version ranges in the bare command. Unpinned, npm picks the latest
90
- majors. `react-native-webview` 14 is outside the peer range, and npm only warns
91
- `ERESOLVE overriding peer dependency` and installs it anyway. AsyncStorage 3
92
- sits next to the SDK's own 2.x copy, which leaves two copies of one native
93
- module. `npx expo install` picks Expo's bundled versions, which fit the ranges
94
- on Expo SDK 53–57, except view-shot on Expo SDK 55 and older.
95
-
96
- `react-native-webview` and `react-native-view-shot` (`^5.0.0`) are **required
97
- peers**. npm 7+ and pnpm install them. Yarn 1 and
90
+ majors, and when one is outside a peer range npm only warns
91
+ `ERESOLVE overriding peer dependency` and installs it anyway. view-shot 6
92
+ requires React Native 0.80 or later, so the command keeps `^5.0.0`, which fits
93
+ every supported React Native. AsyncStorage 3 sits next to the SDK's own 2.x
94
+ copy, which leaves two copies of one native module. `npx expo install` picks
95
+ Expo's bundled versions, which fit the ranges on Expo SDK 53–58, except
96
+ view-shot on Expo SDK 55 and older.
97
+
98
+ `react-native-webview` and `react-native-view-shot` (`^5.0.0 || ^6.0.0`) are
99
+ **required peers**. npm 7+ and pnpm install them. Yarn 1 and
98
100
  `npm install --legacy-peer-deps` do not, so the commands above install them in
99
101
  the app. Both are native modules — rebuild after install (a Metro reload is not
100
102
  enough).
101
103
 
102
- On Expo SDK 56 and 57, leave view-shot unpinned. Expo's default there (5.1.0)
103
- satisfies the peer. A `^5.0.0` pin installs the newest 5.x instead, which
104
- `expo doctor` reports as a version mismatch. To fix an app that already has the
105
- pin, remove `"react-native-view-shot"` from `expo.install.exclude` if it is
106
- there, then run `npx expo install react-native-view-shot`. While the exclude is
107
- set, Expo installs the latest view-shot instead of 5.1.0, and `expo doctor`
108
- skips the check. Installed with the SDK, npm keeps view-shot on 5.x; installed
109
- on its own, it can pull 6.x, outside the peer range.
104
+ On Expo SDK 56 to 58, leave view-shot unpinned. Expo's default there (5.1.0 on
105
+ Expo SDK 56 and 57, 6.1.1 on Expo SDK 58) satisfies the peer. A `^5.0.0` pin
106
+ installs the newest 5.x instead, which `expo doctor` reports as a version
107
+ mismatch. To fix an app that already has the pin, remove
108
+ `"react-native-view-shot"` from `expo.install.exclude` if it is there, then run
109
+ `npx expo install react-native-view-shot`. While the exclude is set, Expo
110
+ installs the latest view-shot instead of its bundled version, and `expo doctor`
111
+ skips the check.
110
112
 
111
113
  On Expo SDK 55 and older, unpinned `npx expo install react-native-view-shot`
112
114
  resolves **4.0.3**, which does not satisfy the peer. Pin `^5.0.0` as in the
@@ -115,7 +117,7 @@ fixes it: installing the SDK alone fails with
115
117
 
116
118
  ```text
117
119
  npm error Found: react-native-view-shot@4.0.3
118
- npm error peer react-native-view-shot@"^5.0.0" from @userflow-tech/react-native
120
+ npm error peer react-native-view-shot@"^5.0.0 || ^6.0.0" from @userflow-tech/react-native
119
121
  ```
120
122
 
121
123
  Do not retry with `--force` or `--legacy-peer-deps`. That installs the SDK and
@@ -136,7 +138,7 @@ the pin, and `npx expo install --fix` puts 4.0.3 back:
136
138
 
137
139
  With the exclude set, always install view-shot as
138
140
  `react-native-view-shot@^5.0.0`. Unpinned, Expo skips its version, so npm can
139
- keep 4.0.3 or pull 6.x.
141
+ keep 4.0.3, or pull 6.x, which requires React Native 0.80 or later.
140
142
 
141
143
  On a bare React Native app, `expo-secure-store` needs Expo modules installed
142
144
  first (`npx install-expo-modules@latest`), then `npx expo install expo-secure-store`.
@@ -354,6 +356,30 @@ watches navigation state, so overlays that do not change the pathname are
354
356
  skipped too). Returning from background past the lifecycle grace window
355
357
  re-fires the current screen.
356
358
 
359
+ ### Current screen auto-start
360
+
361
+ A React Native flow can auto-start when the current screen matches or does not
362
+ match a pattern. The pattern is compared to the same `screenName` this section
363
+ already sends. Matching is case-sensitive. A screen that has not been reported,
364
+ or an empty name, never matches — including "does not match".
365
+
366
+ - Expo Router: match the pathname (`/settings`, `/projects/123`). Route groups
367
+ are omitted, so `app/(tabs)/settings.tsx` is `/settings` and a pattern of
368
+ `/(tabs)/settings` never matches. Dynamic segments are filled in; `*` crosses
369
+ them (`/projects/*` matches `/projects/123` and `/projects/123/edit`, and does
370
+ not match `/projects`). `:name` matches exactly one segment
371
+ (`/projects/:id/edit` matches `/projects/123/edit`, not `/projects/123`).
372
+ - React Navigation and `Userflow.updateScreen`: match the route name
373
+ (`BillingSettings`). `Settings*` matches `SettingsProfile`.
374
+ - An app reports one of those values, not both. Write the pattern for the value
375
+ your integration sends.
376
+ - Modal and sheet presentations are not reported, so a pattern cannot target
377
+ them.
378
+ - The condition is offered on flow auto-start only. Banners, step triggers,
379
+ button conditions, and "hide flow when" do not use it.
380
+ - Leaving the screen does not stop a flow that already started. A "once"
381
+ frequency does not start it again.
382
+
357
383
  ### Expo Router
358
384
 
359
385
  Mount `UserflowExpoRouterScreenTracker` from the `@userflow-tech/react-native/expo-router`
@@ -547,8 +573,8 @@ Screen tracking ≠ action routing. React Navigation apps need
547
573
  | Member | Description |
548
574
  | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
549
575
  | `init(config)` | Validate credentials, store config, start lifecycle + network controllers. |
550
- | `identify(userId, attributes?, options?)` | Identify a user; auto-sets `sdk` / `device_os` / `device_type` and `app_version` / `app_build` from init; `options.signature` for identity verification. |
551
- | `identifyAnonymous(attributes?, options?)` | Stable anonymous id via AsyncStorage; auto-sets `sdk` / `device_os` / `device_type` and `app_version` / `app_build`. |
576
+ | `identify(userId, attributes?, options?)` | Identify a user; auto-sets `sdk` / `sdk_version` / `device_os` / `device_type` and `app_version` / `app_build`; `options.signature` for identity verification. |
577
+ | `identifyAnonymous(attributes?, options?)` | Stable anonymous id via AsyncStorage; auto-sets `sdk` / `sdk_version` / `device_os` / `device_type` and `app_version` / `app_build`. |
552
578
  | `group(groupId, attributes?, options?)` | Associate the current user with a group. |
553
579
  | `updateUser(attributes?)` | Upsert attributes for the current user without re-identifying. |
554
580
  | `updateGroup(attributes?, options?)` | Upsert group / membership attributes without re-grouping. |
@@ -570,9 +596,15 @@ Screen tracking ≠ action routing. React Navigation apps need
570
596
  | `getFlowSessionEngine()` | Mid-flow session engine (created lazily; attach runs after identify). |
571
597
  | `getBannerSessionEngine()` | Banner session engine (created lazily; attach runs after identify). |
572
598
  | `getHostAppVersion()` | Host app native version cached at init, or `null` before init / when unavailable. |
573
- | `getDeviceContext()` | Platform metadata cached during `init` (`sdk`, `deviceOs`, `deviceType`), or `null` before init. |
599
+ | `getDeviceContext()` | Platform metadata cached during `init` (`sdk`, `sdkVersion`, `deviceOs`, `deviceType`), or `null` before init. |
574
600
  | `logHostAppVersion()` | Log the host app's native version (not `SDK_VERSION`) and platform OS. Uses bundled device-info on bare RN. |
575
- | `logDeviceContext()` | Log cached user-attribute values (`sdk` / `device_os` / `device_type`). Requires `init`. |
601
+ | `logDeviceContext()` | Log cached user-attribute values (`sdk` / `sdk_version` / `device_os` / `device_type`). Requires `init`. |
602
+
603
+ `identify` and `identifyAnonymous` always set `sdk_version` to the running SDK version
604
+ (`SDK_VERSION`). A value passed for it there is ignored, with a development warning. `updateUser`
605
+ does not filter it, so a value written that way lasts until the next identify. If your app already
606
+ sends its own `sdk_version` attribute, rename it before upgrading. The other auto-set attributes
607
+ can be overridden by passing your own value.
576
608
 
577
609
  ### Hooks and components
578
610
 
@@ -665,7 +697,7 @@ missing lines are included):
665
697
  ```text
666
698
  [Userflow] Native setup is incomplete. Flows may not run until you fix the following, then rebuild the app (a Metro reload is not enough):
667
699
  - @react-native-async-storage/async-storage is not linked. Anonymous users and Builder pairing will not persist. Add it to the app package.json (npx expo install @react-native-async-storage/async-storage), run pod install on iOS, and rebuild.
668
- - react-native-view-shot is not linked, so Builder element selection gets no screenshot. Install it and rebuild. On Expo SDK 56 and 57, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Otherwise install react-native-view-shot@^5.0.0; on Expo SDK 55 and older, an unpinned npx expo install resolves 4.0.3.
700
+ - react-native-view-shot is not linked, so Builder element selection gets no screenshot. Install it and rebuild. On Expo SDK 56 to 58, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Otherwise install react-native-view-shot@^5.0.0; on Expo SDK 55 and older, an unpinned npx expo install resolves 4.0.3.
669
701
  - react-native-webview is not linked. Evaluate JavaScript and WebView banners will not run. Install it (npx expo install react-native-webview) and rebuild.
670
702
  - react-native-device-info is not linked, so app_version and app_build are not sent. npm install react-native-device-info, then rebuild.
671
703
  See node_modules/@userflow-tech/react-native/docs/troubleshooting.md.
package/docs/custom-fonts.md ADDED
@@ -0,0 +1,36 @@
1
+ # Custom fonts (investigation)
2
+
3
+ Part 1 makes SDK content use the font the host app is already drawing when the theme is still on Userflow's default stack. This note is how a later ticket could let a customer choose a font the app does not already use. No loader is implemented here.
4
+
5
+ ## Where it would be configured
6
+
7
+ The Builder theme, the same place web already configures fonts:
8
+
9
+ - **System font** — the default CSS stack. On React Native this is the Part 1 behavior: the detected app font, or the platform font when nothing is detected.
10
+ - **Google font** (`builtinFontFamily`) — the family web loads from `fonts.googleapis.com`.
11
+ - **Custom family** — a family name the customer installs with theme custom CSS (`@font-face`). `fontCssUrl` is the legacy locked field for that stylesheet.
12
+
13
+ SDK init is only an escape hatch for a face already linked in the app binary, for example `fontFamily` passed at `Userflow.init` when the file cannot be downloaded. It is not the customer-facing control. The dashboard does not run on device, so a builder-only name still has to be resolved by the SDK.
14
+
15
+ ## How the SDK would load a face the app does not have
16
+
17
+ React Native `fontFamily` is one family name, not a CSS stack, and it only resolves a face registered in the process.
18
+
19
+ - **Already registered in the app.** Pass the PostScript name (iOS) or the file name without extension (Android). Part 1 detects this from host `Text` and does not download anything.
20
+ - **Bundled in the SDK.** Not viable for arbitrary customer fonts. There is nothing to ship ahead of time except faces Userflow itself hosts.
21
+ - **Hosted `ttf` or `otf`.** Download the file and register it the way `expo-font` does: `CTFontManager` on iOS, `ReactFontManager` on Android. The registered name has to match the font's internal family name. Web Google CSS is `woff2` and cannot be assigned to RN `fontFamily`. A follow-up should host the `ttf`/`otf` files, not reuse the Google CSS URL. Standard faces in the builder list (Arial, Georgia, and the rest in `backend/lib/userflow/videos/font_family.ex`) exist as web fallbacks and generally do not exist on iOS or Android, so they are not a mobile default.
22
+ - **WebView banners.** Native registration is not enough on Android. The banner HTML needs its own `@font-face` (file URL or a data URI). iOS `WKWebView` often sees fonts registered with `CTFontManager`, but that should not be the only path.
23
+
24
+ ## Platform constraints
25
+
26
+ - iOS and Android both require the font file to be registered before `Text` can use the name. A missing name logs an unrecognized-font warning and falls back to the platform face.
27
+ - RN does not synthesize bold or italic for a custom face. A follow-up must register the weight files the theme actually uses (`fontWeightNormal`, `fontWeightBold`, and the button weights). Part 1 does not copy the app's weight or style; size, weight, and color stay on the theme.
28
+ - Family names differ by platform for the same file. The loader has to record the name each platform registered, not assume the Google family string matches both.
29
+
30
+ ## Recommended follow-up
31
+
32
+ Medium effort, and it is a backend-then-SDK change if the theme gains a font-file URL.
33
+
34
+ 1. Host `ttf`/`otf` for the builtin Google families (the name list already lives in `backend/lib/userflow/videos/font_family.ex`), including the weights the theme uses.
35
+ 2. When `builtinFontFamily` is set, the SDK downloads and registers those files, then sets `fontFamily` to the registered name. Until that load finishes, keep the Part 1 app font so text never renders with a missing face.
36
+ 3. Leave custom `@font-face` CSS web-only until the theme has a real file URL the SDK can download. Do not parse arbitrary customer CSS for font files.
package/docs/troubleshooting.md CHANGED
@@ -5,32 +5,32 @@ Messages are quoted exactly so you can search logs for them.
5
5
 
6
6
  ## Install
7
7
 
8
- | Symptom / log message | Likely cause | Fix |
9
- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
10
- | `expo doctor` reports `react-native-view-shot` | The app pins `^5.0.0`. Expo SDK 55 and older expect 4.0.3. Expo SDK 56 and 57 expect 5.1.0, and the pin installed a newer 5.x. | Expo SDK 55 and older: keep the pin and add `"react-native-view-shot"` to `expo.install.exclude`. Expo SDK 56 and 57: drop the pin, remove `"react-native-view-shot"` from `expo.install.exclude` if it is there, and reinstall with `npx expo install react-native-view-shot`. |
11
- | `Unable to resolve module` for an optional peer (`netinfo`, `expo-secure-store`, `expo-router`, safe-area, navigation) | A custom Metro config does not extend `getDefaultConfig`, so `allowOptionalDependencies` is off. | Extend `getDefaultConfig` from `expo/metro-config` or `@react-native/metro-config`. |
12
- | `ERESOLVE` while installing `@userflow-tech/react-native` | The app already has a version outside a peer range: view-shot 4.0.3 (what unpinned `npx expo install` installs on Expo SDK 55 and older), NetInfo 9.x, safe-area-context 3.x, WebView 13.6.x or 14.x, or React Native older than 0.76. | Move that package into the range in the package README. For view-shot, npm prints `Found: react-native-view-shot@4.0.3` and `peer react-native-view-shot@"^5.0.0" from @userflow-tech/react-native`. Install the SDK and `react-native-view-shot@^5.0.0` in one command, then add `"react-native-view-shot"` to `expo.install.exclude` on Expo SDK 55 and older. Do not retry with `--force` or `--legacy-peer-deps`; that leaves 4.0.3 installed. Raise React Native to 0.76 or later when that is the conflict. |
13
- | `npm warn ERESOLVE overriding peer dependency` naming `react-native-webview`, or `npm ls` lists two versions of `@react-native-async-storage/async-storage` | An unpinned bare install picked WebView 14 (outside `>=13.8.0 <14`) or AsyncStorage 3 (the SDK keeps its own 2.x copy). npm only warns and installs the invalid tree. | Reinstall with the ranges from the bare command in the package README: `'@react-native-async-storage/async-storage@^2'` and `'react-native-webview@>=13.8.0 <14'`. Then run `pod install` and rebuild. |
14
- | Yarn 1 or `npm install --legacy-peer-deps` succeeded, but `react-native-webview` or `react-native-view-shot` is not installed | Those installs do not fetch peers. WebView and view-shot are required peers, not dependencies. | Install `react-native-webview` and `react-native-view-shot` in the app (on Expo SDK 56 and 57, `npx expo install react-native-view-shot` unpinned; otherwise `react-native-view-shot@^5.0.0`), then rebuild native. |
15
- | Banners, flow cards, or Builder bars draw under the status bar, notch, or home indicator. Development logs `[Userflow] react-native-safe-area-context is not installed, so banners, flow cards, and Builder bars draw under the status bar and home indicator. Install it (npx expo install react-native-safe-area-context) and wrap the app in <SafeAreaProvider>.` | `react-native-safe-area-context` is not installed, so insets are zero. | Install the package and wrap the tree in `<SafeAreaProvider>`. |
16
- | `Uncaught Error` / `NativeModule.RNCNetInfo is null` as soon as `Userflow.init` runs | On SDK 0.3.1 and earlier, NetInfo's JavaScript was loaded while its native module was not in the binary. Debug builds show a red screen. Dismissing it leaves the app running; a release build can crash. | Link `@react-native-community/netinfo` and rebuild, or remove it. Current versions skip NetInfo when `RNCNetInfo` is not registered and log one dev warning instead. |
17
- | `[@userflow-tech/react-native] schemeId "…" looks like an environment id. Pass the scheme_id value that starts with userflow- (an opaque id from the dashboard), not the environment UUID.` | The config plugin received the environment UUID. | Pass the `scheme_id` (`userflow-…`) from the dashboard. |
18
- | `No schemeId was passed, so the plugin left the native config unchanged. Builder preview and pairing links will not open this app. Pass the environment scheme_id (userflow-...) from the Userflow dashboard as the plugin schemeId.` | `expo prebuild` ran the plugin without `schemeId`. | Add `{ "schemeId": "userflow-…" }` and rebuild native. |
19
- | react-native-view-shot is not a direct dependency. Builder element selection needs >=5.0.0. On Expo SDK 56 and 57, run `npx expo install react-native-view-shot` unpinned, with no expo.install.exclude entry for it. On Expo SDK 55 and older, an unpinned install resolves 4.0.3, so pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude. | Prebuild did not find view-shot in the app `package.json`. | Expo SDK 56 and 57: `npx expo install react-native-view-shot` (unpinned). Expo SDK 55 and older: `npx expo install react-native-view-shot@^5.0.0` and add `"react-native-view-shot"` to `expo.install.exclude`. Then rebuild. |
20
- | `react-native-safe-area-context is not listed in the app package.json. Expo SDK 53 does not autolink native modules that the app only receives indirectly. Without the native module, banners, flow cards, and Builder bars draw under the status bar and home indicator. Install it in the app (npx expo install react-native-safe-area-context) and wrap the app in <SafeAreaProvider>.` | Expo SDK older than 54, and safe-area-context is not a direct dependency, so its native module is not autolinked. | `npx expo install react-native-safe-area-context` and wrap the tree in `<SafeAreaProvider>`. |
21
- | `[Userflow] react-native-view-shot@4.0.3 is older than 5.0.0, so Builder element selection may not get a screenshot.` The installed version is filled in. The warning also says not to retry with `--force` or `--legacy-peer-deps`. | view-shot 4.x is installed, usually because an `ERESOLVE` was retried with `--force` or `--legacy-peer-deps`, or the 4.0.3 default on Expo SDK 55 and older was left in place. | Expo SDK 56 and 57: remove any view-shot entry from `expo.install.exclude`, run `npx expo install react-native-view-shot` unpinned, and rebuild. Otherwise install `react-native-view-shot@^5.0.0` in the same command as the SDK and rebuild; on Expo SDK 55 and older, also add `"react-native-view-shot"` to `expo.install.exclude`. |
22
- | `react-native-view-shot@4.0.3 is older than 5.0.0, which does not work with this SDK. On Expo SDK 56 and 57, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Expo SDK 55 and older default to 4.0.3: pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude.` | The app has view-shot 4.x. | Expo SDK 56 and 57: `npx expo install react-native-view-shot` (unpinned), then rebuild. Expo SDK 55 and older: pin `^5.0.0`, add the exclude, and rebuild. |
23
- | `@react-native-async-storage/async-storage is not listed in the app package.json. Expo SDK 53 does not autolink native modules that the app only receives indirectly. Install it in the app (npx expo install @react-native-async-storage/async-storage) and rebuild.` | Expo SDK older than 54, and AsyncStorage is only a transitive dependency. The WebView line is the same shape with `react-native-webview`. | Install that package in the app and rebuild. |
24
- | `[Userflow] Native setup is incomplete. Flows may not run until you fix the following, then rebuild the app (a Metro reload is not enough):` | Dev-only check on the first `Userflow.init`. Following lines name each missing native module. A missing safe-area package is a separate warning, because flows still run. | Install the named packages and rebuild. The footer is `See node_modules/@userflow-tech/react-native/docs/troubleshooting.md.` |
25
- | `- @react-native-async-storage/async-storage is not linked. Anonymous users and Builder pairing will not persist. Add it to the app package.json (npx expo install @react-native-async-storage/async-storage), run pod install on iOS, and rebuild.` | AsyncStorage's native module is not in this binary. | Add it to the app `package.json`, run `pod install` on iOS, and rebuild. |
26
- | `- react-native-view-shot is not linked, so Builder element selection gets no screenshot. Install it and rebuild. On Expo SDK 56 and 57, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Otherwise install react-native-view-shot@^5.0.0; on Expo SDK 55 and older, an unpinned npx expo install resolves 4.0.3.` | `RNViewShot` is not registered. | Expo SDK 56 and 57: `npx expo install react-native-view-shot` (unpinned). Otherwise install `react-native-view-shot@^5.0.0`. Then rebuild. |
27
- | `- react-native-webview is not linked. Evaluate JavaScript and WebView banners will not run. Install it (npx expo install react-native-webview) and rebuild.` | The WebView native module is not registered. | Install `react-native-webview` and rebuild. |
28
- | `- react-native-device-info is not linked, so app_version and app_build are not sent. npm install react-native-device-info, then rebuild.` | Bare React Native, and `RNDeviceInfo` is not registered. Expo apps that have `expo-constants` do not log this line. | `npm install react-native-device-info` and rebuild. |
29
- | `[Userflow] This app is running in Expo Go, which cannot load the SDK native modules. Builder preview links will not open the app. Use a development build (npx expo run:ios / npx expo run:android).` | The app is the Expo Go store client. | Use a development build. |
30
- | `[Userflow] UserflowProvider is not inside a <SafeAreaProvider>, so flow cards use the device's initial safe-area insets. Wrap your app in <SafeAreaProvider> from react-native-safe-area-context.` | `UserflowProvider` has no `SafeAreaProvider` ancestor. The app does not crash. Cards use `initialWindowMetrics`, or zero insets when those are unavailable. | Wrap the tree in `SafeAreaProvider`. |
31
- | `Userflow.identifyAnonymous() needs @react-native-async-storage/async-storage, which is not linked in this native build. Add it to your app's package.json, run pod install, and rebuild.` | `identifyAnonymous()` ran without a linked AsyncStorage native module. | Install and rebuild, then call it again. |
32
- | `clientToken is an environment secret key (esk_...). That key must never ship in the app. Pass the client token (ct_...) from Settings → Environments instead.` | `init` was given an `esk_` secret key. | Pass the `ct_…` client token. |
33
- | `[Userflow] Userflow.init() already ran with different options. The new clientToken, serverEndpoint, and pairingEndpoint are ignored because init runs once per process. Userflow.reset() does not apply new credentials. Restart the app to change them.` | A later `init` passed a different token or endpoint while a previous `init` is in flight or has succeeded. | Restart the app after a successful init. `reset()` clears the user and does not apply new credentials. If the previous `init` rejected, call `init` again with the corrected token or endpoint. |
8
+ | Symptom / log message | Likely cause | Fix |
9
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
10
+ | `expo doctor` reports `react-native-view-shot` | The app pins `^5.0.0`. Expo SDK 55 and older expect 4.0.3. Expo SDK 56 and 57 expect 5.1.0, and the pin installed a newer 5.x. Expo SDK 58 expects 6.1.1, which the pin excludes. | Expo SDK 55 and older: keep the pin and add `"react-native-view-shot"` to `expo.install.exclude`. Expo SDK 56 to 58: drop the pin, remove `"react-native-view-shot"` from `expo.install.exclude` if it is there, and reinstall with `npx expo install react-native-view-shot`. |
11
+ | `Unable to resolve module` for an optional peer (`netinfo`, `expo-secure-store`, `expo-router`, safe-area, navigation) | A custom Metro config does not extend `getDefaultConfig`, so `allowOptionalDependencies` is off. | Extend `getDefaultConfig` from `expo/metro-config` or `@react-native/metro-config`. |
12
+ | `ERESOLVE` while installing `@userflow-tech/react-native` | The app already has a version outside a peer range: view-shot 4.0.3 (what unpinned `npx expo install` installs on Expo SDK 55 and older), NetInfo 9.x, safe-area-context 3.x, WebView 13.6.x, or React Native older than 0.76. | Move that package into the range in the package README. For view-shot, npm prints `Found: react-native-view-shot@4.0.3` and `peer react-native-view-shot@"^5.0.0 \|\| ^6.0.0" from @userflow-tech/react-native`. Install the SDK and `react-native-view-shot@^5.0.0` in one command, then add `"react-native-view-shot"` to `expo.install.exclude` on Expo SDK 55 and older. Do not retry with `--force` or `--legacy-peer-deps`; that leaves 4.0.3 installed. Raise React Native to 0.76 or later when that is the conflict. |
13
+ | `npm warn ERESOLVE overriding peer dependency` naming `react-native-webview`, or `npm ls` lists two versions of `@react-native-async-storage/async-storage` | An unpinned bare install picked a WebView major outside `>=13.8.0 <15` or AsyncStorage 3 (the SDK keeps its own 2.x copy). npm only warns and installs the invalid tree. | Reinstall with the ranges from the bare command in the package README: `'@react-native-async-storage/async-storage@^2'` and `'react-native-webview@>=13.8.0 <15'`. Then run `pod install` and rebuild. |
14
+ | Yarn 1 or `npm install --legacy-peer-deps` succeeded, but `react-native-webview` or `react-native-view-shot` is not installed | Those installs do not fetch peers. WebView and view-shot are required peers, not dependencies. | Install `react-native-webview` and `react-native-view-shot` in the app (on Expo SDK 56 to 58, `npx expo install react-native-view-shot` unpinned; otherwise `react-native-view-shot@^5.0.0`), then rebuild native. |
15
+ | Banners, flow cards, or Builder bars draw under the status bar, notch, or home indicator. Development logs `[Userflow] react-native-safe-area-context is not installed, so banners, flow cards, and Builder bars draw under the status bar and home indicator. Install it (npx expo install react-native-safe-area-context) and wrap the app in <SafeAreaProvider>.` | `react-native-safe-area-context` is not installed, so insets are zero. | Install the package and wrap the tree in `<SafeAreaProvider>`. |
16
+ | `Uncaught Error` / `NativeModule.RNCNetInfo is null` as soon as `Userflow.init` runs | On SDK 0.3.1 and earlier, NetInfo's JavaScript was loaded while its native module was not in the binary. Debug builds show a red screen. Dismissing it leaves the app running; a release build can crash. | Link `@react-native-community/netinfo` and rebuild, or remove it. Current versions skip NetInfo when `RNCNetInfo` is not registered and log one dev warning instead. |
17
+ | `[@userflow-tech/react-native] schemeId "…" looks like an environment id. Pass the scheme_id value that starts with userflow- (an opaque id from the dashboard), not the environment UUID.` | The config plugin received the environment UUID. | Pass the `scheme_id` (`userflow-…`) from the dashboard. |
18
+ | `No schemeId was passed, so the plugin left the native config unchanged. Builder preview and pairing links will not open this app. Pass the environment scheme_id (userflow-...) from the Userflow dashboard as the plugin schemeId.` | `expo prebuild` ran the plugin without `schemeId`. | Add `{ "schemeId": "userflow-…" }` and rebuild native. |
19
+ | react-native-view-shot is not a direct dependency. Builder element selection needs >=5.0.0. On Expo SDK 56 to 58, run `npx expo install react-native-view-shot` unpinned, with no expo.install.exclude entry for it. On Expo SDK 55 and older, an unpinned install resolves 4.0.3, so pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude. | Prebuild did not find view-shot in the app `package.json`. | Expo SDK 56 to 58: `npx expo install react-native-view-shot` (unpinned). Expo SDK 55 and older: `npx expo install react-native-view-shot@^5.0.0` and add `"react-native-view-shot"` to `expo.install.exclude`. Then rebuild. |
20
+ | `react-native-safe-area-context is not listed in the app package.json. Expo SDK 53 does not autolink native modules that the app only receives indirectly. Without the native module, banners, flow cards, and Builder bars draw under the status bar and home indicator. Install it in the app (npx expo install react-native-safe-area-context) and wrap the app in <SafeAreaProvider>.` | Expo SDK older than 54, and safe-area-context is not a direct dependency, so its native module is not autolinked. | `npx expo install react-native-safe-area-context` and wrap the tree in `<SafeAreaProvider>`. |
21
+ | `[Userflow] react-native-view-shot@4.0.3 is older than 5.0.0, so Builder element selection may not get a screenshot.` The installed version is filled in. The warning also says not to retry with `--force` or `--legacy-peer-deps`. | view-shot 4.x is installed, usually because an `ERESOLVE` was retried with `--force` or `--legacy-peer-deps`, or the 4.0.3 default on Expo SDK 55 and older was left in place. | Expo SDK 56 to 58: remove any view-shot entry from `expo.install.exclude`, run `npx expo install react-native-view-shot` unpinned, and rebuild. Otherwise install `react-native-view-shot@^5.0.0` in the same command as the SDK and rebuild; on Expo SDK 55 and older, also add `"react-native-view-shot"` to `expo.install.exclude`. |
22
+ | `react-native-view-shot@4.0.3 is older than 5.0.0, which does not work with this SDK. On Expo SDK 56 to 58, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Expo SDK 55 and older default to 4.0.3: pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude.` | The app has view-shot 4.x. | Expo SDK 56 to 58: `npx expo install react-native-view-shot` (unpinned), then rebuild. Expo SDK 55 and older: pin `^5.0.0`, add the exclude, and rebuild. |
23
+ | `@react-native-async-storage/async-storage is not listed in the app package.json. Expo SDK 53 does not autolink native modules that the app only receives indirectly. Install it in the app (npx expo install @react-native-async-storage/async-storage) and rebuild.` | Expo SDK older than 54, and AsyncStorage is only a transitive dependency. The WebView line is the same shape with `react-native-webview`. | Install that package in the app and rebuild. |
24
+ | `[Userflow] Native setup is incomplete. Flows may not run until you fix the following, then rebuild the app (a Metro reload is not enough):` | Dev-only check on the first `Userflow.init`. Following lines name each missing native module. A missing safe-area package is a separate warning, because flows still run. | Install the named packages and rebuild. The footer is `See node_modules/@userflow-tech/react-native/docs/troubleshooting.md.` |
25
+ | `- @react-native-async-storage/async-storage is not linked. Anonymous users and Builder pairing will not persist. Add it to the app package.json (npx expo install @react-native-async-storage/async-storage), run pod install on iOS, and rebuild.` | AsyncStorage's native module is not in this binary. | Add it to the app `package.json`, run `pod install` on iOS, and rebuild. |
26
+ | `- react-native-view-shot is not linked, so Builder element selection gets no screenshot. Install it and rebuild. On Expo SDK 56 to 58, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Otherwise install react-native-view-shot@^5.0.0; on Expo SDK 55 and older, an unpinned npx expo install resolves 4.0.3.` | `RNViewShot` is not registered. | Expo SDK 56 to 58: `npx expo install react-native-view-shot` (unpinned). Otherwise install `react-native-view-shot@^5.0.0`. Then rebuild. |
27
+ | `- react-native-webview is not linked. Evaluate JavaScript and WebView banners will not run. Install it (npx expo install react-native-webview) and rebuild.` | The WebView native module is not registered. | Install `react-native-webview` and rebuild. |
28
+ | `- react-native-device-info is not linked, so app_version and app_build are not sent. npm install react-native-device-info, then rebuild.` | Bare React Native, and `RNDeviceInfo` is not registered. Expo apps that have `expo-constants` do not log this line. | `npm install react-native-device-info` and rebuild. |
29
+ | `[Userflow] This app is running in Expo Go, which cannot load the SDK native modules. Builder preview links will not open the app. Use a development build (npx expo run:ios / npx expo run:android).` | The app is the Expo Go store client. | Use a development build. |
30
+ | `[Userflow] UserflowProvider is not inside a <SafeAreaProvider>, so flow cards use the device's initial safe-area insets. Wrap your app in <SafeAreaProvider> from react-native-safe-area-context.` | `UserflowProvider` has no `SafeAreaProvider` ancestor. The app does not crash. Cards use `initialWindowMetrics`, or zero insets when those are unavailable. | Wrap the tree in `SafeAreaProvider`. |
31
+ | `Userflow.identifyAnonymous() needs @react-native-async-storage/async-storage, which is not linked in this native build. Add it to your app's package.json, run pod install, and rebuild.` | `identifyAnonymous()` ran without a linked AsyncStorage native module. | Install and rebuild, then call it again. |
32
+ | `clientToken is an environment secret key (esk_...). That key must never ship in the app. Pass the client token (ct_...) from Settings → Environments instead.` | `init` was given an `esk_` secret key. | Pass the `ct_…` client token. |
33
+ | `[Userflow] Userflow.init() already ran with different options. The new clientToken, serverEndpoint, and pairingEndpoint are ignored because init runs once per process. Userflow.reset() does not apply new credentials. Restart the app to change them.` | A later `init` passed a different token or endpoint while a previous `init` is in flight or has succeeded. | Restart the app after a successful init. `reset()` clears the user and does not apply new credentials. If the previous `init` rejected, call `init` again with the corrected token or endpoint. |
34
34
 
35
35
  ## Init / identify / group
36
36
 
@@ -120,12 +120,13 @@ Id matching: dashboard `#invite-teammates` ↔ `userflowId="invite-teammates"`,
120
120
 
121
121
  ### 3. Screen / provider
122
122
 
123
- | Symptom | Likely cause |
124
- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
125
- | No overlay at all | Missing `UserflowProvider` above the tree |
126
- | Wrong screen / flow never qualifies | Screen not reported — Expo Router needs `UserflowExpoRouterScreenTracker` under the provider; React Navigation needs `WithUserflowReactNavigation`; or call `updateScreen` / `useUserflowScreen` |
127
- | Works only after identify | Expected for server-driven sessions; `updateScreen` before identify only buffers |
128
- | No `screen_viewed` events | Identify has not run, or an overlay (modal/sheet) is focused — overlays are not screen views |
123
+ | Symptom | Likely cause |
124
+ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
125
+ | No overlay at all | Missing `UserflowProvider` above the tree |
126
+ | Wrong screen / flow never qualifies | Screen not reported — Expo Router needs `UserflowExpoRouterScreenTracker` under the provider; React Navigation needs `WithUserflowReactNavigation`; or call `updateScreen` / `useUserflowScreen` |
127
+ | "Current screen" auto-start never matches | Pattern does not equal the reported value: route groups are dropped (`/(tabs)/settings` is `/settings`), Expo Router sends a path while React Navigation sends a route name, or the focused route is a modal/sheet (not reported). `*` or `:name` covers dynamic segments (`/projects/*`, `/projects/:id`). An unreported or empty screen never matches, including "does not match". Matching is case-sensitive |
128
+ | Works only after identify | Expected for server-driven sessions; `updateScreen` before identify only buffers |
129
+ | No `screen_viewed` events | Identify has not run, or an overlay (modal/sheet) is focused — overlays are not screen views |
129
130
 
130
131
  ### 4. Connection
131
132
 
@@ -140,18 +141,18 @@ Id matching: dashboard `#invite-teammates` ↔ `userflowId="invite-teammates"`,
140
141
 
141
142
  Full setup: [deep-linking.md](deep-linking.md). Pairing is available in all builds (including release).
142
143
 
143
- | Symptom | Likely cause | Fix |
144
- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
145
- | Deep link opens the app but nothing happens | Scheme added in config but **no native rebuild** | `npx expo prebuild` / new development client; Metro reload is not enough |
146
- | Deep link opens the app but nothing happens, and no **Preview mode** top bar appears | `Userflow.init()` rejected, so there is no session to preview into | Check the logs for `[Userflow] Builder pairing link received, but Userflow.init() failed` — fix that error (usually `clientToken`) and re-open the link |
147
- | Killed app opens from a pairing link with no banner, or Preview returns on the wrong step | Pairing did not resume, or the install joined as a new device while the old presence was still on the topic | Install `expo-secure-store` so a relaunch can resume. A cold start should show **Connecting to Builder…** immediately, then **Preview mode**, with the flow at step 1. `exitPreview()` or an expired token ends resume |
148
- | Deep link opens the app and the router shows **Unmatched Route** / "page could not be found" | Deep link is not the root form from the QR; **or** the link was rebuilt with the app's own scheme instead of `scheme_id` | Open the QR unmodified (`userflow-<id>://?pairing_token=…`). If the log says `a scheme Userflow does not own`, do not substitute your app scheme |
149
- | "Can't select this element" right after pairing, or the app jumps to home when pairing | Expo Router navigated on the pairing link | Add `app/+native-intent.ts` exporting `redirectSystemPath` from `@userflow-tech/react-native/expo-router` (see [deep-linking.md](deep-linking.md#expo-router-hosts)) |
150
- | Pairing deep link ignored (preview URL may still work) | Scheme is `userflow-*` but the id after it is empty or has stray hyphens | Use the env's `scheme_id` from the dashboard exactly (e.g. `userflow-v7twv2fw2ja2jaco7kesvowmem`), not the env UUID |
151
- | Builder says “A device was paired earlier…” and Preview closes immediately after a brief spinner | Stale pairing session still present; a ghost device acks | Pair again on the device you are watching, or clear the env's pairing session and re-QR |
152
- | Preview succeeds on the server but the phone stays idle | App is not the paired instance (no **Preview mode** top bar) | Confirm the top bar before hitting Preview; re-open the pairing QR on this install |
153
- | QR / `https://…/pair/<jwt>` does nothing in the app | SDK only parses the **scheme** form after the backend redirect | Open via the OS (scan QR) or forward `{schemeId}://?pairing_token=…` with `handlePairingUrl` |
154
- | Builder selector has no screenshot after Confirm | Missing / unlinked `react-native-view-shot`, or 4.0.3 from Expo SDK 55 and older | Install view-shot (on Expo SDK 56 and 57, `npx expo install react-native-view-shot` unpinned; otherwise `react-native-view-shot@^5.0.0`) and **rebuild native**. At init, look for `- react-native-view-shot is not linked, so Builder element selection gets no screenshot`. When confirming a pick, look for `[Userflow] Required peer react-native-view-shot is not installed; skipping picker screenshot.` |
144
+ | Symptom | Likely cause | Fix |
145
+ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
146
+ | Deep link opens the app but nothing happens | Scheme added in config but **no native rebuild** | `npx expo prebuild` / new development client; Metro reload is not enough |
147
+ | Deep link opens the app but nothing happens, and no **Preview mode** top bar appears | `Userflow.init()` rejected, so there is no session to preview into | Check the logs for `[Userflow] Builder pairing link received, but Userflow.init() failed` — fix that error (usually `clientToken`) and re-open the link |
148
+ | Killed app opens from a pairing link with no banner, or Preview returns on the wrong step | Pairing did not resume, or the install joined as a new device while the old presence was still on the topic | Install `expo-secure-store` so a relaunch can resume. A cold start should show **Connecting to Builder…** immediately, then **Preview mode**, with the flow at step 1. `exitPreview()` or an expired token ends resume |
149
+ | Deep link opens the app and the router shows **Unmatched Route** / "page could not be found" | Deep link is not the root form from the QR; **or** the link was rebuilt with the app's own scheme instead of `scheme_id` | Open the QR unmodified (`userflow-<id>://?pairing_token=…`). If the log says `a scheme Userflow does not own`, do not substitute your app scheme |
150
+ | "Can't select this element" right after pairing, or the app jumps to home when pairing | Expo Router navigated on the pairing link | Add `app/+native-intent.ts` exporting `redirectSystemPath` from `@userflow-tech/react-native/expo-router` (see [deep-linking.md](deep-linking.md#expo-router-hosts)) |
151
+ | Pairing deep link ignored (preview URL may still work) | Scheme is `userflow-*` but the id after it is empty or has stray hyphens | Use the env's `scheme_id` from the dashboard exactly (e.g. `userflow-v7twv2fw2ja2jaco7kesvowmem`), not the env UUID |
152
+ | Builder says “A device was paired earlier…” and Preview closes immediately after a brief spinner | Stale pairing session still present; a ghost device acks | Pair again on the device you are watching, or clear the env's pairing session and re-QR |
153
+ | Preview succeeds on the server but the phone stays idle | App is not the paired instance (no **Preview mode** top bar) | Confirm the top bar before hitting Preview; re-open the pairing QR on this install |
154
+ | QR / `https://…/pair/<jwt>` does nothing in the app | SDK only parses the **scheme** form after the backend redirect | Open via the OS (scan QR) or forward `{schemeId}://?pairing_token=…` with `handlePairingUrl` |
155
+ | Builder selector has no screenshot after Confirm | Missing / unlinked `react-native-view-shot`, or 4.0.3 from Expo SDK 55 and older | Install view-shot (on Expo SDK 56 to 58, `npx expo install react-native-view-shot` unpinned; otherwise `react-native-view-shot@^5.0.0`) and **rebuild native**. At init, look for `- react-native-view-shot is not linked, so Builder element selection gets no screenshot`. When confirming a pick, look for `[Userflow] Required peer react-native-view-shot is not installed; skipping picker screenshot.` |
155
156
 
156
157
  ## Expo
157
158
 
package/expo-plugin/hostDependencyWarnings.d.ts CHANGED
@@ -8,11 +8,11 @@ export interface HostDependencyWarning {
8
8
  * Prebuild checks that do not change the native config.
9
9
  *
10
10
  * `react-native-view-shot` must be at least 5. On Expo SDK 55 and older an
11
- * unpinned install resolves 4.0.3; Expo SDK 56 and 57 bundle 5.1.0, so a
12
- * `^5.0.0` pin there only adds a version mismatch. Expo SDK 53 and older only
13
- * autolink native modules listed in the app's own package.json, so
14
- * AsyncStorage, WebView, and safe-area-context have to be direct dependencies
15
- * there. Expo SDK 54 and later autolink
11
+ * unpinned install resolves 4.0.3; Expo SDK 56 and 57 bundle 5.1.0 and Expo
12
+ * SDK 58 bundles 6.1.1, so a `^5.0.0` pin there only adds a version mismatch.
13
+ * Expo SDK 53 and older only autolink native modules listed in the app's own
14
+ * package.json, so AsyncStorage, WebView, and safe-area-context have to be
15
+ * direct dependencies there. Expo SDK 54 and later autolink
16
16
  * safe-area-context when Expo Router or React Navigation brought it in, so
17
17
  * prebuild does not warn about it on those SDKs. `Userflow.init` warns when
18
18
  * the package itself cannot be loaded.
package/expo-plugin/hostDependencyWarnings.js CHANGED
@@ -18,11 +18,11 @@ const TRANSITIVE_NATIVE_MODULES = [
18
18
  * Prebuild checks that do not change the native config.
19
19
  *
20
20
  * `react-native-view-shot` must be at least 5. On Expo SDK 55 and older an
21
- * unpinned install resolves 4.0.3; Expo SDK 56 and 57 bundle 5.1.0, so a
22
- * `^5.0.0` pin there only adds a version mismatch. Expo SDK 53 and older only
23
- * autolink native modules listed in the app's own package.json, so
24
- * AsyncStorage, WebView, and safe-area-context have to be direct dependencies
25
- * there. Expo SDK 54 and later autolink
21
+ * unpinned install resolves 4.0.3; Expo SDK 56 and 57 bundle 5.1.0 and Expo
22
+ * SDK 58 bundles 6.1.1, so a `^5.0.0` pin there only adds a version mismatch.
23
+ * Expo SDK 53 and older only autolink native modules listed in the app's own
24
+ * package.json, so AsyncStorage, WebView, and safe-area-context have to be
25
+ * direct dependencies there. Expo SDK 54 and later autolink
26
26
  * safe-area-context when Expo Router or React Navigation brought it in, so
27
27
  * prebuild does not warn about it on those SDKs. `Userflow.init` warns when
28
28
  * the package itself cannot be loaded.
@@ -40,7 +40,7 @@ function hostDependencyWarnings(projectRoot, sdkVersion) {
40
40
  if (!viewShot) {
41
41
  warnings.push({
42
42
  property: VIEW_SHOT,
43
- message: 'react-native-view-shot is not a direct dependency. Builder element selection needs >=5.0.0. On Expo SDK 56 and 57, run `npx expo install react-native-view-shot` unpinned, with no expo.install.exclude entry for it. On Expo SDK 55 and older, an unpinned install resolves 4.0.3, so pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude.',
43
+ message: 'react-native-view-shot is not a direct dependency. Builder element selection needs >=5.0.0. On Expo SDK 56 to 58, run `npx expo install react-native-view-shot` unpinned, with no expo.install.exclude entry for it. On Expo SDK 55 and older, an unpinned install resolves 4.0.3, so pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude.',
44
44
  });
45
45
  }
46
46
  else {
@@ -48,7 +48,7 @@ function hostDependencyWarnings(projectRoot, sdkVersion) {
48
48
  if (major != null && major < 5) {
49
49
  warnings.push({
50
50
  property: VIEW_SHOT,
51
- message: `react-native-view-shot@${viewShot} is older than 5.0.0, which does not work with this SDK. On Expo SDK 56 and 57, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Expo SDK 55 and older default to 4.0.3: pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude.`,
51
+ message: `react-native-view-shot@${viewShot} is older than 5.0.0, which does not work with this SDK. On Expo SDK 56 to 58, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Expo SDK 55 and older default to 4.0.3: pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude.`,
52
52
  });
53
53
  }
54
54
  }
package/expo-plugin/hostDependencyWarnings.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"hostDependencyWarnings.js","sourceRoot":"","sources":["../plugin/hostDependencyWarnings.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"hostDependencyWarnings.js","sourceRoot":"","sources":["../plugin/hostDependencyWarnings.ts"],"names":[],"mappings":"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"}
package/lib/commonjs/anchors/AnchorRegistry.js CHANGED
@@ -6,6 +6,11 @@ Object.defineProperty(exports, "__esModule", {
6
6
  exports.anchorRegistry = exports.AnchorRegistry = void 0;
7
7
  /** Host view that can be measured in window coordinates. */
8
8
 
9
+ /**
10
+ * The view instance an anchor ref receives. Structural rather than `View`,
11
+ * which React Native 0.88 types as a function component, not an instance.
12
+ */
13
+
9
14
  /**
10
15
  * Manual-anchor registry for Phase 3 (WS6). Codeless resolution is Phase 4.
11
16
  * Multiple mounts of the same id keep a set; {@link get} returns the most