openpencil/packages/pen-react/CLAUDE.md

pen-react

React UI SDK for OpenPencil -- provider, hooks, panels, toolbar, and property editor components.

Structure

Core

• src/context.ts — DesignEngineContext: React context holding the DesignEngine instance
• src/provider.tsx — DesignProvider: provides engine to React tree. Supports uncontrolled mode (initialDocument) and controlled mode (document + onDocumentChange) with echo-loop prevention

Hooks (src/hooks/)

• use-design-engine.ts — useDesignEngine(): gets engine from context, throws if outside provider
• use-document.ts — useDocument(): returns current PenDocument, re-renders on mutation
• use-selection.ts — useSelection(): returns string[] of selected node IDs
• use-viewport.ts — useViewport(): returns ViewportState (zoom, panX, panY)
• use-active-tool.ts — useActiveTool(): returns current ToolType
• use-history.ts — useHistory(): returns { canUndo, canRedo }
• use-active-node.ts — useActiveNode(): returns the single active PenNode or null
• use-active-page.ts — useActivePage(): returns active page ID
• use-hover.ts — useHover(): returns hovered node ID
• use-variables.ts — useVariables(): returns document variables map

Utilities (src/utils/)

• use-engine-subscribe.ts — useEngineSubscribe(engine, event, getSnapshot): generic hook using useSyncExternalStore to subscribe to engine events with stable snapshot refs

Stores (src/stores/)

• ui-store.ts — useUIStore (Zustand): pure UI state -- panel visibility, layer drag state, collapsed nodes. NOT engine state

Components (src/components/)

• design-canvas.tsx — DesignCanvas: canvas element with CanvasKit rendering via attachCanvas + attachInteraction from pen-engine browser adapter
• core-toolbar.tsx — CoreToolbar: main tool selection bar
• tool-button.tsx — ToolButton: individual tool button with active state
• shape-tool-dropdown.tsx — ShapeToolDropdown: dropdown for shape tools (rectangle, ellipse, line, polygon)
• layer-panel.tsx — LayerPanel: document tree panel with drag-and-drop reordering
• layer-item.tsx — LayerItem: individual layer row with visibility/lock toggles
• layer-context-menu.tsx — LayerContextMenu: right-click context menu for layers
• property-panel.tsx — PropertyPanel: right-side property inspector (delegates to section components)
• color-picker.tsx — ColorPicker: color input with hex/opacity, gradient support
• number-input.tsx — NumberInput: numeric input with drag-to-adjust
• section-header.tsx — SectionHeader: collapsible section header
• font-picker.tsx — FontPicker: font family selector with search
• variable-picker.tsx — VariablePicker: design variable selector
• icon-picker-dialog.tsx — IconPickerDialog: icon search and selection
• boolean-toolbar.tsx — BooleanToolbar: union/subtract/intersect boolean operations
• page-tabs.tsx — PageTabs: multi-page tab bar
• status-bar.tsx — StatusBar: bottom status bar (zoom, selection info)

Property sections (src/components/sections/)

• size-section.tsx — Width, height, x, y, rotation
• fill-section.tsx — Fill array editor (solid, gradient, image)
• stroke-section.tsx — Stroke properties (thickness, alignment, dash)
• text-section.tsx — Text content, font, size, weight, style
• text-layout-section.tsx — Text alignment, growth mode
• corner-radius-section.tsx — Corner radius (uniform or per-corner)
• effects-section.tsx — Blur and shadow effects
• layout-section.tsx — Auto-layout direction, gap, alignment
• layout-padding-section.tsx — Padding (uniform or per-side)
• appearance-section.tsx — Opacity, blend mode, visibility
• icon-section.tsx — Icon font name and family
• image-section.tsx — Image source, fit mode, adjustments
• export-section.tsx — Export format and code preview

Testing

bun --bun vitest run packages/pen-react/src/__tests__/