@pixelmatters/markup 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pixelmatters
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# @pixelmatters/markup
+
+[![npm](https://img.shields.io/npm/v/@pixelmatters/markup.svg)](https://www.npmjs.com/package/@pixelmatters/markup)
+[![license](https://img.shields.io/npm/l/@pixelmatters/markup.svg)](./LICENSE)
+[![bundle](https://img.shields.io/bundlephobia/minzip/@pixelmatters/markup)](https://bundlephobia.com/package/@pixelmatters/markup)
+
+Pin-anchored feedback for live web apps. Drop in a script tag (or one React component) and your stakeholders can leave threaded comments, reactions, and annotated screenshots on top of any page — without touching the host's CSS, build, or routing.
+
+## Highlights
+
+- **Pin anywhere** — click anywhere on the page to attach a comment to that exact element. Pins re-anchor across reflow using a CSS selector + viewport-fraction fallback.
+- **Threads, in real time** — replies stream in via WebSocket. Per-comment edit, delete (with tombstones), and emoji reactions.
+- **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 / Chrome storage partitioning. Verified users get a team badge.
+- **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.
+- **SPA-aware** — patches `history.pushState` / `replaceState` and follows `popstate` to refresh threads on route changes.
+- **Respects the platform** — honours `prefers-reduced-motion` and `prefers-color-scheme`; full keyboard navigation with focus traps in popovers.
+- **Tiny surface, tiny config** — `init({ apiUrl, apiKey })` is enough to start. No global CSS to import, no provider to wrap.
+
+Built with [Preact](https://preactjs.com). Ships as ESM with a vanilla entry and a React/Preact wrapper.
+
+## Install
+
+```bash
+# pnpm
+pnpm install @pixelmatters/markup
+# or yarn
+yarn add @pixelmatters/markup
+# or npm
+npm install @pixelmatters/markup
+```
+
+CDN drop-in (auto-init on `DOMContentLoaded`):
+
+```html
+<script
+  type="module"
+  src="https://unpkg.com/@pixelmatters/markup"
+  data-markup-widget="true"
+  data-api-url="https://your-deployment.convex.site"
+  data-api-key="markup_..."
+  data-position="bottom-right"
+></script>
+```
+
+The `data-markup-widget="true"` attribute is required — it's how the bootstrap locates its own `<script>` tag (since `document.currentScript` is `null` for `type="module"`).
+
+## Quickstart
+
+### Vanilla JS / TypeScript
+
+```ts
+import { init, destroy } from '@pixelmatters/markup'
+
+const stop = init({
+  apiUrl: 'https://your-deployment.convex.site',
+  apiKey: 'markup_...',
+  position: 'bottom-right', // optional
+  theme: 'light', // optional
+})
+
+// Tear down on logout / route change / page unload:
+stop() // equivalent to destroy()
+```
+
+### React / Preact
+
+```tsx
+import { MarkupWidget } from '@pixelmatters/markup/react'
+
+export default function App() {
+  return (
+    <>
+      {/* your app */}
+      <MarkupWidget
+        apiUrl={import.meta.env.VITE_MARKUP_API_URL}
+        apiKey={import.meta.env.VITE_MARKUP_KEY}
+        position="bottom-right" // optional
+        theme="light" // optional
+      />
+    </>
+  )
+}
+```
+
+## API
+
+### `init(config) → destroy`
+
+Mounts the widget. Idempotent: re-calling with the same config is a no-op; calling with a different config tears down the previous instance first. 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-right'` | Where the floating action button sits                                                                   |
+| `theme`    | `'light' \| 'dark' \| 'auto'`     | `'auto'`         | Visual theme — `'light'` or `'dark'`, or `'auto'` (default) to follow the host's `prefers-color-scheme` |
+
+### `destroy()`
+
+Unmounts the widget and removes the host element. Safe to call when nothing is mounted.
+
+### Keyboard
+
+| Shortcut           | Action                                          |
+| ------------------ | ----------------------------------------------- |
+| `cmd/ctrl + .`     | Toggle HUD visibility                           |
+| `cmd/ctrl + click` | Click the FAB to hide the HUD with a hint toast |
+
+## How it works
+
+- 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.
+- 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. New visitors get a random `clientId` so the backend can group their comments across sessions.
+
+## Identity
+
+Anonymous by default, with two opt-in upgrade paths:
+
+- **Sign in with Markup** — opens a popup to `${apiUrl}/widget/auth`. 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 JWT-backed verified identity back to the host page, which persists it under `markup.identity`.
+- **Continue as a guest** — name (and optional email), stored under the same key without `isVerified`.
+
+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.
+
+> **Why a popup, not auto-detect?** Safari ITP, Chrome Storage Partitioning, and Firefox TCP all partition third-party storage and cookies by top-level site. A cross-origin fetch from `customer.com` to `convex.site` cannot see the dashboard session. The popup is the only reliable way to bridge identity across sites without per-host configuration.
+
+## Getting an API key
+
+1. Sign in to the Markup dashboard.
+2. Open your project → **Settings → API Keys**.
+3. Click **New key**, label it, and copy the raw key — it's shown once.
+4. Open **Settings → Domains** and add the host domain (`app.example.com`, `*.staging.example.com`). `localhost` is auto-allowed in dev.
+
+## Browser support
+
+Modern evergreen browsers (Chrome, Edge, Firefox, Safari) and their mobile equivalents. The widget uses native ESM, shadow DOM, and `IntersectionObserver` — no IE11 / legacy bundle.
+
+## Development
+
+```bash
+pnpm dev          # vite dev server with the playground page
+pnpm build        # production build → dist/{widget,react}.{js,d.ts}
+pnpm typecheck    # tsc --noEmit
+```
+
+To test against a local Convex deployment, pass the printed `convex.site` URL as `apiUrl`.
+
+## License
+
+[MIT](./LICENSE) © Pixelmatters
+
+Issues and PRs welcome at [Pixelmatters/markup](https://github.com/Pixelmatters/markup).

package/dist/react.d.ts

@@ -0,0 +1,21 @@
+import { WidgetTheme } from './widget';
+export interface MarkupWidgetProps {
+    /** Convex deployment site URL, e.g. `https://your-deployment.convex.site` */
+    apiUrl: string;
+    /** Raw API key minted from a project's settings page */
+    apiKey: string;
+    /** Where the floating button sits. Defaults to bottom-right. */
+    position?: 'bottom-right' | 'bottom-left';
+    /** 'light' | 'dark' | 'auto' (default 'auto' — follow prefers-color-scheme) */
+    theme?: WidgetTheme;
+}
+/**
+ * React-host entrypoint. Renders nothing — the actual UI mounts itself into
+ * a sibling shadow DOM at `document.body` so it never tangles with the host
+ * tree's CSS.
+ *
+ * `useEffect` is imported from `react`, which the consumer's bundler
+ * resolves: real React in a React app, or `preact/hooks` re-exported via
+ * `preact/compat` in a Preact app that has aliased `react` → `preact/compat`.
+ */
+export declare function MarkupWidget(props: MarkupWidgetProps): null;