@pixelmatters/markup 1.23.0 → 1.25.0

package/README.md

@@ -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.23.0'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.25.0'
   // or
-  // import { init } from 'https://esm.run/@pixelmatters/markup@1.23.0'
+  // import { init } from 'https://esm.run/@pixelmatters/markup@1.25.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.23.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.25.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.23.0"
+  src="https://esm.sh/@pixelmatters/markup@1.25.0"
   data-markup-widget="true"
   data-api-url="https://your-deployment.convex.site"
   data-api-key="markup_..."
@@ -219,7 +219,9 @@ Appearance persists to the host page's `localStorage` (`markup:widget:theme`) an
 
 **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.
 
-The last two menu rows open panels anchored to the same corner as the toolbar:
+The last two menu rows open inside the menu itself, replacing the rows with a
+reading panel and a **Back** button. `Esc` steps back to the rows, and again to
+close.
 
 - **Privacy & data.** A plain-language account of what the widget holds, generated from the live session rather than from a policy document: who you're posting as, what a comment sends, what sits in this site's storage, whether captures are on, and the single host the widget talks to. Anonymous visitors also get **Forget me on this site** here, with the same arm-then-confirm as the identity menu.
 - **Keyboard shortcuts.** The table below, in the modifier vocabulary of the reader's platform. The menu is the only way in on purpose: a key binding for it (`?` being the conventional one) would compete with whatever your app already binds, and the widget can't see your handlers to know.
@@ -273,6 +275,7 @@ The overflow menu's **Privacy & data** panel restates all of this for the person
 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.
 - **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.
 
@@ -372,7 +375,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.23.0'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.25.0'
 
   init({
     apiUrl: '...',
@@ -388,7 +391,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.23.0"
+  src="https://esm.sh/@pixelmatters/markup@1.25.0"
   data-markup-widget="true"
   data-api-url="..."
   data-api-key="..."
@@ -420,11 +423,12 @@ If the host page ships a CSP, the widget needs:
 | ------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
 | `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 |
 
-Only `img-src` degrades gracefully: a blocked avatar falls back to initials, and a blocked image in a capture comes through blank. A missing `connect-src` entry stops the widget working at all, and a missing `style-src` one leaves it unstyled.
+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 `connect-src` entry stops the widget working at all, and a missing `style-src` one leaves it unstyled.
 
 ## Browser support
 

package/dist/widget.d.ts

@@ -7,28 +7,48 @@ export type WidgetTheme = 'light' | 'dark' | 'auto';
  */
 export type WidgetFab = 'default' | 'icon-only';
 export interface ScreenshotsConfig {
-    /** Disable screenshot capture entirely. Default: enabled. */
+    /**
+     * Disable screenshot capture entirely.
+     *
+     * @default true
+     */
     enabled?: boolean;
-    /** Also masks all inputs/selects/textareas in addition to the default sensitive set. Default: false. */
+    /**
+     * Also masks all inputs/selects/textareas in addition to the default sensitive set.
+     *
+     * @default false
+     */
     strictScrub?: boolean;
-    /** Custom CSS selector — matched elements are always masked. */
+    /**
+     * Custom CSS selector — matched elements are always masked.
+     *
+     * @default undefined
+     */
     redactSelector?: string;
 }
 export interface WidgetConfig {
-    /** Convex deployment site URL, e.g. `https://your-deployment.convex.site` */
+    /**
+     * Convex deployment site URL, e.g. `https://your-deployment.convex.site`
+     */
     apiUrl: string;
-    /** Raw API key minted from a project's settings page */
+    /**
+     * Raw API key minted from a project's settings page
+     */
     apiKey: string;
     /**
      * Initial corner for the toolbar. Defaults to bottom-right. Users can
      * move it afterwards from the toolbar's overflow menu.
+     *
+     * @default 'bottom-right'
      */
     position?: 'bottom-right' | 'bottom-left' | 'bottom-center';
     /**
      * Visual theme.
      * - `'light'` — force light palette
      * - `'dark'` — force dark palette
-     * - `'auto'` (default) — follow the host's `prefers-color-scheme`
+     * - `'auto'` — follow the host's `prefers-color-scheme`
+     *
+     * @default 'auto'
      */
     theme?: WidgetTheme;
     /**
@@ -37,20 +57,27 @@ export interface WidgetConfig {
      * `'icon-only'` describes anything the widget can render. Accepted
      * (and dropped) so upgrading doesn't break callers that still pass it;
      * remove it from your config. Will be deleted in the next major.
+     *
+     * @default undefined
      */
     fab?: WidgetFab;
-    /** Screenshot capture and PII-scrub options. */
+    /**
+     * Screenshot capture and PII-scrub options.
+     *
+     * @default undefined
+     */
     screenshots?: ScreenshotsConfig;
     /**
      * Optional dashboard URL the widget links to from the verified-user
      * identity menu ("Account →"). When omitted the menu hides the
      * Account entry. Useful for self-hosters whose dashboard origin
      * isn't statically known to the widget.
+     *
+     * @default 'https://markup.pixelmatters.dev'
      */
     dashboardUrl?: string;
     /**
      * Product telemetry — counts of widget interactions, sent to Markup.
-     * Default: enabled.
      *
      * What it is not: it adds no third-party script, sets no cookie and
      * writes nothing to storage, and carries no identifier for the person
@@ -60,6 +87,8 @@ export interface WidgetConfig {
      *
      * Set `false` if your privacy policy or DPA is easier to write
      * without it.
+     *
+     * @default true
      */
     analytics?: boolean;
 }