From abe336c3ef03f8136cd2362f5d950334d994e380 Mon Sep 17 00:00:00 2001
From: Fabio Montefuscolo <fabio.montefuscolo@gmail.com>
Date: Mon, 3 Aug 2026 22:09:19 +0200
Subject: [PATCH] chore: propose sidepanel-ux-improvements change

---
 .../sidepanel-ux-improvements/.openspec.yaml  |  2 +
 .../sidepanel-ux-improvements/design.md       | 67 ++++++++++++++++++
 .../sidepanel-ux-improvements/proposal.md     | 31 +++++++++
 .../specs/note-editor/spec.md                 | 69 +++++++++++++++++++
 .../specs/notes-storage/spec.md               | 16 +++++
 .../sidepanel-ux-improvements/tasks.md        | 31 +++++++++
 6 files changed, 216 insertions(+)
 create mode 100644 openspec/changes/sidepanel-ux-improvements/.openspec.yaml
 create mode 100644 openspec/changes/sidepanel-ux-improvements/design.md
 create mode 100644 openspec/changes/sidepanel-ux-improvements/proposal.md
 create mode 100644 openspec/changes/sidepanel-ux-improvements/specs/note-editor/spec.md
 create mode 100644 openspec/changes/sidepanel-ux-improvements/specs/notes-storage/spec.md
 create mode 100644 openspec/changes/sidepanel-ux-improvements/tasks.md

