openpencil/openspec/specs/editor-ui/spec.md

# editor-ui Specification

## Purpose
Vue 3 + Reka UI editor interface. Bottom toolbar, layers panel with tree view and drag reorder, properties panel with sectioned layout (appearance, fill, stroke, typography, layout, position), color picker, and Lucide icons.
## Requirements
### Requirement: Vue 3 + Reka UI component architecture
The editor UI SHALL be built with Vue 3, VueUse composables, and Reka UI headless components. The UI framework was migrated from React to Vue 3.

#### Scenario: Editor loads
- **WHEN** user opens the editor at localhost:1420
- **THEN** the Vue 3 application renders with canvas, toolbar, layers panel, and properties panel

### Requirement: Bottom toolbar
The toolbar SHALL be positioned at the bottom of the screen (Figma UI3 style) with tool selection: Select (V), Frame (F), Section (S, in Frame flyout), Rectangle (R), Ellipse (O), Line (L), Polygon (flyout), Star (flyout), Text (T), Hand (H), Pen (P). The shapes flyout (Rectangle, Line, Ellipse, Polygon, Star) SHALL display keyboard shortcuts right-aligned for tools that have them.

#### Scenario: Tool selection via keyboard
- **WHEN** user presses R
- **THEN** the rectangle tool is activated and the toolbar shows R as selected

#### Scenario: Frame flyout includes Section
- **WHEN** user opens the Frame tool flyout
- **THEN** both Frame and Section tools are available

#### Scenario: Shapes flyout includes Polygon and Star
- **WHEN** user opens the shapes flyout
- **THEN** Polygon (triangle icon) and Star (star icon) are listed alongside Rectangle, Line, and Ellipse

#### Scenario: Draw polygon on canvas
- **WHEN** user selects Polygon tool and drags on canvas
- **THEN** a POLYGON node is created with default 3 sides

#### Scenario: Draw star on canvas
- **WHEN** user selects Star tool and drags on canvas
- **THEN** a STAR node is created with 5 points and 0.38 inner radius

### Requirement: Layers panel with tree view
The layers panel SHALL display a tree view of the document hierarchy using Reka UI Tree with expand/collapse and drag reordering.

#### Scenario: Expand/collapse frame children
- **WHEN** user clicks the chevron next to a frame in the layers panel
- **THEN** the frame's children are shown or hidden

#### Scenario: Drag reorder layers
- **WHEN** user drags a layer to a new position in the layers panel
- **THEN** the node's z-order in the scene graph changes accordingly

#### Scenario: Visibility toggle
- **WHEN** user clicks the visibility icon next to a layer
- **THEN** the node is hidden/shown on canvas

### Requirement: Properties panel with tabs
The properties panel SHALL be organized as a tabbed interface with Design | Code | AI tabs (reka-ui Tabs). The Design tab (DesignPanel) contains sections: Appearance (opacity, corner radius with independent mode, visibility toggle), Fill, Stroke, Effects, Typography, Layout, Position. The Code tab shows JSX export. The AI tab shows the chat interface.

#### Scenario: Properties panel shows fill section
- **WHEN** user selects a rectangle with a blue fill
- **THEN** the Fill section shows the hex color #3B82F6 with opacity and visibility controls

#### Scenario: Editable hex input
- **WHEN** user types a new hex value in the fill section
- **THEN** the node's fill updates to the entered color

### Requirement: Color picker
The color picker SHALL provide HSV color selection, hue slider, alpha slider, hex input, and opacity control.

#### Scenario: Change color via HSV
- **WHEN** user moves the color picker cursor in the HSV square
- **THEN** the selected node's fill updates in real time

### Requirement: Lucide icons via Iconify
UI icons SHALL use Lucide icons loaded via unplugin-icons with Iconify, replacing inline emoji/SVG.

#### Scenario: Icon rendering
- **WHEN** the toolbar renders tool icons
- **THEN** Lucide icons are displayed via the icon auto-import resolver

### Requirement: Tailwind CSS 4 styling
The editor SHALL use Tailwind CSS 4 for all styling.

#### Scenario: Dark theme
- **WHEN** the editor renders
- **THEN** the UI uses a dark theme styled with Tailwind CSS 4 utility classes

### Requirement: Pages panel
The editor SHALL display a PagesPanel component showing all pages in the document. Users can switch pages, add pages, delete pages, and rename pages inline (blur commits, Enter/Escape just blur).

#### Scenario: Switch page
- **WHEN** user clicks a page tab in the pages panel
- **THEN** the canvas switches to that page and viewport state is restored

