@pixelmatters/markup 1.27.3 → 1.28.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.27.3'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.28.0'
   // or
-  // import { init } from 'https://esm.run/@pixelmatters/markup@1.27.3'
+  // import { init } from 'https://esm.run/@pixelmatters/markup@1.28.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.27.3`).
+> **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.28.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.27.3"
+  src="https://esm.sh/@pixelmatters/markup@1.28.0"
   data-markup-widget="true"
   data-api-url="https://your-deployment.convex.site"
   data-api-key="markup_..."
@@ -88,44 +88,53 @@ stop() // tears down this instance; the exported destroy() tears down whichever
 
 ### React
 
-```tsx
-import { useEffect } from 'react'
-import { init } from '@pixelmatters/markup'
+React 18 or later. Render the component once near your app root:
 
-export default function App() {
-  useEffect(() => {
-    return init({
-      apiUrl: import.meta.env.VITE_MARKUP_API_URL,
-      apiKey: import.meta.env.VITE_MARKUP_API_KEY,
-      position: 'bottom-right', // optional: 'bottom-right' | 'bottom-left' | 'bottom-center'
-      theme: 'auto', // optional: 'auto' | 'light' | 'dark'
-    })
-  }, [])
+```tsx
+'use client' // Next.js App Router only
+import { useMarkup } from '@pixelmatters/markup/react'
 
-  return <>{/* your app */}</>
+export function Markup() {
+  useMarkup({
+    apiUrl: import.meta.env.VITE_MARKUP_API_URL,
+    apiKey: import.meta.env.VITE_MARKUP_API_KEY,
+    position: 'bottom-right', // optional: 'bottom-right' | 'bottom-left' | 'bottom-center'
+    theme: 'auto', // optional: 'auto' | 'light' | 'dark'
+    enabled: true, // optional: false unmounts it, e.g. from your build environment
+  })
+  return null
 }
 ```
 
+The hook takes the same options as `init()`, plus `enabled`. An inline object
+is fine: the widget remounts only when a value changes. StrictMode's double
+mount leaves one widget, two components with the same options share it until
+both unmount, and server rendering mounts nothing. Don't also call `init()` on
+the same page.
+
 ### Vue 3
 
+Vue 3.3 or later. Call it once from your root component:
+
 ```vue
 <script setup lang="ts">
-import { onMounted, onBeforeUnmount } from 'vue'
-import { init } from '@pixelmatters/markup'
+import { useMarkup } from '@pixelmatters/markup/vue'
 
