Boardier Docs

Main entry point for the Boardier library. Re-exports all public components, types, themes, element factories, engine, utilities, and rendering helpers. Import from this module for the cleanest consumer experience.

`import { BoardierCanvas, defaultTheme, createElement } from 'boardier';`

In-memory clipboard for copy/paste of canvas elements. Deep-clones elements to prevent mutation, assigns fresh IDs on paste, and applies a spatial offset so pasted content is visually distinct.

`clipboard.copy(selectedElements); const pasted = clipboard.paste(20, 20);`

The central orchestrator of the Boardier whiteboard. `BoardierEngine` owns the scene graph, undo/redo history, renderer, clipboard, and the active tool. It exposes a public API for tool switching, element manipulation, multi-page support, viewport control, theming, and an AI-facing interface for LLM integration.

See also: Scene, Renderer, History, Clipboard, BaseTool

`const engine = new BoardierEngine(canvasEl, { showGrid: true }, defaultTheme);`

Simple undo/redo stack using full-scene snapshots. Snapshots are deep-cloned via `structuredClone`, so mutations to the live scene don't affect history entries.

`history.push(scene.getElements()); // after drag-end`

Canvas 2D renderer responsible for drawing all elements, the grid, selection overlays, smart guides, and lasso outlines. Performs viewport culling, coordinate transforms (screen ↔ world), and theme-aware color adaptation for dark backgrounds.

See also: BoardierEngine, Scene

In-memory scene graph that holds all elements and the current selection. Provides CRUD operations, hit-testing, z-ordering, and serialisation. Emits change and selection events consumed by the engine and UI.

All type definitions for the Boardier whiteboard engine. This module contains zero runtime code — it is purely TypeScript type declarations used across every other module. Import only what you need for tree-shaking.

`const pos: Vec2 = { x: 100, y: 200 };`

`const b: Bounds = { x: 0, y: 0, width: 100, height: 50 };`

`if (el.type === 'rectangle') { console.log(el.borderRadius); }`

`engine.setViewState({ scrollX: 0, scrollY: 0, zoom: 1.5 });`

`const json = engine.getSceneData(); localStorage.setItem('scene', JSON.stringify(json));`

`<BoardierCanvas config={{ readOnly: true, showGrid: false }} />`

`const aiConfig: BoardierAIConfig = { apiKey: process.env.OPENAI_KEY!, model: 'gpt-4' };`

`<AIChatPopup config={{ defaultProvider: 'openai', allowHTMLMode: true }} />`

Renderer, hit-tester, and bounds-getter for arrows. Extends line rendering with configurable arrowheads at start and/or end. Supports bézier curves and element binding.

Element registry and factory system. Each element type module (rectangle.ts, ellipse.ts, etc.) calls `registerElement()` to provide a renderer, hit-tester, and bounds getter. The factory functions (`createRectangle`, `createEllipse`, …) produce elements with sensible defaults. Use `createElement(type)` as a generic dispatcher.

See also: core/types for the element type definitions

Renderer, hit-tester, and bounds-getter for interactive checkbox elements. Renders a hand-drawn checkbox with check-mark, label text, and configurable check color/size.

Renderer, hit-tester, and bounds-getter for comment/annotation pins. Displays author, timestamp, text, and resolved status with a colored marker.

Renderer, hit-tester, and bounds-getter for the diamond (rhombus) element. Uses roughDiamond for hand-drawn rendering and point-in-polygon for hit-testing.

Renderer, hit-tester, and bounds-getter for the ellipse element. Uses roughEllipse for hand-drawn rendering, supports labels, fill patterns, and point-in-ellipse hit-testing.

Renderer, hit-tester, and bounds-getter for embedded web content placeholders. Displays a URL title card on the canvas (actual iframe rendering happens in the UI layer).

Renderer, hit-tester, and bounds-getter for frame containers. Frames group child elements with optional clipping, padding, and a labelled header.

Renderer, hit-tester, and bounds-getter for freehand drawing. Records an array of points (and optional per-point pressure values for stylus support). Rendered as a smooth polyline.

Renderer, hit-tester, and bounds-getter for icon elements. Icons are referenced by iconName and iconSet identifiers, with pre-rendered SVG markup cached as Image objects for canvas painting.

