candle-annotator/openspec/changes/archive/2026-02-15-span-annotation/proposal.md

Why

The tool currently only supports point annotations (single-candle markers like Break Up/Down) and line drawings. Many candlestick patterns span multiple consecutive candles (bull flags, head and shoulders, double bottoms, wedges). To label these patterns for ML training, users need the ability to select a range of candles and assign a pattern label. This is the standard approach for labeling multi-candle patterns in time series data.

What Changes

• Add a new "span" annotation type that selects a range of consecutive candles via two clicks (start candle, end candle)
• Add a label assignment UI (dropdown/popover) with user-configurable pattern categories (e.g., bull_flag, bear_flag, head_and_shoulders)
• Add optional metadata fields per span: confidence (1-5), outcome (win/loss/breakeven), free-text notes
• Render span annotations as semi-transparent colored rectangles behind the candle range with label tags
• Add span annotation list in the sidebar (search, filter, select, delete)
• Support editing and deleting existing span annotations
• Add sub-span support within a parent span (e.g., marking "pole" and "flag" within a bull flag)
• Add export in three formats: Windowed Classification CSV, BIO-tagged CSV, Raw Annotations JSON
• Add user-configurable label categories with colors and hotkeys

Capabilities

New Capabilities

• span-annotation: Core span/range annotation interaction - two-click candle selection, label assignment popover, visual rendering as colored rectangles on the chart, span selection/editing/deletion, sidebar list management
• span-labels-config: User-configurable pattern label categories with names, colors, and hotkeys (stored in DB via annotation_types or a new config)
• span-export: Export span annotations in multiple ML-friendly formats - Windowed Classification CSV, BIO-tagged sequence labels CSV, and Raw Annotations JSON with configurable context padding

Modified Capabilities

• annotation-tools: Add "Span" tool mode to the active tool state. The tool toggle system needs a new mode alongside existing break_up, break_down, line, and delete modes.
• backend-api: New API endpoints for span annotations CRUD, span label config CRUD, and span export endpoints. Existing annotation endpoints may need to coexist or be extended.
• chart-canvas: Chart needs to render span annotation rectangles (via SVG overlay or chart primitives) in addition to existing markers and lines. Click handling needs span mode support.

Impact

• Database: New span_annotations table (or extend annotations with span-specific fields). New span_labels config table for pattern categories.
• Frontend components: New SpanOverlay component (or extend SvgOverlay), new SpanPopover/Dialog for label assignment, new SpanAnnotationList sidebar section.
• API routes: New /api/span-annotations CRUD endpoints, new /api/span-labels config endpoints, new /api/export/spans endpoints for the three export formats.
• State management: New state in page.tsx for span mode, active span selection, span annotations list.
• Dependencies: No new external dependencies expected - lightweight-charts SVG overlay approach already established for lines.