@testerpaykit/react 0.0.0-stage → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,876 @@
+import React from 'react';
+import { DeviceMetadata, AppMetadata, TesterPayKit } from '@testerpaykit/sdk';
+export { ActionResult, AgentAction, WidgetInfoForLlm, discoverWidgets, executeAction, isSyntheticEvent, redactSensitive, resetWidgetIds } from '@testerpaykit/ai-tester';
+
+interface TesterPayKitProviderProps {
+    apiKey: string;
+    projectId: string;
+    testerId: string;
+    deviceId: string;
+    deviceMetadata: DeviceMetadata;
+    appMetadata: AppMetadata;
+    baseURL?: string;
+    children: React.ReactNode;
+}
+/**
+ * React Context Provider for TesterPayKit SDK.
+ *
+ * Wraps your app to provide TesterPayKit functionality via the useTesterPayKit hook.
+ *
+ * @example
+ * ```tsx
+ * <TesterPayKitProvider
+ *   apiKey="your-api-key"
+ *   projectId="project-123"
+ *   testerId="tester-456"
+ *   deviceId="device-789"
+ *   deviceMetadata={{ os: 'Web', osVersion: '1.0', ... }}
+ *   appMetadata={{ bundleId: 'com.example.app', version: '1.0.0', ... }}
+ * >
+ *   <App />
+ * </TesterPayKitProvider>
+ * ```
+ */
+declare function TesterPayKitProvider({ apiKey, projectId, testerId, deviceId, deviceMetadata, appMetadata, baseURL, children, }: TesterPayKitProviderProps): React.JSX.Element;
+/**
+ * React hook for accessing TesterPayKit SDK functionality.
+ *
+ * Must be used within a TesterPayKitProvider.
+ *
+ * @returns Object containing tracking methods and SDK instance
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { trackScreenView, trackTap } = useTesterPayKit();
+ *
+ *   useEffect(() => {
+ *     trackScreenView('MyComponent');
+ *   }, []);
+ *
+ *   return (
+ *     <button onClick={() => trackTap('MyComponent', 'submit-btn')}>
+ *       Submit
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useTesterPayKit(): {
+    trackScreenView: (screenName: string, metadata?: Record<string, any>) => Promise<void>;
+    trackTap: (screenName: string, elementId?: string) => Promise<void>;
+    trackEvent: (eventType: string, metadata?: Record<string, any>) => Promise<void>;
+    trackError: (message: string, stack?: string) => Promise<void>;
+    sdk: TesterPayKit | null;
+};
+
+/**
+ * TpkBugReportButton — back-compat thin wrapper around TpkBugReportSheet.
+ *
+ * Renders its own circular FAB that opens/closes a TpkBugReportSheet.
+ * Existing consumers and all tests targeting tpk-bug-report-fab /
+ * tpk-bug-report-overlay / tpk-bug-* testids keep working unchanged.
+ */
+
+interface TpkBugReportButtonProps {
+    /** Initialised TesterPayKit SDK instance. */
+    sdk: TesterPayKit;
+    /**
+     * Screen / route label passed as `currentScreen` in the report.
+     * Falls back to `window.location.pathname` when omitted.
+     */
+    currentScreen?: string;
+    /** Override the button label. Default: "Report a bug". */
+    label?: string;
+    /** Called after the report is enqueued (localId = outbox UUID). */
+    onSubmitted?: (localId: string) => void;
+}
+declare function TpkBugReportButton({ sdk, currentScreen, label, onSubmitted, }: TpkBugReportButtonProps): React.ReactElement;
+
+/**
+ * TpkBugReportSheet — 4-step wizard for submitting rich bug reports.
+ *
+ * Step 1 — Typ & Schwere: type chips + severity selector
+ * Step 2 — Details: title*, description*, expected/actual behavior, frequency,
+ *                   affected feature + voice mic (prefills title+description)
+ * Step 3 — Reproduktion & Beleg: reproduction steps list + screenshot
+ * Step 4 — Überprüfen & Senden: read-only summary + submit
+ *
+ * Back-compat: all data-testid hooks from Phase 1/2 are preserved so
+ * existing screenshot + voice + annotate test suites keep passing.
+ */
+
+interface TpkBugReportSheetProps {
+    /** Initialised TesterPayKit SDK instance. */
+    sdk: TesterPayKit;
+    /** Screen / route label passed as `currentScreen` in the report. */
+    currentScreen?: string;
+    /** Whether the sheet is currently open. */
+    open: boolean;
+    /** Called when the user dismisses the sheet (Cancel or backdrop tap). */
+    onClose: () => void;
+    /** Called after the report is enqueued (localId = outbox UUID). */
+    onSubmitted?: (localId: string) => void;
+    /**
+     * Which step to start on (1-indexed, default 1).
+     * Pass 2 to jump directly to the Details step (e.g. after a long-press voice launch).
+     */
+    initialStep?: number;
+    /**
+     * When true, automatically begin voice recording on mount at the Details step.
+     * The long-press release is a valid user-activation gesture for getUserMedia.
+     * If the mic throws / is denied, falls back to the idle mic state (never crashes).
+     */
+    autoStartVoice?: boolean;
+}
+declare function TpkBugReportSheet({ sdk, currentScreen, open, onClose, onSubmitted, initialStep, autoStartVoice, }: TpkBugReportSheetProps): React.ReactElement | null;
+
+/**
+ * TesterPayKit brand tokens — single source of truth for the widget set.
+ *
+ * Usage: import { tpkTheme } from './theme'
+ * All widget components consume these values so visual changes only happen here.
+ */
+interface TpkColors {
+    /** Brand purple — primary buttons, focus rings, AI-related accents */
+    primary: string;
+    /** Bug-red FAB — stays visible on any background including red error screens */
+    bugRed: string;
+    /** Card / sheet background */
+    surface: string;
+    /** Alternate surface — hover states, subtle rows */
+    surfaceAlt: string;
+    /** Primary text */
+    text: string;
+    /** Secondary / muted text */
+    textMuted: string;
+    /** Dividers and input borders */
+    border: string;
+    /** Success state (confirmation, green check) */
+    success: string;
+    /** Danger state (delete, critical error label) */
+    danger: string;
+    /** Dim backdrop when a modal / menu is open */
+    backdrop: string;
+}
+interface TpkRadius {
+    sm: number;
+    md: number;
+    lg: number;
+}
+interface TpkZIndex {
+    /** Widget overlay — sits above all host-app UI (incl. MUI Drawers, etc.) */
+    overlay: number;
+    /** Menu popup — above the overlay backdrop but below the FAB itself */
+    menu: number;
+    /** FAB button — topmost */
+    fab: number;
+}
+interface TpkTheme {
+    colors: TpkColors;
+    radius: TpkRadius;
+    shadow: string;
+    zIndex: TpkZIndex;
+    spacing: (multiplier: number) => number;
+}
+declare const tpkTheme: TpkTheme;
+
+/**
+ * TesterPayKit i18n — translation dictionary + helpers.
+ *
+ * Default locale: 'de'. English is additive.
+ * makeT(locale) returns a t(key, params?) function.
+ * Falls back to 'de' for any key missing in the target locale.
+ * Supports simple {param} interpolation.
+ */
+type TpkLocale = 'de' | 'en';
+declare const MESSAGES: Record<TpkLocale, Record<string, string>>;
+/**
+ * Returns a translation function for the given locale.
+ * Falls back to 'de' for any key missing in the target locale.
+ * Replaces {param} placeholders with provided param values.
+ */
+declare function makeT(locale: TpkLocale): (key: string, params?: Record<string, string | number>) => string;
+
+/**
+ * TpkTesterHub — branded FAB hub with a popup menu.
+ *
+ * Renders a fixed bottom-right bug-red circular FAB (white ring so it's
+ * visible on any background). Tap opens a card popup menu above the FAB
+ * with a dim backdrop. The FAB glyph rotates to ✕ while open.
+ *
+ * Menu items are defined as data so later phases can add new entries
+ * without modifying the render logic. See the TODO below for the
+ * planned extension items.
+ *
+ * TODO — future menu items (Phase 2+):
+ *   - "📋 Meine Bugs"      → opens the tester's submitted-bug list
+ *   - "🔔 Benachrichtigungen" → opens the in-widget notification feed (with badge)
+ *   - "📊 Session Details"    → earnings + activity summary for the current session
+ *   - "🔄 My Retests"         → retest queue (when assigned retests > 0)
+ */
+
+interface TpkTesterHubProps {
+    /** Initialised TesterPayKit SDK instance. */
+    sdk: TesterPayKit;
+    /** Current screen / route label forwarded to bug reports. */
+    currentScreen?: string;
+    /**
+     * When provided, an "AI-Tester" menu item is shown. All three sub-fields
+     * are forwarded to TpkAiTester.
+     */
+    aiTester?: {
+        apiBaseUrl: string;
+        coordinatorToken: string;
+        projectId: string;
+    };
+    /** Locale for all widget copy. Defaults to 'de'. */
+    locale?: TpkLocale;
+    /** Deep partial theme override. Merged on top of the default tpkTheme. */
+    theme?: Partial<TpkTheme>;
+    /**
+     * Gesture triggers for opening the bug report sheet.
+     * Both default to true. Set a key to false to disable that gesture.
+     */
+    gestures?: {
+        threeFingerTap?: boolean;
+        shake?: boolean;
+    };
+    /**
+     * When true, renders a floating TpkTaskPanel alongside the hub.
+     * Opt-in (default false) because a floating panel is intrusive.
+     * The panel shows only when tasks exist.
+     */
+    taskPanel?: boolean;
+}
+declare function TpkTesterHub({ sdk, currentScreen, aiTester, locale, theme, gestures, taskPanel, }: TpkTesterHubProps): React.ReactElement | null;
+
+/**
+ * TpkTesterLauncher — the logged-out "springboard" wrapper around TpkTesterHub.
+ *
+ * On a public surface, NOT every visitor should get a working bug-report hub
+ * (a half-working tester widget on a promo is a reputation risk). This widget
+ * gates the hub behind a registered tester:
+ *
+ *   logged out  → small FAB → panel with three choices:
+ *                   • "Ich möchte Tester werden"  → opens the tester signup page
+ *                   • "Ich bin Tester"            → magic-link sign-in (email)
+ *                   • "Ausblenden"                → hides the widget (persisted)
+ *   logged in   → the full TpkTesterHub (bug report, my bugs, …)
+ *
+ * TesterPayKit tester auth is PASSWORDLESS (magic-link): the email step asks
+ * the server to mail a single-use link that returns to this app's
+ * `callbackPath` carrying a token. The callback page calls
+ * sdk.consumeTesterMagicLink(token), persists the session, and reloads — at
+ * which point this launcher restores it and shows the hub. The token is
+ * re-applied AFTER the SDK's anonymous auth settles so the registered identity
+ * always wins over the anonymous telemetry one.
+ */
+
+interface TpkTesterLauncherProps {
+    /** Initialised TesterPayKit SDK instance. */
+    sdk: TesterPayKit;
+    /** Current screen / route label forwarded to the hub. */
+    currentScreen?: string;
+    /** Locale for all widget copy. Defaults to 'de'. */
+    locale?: TpkLocale;
+    /** Where "become a tester" sends the user. */
+    becomeTesterUrl?: string;
+    /** App route that consumes the magic-link token. Default '/tester/callback'. */
+    callbackPath?: string;
+    theme?: TpkTesterHubProps['theme'];
+    aiTester?: TpkTesterHubProps['aiTester'];
+    gestures?: TpkTesterHubProps['gestures'];
+}
+declare function TpkTesterLauncher(props: TpkTesterLauncherProps): React.JSX.Element | null;
+
+/**
+ * TpkMyBugsScreen — slide-in panel showing the tester's submitted bug reports.
+ *
+ * Controlled via { sdk, open, onClose }. On open, fetches from
+ * sdk.getMyBugReports() and renders a branded list with colour-coded
+ * status badges. Tapping a row expands its description.
+ */
+
+interface TpkMyBugsScreenProps {
+    sdk: TesterPayKit;
+    open: boolean;
+    onClose: () => void;
+}
+declare function TpkMyBugsScreen({ sdk, open, onClose }: TpkMyBugsScreenProps): React.ReactElement | null;
+
+/**
+ * TpkNotificationsScreen — slide-in panel showing the tester's notifications.
+ *
+ * Controlled via { sdk, open, onClose, onUnreadChange? }. On open, fetches
+ * from sdk.getNotifications(). Unread rows are visually distinct. Tapping a
+ * row marks it read; "Alle gelesen" marks all.
+ */
+
+interface TpkNotificationsScreenProps {
+    sdk: TesterPayKit;
+    open: boolean;
+    onClose: () => void;
+    /** Called with the new unread count after any read action. */
+    onUnreadChange?: (count: number) => void;
+}
+declare function TpkNotificationsScreen({ sdk, open, onClose, onUnreadChange, }: TpkNotificationsScreenProps): React.ReactElement | null;
+
+/**
+ * TpkGeneralFeedbackDialog — lightweight single-screen feedback dialog.
+ *
+ * DACH-first copy (German default, English via TpkUiProvider). Provides:
+ *   - 1–5 star rating
+ *   - Category select (Allgemein / Feature-Wunsch / Verbesserung / Lob / Kritik)
+ *   - Title field (max 100 chars)
+ *   - Details textarea (max 1000 chars)
+ *
+ * Submits via sdk.submitBugReport({ type: 'generalFeedback', ... })
+ * with rating + feedbackCategory in metadata.
+ */
+
+interface TpkGeneralFeedbackDialogProps {
+    sdk: TesterPayKit;
+    open: boolean;
+    onClose: () => void;
+    onSubmitted?: (localId: string) => void;
+    /** Current screen / route label forwarded to the report. */
+    currentScreen?: string;
+}
+declare function TpkGeneralFeedbackDialog({ sdk, open, onClose, onSubmitted, currentScreen, }: TpkGeneralFeedbackDialogProps): React.ReactElement | null;
+
+/**
+ * crashCapture — installs global window error handlers and persists the most
+ * recent uncaught error to localStorage under the key `tpk:pendingCrash`.
+ *
+ * SSR-safe: all window/localStorage accesses are guarded.
+ * Debounced: a burst of errors within 500 ms is coalesced into one entry.
+ */
+
+declare const PENDING_CRASH_KEY = "tpk:pendingCrash";
+interface PendingCrash {
+    message: string;
+    stack: string;
+    screen: string;
+    ts: number;
+}
+declare function getPendingCrash(): PendingCrash | null;
+declare function clearPendingCrash(): void;
+/**
+ * Installs `window.error` and `unhandledrejection` listeners.
+ * Returns an uninstaller function.
+ *
+ * Safe to call in SSR: returns a no-op uninstaller when `window` is absent.
+ */
+declare function installCrashCapture(sdk: TesterPayKit): () => void;
+
+/**
+ * TpkCrashDialog — displays a captured crash and lets the tester submit a report.
+ *
+ * Controlled: { sdk, crash, open, onClose, onSubmitted? }
+ * Red header. Shows error message + expandable stack trace (monospace).
+ * Optional "Was hast du gemacht?" notes textarea.
+ * Submit → sdk.submitBugReport({ type: 'crash', ... }) then clearPendingCrash().
+ * "Verwerfen" closes + clears.
+ */
+
+interface TpkCrashDialogProps {
+    sdk: TesterPayKit;
+    crash: PendingCrash | null;
+    open: boolean;
+    onClose: () => void;
+    onSubmitted?: (localId: string) => void;
+}
+declare function TpkCrashDialog({ sdk, crash, open, onClose, onSubmitted, }: TpkCrashDialogProps): React.ReactElement | null;
+
+/**
+ * TpkSessionEndDialog — quick end-of-session prompt.
+ *
+ * Controlled: { sdk, open, onClose, onSubmitted? }
+ * - 1–5 star rating
+ * - Short comment (required)
+ * - "Was hast du getestet?" optional field
+ *
+ * Submit → sdk.submitBugReport({ type: 'generalFeedback', metadata: { rating, kind: 'session_end', tested } })
+ *        then sdk.endSession('completed') (best-effort).
+ */
+
+interface TpkSessionEndDialogProps {
+    sdk: TesterPayKit;
+    open: boolean;
+    onClose: () => void;
+    onSubmitted?: (localId: string) => void;
+}
+declare function TpkSessionEndDialog({ sdk, open, onClose, onSubmitted, }: TpkSessionEndDialogProps): React.ReactElement | null;
+
+/**
+ * TpkDebugLogsScreen — slide-in panel showing the SDK debug log ring buffer.
+ *
+ * Shows the most recent entries newest-first in a monospace list, with a
+ * refresh button, a "Leeren" (clear) button, an empty state, and a small
+ * info block at the top with sessionId + current earnings.
+ */
+
+interface TpkDebugLogsScreenProps {
+    sdk: TesterPayKit;
+    open: boolean;
+    onClose: () => void;
+}
+declare function TpkDebugLogsScreen({ sdk, open, onClose, }: TpkDebugLogsScreenProps): React.ReactElement | null;
+
+/**
+ * TpkWorkboardScreen — slide-in panel showing the tester's assigned tasks
+ * plus the current build info.
+ *
+ * Controlled via { sdk, open, onClose }. On open, fetches sdk.getMyTasks()
+ * and optionally sdk.getMyPoints() (best-effort). Each task row has a
+ * "Starten" / "Erledigt" / ✓ action depending on its status.
+ */
+
+interface TpkWorkboardScreenProps {
+    sdk: TesterPayKit;
+    open: boolean;
+    onClose: () => void;
+}
+declare function TpkWorkboardScreen({ sdk, open, onClose }: TpkWorkboardScreenProps): React.ReactElement | null;
+
+/**
+ * TpkRetestScreen — slide-in panel showing the tester's retest queue.
+ *
+ * Controlled via { sdk, open, onClose }. On open, fetches sdk.getMyRetests().
+ * Each row shows bug title + status badge + fix info if present. Two action
+ * buttons: "Bestätigt (behoben)" → sdk.verifyRetest(bugId) and
+ * "Wieder offen" → sdk.reopenRetest(bugId). Re-fetches after each action.
+ *
+ * A bug with acceptance steps is judged step by step first: "Bestätigt"
+ * stays disabled until every step passed, and the verdicts go along with
+ * verify / reopen.
+ */
+
+interface TpkRetestScreenProps {
+    sdk: TesterPayKit;
+    open: boolean;
+    onClose: () => void;
+}
+declare function TpkRetestScreen({ sdk, open, onClose }: TpkRetestScreenProps): React.ReactElement | null;
+
+/**
+ * TpkSessionDetailsScreen — slide-in panel showing live session info.
+ *
+ * Pure local/live: no network calls needed. Shows session id, started-at,
+ * elapsed time, live earnings, and debug log count. A refresh button
+ * re-reads the live values from the SDK.
+ */
+
+interface TpkSessionDetailsScreenProps {
+    sdk: TesterPayKit;
+    open: boolean;
+    onClose: () => void;
+}
+declare function TpkSessionDetailsScreen({ sdk, open, onClose }: TpkSessionDetailsScreenProps): React.ReactElement | null;
+
+/**
+ * TpkTaskPanel — floating, draggable checklist panel (Flutter parity).
+ *
+ * Renders NOTHING when getMyTasks() returns an empty list.
+ * When tasks exist: a fixed, draggable card (collapsed by default) showing
+ * "Aufgaben X/Y" + a progress bar. Expanding reveals task rows with
+ * "Starten" / "Erledigt" actions. Can be dismissed for the session.
+ *
+ * z-index is intentionally below the FAB menu so it doesn't overlap controls.
+ * Position is fixed, bottom-left (so it doesn't clash with bottom-right FAB).
+ */
+
+interface TpkTaskPanelProps {
+    sdk: TesterPayKit;
+    /** Called when user dismisses the panel. */
+    onClose?: () => void;
+    /** Called after a task action so the parent can refresh its badge. */
+    onTasksChanged?: () => void;
+}
+declare function TpkTaskPanel({ sdk, onClose, onTasksChanged }: TpkTaskPanelProps): React.ReactElement | null;
+
+/**
+ * gestures.ts — lightweight gesture helpers for the TesterPayKit widget.
+ *
+ * All functions are SSR-safe (no-op when document/window is absent).
+ * Both installers return an uninstall function.
+ */
+/**
+ * Installs a document-level touchstart listener.
+ * When exactly 3 simultaneous touch points are detected, calls onTrigger.
+ * Debounced so rapid re-fires count as one gesture (300 ms window).
+ *
+ * @returns Uninstaller — call it to remove the listener.
+ */
+declare function installThreeFingerTap(onTrigger: () => void): () => void;
+interface ShakeDetectionOptions {
+    /** Acceleration delta threshold (m/s²) that counts as a shake. Default: 15. */
+    threshold?: number;
+    /** Minimum ms between successive triggers. Default: 1500. */
+    cooldownMs?: number;
+}
+/**
+ * Requests iOS DeviceMotion permission (needed on Safari iOS 13+).
+ * Must be called from a user-gesture handler.
+ *
+ * Returns:
+ *  - true  if permission granted or not required (Android / desktop)
+ *  - false if permission denied or DeviceMotionEvent unavailable
+ */
+declare function requestShakePermission(): Promise<boolean>;
+/**
+ * Installs a window-level 'devicemotion' listener.
+ * When the device is shaken (acceleration delta > threshold), calls onTrigger.
+ * Respects a cooldown between triggers.
+ *
+ * iOS guard: if DeviceMotionEvent.requestPermission exists, this function does
+ * NOT call it automatically (it needs a user gesture). Attach the listener
+ * immediately on non-iOS; on iOS the listener fires only after the caller
+ * obtains permission via requestShakePermission() — which is fine because
+ * the native OS only delivers events after permission is granted.
+ *
+ * No-op + never throws when DeviceMotionEvent is absent (e.g. jsdom).
+ *
+ * @returns Uninstaller — call it to remove the listener.
+ */
+declare function installShakeDetection(onTrigger: () => void, opts?: ShakeDetectionOptions): () => void;
+
+/**
+ * Web screenshot capture utility using html2canvas.
+ *
+ * Renders the current DOM to a canvas and returns a JPEG dataURL.
+ * Browser-only — returns null and logs a warning in non-browser environments
+ * or when html2canvas fails.
+ *
+ * Contract: Part B — web screenshot capture for TpkBugReportButton
+ *
+ * Auto-PII masking: any element carrying `data-tpk-sensitive` in the DOM
+ * (placed by <TpkSensitive> or by hand) is masked in the cloned document
+ * before rendering — nothing is sent to the canvas unredacted.
+ */
+/**
+ * Finds every `[data-tpk-sensitive]` element under `root`, applies the
+ * requested mask strategy, and returns the number of elements masked.
+ *
+ * Pure helper — operates on any object with `querySelectorAll`.
+ * Does NOT depend on html2canvas or a real browser: safe to unit-test in jsdom.
+ *
+ * @param root  Any DOM subtree root (Document, Element, or jsdom equivalent).
+ * @returns     Number of elements that were masked.
+ */
+declare function applySensitiveMasks(root: {
+    querySelectorAll: (sel: string) => ArrayLike<Element>;
+}): number;
+/**
+ * Capture the current page as a JPEG dataURL.
+ *
+ * @returns A JPEG dataURL string, or null if capture failed or unavailable.
+ */
+declare function captureScreenshot(): Promise<string | null>;
+
+/**
+ * TpkSensitive — auto-PII masking marker for screenshots.
+ *
+ * Wrap any React element in <TpkSensitive> and it will be automatically
+ * blurred or blocked in every screenshot captured by captureScreenshot().
+ *
+ * @example
+ *   <TpkSensitive>
+ *     <input type="password" ... />
+ *   </TpkSensitive>
+ *
+ *   // block mode (opaque rectangle):
+ *   <TpkSensitive mask="block">
+ *     <span>{cardNumber}</span>
+ *   </TpkSensitive>
+ *
+ * @remarks
+ * Non-React / third-party markup: add the attribute directly on any element:
+ *   <div data-tpk-sensitive data-tpk-mask="block">...</div>
+ * captureScreenshot will mask those elements the same way.
+ */
+
+type TpkSensitiveMask = 'blur' | 'block';
+interface TpkSensitiveProps {
+    /** Masking strategy. 'blur' (default) applies a 12 px gaussian blur.
+     *  'block' replaces the element with a solid opaque rectangle. */
+    mask?: TpkSensitiveMask;
+    children?: React.ReactNode;
+}
+/**
+ * Marker component. Renders a plain <span> with `data-tpk-sensitive`
+ * (and `data-tpk-mask`) so captureScreenshot can locate and mask it.
+ * Zero visual side-effect in normal rendering.
+ */
+declare function TpkSensitive({ mask, children }: TpkSensitiveProps): React.ReactElement;
+
+/**
+ * Browser MediaRecorder helper for voice bug capture.
+ *
+ * Usage:
+ *   const session = await startVoiceRecording();
+ *   if (session.unsupported) { ... }
+ *   // user records …
+ *   const result = await session.stop();
+ *   if (result) { sdk.extractBugFromVoice(result.base64, result.mimeType); }
+ */
+interface VoiceRecordingResult {
+    /** Raw base64 audio (no data: prefix). */
+    base64: string;
+    /** MIME type reported by MediaRecorder (e.g. 'audio/webm;codecs=opus'). */
+    mimeType: string;
+    /** Recording duration in milliseconds. */
+    durationMs: number;
+}
+interface VoiceRecordingSession {
+    /** Stop recording and resolve the result. Returns null if recording produced no data. */
+    stop: () => Promise<VoiceRecordingResult | null>;
+}
+interface VoiceRecordingUnsupported {
+    unsupported: true;
+    reason: string;
+}
+/**
+ * Start a voice recording session using the browser's MediaRecorder API.
+ *
+ * Returns a `VoiceRecordingUnsupported` discriminant when the environment
+ * does not support audio capture (SSR, no mic permission API, etc.) —
+ * it never throws.
+ */
+declare function startVoiceRecording(): Promise<VoiceRecordingSession | VoiceRecordingUnsupported>;
+
+/**
+ * Browser screen recording helper using the Screen Capture API.
+ *
+ * Usage:
+ *   const result = await startScreenRecording();
+ *   if (result === 'unsupported') { ... }
+ *   if (result === 'cancelled') { ... }
+ *   const { stop } = result;
+ *   // user clicks stop later…
+ *   const recording = await stop();  // null if no data
+ */
+interface ScreenRecordingResult {
+    /** Raw base64 video data (no data: prefix). */
+    base64: string;
+    /** MIME type reported by MediaRecorder (e.g. 'video/webm'). */
+    mimeType: string;
+    /** Recording duration in milliseconds. */
+    durationMs: number;
+    /** Approximate byte size of the raw recording. */
+    sizeBytes: number;
+}
+interface ScreenRecordingSession {
+    /** Stop recording and resolve the result. Returns null if no data was produced. */
+    stop: () => Promise<ScreenRecordingResult | null>;
+}
+interface ScreenRecordingUnsupported {
+    unsupported: true;
+    reason: string;
+}
+/**
+ * Start a screen recording session using the browser's Screen Capture API.
+ *
+ * Returns:
+ *  - `{ unsupported: true, reason }` when the environment does not support
+ *    screen capture (SSR, old browser, no MediaRecorder).
+ *  - `'cancelled'` when the user dismissed the OS screen-picker
+ *    (getDisplayMedia rejects with NotAllowedError / name: 'NotAllowedError').
+ *  - A `ScreenRecordingSession` with a `stop()` method when recording is underway.
+ *
+ * Never throws.
+ */
+declare function startScreenRecording(): Promise<ScreenRecordingSession | ScreenRecordingUnsupported | 'cancelled'>;
+
+interface TpkAiTesterProps {
+    visible: boolean;
+    /** API base URL — same value the rest of the SDK uses for HTTP. */
+    apiBaseUrl: string;
+    /** Coordinator JWT — used for the initial POST to start the session. */
+    coordinatorToken: string;
+    /** Project UUID. */
+    projectId: string;
+    /** Configuration sent to the create-session endpoint. */
+    configuration?: {
+        durationMinutes?: number;
+        maxActions?: number;
+        strategy?: 'llm' | 'random' | 'hybrid';
+        focusAreas?: string[];
+        captureScreenshots?: boolean;
+        submitBugs?: boolean;
+    };
+    /** Called when the user clicks Stop or the session ends naturally. */
+    onClose: () => void;
+    /** Called once on session end with the final status payload. */
+    onSessionEnded?: (status: 'completed' | 'failed' | 'cancelled', sessionId: string | null) => void;
+}
+declare function TpkAiTester({ visible, apiBaseUrl, coordinatorToken, projectId, configuration, onClose, onSessionEnded, }: TpkAiTesterProps): React.ReactElement | null;
+
+/**
+ * ScreenshotAnnotator — full-screen modal canvas editor for annotating
+ * screenshots before attaching them to a bug report.
+ *
+ * Tools: Pen · Arrow · Rectangle · Text · Blur/Pixelate (PII-redaction)
+ * Features: Undo / Redo · Color swatches + native color picker · Stroke width
+ *
+ * SSR-safe: all canvas/window access is guarded behind typeof window checks
+ * and null-context guards.
+ */
+
+interface ScreenshotAnnotatorProps {
+    /** Source screenshot as a data URL */
+    dataUrl: string;
+    /** Called with the annotated image data URL when the user saves */
+    onSave: (annotatedDataUrl: string) => void;
+    /** Called when the user cancels without saving */
+    onCancel: () => void;
+}
+declare function ScreenshotAnnotator({ dataUrl, onSave, onCancel, }: ScreenshotAnnotatorProps): React.ReactElement | null;
+
+/**
+ * Pure (DOM-free) operation stack for the screenshot annotation editor.
+ *
+ * All types, the undo/redo stack, arrowhead geometry, and pixelate-region
+ * math live here so they can be unit-tested without a canvas.
+ */
+type ToolKind = 'pen' | 'arrow' | 'rect' | 'text' | 'blur';
+interface Point {
+    x: number;
+    y: number;
+}
+interface StrokeStyle {
+    color: string;
+    width: number;
+}
+interface PenOp {
+    kind: 'pen';
+    points: Point[];
+    style: StrokeStyle;
+}
+interface ArrowOp {
+    kind: 'arrow';
+    from: Point;
+    to: Point;
+    style: StrokeStyle;
+}
+interface RectOp {
+    kind: 'rect';
+    from: Point;
+    to: Point;
+    style: StrokeStyle;
+}
+interface TextOp {
+    kind: 'text';
+    position: Point;
+    text: string;
+    style: StrokeStyle;
+    fontSize: number;
+}
+interface BlurOp {
+    kind: 'blur';
+    from: Point;
+    to: Point;
+    /** Pixel size for the pixelation block (default 12) */
+    blockSize: number;
+}
+type AnnotateOp = PenOp | ArrowOp | RectOp | TextOp | BlurOp;
+interface OpStack {
+    ops: AnnotateOp[];
+    /** Operations that were undone (redo buffer) */
+    redoBuffer: AnnotateOp[];
+}
+declare function emptyStack(): OpStack;
+declare function pushOp(stack: OpStack, op: AnnotateOp): OpStack;
+declare function undo(stack: OpStack): OpStack;
+declare function redo(stack: OpStack): OpStack;
+/**
+ * Returns the two wing points for an arrowhead at `to` pointing from `from`.
+ * Returned as [wing1, wing2] in the same coordinate space.
+ */
+declare function arrowheadPoints(from: Point, to: Point, headLength?: number, headAngle?: number): [Point, Point];
+/**
+ * Normalises a rect defined by two arbitrary corner points into a
+ * { x, y, width, height } with width and height always positive.
+ */
+declare function normaliseRect(from: Point, to: Point): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Returns the list of pixel-block cells for a pixelate pass.
+ * Each cell is { x, y, width, height } — the grid of blocks that cover
+ * the region. Cells on the right/bottom edges may be narrower/shorter.
+ *
+ * This is pure math; the actual pixel-sampling runs on the canvas.
+ */
+declare function pixelateBlocks(from: Point, to: Point, blockSize: number): Array<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>;
+
+/**
+ * TpkUiContext — internal context carrying locale + theme for all TPK widgets.
+ *
+ * TpkUiProvider({ locale?, theme?, children })
+ *   - locale defaults to the browser language (de* → German, else English)
+ *   - theme = deepMerge(tpkTheme, themeOverride)
+ *   - exposes useTpkUi() hook
+ *
+ * Components work WITHOUT a provider: useTpkUi() returns 'de' + default theme.
+ * This ensures existing tests that render components without a provider keep passing.
+ */
+
+type TFunc = (key: string, params?: Record<string, string | number>) => string;
+interface TpkUiContextValue {
+    t: TFunc;
+    locale: TpkLocale;
+    theme: TpkTheme;
+}
+interface TpkUiProviderProps {
+    locale?: TpkLocale;
+    theme?: Partial<TpkTheme>;
+    children: React.ReactNode;
+}
+declare function TpkUiProvider({ locale, theme, children }: TpkUiProviderProps): React.ReactElement;
+/**
+ * Returns { t, locale, theme } from the nearest TpkUiProvider.
+ * Falls back to 'de' + default theme if no provider is present.
+ */
+declare function useTpkUi(): TpkUiContextValue;
+
+/**
+ * TpkWidgetTour — first-launch onboarding shown ONCE.
+ *
+ * 3 swipeable cards (brand purple):
+ *   Card 1 — "Dein Tester-Knopf" (the FAB)
+ *   Card 2 — "Sprich den Bug" (voice — hero card)
+ *   Card 3 — "Screenshot inklusive" (capture + annotate)
+ *
+ * Gated by localStorage key `tpk:tourSeen`.
+ * Use hasSeenTour() / markTourSeen() from this module.
+ *
+ * Props:
+ *   onDone   — called when the user finishes ("Los geht's") or skips.
+ *   onSkip   — optional alias; if provided, called on skip instead of onDone.
+ *              onDone is still called after markTourSeen on both paths.
+ */
+
+/** SSR-safe: returns false if localStorage is unavailable. */
+declare function hasSeenTour(): boolean;
+/** SSR-safe: best-effort write. */
+declare function markTourSeen(): void;
+interface TpkWidgetTourProps {
+    /** Called after the tour finishes (last card) OR is skipped — in both cases markTourSeen() is called first. */
+    onDone: () => void;
+    /** Optional separate callback on skip. onDone is still called. */
+    onSkip?: () => void;
+}
+declare function TpkWidgetTour({ onDone, onSkip }: TpkWidgetTourProps): React.ReactElement;
+
+export { MESSAGES, PENDING_CRASH_KEY, ScreenshotAnnotator, TesterPayKitProvider, TpkAiTester, TpkBugReportButton, TpkBugReportSheet, TpkCrashDialog, TpkDebugLogsScreen, TpkGeneralFeedbackDialog, TpkMyBugsScreen, TpkNotificationsScreen, TpkRetestScreen, TpkSensitive, TpkSessionDetailsScreen, TpkSessionEndDialog, TpkTaskPanel, TpkTesterHub, TpkTesterLauncher, TpkUiProvider, TpkWidgetTour, TpkWorkboardScreen, applySensitiveMasks, arrowheadPoints, captureScreenshot, clearPendingCrash, emptyStack, getPendingCrash, hasSeenTour, installCrashCapture, installShakeDetection, installThreeFingerTap, makeT, markTourSeen, normaliseRect, pixelateBlocks, pushOp, redo, requestShakePermission, startScreenRecording, startVoiceRecording, tpkTheme, undo, useTesterPayKit, useTpkUi };
+export type { AnnotateOp, ArrowOp, BlurOp, OpStack, PenOp, PendingCrash, Point, RectOp, ScreenRecordingResult, ScreenRecordingSession, ScreenRecordingUnsupported, ScreenshotAnnotatorProps, ShakeDetectionOptions, StrokeStyle, TesterPayKitProviderProps, TextOp, ToolKind, TpkAiTesterProps, TpkBugReportButtonProps, TpkBugReportSheetProps, TpkColors, TpkCrashDialogProps, TpkDebugLogsScreenProps, TpkGeneralFeedbackDialogProps, TpkLocale, TpkMyBugsScreenProps, TpkNotificationsScreenProps, TpkRadius, TpkRetestScreenProps, TpkSensitiveMask, TpkSensitiveProps, TpkSessionDetailsScreenProps, TpkSessionEndDialogProps, TpkTaskPanelProps, TpkTesterHubProps, TpkTesterLauncherProps, TpkTheme, TpkWorkboardScreenProps, TpkZIndex, VoiceRecordingResult, VoiceRecordingSession, VoiceRecordingUnsupported };