Renderer, hit-tester, and bounds-getter for image elements. Supports data URLs and external URLs with object-fit modes (contain/cover/fill).

Renderer, hit-tester, and bounds-getter for straight/bézier lines. Supports an optional controlPoint for quadratic curves and element-binding at start/end points.

Renderer, hit-tester, and bounds-getter for the highlighter-marker element. Draws wide, translucent strokes ideal for annotations and emphasis.

Renderer, hit-tester, and bounds-getter for interactive radio-button groups. Supports vertical/horizontal layouts with configurable option labels and selection index.

Renderer, hit-tester, and bounds-getter for the rectangle element. Supports border-radius (uniform or per-corner), labels, fill styles (solid/hachure/cross-hatch/dots), stroke styles, shadow, and roughness-based hand-drawn rendering via `roughRect`.

Renderer, hit-tester, and bounds-getter for grid/table elements. Renders rows, columns, cell text, optional headers, and proportional column/row sizing.

Renderer, hit-tester, bounds-getter, and measureText() utility for multi-line text elements. Supports font family/size selection, text alignment, line-height, and optional inline icon placeholders.

Abstract base class and `ToolContext` interface for all Boardier tools. Every tool receives a `ToolContext` with access to the scene, history, renderer, clipboard, theme, viewport, and utility callbacks. Extend `BaseTool` to create custom tool behaviours.

See also: core/Engine for tool registration

Click-to-place tool for adding comment/annotation pins. Creates a CommentElement at the click position with default author and timestamp.

Eraser tool that removes elements on pointer contact. Hit-tests under the cursor and removes matching elements in real-time as the pointer moves.

Freehand drawing tool. Records pointer positions on move and creates a FreehandElement on release. Supports pressure-sensitive input from styluses.

Click-to-place tool for inserting icon elements. Creates an IconElement with a default icon that can be changed via the icon picker.

Tool for inserting images. Opens a file picker on click and creates an ImageElement from the selected file.

Tool for creating lines and arrows. Supports straight segments, bézier curves (via alt-drag control point), element binding (snapping to target shapes), and multi-point polylines.

Highlighter / marker tool that creates wide, translucent strokes. Records pointer positions during drag and creates a MarkerElement on release.

Hand/pan tool for scrolling the canvas viewport. Also used as a space-bar override in the engine.

The default selection tool. Handles click-to-select, box selection, lasso selection, drag-to-move, resize handles, smart alignment guides, and keyboard shortcuts (delete, copy, paste, undo/redo, select-all). This is the most complex tool in Boardier.

Generic tool for creating rectangle, ellipse, and diamond shapes. Click-and-drag creates the shape; hold Shift for square/circle constraint.

Click-to-place text tool. Creates a TextElement at the click position and immediately requests the text editor overlay.

Generic tool for placing widget elements (checkbox, radiogroup, frame, embed, table). Accepts a widget type and default dimensions; creates the corresponding element on click.

Ships two built-in themes: `defaultTheme` (light) and `defaultDarkTheme`. Both are complete BoardierTheme objects that can be used directly or spread into custom themes. Also exports `roughUIStyle` and `cleanUIStyle` presets.

`<BoardierCanvas theme={defaultTheme} />` or `<BoardierCanvas theme={defaultDarkTheme} />`

Factory function that creates a Notier-branded theme. Accepts optional overrides for accent and background colors.

`const theme = createNotierTheme({ accent: '#6366f1' });`

The complete BoardierTheme interface. Every visual aspect of the engine — canvas background, grid, selection, panels, tooltips, fonts, and element defaults — is configurable through a single theme object. The `uiStyle` section provides full CSS-level control over UI component shapes.

`const myTheme: BoardierTheme = { ...defaultTheme, canvasBackground: '#1e1e1e' };`

Floating AI chat popup component for conversational whiteboard editing. Supports OpenAI, Anthropic (Claude), and Google Gemini providers. Users provide their own API keys. Integrates with Boardier's AI capabilities including element generation and HTML-based smart layouts.

`<AIChatPopup engine={engine} config={{ defaultProvider: 'openai' }} theme={theme} />`

