@pixelmatters/markup 1.26.0 → 1.27.1

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.26.0'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.27.1'
   // or
-  // import { init } from 'https://esm.run/@pixelmatters/markup@1.26.0'
+  // import { init } from 'https://esm.run/@pixelmatters/markup@1.27.1'
 
   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.26.0`).
+> **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.1`).
 
 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.26.0"
+  src="https://esm.sh/@pixelmatters/markup@1.27.1"
   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.
 
@@ -279,6 +291,76 @@ Capture degrades instead of failing outright:
 - **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.26.0'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.27.1'
 
   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.26.0"
+  src="https://esm.sh/@pixelmatters/markup@1.27.1"
   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.
      *