#### Scenario: Add page
- **WHEN** user clicks the add page button
- **THEN** a new page is created and becomes active

#### Scenario: Inline page rename
- **WHEN** user double-clicks a page name
- **THEN** an inline text input appears, blur commits the rename

### Requirement: Section tool
The toolbar SHALL include a Section tool (shortcut <kbd>S</kbd>) in the Frame flyout. Drawing on canvas creates a SECTION node.

#### Scenario: Section tool activation
- **WHEN** user presses S
- **THEN** the section tool activates and the toolbar shows Section as selected

### Requirement: Fill type picker with gradient and image support
The fill section in the properties panel SHALL provide a type picker with tabs: Solid, Gradient (Linear, Radial, Angular, Diamond), and Image. Gradient fills show editable gradient stops. Image fills show image selection.

#### Scenario: Switch fill to linear gradient
- **WHEN** user selects "Linear Gradient" from the fill type picker
- **THEN** the selected node's fill changes to GRADIENT_LINEAR with default stops and the gradient stop editor appears

#### Scenario: Edit gradient stop
- **WHEN** user drags a gradient stop to position 50%
- **THEN** the stop position updates and the node re-renders with the adjusted gradient

### Requirement: Page background color
The properties panel SHALL show a page section with canvas background color picker when no nodes are selected.

#### Scenario: Change canvas background
- **WHEN** user selects no nodes and changes the page color
- **THEN** the canvas background updates to the chosen color

### Requirement: Hover highlight in canvas
The editor SHALL highlight nodes on hover with a shape-aware outline (follows actual geometry, not just bounding box).

#### Scenario: Hover feedback
- **WHEN** user moves cursor over a node without clicking
- **THEN** a highlight outline appears around the node shape


### Requirement: Component keyboard shortcuts
The editor SHALL support keyboard shortcuts for component operations: ⌥⌘K (create component), ⌥⌘B (detach instance), ⇧⌘K (create component set).

#### Scenario: Create component shortcut
- **WHEN** user selects a frame and presses ⌥⌘K
- **THEN** the frame becomes a component

### Requirement: Z-order keyboard shortcuts
The editor SHALL support ] (bring to front) and [ (send to back) keyboard shortcuts.

#### Scenario: Bring to front shortcut
- **WHEN** user selects a node and presses ]
- **THEN** the node moves to the top of its z-order

### Requirement: Visibility and lock keyboard shortcuts
The editor SHALL support ⇧⌘H (toggle visibility) and ⇧⌘L (toggle lock) keyboard shortcuts.

#### Scenario: Toggle visibility shortcut
- **WHEN** user selects a node and presses ⇧⌘H
- **THEN** the node's visibility toggles

### Requirement: Effects section in properties panel
The properties panel SHALL include an Effects section showing all effects on the selected node. Each effect displays as a collapsible row with: color swatch (shadows) or blur icon (blurs), type dropdown (DROP_SHADOW, INNER_SHADOW, LAYER_BLUR, BACKGROUND_BLUR, FOREGROUND_BLUR), visibility toggle, and remove button. Clicking a row expands inline controls.

#### Scenario: Add drop shadow effect
- **WHEN** user clicks the + button in the Effects section
- **THEN** a DROP_SHADOW effect is added with default values (offset 0,4; radius 4; spread 0; color rgba(0,0,0,0.25))

#### Scenario: Switch effect type
- **WHEN** user changes the type dropdown from DROP_SHADOW to LAYER_BLUR
- **THEN** the effect type updates and offset/spread fields are hidden (only blur radius shown)

#### Scenario: Inline shadow controls
- **WHEN** user expands a shadow effect row
- **THEN** X/Y offset, blur radius, spread, color picker, hex input, and opacity controls appear inline

#### Scenario: Toggle effect visibility
- **WHEN** user clicks the eye icon on an effect row
- **THEN** the effect's `visible` property toggles and the canvas re-renders

#### Scenario: Remove effect
- **WHEN** user clicks the − button on an effect row
- **THEN** the effect is removed from the node

### Requirement: Independent corner radius toggle in Appearance section
The Appearance section SHALL show a corner radius toggle button for RECTANGLE, ROUNDED_RECTANGLE, FRAME, COMPONENT, and INSTANCE nodes. When toggled to independent mode, a 2×2 grid of per-corner radius inputs (top-left, top-right, bottom-left, bottom-right) replaces the single radius input. Each corner has a distinct icon. Toggling back to uniform sets all corners to the top-left value.

