@tapthrough/expo 0.0.0-stage → 0.1.0

package/src/Tapthrough.tsx

@@ -0,0 +1,171 @@
+import Constants from 'expo-constants'
+import * as Linking from 'expo-linking'
+import { type Href, router, useRootNavigationState } from 'expo-router'
+import { type ReactNode, useEffect } from 'react'
+import { ActivityIndicator, Pressable, StyleSheet, Text, View } from 'react-native'
+import { setFlagOverrides } from './core/flags.js'
+import type { AuthAdapter, ResetTarget } from './core/launch.js'
+import { ReportButton } from './Feedback.js'
+import { useLaunchState } from './hooks.js'
+import { controller, pluginConfig } from './runtime.js'
+
+export interface TapthroughProps {
+  children: ReactNode
+  /**
+   * How to log in with the seeded session, e.g. `supabaseAuth(supabase)`.
+   * Leave it out if the app has no login.
+   */
+  auth?: AuthAdapter
+  /** Local state to clear before logging in: query caches, persisted keys, stores. */
+  reset?: ResetTarget[]
+  /** Overrides the config plugin's `seedHookUrl`. */
+  seedHookUrl?: string
+  /** Overrides the config plugin's `enabled`. Off unless one of them turns it on. */
+  enabled?: boolean
+  /** Shows the Report button on PR previews. Defaults to true. */
+  feedback?: boolean
+  /** Overrides the config plugin's `apiUrl`, where reports are sent. */
+  apiUrl?: string
+}
+
+/** For apps without login: the seeded session is ignored. */
+const noAuth: AuthAdapter = { signIn: async () => {} }
+
+/**
+ * Wrap your root layout's content with it. When the app opens from a
+ * Tapthrough link, it seeds the test user, logs in, applies flags and opens
+ * the scenario's screen. Otherwise it renders `children` and does nothing.
+ */
+export function Tapthrough({
+  children,
+  auth = noAuth,
+  reset,
+  seedHookUrl,
+  enabled,
+  feedback = true,
+  apiUrl,
+}: TapthroughProps) {
+  const config = pluginConfig()
+  const isEnabled = enabled ?? config.enabled
+  const hookUrl = seedHookUrl ?? config.seedHookUrl
+  const navigationReady = Boolean(useRootNavigationState()?.key)
+
+  useEffect(() => {
+    if (!isEnabled) return
+    if (!hookUrl) {
+      console.warn('[tapthrough] Enabled without a seedHookUrl; launch links will be ignored.')
+      return
+    }
+    const config = Constants.expoConfig
+    const audiences = [config?.ios?.bundleIdentifier, config?.android?.package].filter(
+      (id): id is string => typeof id === 'string',
+    )
+    controller.configure({
+      seedHookUrl: hookUrl,
+      expectedAudiences: audiences,
+      auth,
+      reset: reset ?? [],
+      applyFlags: setFlagOverrides,
+    })
+    return () => controller.configure(undefined)
+  }, [isEnabled, hookUrl, auth, reset])
+
+  useEffect(() => {
+    if (!navigationReady) return
+    // Back to the root of the stack, then push: the reviewer lands on the scenario's
+    // screen with a back button, instead of on a stack that holds only that screen.
+    controller.setNavigator((path) => {
+      if (router.canDismiss()) router.dismissAll()
+      router.push(path as Href)
+    })
+    return () => controller.setNavigator(undefined)
+  }, [navigationReady])
+
+  // Fallback for apps without `+native-intent`; tokens are de-duplicated.
+  useEffect(() => {
+    if (!isEnabled) return
+    let active = true
+    void Linking.getInitialURL().then((url) => {
+      if (active) controller.offer(url)
+    })
+    const subscription = Linking.addEventListener('url', ({ url }) => controller.offer(url))
+    return () => {
+      active = false
+      subscription.remove()
+    }
+  }, [isEnabled])
+
+  return (
+    <>
+      {children}
+      {(isEnabled || config.staff) && feedback ? (
+        <ReportButton
+          apiUrl={apiUrl ?? config.apiUrl}
+          canSetUp={Boolean(hookUrl)}
+          appKey={config.staff ? config.appKey : undefined}
+        />
+      ) : null}
+      {isEnabled ? <LaunchOverlay /> : null}
+    </>
+  )
+}
+
+function LaunchOverlay() {
+  const state = useLaunchState()
+  // The Review popover shows its own progress for setups it started.
+  if (state.status !== 'idle' && state.source === 'app') return null
+  if (state.status === 'launching') {
+    return (
+      <View style={styles.backdrop} pointerEvents="auto">
+        <ActivityIndicator size="large" color="#ffffff" />
+        <Text style={styles.backdropText}>Setting up your review…</Text>
+      </View>
+    )
+  }
+  if (state.status === 'error') {
+    return (
+      <View style={styles.card} accessibilityRole="alert">
+        <Text style={styles.title}>Couldn't open this preview</Text>
+        <Text style={styles.message}>{state.error.message}</Text>
+        <Pressable
+          onPress={controller.dismiss}
+          style={styles.button}
+          accessibilityRole="button"
+          hitSlop={8}
+        >
+          <Text style={styles.buttonText}>Dismiss</Text>
+        </Pressable>
+      </View>
+    )
+  }
+  return null
+}
+
+const styles = StyleSheet.create({
+  backdrop: {
+    position: 'absolute',
+    top: 0,
+    right: 0,
+    bottom: 0,
+    left: 0,
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 16,
+    backgroundColor: 'rgba(17, 17, 17, 0.85)',
+  },
+  backdropText: { color: '#ffffff', fontSize: 16 },
+  card: {
+    position: 'absolute',
+    left: 16,
+    right: 16,
+    bottom: 48,
+    padding: 16,
+    gap: 8,
+    borderRadius: 12,
+    backgroundColor: '#1f1f1f',
+  },
+  title: { color: '#ffffff', fontSize: 16, fontWeight: '600' },
+  message: { color: '#d4d4d4', fontSize: 14, lineHeight: 20 },
+  button: { alignSelf: 'flex-end', paddingVertical: 8, paddingHorizontal: 12 },
+  buttonText: { color: '#8ab4ff', fontSize: 15, fontWeight: '600' },
+})

