@paybook/splash

Quick Start

Get Splash running in your React project in under 2 minutes. The widget adds a floating debug overlay activated by a keyboard shortcut — no UI changes to your existing app.

npm install @paybook/splash

import { DevToolsProvider } from "@paybook/splash/client";

function App() {
  return (
    <DevToolsProvider
      apiKey={import.meta.env.VITE_SPLASH_API_KEY}
      projectId="your-project-id"
      config={{
        projectName: "My App",
        techStack: "React + Vite + tRPC",
        shortcut: "ctrl+shift+0",
      }}
    >
      {/* Your existing app */}
      <RouterProvider router={router} />
    </DevToolsProvider>
  );
}

VITE_SPLASH_API_KEY=splk_your_api_key_here
VITE_SPLASH_PROJECT_ID=your-project-id

Installation

npm / yarn / pnpm

npm install @paybook/splash

Peer Dependencies

Splash requires React 18+ as a peer dependency. If you're using tRPC, Splash can integrate directly with your existing tRPC client for zero-config server communication.

{
  "peerDependencies": {
    "react": ">=18.0.0",
    "react-dom": ">=18.0.0"
  },
  "optionalPeerDependencies": {
    "@trpc/client": ">=11.0.0",
    "@trpc/react-query": ">=11.0.0"
  }
}

Configuration

Splash is configured through the DevToolsProvider component. All configuration is optional — sensible defaults are applied.

Feature Flags

Enable or disable individual features through the features config object. All features are enabled by default.

<DevToolsProvider
  apiKey={apiKey}
  projectId={projectId}
  config={{
    features: {
      debugWidget: true,       // Bug report overlay
      featureRequests: true,   // Feature request tab
      screenDocs: true,        // Screen documentation
      taskManager: true,       // Task management
      activityLog: true,       // Activity logging
      aiSpecGen: true,         // AI spec generation
      voiceAnnotation: true,   // Voice annotations on bugs
    },
  }}
>
  <App />
</DevToolsProvider>

Bug Reports

The Bug Report tab captures a screenshot of the current viewport, lets the developer annotate it with arrows, circles, freehand drawings, and text labels, then submits the report with full context to the Splash Platform.

How it works

Annotation Tools

Feature Requests

The Feature tab lets developers submit feature requests with full visual context. Unlike traditional feature request forms, Splash captures the exact screen state where the idea originated, making it easy for product teams to understand the context.

AI-Generated Artifacts

Categories

Screen Documentation

The Screen Docs tab provides route-aware documentation for every screen in your app. Documentation can be AI-generated from the current page context or manually written. Each doc includes structured fields: purpose, data flow, components, and known issues.

AI Generation

When you open the Docs tab on a screen that hasn't been documented yet, Splash can automatically generate documentation by analyzing the visible DOM elements, route path, page title, and optional screenshot. The AI produces structured documentation covering what the screen does, what data it reads/writes, key components, and potential issues.

Notes System

Every screen doc supports a notes system where team members can add contextual notes categorized as: Context (background info), Decision (why something was built this way), Gotcha (known pitfalls), To Do (future work), or General.

Dashboard Overview

The Splash Dashboard is the central command center for managing your development projects. It provides a comprehensive view of all projects, team activity, bug submissions, feature requests, and AI conversations — all in a modern, dark-themed interface with spatial UI elements.

AI Conversations

The Conversations page is where requirements come to life. It provides an AI-powered chat interface that guides you through defining project requirements, refining technical specifications, and generating RFPs (Request for Proposals). The AI agent adapts its role based on the conversation context — acting as an architect, analyst, or technical lead as needed.

Conversation Phases

Smart Context Window

The AI uses a smart context window that sends the last 20 messages plus a system prompt with project progress hints. This ensures the AI always has relevant context without exceeding token limits. A duplicate response detection system prevents the AI from getting stuck in loops — if a response matches a previous one, the system automatically regenerates with an anti-loop instruction.

Infinite Scroll

Conversations use cursor-based pagination with lazy loading. When you open a conversation, only the most recent 30 messages are loaded. Scrolling up triggers automatic loading of older messages with scroll position preservation — no jarring jumps. A floating "Latest" button appears when you scroll away from the bottom, letting you jump back instantly.

Typing Indicator

Before the AI starts streaming its response, a smooth bouncing-dots typing indicator appears in the chat. This provides visual feedback that the AI is processing your message, improving perceived responsiveness. The indicator uses Framer Motion for fluid animations.

Bookmarks & Reactions

Every message in a conversation supports bookmarks and emoji reactions. Hover over any message to reveal the action bar with three buttons: bookmark pin, emoji picker, and branch fork.

Bookmarks

