@pixelmatters/markup 1.18.1 → 1.18.2

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.18.1'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.18.2'
   // or
-  // import { init } from 'https://esm.run/@pixelmatters/markup@1.18.1'
+  // import { init } from 'https://esm.run/@pixelmatters/markup@1.18.2'
 
   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 — a future major release will break your page silently. Always pin (`@pixelmatters/markup@1.18.1`).
+> **Why pin the version?** CDN URLs without a version (`@pixelmatters/markup`) resolve to whatever's `latest` on npm — a future major release will break your page silently. Always pin (`@pixelmatters/markup@1.18.2`).
 
 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.18.1"
+  src="https://esm.sh/@pixelmatters/markup@1.18.2"
   data-markup-widget="true"
   data-api-url="https://your-deployment.convex.site"
   data-api-key="markup_..."
@@ -307,12 +307,24 @@ Signed-in authors render their profile picture — on their comments and on the
 
 ## AI prompt
 
-If your IDE / agent supports the [`skills`](https://www.npmjs.com/package/skills) CLI (Claude Code, Cursor, etc.), install the bundled skill instead of pasting a prompt — it gives the agent persistent, up-to-date install + troubleshooting guidance:
+This package ships its own Agent Skill — persistent install + troubleshooting guidance for your agent, instead of a prompt you paste once and lose. Install it rather than the prompt below where you can.
+
+If `@pixelmatters/markup` is already a dependency, the skill is already on disk under `node_modules`, versioned with the release you installed. [TanStack Intent](https://tanstack.com/intent/latest) wires it into whatever agent config you use (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, …):
 
 ```bash
-npx skills add Pixelmatters/markup --skill pixelmatters-markup
+npx @tanstack/intent@latest install
 ```
 
+Re-run it when you add another Intent-enabled package. A `pnpm update` of this one is enough on its own — the skill travels with the tarball, so it refreshes in place.
+
+If you'd rather pull it straight from the repo, or you're deciding whether to adopt the widget at all and haven't installed it yet, the [`skills`](https://www.npmjs.com/package/skills) CLI takes it by path:
+
+```bash
+npx skills add Pixelmatters/markup/packages/widget/skills/install-markup-widget
+```
+
+The path matters — it's where the skill lives in the repo, and without it the CLI picks up this repo's internal contributor skills instead.
+
 Otherwise, paste the block below into Claude, ChatGPT, Cursor, or any other LLM and it'll wire the widget into your codebase end-to-end.
 
 ````markdown
@@ -358,7 +370,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.18.1'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.18.2'
 
   init({
     apiUrl: '...',
@@ -374,7 +386,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.18.1"
+  src="https://esm.sh/@pixelmatters/markup@1.18.2"
   data-markup-widget="true"
   data-api-url="..."
   data-api-key="..."

package/dist/widget.js

@@ -7495,7 +7495,7 @@ function Dc({ apiUrl: e, apiKey: t, position: n = "bottom-right", screenshots: r
 					onOpenPrivacy: () => C("privacy"),
 					onOpenShortcuts: () => C("shortcuts"),
 					onHideForSession: () => Ce({ type: "hide-with-toast" }),
-					version: "1.18.1",
+					version: "1.18.2",
 					dashboardUrl: i
 				})
 			}) : null,
@@ -7592,11 +7592,11 @@ function jc(e, t) {
 	a.className = "markup-shadow-root", r.appendChild(a), je({
 		apiUrl: t.apiUrl,
 		apiKey: t.apiKey,
-		widgetVersion: "1.18.1"
+		widgetVersion: "1.18.2"
 	}), be(t.analytics === !1 ? null : {
 		apiUrl: t.apiUrl,
 		apiKey: t.apiKey,
-		widgetVersion: "1.18.1"
+		widgetVersion: "1.18.2"
 	}), F("widget_loaded");
 	let { theme: o, analytics: s, ...c } = t;
 	return de(/* @__PURE__ */ Q(Ce, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelmatters/markup",
-  "version": "1.18.1",
+  "version": "1.18.2",
   "description": "Embeddable feedback widget for collecting visual bug reports, screenshots, and comments on live web apps.",
   "keywords": [
     "annotation",
@@ -10,6 +10,7 @@
     "pixelmatters",
     "preact",
     "screenshot",
+    "tanstack-intent",
     "widget"
   ],
   "homepage": "https://github.com/Pixelmatters/markup#readme",
@@ -27,6 +28,8 @@
     "dist/widget.js",
     "dist/widget.js.map",
     "dist/widget.d.ts",
+    "skills",
+    "!skills/_artifacts",
     "README.md",
     "LICENSE"
   ],
@@ -47,6 +50,7 @@
     "@medv/finder": "^4.0.2",
     "@playwright/test": "^1.62.1",
     "@preact/preset-vite": "^2.10.6",
+    "@tanstack/intent": "0.3.6",
     "convex": "^1.38.0",
     "html-to-image": "^1.11.13",
     "preact": "^10.29.7",
@@ -62,6 +66,7 @@
     "dev": "vite",
     "test:e2e": "playwright test",
     "test:e2e:ui": "playwright test --ui",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "validate:skills": "intent validate"
   }
 }

package/skills/install-markup-widget/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: install-markup-widget
+description: Install, configure, and troubleshoot the `@pixelmatters/markup` feedback widget — a drop-in script that lets end-users pin threaded comments on any web page. Use this skill whenever the host project depends on `@pixelmatters/markup`, imports `init` / `destroy` from it, references a `markup_…` API key, or the user asks about installing / debugging the Markup feedback widget.
+sources:
+  - 'Pixelmatters/markup:packages/widget/README.md'
+  - 'Pixelmatters/markup:docs/widget-guide.md'
+  - 'Pixelmatters/markup:packages/widget/src/widget.ts'
+metadata:
+  library: pixelmatters-markup
+  library_version: '1.18.2'
+---
+
+`@pixelmatters/markup` is a Preact widget that runs inside a shadow DOM and talks to a hosted Convex backend at `https://<deployment>.convex.site`. The host page calls `init({ apiUrl, apiKey })` once at the app root and gets back a `destroy()` function. Everything else — pin anchoring, threads, mentions, identity, screenshots, real-time updates — lives inside the widget bundle.
+
+The widget renders a single compact **toolbar pill** in one bottom corner: comment, inbox (signed-in users only), pin-visibility toggle, identity menu, and an overflow menu holding Appearance, Position, an auto-capture toggle, and "Hide for this session". Installs predating 1.15.0 described a floating action button — that's gone, along with drag-to-reposition.
+
+## Install
+
+Detect the package manager (presence of `pnpm-lock.yaml` / `yarn.lock` / `package-lock.json`) and use it:
+
+```bash
+pnpm add @pixelmatters/markup   # or: yarn add … / npm install …
+```
+
+For a `<script>`-tag drop-in (no bundler / CMS / page-builder), use the inline ESM form and **always pin the version**:
+
+```html
+<script type="module">
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.18.2'
+  init({ apiUrl: '…', apiKey: '…' })
+</script>
+```
+
+If the host disallows inline JS, use the auto-init form. `data-markup-widget="true"` is required — it's how the bundle finds its own script element under `type="module"`:
+
+```html
+<script
+  type="module"
+  src="https://esm.sh/@pixelmatters/markup@1.18.2"
+  data-markup-widget="true"
+  data-api-url="…"
+  data-api-key="…"
+  data-position="bottom-right"
+  data-theme="auto"
+></script>
+```
+
+The recognised attributes are `data-api-url`, `data-api-key`, `data-position`, `data-theme`, and `data-dashboard-url`. The `screenshots` options are `init()`-only.
+
+## Wire-up
+
+There is no framework-specific entrypoint — no `@pixelmatters/markup/react`, no provider to wrap. Every framework calls `init()` from a mount hook (`useEffect`, `onMounted`, `onMount`, …) and the function it returns on cleanup. A module-level `destroy` is exported too, for call sites that can't hold onto the returned one; it tears down whichever instance is currently mounted.
+
+```ts
+import { init, destroy } from '@pixelmatters/markup'
+```
+
+`init` returns the matching `destroy`. Mount **once at the app root**, not per route — the widget patches `history.pushState` / `replaceState` and listens for `popstate` itself, so SPAs work without remounting. Calling `init` repeatedly is safe (the history wrapper is module-scoped, so init/destroy cycles don't stack), but it tears down the previous mount each time — so a render loop calling `init` will thrash. Always anchor it to a one-time mount lifecycle.
+
+If `apiUrl` or `apiKey` is missing, `init` logs a `[markup]` console warning and returns a no-op `destroy` rather than mounting — useful to know when debugging "nothing showed up."
+
+```ts
+// React — App.tsx
+useEffect(() => {
+  return init({
+    apiUrl: import.meta.env.VITE_MARKUP_API_URL,
+    apiKey: import.meta.env.VITE_MARKUP_API_KEY,
+  })
+}, [])
+```
+
+```vue
+<!-- Vue 3 -->
+<script setup lang="ts">
+import { onMounted, onBeforeUnmount } from 'vue'
+import { init } from '@pixelmatters/markup'
+let stop: (() => void) | undefined
+onMounted(() => { stop = init({ apiUrl: …, apiKey: … }) })
+onBeforeUnmount(() => stop?.())
+</script>
+```
+
+```ts
+// Plain HTML / vanilla
+const stop = init({ apiUrl, apiKey })
+window.addEventListener('beforeunload', stop)
+```
+
+Tear down on logout if you don't want the widget visible to signed-out users. `init` is safe to call repeatedly — each call destroys the previous instance first.
+
+## Credentials
+
+- `apiUrl`: the project's Convex deployment site URL — copy from **Markup dashboard → Settings → Install**. Format: `https://<deployment>.convex.site`.
+- `apiKey`: mint from **Settings → API Keys**. The raw key is shown **exactly once**; if it's lost, revoke and mint a new one.
+
+Conventions:
+
+- Store both in env vars (`VITE_MARKUP_API_URL`, `VITE_MARKUP_API_KEY`, or the framework equivalent — `NEXT_PUBLIC_…`, `PUBLIC_…`).
+- Add to `.env.example`. Ensure `.env*.local` is in `.gitignore` (most Vite / Next templates already do this).
+- The API key is public-by-design — it's gated server-side by the project's `allowedDomains`. Treating it like a secret anyway keeps it out of git history and forces rotation through the dashboard rather than ad-hoc.
+
+## Domain allowlist
+
+Production deployments **do not** auto-allow `localhost`. Before the widget will load on a new host:
+
+1. **Settings → Domains** in the dashboard.
+2. Add the exact host (`app.example.com`) or a glob (`*.staging.example.com`).
+3. To test against the live deployment from local dev, add `localhost` explicitly.
+
+A request from an unlisted origin gets `403 Origin not allowed` with no CORS headers — in browser devtools it shows as a CORS error, not a clean JSON error.
+
+## Config options
+
+| Option         | Type                                                 | Default           | Notes                                                                                                                               |
+| -------------- | ---------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `apiUrl`       | `string`                                             | required          | `https://*.convex.site`                                                                                                             |
+| `apiKey`       | `string`                                             | required          | `markup_…`                                                                                                                          |
+| `position`     | `'bottom-right' \| 'bottom-left' \| 'bottom-center'` | `'bottom-right'`  | Initial toolbar corner — users move it with the Position picker in the overflow menu; the choice is per-mount and resets on reload  |
+| `theme`        | `'light' \| 'dark' \| 'auto'`                        | `'auto'`          | `'auto'` follows the host's `prefers-color-scheme`. A user's pick in the overflow menu persists and outranks this on later `init()` |
+| `screenshots`  | `ScreenshotsConfig` (see below)                      | enabled, defaults | Capture toggle + PII-scrub knobs                                                                                                    |
+| `dashboardUrl` | `string`                                             | —                 | Adds an **Account →** link to the signed-in identity menu and retargets the "Powered by Markup" line. For self-hosters              |
+| `fab`          | `'default' \| 'icon-only'`                           | —                 | **Deprecated, ignored since 1.15.0.** Accepted so old configs still compile; `init()` drops it and warns once. Remove it            |
+
+### Screenshots & PII scrub
+
+```ts
+init({
+  apiUrl,
+  apiKey,
+  screenshots: {
+    enabled: true, // default true — set false to disable screenshot capture
+    strictScrub: false, // mask EVERY input/select/textarea (not just sensitive)
+    redactSelector: '.private', // extra CSS selector — matched elements always masked
+  },
+})
+```
+
+Auto-masked by default (regardless of `strictScrub`):
+
+- `input[type="password"]`
+- `input[autocomplete~="cc-number" | "cc-csc" | "cc-exp" | "cc-name" | "cc-type"]`
+- `input[autocomplete~="current-password" | "new-password" | "one-time-code"]`
+
+HTML attributes the widget honours on the host page:
+
+- `data-markup-private` / `data-markup-redact` — always masked (in addition to auto-detection).
+- `data-markup-safe` — any element with this attribute (or an ancestor that has it) is **exempted** from auto-detection and from `redactSelector` / `strictScrub`. Use sparingly — putting it on a wrapper accidentally un-protects everything inside.
+- `data-markup-skip` — removes the element from the screenshot entirely, rather than masking it.
+
+Tell users with strict compliance needs to opt into `strictScrub: true` and pin sensitive areas with `data-markup-private` rather than relying on the default heuristics.
+
+End users can also switch capture off for themselves with **Auto-capture screenshots** in the overflow menu. `screenshots.enabled: false` from the host still wins — that row renders disabled.
+
+Capture degrades rather than failing silently: an image the browser won't hand over (a third-party avatar served without CORS headers is the usual culprit) comes through blank while the rest of the page captures; an oversized capture is re-encoded down a quality-then-scale ladder to fit the server's 2 MB cap; and if it still can't produce an image the composer says _Screenshot unavailable_ and the comment posts without one.
+
+## Mentions & inbox
+
+Typing `@` in a composer opens a picker of project members and inserts a chip — the stored `@[Display Name](userId)` form never reaches the screen. `↑`/`↓` move, `enter` or `tab` picks, `esc` dismisses. It works for anonymous visitors too; the member list is fetched once per mount with the API key, and a failed fetch degrades to "no picker, no chips" rather than blocking the widget.
+
+Mentioned teammates get a notification. **Signed-in** users read those from the inbox button on the toolbar, which carries an unread badge; anonymous visitors don't get the button. A mention that doesn't highlight means nobody was notified — the target isn't a project member, has left, or is the author themselves.
+
+Comments written by an AI agent through Markup's MCP server carry a bot badge. They're posted under a team member's name, so the badge is the only signal that a machine wrote it.
+
+## Verify the install
+
+Don't call it done on a clean build — the widget can compile in and still never
+mount. Run the dev server, then:
+
+1. Confirm the toolbar pill is in the configured bottom corner.
+2. Click the comment button, drop a pin anywhere on the page, submit a comment.
+3. Confirm the thread appears on the project in the Markup dashboard. It arrives
+   over WebSocket, so it should show without a refresh.
+
+A pin that posts but never lands in the dashboard is a project mismatch — the
+API key belongs to a different project than the one being watched.
+
+## Diagnostics
+
+Walk these in order when the widget is misbehaving:
+
+| Symptom                                                                                 | Cause                                                                                                                                                                           | Fix                                                                                                                                                                                    |
+| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Toolbar doesn't appear, console warns `[markup] init() requires both apiUrl and apiKey` | One of the env vars is unset / undefined at the call site                                                                                                                       | Confirm the framework's env-var prefix (`VITE_…`, `NEXT_PUBLIC_…`, etc.) and that `.env` is being loaded                                                                               |
+| Toolbar doesn't appear, console shows `403 Origin not allowed`                          | Host is not in `allowedDomains`                                                                                                                                                 | Dashboard → Settings → Domains, add the exact host (`app.example.com`) or a wildcard (`*.example.com` matches any subdomain depth)                                                     |
+| Toolbar renders unstyled, or threads never load                                         | CSP is missing `style-src 'unsafe-inline'` (the stylesheet is a `<style>` element in the shadow root) or the deployment origins under `connect-src`                             | See the CSP bullet under **Don'ts**                                                                                                                                                    |
+| Comments show initials where profile pictures are expected                              | The host's CSP `img-src` blocks the picture host, or the account has none set                                                                                                   | Add the picture host to `img-src`. Initials are the intended fallback, not a bug                                                                                                       |
+| `@` types a literal character, no picker                                                | The member fetch failed (a `403`/`429` on `/widget/members` degrades silently by design)                                                                                        | Check the network tab for `/widget/members`; the usual cause is the domain allowlist                                                                                                   |
+| `401 Invalid api key`                                                                   | Key revoked, wrong project, or copy-paste truncation                                                                                                                            | Mint a fresh key and replace the env var                                                                                                                                               |
+| `429` + `Retry-After` header                                                            | Rate-limited (per-key pre-auth or per-project bucket)                                                                                                                           | Stop polling; respect the `Retry-After` seconds. If hit during normal use, ask the user to contact support to raise the project limit                                                  |
+| `400 Invalid anchor` / `Invalid viewport` / `Field too long`                            | Widget POSTed a coord outside `[0..1]`, a non-finite viewport size, or an over-long string (route > 256, url > 2048, userAgent > 500, anchorSelector > 1024, authorEmail > 320) | The bundled widget always stays inside these limits; this only fires if something between the widget and the API rewrote the payload — check for a misbehaving service worker or proxy |
+| Pins drift after host layout changes                                                    | Selector resolution failed; falling back to viewport fractions                                                                                                                  | Expected. Use stable IDs / data-attributes on anchor targets if precision matters                                                                                                      |
+| Pins disappear after route change in an SPA                                             | `init` was called per-route and remounted state                                                                                                                                 | Move `init` to a single root-level mount; the widget handles history itself                                                                                                            |
+| Widget styling looks broken inside an iframe                                            | Shadow DOM doesn't pierce frame boundaries                                                                                                                                      | Mount the widget **inside** the iframe document, not the parent                                                                                                                        |
+| Verified identity doesn't survive reload                                                | Host code clears `localStorage['markup.identity']` on logout                                                                                                                    | Only clear it on Markup-specific sign-out, not on host logout                                                                                                                          |
+| Popup sign-in flashes and closes                                                        | Popup origin failed `allowedDomains` check, or the stored JWT was expired and dropped                                                                                           | Add the host to the project's allowlist; the popup re-validates. Expired JWTs are silently dropped on next load — sign in again                                                        |
+| HMR leaves duplicate toolbars in dev                                                    | Hot reload re-runs `init` without cleanup                                                                                                                                       | Return the `destroy` from `useEffect` / `onMounted` so HMR can call it. (The history wrapper itself is module-scoped, so repeated init/destroy cycles no longer leak listeners.)       |
+| Screenshot is missing my custom field                                                   | Auto-mask matched the input (e.g. `autocomplete="cc-number"`) or your selector                                                                                                  | Inspect with the widget devtools panel; add `data-markup-safe` on the wrapper to exempt it from auto-detection                                                                         |
+| Widget invisible behind host UI                                                         | Z-index conflict on the shadow host element                                                                                                                                     | The widget mounts `<div id="markup-widget">` at `document.body`; raise its `z-index` from host CSS if you must                                                                         |
+
+## Don'ts
+
+- **Don't import CSS** — there is none to import. Styles live inside the shadow root.
+- **Don't wrap in a provider component.** `init` is the entire public surface.
+- **Don't call `init` inside a route component.** Mount at the app root once.
+- **Don't hardcode the API key.** Use env vars so rotations don't require a code change.
+- **Don't ship CDN URLs without a version pin.** `@pixelmatters/markup@1.18.2`, not `@pixelmatters/markup`.
+- **Don't add `https://*.convex.site` to `connect-src` and assume that's the whole CSP story.** The deployment domain (`<your-deployment>.convex.site`) is what the widget hits over HTTP, and it must be listed explicitly. Live thread updates go to `wss://<your-deployment>.convex.cloud` — the widget derives that origin from `apiUrl` — so `connect-src` needs both. `img-src` needs `blob:`, `data:`, and the host serving profile pictures; `style-src` needs `'unsafe-inline'` because the widget appends its stylesheet as a `<style>` element inside its shadow root. Add `https://esm.sh` to `script-src` only if you took the CDN path.
+
+## Versioning & releases
+
+The widget follows semver. Pin to a major in `package.json` (`^1.5.0`) so patch + minor updates flow through `pnpm update`, but a future `2.0` cannot break the host silently. For CDN consumers, pin the exact version — there's no lockfile to catch a surprise major.
+
+## Reference
+
+- Install tutorial: https://pixelmatters-markup.pages.dev/docs/install
+- Package on npm: https://www.npmjs.com/package/@pixelmatters/markup
+- Source: https://github.com/Pixelmatters/markup
+
+## When in doubt
+
+The widget's `init({ apiUrl, apiKey })` is intentionally the entire API. If a question seems to need a richer surface (custom triggers, programmatic pin creation, headless mode), it's almost certainly something the widget doesn't do — say so plainly rather than inventing options.