#### Scenario: Toggle to independent corners
- **WHEN** user clicks the independent corners button
- **THEN** four separate corner radius inputs appear in a grid layout

#### Scenario: Toggle back to uniform
- **WHEN** user clicks the independent corners button while in independent mode
- **THEN** a single corner radius input appears, set to the top-left value

### Requirement: Resizable panels
The left (layers) and right (properties) panels SHALL be resizable via reka-ui Splitter components (SplitterGroup, SplitterPanel, SplitterResizeHandle). Default width SHALL be 15%, minimum 10%, maximum 30%. Panel layout SHALL persist across reloads via auto-save-id. The resize handle SHALL be 8px wide with negative margins and a centered 1px visible line that highlights blue on hover/drag.

#### Scenario: Resize layers panel
- **WHEN** user drags the resize handle between layers panel and canvas
- **THEN** the layers panel width changes and the canvas resizes accordingly

#### Scenario: Panel size persists
- **WHEN** user resizes panels and reloads the page
- **THEN** panel widths are restored to the previous sizes

### Requirement: Throttled WebGL surface recreation during resize
The CanvasKit surface SHALL be recreated at most once per animation frame during panel resize, coalesced via requestAnimationFrame in the ResizeObserver callback.

#### Scenario: Panel resize performance
- **WHEN** user drags a panel resize handle continuously
- **THEN** the WebGL surface is recreated at most once per frame

### Requirement: Variables dialog
The editor SHALL display a VariablesSection in the page-level properties panel showing variable/collection counts and a settings icon. Clicking the icon opens a VariablesDialog (reka-ui Dialog) with: collection tabs (reka-ui Tabs, double-click to rename), a TanStack Table (@tanstack/vue-table) with resizable columns (Name | Mode 1 | Mode 2 | ...), search bar, and a "+ Create variable" button. Color variables display inline ColorInput with picker. Variable names and values are editable inline (reka-ui Editable).

#### Scenario: Open variables dialog
- **WHEN** user clicks the settings icon in the Variables section of page properties
- **THEN** a dialog opens showing collection tabs and a variables table

#### Scenario: Rename collection
- **WHEN** user double-clicks a collection tab name
- **THEN** the tab becomes editable for renaming

#### Scenario: Resize table columns
- **WHEN** user drags a column border in the variables table header
- **THEN** the column width adjusts

#### Scenario: Search variables
- **WHEN** user types in the search bar in the variables dialog
- **THEN** only variables matching the search term are shown

#### Scenario: Edit variable value
- **WHEN** user clicks a variable value cell in the table
- **THEN** an editable input allows changing the value for that mode

### Requirement: Fill section variable picker
The fill section SHALL include a variable picker (reka-ui Popover + Combobox) to bind a color variable to a fill. Bound fills display a purple variable name badge with a detach button.

#### Scenario: Bind variable to fill
- **WHEN** user selects a color variable from the fill variable picker
- **THEN** the fill shows a purple badge with the variable name

#### Scenario: Detach variable from fill
- **WHEN** user clicks the detach button on a bound fill
- **THEN** the variable binding is removed and the fill shows the resolved color

### Requirement: Export section in properties panel
The properties panel SHALL include an ExportSection when nodes are selected. The section provides: scale selector (0.5×, 0.75×, 1×, 1.5×, 2×, 3×, 4×), format picker (PNG, JPG, WEBP), multi-export support (add/remove export settings), live preview with checkerboard background, and an Export button. JPG uses white background, PNG/WEBP use transparency.

#### Scenario: Export as PNG
- **WHEN** user sets format to PNG, scale to 2×, and clicks Export
- **THEN** a 2× resolution PNG is saved via native dialog / FSAPI / download

#### Scenario: Export via context menu
- **WHEN** user right-clicks a node and selects "Export…"
- **THEN** the export flow starts for the selected node

#### Scenario: Export via keyboard shortcut
- **WHEN** user presses ⇧⌘E with a node selected
- **THEN** the export flow starts

### Requirement: Splash loader
The editor SHALL display a minimalist loading animation (centered logo + progress bar) during WASM (CanvasKit) initialization. The loader fades out when the canvas is ready.

#### Scenario: Initial load
- **WHEN** user opens the editor
- **THEN** a splash loader is shown until CanvasKit WASM is loaded, then fades out

### Requirement: ColorInput component
A reusable ColorInput component SHALL display a color swatch with ColorPicker and an optional hex input. It SHALL replace duplicated color picker + hex input patterns in PageSection, StrokeSection, EffectsSection, and VariablesDialog.

