@synostudios/app-reporter 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Synostudios LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @synostudios/app-reporter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A floating bug-report button for Expo / React Native apps. Tap it, type what's wrong, and it sends a screenshot, your note and some context (route, app version, device, build commit) to your report endpoint.
+
+It shows only in development builds and TestFlight installs, never in App Store installs.
+
+- **Drag** the button anywhere; it snaps to the nearest side.
+- **Tap** to report. The button hides itself before the screenshot, so it isn't in it.
+- **Long-press** to hide it until the next launch.
+
+## Install
+
+```bash
+npx expo install @synostudios/app-reporter react-native-view-shot react-native-screens expo-application expo-device
+```
+
+The package includes a few lines of native Swift (to tell a TestFlight install from an App Store one), so rebuild the app afterwards: `npx expo run:ios`, or `expo prebuild` and a new build.
+
+## Use
+
+At the app's root:
+
+```tsx
+// src/app/_layout.tsx (Expo Router)
+import { IssueReporter } from "@synostudios/app-reporter";
+import { usePathname } from "expo-router";
+
+export default function RootLayout() {
+  const pathname = usePathname();
+  return (
+    <>
+      <Stack />
+      <IssueReporter
+        harnessUrl={process.env.EXPO_PUBLIC_HARNESS_URL}
+        getToken={async () => (await supabase.auth.getSession()).data.session?.access_token}
+        buildSha={process.env.EXPO_PUBLIC_KITCHEN_SHA}
+        getContext={() => ({ route: pathname })}
+      />
+    </>
+  );
+}
+```
+
+## Props
+
+| Prop | |
+|---|---|
+| `harnessUrl` | Base URL of the service that receives reports (`POST {harnessUrl}/api/reports`) |
+| `getToken` | The signed-in user's access token, sent as `Authorization: Bearer`. Your endpoint decides who may report |
+| `enabled` | Defaults to `isTestBuild` (below) |
+| `buildSha` | The git commit the build came from |
+| `getContext` | Extra context sent with the report, e.g. `{ route }` |
+| `insets` | Space to keep clear at the top and bottom; defaults suit a notched iPhone |
+
+## Where it shows
+
+A TestFlight build is the same binary that later goes to the App Store, so the switch happens at runtime. `isTestBuild` (exported) is true in dev builds, and in release builds on a real device whose App Store receipt is a sandbox one, which is what TestFlight installs get. App Store installs get a production receipt, so the button never renders there.
+
+The code still ships in App Store builds, switched off, so don't put anything secret in its props: authenticate reports with the user's own session, as above.
+
+The button and sheet render in a `FullWindowOverlay` (react-native-screens), a window above the app's, so they show over native modals and form sheets too.
+
+## License
+
+MIT

package/expo-module.config.json

@@ -0,0 +1,4 @@
+{
+  "platforms": ["apple"],
+  "apple": { "modules": ["ReporterModule"] }
+}

package/ios/AppOsReporter.podspec

@@ -0,0 +1,17 @@
+require 'json'
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'AppOsReporter'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.license        = package['license']
+  s.author         = 'Synostudios'
+  s.homepage       = 'https://www.npmjs.com/package/@synostudios/app-reporter'
+  s.platforms      = { :ios => '15.1' }
+  s.source         = { git: '' }
+  s.static_framework = true
+  s.swift_version  = '5.9'
+  s.dependency 'ExpoModulesCore'
+  s.source_files = '**/*.swift'
+end

package/ios/ReporterModule.swift

