Add browser storage persistence for GramFrame annotations

[IanMayo]

Summary

Implements automatic persistence of user annotations (analysis markers, harmonic sets, doppler curves) in browser storage, with context-aware storage selection (localStorage for trainers, sessionStorage for students) and a "Clear gram" button for trainer pages.

Key Changes

• Storage Module (src/core/storage.js): New adapter module providing context detection, key generation, save/load/clear operations, schema versioning (v1), and graceful degradation with try/catch wrapping all Web Storage calls

  • detectUserContext(): Identifies trainer pages by presence of anchor with exact text "ANALYSIS"
  • getStorage(): Returns appropriate Storage object (localStorage/sessionStorage) with availability probing
  • saveAnnotations(): Persists annotation state only when data exists; removes empty entries
  • loadAnnotations(): Validates schema version and discards incompatible data
  • clearAnnotations(): Removes stored data for current page

• GramFrame Integration (src/main.js):

  • Detects user context and calculates storage instance index during construction
  • Restores saved annotations before first state notification
  • Registers state listener that saves annotations on relevant state changes (with deduplication)
  • Adds "Clear gram" button to trainer pages only
  • _clearGram(): Resets all annotation state and storage, re-renders UI

• Type Definitions (src/types.js): Added JSDoc typedefs for StoredAnnotations, StoredAnalysisData, StoredMarker, StoredHarmonicsData, StoredHarmonicSet, and StoredDopplerData

• Styling (src/gramframe.css): Added .gram-frame-clear-btn with gradient background, hover/active states, and responsive styling

• Test Fixtures: Created trainer-page.html and student-page.html for integration testing

• Test Suite (tests/storage.spec.js): Comprehensive Playwright tests covering:

  • US1: Trainer annotations persist across page reloads (analysis markers, harmonic sets, doppler curves)
  • US2: Student annotations persist within session only
  • US3: Clear gram button removes annotations from display and storage
  • Edge cases: graceful degradation when storage unavailable, schema version validation, lazy storage initialization

• Test Helpers (tests/helpers/gram-frame-page.js): Added storage utility methods (clearStorage(), getStorageEntry(), setStorageEntry(), getStorageKeys())

Notable Implementation Details

• Multi-instance support: Storage keys include instance index to support multiple GramFrame instances on the same page
• Lazy initialization: Storage entries only created when first annotation is added; empty state removes entries
• Schema versioning: Unrecognized schema versions are discarded with console warning
• Deduplication: State listener compares serialized annotation snapshots to avoid redundant writes
• Silent restoration: Annotations restored without prompts or dialogs
• Graceful degradation: All storage operations wrapped in try/catch; component continues functioning if storage unavailable

https://claude.ai/code/session_01Gb6npXwykVzbvHBZUgmYty

[netlify]

✅ Deploy Preview for gramframe ready!

Name	Link
🔨 Latest commit	cc31846
🔍 Latest deploy log	https://app.netlify.com/projects/gramframe/deploys/69c66bddb906a50007d9eac8
😎 Deploy Preview	https://deploy-preview-164--gramframe.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[github-actions]

PR Preview

Preview deployment is ready! View Preview

Last updated: 2026-03-27T11:37:22.951Z