#### Scenario: Color input with editing
- **WHEN** ColorInput is rendered with editable=true
- **THEN** a swatch with picker and an editable hex input are shown

#### Scenario: Color input read-only
- **WHEN** ColorInput is rendered with editable=false (default)
- **THEN** a swatch with picker and a read-only hex label are shown

### Requirement: ColorPicker alpha slider checkerboard
The ColorPicker alpha slider SHALL display a checkerboard background behind the transparent-to-color gradient, matching FillPicker's implementation.

#### Scenario: Alpha slider visual
- **WHEN** user opens a ColorPicker
- **THEN** the alpha slider shows a checkerboard pattern indicating transparency

### Requirement: Demo variable collections
The demo document SHALL include three variable collections demonstrating multi-mode and alias features: Primitives (Light/Dark modes, 9 color variables), Semantic (aliases to Primitives), and Spacing (Default/Compact modes, 8 number variables). Variables SHALL be bound to demo nodes.

#### Scenario: Demo loads with variables
- **WHEN** the demo document is created
- **THEN** three collections with variables and bindings are present in the scene graph

### Requirement: Rich text formatting buttons
The TypographySection SHALL include B/I/U/S toggle buttons for Bold, Italic, Underline, and Strikethrough. When text is selected during editing, the buttons apply formatting to the selection. When editing with no selection, they toggle the whole-node style. The active state reflects current selection formatting.

#### Scenario: Bold button with selection
- **WHEN** user selects text and clicks the Bold button (or presses ⌘B)
- **THEN** the selection becomes bold and the B button shows active state

#### Scenario: Underline button with no selection
- **WHEN** user clicks the Underline button during editing with no selection
- **THEN** the entire text node's underline style toggles

### Requirement: AI chat panel
The editor SHALL include an AI chat panel accessible via the AI tab in properties panel or ⌘J shortcut. The panel provides: message list with streaming markdown (vue-stream-markdown), tool call timeline with collapsible details (reka-ui Collapsible), typing indicator, API key setup for OpenRouter (stored in Tauri Stronghold). Messages scroll automatically (reka-ui ScrollArea).

#### Scenario: Send message
- **WHEN** user types a message and presses Enter in the chat input
- **THEN** the message is sent to OpenRouter and a streaming response appears

#### Scenario: Toggle chat
- **WHEN** user presses ⌘J
- **THEN** the properties panel switches to the AI tab (or back to Design)

### Requirement: AI model selector
The chat input SHALL include a model selector with curated models: Claude, Gemini, GPT, DeepSeek, Qwen, Kimi, Llama. Models are stored in @open-pencil/core constants with benchmark-ranked tags.

#### Scenario: Change model
- **WHEN** user selects a different model from the selector
- **THEN** subsequent messages use the selected model

### Requirement: AI tools
The chat SHALL support 10 design tools with valibot schemas: create_shape, set_fill, set_stroke, update_node, set_layout, delete_node, select_nodes, get_page_tree, get_selection, rename_node. Tools execute against the editor store. The ToolLoopAgent calls tools automatically in a loop.

#### Scenario: AI creates a shape
- **WHEN** user asks "Create a blue rectangle 200×100"
- **THEN** the AI calls create_shape with type RECTANGLE, width 200, height 100, and set_fill with blue color

#### Scenario: Tool call visible in chat
- **WHEN** the AI executes a tool
- **THEN** a collapsible tool call section shows the tool name, input, and output

### Requirement: DirectChatTransport
The chat SHALL communicate directly with OpenRouter from the browser — no backend server required. The API key is stored securely in Tauri Stronghold (or localStorage fallback in browser). X-OpenRouter-Title header identifies the app.

#### Scenario: No backend required
- **WHEN** user configures an OpenRouter API key and sends a message
- **THEN** the request goes directly to OpenRouter without a proxy server

### Requirement: Code panel with JSX export
The properties panel Code tab SHALL display the selected node(s) as JSX code using sceneNodeToJsx(). The panel provides Prism.js syntax highlighting, line numbers, and a copy-to-clipboard button. Multi-selection shows each node's JSX.

#### Scenario: View JSX for selection
- **WHEN** user selects a frame and clicks the Code tab
- **THEN** the JSX representation of the frame and its children is displayed with syntax highlighting

#### Scenario: Copy JSX
- **WHEN** user clicks the copy button in the Code panel
- **THEN** the JSX code is copied to the clipboard