package/src/core/annotations.ts

@@ -0,0 +1,116 @@
+/** A box drawn on the screenshot, in fractions of its width and height (what the server expects). */
+export interface AnnotationBox {
+  kind: 'highlight' | 'blur'
+  x: number
+  y: number
+  w: number
+  h: number
+}
+
+/** Boxes smaller than this (in fractions) are treated as accidental taps. */
+const MIN_SIZE = 0.03
+export const MAX_ANNOTATIONS = 10
+
+const clamp = (value: number) => Math.min(1, Math.max(0, value))
+const round = (value: number) => Math.round(value * 1000) / 1000
+
+/**
+ * The box between where a drag started and where it is now, in the drawing
+ * area's coordinates, normalized to its size. Works in any drag direction and
+ * clamps to the image. Returns null while the drag is too small to be a box.
+ */
+export function boxFromDrag(
+  kind: AnnotationBox['kind'],
+  start: { x: number; y: number },
+  current: { x: number; y: number },
+  size: { width: number; height: number },
+): AnnotationBox | null {
+  if (size.width <= 0 || size.height <= 0) return null
+  const x1 = clamp(start.x / size.width)
+  const y1 = clamp(start.y / size.height)
+  const x2 = clamp(current.x / size.width)
+  const y2 = clamp(current.y / size.height)
+  const w = Math.abs(x2 - x1)
+  const h = Math.abs(y2 - y1)
+  if (w < MIN_SIZE || h < MIN_SIZE) return null
+  return { kind, x: round(Math.min(x1, x2)), y: round(Math.min(y1, y2)), w: round(w), h: round(h) }
+}
+
+/** A freehand line drawn on the screenshot: points in fractions of its width and height. */
+export interface AnnotationStroke {
+  kind: 'draw'
+  points: [number, number][]
+}
+
+export type Annotation = AnnotationBox | AnnotationStroke
+
+/** The most points a stroke keeps; longer ones are thinned evenly. */
+export const MAX_STROKE_POINTS = 120
+/** Points closer than this to the last one (in fractions) add nothing visible. */
+const MIN_STEP = 0.004
+
+/**
+ * Adds a touch position, in the drawing area's coordinates, to a stroke.
+ * Returns the same array when the point is too close to the last one, so a
+ * slow finger doesn't pile up points.
+ */
+export function addStrokePoint(
+  points: [number, number][],
+  at: { x: number; y: number },
+  size: { width: number; height: number },
+): [number, number][] {
+  if (size.width <= 0 || size.height <= 0) return points
+  const next: [number, number] = [round(clamp(at.x / size.width)), round(clamp(at.y / size.height))]
+  const last = points.at(-1)
+  if (last && Math.hypot(next[0] - last[0], next[1] - last[1]) < MIN_STEP) return points
+  return [...points, next]
+}
+
+/** Keeps the first and last points and an even spread between, up to `max`. */
+export function thinStroke(
+  points: [number, number][],
+  max = MAX_STROKE_POINTS,
+): [number, number][] {
+  if (points.length <= max) return points
+  const step = (points.length - 1) / (max - 1)
+  return Array.from({ length: max }, (_, i) => points[Math.round(i * step)] as [number, number])
+}
+
+/** A finished stroke, or null when it was only a tap. */
+export function finishStroke(points: [number, number][]): AnnotationStroke | null {
+  return points.length >= 2 ? { kind: 'draw', points: thinStroke(points) } : null
+}
+
+export interface Segment {
+  left: number
+  top: number
+  length: number
+  angle: number
+}
+
+/**
+ * A stroke as straight segments in pixels, each centered on its midpoint and
+ * rotated into place, for drawing with plain views.
+ */
+export function strokeSegments(
+  points: [number, number][],
+  size: { width: number; height: number },
+): Segment[] {
+  const segments: Segment[] = []
+  for (let i = 1; i < points.length; i++) {
+    const [ax, ay] = points[i - 1] as [number, number]
+    const [bx, by] = points[i] as [number, number]
+    const x1 = ax * size.width
+    const y1 = ay * size.height
+    const x2 = bx * size.width
+    const y2 = by * size.height
+    const length = Math.hypot(x2 - x1, y2 - y1)
+    segments.push({
+      left: (x1 + x2) / 2 - length / 2,
+      top: (y1 + y2) / 2,
+      length,
+      angle: Math.atan2(y2 - y1, x2 - x1),
+    })
+  }
+  return segments
+}

