rn-backstage 1.4.3 → 1.4.4

package/README.md

@@ -104,7 +104,6 @@ Pass a `storageAdapter` to render a **Storage** tab that lets you browse, edit,
 
 ```tsx
 import AsyncStorage from '@react-native-async-storage/async-storage'
-
 ;<Backstage
   storageAdapter={{
     getAllKeys: () => AsyncStorage.getAllKeys(),
@@ -119,7 +118,6 @@ MMKV example:
 
 ```tsx
 import { storage } from './mmkv'
-
 ;<Backstage
   storageAdapter={{
     getAllKeys: () => Promise.resolve(storage.getAllKeys()),
@@ -181,7 +179,7 @@ Add a `bugReport` config to enable one-tap bug reporting. Tapping the 🐛 butto
 | `pillWidth`              | `number`                      | `60`        | Width of the floating pill                      |
 | `pillHeight`             | `number`                      | `32`        | Height of the floating pill                     |
 | `extraTabs`              | `BackstageTab[]`              | `[]`        | Additional custom tabs                          |
-| `bugReport`              | `BugReportConfig`             | `undefined` | Bug report config (shows 🐛 button in header)    |
+| `bugReport`              | `BugReportConfig`             | `undefined` | Bug report config (shows 🐛 button in header)   |
 | `styles`                 | `BackstageStyleOverrides`     | `undefined` | Custom style overrides                          |
 | `children`               | `ReactNode`                   | `undefined` | Extra content in InfoTab                        |
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "rn-backstage",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "description": "A zero-dependency developer/QA debug panel for React Native apps",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
   "types": "lib/typescript/index.d.ts",
-  "react-native": "lib/module/index",
+  "react-native": "src/index",
   "source": "src/index",
   "files": [
+    "src",
     "lib",
-    "README.md",
     "!**/__tests__",
     "!**/__fixtures__",
     "!**/__mocks__",

package/src/Backstage.tsx

@@ -0,0 +1,227 @@
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react'
+import { StyleSheet, View } from 'react-native'
+import { DEFAULT_MAX_LOGS, DEFAULT_MAX_NETWORK_ENTRIES } from './constants'
+import { installInterceptor, LogBuffer, uninstallInterceptor } from './log-interceptor'
+import {
+  installNetworkInterceptor,
+  NetworkBuffer,
+  uninstallNetworkInterceptor,
+} from './network-interceptor'
+import { FloatingPill } from './components/FloatingPill'
+import { BackstagePanel } from './components/BackstagePanel'
+import { BackstageThemeProvider } from './ThemeContext'
+import type { BackstageProps, BackstageRef, LogEntry, NetworkEntry } from './types'
+
+// ─── Component ───────────────────────────────────────────────────────────────
+
+export const Backstage = forwardRef<BackstageRef, BackstageProps>(
+  (
+    {
+      visible = true,
+      theme: themePreference = 'auto',
+      appVersion,
+      buildNumber,
+      bundleId,
+      deviceInfo,
+      state,
+      quickActions,
+      featureFlags,
+      onToggleFeatureFlag,
+      storageAdapter,
+      maxLogs = DEFAULT_MAX_LOGS,
+      logFilters,
+      onCopyLogs,
+      extraTabs,
+      children,
+      styles: propStyles,
+      initialX,
+      initialY,
+      pillText,
+      pillWidth,
+      pillHeight,
+      enableNetworkInspector = true,
+      maxNetworkEntries = DEFAULT_MAX_NETWORK_ENTRIES,
+      maxNetworkBodySize,
+      networkFilters,
+      autoFilterNetworkLogs = true,
+      jsonMaxDepth,
+      bugReport: bugReportConfig,
+    },
+    ref,
+  ) => {
+    const [panelVisible, setPanelVisible] = useState(false)
+    const [hasError, setHasError] = useState(false)
+    const [logs, setLogs] = useState<LogEntry[]>([])
+    const [networkEntries, setNetworkEntries] = useState<NetworkEntry[]>([])
+
+    const logBuffer = useRef(new LogBuffer(maxLogs))
+    const networkBuffer = useRef(new NetworkBuffer(maxNetworkEntries))
+
+    // ── Panel controls ────────────────────────────────────────
+
+    const openPanel = useCallback(() => {
+      setPanelVisible(true)
+      // Sync logs and network entries when opening panel
+      setLogs(logBuffer.current.getAll())
+      setNetworkEntries(networkBuffer.current.getAll())
+    }, [])
+
+    const closePanel = useCallback(() => {
+      setPanelVisible(false)
+    }, [])
+
+    const clearLogs = useCallback(() => {
+      logBuffer.current.clear()
+      setLogs([])
+      setHasError(false)
+    }, [])
+
+    // ── Refresh logs ──────────────────────────────────────────────────
+
+    const refreshLogs = useCallback(() => {
+      setLogs(logBuffer.current.getAll())
+    }, [])
+
+    // ── Network controls ──────────────────────────────────────────────
+
+    const refreshNetwork = useCallback(() => {
+      setNetworkEntries(networkBuffer.current.getAll())
+    }, [])
+
+    const clearNetwork = useCallback(() => {
+      networkBuffer.current.clear()
+      setNetworkEntries([])
+    }, [])
+
+    // ── Install console interceptor ───────────────────────────
+
+    useEffect(() => {
+      const handleLogEntry = (entry: LogEntry) => {
+        logBuffer.current.push(entry)
+
+        // Track error state for the floating pill
+        if (entry.level === 'error') {
+          setHasError(true)
+        }
+      }
+
+      installInterceptor(handleLogEntry, logFilters, {
+        autoFilterNetworkLogs: enableNetworkInspector && autoFilterNetworkLogs,
+      })
+
+      return () => {
+        uninstallInterceptor()
+      }
+    }, [logFilters, enableNetworkInspector, autoFilterNetworkLogs])
+
+    // ── Install network interceptor ───────────────────────────────
+
+    useEffect(() => {
+      if (!enableNetworkInspector) return
+
+      const handleNetworkEntry = (entry: NetworkEntry) => {
+        networkBuffer.current.upsert(entry)
+
+        // Auto-refresh if panel is open
+        if (panelVisible) {
+          setNetworkEntries(networkBuffer.current.getAll())
+        }
+      }
+
+      installNetworkInterceptor(handleNetworkEntry, {
+        filters: networkFilters,
+        maxBodySize: maxNetworkBodySize,
+      })
+
+      return () => {
+        uninstallNetworkInterceptor()
+      }
+    }, [enableNetworkInspector, networkFilters, maxNetworkBodySize, panelVisible])
+
+    // ── Expose ref methods ────────────────────────────────────
+
+    const openBugReportRef = useRef<(() => void) | null>(null)
+
+    useImperativeHandle(ref, () => ({
+      open: openPanel,
+      close: closePanel,
+      clearLogs,
+      submitBugReport: () => {
+        if (bugReportConfig) {
+          openPanel()
+          // Small delay to let panel mount first
+          setTimeout(() => openBugReportRef.current?.(), 100)
+        }
+      },
+    }))
+
+    // ── Render ────────────────────────────────────────────────
+
+    if (!visible) return null
+
+    const displayText = pillText || (appVersion ? `v${appVersion}` : 'DEV')
+
+    return (
+      <BackstageThemeProvider preference={themePreference}>
+        <View style={styles.container} pointerEvents="box-none">
+          <FloatingPill
+            text={displayText}
+            hasError={hasError}
+            onPress={openPanel}
+            initialX={initialX}
+            initialY={initialY}
+            pillWidth={pillWidth}
+            pillHeight={pillHeight}
+            styles={propStyles}
+          />
+          <BackstagePanel
+            visible={panelVisible}
+            onClose={closePanel}
+            appVersion={appVersion}
+            buildNumber={buildNumber}
+            bundleId={bundleId}
+            deviceInfo={deviceInfo}
+            state={state}
+            quickActions={quickActions}
+            featureFlags={featureFlags}
+            onToggleFeatureFlag={onToggleFeatureFlag}
+            logs={logs}
+            onRefreshLogs={refreshLogs}
+            onCopyLogs={onCopyLogs}
+            networkEntries={networkEntries}
+            onRefreshNetwork={refreshNetwork}
+            onClearNetwork={clearNetwork}
+            onCopyNetwork={onCopyLogs}
+            extraTabs={extraTabs}
+            jsonMaxDepth={jsonMaxDepth}
+            storageAdapter={storageAdapter}
+            bugReportConfig={bugReportConfig}
+            bugReportOpenerRef={openBugReportRef}
+            styles={propStyles}
+          >
+            {children}
+          </BackstagePanel>
+        </View>
+      </BackstageThemeProvider>
+    )
+  },
+)
+
+Backstage.displayName = 'Backstage'
+
+// ─── Styles ──────────────────────────────────────────────────────────────────
+
+const styles = StyleSheet.create({
+  container: {
+    ...StyleSheet.absoluteFillObject,
+    zIndex: 99999,
+    elevation: 99999,
+  },
+})

package/src/ThemeContext.tsx

@@ -0,0 +1,38 @@
+import React, { createContext, useContext, useMemo } from 'react'
+import { useColorScheme } from 'react-native'
+import { DarkTheme, LightTheme } from './constants'
+import type { BackstageTheme } from './types'
+
+// ─── Theme Preference ────────────────────────────────────────────────────────
+
+export type ThemePreference = 'light' | 'dark' | 'auto'
+
+// ─── Context ─────────────────────────────────────────────────────────────────
+
+const ThemeContext = createContext<BackstageTheme>(DarkTheme)
+
+// ─── Provider ────────────────────────────────────────────────────────────────
+
+interface ThemeProviderProps {
+  preference: ThemePreference
+  children: React.ReactNode
+}
+
+export const BackstageThemeProvider: React.FC<ThemeProviderProps> = ({ preference, children }) => {
+  const systemScheme = useColorScheme()
+
+  const theme = useMemo(() => {
+    if (preference === 'light') return LightTheme
+    if (preference === 'dark') return DarkTheme
+    // 'auto' — follow system, fallback to dark
+    return systemScheme === 'light' ? LightTheme : DarkTheme
+  }, [preference, systemScheme])
+
+  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>
+}
+
+// ─── Hook ────────────────────────────────────────────────────────────────────
+
+export function useBackstageTheme(): BackstageTheme {
+  return useContext(ThemeContext)
+}

package/src/bug-report.ts

@@ -0,0 +1,184 @@
+import { Platform } from 'react-native'
+import type {
+  AppInfoItem,
+  BugReport,
+  BugReportSeverity,
+  LogEntry,
+  NetworkEntry,
+} from './types'
+import { LogLevel } from './types'
+
+// ─── Report Composition ──────────────────────────────────────────────────────
+
+const SEVERITY_LABELS: Record<BugReportSeverity, string> = {
+  low: '🟢 Low',
+  medium: '🟡 Medium',
+  high: '🟠 High',
+  critical: '🔴 Critical',
+}
+
+function formatTimestamp(ts: number): string {
+  const d = new Date(ts)
+  return d.toISOString().replace('T', ' ').substring(0, 19)
+}
+
+function formatLogLevel(level: LogLevel): string {
+  switch (level) {
+    case LogLevel.error:
+      return '❌ ERROR'
+    case LogLevel.warn:
+      return '⚠️ WARN'
+    case LogLevel.info:
+      return 'ℹ️ INFO'
+    case LogLevel.debug:
+      return '🔍 DEBUG'
+    default:
+      return '📝 LOG'
+  }
+}
+
+export function formatDeviceInfoForReport(items: AppInfoItem[]): string {
+  if (items.length === 0) return ''
+  const lines = items.map(i => `- **${i.label}**: ${i.value}`)
+  return `## 📱 Device Info\n\n${lines.join('\n')}\n`
+}
+
+export function formatLogsForReport(logs: LogEntry[]): string {
+  if (logs.length === 0) return ''
+  const lines = logs.map(
+    l => `\`${formatTimestamp(l.timestamp)}\` ${formatLogLevel(l.level)} ${l.message}`,
+  )
+  return `## 📋 Console Logs (${logs.length})\n\n\`\`\`\n${lines.join('\n')}\n\`\`\`\n`
+}
+
+export function formatNetworkForReport(entries: NetworkEntry[]): string {
+  if (entries.length === 0) return ''
+  const lines = entries.map(e => {
+    const status = e.status ?? '⏳'
+    const duration = e.duration ? `${e.duration}ms` : '...'
+    return `- \`${e.method}\` ${e.url} → ${status} (${duration})`
+  })
+  return `## 🌐 Network Activity (${entries.length})\n\n${lines.join('\n')}\n`
+}
+
+export function formatStateForReport(state: Record<string, unknown>): string {
+  try {
+    const json = JSON.stringify(state, null, 2)
+    // Truncate if too large
+    const truncated = json.length > 5000 ? json.substring(0, 5000) + '\n... (truncated)' : json
+    return `## 🌳 State Snapshot\n\n\`\`\`json\n${truncated}\n\`\`\`\n`
+  } catch {
+    return `## 🌳 State Snapshot\n\n\`[Could not serialize state]\`\n`
+  }
+}
+
+export function composeBugReport(report: BugReport): string {
+  const sections: string[] = []
+
+  sections.push(`# 🐛 Bug Report: ${report.title}\n`)
+  sections.push(`**Severity**: ${SEVERITY_LABELS[report.severity]}`)
+  sections.push(`**Reported**: ${formatTimestamp(report.timestamp)}`)
+  sections.push(`**Platform**: ${Platform.OS} ${Platform.Version}\n`)
+
+  if (report.description) {
+    sections.push(`## Description\n\n${report.description}\n`)
+  }
+
+  if (report.deviceInfo.length > 0) {
+    sections.push(formatDeviceInfoForReport(report.deviceInfo))
+  }
+
+  if (report.logs.length > 0) {
+    sections.push(formatLogsForReport(report.logs))
+  }
+
+  if (report.networkEntries.length > 0) {
+    sections.push(formatNetworkForReport(report.networkEntries))
+  }
+
+  if (report.state && Object.keys(report.state).length > 0) {
+    sections.push(formatStateForReport(report.state))
+  }
+
+  if (report.screenshotUri) {
+    sections.push(`## 📸 Screenshot\n\nAttached: ${report.screenshotUri}\n`)
+  }
+
+  sections.push('---\n*Generated by rn-backstage*')
+
+  return sections.join('\n')
+}
+
+// ─── Webhook Submission ──────────────────────────────────────────────────────
+
+export async function submitToWebhook(
+  webhookUrl: string,
+  report: BugReport,
+): Promise<{ success: boolean; error?: string }> {
+  try {
+    const body: Record<string, unknown> = {
+      title: report.title,
+      description: report.description,
+      severity: report.severity,
+      platform: Platform.OS,
+      platformVersion: String(Platform.Version),
+      timestamp: report.timestamp,
+      deviceInfo: report.deviceInfo,
+      logs: report.logs.map(l => ({
+        level: l.level,
+        message: l.message,
+        timestamp: l.timestamp,
+      })),
+      networkEntries: report.networkEntries.map(e => ({
+        method: e.method,
+        url: e.url,
+        status: e.status,
+        duration: e.duration,
+      })),
+    }
+
+    if (report.state) {
+      body.state = report.state
+    }
+
+    if (report.screenshotUri) {
+      body.screenshotUri = report.screenshotUri
+    }
+
+    const response = await fetch(webhookUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      return { success: false, error: `HTTP ${response.status}` }
+    }
+
+    return { success: true }
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : 'Unknown error',
+    }
+  }
+}
+
+// ─── Device Info Builder ─────────────────────────────────────────────────────
+
+export function buildDeviceInfo(
+  appVersion?: string,
+  buildNumber?: string,
+  bundleId?: string,
+  extraInfo: AppInfoItem[] = [],
+): AppInfoItem[] {
+  const info: AppInfoItem[] = [
+    { label: 'Platform', value: `${Platform.OS} ${Platform.Version}` },
+  ]
+
+  if (appVersion) info.push({ label: 'App Version', value: appVersion })
+  if (buildNumber) info.push({ label: 'Build Number', value: buildNumber })
+  if (bundleId) info.push({ label: 'Bundle ID', value: bundleId })
+
+  return [...info, ...extraInfo]
+}