The top-level React component for embedding the Boardier whiteboard. Wraps the BoardierEngine with a canvas element and provides a complete UI including toolbar, property panel, zoom controls, export dialog, text editor overlays, context menu, minimap, page navigator, and presentation mode. All UI panels are draggable via the DraggablePanel system.

`<BoardierCanvas config={{ showGrid: true }} theme={defaultTheme} onChange={handleChange} />`

Ref: BoardierCanvasRef (via React.forwardRef) — exposes getEngine(), getSceneData(), loadScene(), exportToPNG(), exportToSVG(), exportToJSON()

Props: BoardierCanvasProps

Right-click context menu for the canvas. Shows element operations (copy, paste, delete, duplicate, z-order, arrange submenu, send to AI, select all) positioned at the cursor.

A generic draggable container used to wrap toolbar, zoom controls, and export panels. Supports position persistence, no-drop zones, and optional lock mode via BoardierLayoutConfig.

Modal dialog for exporting the scene to PNG, SVG, or JSON. Provides format selection, scale/padding controls, and a download button.

Searchable icon picker dialog that renders icons from react-icons sets (Feather, Material Design, Font Awesome, etc.). Supports lazy loading, search filtering, and set tabs.

A small overview map of the entire scene shown in a corner, with integrated zoom controls as a footer. Renders a scaled-down view of all elements and a viewport indicator. Click-to-navigate and drag-to-pan are supported.

Multi-page navigation panel. Lists all pages/slides, allows adding, deleting, renaming, and switching between pages.

Fullscreen presentation mode that displays pages/frames as slides. Supports keyboard navigation, auto-fit zoom, and ESC to exit.

Side panel that displays and edits properties of selected elements: stroke color, fill color/style, stroke width/style, opacity, roughness, font, text alignment, border radius, and element-specific fields.

Inline text editor overlay positioned on top of shape elements (rectangles, ellipses, diamonds) for editing their labels.

Floating textarea overlay for editing text elements in-place. Auto-resizes to fit content and supports multi-line editing.

Main tool-selection toolbar. Renders tool buttons for all element types plus select, pan, and eraser. Supports keyboard shortcuts and active-tool highlighting.

Themed tooltip component that appears on hover. Positions itself above/below the trigger element and respects theme colors.

Zoom-in, zoom-out, and fit-to-content buttons displayed in a compact panel. Shows the current zoom percentage.

Colour palettes, stroke widths, font sizes, and font families used as defaults throughout the UI and element creation. All are exported as `readonly` arrays.

Export functions for converting scene elements to PNG (as Blob), JSON (as string), and SVG (as string). PNG export renders to an offscreen canvas at configurable scale and padding. SVG export generates self-contained markup.

`const blob = await exportToPNG(elements, '#fff', 40, 2);`

Unique ID generator for element IDs. Uses `Math.random().toString(36)` for fast, collision-resistant short IDs.

Pure math helpers used throughout the engine: distance, midpoint, rotation, bounds testing, segment/polyline/bézier distance, path simplification, and polygon point-in-polygon testing. All functions are stateless and tree-shakeable.

Converts Mermaid diagram syntax into Boardier elements. parseMermaid() parses text into a graph structure; mermaidToBoardier() converts that into positioned BoardierElement arrays.

`const elements = mermaidToBoardier('graph TD; A-->B; B-->C');`

Shared Canvas 2D rendering helpers: applyStrokeStyle() for dash patterns and drawPatternFill() for hachure/cross-hatch/dot/zigzag fill patterns used by shape renderers.

Hand-drawn rendering primitives powered by a seeded PRNG. Provides roughRect, roughEllipse, roughDiamond, roughPolyline, roughBezier, and roughFillRect for a sketchy aesthetic. Roughness 0 = clean, 2 = very rough.

Generates changelog data from boardier-since and boardier-changed annotations. Groups new modules by the version they were introduced, and changed modules by the version they were modified. Outputs `website/src/data/changelog.json` consumed by the /changelog page. Usage: npx tsx scripts/generateChangelog.ts

Parses all @boardier- JSDoc annotations from the boardier source tree and outputs a structured JSON file consumed by the /docs page at build time.