-let stop: (() => void) | undefined
-onMounted(() => {
-  stop = init({
-    apiUrl: import.meta.env.VITE_MARKUP_API_URL,
-    apiKey: import.meta.env.VITE_MARKUP_API_KEY,
-    position: 'bottom-right', // optional: 'bottom-right' | 'bottom-left' | 'bottom-center'
-    theme: 'auto', // optional: 'auto' | 'light' | 'dark'
-  })
+useMarkup({
+  apiUrl: import.meta.env.VITE_MARKUP_API_URL,
+  apiKey: import.meta.env.VITE_MARKUP_API_KEY,
+  position: 'bottom-right', // optional: 'bottom-right' | 'bottom-left' | 'bottom-center'
+  theme: 'auto', // optional: 'auto' | 'light' | 'dark'
 })
-onBeforeUnmount(() => stop?.())
 </script>
 ```
 
+The composable takes the same options as `init()`, plus `enabled`, as a plain
+object, a ref or a getter (`() => ({ …, theme: theme.value })`), and remounts
+the widget only when a value changes. Two components with the same options
+share one widget until both unmount, and nothing mounts during server
+rendering.
+
 ### SolidJS
 
 ```tsx
@@ -231,6 +240,12 @@ 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.
 
+A thread's own **⋯** menu has **Copy link**, and for signed-in users
+**Copy for agent**: the thread as a Markdown prompt for a coding agent, with
+the page, element, declared source path and every comment. Comment text is
+quoted line by line and every other value is a quoted string, so what a
+visitor typed can't pass itself off as part of the instructions.
+
 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.
@@ -361,6 +376,29 @@ 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.
 
+## Anchors and source paths
+
+Two optional attributes make pins sturdier and give agents a place to start.
+Neither is required; without them the widget anchors by structure and text.
+
+```html
+<section data-markup-anchor="pricing" data-markup-source="src/components/Pricing.tsx">…</section>
+```
+
+| Attribute            | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-markup-anchor` | A stable name for the element, used ahead of ids and test attributes when a pin's selector is built. Treat it like an id: a name unique on the page addresses the element on its own, and a pin placed on it stays attached when its text changes. A name several elements share (`edit` on every row's button) is kept only as a hint alongside the element's position. In a list that can be reordered, name each item (`data-markup-anchor="todo-42"`) so a pin follows its item rather than its position. |
+| `data-markup-source` | A repository-relative path. The nearest one above the pinned element is stored with the thread, shown in the dashboard, and returned to agents by the MCP server's `get_thread` as `anchorSource`. Values over 512 characters are ignored.                                                                                                                                                                                                                                                                    |
+
+Without a name, a pin in a list that was reordered or filtered still finds
+its item when the pinned text is unique in the list, such as a title. It can't
+tell identical controls apart: a pin on one of several **Edit** buttons stays
+with whichever row now holds its old position. Name the items to cover that
+case.
+
+Both are read from your page as it is, so keep them accurate: an agent is told
+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.
@@ -448,16 +486,16 @@ init({
 
 There is no `fab` option any more. It's accepted, ignored, and warns once. Drop it if you find one in my config.
 
-For React/Vue/Solid hosts, call `init()` from a mount lifecycle hook
-(`useEffect`, `onMounted`, `onMount`) and call the returned `destroy` on
-cleanup. There's no framework-specific entrypoint; `init` is the whole
-public API.
+For React or Vue, use `useMarkup` from `@pixelmatters/markup/react` or
+`@pixelmatters/markup/vue` once near the app root. For Solid and others, call
+`init()` from a mount lifecycle hook (`onMount`) and call the returned
+`destroy` on cleanup.
 
 For a `<script>` tag drop-in (no bundler), use the inline ESM form and **pin the version**:
 
 ```html
 <script type="module">
-  import { init } from 'https://esm.sh/@pixelmatters/markup@1.27.3'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.28.0'
 
   init({
     apiUrl: '...',
@@ -473,7 +511,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.27.3"
+  src="https://esm.sh/@pixelmatters/markup@1.28.0"
   data-markup-widget="true"
   data-api-url="..."
   data-api-key="..."

package/dist/react.d.ts

@@ -0,0 +1,21 @@
+import { WidgetConfig } from './widget';
+export type { WidgetConfig } from './widget';
+export type UseMarkupOptions = WidgetConfig & {
+    /**
+     * `false` unmounts the widget, or never mounts it. Drive it from your build
+     * environment to keep the widget off production.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+};
+/**
+ * Mounts the widget for as long as the calling component is mounted. Call it
+ * once near your app root.
+ *
+ * An inline options object is fine: the widget remounts only when a value
+ * changes, not when the object is recreated. Two components using the same
+ * options share one widget, and it stays until both unmount. Server rendering
+ * mounts nothing.
+ */
+export declare function useMarkup(options: UseMarkupOptions): void;

package/dist/react.js

@@ -0,0 +1,15 @@
+"use client";
+import { init as e, t } from "./widget.js";
+import { t as n } from "./shared-mount-DABK4arh.js";
+import { useEffect as r } from "react";
+//#region src/react.ts
+function i(i) {
+	let { enabled: a = !0, ...o } = i, s = a ? t(o) : null;
+	r(() => {
+		if (s !== null) return n(s, e);
+	}, [s]);
+}
+//#endregion
+export { i as useMarkup };
+
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","names":[],"sources":["../src/react.ts"],"sourcesContent":["'use client'\n\nimport { useEffect } from 'react'\n\nimport { configKey } from './runtime/config-key'\nimport { acquireMount } from './runtime/shared-mount'\nimport { init, type WidgetConfig } from './widget'\n\nexport type { WidgetConfig } from './widget'\n\nexport type UseMarkupOptions = WidgetConfig & {\n  /**\n   * `false` unmounts the widget, or never mounts it. Drive it from your build\n   * environment to keep the widget off production.\n   *\n   * @default true\n   */\n  enabled?: boolean\n}\n\n/**\n * Mounts the widget for as long as the calling component is mounted. Call it\n * once near your app root.\n *\n * An inline options object is fine: the widget remounts only when a value\n * changes, not when the object is recreated. Two components using the same\n * options share one widget, and it stays until both unmount. Server rendering\n * mounts nothing.\n */\nexport function useMarkup(options: UseMarkupOptions): void {\n  const { enabled = true, ...config } = options\n  const key = enabled ? configKey(config) : null\n\n  useEffect(() => {\n    if (key === null) return\n    return acquireMount(key, init)\n  }, [key])\n}\n"],"mappings":";;;;;AA6BA,SAAgB,EAAU,GAAiC;CACzD,IAAM,EAAE,aAAU,IAAM,GAAG,MAAW,GAChC,IAAM,IAAU,EAAU,CAAM,IAAI;CAE1C,QAAgB;EACV,UAAQ,MACZ,OAAO,EAAa,GAAK,CAAI;CAC/B,GAAG,CAAC,CAAG,CAAC;AACV"}

package/dist/shared-mount-DABK4arh.js

@@ -0,0 +1,27 @@
+//#region src/runtime/shared-mount.ts
+var e = /* @__PURE__ */ new Map();
+function t(t, n) {
+	let r = n(JSON.parse(t)), i = (e.get(t)?.count ?? 0) + 1;
+	e.delete(t), e.set(t, {
+		count: i,
+		dispose: r
+	});
+	let a = !1;
+	return () => {
+		if (a) return;
+		a = !0;
+		let r = e.get(t);
+		if (!r || (--r.count, r.count > 0)) return;
+		e.delete(t), r.dispose();
+		let i = [...e.entries()].at(-1);
+		if (i) try {
+			i[1].dispose = n(JSON.parse(i[0]));
+		} catch (e) {
+			i[1].dispose = () => {}, console.warn("[markup] could not remount the widget", e);
+		}
+	};
+}
+//#endregion
+export { t };
+
+//# sourceMappingURL=shared-mount-DABK4arh.js.map

package/dist/shared-mount-DABK4arh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-mount-DABK4arh.js","names":[],"sources":["../src/runtime/shared-mount.ts"],"sourcesContent":["import type { WidgetConfig } from '../widget'\n\ntype Holder = { count: number; dispose: () => void }\n\nconst holders = new Map<string, Holder>()\n\n/**\n * Counts hook holders per config, so the first of two components to unmount\n * doesn't take the widget away from the other. `init` still runs on every\n * acquire: it is a no-op for the live config, and it remounts one that a\n * different config has since replaced.\n *\n * Holders of different configs contend for the one widget, and the latest to\n * acquire wins. When it lets go, the most recent remaining config is mounted\n * again, so no holder is left without a widget while it still wants one.\n */\nexport function acquireMount(key: string, init: (config: WidgetConfig) => () => void): () => void {\n  const dispose = init(JSON.parse(key) as WidgetConfig)\n  const count = (holders.get(key)?.count ?? 0) + 1\n  // Re-inserted so the map's order is recency, which the release path reads.\n  holders.delete(key)\n  holders.set(key, { count, dispose })\n\n  let isReleased = false\n  return () => {\n    if (isReleased) return\n    isReleased = true\n    const current = holders.get(key)\n    if (!current) return\n    current.count -= 1\n    if (current.count > 0) return\n    holders.delete(key)\n    current.dispose()\n    const survivor = [...holders.entries()].at(-1)\n    if (!survivor) return\n    // This runs inside some other component's cleanup; a failure to bring\n    // the survivor back must not surface as that component's error.\n    try {\n      survivor[1].dispose = init(JSON.parse(survivor[0]) as WidgetConfig)\n    } catch (error) {\n      survivor[1].dispose = () => {}\n      console.warn('[markup] could not remount the widget', error)\n    }\n  }\n}\n"],"mappings":";AAIA,IAAM,oBAAU,IAAI,IAAoB;AAYxC,SAAgB,EAAa,GAAa,GAAwD;CAChG,IAAM,IAAU,EAAK,KAAK,MAAM,CAAG,CAAiB,GAC9C,KAAS,EAAQ,IAAI,CAAG,CAAC,EAAE,SAAS,KAAK;CAG/C,AADA,EAAQ,OAAO,CAAG,GAClB,EAAQ,IAAI,GAAK;EAAE;EAAO;CAAQ,CAAC;CAEnC,IAAI,IAAa;CACjB,aAAa;EACX,IAAI,GAAY;EAChB,IAAa;EACb,IAAM,IAAU,EAAQ,IAAI,CAAG;EAG/B,IAFI,CAAC,MACL,IAAQ,OACJ,EAAQ,QAAQ,IAAG;EAEvB,AADA,EAAQ,OAAO,CAAG,GAClB,EAAQ,QAAQ;EAChB,IAAM,IAAW,CAAC,GAAG,EAAQ,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE;EACxC,OAGL,IAAI;GACF,EAAS,EAAE,CAAC,UAAU,EAAK,KAAK,MAAM,EAAS,EAAE,CAAiB;EACpE,SAAS,GAAO;GAEd,AADA,EAAS,EAAE,CAAC,gBAAgB,CAAC,GAC7B,QAAQ,KAAK,yCAAyC,CAAK;EAC7D;CACF;AACF"}

package/dist/vue.d.ts

@@ -0,0 +1,23 @@
+import { MaybeRefOrGetter } from 'vue';
+import { WidgetConfig } from './widget';
+export type { WidgetConfig } from './widget';
+export type UseMarkupOptions = WidgetConfig & {
+    /**
+     * `false` unmounts the widget, or never mounts it. Drive it from your build
+     * environment to keep the widget off production.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+};
+/**
+ * Mounts the widget for as long as the calling component is mounted. Call it
+ * once from your root component's `setup`.
+ *
+ * Pass a plain object, a ref, or a getter. The widget remounts only when a
+ * value changes, not when the object is replaced by an equal one. Two
+ * components using the same options share one widget, and it stays until
+ * both unmount. Nothing mounts during server rendering, since mounting waits
+ * for `onMounted`.
+ */
+export declare function useMarkup(options: MaybeRefOrGetter<UseMarkupOptions>): void;

package/dist/vue.js

@@ -0,0 +1,21 @@
+import { init as e, t } from "./widget.js";
+import { t as n } from "./shared-mount-DABK4arh.js";
+import { computed as r, onBeforeUnmount as i, onMounted as a, toValue as o, watch as s } from "vue";
+//#region src/vue.ts
+function c(c) {
+	let l = r(() => {
+		let { enabled: e = !0, ...n } = o(c);
+		return e ? t(n) : null;
+	}), u = null, d = (t) => {
+		u?.(), u = t === null ? null : n(t, e);
+	}, f = null;
+	a(() => {
+		d(l.value), f = s(l, d);
+	}), i(() => {
+		f?.(), d(null);
+	});
+}
+//#endregion
+export { c as useMarkup };
+
+//# sourceMappingURL=vue.js.map

package/dist/vue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vue.js","names":[],"sources":["../src/vue.ts"],"sourcesContent":["import { computed, onBeforeUnmount, onMounted, toValue, watch, type MaybeRefOrGetter } from 'vue'\n\nimport { configKey } from './runtime/config-key'\nimport { acquireMount } from './runtime/shared-mount'\nimport { init, type WidgetConfig } from './widget'\n\nexport type { WidgetConfig } from './widget'\n\nexport type UseMarkupOptions = WidgetConfig & {\n  /**\n   * `false` unmounts the widget, or never mounts it. Drive it from your build\n   * environment to keep the widget off production.\n   *\n   * @default true\n   */\n  enabled?: boolean\n}\n\n/**\n * Mounts the widget for as long as the calling component is mounted. Call it\n * once from your root component's `setup`.\n *\n * Pass a plain object, a ref, or a getter. The widget remounts only when a\n * value changes, not when the object is replaced by an equal one. Two\n * components using the same options share one widget, and it stays until\n * both unmount. Nothing mounts during server rendering, since mounting waits\n * for `onMounted`.\n */\nexport function useMarkup(options: MaybeRefOrGetter<UseMarkupOptions>): void {\n  const key = computed(() => {\n    const { enabled = true, ...config } = toValue(options)\n    return enabled ? configKey(config) : null\n  })\n\n  let release: (() => void) | null = null\n  const apply = (next: string | null) => {\n    release?.()\n    release = next === null ? null : acquireMount(next, init)\n  }\n\n  let stopWatching: (() => void) | null = null\n  onMounted(() => {\n    apply(key.value)\n    stopWatching = watch(key, apply)\n  })\n  onBeforeUnmount(() => {\n    stopWatching?.()\n    apply(null)\n  })\n}\n"],"mappings":";;;;AA4BA,SAAgB,EAAU,GAAmD;CAC3E,IAAM,IAAM,QAAe;EACzB,IAAM,EAAE,aAAU,IAAM,GAAG,MAAW,EAAQ,CAAO;EACrD,OAAO,IAAU,EAAU,CAAM,IAAI;CACvC,CAAC,GAEG,IAA+B,MAC7B,KAAS,MAAwB;EAErC,AADA,IAAU,GACV,IAAU,MAAS,OAAO,OAAO,EAAa,GAAM,CAAI;CAC1D,GAEI,IAAoC;CAKxC,AAJA,QAAgB;EAEd,AADA,EAAM,EAAI,KAAK,GACf,IAAe,EAAM,GAAK,CAAK;CACjC,CAAC,GACD,QAAsB;EAEpB,AADA,IAAe,GACf,EAAM,IAAI;CACZ,CAAC;AACH"}