helldots 0.5.0 → 0.6.0

package/README.md

@@ -141,6 +141,59 @@ Three ways out, cheapest first:
 - **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
@@ -151,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.
@@ -165,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
@@ -194,7 +376,7 @@ OS: iOS 17.2
 
 | Option                  | Type                             | Default             |                                                                   |
 | ----------------------- | -------------------------------- | ------------------- | ----------------------------------------------------------------- |
-| `user`                  | `{ name: string }`               | `"Anonymous"`       | Author of new comments and replies                                |
+| `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 |
@@ -217,6 +399,7 @@ createCommentOverlay({
     // "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);
   },
 });
@@ -227,17 +410,18 @@ 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 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         |
+| 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
 
@@ -261,6 +445,8 @@ 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
 ```