@pixelmatters/markup 1.25.2 → 1.27.0

package/README.md

@@ -15,7 +15,7 @@ Pin-anchored feedback for live web apps. Drop in a script tag and your stakehold
 - **Drop-in identity.** Anonymous by default, with a popup-based sign-in that survives Safari ITP and Chrome storage partitioning. Signed-in authors show their profile picture; everyone else gets initials. A project can be set to **members only** in the dashboard, in which case visitors are asked to sign in before commenting; everyone still sees the pins.
 - **Agent replies are labelled.** A comment written by an AI agent through Markup's MCP server carries a bot badge. It's posted under a team member's name, so the badge is the only way a visitor can tell a machine answered.
 - **Style-isolated.** Runs inside an open shadow root with `:host { all: initial }`, so host CSS can't bleed in and widget CSS can't bleed out.
-- **SPA-aware.** Patches `history.pushState` / `replaceState` and follows `popstate` and `hashchange` to refresh threads on route changes. Hash routers are supported: a `#/orders` path is part of the route a thread is filed under, while a plain `#section` anchor is not, and neither is a query string in either position — `#/orders?tab=2` and `#/orders` are one page, as `/orders?tab=2` and `/orders` already were.
+- **SPA-aware.** Patches `history.pushState` / `replaceState` and follows `popstate` and `hashchange` to refresh threads on route changes. Hash routers are supported, and a query string is left out of the route unless you opt it in with `routeParams`. See [Routing](#routing).
 - **Respects the platform.** Honours `prefers-reduced-motion` and `prefers-color-scheme`, with full keyboard navigation and focus traps in popovers.
 - **Tiny API, tiny config.** `init({ apiUrl, apiKey })` is enough to start. No global CSS to import, no provider to wrap.
 
@@ -37,9 +37,9 @@ CDN drop-in, no build step. Paste this just before `</body>`:
 ```html
 <script type="module">
   // Pin the exact version; esm.sh resolves it from npm
-  import { init } from 'https://esm.sh/@pixelmatters/markup@1.25.2'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.27.0'
   // or
-  // import { init } from 'https://esm.run/@pixelmatters/markup@1.25.2'
+  // import { init } from 'https://esm.run/@pixelmatters/markup@1.27.0'
 
   init({
     apiUrl: 'https://your-deployment.convex.site',
@@ -50,14 +50,14 @@ CDN drop-in, no build step. Paste this just before `</body>`:
 </script>
 ```
 
-> **Why pin the version?** CDN URLs without a version (`@pixelmatters/markup`) resolve to whatever's `latest` on npm, so a future major release will break your page with no warning. Always pin (`@pixelmatters/markup@1.25.2`).
+> **Why pin the version?** CDN URLs without a version (`@pixelmatters/markup`) resolve to whatever's `latest` on npm, so a future major release will break your page with no warning. Always pin (`@pixelmatters/markup@1.27.0`).
 
 If your platform doesn't allow inline JS (some CMS / page-builder editors), use the auto-init form instead. Point a `<script src=…>` at the bundle and pass config via `data-*` attributes:
 
 ```html
 <script
   type="module"
-  src="https://esm.sh/@pixelmatters/markup@1.25.2"
+  src="https://esm.sh/@pixelmatters/markup@1.27.0"
   data-markup-widget="true"
   data-api-url="https://your-deployment.convex.site"
   data-api-key="markup_..."
@@ -162,6 +162,7 @@ Mounts the widget. Always tears down any existing instance before mounting, so c
 | `analytics`    | `boolean`                                            | `true`           | Product telemetry: counts of widget interactions, sent to Markup. Adds no third-party script, sets no cookie, writes nothing to storage, and carries no identifier for your users. See [Product telemetry](#product-telemetry)                                                  |
 | `screenshots`  | `ScreenshotsConfig`                                  | capture enabled  | Capture and PII-scrub options. See [Screenshots & privacy](#screenshots--privacy)                                                                                                                                                                                               |
 | `dashboardUrl` | `string`                                             | none             | Dashboard URL the identity menu links to as **Account →** for signed-in users; it also retargets the overflow menu's "Powered by Markup" line. Omit it and the Account entry is hidden. Mostly useful for self-hosters, whose dashboard origin the widget can't know statically |
+| `routeParams`  | `string[]`                                           | `[]`             | Query params that name a _view_ rather than filter one, and so belong in the route a thread is filed under. See [Routing](#routing)                                                                                                                                             |
 
 <details>
 <summary><code>fab</code> (deprecated, ignored since 1.15.0)</summary>
@@ -207,15 +208,26 @@ Unmounts the widget and removes the host element. Safe to call when nothing is m
 
 The widget mounts a single compact pill in the corner set by `position`:
 
-| Control             | What it does                                                                                                                                                                                                                                           |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Comment**         | Arms placement. The next click on the page drops a pin, and it flips to a cancel icon while armed.                                                                                                                                                     |
-| **Inbox**           | Mention notifications for this project, with an unread badge. Signed-in users only; anonymous visitors don't get the button.                                                                                                                           |
-| **Pins** (eye)      | Hides or shows every pin without hiding the toolbar.                                                                                                                                                                                                   |
-| **Identity**        | Avatar button. Anonymous: a sign-in prompt plus "Forget me on this site". Signed in: name, email, an **Account →** link when `dashboardUrl` is set, and **Sign out**.                                                                                  |
-| **Overflow** (`☰`) | **Appearance** (Light / Dark / Auto), **Position** (left / center / right), an **Auto-capture screenshots** toggle, a **Show resolved threads** toggle, **Privacy & data**, **Keyboard shortcuts**, **Hide for this session**, and the widget version. |
+| Control             | What it does                                                                                                                                                                                                                                                                               |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Comment**         | Arms placement. The next click on the page drops a pin, and it flips to a cancel icon while armed.                                                                                                                                                                                         |
+| **Inbox**           | Mention notifications for this project, with an unread badge. Signed-in users only; anonymous visitors don't get the button.                                                                                                                                                               |
+| **Pins** (eye)      | Hides or shows every pin without hiding the toolbar.                                                                                                                                                                                                                                       |
+| **Identity**        | Avatar button. Anonymous: a sign-in prompt plus "Forget me on this site". Signed in: name, email, an **Account →** link when `dashboardUrl` is set, and **Sign out**.                                                                                                                      |
+| **Overflow** (`☰`) | **Appearance** (Light / Dark / Auto), **Position** (left / center / right), an **Auto-capture screenshots** toggle, an **Only this URL's pins** toggle, a **Show resolved threads** toggle, **Privacy & data**, **Keyboard shortcuts**, **Hide for this session**, and the widget version. |
 
-Appearance persists to the host page's `localStorage` (`markup:widget:theme`) and, once a user has set it, takes precedence over the `theme` option on every later `init()`. Position, pin visibility, the auto-capture toggle and the resolved-threads toggle are per-mount. They reset on reload, and `position` seeds the toolbar again.
+Appearance persists to the host page's `localStorage` (`markup:widget:theme`) and, once a user has set it, takes precedence over the `theme` option on every later `init()`. Position, pin visibility, the auto-capture toggle, the URL-scope toggle and the resolved-threads toggle are per-mount. They reset on reload, and `position` seeds the toolbar again.
+
+**Only this URL's pins** is off by default. A route is `host + pathname`, so
+views your app distinguishes only by a query param share one set of pins and
+draw each other's. Turned on, the widget renders only the pins left on the URL
+you are on, by query string, and the overflow button carries
+a badge counting what is being held back — the pins are hidden from the page,
+never dropped, and an open thread stays drawn whichever URL it belongs to.
+
+Leave it off if your params are filters rather than views (`?page=2&sort=name`):
+it would split one page's feedback across every combination a reader happens to
+have on. A pin's tooltip names the URL it was left on either way.
 
 **Show resolved threads** is off by default. Turned on, the widget also renders the route's most recently resolved threads (up to 100) as muted check-mark pins. Opening one shows the thread read-only: no replies, edits, reactions or resolve button. Reopening still happens from the dashboard.
 
@@ -240,7 +252,7 @@ close.
 
 ## Screenshots & privacy
 
-By default, the widget captures the visible viewport as a JPEG before you submit a thread. Sensitive fields are blacked out **before** the image is produced. The live DOM is mutated only for the duration of the capture, then restored. No image content leaves the browser until the user explicitly attaches the screenshot and posts.
+By default, the widget captures the visible viewport as a WebP image before you submit a thread (JPEG on browsers that can't encode WebP). Sensitive fields are blacked out **before** the image is produced. The live DOM is mutated only for the duration of the capture, then restored. No image content leaves the browser until the user explicitly attaches the screenshot and posts.
 
 **Auto-scrubbed (zero config):**
 
@@ -276,9 +288,79 @@ Capture degrades instead of failing outright:
 
 - **An image the browser won't hand over** comes through blank, and the rest of the page still captures. A third-party avatar served without CORS headers is the usual culprit. It used to abort the whole screenshot.
 - **Icons from an SVG sprite** are fetched and inlined before the capture. The capture renders your page as an SVG document, which is not allowed to load anything external, so a `<use href="/sprite.svg#icon">` would otherwise draw nothing — on a design system that ships its icons that way, every icon in the screenshot went missing. A sprite the widget can't read (cross-origin without CORS headers, or outside your `connect-src`) leaves those icons blank and the rest captures as before.
-- **An oversized capture** is re-encoded until it fits the server's 2 MB cap: quality drops first (0.85 → 0.6), then the raster shrinks (full → ¾ → ½), because a smaller sharp screenshot beats a full-size illegible one.
+- **Captures are sized for storage, not for zooming.** The raster is capped at 1.5x device pixel ratio, so a 2x or 3x display doesn't bank detail nobody looks at in a lightbox. The image is then encoded down a ladder — quality drops first (0.85 → 0.6), then the raster shrinks (full → ¾ → ½) — until it lands under roughly 400 KB. A page that can't get there at any rung keeps the sharpest version that still fits the server's 2 MB hard cap, because a smaller sharp screenshot beats a full-size illegible one but not by any margin.
 - **If nothing works**, the composer reads _Screenshot unavailable_ and the comment posts without one. Previously the row just disappeared, which looked identical to screenshots being switched off for the project.
 
+## Routing
+
+A thread is filed under a **route**, and pins are drawn for the route you are
+standing on. A route is `host + pathname`, plus a hash-router path when the
+fragment is one:
+
+| URL                                   | Route                     |
+| ------------------------------------- | ------------------------- |
+| `https://app.acme.com/orders`         | `app.acme.com/orders`     |
+| `https://app.acme.com/orders?page=2`  | `app.acme.com/orders`     |
+| `https://app.acme.com/#/orders`       | `app.acme.com/#/orders`   |
+| `https://app.acme.com/#/orders?tab=2` | `app.acme.com/#/orders`   |
+| `https://staging.acme.com/orders`     | `staging.acme.com/orders` |
+
+The host is part of it, so staging and production never share pins. The query
+string is not, in either position — `?page=2` is a filter over a page, not a
+different page, and keying on it would split one conversation across every
+combination a reader happens to have on.
+
+### When a query param _is_ the page
+
+Some apps route a view by param: a multi-step form at one path with
+`?step=shipping`, `?step=payment` and so on. Those are different pages that
+happen to share a URL path, and by default they share one set of pins — every
+step's feedback is drawn on whichever step you are reading, at positions that
+mean nothing there.
+
+List the params that name a view:
+
+```js
+init({
+  apiUrl: '…',
+  apiKey: '…',
+  routeParams: ['step'],
+})
+```
+
+`/checkout?step=shipping` and `/checkout?step=payment` now have their own
+routes and their own pins. Params you don't list are still ignored, so
+`?step=payment&page=2` and `?step=payment&page=3` remain one page.
+
+Order doesn't matter — the key sorts them, so a router free to reorder its
+query can't split a view in two. A listed param the URL omits contributes
+nothing, so if a view is reachable both bare and with the param, those are two
+routes; make your router always write it.
+
+> **`routeParams` reads the real query string only.** On a hash router the
+> query lives inside the fragment (`#/orders?tab=2`), where `location.search`
+> is empty — so listing `tab` there does nothing. A hash-routed app that needs
+> per-param views has to put the distinguishing part in the router _path_
+> (`#/orders/tab/2`), which the key already carries. Tell us if that's you.
+
+> **Changing `routeParams` re-keys new threads.** Pins already stored under the
+> old route stop appearing until an operator runs
+> `threads/migration:rekeySearchRoutes` with the same list. Threads store their
+> full URL, so nothing is lost and the backfill can be re-run whenever the list
+> changes — widening, narrowing and dropping the option are all recoverable —
+> but there is a window each time. Coordinate the config change with the
+> backfill.
+
+Keep the listed params short. The route key is capped at 256 characters at the
+API edge, so a param carrying a serialized filter or a token can push a long
+path over it — and the failure is one-sided: pins still render, but posting a
+comment on those views is rejected.
+
+Leaving `routeParams` empty is the right answer for most apps. Where views
+share a route, each pin's tooltip names the URL it was left on, and the
+overflow menu's **Only this URL's pins** narrows the page to one view without
+changing how anything is stored.
+
 ## How it works
 
 - The widget mounts `<div id="markup-widget">` on `document.body` and attaches an open shadow root.
@@ -375,7 +457,7 @@ For a `<script>` tag drop-in (no bundler), use the inline ESM form and **pin the
 
 ```html
 <script type="module">
-  import { init } from 'https://esm.sh/@pixelmatters/markup@1.25.2'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.27.0'
 
   init({
     apiUrl: '...',
@@ -391,7 +473,7 @@ If inline JS is disallowed (some CMS / page-builder editors), use the auto-init
 ```html
 <script
   type="module"
-  src="https://esm.sh/@pixelmatters/markup@1.25.2"
+  src="https://esm.sh/@pixelmatters/markup@1.27.0"
   data-markup-widget="true"
   data-api-url="..."
   data-api-key="..."

package/dist/widget.d.ts

@@ -76,6 +76,45 @@ export interface WidgetConfig {
      * @default 'https://markup.pixelmatters.dev'
      */
     dashboardUrl?: string;
+    /**
+     * Query params that name a *view* rather than filter one, and so belong in
+     * the route a thread is filed under.
+     *
+     * A route is `host + pathname` (plus a hash-router path). Views your app
+     * distinguishes only by a param — `/checkout?step=shipping` and
+     * `/checkout?step=payment` — therefore share one route and draw each
+     * other's pins. Listing `'step'` gives each its own.
+     *
+     * Empty by default, and left that way for most apps: a param that filters
+     * a list (`?page=2&sort=name`) is not a different page, and keying on it
+     * splits one conversation across every combination a reader happens to
+     * have on. List only the params that change *what the page is*.
+     *
+     * Order doesn't matter — the key sorts them, so a router free to reorder
+     * its query can't split a view in two. A listed param the URL omits
+     * contributes nothing, so if a view is reachable both bare and with the
+     * param, those are two routes.
+     *
+     * Reads `location.search` only. A hash router's query lives inside the
+     * fragment (`#/orders?tab=2`), where there is no query string, so this
+     * option cannot reach it — such an app needs the distinguishing part in
+     * the router path, which the route key already carries.
+     *
+     * **Changing this re-keys new threads.** Pins already stored under the old
+     * route stop appearing until an operator runs the matching backfill
+     * (`threads/migration:rekeySearchRoutes`) with the same list. The backfill
+     * can be re-run whenever the list changes, so widening, narrowing and
+     * dropping the option are all recoverable — but there is a window each
+     * time, so coordinate the two.
+     *
+     * Keep the listed params short. The route key is capped at 256 characters
+     * at the API edge, and a param carrying a serialized filter or a token can
+     * push a long path past it; comments on those views are then rejected
+     * while the pins still render.
+     *
+     * @default []
+     */
+    routeParams?: string[];
     /**
      * Product telemetry — counts of widget interactions, sent to Markup.
      *