Hero Whiteboard

A collaborative visual whiteboard — brainstorm, diagram, plan, present, and document decisions on an infinite canvas with real-time and async collaboration.

Architecture

Hero Whiteboard follows the Hero three-crate model:

Crate	Purpose
hero_whiteboard_server	Business logic, SQLite storage, OpenRPC API (Unix socket)
hero_whiteboard_sdk	JSON-RPC client for the server over Unix socket
hero_whiteboard_ui	End-user whiteboard UI + admin dashboard (Axum + Konva.js)
hero_whiteboard_examples	SDK usage examples and integration tests
hero_whiteboard	CLI for registering and managing services via hero_proc

Sockets

Service	Path
Server	~/hero/var/sockets/hero_whiteboard_server.sock
UI	~/hero/var/sockets/hero_whiteboard_ui.sock

Quick Start

make build          # Build all crates
make install        # Install binaries to ~/hero/bin/
make run            # Start server + UI
make status         # Check service status
make logs           # View server logs
make logs-ui        # View UI logs
make stop           # Stop all services
make restart        # Restart all services

API

The server exposes a full JSON-RPC 2.0 API over the Unix socket. See the OpenRPC spec for all 45+ methods across these domains:

• workspace.* — multi-tenant workspace management
• board.* — board CRUD
• object.* — whiteboard objects (sticky notes, shapes, text, etc.)
• connector.* — arrows and connectors between objects
• comment.* — threaded comments
• share.* — share links and tokens
• group.* — groups and permissions
• user.* — user management
• rpc.health, rpc.discover — health and OpenRPC discovery

Browser Compatibility

Hero Whiteboard is tested on modern Chromium-based browsers (Chrome, Edge, Brave) and Firefox.

Brave Browser

Brave's fingerprint protection adds noise to the HTML Canvas API (getImageData), which can interfere with Konva.js hit detection used by the whiteboard. Symptoms include:

• Objects can't be moved (dragging does nothing)
• Right-clicking an object shows the browser's default menu (with "Paste") instead of the whiteboard's copy/cut/delete menu
• Behavior is random: some objects work, others don't; refreshing may change which ones

How to fix:

1. Open brave://settings/shields
2. Scroll to Fingerprinting and set it to "Allow all fingerprinting", or
3. Click the Shields icon (lion) in the address bar on the whiteboard page and turn Shields OFF for the site

If the issue persists:

• Disable Hardware acceleration: brave://settings/system → toggle off "Use graphics acceleration when available"
• Check brave://flags and disable any fingerprinting-related experimental features
• Avoid using Private Windows (especially "Private Window with Tor"), which enforce protections that can't be fully disabled

This is a general limitation that affects canvas-based apps (Figma, Miro, etc.) on Brave, not specific to Hero Whiteboard.

Web Frame (Iframe) Limitations

The Web Frame tool embeds external websites using an HTML <iframe>. Many websites block iframe embedding via HTTP headers (X-Frame-Options: DENY/SAMEORIGIN or Content-Security-Policy: frame-ancestors). This is a security feature enforced by the browser and cannot be bypassed by any client-side code.

Sites that typically work

• https://example.com
• https://en.wikipedia.org
• YouTube embeds (https://www.youtube.com/embed/<VIDEO_ID>)
• CodePen/JSFiddle embeds
• Most documentation sites (MDN, etc.)
• Internal/intranet tools (unless they explicitly set blocking headers)

Sites that will NOT work

• Google, Gmail, Google Docs, Google Maps (standard URLs)
• Facebook, Twitter/X, Instagram, LinkedIn
• Most major news sites (NYT, BBC, CNN)
• Banks and financial services
• Most GitHub pages

When a site blocks embedding, the web frame shows an "Open in new tab" button as a fallback so you can still access the content.

Tips

• For YouTube, use the embed URL format: https://www.youtube.com/embed/VIDEO_ID
• For Google Maps, use the embed URL from "Share → Embed a map"
• Double-click a web frame to change its URL

Documentation

• SPECIFICATIONS.md — Full functional specification
• INSTRUCTIONS_TECH.md — Technical implementation instructions