cavepaintings

Cavepaintings

Experimental -- This project is in active development and should be considered in public testing. APIs, features, and behavior may change between releases. Feedback and bug reports are welcome via GitHub Issues.

A browser-based interactive drawing canvas that integrates with Claude Code. Draw diagrams, paste and annotate images, and submit canvas snapshots directly into your Claude Code conversation over a persistent WebSocket connection.

Dark-themed canvas with left toolbar, floating properties panel, zoom indicator, and submit bar. The architecture diagram shows the bidirectional data flow -- submissions go from canvas to Claude, and the push API sends objects back.

Features

Drawing Tools

• Shapes -- rectangles (R), ellipses (E), arrows (A), lines (L), polygons (P)
• Freehand draw (D) -- pencil brush with customizable color and width
• Text (T) -- click to place, double-click to edit inline
• Image (I) -- file picker, clipboard paste (Ctrl+V), drag-drop, or paste a URL
• Connectors (C) -- lines that attach to object anchor points and follow when objects move, with automatic routing around obstacles

Canvas Management

• Object list panel (O) -- see all objects, click to select, drag to reorder z-index, double-click to rename, keyboard navigation
• Properties panel (Q) -- fill, stroke, opacity, font size, z-ordering; always visible with an empty-state prompt when nothing is selected
• Snap-to-grid (G) -- toggle a dot grid; objects snap to 24px increments when moved
• Zoom & pan -- scroll wheel to zoom (0.1x--10x), Alt+drag or middle-click to pan, zoom indicator with click-to-reset
• Undo/redo -- 50-state stack with Ctrl+Z / Ctrl+Y
• Copy/paste -- Ctrl+C / Ctrl+V to duplicate objects (multi-select supported)

Export & Persistence

• Export -- PNG (2x HiDPI), SVG, and JSON
• Import -- JSON re-import to restore diagrams
• Auto-save -- canvas state persists in localStorage across browser refreshes
• Dark/Light theme -- toggle between themes, persists across sessions

Claude Code Integration

• Submit to Claude -- sends 2x HiDPI PNG + Fabric.js JSON + optional message over WebSocket; Ctrl+Enter shortcut from the prompt field
• Automatic notifications -- a UserPromptSubmit hook detects new submissions and injects them into Claude's context with prompt text and object summaries
• Canvas push API -- Claude can programmatically place objects on the canvas via POST /api/canvas
• Submissions API -- harness-agnostic GET /api/submissions?since=<timestamp> endpoint for polling
• Connection status -- green/red indicator with automatic reconnect (exponential backoff)

Responsive & Touch

• Tablet layout -- at viewport widths below 768px, the toolbar moves to a horizontal top bar with 44px touch targets, and panels become bottom sheets
• Touch gestures -- pinch to zoom, two-finger drag to pan, long-press for context menu, double-tap to edit text

Security

• HTTP security headers -- Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, Referrer-Policy on all responses
• Input validation -- schema validation on POST /api/canvas with 5 MB body limit
• WebSocket origin checking -- accepts only localhost origins, blocks cross-site hijacking
• File permissions -- submissions and state files written with restrictive permissions (0700 dirs, 0600 files)
• Rate limiting -- sliding window limits on all API endpoints and WebSocket messages
• Path traversal protection -- static file server validates against traversal attacks

Accessibility

• aria-labels on all controls with keyboard shortcut hints
• aria-pressed states on toggle buttons
• Label associations on all inputs
• Keyboard navigation in object list panel (arrow keys, Alt+Arrow to reorder, Delete to remove)
• Toast notifications use role="alert" for screen reader announcements

Quick Start

Cavepaintings is designed to be installed as a Claude Code plugin. Once installed, use /cavepaintings and /cavepaintings-stop inside any Claude Code session -- no manual server management needed.

Prerequisites: Node.js (v18+) and npm. Dependencies install automatically on first launch.

1. Register the marketplace

Add to your Claude Code settings (~/.claude/settings.json):

{
  "extraKnownMarketplaces": {
    "cavepaintings-marketplace": {
      "repo": "RCellar/cavepaintings",
      "branch": "master"
    }
  }
}

Or ask Claude Code: "Add RCellar/cavepaintings as a custom marketplace called cavepaintings-marketplace"

2. Install the plugin

In Claude Code, run /plugins, navigate to Discover, find cavepaintings, and install it.

3. Use it

/cavepaintings          # opens the canvas in your browser
/cavepaintings-stop     # stops the server