package/src/core/bubble.ts

@@ -0,0 +1,45 @@
+export interface Point {
+  x: number
+  y: number
+}
+
+export interface Bounds {
+  width: number
+  height: number
+  /** Space kept clear at the top and bottom, for the status bar and home indicator. */
+  insetTop: number
+  insetBottom: number
+}
+
+export const BUBBLE_SIZE = 48
+export const EDGE_MARGIN = 8
+/** Movement under this many points counts as a tap, not a drag. */
+export const TAP_SLOP = 6
+
+function clampY(y: number, bounds: Bounds, size: number) {
+  const min = bounds.insetTop
+  const max = bounds.height - bounds.insetBottom - size
+  return Math.min(Math.max(y, min), Math.max(min, max))
+}
+
+/** Where the bubble rests after a drag: the nearer side edge, kept on screen. */
+export function snapToEdge(point: Point, bounds: Bounds, size = BUBBLE_SIZE): Point {
+  const left = point.x + size / 2 < bounds.width / 2
+  return {
+    x: left ? EDGE_MARGIN : bounds.width - size - EDGE_MARGIN,
+    y: clampY(point.y, bounds, size),
+  }
+}
+
+/** Starts on the right edge, a little above the bottom, clear of most tab bars. */
+export function defaultPosition(bounds: Bounds, size = BUBBLE_SIZE): Point {
+  return snapToEdge(
+    { x: bounds.width, y: bounds.height - bounds.insetBottom - size - 96 },
+    bounds,
+    size,
+  )
+}
+
+export function isTap(dx: number, dy: number) {
+  return Math.abs(dx) < TAP_SLOP && Math.abs(dy) < TAP_SLOP
+}

package/src/core/controller.ts

