helldots 0.4.0 → 0.6.0

package/README.md

@@ -73,12 +73,34 @@ export function Comments({ user }) {
 }
 ```
 
+### Single-page apps
+
+A client-side router swaps the DOM without a page load, so tell the widget
+when a navigation happened and let its own cross-page jumps use your router:
+
+```js
+const overlay = createCommentOverlay({
+  user,
+  persistence: "localStorage",
+  navigate: (page) => router.push(page), // "view on its page" without a reload
+});
+
+// After every route render (React Router, Vue Router, …)
+router.afterEach(() => overlay.notifyNavigation());
+```
+
+`notifyNavigation()` reclassifies every comment against the new URL,
+re-resolves anchors against the new DOM and rebuilds the markers. Calling it
+after a same-path re-render is also the way to re-anchor when your app
+replaced the route's DOM. `autoDetectNavigation: true` additionally covers
+back/forward (popstate) automatically.
+
 ## What gets captured
 
 When someone leaves a comment, HellDots records more than the text:
 
 **A screenshot of the page as they saw it.** Taken automatically, JPEG at half
-scale (~30–100 KB). The widget's own UI is hidden during the capture, so the
+scale (~30–100 KB). The widget's own UI is excluded from the capture, so the
 toolbar never ends up inside the image. Dragging a region additionally attaches
 a full-resolution PNG crop of exactly what was selected.
 
@@ -94,6 +116,84 @@ orphaned rather than silently dropped.
 Set `autoScreenshot: false` to skip the capture — the render costs a moment
 on every comment, and some apps would rather not pay it.
 
+### Web fonts in screenshots
+
+A screenshot is not a screen grab: the browser exposes no way to rasterize
+the painted page from JavaScript, so the capture is a re-render of the DOM.
+Anything the re-render cannot reach is missing from it — web fonts included.
+
+A font loaded through a cross-origin `<link>` (Google Fonts and friends) is
+one of those. Reading `cssRules` on such a stylesheet throws `SecurityError`,
+so its `@font-face` never reaches the capture and the text comes out in a
+fallback face. That is not only cosmetic: the fallback's metrics differ, so
+glyphs sit at different positions than on screen, and a drag selection tight
+around a few letters can come back holding the wrong ones.
+
+Three ways out, cheapest first:
+
+- **Self-host the font**, or add `crossorigin` to the `<link>`. The
+  stylesheet becomes readable and the capture matches the page, with no
+  extra requests at capture time.
+- **`embedCrossOriginFonts: true`.** HellDots re-fetches those stylesheets
+  (the same URLs the page already loaded, cached per session) and hands them
+  to the renderer. Off by default: a comment widget making third-party
+  requests on your users' behalf should be your call, not ours.
+- **Leave it.** Captures of such a page stay misaligned where text is
+  concerned; everything else about them is correct.
+
+## Identity
+
+HellDots authenticates nobody. It takes whoever your app says is signed in
+and records that:
+
+```js
+createCommentOverlay({
+  user: { name: currentUser.fullName, id: currentUser.id },
+});
+```
+
+`name` is the display name — it is what appears on every comment and reply.
+`id` is optional, never rendered, and persisted as `authorId` on everything
+that user creates. Pass it whenever two people on your team can share a
+display name: without it they are indistinguishable in the record, and they
+share one reaction.
+
+```js
+overlay.serializeComments()[0];
+// { author: "Ana Pérez", authorId: "u_42", ... }
+```
+
+Both fields ride along in `serializeComments()` output, on comments and on
+replies alike. **The display name travels with the record**, so a store that
+holds nothing but comments — a database of its own, with no users table —
+renders every author and every audit entry without a single lookup back into
+your app. The id is opaque to HellDots: point it at your user table, at a
+comments-only store, or at nothing. `authorId` is `null` when you pass no
+`id`, and on records written before it existed — the field is additive, so no
+stored corpus needs migrating.
+
+What the denormalised name costs: a rename does not travel backwards. Old
+comments keep the name that was current when they were written, which is what
+an audit trail should do, and the id is what lets you reconcile if you want
+the current one.
+
+With no `id` at all, two people sharing a display name are one author. If your
+app has no accounts, mint the id yourself — you control the key, the lifetime
+and the consent story, which HellDots cannot:
+
+```js
+const KEY = "my-app-anon-id";
+let id = localStorage.getItem(KEY);
+if (!id) localStorage.setItem(KEY, (id = crypto.randomUUID()));
+createCommentOverlay({ user: { name: typedName, id } });
+```
+
+Bear in mind what that identifies: a browser profile, not a person.
+
+Whatever you declare here is taken at face value and stored as-is. The record
+says what your application asserted about who acted; verifying that claim is
+your backend’s job, and `onChange` carries every mutation to it.
+
 ## Triage
 
 Comments carry an optional type, priority and free-form tags. All three start
@@ -104,6 +204,12 @@ neutral: the person reporting can classify, or not.
 | `type`     | `bug`, `suggestion`, `question`, `improvement`, or `null` |
 | `priority` | `high`, `medium`, `low`, or `null`                        |
 | `tags`     | any strings — trimmed, lowercased and de-duplicated       |
+| `status`   | `open`, `in_progress`, `in_review`, `resolved`            |
+
+The status is the one field that is never neutral: every comment starts `open`
+and moves through the lifecycle in any order. `open` is the only state painted
+in an unsaturated off-white, so the three states somebody actually moved a
+comment into are the ones that stand out.
 
 The inbox filters on all of them, combined with page and status. Resolved
 comments show how long they took, measured from creation to resolution.
@@ -118,6 +224,129 @@ overlay.setCommentStatus(id, "resolved"); // stamps the resolution time
 Passing `null` to `setCommentType` or `setCommentPriority` returns the field to
 its neutral state. Reopening a resolved comment clears its resolution time.
 
+### Reactions
+
+Comments and replies take one of six reactions — 👍 👎 ❤️ 🎉 👀 🚀 — so a team
+can agree, flag "watching this" or mark something shipped without adding a
+reply. The set is fixed: a searchable picker would need an emoji dataset
+larger than the whole widget.
+
+The emoji button in a comment's action strip (or on a reply's meta line) is
+where a reaction starts. Once there is one, a row of pills sits under the
+comment — below its screenshot when it has one — and carries its own button for
+adding another. Nothing is shown there until somebody reacts.
+
+```js
+overlay.toggleCommentReaction(id, "👍");
+overlay.toggleReplyReaction(commentId, replyId, "🎉");
+```
+
+Both toggle: reacting again with the same emoji removes it. A reaction is
+stored against `user.id` when you pass one, and against `user.name`
+otherwise — so give HellDots an `id` if two people on your team can share a
+display name:
+
+```js
+createCommentOverlay({ user: { name: currentUser.name, id: currentUser.id } });
+```
+
+Reactions ride along in `serializeComments()` output as `reactions`, an
+`{ emoji: actorKey[] }` map that is `null` when nobody has reacted. The pills
+show counts, never who reacted: the stored keys are your ids, and they stay
+out of the UI.
+
+### Audit trail
+
+Every comment carries an append-only log of what happened to it — who created
+it, edited its text, moved its status or changed its classification, and when.
+It shows up as a folded `History (n)` disclosure in the inbox detail, next to
+the context block.
+
+```js
+overlay.serializeComments()[0].history;
+// [
+//   { type: "created",  at: "…", actor: { id: "u_42", name: "Ana Pérez" } },
+//   { type: "status",   at: "…", actor: {…}, from: "open", to: "resolved" },
+//   { type: "classified", at: "…", actor: {…}, field: "type", from: null, to: "bug" },
+// ]
+```
+
+Replies and reactions are deliberately **not** in it. A reply already carries
+its own author and timestamp and is visible in the thread; reactions are
+high-frequency signal with no audit value. That bound is what keeps the log at
+three to five entries per comment — a hundred comments’ worth of history costs
+about what two automatic screenshots cost.
+
+Resolution time is derived from this log rather than stored beside it, so a
+comment that was resolved, reopened and resolved again reports the duration of
+the resolution currently in force, and the superseded ones are listed under
+**Previous resolutions** in the same disclosure.
+
+Two things worth knowing before you rely on it:
+
+- **It is attributive, not evidential.** HellDots authenticates nobody. The log
+  records the `user` your app declared at the moment of the action, so it says
+  what your application asserted about who acted — not a verified fact. Verify
+  on your own backend if you need the stronger claim; `onChange` carries every
+  mutation to it.
+- **Timestamps come from the acting client’s clock.** Merge corpora written on
+  machines whose clocks disagree and an entry can predate the comment it
+  belongs to. Durations are clamped at zero rather than rendered negative.
+
+A corpus written before the log existed loads unchanged with `history: null`,
+and its comments render no disclosure — additive, so nothing needs migrating.
+
+## Metrics and reports
+
+The inbox header carries a **Metrics** button. It swaps the list for a
+dashboard: totals, how many were resolved and how many came back, average and
+median resolution time, bars per status, type and priority, and a daily
+distribution. Each bar carries the colour its own picker uses, so a chip and
+its bar read as the same thing.
+
+The dashboard measures **what the panel is currently filtered to** — the
+filter summary sits right above the figures, so they answer "what am I looking
+at". For the unfiltered aggregate, ask the overlay:
+
+```js
+overlay.getMetrics();
+// {
+//   total: 42,
+//   byStatus:   { open: 12, in_progress: 4, in_review: 2, resolved: 24 },
+//   byType:     { bug: 18, suggestion: 9, question: 3, improvement: 4, unset: 8 },
+//   byPriority: { high: 7, medium: 15, low: 6, unset: 14 },
+//   overTime:   [{ date: "2026-08-18", count: 5 }, …],
+//   resolution: { resolvedCount: 24, reopenedCount: 3,
+//                 averageMs: 9000000, medianMs: 5400000 },
+// }
+```
+
+Every bucket is present even when empty, so you can index it without guarding.
+`overTime` lists only the days that saw activity — filling the gaps would put
+a year of empty buckets between two comments twelve months apart.
+
+### Exporting
+
+Three buttons at the foot of the dashboard, and the same three as methods:
+
+```js
+overlay.exportCommentsCsv(); // helldots-comments.csv — one row per comment
+overlay.exportMetricsCsv(); // helldots-metrics.csv  — section, key, value
+overlay.printMetricsReport(); // the browser's print dialog → Save as PDF
+```
+
+The CSVs are RFC 4180 with a UTF-8 BOM, so Excel opens them without turning
+every accent into mojibake, and a value that would otherwise be evaluated as a
+formula is neutralised on the way out. Headers are the internal field names
+rather than translated labels: the file is an interchange format, and a column
+whose spelling follows the widget's locale cannot be joined against anything.
+Screenshots stay out — a 33 KB base64 string in a spreadsheet cell is not data.
+
+The PDF is the browser's. HellDots builds the report in its own document and
+asks that document to print, so "Save as PDF" in the dialog gives you a real
+one at no cost in bundle size — the lightest PDF library measured 133 KB gzip
+against a 50 KB budget. What prints is the report, not the page behind it.
+
 ## Handing a comment to a coding agent
 
 Every comment has a **copy** button that puts a plain-text context block on the
@@ -145,26 +374,54 @@ OS: iOS 17.2
 
 ## Options
 
-| Option             | Type                             | Default          |                                                           |
-| ------------------ | -------------------------------- | ---------------- | --------------------------------------------------------- |
-| `user`             | `{ name: string }`               | `"Anonymous"`    | Author of new comments and replies                        |
-| `persistence`      | `"localStorage"` \| `"none"`     | `"none"`         | Auto save/restore, or handle it yourself via callbacks    |
-| `autoScreenshot`   | `boolean`                        | `true`           | Capture a screenshot and environment snapshot per comment |
-| `locale`           | `"en"` \| `"es"`                 | browser language | UI language, falling back to English                      |
-| `shortcutKey`      | `string`                         | `"c"`            | Key that toggles comment mode                             |
-| `shortcutModifier` | `"alt"` \| `"ctrl"` \| `"shift"` | `"alt"`          | Modifier for that key                                     |
-| `autoInit`         | `boolean`                        | `true`           | When `false`, returns an initializer to call yourself     |
+| Option                  | Type                             | Default             |                                                                   |
+| ----------------------- | -------------------------------- | ------------------- | ----------------------------------------------------------------- |
+| `user`                  | `{ name: string, id?: string }`  | `"Anonymous"`       | Author of new comments and replies; `id` persists as `authorId`   |
+| `persistence`           | `"localStorage"` \| `"none"`     | `"none"`            | Auto save/restore, or handle it yourself via callbacks            |
+| `autoScreenshot`        | `boolean`                        | `true`              | Capture a screenshot and environment snapshot per comment         |
+| `embedCrossOriginFonts` | `boolean`                        | `false`             | Fetch unreadable stylesheets so their web fonts reach the capture |
+| `locale`                | `string`                         | browser language    | `"en"` and `"es"` ship; anything else falls back per key          |
+| `linkParam`             | `string`                         | `"helldotsComment"` | Query param used by "Copy link" URLs                              |
+| `navigate`              | `(page: string) => void`         | full page load      | SPA router hook for the widget's cross-page jumps                 |
+| `autoDetectNavigation`  | `boolean`                        | `false`             | Run `notifyNavigation()` on popstate (back/forward)               |
+| `shortcutKey`           | `string`                         | `"c"`               | Key that toggles comment mode                                     |
+| `shortcutModifier`      | `"alt"` \| `"ctrl"` \| `"shift"` | `"alt"`             | Modifier for that key                                             |
+| `autoInit`              | `boolean`                        | `true`              | When `false`, returns an initializer to call yourself             |
 
 ### Callbacks
 
-| Callback                          | Fires when                                         |
-| --------------------------------- | -------------------------------------------------- |
-| `onCommentCreated(comment)`       | A new comment is saved                             |
-| `onReplyAdded(comment, reply)`    | A reply is added to any comment                    |
-| `onCommentStatusChanged(comment)` | Status moves between open / in progress / resolved |
-| `onCommentUpdated(comment)`       | Type, priority or tags change                      |
-| `onCommentDeleted(id)`            | A comment is removed                               |
-| `onAnchorLost(comment)`           | A comment could not be re-anchored on load         |
+Every change is also available as one stream, which is usually what you want
+when the whole thing syncs to a single endpoint:
+
+```js
+createCommentOverlay({
+  onChange: (event) => {
+    // "comment:created" | "comment:edited" | "comment:deleted"
+    // "comment:status-changed" | "comment:updated" | "comment:anchor-lost"
+    // "reply:added" | "reply:deleted" | "reply:edited"
+    // "reaction:toggled"
+    api.post("/helldots-events", event);
+  },
+});
+```
+
+`ChangeEvent` is a discriminated union: switch on `event.type` and
+TypeScript narrows the payload. The specific callbacks below carry the same
+events at the same moments — subscribe either way, or both. A handler that
+throws is caught and warned about, never rolling back the change.
+
+| Callback                            | Fires when                                                     |
+| ----------------------------------- | -------------------------------------------------------------- |
+| `onCommentCreated(comment)`         | A new comment is saved                                         |
+| `onReplyAdded(comment, reply)`      | A reply is added to any comment                                |
+| `onReplyDeleted(comment, reply)`    | A reply is removed                                             |
+| `onCommentEdited(comment)`          | A comment's text is rewritten                                  |
+| `onReplyEdited(comment, reply)`     | A reply's text is rewritten                                    |
+| `onCommentStatusChanged(comment)`   | Status moves along the lifecycle                               |
+| `onCommentUpdated(comment)`         | Type, priority or tags change                                  |
+| `onCommentDeleted(id)`              | A comment is removed                                           |
+| `onAnchorLost(comment)`             | A comment could not be re-anchored on load                     |
+| `onReactionToggled(comment, reply)` | A reaction is added or removed (`reply` is `null` at the root) |
 
 ## API
 
@@ -174,19 +431,29 @@ const overlay = createCommentOverlay(options);
 overlay.comments; // Comment[]
 overlay.commentMode; // boolean
 overlay.toggleCommentMode();
-overlay.addReply(comment, text); // → CommentReply
+overlay.addReply(commentOrId, text, screenshots?); // → CommentReply | null
+overlay.deleteReply(commentId, replyId); // → boolean
+overlay.editComment(id, text); // → boolean
+overlay.editReply(commentId, replyId, text); // → boolean
+overlay.commentLink(id); // → string | null (shareable URL)
 overlay.serializeComments(); // → SerializedComment[]
 overlay.loadComments(data); // → { anchored, orphaned, inactive }
+overlay.notifyNavigation(); // re-sync after a client-side navigation
+overlay.clearComments(); // bulk reset, fires no callbacks
 overlay.deleteComment(id); // → boolean
 overlay.setCommentStatus(id, status); // → boolean
 overlay.setCommentType(id, type); // → boolean
 overlay.setCommentPriority(id, priority); // → boolean
 overlay.setCommentTags(id, tags); // → boolean
+overlay.toggleCommentReaction(id, emoji); // → boolean
+overlay.toggleReplyReaction(commentId, replyId, emoji); // → boolean
 overlay.cleanup(); // remove the widget entirely
 ```
 
 The setters return `false` for an unknown id or an invalid value, and make no
