@pixelmatters/markup 1.14.0 → 1.16.0

package/README.md

@@ -35,34 +35,32 @@ 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.14.0'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.16.0'
   // or
-  // import { init } from 'https://esm.run/@pixelmatters/markup@1.14.0'
+  // import { init } from 'https://esm.run/@pixelmatters/markup@1.16.0'
 
   init({
     apiUrl: 'https://your-deployment.convex.site',
     apiKey: 'markup_...',
     position: 'bottom-right', // optional: 'bottom-right' | 'bottom-left' | 'bottom-center'
     theme: 'auto', // optional: 'auto' | 'light' | 'dark'
-    fab: 'default', // optional: 'default' | 'icon-only'
   })
 </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.14.0`).
+> **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.16.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.14.0"
+  src="https://esm.sh/@pixelmatters/markup@1.16.0"
   data-markup-widget="true"
   data-api-url="https://your-deployment.convex.site"
   data-api-key="markup_..."
   data-position="bottom-right"
   data-theme="auto"
-  data-fab="default"
 ></script>
 ```
 
@@ -80,7 +78,6 @@ const stop = init({
   apiKey: 'markup_...',
   position: 'bottom-right', // optional: 'bottom-right' | 'bottom-left' | 'bottom-center'
   theme: 'light', // optional: 'auto' | 'light' | 'dark'
-  fab: 'default', // optional: 'default' | 'icon-only'
 })
 
 // Tear down on logout / route change / page unload:
@@ -100,7 +97,6 @@ export default function App() {
       apiKey: import.meta.env.VITE_MARKUP_API_KEY,
       position: 'bottom-right', // optional: 'bottom-right' | 'bottom-left' | 'bottom-center'
       theme: 'auto', // optional: 'auto' | 'light' | 'dark'
-      fab: 'default', // optional: 'default' | 'icon-only'
     })
   }, [])
 
@@ -122,7 +118,6 @@ onMounted(() => {
     apiKey: import.meta.env.VITE_MARKUP_API_KEY,
     position: 'bottom-right', // optional: 'bottom-right' | 'bottom-left' | 'bottom-center'
     theme: 'auto', // optional: 'auto' | 'light' | 'dark'
-    fab: 'default', // optional: 'default' | 'icon-only'
   })
 })
 onBeforeUnmount(() => stop?.())
@@ -142,7 +137,6 @@ export default function App() {
       apiKey: import.meta.env.VITE_MARKUP_API_KEY,
       position: 'bottom-right', // optional: 'bottom-right' | 'bottom-left' | 'bottom-center'
       theme: 'auto', // optional: 'auto' | 'light' | 'dark'
-      fab: 'default', // optional: 'default' | 'icon-only'
     })
     onCleanup(stop)
   })
