@pixelmatters/markup 1.32.4 → 1.33.0

package/README.md

@@ -14,7 +14,7 @@ Pin-anchored feedback for live web apps. Drop in a script tag and your stakehold
 - **Annotated screenshots.** Opt-in capture with the pin marker drawn on the image and embedded fonts, so the snapshot matches what the user saw.
 - **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.
+- **Style-isolated.** Runs inside an open shadow root with `:host { all: initial !important }`, so host CSS can't bleed in or restyle the widget, 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, 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.32.4'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.33.0'
   // or
-  // import { init } from 'https://esm.run/@pixelmatters/markup@1.32.4'
+  // import { init } from 'https://esm.run/@pixelmatters/markup@1.33.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.32.4`).
+> **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.33.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.32.4"
+  src="https://esm.sh/@pixelmatters/markup@1.33.0"
   data-markup-widget="true"
   data-api-url="https://your-deployment.convex.site"
   data-api-key="markup_..."
@@ -214,6 +214,26 @@ What it is not, concretely:
 
 Unmounts the widget and removes the host element. Safe to call when nothing is mounted.
 
+### Hiding the widget or stacking it lower
+
+Ordinary CSS can't reach the widget's host element (see [How it works](#how-it-works)), so `#markup-widget { display: none }` or a `z-index` of yours has no effect. Set one of these custom properties instead, on `#markup-widget` or on any ancestor such as `:root`. Both inherit, so they work inside a media query or under a class you toggle:
+
+```css
+/* Hide the widget on small screens. */
+@media (max-width: 640px) {
+  :root {
+    --markup-display: none;
+  }
+}
+
+/* Keep the widget beneath your cookie banner. */
+#markup-widget {
+  --markup-z-index: 999;
+}
+```
+
+`--markup-display` takes `none` to hide the widget, and defaults to `block`. `--markup-z-index` takes an integer, and defaults to `2147483647`. The `hidden` attribute on `#markup-widget` also hides it. The widget never prints.
+
 ## The toolbar
 
 The widget mounts a single compact pill in the corner set by `position`:
@@ -269,7 +289,11 @@ close.
 
 ## Screenshots & privacy
 
-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. Each masked element becomes one solid black block covering its box, with nothing inside it showing: no text, images, icons or child elements, even where they overflow the box. Masking a `<canvas>`, `<video>` or `<iframe>` also blacks out any image beside it in the same parent. The mask is applied to the copy of the page the capture renders, so the page itself never shows it. 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 mask is drawn into the snapshot, never onto your page, so nothing on the page changes, and masking holds even under a `style-src` without `'unsafe-inline'`. Each masked element comes out as one solid black block covering its box, whatever your stylesheets say about it: its text, placeholder, images, canvases, SVG, icons, backgrounds and child elements are all left out, and its images and backgrounds aren't fetched or read. Sprite files and webfonts still are, since the rest of the page shares them and they hold nothing of the field. No image content leaves the browser until the user explicitly attaches the screenshot and posts.
+
+The capture works in slices of a few milliseconds and leaves out what is outside the viewport. Your page's own timers, messages and frames run between slices, so a large page stays responsive while it runs. One step can't be split: the browser laying out the finished snapshot, which takes longer the more is on screen. Because the page keeps running, each part of it is captured as it is when the capture reaches it, so content your page moves or changes mid-capture appears where your page put it. A list or table your page renders again while the capture is partway through it is read again, so it comes out whole rather than half old and half new.
+
+Two things don't follow your scroll position: an element that scrolls on its own is captured from its top (this includes an app shell that scrolls a root `<div>` rather than the window), and a `position: sticky` element is captured where it sits before it sticks.
 
 **Auto-scrubbed (zero config):**
 
@@ -295,7 +319,7 @@ By default, the widget captures the visible viewport as a WebP image before you
 | `screenshots.strictScrub`    | `boolean` | `false` | Also masks all `input`, `select`, and `textarea` elements.                                   |
 | `screenshots.redactSelector` | `string`  | none    | Custom CSS selector; matched elements are masked unless inside a `data-markup-safe` element. |
 
-When a screenshot is attached in the composer, a chip shows how many fields were redacted. Clicking it expands the list of CSS selectors that were masked.
+The rules apply inside open shadow roots and same-origin iframes too. When a screenshot is attached in the composer, a chip shows how many masked fields the screenshot shows, those included; a matching field that is hidden, skipped or off screen isn't in it and isn't counted. Clicking it expands the list of CSS selectors that were masked.
 
 Users can also switch capture off for themselves with **Auto-capture screenshots** in the toolbar's overflow menu. A host that set `screenshots.enabled: false` still wins. The row renders disabled and says so, rather than offering a control that does nothing.
 
@@ -406,8 +430,8 @@ to start from `anchorSource` and confirm it, not to trust it blindly.
 
 ## How it works
 
-- The widget mounts `<div id="markup-widget">` on `document.body` and attaches an open shadow root. It does so once the page is idle, or 2 s after `init()` on a page that never is, so `init()` returns before the element exists.
-- All UI lives in that shadow root, with `:host { all: initial }` blocking style inheritance.
+- The widget mounts `<div id="markup-widget">` on `document.body` and attaches an open shadow root. It does so once the page is idle, or 2 s after `init()` on a page that never is, so `init()` returns before the element exists. The requests it needs before it can show pins, for the live-update credential and, on a first visit, an anonymous identity, go out from `init()` itself, so they overlap that wait.
+- All UI lives in that shadow root, with `:host { all: initial !important }` blocking style inheritance. The `!important` also means no rule on your page can restyle the host element, whether it matches by accident (`div`, `body > div`, `[data-theme]`) or aims at `#markup-widget`: it can't paint or move the widget. To hide it or stack it lower, use the custom properties in [Hiding the widget or stacking it lower](#hiding-the-widget-or-stacking-it-lower); to take it off the page, call `destroy()`. It never prints.
 - The host element is `position: fixed; inset: 0; pointer-events: none`, so the widget paints over the entire viewport without blocking the host's clicks; only the toolbar and active popovers opt back in to pointer events.
 - A modal on your page, such as a Radix or Base UI dialog, doesn't lock the widget out. Focus, wheel and touch events inside the widget are not passed on to your page, so a focus trap or scroll lock never sees them. A field of yours still gets its `focusout` when focus moves into the widget, without a `relatedTarget`. The widget also removes the `aria-hidden` or `inert` a modal puts on it, so screen readers can reach it. A Base UI popup that allows presses outside it still closes on a click in the widget, and a native `<dialog>` opened with `showModal()` makes the widget inert.
 - Pins are anchored as `(x, y)` fractions of the document plus a CSS path from the nearest landmark (a stable `id`, `data-testid`, `main`, `form`, `table`, …) and the element's text. The path wins when it still resolves, relaxing from the top if a wrapper changed, and a match whose text differs is rejected; the fraction is the fallback so pins survive layout changes.
@@ -501,7 +525,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.32.4'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.33.0'
 
   init({
     apiUrl: '...',
@@ -517,7 +541,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.32.4"
+  src="https://esm.sh/@pixelmatters/markup@1.33.0"
   data-markup-widget="true"
   data-api-url="..."
   data-api-key="..."
@@ -545,16 +569,16 @@ Constraints:
 
 If the host page ships a CSP, the widget needs:
 
-| Directive     | Value                                                                      | Why                                                                                 |
-| ------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `connect-src` | `https://<deployment>.convex.site`                                         | threads, comments, identity, screenshot upload, error reports                       |
-| `connect-src` | `wss://<deployment>.convex.cloud`                                          | live thread updates                                                                 |
-| `connect-src` | your own origin, if you serve icons from an SVG sprite                     | fetched so `<use href="/sprite.svg#icon">` icons aren't blank in screenshots        |
-| `img-src`     | wherever your team's profile pictures are hosted, plus `blob:` and `data:` | avatars, the screenshot preview thumbnail, and the capture pipeline                 |
-| `script-src`  | `https://esm.sh`                                                           | CDN path only; a bundled install needs nothing here                                 |
-| `style-src`   | `'unsafe-inline'`                                                          | the widget appends its stylesheet as a `<style>` element inside its own shadow root |
+| Directive     | Value                                                                                                  | Why                                                                                 |
+| ------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| `connect-src` | `https://<deployment>.convex.site`                                                                     | threads, comments, identity, screenshot upload, error reports                       |
+| `connect-src` | `wss://<deployment>.convex.cloud`                                                                      | live thread updates                                                                 |
+| `connect-src` | your own origin, and any CDN serving your webfonts, CSS backgrounds, cross-origin images or SVG sprite | fetched so screenshots include them, such as `<use href="/sprite.svg#icon">` icons  |
+| `img-src`     | wherever your team's profile pictures are hosted, plus `blob:` and `data:`                             | avatars, the screenshot preview thumbnail, and the capture pipeline                 |
+| `script-src`  | `https://esm.sh`                                                                                       | CDN path only; a bundled install needs nothing here                                 |
+| `style-src`   | `'unsafe-inline'`                                                                                      | the widget appends its stylesheet as a `<style>` element inside its own shadow root |
 
-Only `img-src` and the sprite entry degrade gracefully: a blocked avatar falls back to initials, and a blocked image or sprite in a capture comes through blank. A missing `https://…convex.site` entry stops the widget working at all. A missing `wss://…convex.cloud` entry leaves the toolbar up and posting working, but threads never load; the widget reports that once rather than retrying. A missing `style-src` entry leaves it unstyled.
+Only `img-src` and the asset entry degrade gracefully: a blocked avatar falls back to initials, and a blocked image or sprite in a capture comes through blank. Without `data:` in `img-src` the capture itself can't load, and the composer reads _Screenshot unavailable_. A missing `https://…convex.site` entry stops the widget working at all. A missing `wss://…convex.cloud` entry leaves the toolbar up and posting working, but threads never load; the widget reports that once rather than retrying. A missing `style-src` entry leaves it unstyled.
 
 ## Browser support