Store user contributions in browser-storage

[IanMayo]

Here's the initial description of the problem:

• analyst has added cursors to a gram image, and wishes to check they're valid
• analyst clicks on Analysis link, which takes browser to analysis page
• analyst goes back to the gram page, and their cursors have been lost (page refresh)

Initial answer is to teach user how to open link in new tab, and offer to modify script to generate links that always open analysis table in new popup tab.

Longer answer is to offer to store user contributions (cursors, harmonics, dopplers) in the browser. This was seen as beneficial, since once trainer has annotated a gram, the annotations will still be there next time they open the gram. They would be stored as a JSON array of entries, in a browser storage slot that has the current page as index.

This capability would require a Clear gram button, which would clear the stored annotations for this page.

Hmm, but what about students using a PC that was used by a student on a previous course? We wouldn't like them to see the cursors/harmonics/doppler for the previous user.

This would require a Clear all button (if that's possible, since we're not on the exact same web page - though we are at the same (file-based) TLD).

Or, we set these cookies to expire, after, say 2 weeks (length of time to be discussed with analyst).

[IanMayo]

Issue #159 — Store User Contributions in Browser Storage

Proposed Solution

After discussion, here is a design that covers both identified user scenarios without requiring any changes to the DITA publishing pipeline.

---

User Scenarios

User	Problem	Storage
Trainer	Adds annotations, navigates to Analysis page, goes back — loses work	localStorage (permanent, dedicated PC)
Student	Adds cursors, navigates to help page, goes back — loses work	sessionStorage (survives navigation, auto-clears on browser close)

---

Distinguishing Trainer from Student

Trainer pages already contain an anchor with the exact text ANALYSIS (controlled by the DITA audience="-trainee" filter). This is used as the discriminator — no new configuration required:

const isTrainer = [...document.querySelectorAll('a')]
  .some(a => a.textContent.trim() === 'ANALYSIS')

const storage = isTrainer ? localStorage : sessionStorage

This is robust and decoupled from URL structure. It must be clearly documented in the codebase so future maintainers understand the intent.

---

Storage Schema

Key:   "gramframe::/path/to/gram1.html"
Value: {
  "version": 1,
  "cursors": [...],
  "harmonics": [...],
  "dopplers": [...],
  "savedAt": "2026-03-27T10:00:00Z"
}

• The gramframe:: prefix avoids collisions with other storage consumers
• window.location.pathname is used as the key suffix — stable for file:// based deployments
• version enables safe schema migration: if version is absent or mismatched on load, discard stored data and log a console warning
• savedAt is retained for debugging purposes

---

Load Behaviour

• Stored annotations are silently restored — no prompt
• Write to storage on every annotation change
• Student shared-PC risk is eliminated automatically — sessionStorage dies with the browser

---

Clear Gram Button

• Rendered on trainer pages only (same ANALYSIS link detection)
• Clears immediately — no confirmation dialog
• Deletes the localStorage entry for the current page and resets component state

---

What This Does NOT Need

• TTL expiry
• "Clear All" button
• Any changes to DITA source or OxygenXML publishing config