helldots 0.6.0 → 0.8.0

package/README.md

@@ -53,6 +53,51 @@ overlay.loadComments(stored);
 Every comment is plain JSON — pass `serializeComments()` output straight to
 your API and hand it back to `loadComments()` later.
 
+`loadComments()` is safe to call at any point: made before the widget has
+mounted, the data is held and applied at mount — though the counts come back
+as zeroes, because nothing has been resolved against the DOM yet. Use
+`onReady` when you want them:
+
+```js
+createCommentOverlay({
+  onReady: async (overlay) => {
+    const { orphaned } = overlay.loadComments(await api.get("/comments"));
+    if (orphaned) console.info(`${orphaned} comments lost their element`);
+  },
+});
+```
+
+### Loading only the comment in a link
+
+A corpus too big to ship on every page load can be fetched per page — but
+then a shared "Copy link" URL points at a comment that is not in the set.
+`onCommentRequested` fires for exactly that case, once per id:
+
+```js
+const overlay = createCommentOverlay({
+  onCommentRequested: async (id) => {
+    overlay.loadComments([await api.get(`/comments/${id}`)]);
+  },
+});
+
+overlay.loadComments(await api.get(`/comments?page=${location.pathname}`));
+```
+
+Return a promise and the link is retried once it settles — the inbox opens on
+the comment as soon as it lands. Until then it says the comment was not
+found, rather than doing nothing.
+
+To read the id yourself before any of this exists — to fetch that one comment
+and nothing else — the package exports the reader the widget uses, so the
+parameter name never has to be written twice:
+
+```js
+import { readCommentLinkParam, DEFAULT_LINK_PARAM } from "helldots";
+
+const id = readCommentLinkParam(); // defaults to DEFAULT_LINK_PARAM
+const only = id ? [await api.get(`/comments/${id}`)] : [];
+```
+
 ### Server-rendered apps
 
 Importing the package on the server is safe — nothing touches the DOM at
@@ -141,6 +186,137 @@ Three ways out, cheapest first:
 - **Leave it.** Captures of such a page stay misaligned where text is
   concerned; everything else about them is correct.
 
