@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

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

# 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:

# 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:

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

Then run pnpm db:push to sync.

2. Wire the Server Router

// 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

// 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:

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:

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

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

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