Pin important messages by clicking the bookmark icon. Bookmarked messages get an amber ring indicator and appear in a slide-out sidebar panel accessible from the header toolbar. Each bookmark can have an optional text note explaining why it was pinned. Click any bookmark in the panel to jump directly to that message in the conversation.

Emoji Reactions

Add emoji reactions to messages using the quick picker (8 commonly used emojis). Reactions appear as animated pill badges below the message with aggregated counts. Your own reactions are highlighted with a distinct border. Click a reaction badge to toggle it on/off. Multiple users can react to the same message, and counts update in real-time.

Conversation Branching

Fork a conversation at any message to explore alternative directions without losing the original thread. The branch switcher in the header shows all branches (main thread, active branches, and archived ones) and lets you switch between them instantly.

Search & Export

Find any message across your entire conversation history with full-text search. Click the search icon or press Ctrl+F to open the search bar. Results update in real-time as you type, with match count and prev/next navigation using Enter / Shift+Enter. Matching keywords are highlighted with yellow markers, and navigating between matches triggers a flash-scroll animation.

PDF Export

Export your entire conversation to a formatted PDF document. The export includes all messages with timestamps, role labels (User / AI), and proper formatting. The PDF is generated client-side and opens in a new tab for printing or saving. Useful for sharing conversation outcomes with stakeholders who don't have dashboard access.

API Keys

API keys are managed at the organization level and scoped to specific projects with granular permissions — similar to GitHub's fine-grained personal access tokens.

Key Format

All keys use the splk_ prefix followed by a random string. Keys are hashed (SHA-256) before storage — the full key is only shown once at creation time.

splk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Project Scoping

Permissions

Permissions follow a resource:action pattern. Each API key can have different permission sets per project.

API: Debug / Bugs

All API endpoints require a Bearer splk_... token in the Authorization header.

API: Tasks

API: Documentation

API: Feature Requests

API: Activity

API: AI

API: Conversations

The Conversations API provides endpoints for managing AI-powered requirement conversations, including sending messages, fetching paginated history, full-text search, and bulk export.

SDK: DevToolsProvider

The DevToolsProvider is the main entry point for the Splash SDK. It wraps your application and provides the debug overlay, keyboard shortcut handling, screenshot capture, and API communication.

import { DevToolsProvider } from "@paybook/splash/client";

function App() {
  return (
    <DevToolsProvider
      apiKey={import.meta.env.VITE_SPLASH_API_KEY}
      projectId={import.meta.env.VITE_SPLASH_PROJECT_ID}
      config={{
        shortcut: "ctrl+shift+0",
        projectName: "My SaaS App",
        techStack: "React 19 + Vite + tRPC + Tailwind",
        accentColor: "#7C3AED",
        defaultMode: "bug",
        features: {
          debugWidget: true,
          featureRequests: true,
          screenDocs: true,
          taskManager: true,
          activityLog: true,
          aiSpecGen: true,
          voiceAnnotation: true,
        },
      }}
    >
      <RouterProvider router={router} />
    </DevToolsProvider>
  );
}

Provider Props

SDK: Config Options

The full DevToolsConfig type with all available options:

1interface DevToolsConfig {
2  /** Keyboard shortcut to toggle overlay. Default: "ctrl+shift+0" */
3  shortcut?: string;
4
5  /** Project name for AI context. Default: "My Project" */
6  projectName?: string;
7
8  /** Tech stack description. Default: "React + tRPC" */
9  techStack?: string;
10
11  /** Primary accent color. Default: "#7C3AED" */
12  accentColor?: string;
13
14  /** Default tab when overlay opens. Default: "bug" */
15  defaultMode?: "bug" | "feature" | "docs";
16
17  /** Feature flags — all true by default */
18  features?: {
19    debugWidget?: boolean;       // Bug report tab
20    featureRequests?: boolean;   // Feature request tab
21    screenDocs?: boolean;        // Screen docs tab
22    taskManager?: boolean;       // Task management
23    activityLog?: boolean;       // Activity logging
24    aiSpecGen?: boolean;         // AI spec generation
25    voiceAnnotation?: boolean;   // Voice annotations
26  };
27
28  /** Custom route paths for built-in pages */
29  routes?: {
30    taskManager?: string;        // Default: "/devtools/tasks"
31    debugDashboard?: string;     // Default: "/devtools/debug"
32  };
33}

System Architecture

Splash follows a layered architecture with clear separation between the SDK (client-side widget), the Platform API (server-side processing), and the Dashboard (management UI). Each layer communicates through well-defined interfaces.

Data Flow

Understanding how data flows through Splash helps when debugging integration issues or extending the platform.

Bug Report Flow

Conversation Flow