commenting feature

[frankdilo]

• select some text
• comment it
• the comment gets added as an html comment in the markdown file (so the renderer does not pick it up), but it is persisted
• comments should have a visible ID that you can reference (like COM-1/2/3)
• comments should be editalbe in the UI and deletable
• comments should persist and show a timestamp of when they were made

IDEA: so you can ask agents to iterate on comments that are already in the file

[frankdilo]

Summary of attempts

Approach A (native UI / SwiftUI popover)

• Implemented comment markers in the markdown (MV-COMMENT-START/END with JSON payload), highlight spans in the WebView, and a native SwiftUI popover editor triggered from selection or highlight clicks.
• Tried moving the toolbar button into the title bar, but ran into UX issues (active state mismatch) and even a crash on launch after one change. We stabilized the crash, but the UX still felt off.
• Key pain points: keeping WebView selection state in sync with native popover geometry, popover dismissal timing, and fragile handling of highlight/selection when the DOM is reloaded.

Approach B (all-in-HTML UI with React via CDN)

• Replaced the native popover with an HTML/React overlay (selection bubble + inline editor) rendered in the WebView, sending add/update/delete messages back to Swift.
• Still saw issues: clicking highlights did not reliably open the editor, and adding a comment sometimes made previous comments disappear. The comment UI also had to work around DOM-wrapping/highlight logic and selection offsets.
• Key pain points: mapping selection offsets back into UTF-8 source offsets, maintaining stable anchors while the markdown is edited externally, and DOM mutation (wrapping highlight spans) causing event/selection edge cases.

Inherent complexities

• Anchoring comments to markdown text is fragile: offsets shift as markdown changes, especially with front matter and HTML comment markers inserted.
• The renderer uses source range mapping with UTF-8 offsets; any mismatch between DOM text and source positions (e.g., inline HTML, code blocks, link text) can break selection mapping.
• Highlights are applied by wrapping DOM ranges between HTML comment markers, which mutates the DOM and can invalidate selections or event targets.
• Keeping state in sync across Swift, WebView JS, and file writes is tricky when the file can be edited externally.

Both approaches are currently not meeting the UX/robustness bar.

[frankdilo]

Moved commit 5f474be to a branch for the refactor.

Branch: https://github.com/frankdilo/MarkdownViewer/tree/refactor/app-modules

[frankdilo]

Moved commit b23c614 off main and parked it on a branch.

Branch (commit b23c614):
https://github.com/frankdilo/MarkdownViewer/tree/comment-ui-checkpoint