@@ -157,13 +151,12 @@ export default function App() {
 
 Mounts the widget. Always tears down any existing instance before mounting, so calling `init` again (with the same or a different config) is safe. Returns the `destroy` function.
 
-| Option     | Type                                                 | Default          | Description                                                                                                                           |
-| ---------- | ---------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `apiUrl`   | `string`                                             | required         | Convex deployment site URL (`https://*.convex.site`)                                                                                  |
-| `apiKey`   | `string`                                             | required         | Project API key — mint one in the dashboard                                                                                           |
-| `position` | `'bottom-right' \| 'bottom-left' \| 'bottom-center'` | `'bottom-right'` | Initial placement for the floating action button — users can drag it across the viewport thirds to snap between left / center / right |
-| `theme`    | `'light' \| 'dark' \| 'auto'`                        | `'auto'`         | Visual theme — `'light'` or `'dark'`, or `'auto'` (default) to follow the host's `prefers-color-scheme`                               |
-| `fab`      | `'default' \| 'icon-only'`                           | `'default'`      | Floating button variant — `'icon-only'` drops the "Markup" label for a circular icon button                                           |
+| Option     | Type                                                 | Default          | Description                                                                                                                                                                                                          |
+| ---------- | ---------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apiUrl`   | `string`                                             | required         | Convex deployment site URL (`https://*.convex.site`)                                                                                                                                                                 |
+| `apiKey`   | `string`                                             | required         | Project API key — mint one in the dashboard                                                                                                                                                                          |
+| `position` | `'bottom-right' \| 'bottom-left' \| 'bottom-center'` | `'bottom-right'` | Initial placement for the toolbar — users can move it with the Position picker in the toolbar's overflow menu                                                                                                        |
+| `theme`    | `'light' \| 'dark' \| 'auto'`                        | `'auto'`         | Initial theme — `'light'` or `'dark'`, or `'auto'` (default) to follow the host's `prefers-color-scheme`. Users can change this from the overflow menu; their choice persists and wins over this option from then on |
 
 ### `destroy()`
 
@@ -173,9 +166,10 @@ Unmounts the widget and removes the host element. Safe to call when nothing is m
 
 | Shortcut              | Action                                                                 |
 | --------------------- | ---------------------------------------------------------------------- |
+| `c`                   | Start placing a markup (ignored while typing)                          |
+| `esc`                 | Cancel placement, or close the open popover                            |
 | `cmd/ctrl + .`        | Toggle HUD visibility                                                  |
-| `cmd/ctrl + click`    | Click the FAB to hide the HUD with a hint toast                        |
-| Drag the FAB          | Snap it to whichever bottom corner the pointer ends in                 |
+| `cmd/ctrl + click`    | Click the toolbar's comment button to hide the HUD with a hint toast   |
 | Drag a popover header | Move the open thread / new-thread popover; resets to the pin on reopen |
 
 ## Screenshots & privacy
@@ -210,7 +204,7 @@ When a screenshot is attached in the composer, a chip shows how many fields were
 
 - The widget mounts `<div id="markup-widget">` on `document.body` and attaches an open shadow root.
 - All UI lives in that shadow root, with `:host { all: initial }` blocking style inheritance.
-- 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 FAB and active popovers opt back in to pointer events.
+- 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.
 - Pins are anchored as `(x, y)` fractions of the document plus a best-effort CSS selector (via [`@medv/finder`](https://github.com/antonmedv/finder)). The selector wins when it still resolves; the fraction is the fallback so pins survive layout changes.
 - Identity lives in **host-page** `localStorage` under `markup.identity`, keyed to the top-level site. On first load the widget mints a server-signed anonymous JWT via `POST /widget/anon-identity` so the backend can verify the `authorClientId` on every anon write — tampering with the cached `clientId` invalidates the signature. Verified identities upgrade to a `Bearer` JWT via the popup flow described below.
 
@@ -218,7 +212,7 @@ When a screenshot is attached in the composer, a chip shows how many fields were
 
 Anonymous by default, with two opt-in upgrade paths:
 
-- **Sign in with Markup** — the widget POSTs to `/widget/popup-exchange` with the apiKey + Origin gate, gets back a single-use 60-second code, then opens `${apiUrl}/widget/auth?code=…` in a popup. Because the popup is first-party to the deployment origin, the better-auth session cookie is sent normally (sidestepping third-party cookie blocks). The popup `postMessage`s a verified identity plus a 7-day server-signed `Bearer` JWT back to the host page, which persists them under `markup.identity` and attaches the JWT as `Authorization: Bearer` on subsequent writes. The apiKey never appears in the popup URL.
+- **Sign in with Markup** — the widget POSTs to `/widget/popup-exchange` with the apiKey + Origin gate, gets back a single-use 60-second code, then opens `${apiUrl}/widget/auth?code=…` in a popup. Because the popup is first-party to the deployment origin, the better-auth session cookie is sent normally (sidestepping third-party cookie blocks). The popup `postMessage`s a verified identity plus a short-lived server-signed `Bearer` JWT back to the host page, which attaches it as `Authorization: Bearer` on subsequent writes. Where partitioned (CHIPS) cookies are available the tokens are held in `HttpOnly` cookies and the session refreshes for up to 7 days; where they aren't, the widget falls back to `markup.identity` in the host page's `localStorage` and the session is capped at 24 hours, since a token stored there is readable by any script on the page. The apiKey never appears in the popup URL.
 - **Continue as a guest** — name (and optional email), stored alongside the server-issued anonymous `clientId` + JWT minted on first load.
 
 The popup origin is validated against the project's `allowedDomains` before any identity is returned, so only embeds on approved domains can resolve dashboard sessions. Verified JWTs can be invalidated before their TTL via the dashboard's "Sign out everywhere" action.
@@ -247,7 +241,7 @@ You are helping me install the **`@pixelmatters/markup`** feedback widget into m
 
 ## What it is
 
-A drop-in feedback widget published on npm as `@pixelmatters/markup`. It mounts a floating action button that lets users pin threaded comments (and optional annotated screenshots) anywhere on the page. It runs inside a shadow DOM so it doesn't affect host CSS.
+A drop-in feedback widget published on npm as `@pixelmatters/markup`. It mounts a compact toolbar that lets users pin threaded comments (and optional annotated screenshots) anywhere on the page. It runs inside a shadow DOM so it doesn't affect host CSS.
 
 ## My credentials
 
@@ -265,7 +259,6 @@ init({
   apiKey: string,                            // required
   position?: 'bottom-right' | 'bottom-left' | 'bottom-center', // default 'bottom-right'
   theme?: 'light' | 'dark' | 'auto',         // default 'auto'
-  fab?: 'default' | 'icon-only',             // default 'default'
 }) // returns a destroy() function — call it on unmount / logout / route teardown
 ```
 
@@ -278,14 +271,13 @@ 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.14.0'
+  import { init } from 'https://esm.sh/@pixelmatters/markup@1.16.0'
 
   init({
     apiUrl: '...',
     apiKey: '...',
     position: 'bottom-right',
     theme: 'auto',
-    fab: 'default',
   })
 </script>
 ```
@@ -295,12 +287,11 @@ 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.14.0"
+  src="https://esm.sh/@pixelmatters/markup@1.16.0"
   data-markup-widget="true"
   data-api-url="..."
   data-api-key="..."
   data-position="bottom-right"
-  data-fab="default"
 ></script>
 ```
 

package/dist/widget.d.ts

@@ -1,4 +1,10 @@
 export type WidgetTheme = 'light' | 'dark' | 'auto';
+/**
+ * @deprecated The floating action button was replaced by the toolbar
+ * pill, which has no variants. Kept so existing type imports keep
+ * compiling; it is no longer referenced by anything the widget renders
+ * and will be removed in the next major.
+ */
 export type WidgetFab = 'default' | 'icon-only';
 export interface ScreenshotsConfig {
     /** Disable screenshot capture entirely. Default: enabled. */
@@ -13,7 +19,10 @@ export interface WidgetConfig {
     apiUrl: string;
     /** Raw API key minted from a project's settings page */
     apiKey: string;
-    /** Where the floating button sits. Defaults to bottom-right. */
+    /**
+     * Initial corner for the toolbar. Defaults to bottom-right. Users can
+     * move it afterwards from the toolbar's overflow menu.
+     */
     position?: 'bottom-right' | 'bottom-left' | 'bottom-center';
     /**
      * Visual theme.
@@ -23,11 +32,11 @@ export interface WidgetConfig {
      */
     theme?: WidgetTheme;
     /**
-     * Floating action button variant.
-     * - `'default'` — pill button with icon + "Markup" label
-     * - `'icon-only'` — circular icon-only button (no label)
-     *
-     * Defaults to `'default'`.
+     * @deprecated Ignored. The floating action button was replaced by the
+     * toolbar pill, which has no variants, so neither `'default'` nor
+     * `'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.
      */
     fab?: WidgetFab;
     /** Screenshot capture and PII-scrub options. */