@@ -0,0 +1,119 @@
+import { scenarioIdFromToken } from './feedback.js'
+import { type LaunchDeps, type LaunchError, type LaunchStage, runLaunch } from './launch.js'
+import { parseLaunchUrl } from './url.js'
+
+/**
+ * Where a launch came from: a link opened from outside the app, or the
+ * Review popover's Set Up button. The popover shows its own progress for
+ * launches it started, so the full-screen overlay only covers links.
+ */
+export type LaunchSource = 'link' | 'app'
+
+export type LaunchState =
+  | { status: 'idle' }
+  | { status: 'launching'; source: LaunchSource; stage?: LaunchStage }
+  | { status: 'done'; source: LaunchSource; path: string }
+  | { status: 'error'; source: LaunchSource; error: LaunchError }
+
+export type ControllerDeps = Omit<LaunchDeps, 'navigate'>
+type Navigate = LaunchDeps['navigate']
+
+/** A value that may not exist yet; `get()` waits for it. */
+function slot<T>() {
+  let value: T | undefined
+  let waiters: ((value: T) => void)[] = []
+  return {
+    set(next: T | undefined) {
+      value = next
+      if (next === undefined) return
+      for (const resolve of waiters) resolve(next)
+      waiters = []
+    },
+    get(): Promise<T> {
+      return value !== undefined
+        ? Promise.resolve(value)
+        : new Promise((resolve) => waiters.push(resolve))
+    },
+  }
+}
+
+/**
+ * Turns incoming URLs into launches. Each token runs once and launches run one
+ * at a time. A URL can arrive before the app is ready (Expo Router hands over
+ * the initial URL before the root layout mounts), so each launch waits for
+ * `configure()` and navigation waits for `setNavigator()`.
+ */
+export function createLaunchController() {
+  let state: LaunchState = { status: 'idle' }
+  const listeners = new Set<() => void>()
+  const seen = new Set<string>()
+  const queue: { token: string; source: LaunchSource }[] = []
+  const deps = slot<ControllerDeps>()
+  const navigator = slot<Navigate>()
+  let running = false
+  let lastScenarioId: string | undefined
+
+  function setState(next: LaunchState) {
+    state = next
+    for (const listener of listeners) listener()
+  }
+
+  async function drain() {
+    if (running) return
+    running = true
+    try {
+      for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+        const { token, source } = next
+        const current = await deps.get()
+        setState({ status: 'launching', source })
+        const result = await runLaunch(token, {
+          ...current,
+          navigate: async (path) => (await navigator.get())(path),
+          onStage: (stage) => setState({ status: 'launching', source, stage }),
+        })
+        if (result.ok) lastScenarioId = scenarioIdFromToken(token)
+        setState(
+          result.ok
+            ? { status: 'done', source, path: result.path }
+            : { status: 'error', source, error: result.error },
+        )
+      }
+    } finally {
+      running = false
+    }
+  }
+
+  return {
+    /** Queues a launch if `url` carries a token not seen before. Returns whether it did. */
+    offer(url: string | null | undefined, source: LaunchSource = 'link'): boolean {
+      const token = parseLaunchUrl(url)
+      if (!token || seen.has(token)) return false
+      seen.add(token)
+      queue.push({ token, source })
+      void drain()
+      return true
+    },
+    /** Supplies the seed hook URL and adapters; queued launches start once this is called. */
+    configure(next: ControllerDeps | undefined) {
+      deps.set(next)
+    },
+    /** Pass the router's navigate once it can navigate; undefined when it unmounts. */
+    setNavigator(next: Navigate | undefined) {
+      navigator.set(next)
+    },
+    dismiss() {
+      if (state.status === 'error' || state.status === 'done') setState({ status: 'idle' })
+    },
+    getState: () => state,
+    /** The scenario the app was last launched into, for attributing reports. */
+    lastScenarioId: () => lastScenarioId,
+    subscribe(listener: () => void) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+  }
+}
+
+export type LaunchController = ReturnType<typeof createLaunchController>

package/src/core/diagnostics.ts

