npm package: @paybook/splash
Description: Splash — visual debug overlay, AI task generation, and developer tooling for React + tRPC projects. A Paybook tool.
Author: gerardo-trevino
Latest version: 0.1.7

# @paybook/splash

A standalone, portable development tooling system that drops into any React + tRPC project. It provides AI-powered task management, a visual debug annotation widget, and development workflow automation — all wired through a single provider component and a composable server router.

**Author:** gerardo-trevino  
**License:** MIT  
**Version:** 0.1.0  
**Homepage:** [paybook.com/splash](https://www.paybook.com/splash)

---

## Overview

Splash is designed as a self-contained module that can be integrated into any web application built on React and tRPC. It ships with four subsystems that work together to streamline the development cycle:

| Subsystem | Description |
|---|---|
| **Task Manager** | Full CRUD task board with status tracking, priority levels, categories, and assignees |
| **AI Spec Generator** | LLM-powered specification and execution plan generation from rough feature ideas |
| **Debug Widget** | Visual screen annotation overlay with screenshot capture, drawing tools, and issue submission |
| **Activity Log** | Audit trail that records all task operations, AI generations, and debug submissions |

The package is structured into three layers — `server`, `client`, and `shared` — each importable independently. The server layer provides tRPC router factories that compose into the host application's existing router. The client layer provides a React context provider that wraps the application with the debug overlay and keyboard shortcuts. The shared layer provides constants and TypeScript types used by both sides.

---

## Installation

```bash
# From npm (when published):
pnpm add @paybook/splash

# Or install from a local path:
pnpm add ../splash
```

### Peer Dependencies

The package expects the following peer dependencies to be installed in the host project:

| Dependency | Version | Required |
|---|---|---|
| `react` | >= 18.0.0 | Yes |
| `@trpc/server` | >= 11.0.0 | Yes |
| `drizzle-orm` | >= 0.30.0 | Yes |
| `zod` | >= 3.0.0 | Yes |
| `@trpc/react-query` | >= 11.0.0 | Optional |
| `zustand` | >= 4.0.0 | Optional |

---

## Quick Start

### 1. Run the Database Migration

Execute the SQL migration to create the `devtools_tasks` and `devtools_activities` tables:

```bash
# Apply the migration file to your database
mysql -u root -p your_database < node_modules/@paybook/splash/migrations/001_devtools_tables.sql
```

Or import the Drizzle schema directly into your project's schema file:

```ts
// drizzle/schema.ts
export { devtoolsTasks, devtoolsActivities } from "@paybook/splash/schema";
```

Then run `pnpm db:push` to sync.

### 2. Wire the Server Router

```ts
// server/routers.ts
import { createDevToolsRouter } from "@paybook/splash/server";
import { router, publicProcedure, protectedProcedure, adminProcedure } from "./_core/trpc";
import { db } from "./db";
import { invokeLLM } from "./_core/llm";

const devtoolsRouter = createDevToolsRouter(
  {
    db,
    llm: { invoke: (params) => invokeLLM(params) },
    projectName: "My Project",
    techStack: "React + tRPC + Tailwind",
  },
  { router, publicProcedure, protectedProcedure, adminProcedure }
);

export const appRouter = router({
  // ... your existing routes
  devtools: devtoolsRouter,
});
```

### 3. Wrap the Client

```tsx
// client/src/App.tsx (or main.tsx)
import { DevToolsProvider } from "@paybook/splash/client";
import { trpc } from "./lib/trpc";

function App() {
  return (
    <DevToolsProvider
      enabled={import.meta.env.DEV}
      shortcut="ctrl+shift+0"
      projectName="My Project"
      trpc={trpc}
    >
      <YourRoutes />
    </DevToolsProvider>
  );
}
```

That is the complete integration. The debug overlay activates with `Ctrl+Shift+0` (or `Cmd+Shift+0` on macOS), and all task/activity data flows through the tRPC router you just wired.

---

## Architecture

```
@paybook/splash/
├── index.ts                  # Main entry — re-exports everything
├── server/
│   ├── index.ts              # createDevToolsRouter factory
│   ├── schema.ts             # Drizzle table definitions
│   ├── db.ts                 # Database query helpers
│   ├── taskRouter.ts         # Task CRUD procedures
│   ├── aiRouter.ts           # AI spec/plan generation procedures
│   ├── debugRouter.ts        # Debug submission procedures
│   └── activityRouter.ts     # Activity feed procedures
├── client/
│   ├── index.ts              # Client entry — exports provider, hooks, components
│   ├── DevToolsProvider.tsx  # Main React provider + debug overlay
│   ├── debugStore.ts         # Zustand store for debug widget state
│   ├── hooks/
│   │   ├── useDebugWidget.ts # Keyboard listener + screen capture
│   │   └── useDraggable.ts   # Drag-and-drop utility hook
│   └── components/
│       └── AnnotationCanvas.tsx  # Canvas-based annotation renderer
├── shared/
│   ├── index.ts              # Barrel exports
│   ├── types.ts              # TypeScript interfaces
│   └── constants.ts          # Shared constants
├── migrations/
│   └── 001_devtools_tables.sql  # SQL migration
└── tests/
    ├── server.test.ts        # Server-side tests (45 assertions)
    └── client.test.ts        # Client-side tests
```

---

## Server API

### `createDevToolsRouter(config, trpcHelpers)`

The main factory function that composes all four sub-routers into a single tRPC router.

**Config:**

| Field | Type | Required | Description |
|---|---|---|---|
| `db` | Drizzle instance | Yes | Your Drizzle ORM database connection |
| `llm` | `{ invoke: (params) => Promise }` | Yes | LLM adapter — wraps your `invokeLLM` call |
| `projectName` | `string` | No | Project name for AI context |
| `techStack` | `string` | No | Tech stack description for AI context |
| `systemPrompt` | `string` | No | Custom system prompt for AI spec generation |
| `storage` | `{ put, get }` | No | S3 storage adapter for screenshots |

**tRPC Helpers:**

| Field | Type | Description |
|---|---|---|
| `router` | tRPC `router` | Your tRPC router factory |
| `publicProcedure` | tRPC procedure | Public procedure (no auth required) |
| `protectedProcedure` | tRPC procedure | Protected procedure (auth required) |
| `adminProcedure` | tRPC procedure | Admin procedure (optional, falls back to protected) |

### Procedures

The composed router exposes these procedure namespaces:

**`devtools.tasks.*`** — Task CRUD  
- `list` — Query all tasks (with optional status/priority filters)  
- `create` — Create a new task from title + rough idea  
- `update` — Update task fields by taskId  
- `delete` — Delete a task by taskId  

**`devtools.ai.*`** — AI Generation  
- `generateSpec` — Generate a detailed specification from a task's rough idea  
- `generateExecutionPlan` — Generate a step-by-step execution plan from a task's spec  

**`devtools.debug.*`** — Debug Submissions  
- `submit` — Submit a debug report with screenshot, annotations, and description  

**`devtools.activity.*`** — Activity Feed  
- `recent` — Query recent activity entries  
- `log` — Log a new activity entry  

---

## Client API

### `<DevToolsProvider>`

The main React component that wraps your application.

| Prop | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | — | Enable/disable the devtools system |
| `shortcut` | `string` | `"ctrl+shift+0"` | Keyboard shortcut to toggle debug overlay |
| `projectName` | `string` | `"My Project"` | Project name shown in debug reports |
| `trpc` | tRPC client | — | Your tRPC client instance |
| `onSubmit` | `(data) => Promise<void>` | — | Custom submit handler (alternative to tRPC) |
| `onToggle` | `(isOpen) => void` | — | Callback when debug mode toggles |

### `useDevTools()`

React hook that provides programmatic access to the devtools state:

```tsx
const { isOpen, toggle, open, close, config } = useDevTools();
```

### Debug Overlay Features

When activated (via keyboard shortcut or `open()`), the debug overlay provides:

- **Screen Capture** — Captures the current page state before the overlay renders, ensuring a clean screenshot
- **Annotation Tools** — Arrow, circle, freehand draw, and text annotations with customizable colors and line widths
- **Draggable Panels** — Both the toolbar and submit panel can be repositioned by dragging
- **Keyboard Shortcuts** — `A` (arrow), `C` (circle), `F` (freehand), `T` (text), `Ctrl+Z` (undo), `ESC` (close)
- **Issue Submission** — Generates a task with the annotated screenshot, page metadata, and visible element context

---

## Shared Constants

All constants are importable from `@paybook/splash/shared`:

```ts
import {
  PACKAGE_NAME,          // "@paybook/splash"
  TASK_STATUSES,         // ["backlog", "ready", "in_progress", "review", "done"]
  TASK_PRIORITIES,       // ["low", "medium", "high", "critical"]
  TASK_CATEGORIES,       // ["feature", "bug", "improvement", "refactor", "documentation", "test"]
  ANNOTATION_TOOLS,      // ["arrow", "circle", "freehand", "text"]
  DEFAULT_SHORTCUT,      // "ctrl+shift+0"
  DEFAULT_CONFIG,        // Full default configuration object
  PRIORITY_COLORS,       // { critical: "#EF4444", high: "#F97316", ... }
  STATUS_LABELS,         // { backlog: "Backlog", ready: "Ready", ... }
  ANNOTATION_COLORS,     // Color palette for annotations
  LINE_WIDTHS,           // Available line width options
} from "@paybook/splash/shared";
```

---

## Testing

```bash
cd splash
pnpm test
```

The test suite includes 45 assertions covering:

- Database helper function exports and signatures
- Router factory composition and return values
- Schema table definitions and column presence
- Shared constant values and completeness
- Client component and hook exports
- Debug store state management (add, clear, reset, tool switching)

---

## Build

```bash
pnpm build
```

Splash uses **tsup** to compile TypeScript source into ESM with declaration files. The output goes to `dist/` and all subpath exports resolve to the compiled artifacts.

---

## Design Decisions

The package follows several deliberate design constraints to maximize portability:

The **DevToolsProvider** uses only inline styles — no Tailwind, no shadcn/ui, no external CSS. This ensures the debug overlay renders correctly regardless of the host project's styling system. The overlay uses a dark glassmorphism aesthetic with the `#7C3AED` accent color.

The **server routers** accept tRPC helpers as constructor arguments rather than importing them directly. This means the package works with any tRPC setup — the host project passes its own `router`, `publicProcedure`, and `protectedProcedure` instances.

The **database layer** uses Drizzle ORM with table names prefixed by `devtools_` to avoid collisions with the host project's schema. The migration SQL is provided as a standalone file that can be run independently.

The **LLM integration** uses an adapter pattern — the host project wraps its own LLM client in a `{ invoke }` object, so the package never imports LLM libraries directly.

---

## Roadmap

- [ ] Feature builder — create new features from the visual overlay
- [ ] Built-in documentation system — auto-document components and routes
- [ ] Voice annotation transcription (record audio, transcribe via Whisper)
- [ ] Debug dashboard page component (view submitted reports, analytics)
- [ ] Task manager page component (Kanban board UI)
- [ ] Real-time collaboration via WebSocket
- [ ] Export to GitHub Issues integration
- [ ] npm publish to `@paybook/splash`