-change when they do.
+change when they do. To reconcile against a backend after remote deletions,
+call `clearComments()` and then `loadComments(freshData)` — `loadComments`
+alone replaces by id but never removes.
 
 TypeScript definitions ship with the package — no `@types` install needed.
 
@@ -196,6 +463,13 @@ With `persistence: "localStorage"`, every comment (screenshot included) lives
 under a single key shared across all pages of your app. Browsers cap that at
 roughly 5 MB, which is on the order of a hundred comments with screenshots.
 
+The mode assumes one active tab per page: writes from another tab are
+preserved on the next sync, but two tabs editing the same comment
+concurrently resolve last-write-wins, and a comment deleted in one tab can
+reappear if another tab still holding it in memory saves afterwards. Hosts
+that need real multi-tab editing should persist through the callbacks
+instead.
+
 When the quota is reached, HellDots sheds the _automatic_ screenshots of the
 oldest comments and retries, so the comments themselves survive. Screenshots a
 user deliberately attached are never discarded. If you expect heavy use, wire
@@ -209,8 +483,8 @@ page's CSS cannot leak into it and its styles cannot leak out.
 ## ESM only
 
 This package ships ES modules only. `import` works everywhere — bundlers, Vite,
-Next.js, native `<script type="module">`. There is no CommonJS build, so
-`require("helldots")` will not work.
+Next.js, Node ≥ 18, native `<script type="module">`. There is no CommonJS
+build, so `require("helldots")` will not work.
 
 For a plain `<script>` tag with no bundler, a self-contained UMD build is on
 the CDN: