xiaodao-spreader 0.1.37 → 0.1.41

package/README.md

@@ -24,18 +24,19 @@ A high-performance, canvas-based spreadsheet component for Vue 3: bringing an Ex
 - **Merge Cells**: Merge & Center, Merge Across, Unmerge; merged-region borders stored at the anchor, shared borders resolved at render time
 - **Freeze Panes**: Pin frozen top rows / left columns so they keep visible while the body scrolls. The toolbar "Freeze Panes" dropdown exposes *Freeze Panes* (freezes at the top-left corner of the current selection / active cell: Excel's "Freeze Panes" behavior), *Freeze First Row*, *Freeze First Column*, and *Unfreeze* (shown only when a pane is already frozen, replacing the "Freeze Panes" entry). Per-sheet view state (`freeze: { rows, cols }`) persisted through v-model; merged cells straddling the freeze line are handled correctly: only the frozen portion stays pinned, the rest scrolls away
 - **Rich Cell Formatting**: Font family, font size (5–72), bold, italic, underline, strikethrough, text color, fill color, horizontal & vertical alignment, wrap text
-- **Borders**: Top / bottom / left / right / outside / all / none with 5 predefined styles and custom color; stored in a dedicated border pool, shared borders resolved at render time
+- **Borders**: Top / bottom / left / right / outside / all / none with 5 predefined styles, custom color, and per-side line type (solid / dashed / dotted); stored in a dedicated border pool, shared borders resolved at render time
 - **Undo / Redo**: Full state snapshots for cells, column widths, and row heights (50 steps)
 - **Format Painter**: Copy & apply cell formatting across ranges
 - **Number Format**: Excel-style number formatting (General / Text / Number / Currency / Accounting / Percent / Scientific / Date / Time / DateTime / Duration) with a custom format dialog; display-only, never mutates the stored cell value
 - **Smart Data Recognition**: Typing `100%`, `1,234`, `¥1,234.56` auto-converts the text to a number and applies the matching format; common date/time text auto-converts to dates: matching Excel input behavior
 - **Sorting & Sort Warning**: Sort any column by its **displayed content** (numbers / dates / text); sorting moves data only, never cell styles; ranges containing merged cells or formulas are auto-disabled; when adjacent data sits outside the selection, an Excel-style **Sort Warning** dialog lets you choose "Expand the selection" or "Sort the current selection only"
-- **Auto Filter (AutoFilter)**: Excel-style auto filter on a normal range. Enable via the toolbar **Data → Filter** or `Ctrl+Shift+L`; select a data cell (or a single-row multi-column range) and the filter is created by intelligently probing the contiguous data region **downward** from that header row. Each column header shows a filter drop-down arrow; opening it reveals the filter panel (values / text / number / date / search / blanks / multi-column AND). Clearing one column's criteria clears only that column; removing the AutoFilter clears everything. Only columns inside the Filter Range get an arrow; selecting a single merged cell with no active filter disables the filter button — *see [Auto Filter (AutoFilter)](#auto-filter-autofilter)*
+- **Auto Filter (AutoFilter)**: Excel-style auto filter on a normal range. Enable via the toolbar **Data → Filter** or `Ctrl+Shift+L`; select a data cell (or a single-row multi-column range) and the filter is created by intelligently probing the contiguous data region **downward** from that header row. Each column header shows a filter drop-down arrow; opening it reveals the filter panel (values / text / number / date / search / blanks / multi-column AND). Clearing one column's criteria clears only that column; removing the AutoFilter clears everything. Only columns inside the Filter Range get an arrow; selecting a single merged cell with no active filter disables the filter button - *see [Auto Filter (AutoFilter)](#auto-filter-autofilter)*
 - **Find & Replace**: Open via the toolbar find button or `Ctrl/Cmd+F` (also `Ctrl/Cmd+H`); three scopes: current sheet / entire workbook / current selection; match case and match entire cell; highlights all matches and locates the active one with wrap-around navigation; single and replace-all both integrate with undo/redo, mutating only the raw `value` (always kept a string), never format / border / merge
-- **Conditional Formatting**: Excel-style conditional formatting rules stored per-sheet. The toolbar "Conditional Formatting" dropdown offers preset rules (greater than / less than / between / text contains / duplicate / unique / blank / not blank) and a "New Rule" dialog with cell value and formula-based conditions. Rules render as temporary style overlays on top of the base cell style — no mutation of the underlying cell `value` or `styleId`. Rule priority (smaller number = higher), `stopIfTrue` semantics, and automatic cache invalidation on cell value change. Inserting / deleting rows or columns adjusts rule ranges and formula references via the same `shiftFormulaRefs` engine used by auto-fill. Includes a "Manage Rules" dialog for editing, reordering, and deleting rules; the "Clear Rules" sub-dialog lets you clear all rules or rules from selected ranges. Render-time style synthesis correctly composes CF background, font color, bold, italic, underline, and strikethrough with the base cell style. *see [Conditional Formatting](#conditional-formatting)*
-- **Data Validation**: Excel-style data validation rules stored per-sheet. The toolbar "Data Validation" button opens a dialog to set the allowed type (any value / list / whole number / decimal / date / time / text length / custom formula), the operator (between, not between, equal, greater than, …), and the criterion values. List validation shows an in-cell dropdown with search and full keyboard navigation (↑ ↓ / Home / End / PageUp / PageDown / Enter / Esc). Per-rule input message and error alert (Stop / Warning / Information) are supported; validation runs *before* the value is committed, so Stop-level violations reject the edit while Warning/Information let the user confirm. All rules on a range must pass. Rules persist through v-model, integrate with undo/redo, and adjust automatically on row/column insert/delete. Copy/paste and Auto Fill validate atomically — a Stop violation cancels the whole operation. *see [Data Validation](#data-validation)*
+- **Conditional Formatting**: Excel-style conditional formatting rules stored per-sheet. The toolbar "Conditional Formatting" dropdown offers preset rules (greater than / less than / between / text contains / duplicate / unique / blank / not blank) and a "New Rule" dialog with cell value and formula-based conditions. Rules render as temporary style overlays on top of the base cell style - no mutation of the underlying cell `value` or `styleId`. Rule priority (smaller number = higher), `stopIfTrue` semantics, and automatic cache invalidation on cell value change. Inserting / deleting rows or columns adjusts rule ranges and formula references via the same `shiftFormulaRefs` engine used by auto-fill. Includes a "Manage Rules" dialog for editing, reordering, and deleting rules; the "Clear Rules" sub-dialog lets you clear all rules or rules from selected ranges. Render-time style synthesis correctly composes CF background, font color, bold, italic, underline, and strikethrough with the base cell style. *see [Conditional Formatting](#conditional-formatting)*
+- **Data Validation**: Excel-style data validation rules stored per-sheet. The toolbar "Data Validation" button opens a dialog to set the allowed type (any value / list / whole number / decimal / date / time / text length / custom formula), the operator (between, not between, equal, greater than, …), and the criterion values. List validation shows an in-cell dropdown with search and full keyboard navigation (↑ ↓ / Home / End / PageUp / PageDown / Enter / Esc). Per-rule input message and error alert (Stop / Warning / Information) are supported; validation runs *before* the value is committed, so Stop-level violations reject the edit while Warning/Information let the user confirm. All rules on a range must pass. Rules persist through v-model, integrate with undo/redo, and adjust automatically on row/column insert/delete. Copy/paste and Auto Fill validate atomically - a Stop violation cancels the whole operation. *see [Data Validation](#data-validation)*
+- **Cell Notes**: Excel-style cell notes (comments). Right-click menu to create / edit / delete; red triangle indicator at cell corner marks cells with notes; hover to preview, click to edit. Notes are independent from cell values and styles, stored via a Note Pool (Sheet-level notes pool + cell.noteId reference), so sort / insert-delete moves cells together with their notes. Notes support multi-line text, optional author, and create/update timestamps. Author name can be set via the noteAuthor prop. *see [Cell Notes](#cell-notes)*
 - **Auto Fill (Fill Handle)**: Excel-style fill handle at the bottom-right corner of the active selection. Drag it up/down/left/right to fill cells: single values copy, number/date/text-number sequences auto-continue (e.g. `1,2 → 3,4,5`), formula references adjust per relative/absolute/mixed rules (e.g. `=A1*2` → `=A2*2`), and source `styleId` is reused via the style pool. Live preview during drag, edge auto-scroll, dynamic sheet expansion, freeze-pane compatibility, and a single undo step per operation: *see [Auto Fill](#auto-fill)*
-- **Row / Column Grouping & Collapsing**: Excel-style row/column outlines. Select whole rows or columns, then the toolbar "Group" dropdown (between Sort and Filter) offers Add Group / Ungroup / Clear Outline / Expand All / Collapse All, applied directly to the selected axis; row/column context menus expose a matching "Group" submenu. Only one level of non-overlapping groups is supported — nesting and partial overlap are rejected with a message. Group ranges get alternating background colors in the row/column header band; ± collapse buttons float inside the header band without reserving a separate gutter. Collapsed rows/columns are skipped during content rendering; inserting/deleting rows or columns shifts group ranges and auto-removes emptied groups. Groups persist per-sheet (`rowOutlines` / `columnOutlines`) through v-model, and every mutation integrates with undo/redo. *see [Row / Column Grouping & Collapsing](#row--column-grouping--collapsing)*
+- **Row / Column Grouping & Collapsing**: Excel-style row/column outlines. Select whole rows or columns, then the toolbar "Group" dropdown (between Sort and Filter) offers Add Group / Ungroup / Clear Outline / Expand All / Collapse All, applied directly to the selected axis; row/column context menus expose a matching "Group" submenu. Only one level of non-overlapping groups is supported - nesting and partial overlap are rejected with a message. Group ranges get alternating background colors in the row/column header band; ± collapse buttons float inside the header band without reserving a separate gutter. Collapsed rows/columns are skipped during content rendering; inserting/deleting rows or columns shifts group ranges and auto-removes emptied groups. Groups persist per-sheet (`rowOutlines` / `columnOutlines`) through v-model, and every mutation integrates with undo/redo. *see [Row / Column Grouping & Collapsing](#row--column-grouping--collapsing)*
 
 ### Interaction
 - **Smart Selection**: Click, drag, Shift+Click, row/column header select, corner-cell select-all
@@ -140,6 +141,7 @@ const myData = ref<SheetModelData[]>([
 | `height` | `number \| string` | - | Component height (pixels; omit or pass `string` for responsive) |
 | `theme` | `'light' \| 'dark'` | `'light'` | Theme mode |
 | `locale` | `string` | `'zh-CN'` | Language: `'zh-CN'` \| `'en-US'` |
+| `noteAuthor` | `string` | `''` | Current note author name; when empty, saved notes have empty author field that renders as i18n placeholder |
 
 ---
 
@@ -157,15 +159,18 @@ interface SheetModelData {
   cells: Record<string, {
     value: string;
     styleId?: number;
+    /** Note reference pointing to a CellNote in the Sheet-level notes pool */
+    noteId?: string;
   }>;
   merges?: Record<string, SelectionRange>;
   freeze?: { rows: number; cols: number };
   colWidths?: Record<number, number>;
   rowHeights?: Record<number, number>;
-  /** Logic column count (0-based exclusive). Defaults to 26 when omitted. */
-  colCount?: number;
-  /** Logic row count (0-based exclusive). Defaults to 200 when omitted. */
-  rowCount?: number;
+  // Grid dimensions (colCount/rowCount) are not persisted: they are derived from
+  // content on load (deriveModelDims), at least the props default 26x200, then
+  // extended by data / custom row/column sizes / rule ranges
+  /** Cell notes pool: CellNote objects keyed by noteId; cell.noteId references into this pool */
+  notes?: Record<string, CellNote>;
 }
 ```
 
@@ -185,7 +190,7 @@ import type {
   CellData,        // { value: string; styleId?: number }
   CellStyle,       // Typed style interface (font, color, border, alignment, etc.)
   BorderStyle,     // Four-side border { top; right; bottom; left }
-  BorderSide,      // Single border side { width; color; style }
+  BorderSide,      // Single border side { width; color; style; owner? }
   BorderSource,    // Border source 'cell' | 'merge'
   Range,           // { start: number; end: number }
   SpreadsheetOptions,
@@ -214,41 +219,62 @@ src/
     └── spreader/
         ├── index.ts                  # Unified export: component + types (barrel)
         ├── components/
-        │   ├── spreader.vue          # Entry component: template + style + composition
-        │   ├── toolbar.vue           # Toolbar with overflow dropdown
-        │   ├── tabbar.vue            # Sheet tab bar
-        │   ├── dropdown.vue          # Generic dropdown component
-        │   ├── find-replace-bar.vue  # Find/replace bar UI
+        │   ├── spreader.vue         # Entry component: template + style + composition
+        │   ├── toolbar.vue          # Toolbar with overflow dropdown
+        │   ├── tabbar.vue           # Sheet tab bar
+        │   ├── dropdown.vue         # Generic dropdown component
+        │   ├── find-replace-bar.vue # Find/replace bar UI
+        │   ├── note-overlay.vue     # Note view/edit overlay (dual-mode: view + edit)
         │   └── pickers/
-        │       ├── colorPicker.vue       # Text & fill color picker
-        │       ├── borderPicker.vue      # Border picker
-        │       ├── mergePicker.vue       # Merge cell picker
-        │       ├── numberFormatDialog.vue # Number format custom dialog
-        │       ├── sortPicker.vue        # Sort dropdown
-        │       ├── sortConfirmDialog.vue # Excel-style sort warning dialog
-        │       ├── calcPicker.vue        # Sum / average / count picker
-        │       └── insertFunctionDialog.vue # Insert function dialog
+        │       ├── border-picker.vue                  # Border picker (per-side type/color/line style + submenus)
+        │       ├── calc-picker.vue                    # Sum / average / count picker
+        │       ├── color-palette.vue                  # Shared color swatch palette for text / fill / border
+        │       ├── color-picker.vue                   # Text & fill color picker
+        │       ├── conditional-format-manager.vue     # Conditional formatting "Manage Rules" dialog
+        │       ├── conditional-format-menu.vue        # Conditional formatting toolbar dropdown (presets + new / manage / clear rules)
+        │       ├── conditional-format-rule-editor.vue # Conditional formatting "New / Edit Rule" dialog
+        │       ├── data-validation-alert.vue          # Data validation error alert (Stop / Warning / Information)
+        │       ├── data-validation-dialog.vue         # Data validation settings dialog
+        │       ├── data-validation-dropdown.vue       # Data validation list dropdown (search + virtual list + keyboard)
+        │       ├── data-validation-input-message.vue  # Cell-focus input message tooltip
+        │       ├── filter-popup.vue                   # Auto Filter panel (values / text / number / date + search + blanks + multi-column AND)
+        │       ├── insert-function-dialog.vue         # Insert function dialog
+        │       ├── merge-picker.vue                   # Merge cell picker
+        │       ├── number-format-dialog.vue           # Number format dialog
+        │       ├── outline-picker.vue                 # Toolbar "Group" dropdown (add / ungroup / clear, expand / collapse)
+        │       ├── sort-confirm-dialog.vue            # Excel-style sort warning dialog
+        │       └── sort-picker.vue                    # Sort dropdown
         ├── composables/
-        │   ├── core-state.ts        # Props, cells/merges/selection, font metrics, navigation
-        │   ├── undo-styles.ts       # Undo/redo, format painter, font/alignment/color
-        │   ├── borders-merge.ts     # Border ops, merge ops, clipboard, sum
-        │   ├── sheets-ops.ts        # Row/col ops, multi-sheet, v-model emit, theme, refs
-        │   ├── find-replace.ts      # Find/replace state & interaction (Vue-dependent)
-        │   └── interactions.ts      # Renderer, formula bar, tab bar, context menu, scrollbar, events
+        │   ├── borders-merge.ts       # Border ops, merge ops, clipboard, sum/avg/count
+        │   ├── core-state.ts          # Props, cells/merges/selection, font metrics, navigation, outline state
+        │   ├── find-replace.ts        # Find/replace state & interaction (Vue-dependent)
+        │   ├── interactions.ts        # Renderer, formula bar, tab bar, context menu, scrollbar, events
+        │   ├── sheets-ops.ts          # Row/col ops, multi-sheet, v-model emit, theme, refs
+        │   ├── undo-styles.ts         # Undo/redo, format painter, font/alignment/color
+        │   └── float-menu-position.ts # Shared toolbar dropdown positioning (right-anchor + flip/clamp)
         └── core/
-            ├── constants.ts         # Layout constants, i18n, theme palettes
-            ├── types.ts             # All type definitions
-            ├── style-pool.ts        # Style pool: dedup, registration, resolve, migration, GC
-            ├── border-pool.ts       # Border pool: dedup, registration, resolve, migration, GC
-            ├── border-resolve.ts    # Shared-border conflict resolution (resolveSharedBorder)
-            ├── formula.ts           # Formula engine (parse, evaluate, deps, cache)
-            ├── find-replace-core.ts # Find/replace pure algorithms (zero Vue deps, unit-testable)
-            ├── sort-core.ts         # Sort pure algorithms (zero Vue deps, unit-testable)
-            ├── autofill.ts          # Auto-fill pure engine (pattern inference, fill handle logic, zero Vue deps)
-            ├── number-format.ts     # Number format engine (Excel-style display formatting)
-            ├── conditional-formatting.ts # Conditional formatting engine (condition eval, rule cache, formula ref shift)
-            ├── theme.ts             # Theme CSS variable construction
-            └── utils.ts             # Pure utilities (col label, hit test, resolve size)
+            ├── autofill.ts               # Auto-fill pure engine (pattern inference, fill handle, zero Vue deps)
+            ├── border-color.ts           # Per-side border color: color decoupled from line type, plan color changes
+            ├── border-icon.ts            # Border icon single source (toolbar + picker)
+            ├── border-pool.ts            # Border pool: dedup, registration, resolve, migration, GC
+            ├── border-resolve.ts         # Shared-border conflict resolution (resolveSharedBorder)
+            ├── border-style.ts           # Border line type (solid / dashed / dotted): normalize + dash pattern
+            ├── conditional-formatting.ts # Conditional formatting engine (condition eval + rule cache, pure)
+            ├── constants.ts              # Layout constants, i18n text, theme color palette
+            ├── data-validation.ts        # Data validation engine (pure)
+            ├── filter-core.ts            # AutoFilter engine (pure, cascading candidates)
+            ├── find-replace-core.ts      # Find/replace pure algorithms (zero Vue deps, unit-testable)
+            ├── formula.ts                # Formula engine (parsing, evaluation, dependency tracking)
+            ├── model-dims.ts             # Model dimensions derived from content (pure)
+            ├── notes.ts                  # Note pool management: CRUD, persistence, undo integration
+            ├── number-format.ts          # Number format engine (Excel-style display formatting)
+            ├── outline-core.ts           # Row/column grouping pure engine (validation / shifting / collapse)
+            ├── sort-core.ts              # Sort pure algorithms (zero Vue deps, unit-testable)
+            ├── sort-icon.ts              # Sort icon single source (toolbar + picker)
+            ├── style-pool.ts             # Style pool: dedup, registration, resolve, migration, GC
+            ├── theme.ts                  # Theme CSS variable construction
+            ├── types.ts                  # All type definitions
+            └── utils.ts                  # Pure utilities (column label, hit test, resolve size)
 ```
 
 ### Design Principles
@@ -374,11 +400,11 @@ An Excel-style number formatting engine (`spreader/core/number-format.ts`) that
 
 ## Conditional Formatting
 
-Excel-style conditional formatting stored per-sheet in `SheetState.conditionalFormats` (array of `ConditionalFormattingRule`). The engine lives in `spreader/core/conditional-formatting.ts` — pure-logic, zero Vue/Canvas deps, with unit tests in `test/conditional-formatting.test.ts`.
+Excel-style conditional formatting stored per-sheet in `SheetState.conditionalFormats` (array of `ConditionalFormattingRule`). The engine lives in `spreader/core/conditional-formatting.ts` - pure-logic, zero Vue/Canvas deps, with unit tests in `test/conditional-formatting.test.ts`.
 
 ### Rule Structure
 
-Each rule has a stable `id`, a `condition`, a `format` override, one or more `ranges`, a numeric `priority` (smaller = higher precedence), `stopIfTrue`, and `enabled` flag. The `format` carries only visual properties (`backgroundColor`, `color`, `fontWeight`, `fontStyle`, `underline`, `strikethrough`) — it never writes back to `cell.styleId`.
+Each rule has a stable `id`, a `condition`, a `format` override, one or more `ranges`, a numeric `priority` (smaller = higher precedence), `stopIfTrue`, and `enabled` flag. The `format` carries only visual properties (`backgroundColor`, `color`, `fontWeight`, `fontStyle`, `underline`, `strikethrough`) - it never writes back to `cell.styleId`.
 
 ### Supported Condition Types
 
@@ -405,25 +431,25 @@ Duplicate / unique / top-bottom / above-below rules need a value-frequency stati
 
 ### Insert / Delete Propagation
 
-`shiftFormulaRefsSafe` in the CF engine reuses the same `shiftFormulaRefs` function from the formula engine — so `$B$2` (absolute) stays locked while `A1` (relative) shifts. Rule ranges also expand/shrink accordingly; ranges completely removed from the sheet are auto-deleted.
+`shiftFormulaRefsSafe` in the CF engine reuses the same `shiftFormulaRefs` function from the formula engine - so `$B$2` (absolute) stays locked while `A1` (relative) shifts. Rule ranges also expand/shrink accordingly; ranges completely removed from the sheet are auto-deleted.
 
 ### Render-time Style Synthesis
 
-`resolveConditionalFormatting` is called per viewport cell inside `drawCells`. It walks all enabled rules whose ranges contain the cell, applies priority-merging, and produces a temporary `cfStyle`. `applyCfFormat` merges this onto the base resolved style, composing `backgroundColor`, `color`, `fontWeight`, `fontStyle`, `underline`, and `strikethrough` — including correct handling of merged cells (CF applies to the anchor cell and propagates to the entire merge region).
+`resolveConditionalFormatting` is called per viewport cell inside `drawCells`. It walks all enabled rules whose ranges contain the cell, applies priority-merging, and produces a temporary `cfStyle`. `applyCfFormat` merges this onto the base resolved style, composing `backgroundColor`, `color`, `fontWeight`, `fontStyle`, `underline`, and `strikethrough` - including correct handling of merged cells (CF applies to the anchor cell and propagates to the entire merge region).
 
 ### UI Components
 
 | File | Role |
 |------|------|
 | `conditional-format-menu.vue` | Toolbar dropdown: preset rules (highlight cells, blank, duplicate, unique), New Rule, Manage Rules, Clear Rules submenu. Teleport-based submenus with hover-intent (150ms debounce) for cross-gap hover transitions |
-| `conditional-format-rule-editor.vue` | "New Rule" dialog: condition type selector (reuses `SpDropdown`), threshold inputs, format panel (background color picker, text color picker, bold, italic, underline, strikethrough — all reuse toolbar picker/button styles), application range auto-filled from current selection |
+| `conditional-format-rule-editor.vue` | "New Rule" dialog: condition type selector (reuses `SpDropdown`), threshold inputs, format panel (background color picker, text color picker, bold, italic, underline, strikethrough - all reuse toolbar picker/button styles), application range auto-filled from current selection |
 | `conditional-format-manager.vue` | "Manage Rules" dialog: list all rules for the active sheet, drag-to-reorder priority toggle, edit/delete per rule, clear all / clear selection |
 
 ---
 
 ## Data Validation
 
-Excel-style data validation stored per-sheet in `SheetState.dataValidations` (array of `DataValidationRule`). The engine lives in `spreader/core/data-validation.ts` — pure-logic, zero Vue/Canvas deps, with unit tests in `test/data-validation.test.ts` and `test/data-validation-integration.test.ts`.
+Excel-style data validation stored per-sheet in `SheetState.dataValidations` (array of `DataValidationRule`). The engine lives in `spreader/core/data-validation.ts` - pure-logic, zero Vue/Canvas deps, with unit tests in `test/data-validation.test.ts` and `test/data-validation-integration.test.ts`.
 
 ### Rule Structure
 
@@ -433,7 +459,7 @@ Each rule has a stable `id`, a `type`, an `operator`, criterion values `formula1
 
 | Type | Description |
 |------|-------------|
-| `any` | No constraint — selecting it on save clears validation for the range |
+| `any` | No constraint - selecting it on save clears validation for the range |
 | `list` | In-cell dropdown from fixed values or a cell range |
 | `wholeNumber` / `decimal` | Numeric constraint |
 | `date` / `time` | Date / time constraint (ISO, `YYYY年M月D日`, US `m/d/yyyy`, or Excel serial) |
@@ -448,7 +474,7 @@ List validation resolves its items from either fixed `values` (`{ type: 'values'
 
 ### Validation Flow
 
-Validation runs **before** the value is committed. `commitEdit` returns `Promise<boolean>` — `false` means a Stop-level violation rejected the edit and the editor state is preserved. Warning/Information alerts call `showValidationAlert` and await user confirmation before proceeding. When multiple rules target the same range, **all** must pass (`rules.every()`).
+Validation runs **before** the value is committed. `commitEdit` returns `Promise<boolean>` - `false` means a Stop-level violation rejected the edit and the editor state is preserved. Warning/Information alerts call `showValidationAlert` and await user confirmation before proceeding. When multiple rules target the same range, **all** must pass (`rules.every()`).
 
 ### Range Index
 
@@ -456,7 +482,7 @@ A spatial row-band index (`DvIndex`) maps a (row, col) lookup to candidate rules
 
 ### Atomic Paste / Auto Fill
 
-Copy/paste and Auto Fill compute every candidate first, run `validateCells`, and cancel the whole operation if any Stop-level violation occurs — no partial commit.
+Copy/paste and Auto Fill compute every candidate first, run `validateCells`, and cancel the whole operation if any Stop-level violation occurs - no partial commit.
 
 ### Insert / Delete Propagation
 
@@ -469,7 +495,7 @@ Copy/paste and Auto Fill compute every candidate first, run `validateCells`, and
 | `data-validation-dialog.vue` | Toolbar "Data Validation" dialog: type/operator/value, list source, input message, error alert, apply range; validates min/max literals on save |
 | `data-validation-dropdown.vue` | In-cell list dropdown: virtual list, search box, full keyboard nav (↑ ↓ / Home / End / PageUp / PageDown / Enter / Esc) |
 | `data-validation-alert.vue` | Stop / Warning / Information alert box |
-| `data-validation-input-message.vue` | Hover tooltip showing the rule's input message (lives in `components/`, not `pickers/`) |
+| `data-validation-input-message.vue` | Hover tooltip showing the rule's input message |
 
 ### Persistence & Undo
 
@@ -504,6 +530,51 @@ Inserting/deleting rows or columns shifts group ranges via `addOutlineForInsert`
 
 ---
 
+## Cell Notes
+
+Excel-style cell notes (comments), fully independent from cell values and styles. The engine lives in `spreader/core/notes.ts` - pure-logic, zero Vue/Canvas deps; the UI overlay is `components/note-overlay.vue`.
+
+### Data Model
+
+Notes use a **Note Pool** storage pattern: each sheet maintains a `notes` pool keyed by stable `id`, and cells only store a `noteId` reference.
+
+``	ypescript
+interface CellNote {
+  id: string;           // Stable unique ID
+  text: string;         // Note body (multi-line text)
+  author?: string;      // Optional author name
+  createdAt: number;    // Creation time (epoch ms)
+  updatedAt: number;    // Last modification time (epoch ms)
+}
+``
+
+- **`CellData.noteId`**: Per-cell reference pointing into `SheetState.notes`
+- **`SheetModelData.notes`**: v-model serialized note pool, keyed by noteId
+
+The Note Pool design ensures that sort, insert/delete row/column, and other cell-moving operations carry `noteId` together with the cell data - notes never get orphaned.
+
+### Entry Points
+
+- **Context menu**: Cell right-click menu offers *New Note / Edit Note / Delete Note*; edit/delete are hidden when no note exists, new is hidden when one does
+- **Shift+F2**: Toggle the edit overlay on a note-bearing cell
+- **Hover preview**: A read-only view overlay pops up when the cursor hovers over a cell with a note
+
+### Rendering
+
+- Cells with a note show a 6px red triangle indicator in the top-right corner, drawn on Canvas (zero DOM cost)
+- The `note-overlay.vue` component is a Vue DOM overlay with `position: absolute` mounted inside `.spreadsheet-wrapper`, constrained by `overflow: hidden` to the table area - it never spills over the toolbar, row/column headers, frozen panes, or scrollbars
+- Z-index layering: non-frozen overlays sit *below* the freeze canvas (z-index: 0 vs 1), frozen-region overlays sit *above* it (z-index: 2); scrollbars (z-index: 3) always stay on top for interactivity
+
+### Author Name
+
+Set the current author via the `noteAuthor` prop. When empty, saved notes store an empty `author` field, and display falls back to an i18n placeholder (`Unnamed`).
+
+### Persistence & Undo
+
+- Notes persist through the sheet v-model (`notes` field), round-tripping correctly through save / load / duplicate-sheet
+- Creating / editing / deleting a note each produces one undo step, sharing the same undo stack as cell values, styles, and borders
+
+---
 ## Auto Fill
 
 An Excel-style fill-handle mechanism (`spreader/core/autofill.ts` pure engine + `composables/interactions.ts` canvas/interaction layer). Drag the small square at the bottom-right corner of the active selection to fill cells: no DOM handles, all drawn on Canvas.
@@ -608,9 +679,10 @@ Reuses the existing engine: the title shows the column's header text (not the co
 A dedicated border storage & rendering mechanism (`spreader/core/border-pool.ts` + `border-resolve.ts`).
 
 - **Dedicated border pool**: each sheet maintains a `borders: BorderStyle[]` pool (`borders[0]` is always the empty border `{}`); styles reference borders by index (`borderId`), and identical borders are deduplicated.
-- **Shared-border resolution**: adjacent cells' shared border is resolved at render time via `resolveSharedBorder()`: wider wins, then the first side on equal width; setting a border no longer mutates neighboring cells.
+- **Shared-border resolution**: adjacent cells' shared border is resolved at render time via `resolveSharedBorder()`: wider wins, then the first side on equal width; when exactly one side carries an `owner` flag (set by an explicit border or selection operation) that side wins the shared edge regardless of width, so a freshly applied selection-boundary edge takes priority over a pre-existing neighbor edge. Setting a border no longer mutates neighboring cells.
 - **Merged cells**: merged-region borders are stored at the anchor (top-left); internal borders are masked, outer boundaries are resolved segment-wise against neighbors, and the four corners fill in corner blocks.
 - **Legacy compatibility**: legacy inline border props (`borderTopWidth`, etc., deprecated) are auto-migrated via `migrateBordersInStyles()` on load.
+- **Per-side color & line type (decoupled)**: both live on each `BorderSide` (`{ width; color; style }`). Color is a standard HEX string; `''` / omitted means "auto" and renders as the default `#444`. Line `style` is one of `solid` / `dashed` / `dotted`; legacy data with no `style` defaults to `solid`, and a `solid` side stores no `style` key so its dedup key matches historical empty-border data. Changing the color only touches `color` and keeps `width`/`style`; changing the line type only touches `style` and keeps `width`/`color`. The border picker exposes two submenus: a color selector (reuses the text-color palette with an **Automatic** entry, colors only existing borders) and a **line-type** selector (solid / dashed / dotted previews, sets the active pen line type, then applies it to subsequent border operations and to the selection's existing edges, never creating a border that isn't there). Pure logic lives in `core/border-color.ts` (`withBorderColor` / `withBorderWidth` / `planBorderColorChanges` / `resolveSelectionBorderColor`) and `core/border-style.ts` (`normalizeBorderLineStyle` / `borderLineDash`), fully decoupled from Vue/Canvas and unit-tested. The renderer draws dashed/dotted via `paintBorderEdge` (solid keeps the original `fillRect` path so grid lines and the selection frame stay untouched).
 
 ---
 
@@ -732,7 +804,7 @@ x-spreader is touch-first: every mouse interaction has a symmetric touch path, v
 - [x] Sort & filter: sort by displayed content with Excel-style Sort Warning dialog (expand selection / current selection only); see [Sorting & Sort Warning](#features)
 - [x] Auto Filter (AutoFilter): toolbar "Filter" / `Ctrl+Shift+L` to enable, header drop-down arrows, intelligent downward data probing, value/text/number/date multi-type filters, separate clear-column vs remove-all; see [Auto Filter (AutoFilter)](#auto-filter-autofilter)
 - [x] Touch & mobile interaction: symmetric touch paths for select / context menu / filter / resize / range select / format brush / tab menu; popups close on outside tap; see [Touch & Mobile Interaction](#touch--mobile-interaction)
-- [ ] Cell comments / notes
+- [x] Cell comments / notes: Note Pool storage, context-menu CRUD, hover preview, edit overlay, persistence & undo; see [Cell Notes](#cell-notes)
 - [ ] Print layout
 
 ### Long-term