+### When a capture is slow
+
+A screenshot is not a screenshot. The browser does not hand that to
+JavaScript, so the renderer re-creates the page instead: it clones the DOM,
+reads every element's computed style, inlines all of it, serialises the
+result into an SVG `<foreignObject>` and rasterises that.
+
+Reading the styles is the render. A browser exposes around 527 computed
+properties per element, and the renderer reads all of them — on a page with
+a few thousand live nodes that is hundreds of thousands of property reads,
+and it is ~91% of the cost. Two things follow, in this order:
+
+- **Nothing waits for it.** Clicking or dragging places the marker and opens
+  the comment box immediately; the render runs behind it and the images drop
+  in when they land. A dragged region shows a "Capturing…" slot in the
+  attachment strip until its crop arrives, and Send waits for it if you get
+  there first. This is always on; there is nothing to configure.
+- **The page no longer freezes while it happens.** The capture hands the
+  main thread back to the browser every 8 ms, so the page keeps painting and
+  accepting keystrokes even on a render that runs for a second. Also always
+  on — and it is what makes the point above worth anything, since a box you
+  can see but cannot type into is not much better than no box.
+- **`fastCapture: true`** narrows those reads to a curated list of the
+  properties that change a pixel — measured at ~2.7x off that phase on a
+  12 000-element page, and pixel-identical to a full capture on the pages it
+  was verified against.
+
+`fastCapture` is off by default because the list is a fidelity contract, and
+no list is provably complete for a page this library has never seen: a
+property it does not name is simply absent from the image. Turn it on for a
+heavy page, look at one capture before trusting it, and open an issue if
+something comes out wrong — the fix is one more entry in the list.
+
+There is a third lever if your page embeds same-origin iframes.
+**`skipIframeContent: true`** renders them blank instead of cloning what is
+inside. An iframe's cost is invisible from the outside — the renderer walks
+into the frame and clones its whole document, so a page that reports 242
+elements can be a capture of 9 245. Measured at 2374 ms against 82 ms on one
+9 000-node embedded frame.
+
+The `<iframe>` element itself is kept: its box, its border, the space it
+occupies. That matters more than it sounds — removing the element instead
+would slide everything below it up by the frame's height while the crop is
+still taken at live page coordinates, which puts the bottom of every capture
+out of register.
+
+A cross-origin frame has nothing to gain here. The renderer cannot read into
+it, so it is already blank in the output, and contrary to a common guess it
+does not stall or wait on one either.
+
+What none of them touches is rasterisation, which is a single browser
+operation with no JavaScript inside it. On a very long page that stays a
+few hundred milliseconds of unavoidable work.
+
+### When one dead asset holds a capture up
+
+To inline the page's images and fonts the renderer re-fetches them, and gives
+each one 30 seconds before giving up. A URL that never answers stalls the
+capture until that fires. The capture still succeeds — that asset becomes a
+transparent placeholder — but it waits first.
+
+The wait is bounded rather than multiplied: one dead asset and ten cost the
+same, because they are waited on concurrently. What it is not is one times the
+timeout. The setting drives two waits in sequence on the same asset — first
+for the image already on the page to finish loading, then for the fetch that
+inlines it — so the real cost is a consistent ~2x. The 30 second default is
+therefore about a minute.
+
+**`captureTimeout: 5000`** cuts that to roughly ten seconds. It is left at
+the default because lowering it trades a slow capture for a silently
+incomplete one: an asset that was only slow, rather than dead, gets dropped
+and leaves a hole with nothing to say so. Since these are assets your page
+has already loaded, most come from cache instantly and the tail is exactly
+the large or uncached ones you would be wrong to drop. Set it if you have
+measured your own page and decided which way you would rather it failed.
+
+### Very long pages
+
+Browsers cap how large a canvas can be — 65 535 pixels in a dimension in
+Chromium, less in Firefox, and a separate and much lower area cap on mobile
+Safari. A page past that cap cannot be rendered at full scale, so HellDots
+fits the scale to what the browser will actually paint and checks that the
+result holds pixels before using it.
+
+Nothing below the cap changes. Past it the capture goes soft in proportion:
+a 68 000px page renders at 0.96, a 140 000px page at 0.47. If even the
+smallest attempt comes back empty, the capture fails through `onError`
+rather than attaching a blank image.
+
+### Keeping screenshots out of your database
+
+Every image is stored as a base64 data URL inside the record — around 33 KB
+for the automatic capture alone. That is the first thing shed when
+localStorage hits its quota, and in your own backend it means a 33 KB string
+per comment in whatever column holds the JSON.
+
+`transformScreenshot` is where you swap it for a URL:
+
+```js
+createCommentOverlay({
+  transformScreenshot: async (dataUrl, { kind, commentId }) => {
+    const blob = await (await fetch(dataUrl)).blob();
+    const { url } = await api.upload(blob, { kind, commentId });
+    return url; // stored in place of the data URL
+  },
+});
+```
+
+It runs for every image the widget acquires: the automatic capture
+(`kind: "context"`), a drag-crop region, and anything attached through the
+file picker on a comment or a reply (`kind: "attachment"`). The two kinds
+exist so the disposable one and the deliberate one can go to different
+buckets.
+
+**It runs at two different moments, and `kind` does not tell them apart.**
+Everything on a comment transforms when the comment is saved; an attachment
+on a _reply_ transforms when the file is picked, because `addReply()` is
+synchronous and cannot wait on your upload. So a reply attachment can be
+uploaded and then never referenced — the user closes the popover without
+sending — and a comment can do the same in a narrower window, by being
+dismissed while its upload is still in flight. Sweep for unreferenced blobs;
+a URL you were handed is not a promise that a record will point at it.
+
+It is **fail-open**. If your upload rejects — or resolves to anything that is
+not a non-empty string — the original data URL is kept and you get
+`onError(error, "transform")`. You receive a large record rather than losing
+somebody's comment.
+
+Not called for records you pass to `loadComments()`, nor for screenshots you
+hand to `addReply()` yourself: in both cases the strings are already yours.
+
 ## Identity
 
 HellDots authenticates nobody. It takes whoever your app says is signed in