diff --git a/openspec/changes/sidepanel-ux-improvements/.openspec.yaml b/openspec/changes/sidepanel-ux-improvements/.openspec.yaml
new file mode 100644
index 0000000..e08b5f8
--- /dev/null
+++ b/openspec/changes/sidepanel-ux-improvements/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-03
diff --git a/openspec/changes/sidepanel-ux-improvements/design.md b/openspec/changes/sidepanel-ux-improvements/design.md
new file mode 100644
index 0000000..e02c0f1
--- /dev/null
+++ b/openspec/changes/sidepanel-ux-improvements/design.md
@@ -0,0 +1,67 @@
+# Design: Side panel UX improvements
+
+## Context
+
+The side panel (`sidepanel/sidepanel.js`) is a single `<textarea>` editor with debounced autosave (500ms) into IndexedDB via `shared/storage.js`. Cross-panel consistency uses a `BroadcastChannel('side-notes')`: every save posts `{type:'save', key, updatedAt}`, and any other panel showing the same key reloads `editor.value` — which resets that panel's caret to the start. Note records are plain JS objects (IndexedDB is schemaless), so adding fields needs no version bump or migration. See proposal.md for motivation.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Focus + caret/scroll restoration on every `loadNoteForTab` path (panel open, tab switch, navigation) with one code path.
+- Caret persistence that never disturbs other open panels.
+- Font-size adjustment (buttons + shortcuts) persisted in `localStorage`.
+
+**Non-Goals:**
+- Restoring selection direction or multi-range selections (collapsed caret and simple ranges only).
+- Applying the font size to the notes-list page.
+- Syncing the font-size preference across devices (localStorage is per-machine).
+
+## Decisions
+
+### 1. Caret/scroll live on the note record
+
+Store `caretStart`, `caretEnd`, `scrollTop` on the note record in IndexedDB rather than in `localStorage` keyed by note key. The position is conceptually part of the note's state, travels with the record, and avoids a second lookup store. `saveNote` gains an optional `caret` parameter; when present, the fields are written on the record; when absent, existing fields are preserved (spread of `existing` already does this on update).
+
+Alternative considered: `localStorage` map of key → position. Simpler writes, but duplicates the keying logic, can leak entries for deleted notes, and splits note state across two stores.
+
+### 2. Three write paths for the caret
+
+```
+typing ─────────► existing 500ms autosave ──► saveNote(key, content, meta, {caret, scrollTop}) + broadcast 'save'
+caret move only ─► 800ms debounced caret save ► saveNote(..., {caretOnly: true}) — no broadcast
+blur / visibilitychange(hidden) ──► flush pending caret save immediately
+```
+
+Caret-only movement is tracked via the `selectionchange` event (fires on the document when the textarea selection changes) plus `scroll` on the editor. The caret-only save calls `saveNote` with the *current* content (unchanged) and new caret fields — it reuses the existing update-in-place path, so content, timestamps, and metadata are untouched. `updatedAt` is refreshed; that is acceptable and keeps "last touched" honest.
+
+Alternative considered: writing caret fields via a dedicated storage function. Rejected — a second write path to the same record invites lost-update races with autosave; funneling both through `saveNote` serializes them naturally.
+
+### 3. Caret-only saves do not broadcast
+
+The cross-panel reload exists to propagate *content* changes. A caret-only save broadcasting `type:'save'` would make every other panel reload `editor.value` and lose its own caret — two panels would fight. So caret-only saves post nothing. As defense in depth (and fixing the latent bug where a blur-triggered reload in panel B discards B's caret even when content is identical), `reloadFromDB` compares fetched content to `editor.value` and skips the assignment when identical, updating only its local caret if unfocused.
+
+Alternative considered: a `caretOnly: true` flag on the broadcast so receivers can update their stored caret for future restores. Unnecessary — each panel persists its own caret on its own save/blur, so remote caret values are never needed live; they're read on load.
+
+### 4. Restore is part of `loadNoteForTab`, clamped
+
+After setting `editor.value`, restore via `editor.setSelectionRange(min(caretStart, len), min(caretEnd, len))` and `editor.scrollTop = savedScrollTop`, then `editor.focus()`. Focus is applied only in `loadNoteForTab` paths triggered by panel init and explicit loads — the `chrome.tabs.onActivated` handler also calls `loadNoteForTab`, but focusing there is still correct per the spec (switching tabs restores that note's caret; the panel only updates when the panel itself is focused/visible, since side panels are per-window). `autofocus` is *not* used: it only runs on first page load and can't express the caret restore.
+
+Clamping handles the case where another panel shortened the note after the caret was saved. Legacy records without caret fields default to `0`/`0`/scroll `0`.
+
+### 5. Font size: CSS variable + localStorage, buttons and shortcuts
+
+- Default 16px; range 10–24px; step 1px. Applied as `editor.style.fontSize` (inline style beats the stylesheet; line-height stays the unitless `1.6` so it scales automatically — `selectMatch`'s computed-line-height math keeps working).
+- Persisted under a single `localStorage` key (e.g. `side-notes:fontSize`), read at init before first paint of content.
+- Header gains two buttons labeled `A-` and `A+` placed before the existing `☰` button, styled like it.
+- Shortcuts handled in the existing `document` keydown listener alongside Ctrl+F: `Ctrl/Cmd+=` (also accept `Ctrl/Cmd+'+'` for shift variants), `Ctrl/Cmd+-`, `Ctrl/Cmd+0` reset — all `preventDefault()`ed. Extension pages aren't affected by browser zoom shortcuts, but preventDefault is harmless insurance.
+
+## Risks / Trade-offs
+
+- **`selectionchange` fires very often** (every arrow key) → 800ms debounce, plus the guard that a caret-only save is skipped if a content autosave is pending (the autosave will capture the caret anyway).
+- **Caret-only save resets nothing visible but does write IndexedDB frequently** → writes are tiny records on a local DB; debounce keeps this to ~1/second max while moving.
+- **Chrome may not grant focus to the panel when opened without a user gesture** → `editor.focus()` is best-effort; worst case the caret is still restored and one click focuses. Verify manually on open-via-toolbar and open-via-context-menu.
+- **Restoring `scrollTop` immediately after setting `value` can be clamped by layout timing** → if restore lands before layout, wrap the scroll assignment in `requestAnimationFrame`.
+
+## Migration Plan
+
+No data migration: IndexedDB schema is unchanged (no new indexes, no version bump); old records simply lack the caret fields and default to offset 0. Rollback is a revert — stray caret fields on records are harmless to older code (ignored on read, preserved on update via the `...existing` spread).
diff --git a/openspec/changes/sidepanel-ux-improvements/proposal.md b/openspec/changes/sidepanel-ux-improvements/proposal.md
new file mode 100644
index 0000000..2adeaee
--- /dev/null
+++ b/openspec/changes/sidepanel-ux-improvements/proposal.md
@@ -0,0 +1,31 @@
+# Proposal: Side panel UX improvements
+
+## Why
+
+Opening the side panel requires a manual click into the textarea before typing, the editor font is small (13px) with no way to adjust it, and the caret position is lost every time the panel closes or the tab switches — forcing users to scroll back to where they were.
+
+## What Changes
+
+- Focus the editor automatically when the side panel opens, restoring the caret to its last saved position (and scroll offset) instead of the top of the note.
+- Persist caret position (`selectionStart`/`selectionEnd`) and `scrollTop` on the note record, written during autosave, on a debounce after caret-only movement, and flushed on blur/panel hide. Restored positions are clamped to the current content length.
+- Prevent caret-only saves from disturbing other open panels: cross-panel reload messages distinguish content changes from caret-only updates so a remote caret save never resets another panel's caret.
+- Bump the default editor font size to 16px (already monospace) and add font-size controls (`A-` / `A+`) in the header next to the notes-list button, plus `Ctrl+=` / `Ctrl+-` keyboard shortcuts and `Ctrl+0` to reset. The chosen size persists in `localStorage` and applies across panel sessions.
+
+## Capabilities
+
+### New Capabilities
+
+(none)
+
+### Modified Capabilities
+
+- `note-editor`: new requirements for focus-on-open with caret/scroll restoration, adjustable persisted editor font size, and cross-panel reload that ignores caret-only remote updates.
+- `notes-storage`: the note record data model gains optional caret and scroll-position fields.
+
+## Impact
+
+- `sidepanel/sidepanel.js` — focus/restore logic, caret tracking, font-size controls and shortcuts, broadcast message handling.
+- `sidepanel/sidepanel.html` — `A-` / `A+` buttons in the header.
+- `sidepanel/sidepanel.css` — base font-size moved to a variable/inline style; button styles.
+- `shared/storage.js` — save path accepts and preserves caret/scroll fields; no IndexedDB schema migration needed (records are schemaless).
+- No manifest or permission changes; `localStorage` needs no permission.
diff --git a/openspec/changes/sidepanel-ux-improvements/specs/note-editor/spec.md b/openspec/changes/sidepanel-ux-improvements/specs/note-editor/spec.md
new file mode 100644
index 0000000..1377014
--- /dev/null
+++ b/openspec/changes/sidepanel-ux-improvements/specs/note-editor/spec.md
@@ -0,0 +1,69 @@
+## ADDED Requirements
+
+### Requirement: Editor focused on panel open with restored caret
+WHEN the side panel opens, the system SHALL place input focus in the note editor and restore the caret to the position last saved for that note, including the editor's scroll offset. Restoration also applies when the panel switches to a different tab's note or reloads after navigation. If the saved position exceeds the current content length (e.g., the note was edited elsewhere), it SHALL be clamped to a valid offset. Notes saved before this feature have no stored position and SHALL restore to the start of the note.
+
+#### Scenario: Panel opens with caret where the user left it
+- **WHEN** a user edits a note, moves the caret to a specific position, closes the panel, and reopens it on the same page
+- **THEN** the editor has focus and the caret is at the last saved position with the same scroll offset
+
+#### Scenario: Switching tabs restores that note's caret
+- **WHEN** a user switches to a different tab whose note has a saved caret position
+- **THEN** the panel shows the new tab's note with its own saved caret position restored
+
+#### Scenario: Saved position beyond current content is clamped
+- **WHEN** a note's content was shortened in another panel after the caret position was saved
+- **THEN** the caret is restored at the end of the current content rather than an invalid offset
+
+#### Scenario: Legacy note without a saved position
+- **WHEN** a user opens a note that was saved before caret persistence existed
+- **THEN** the editor has focus with the caret at the start of the note and no error occurs
+
+### Requirement: Caret position saved continuously
+The system SHALL save the caret position (and editor scroll offset) as part of every autosave, SHALL also persist caret-only movement (selection changes without content edits) after a short debounce, and SHALL flush any unsaved caret position when the editor loses focus or the panel is hidden.
+
+#### Scenario: Caret saved with content autosave
+- **WHEN** a user types in the editor and the autosave completes
+- **THEN** the stored note record includes the caret position and scroll offset at save time
+
+#### Scenario: Caret-only movement is persisted
+- **WHEN** a user moves the caret without typing and then closes the panel
+- **THEN** the last caret position has been persisted and is restored on the next open
+
+### Requirement: Caret-only remote saves do not disturb other panels
+WHEN the same note is open in more than one panel and a remote panel persists only a caret/scroll update (content unchanged), other panels SHALL NOT reload the editor content or move their own caret. Content-changing remote saves keep the existing refresh behavior (reload immediately, or defer until blur when the local editor is focused).
+
+#### Scenario: Remote caret save leaves local caret untouched
+- **WHEN** a note open in tab A persists a caret-only update and the same note is open in tab B
+- **THEN** tab B's editor content and caret position remain unchanged
+
+#### Scenario: Remote content save still refreshes
+- **WHEN** a note open in tab A saves changed content and the same note is open in tab B without editor focus
+- **THEN** tab B's panel updates to show the content saved from tab A
+
+### Requirement: Adjustable editor font size
+The editor SHALL render note text in a monospace font at a user-adjustable size, defaulting to 16px when no preference is stored. The size SHALL be changeable via decrease/increase controls in the panel header adjacent to the notes-list button, and via keyboard shortcuts (increase: `Ctrl+=`/`Cmd+=`, decrease: `Ctrl+-`/`Cmd+-`, reset to default: `Ctrl+0`/`Cmd+0`). The size SHALL be clamped to a bounded range (minimum 10px, maximum 24px, step 1px) and persisted in local storage so it applies to subsequent panel sessions.
+
+#### Scenario: Default size for new users
+- **WHEN** a user opens the side panel with no stored font-size preference
+- **THEN** the editor text renders at 16px in a monospace font
+
+#### Scenario: Increase and decrease via header controls
+- **WHEN** a user clicks the font-size increase control, then the decrease control
+- **THEN** the editor font size grows by one step, then returns to its previous size
+
+#### Scenario: Keyboard shortcuts adjust the size
+- **WHEN** the user presses `Ctrl+=` and later `Ctrl+-` while the panel is focused
+- **THEN** the editor font size increases by one step, then decreases by one step, and the browser's page zoom is not triggered
+
+#### Scenario: Reset shortcut restores the default
+- **WHEN** a user has changed the font size and presses `Ctrl+0`
+- **THEN** the editor font size returns to 16px
+
+#### Scenario: Size is clamped at the bounds
+- **WHEN** a user repeatedly decreases the font size below the minimum or increases it above the maximum
+- **THEN** the size stops at the bound and the control remains usable in the opposite direction
+
+#### Scenario: Size persists across sessions
+- **WHEN** a user changes the font size, closes the panel, and reopens it later
+- **THEN** the editor renders at the previously chosen size
diff --git a/openspec/changes/sidepanel-ux-improvements/specs/notes-storage/spec.md b/openspec/changes/sidepanel-ux-improvements/specs/notes-storage/spec.md
new file mode 100644
index 0000000..3085287
--- /dev/null
+++ b/openspec/changes/sidepanel-ux-improvements/specs/notes-storage/spec.md
@@ -0,0 +1,16 @@
+## MODIFIED Requirements
+
+### Requirement: Note record data model
+Each stored note record SHALL include: a stable unique identifier, the derived URL key, the page title and favicon URL captured at save time, the markdown content, a creation timestamp, a last-updated timestamp, and an optional deletion timestamp. A record MAY additionally include the editor caret position (selection start and end offsets) and the editor scroll offset, captured at save time; these fields are optional and absent on records created before caret persistence existed. Caret/scroll updates MUST NOT modify the content, timestamps, or identity of the record.
+
+#### Scenario: Metadata captured on first save
+- **WHEN** a user's edits to a page's note are saved for the first time
+- **THEN** the stored record includes a unique id, the derived key, the page's title, its favicon URL, the content, and matching creation and last-updated timestamps
+
+#### Scenario: Caret and scroll captured on save
+- **WHEN** a note is saved while the editor has a known caret position and scroll offset
+- **THEN** the stored record includes those values alongside the content
+
+#### Scenario: Caret-only update preserves other fields
+- **WHEN** a caret/scroll update is persisted without any content change
+- **THEN** the record's content, page metadata, and creation timestamp are unchanged
diff --git a/openspec/changes/sidepanel-ux-improvements/tasks.md b/openspec/changes/sidepanel-ux-improvements/tasks.md
new file mode 100644
index 0000000..ccfeb7a
--- /dev/null
+++ b/openspec/changes/sidepanel-ux-improvements/tasks.md
@@ -0,0 +1,31 @@
+# Tasks: Side panel UX improvements
+
+## 1. Storage: caret/scroll fields on the note record
+
+- [ ] 1.1 Extend `saveNote` in `shared/storage.js` with an optional caret parameter (`{ caretStart, caretEnd, scrollTop }`); when provided, write those fields onto the record (both insert and update-in-place paths); when absent, preserve existing fields
+- [ ] 1.2 Verify old records without caret fields still load and save unchanged (no IndexedDB version bump)
+
+## 2. Caret persistence in the side panel
+
+- [ ] 2.1 In `sidepanel/sidepanel.js`, pass current caret (`selectionStart`/`selectionEnd`) and `scrollTop` to `saveNote` in the existing autosave (`doSave`)
+- [ ] 2.2 Track caret-only movement via `document` `selectionchange` (filtered to the editor) and editor `scroll`; debounce ~800ms into a caret-only save that calls `saveNote` without broadcasting; skip it while a content autosave is pending
+- [ ] 2.3 Flush any pending caret-only save on editor `blur` and on `visibilitychange` → hidden
+
+## 3. Focus and caret/scroll restore
+
+- [ ] 3.1 In `loadNoteForTab`, after setting `editor.value`, restore caret via `setSelectionRange` with offsets clamped to content length (default 0 for legacy records), restore `scrollTop` (in `requestAnimationFrame` if layout timing clamps it), and call `editor.focus()`
+- [ ] 3.2 Make `reloadFromDB` skip the `editor.value` assignment when fetched content is identical, so remote saves never move the local caret unnecessarily
+- [ ] 3.3 Manually verify focus lands when the panel opens via toolbar action and via keyboard shortcut; caret restore works on panel open, tab switch, and SPA navigation
+
+## 4. Adjustable font size
+
+- [ ] 4.1 Add `A-` and `A+` buttons to the header in `sidepanel/sidepanel.html` before the `☰` button; style them like `#open-list` in `sidepanel/sidepanel.css`
+- [ ] 4.2 In `sidepanel/sidepanel.js`, implement font-size state: default 16px, range 10–24px, step 1px; apply via `editor.style.fontSize`; load from `localStorage` (`side-notes:fontSize`) at init and persist on every change
+- [ ] 4.3 Wire the two buttons to decrease/increase with clamping
+- [ ] 4.4 Add keyboard shortcuts in the existing keydown handler: `Ctrl/Cmd+=` (and `+` variant) increase, `Ctrl/Cmd+-` decrease, `Ctrl/Cmd+0` reset to 16px, all with `preventDefault()`
+- [ ] 4.5 Verify the find match scrolling (`selectMatch`) still scrolls correctly at min and max font sizes
+
+## 5. Validation
+
+- [ ] 5.1 Load the unpacked extension and walk every scenario in `specs/note-editor/spec.md` and `specs/notes-storage/spec.md`
+- [ ] 5.2 Two-panel test: same note in two tabs — caret-only movement in A does not disturb B's caret; content edit in A still refreshes B (immediately when unfocused, deferred until blur when focused)