@@ -0,0 +1,128 @@
+/** What a report carries about the moments before it: bounded, scrubbed, no request bodies. */
+export interface Diagnostics {
+  screens: { path: string; at: number }[]
+  logs: { level: 'error' | 'warn'; message: string; at: number }[]
+  requests: { method: string; path: string; status: number; at: number }[]
+}
+
+const LIMITS = { screens: 20, logs: 20, requests: 10 }
+
+/** Removes credentials from text: query params, Bearer headers and JWT-looking strings. */
+export function redact(text: string): string {
+  return text
+    .replace(
+      /\b(access_token|refresh_token|id_token|token|apikey|api_key|key|password|secret|t)=([^&\s"']+)/gi,
+      '$1=[redacted]',
+    )
+    .replace(/\bBearer\s+[^\s"']+/gi, 'Bearer [redacted]')
+    .replace(/\beyJ[\w-]+\.[\w-]+\.[\w-]+/g, '[jwt]')
+}
+
+/** Host and path only: query strings often carry tokens or personal data. */
+export function requestPath(url: string): string {
+  const [withoutQuery = ''] = url.split(/[?#]/)
+  const match = /^[a-z][a-z0-9+.-]*:\/\/([^/]+)(\/.*)?$/i.exec(withoutQuery)
+  return redact(match ? `${match[1]}${match[2] ?? '/'}` : withoutQuery)
+}
+
+function format(args: unknown[]): string {
+  return args
+    .map((arg) => {
+      if (typeof arg === 'string') return arg
+      if (arg instanceof Error) return `${arg.name}: ${arg.message}`
+      try {
+        return JSON.stringify(arg)
+      } catch {
+        return String(arg)
+      }
+    })
+    .join(' ')
+}
+
+function push<T>(list: T[], item: T, max: number) {
+  list.push(item)
+  if (list.length > max) list.splice(0, list.length - max)
+}
+
+export function createDiagnostics(now: () => number = Date.now) {
+  const screens: Diagnostics['screens'] = []
+  const logs: Diagnostics['logs'] = []
+  const requests: Diagnostics['requests'] = []
+
+  return {
+    recordScreen(path: string) {
+      if (screens.at(-1)?.path === path) return
+      push(screens, { path: requestPath(path), at: now() }, LIMITS.screens)
+    },
+    recordLog(level: 'error' | 'warn', args: unknown[]) {
+      push(logs, { level, message: redact(format(args)).slice(0, 500), at: now() }, LIMITS.logs)
+    },
+    recordRequest(method: string, url: string, status: number) {
+      push(
+        requests,
+        {
+          method: method.toUpperCase().slice(0, 10),
+          path: requestPath(url).slice(0, 300),
+          status,
+          at: now(),
+        },
+        LIMITS.requests,
+      )
+    },
+    snapshot(): Diagnostics {
+      return { screens: [...screens], logs: [...logs], requests: [...requests] }
+    },
+  }
+}
+
+export type DiagnosticsRecorder = ReturnType<typeof createDiagnostics>
+
+interface Hooks {
+  console: Pick<Console, 'error' | 'warn'>
+  errorUtils?: {
+    getGlobalHandler(): (error: unknown, isFatal?: boolean) => void
+    setGlobalHandler(handler: (error: unknown, isFatal?: boolean) => void): void
+  }
+  fetchHost: { fetch: typeof fetch }
+}
+
+/**
+ * Starts recording console errors and warnings, uncaught errors and failed
+ * requests. Each hook calls through to the original, so the app behaves the
+ * same. Requests to `ignoreUrl` (Tapthrough itself) are skipped.
+ */
+export function installDiagnostics(recorder: DiagnosticsRecorder, hooks: Hooks, ignoreUrl: string) {
+  const { console: target, errorUtils, fetchHost } = hooks
+
+  for (const level of ['error', 'warn'] as const) {
+    const original = target[level].bind(target)
+    target[level] = (...args: unknown[]) => {
+      recorder.recordLog(level, args)
+      original(...args)
+    }
+  }
+
+  if (errorUtils) {
+    const previous = errorUtils.getGlobalHandler()
+    errorUtils.setGlobalHandler((error, isFatal) => {
+      recorder.recordLog('error', [isFatal ? 'Uncaught (fatal):' : 'Uncaught:', error])
+      previous(error, isFatal)
+    })
+  }
+
+  const originalFetch = fetchHost.fetch
+  fetchHost.fetch = async (input, init) => {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+    const method =
+      init?.method ?? (typeof input === 'object' && 'method' in input ? input.method : 'GET')
+    const ignored = url.startsWith(ignoreUrl)
+    try {
+      const response = await originalFetch(input, init)
+      if (!ignored && !response.ok) recorder.recordRequest(method, url, response.status)
+      return response
+    } catch (error) {
+      if (!ignored) recorder.recordRequest(method, url, 0)
+      throw error
+    }
+  }
+}