@@ -335,6 +511,14 @@ overlay.exportMetricsCsv(); // helldots-metrics.csv  — section, key, value
 overlay.printMetricsReport(); // the browser's print dialog → Save as PDF
 ```
 
+Both CSV methods **return the same text they download**, so a host that wanted
+to send those rows somewhere instead of handing the user a file does not have
+to build them a second time:
+
+```js
+await api.post("/reports/comments", { csv: overlay.exportCommentsCsv() });
+```
+
 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
@@ -374,19 +558,28 @@ OS: iOS 17.2
 
 ## Options
 
-| 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             |
+| 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 |
+| `fastCapture`           | `boolean`                            | `false`             | Read a curated style list instead of all ~527 computed properties |
+| `skipIframeContent`     | `boolean`                            | `false`             | Render embedded documents as blank instead of cloning them        |
+| `captureTimeout`        | `number`                             | `30000`             | Milliseconds one remote asset may hold a capture up               |
+| `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                 |
+| `onReady`               | `(overlay) => void`                  | —                   | Widget mounted; the safe place to `loadComments()`                |
+| `onError`               | `(error, context) => void`           | —                   | A survivable failure — capture, storage, load, link or transform  |
+| `onCommentRequested`    | `(id) => void \| Promise`            | —                   | A link points at a comment the widget does not hold               |
+| `transformScreenshot`   | `(dataUrl, info) => Promise<string>` | —                   | Swap every image the widget acquires for a string of your own     |
+| `onCommentModeChanged`  | `(active: boolean) => void`          | —                   | Comment mode turned on or off, however it was flipped             |
+| `onCommentOpened`       | `(comment) => void`                  | —                   | Somebody opened a comment's thread — build unread counts on this  |
+| `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
 
@@ -410,18 +603,108 @@ 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) |
+Every one of them ends with a `meta` argument (the same fields are flattened
+onto the `onChange` event), so an existing handler that ignores it keeps
+working unchanged.
+
+| Callback                                  | Fires when                                                     |
+| ----------------------------------------- | -------------------------------------------------------------- |
+| `onCommentCreated(comment, meta)`         | A new comment is saved                                         |
+| `onReplyAdded(comment, reply, meta)`      | A reply is added to any comment                                |
+| `onReplyDeleted(comment, reply, meta)`    | A reply is removed                                             |
+| `onCommentEdited(comment, meta)`          | A comment's text is rewritten                                  |
+| `onReplyEdited(comment, reply, meta)`     | A reply's text is rewritten                                    |
+| `onCommentStatusChanged(comment, meta)`   | Status moves along the lifecycle                               |
+| `onCommentUpdated(comment, meta)`         | Type, priority or tags change                                  |
+| `onCommentDeleted(id, meta)`              | A comment is removed                                           |
+| `onAnchorLost(comment, meta)`             | A comment could not be re-anchored                             |
+| `onReactionToggled(comment, reply, meta)` | A reaction is added or removed (`reply` is `null` at the root) |
+
+Five more do not report a change to a comment:
+
+| Callback                       | Fires when                                                      |
+| ------------------------------ | --------------------------------------------------------------- |
+| `onReady(overlay)`             | The widget has mounted and every method is safe to call         |
+| `onError(error, context)`      | Something survivable went wrong — see below                     |
+| `onCommentRequested(id)`       | A link points at a comment the widget does not hold — see below |
+| `onCommentModeChanged(active)` | Comment mode turned on or off — see below                       |
+| `onCommentOpened(comment)`     | Somebody opened a comment's thread — see below                  |
+
+#### `meta.origin` — who caused the change
+
+`"user"` is somebody acting inside the widget; `"host"` is your own code
+calling a method. The inbox and the thread popover drive the very same public
+methods you do, so this is the only thing that tells the two apart.
+
+It matters as soon as more than one person is looking. Applying a change that
+arrived over a socket means calling `setCommentStatus()` — which emits, which
+sends it straight back to the server:
+
+```js
+createCommentOverlay({
+  onChange: (event) => {
+    if (event.origin === "host") return; // our own write, echoed back
+    api.post("/helldots-events", event);
+  },
+});
+
+socket.on("comment:resolved", ({ id }) =>
+  overlay.setCommentStatus(id, "resolved")
+);
+```
+
+Without the guard that loop runs forever. `comment:anchor-lost` is always
+`"host"` too, so this also silences the repeat every `notifyNavigation()`
+produces for a comment whose element is not on the new page.
+
+#### `meta.from` / `meta.to` — what moved
+
+`comment:status-changed` carries both ends of the move, and `comment:updated`
+adds `field` to say which of the three it was about:
+
+```js
+onCommentStatusChanged: (comment, { from, to }) => {
+  if (from === "resolved") notify(`${comment.author} reopened this`);
+},
+onCommentUpdated: (comment, meta) => {
+  if (meta.field === "priority" && meta.to === "high") page(comment);
+},
+```
+
+`field` narrows `from` and `to` for you in TypeScript. Re-applying a value a
+comment already holds is a no-op: no event, no write.
+
+#### `onCommentModeChanged` and `onCommentOpened`
+
+Comment mode is the one the host cannot observe on its own: the keyboard
+shortcut never reaches your code, so an app that has to stand down while
+somebody is picking an element has no other signal.
+
+```js
+onCommentModeChanged: (active) => {
+  carousel.paused = active; // your drag-and-drop would fight the picker
+},
+```
+
+`onCommentOpened` fires when a thread is actually read — from its marker or
+from the inbox detail, the only two places the replies are visible. It does
+not fire when the inbox merely re-renders. HellDots stores no read state of
+its own, because whose "read" it is depends on an identity only you can
+persist:
+
+```js
+onCommentOpened: (comment) => api.post(`/comments/${comment.id}/read`),
+```
+
+#### `onError(error, context)`
+
+Failures the widget survives but you would otherwise only find in the
+console: `"capture"` (a screenshot did not render — the comment saves without
+one), `"storage"` (localStorage could not be written, so this browser's copy
+now diverges), `"load"` (a malformed record was skipped), `"link"` (an
+`onCommentRequested` handler threw or rejected), `"transform"` (a
+`transformScreenshot` handler failed, so the data URL was kept). The console
+warning stays either way.
 
 ## API
 
@@ -447,9 +730,22 @@ overlay.setCommentPriority(id, priority); // → boolean
 overlay.setCommentTags(id, tags); // → boolean
 overlay.toggleCommentReaction(id, emoji); // → boolean
 overlay.toggleReplyReaction(commentId, replyId, emoji); // → boolean
+overlay.setUser(user); // → boolean (null returns to the anonymous author)
+overlay.exportCommentsCsv(comments?); // → string (and downloads it)
+overlay.exportMetricsCsv(comments?); // → string (and downloads it)
 overlay.cleanup(); // remove the widget entirely
 ```
 
+Two module-level helpers come with the package, for reading a deep link
+before an overlay exists:
+
+```ts
+import { readCommentLinkParam, DEFAULT_LINK_PARAM } from "helldots";
+
+DEFAULT_LINK_PARAM; // "helldotsComment"
+readCommentLinkParam(param?, href?); // → string | null
+```
+
 The setters return `false` for an unknown id or an invalid value, and make no
 change when they do. To reconcile against a backend after remote deletions,
 call `clearComments()` and then `loadComments(freshData)` — `loadComments`