@@ -0,0 +1,35 @@
+import ExpoModulesCore
+import UIKit
+
+public class ReporterModule: Module {
+  private var timer: Timer?
+
+  public func definition() -> ModuleDefinition {
+    Name("AppOsReporter")
+
+    // TestFlight, Xcode and simulator installs carry a sandbox receipt; App Store installs a production one.
+    // ponytail: appStoreReceiptURL is deprecated from iOS 18 but still answers; switch to StoreKit's
+    // AppTransaction.shared.environment (async, iOS 16+) if Apple removes it.
+    Constant("isSandbox") {
+      Bundle.main.appStoreReceiptURL?.lastPathComponent == "sandboxReceipt"
+    }
+
+    // react-native-screens' FullWindowOverlay adds its view to the window once, when it mounts, so a modal or sheet
+    // presented afterwards lands on top of it. This keeps the overlay in front.
+    // ponytail: a 0.5s poll, since UIKit has no "a view controller was presented" hook; only runs while the reporter shows.
+    Function("keepOnTop") {
+      DispatchQueue.main.async {
+        guard self.timer == nil else { return }
+        self.timer = Timer.scheduledTimer(withTimeInterval: 0.5, repeats: true) { _ in
+          for case let scene as UIWindowScene in UIApplication.shared.connectedScenes {
+            for window in scene.windows {
+              for view in window.subviews where String(describing: type(of: view)).contains("FullWindowOverlayContainer") {
+                if view !== window.subviews.last { window.bringSubviewToFront(view) }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@synostudios/app-reporter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "A draggable bug-report button for Expo apps: screenshot, note and context, sent to your own endpoint. Shows only in dev and TestFlight builds.",
+  "license": "MIT",
+  "main": "src/index.tsx",
+  "types": "src/index.tsx",
+  "react-native": "src/index.tsx",
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "ios",
+    "expo-module.config.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "release": "npm run typecheck && npm version minor --no-git-tag-version && npm publish"
+  },
+  "peerDependencies": {
+    "expo": ">=52",
+    "expo-application": ">=6",
+    "expo-device": ">=7",
+    "react": ">=19",
+    "react-native": ">=0.79",
+    "react-native-screens": ">=4",
+    "react-native-view-shot": ">=4"
+  },
+  "devDependencies": {
+    "@types/react": "~19.3.0",
+    "expo": "~58.0.23",
+    "expo-application": "~58.1.2",
+    "expo-device": "~58.0.5",
+    "react": "19.3.0",
+    "react-native": "0.88.0",
+    "react-native-screens": "~4.30.0",
+    "react-native-view-shot": "^6.2.1",
+    "typescript": "~6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/drag.ts

@@ -0,0 +1,24 @@
+// Where the button settles after a drag, and whether a touch was a tap. Pure, so it's unit-tested.
+
+export const SIZE = 52;
+const MARGIN = 12;
+
+// Snaps to the nearer side edge and keeps the button inside the safe area, so it never covers the notch or home bar.
+export function snap(
+  x: number,
+  y: number,
+  screen: { width: number; height: number },
+  insets: { top: number; bottom: number } = { top: 0, bottom: 0 },
+) {
+  const left = MARGIN;
+  const right = screen.width - SIZE - MARGIN;
+  const top = insets.top + MARGIN;
+  const bottom = screen.height - insets.bottom - SIZE - MARGIN;
+  return { x: x + SIZE / 2 < screen.width / 2 ? left : right, y: Math.min(Math.max(y, top), Math.max(top, bottom)) };
+}
+
+// A touch that barely moved counts as a tap, not a drag.
+export const isTap = (dx: number, dy: number) => Math.hypot(dx, dy) < 6;
+
+// Starting spot: the right edge, two thirds of the way down.
+export const start = (screen: { width: number; height: number }) => ({ x: screen.width - SIZE - MARGIN, y: Math.round(screen.height * 0.66) });

package/src/index.tsx

@@ -0,0 +1,274 @@
+// A draggable button that files a bug, with a screenshot, on the app's Fixes tab in the App Harness.
+// Shows in dev builds and TestFlight installs, never in App Store installs: see README.md.
+import * as Application from "expo-application";
+import * as Device from "expo-device";
+import { requireOptionalNativeModule } from "expo"; // expo re-exports it; a direct expo-modules-core peer trips expo-doctor (2026-11-09)
+import { useEffect, useRef, useState } from "react";
+import {
+  ActivityIndicator,
+  Animated,
+  Image,
+  KeyboardAvoidingView,
+  Linking,
+  PanResponder,
+  Platform,
+  Pressable,
+  StyleSheet,
+  Text,
+  TextInput,
+  useWindowDimensions,
+  View,
+} from "react-native";
+import { FullWindowOverlay } from "react-native-screens";
+import { captureScreen } from "react-native-view-shot";
+import { isTap, SIZE, snap, start } from "./drag";
+
+// ios/ReporterModule.swift: true in a TestFlight install (and a simulator or Xcode install), false from the App Store.
+// Missing until the app's native code is rebuilt, which reads as false.
+const native = requireOptionalNativeModule<{ isSandbox: boolean; keepOnTop(): void }>("AppOsReporter");
+const sandbox = native?.isSandbox ?? false;
+/** Dev builds, and release builds installed from TestFlight. Never an App Store install. */
+export const isTestBuild = __DEV__ || (sandbox && Device.isDevice);
+
+export type IssueReporterProps = {
+  /** The harness, e.g. http://localhost:3000 (the iOS simulator reaches your Mac's localhost). */
+  harnessUrl: string | undefined;
+  /** The signed-in user's access token (e.g. the Supabase session's). The harness only takes reports from the app's testers. */
+  getToken: () => Promise<string | null | undefined> | string | null | undefined;
+  /** Defaults to isTestBuild: dev builds and TestFlight installs. */
+  enabled?: boolean;
+  /** The git commit this build came from, e.g. process.env.EXPO_PUBLIC_KITCHEN_SHA. The fix starts from it. */
+  buildSha?: string;
+  /** Extra context for the report, e.g. () => ({ route: pathname }). */
+  getContext?: () => Record<string, unknown>;
+  /** Space to keep clear at the top and bottom (safe area insets). */
+  insets?: { top: number; bottom: number };
+};
+
+type Sent = { url: string } | { error: string };
+
+export function IssueReporter({ enabled = isTestBuild, ...props }: IssueReporterProps) {
+  if (!enabled) return null;
+  return <Reporter {...props} />;
+}
+
+function Reporter({ harnessUrl, getToken, buildSha, getContext, insets = { top: 50, bottom: 34 } }: Omit<IssueReporterProps, "enabled">) {
+  const screen = useWindowDimensions();
+  const [pos] = useState(() => new Animated.ValueXY(start(screen)));
+  const [hidden, setHidden] = useState(false); // long-press hides it until the next launch
+  const [capturing, setCapturing] = useState(false);
+  const [shot, setShot] = useState<string | null>(null);
+  const [context, setContext] = useState<Record<string, unknown>>({});
+
+  const open = async () => {
+    const ctx = getContext?.() ?? {};
+    setCapturing(true);
+    // Let the button disappear from the screen before capturing it.
+    await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+    try {
+      setShot(await captureScreen({ format: "png", result: "base64" }));
+    } catch {
+      setShot(""); // report without a screenshot rather than not at all
+    } finally {
+      setCapturing(false);
+      setContext(ctx);
+    }
+  };
+
+  // Keep the overlay above sheets presented after it (ios/ReporterModule.swift).
+  useEffect(() => native?.keepOnTop(), []);
+
+  // The gesture handlers outlive renders, so they read the latest screen size and open() through a ref.
+  const latest = useRef({ screen, insets, open });
+  useEffect(() => {
+    latest.current = { screen, insets, open };
+  });
+  // eslint-disable-next-line react-hooks/refs -- the callbacks read the ref when a gesture fires, never during render
+  const [pan] = useState(() => {
+    const g = { at: start(screen), long: false, timer: undefined as ReturnType<typeof setTimeout> | undefined };
+    return PanResponder.create({
+      onStartShouldSetPanResponder: () => true,
+      onPanResponderGrant: () => {
+        g.long = false;
+        g.timer = setTimeout(() => {
+          g.long = true;
+          setHidden(true);
+        }, 700);
+      },
+      onPanResponderMove: (_, d) => {
+        if (!isTap(d.dx, d.dy)) clearTimeout(g.timer);
+        pos.setValue({ x: g.at.x + d.dx, y: g.at.y + d.dy });
+      },
+      onPanResponderRelease: (_, d) => {
+        clearTimeout(g.timer);
+        if (g.long) return;
+        if (isTap(d.dx, d.dy)) {
+          pos.setValue(g.at);
+          latest.current.open();
+          return;
+        }
+        g.at = snap(g.at.x + d.dx, g.at.y + d.dy, latest.current.screen, latest.current.insets);
+        Animated.spring(pos, { toValue: g.at, useNativeDriver: false, friction: 7 }).start();
+      },
+    });
+  });
+
+  if (hidden || capturing) return null;
+  // FullWindowOverlay is a window above the app's, so the button and sheet show over native modals and sheets too.
+  // Its children must be the button or the full-screen sheet themselves: a full-size wrapper would swallow every touch.
+  return (
+    <FullWindowOverlay>
+      {shot === null ? (
+        <Animated.View testID="app-os-reporter" {...pan.panHandlers} accessibilityRole="button" accessibilityLabel="Report a bug" style={[styles.button, pos.getLayout()]}>
+          <Text style={styles.glyph}>!</Text>
+        </Animated.View>
+      ) : (
+        <Sheet
+          shot={shot}
+          top={insets.top}
+          onClose={() => setShot(null)}
+          send={async (note, expected) => send({ harnessUrl, token: (await getToken()) ?? undefined, shot, note, expected, buildSha, context, screen })}
+        />
+      )}
+    </FullWindowOverlay>
+  );
+}
+
+function Sheet({ shot, top, onClose, send }: { shot: string; top: number; onClose: () => void; send: (note: string, expected: string) => Promise<Sent> }) {
+  const [note, setNote] = useState("");
+  const [expected, setExpected] = useState("");
+  const [sending, setSending] = useState(false);
+  const [sent, setSent] = useState<Sent | null>(null);
+  const submit = async () => {
+    setSending(true);
+    setSent(await send(note, expected));
+    setSending(false);
+  };
+  const done = sent && "url" in sent;
+  return (
+    <View style={[styles.sheet, { paddingTop: top }]} accessibilityViewIsModal>
+      <KeyboardAvoidingView behavior={Platform.OS === "ios" ? "padding" : undefined} style={{ flex: 1 }}>
+        <View style={styles.header}>
+          <Pressable onPress={onClose} hitSlop={12}>
+            <Text style={styles.link}>{done ? "Done" : "Cancel"}</Text>
+          </Pressable>
+          <Text style={styles.title}>Report a bug</Text>
+          {/* Send sits in the header, where the keyboard can't cover it */}
+          {done ? (
+            <View style={{ width: 60 }} />
+          ) : sending ? (
+            <ActivityIndicator style={{ width: 60 }} />
+          ) : (
+            <Pressable onPress={submit} disabled={!note.trim()} hitSlop={12} accessibilityRole="button">
+              <Text style={[styles.link, styles.send, !note.trim() && { opacity: 0.35 }]}>{sent ? "Retry" : "Send"}</Text>
+            </Pressable>
+          )}
+        </View>
+        {done ? (
+          <View style={styles.body}>
+            <Text style={styles.ok}>Reported</Text>
+            <Text style={styles.muted}>It&apos;s on the app&apos;s Fixes tab in the harness, where Claude is restating it.</Text>
+            <Pressable onPress={() => Linking.openURL(sent.url)} style={styles.secondary}>
+              <Text style={styles.secondaryText}>Open in the harness</Text>
+            </Pressable>
+          </View>
+        ) : (
+          <View style={styles.body}>
+            {/* eslint-disable-next-line jsx-a11y/alt-text -- a web rule; React Native's Image is labelled with accessibilityLabel */}
+            {shot ? <Image source={{ uri: `data:image/png;base64,${shot}` }} style={styles.thumb} resizeMode="contain" accessibilityLabel="Screenshot of the screen you were on" /> : <Text style={styles.muted}>No screenshot (capture failed).</Text>}
+            <TextInput
+              value={note}
+              onChangeText={setNote}
+              placeholder="What's wrong?"
+              multiline
+              autoFocus
+              style={[styles.input, { minHeight: 90 }]}
+              editable={!sending}
+            />
+            <TextInput value={expected} onChangeText={setExpected} placeholder="What did you expect? (optional)" style={styles.input} editable={!sending} />
+            {sent && "error" in sent && <Text style={styles.error}>{sent.error}</Text>}
+          </View>
+        )}
+      </KeyboardAvoidingView>
+    </View>
+  );
+}
+
+async function send(r: {
+  harnessUrl?: string;
+  token?: string;
+  shot: string;
+  note: string;
+  expected: string;
+  buildSha?: string;
+  context: Record<string, unknown>;
+  screen: { width: number; height: number };
+}): Promise<Sent> {
+  if (!r.harnessUrl) return { error: "Set harnessUrl on <IssueReporter /> (see its README)." };
+  if (!r.token) return { error: "Sign in to the app first: the harness takes reports from its testers only." };
+  // One JSON body with the screenshot as base64: multipart file parts differ between React Native's fetch and Expo's
+  // (Expo's rejects { uri, name, type } parts with "Unsupported FormDataPart implementation").
+  const payload = JSON.stringify({
+    screenshot: r.shot || undefined,
+    report: {
+      note: r.note.trim(),
+      expected: r.expected.trim() || undefined,
+      meta: {
+        bundleId: Application.applicationId,
+        appVersion: Application.nativeApplicationVersion,
+        buildNumber: Application.nativeBuildVersion,
+        buildSha: r.buildSha,
+        platform: Platform.OS,
+        osVersion: Device.osVersion ?? String(Platform.Version),
+        device: Device.modelName,
+        simulator: !Device.isDevice,
+        screen: { width: Math.round(r.screen.width), height: Math.round(r.screen.height) },
+        context: r.context,
+      },
+    },
+  });
+  try {
+    const res = await fetch(`${r.harnessUrl.replace(/\/+$/, "")}/api/reports`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${r.token}`, "Content-Type": "application/json" },
+      body: payload,
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) return { error: body.error ?? `The harness answered ${res.status}.` };
+    return { url: body.url };
+  } catch (e) {
+    return { error: `Couldn't reach the harness at ${r.harnessUrl} (${e instanceof Error ? e.message : String(e)}).` };
+  }
+}
+
+const styles = StyleSheet.create({
+  button: {
+    position: "absolute",
+    width: SIZE,
+    height: SIZE,
+    borderRadius: SIZE / 2,
+    backgroundColor: "#18181b",
+    alignItems: "center",
+    justifyContent: "center",
+    shadowColor: "#000",
+    shadowOpacity: 0.25,
+    shadowRadius: 8,
+    shadowOffset: { width: 0, height: 3 },
+    elevation: 6,
+    zIndex: 9999,
+  },
+  glyph: { color: "#fff", fontSize: 24, fontWeight: "800" },
+  sheet: { position: "absolute", top: 0, left: 0, right: 0, bottom: 0, backgroundColor: "#fff" },
+  header: { flexDirection: "row", alignItems: "center", justifyContent: "space-between", padding: 16, borderBottomWidth: StyleSheet.hairlineWidth, borderColor: "#e4e4e7" },
+  title: { fontSize: 17, fontWeight: "600", color: "#18181b" },
+  link: { fontSize: 17, color: "#2563eb", width: 60 },
+  send: { fontWeight: "600", textAlign: "right" },
+  body: { padding: 16, gap: 12 },
+  thumb: { height: 220, borderRadius: 12, backgroundColor: "#f4f4f5" },
+  input: { borderWidth: 1, borderColor: "#d4d4d8", borderRadius: 10, padding: 12, fontSize: 16, color: "#18181b", textAlignVertical: "top" },
+  secondary: { borderWidth: 1, borderColor: "#d4d4d8", borderRadius: 10, height: 44, alignItems: "center", justifyContent: "center" },
+  secondaryText: { color: "#18181b", fontSize: 16, fontWeight: "500" },
+  ok: { fontSize: 22, fontWeight: "700", color: "#047857" },
+  muted: { color: "#71717a", fontSize: 15 },
+  error: { color: "#dc2626", fontSize: 15 },
+});