overplay 4.0.0

package/CHANGELOG.md

@@ -0,0 +1,194 @@
+# Changelog
+
+## 4.0.0 — 2026-10-17
+
+The package and code now use the Overplay name everywhere. This release has breaking changes.
+
+- New npm package: `overplay`. Run `npm uninstall @commentwidget/core` and `npm install overplay`. The old package gets no more releases.
+- New API names: `initOverplay()` replaces `initCommentWidget()`. The script-tag global is `Overplay` (`Overplay.init()`), not `CommentWidget`. The types are `OverplayConfig` and `OverplayAPI`. The old names are removed.
+- New built files: `dist/overplay.esm.js`, `dist/overplay.umd.js` and `dist/overplay.iife.js`.
+- New anchor attribute: use `data-overplay-anchor` in place of `data-comment-anchor`. Pins saved with the old attribute in their selector no longer find their component until you update your markup.
+- New browser storage keys (`overplay:*`). Widget settings, the saved name, launcher position and filters reset once. Local-only notes from the default store are not carried over; pass `new LocalStorageAdapter('comment-widget:<projectId>:comments')` to keep reading them. Hosted users sign in again once.
+- The widget host element has `data-overplay` in place of `data-comment-widget`.
+- Webhooks: the headers are now `X-Overplay-Event`, `X-Overplay-Delivery`, `X-Overplay-Timestamp` and `X-Overplay-Signature`. The signature scheme is unchanged. Update receivers that read the old `X-CommentWidget-*` headers.
+- Account exports use the format label `overplay-export`.
+- The source repository moves to `github.com/artemsvit/Overplay`. Old links redirect.
+
+## 3.13.0 — 2026-10-17
+
+- New name and look: the product is now **Overplay**. A new design system inspired by dock.us: one blue accent (`#0068f9`), near-black ink, cool gray surfaces, the Inter font (self-hosted), pill buttons, hairline borders and large rounded page panels.
+- Website: the landing hero is a blue panel with white type; the product preview sits in a gray dotted stage. Section headings are larger. Eyebrow labels use sentence case.
+- Dashboard: quieter sidebar with a gray active row, ink tabs, and accent text that stays readable in dark mode.
+- Widget: pill buttons, the new blue as the default `primaryColor`, and a near-black floating button. The Blue pin color is now the brand blue.
+- Emails, the sign-in window, dialogs, the link preview image, the touch icon and the email logo use the new brand.
+- The logo is the comment pin with a ring inside. Icon buttons are circles. Tabs and segmented controls are pills; the widget's Open / Resolved / All tabs fill the panel width.
+- Cloud: the old address `comments.artsvit.com` only redirects to `https://overplay.app` (301, or 308 for requests that send data). Sign in again on overplay.app, and reconnect MCP clients at `https://overplay.app/mcp`. Account emails come from `accounts@mail.overplay.app`. The widget calls `https://overplay.app` when `serverUrl` is the old address.
+- The landing hero keeps its dot grid and soft glow, without a frame. Dashboard rows show no gray hover; the sidebar uses Title Case and Upgrade Plan is a button.
+- Teams: the account owner creates teams, adds people by username, makes some of them team admins and gives each team chosen projects. Team members get access to those projects; team admins manage them. Each person uses one seat per project.
+- MCP Server page: setup first, then Project Access, then **Connections** and **Recent Activity** tabs. Recent Activity is a log of who used MCP, with which agent, in which project, and the result. Owners and admins see everyone's agent actions in their projects.
+- Cloud: MCP is part of Pro and Max. Free accounts see an upgrade banner; their connections are kept and work again after an upgrade. Community keeps MCP for everyone.
+- Cloud: Free now allows 2 members per project. Plan cards list MCP, and the Yearly switch shows **2 Months Free** with the price per month.
+- Widget: the comment menu holds only **Delete Comment**. Where a comment opens stays a Settings choice.
+
+## 3.12.0 — 2026-10-16
+
+- Search and filters in the widget panel. Search finds words in a note, its replies, the people who wrote them and the name of its element, and ignores case and accents. Matches are marked, and a row shows the reply or element that matched. Filter by **Open**, **Resolved** or **All**, by **Mine**, or by an author from the list. **This Page** and **All Pages** count what each view shows. **Clear Filters** brings the list back when no notes match. Escape clears the search, and **/** moves to it from anywhere in the panel. Pins on the page follow the filters. The filters stay while the browser tab is open.
+- Website: a public **Changelog** page at `/changelog`, built from this file. Every page footer links to it.
+- Website: on phones, a menu button in the header opens How it works, Pricing, Docs and Sign in (or Dashboard). Press Esc to close it.
+- Dashboard: new accounts see a **Get started** checklist on the Projects page: create a project, install the widget, leave a first comment, add a member and connect an AI agent. Done steps are checked from your account data. **Hide Checklist** hides it in this browser.
+- Cloud: Plan & billing shows meters for comments this UTC month, projects, and members in your largest project. The sidebar shows a compact version. At 80% and 100% of the monthly comment limit, the dashboard shows a banner and the account owner gets one email per threshold each month.
+- Cloud: optional yearly billing for Pro ($150/year) and Max ($300/year), tax included. A Monthly/Yearly switch appears on /pricing and Plan & billing once the yearly Paddle prices are configured (`PADDLE_PRICE_ID_YEARLY`, `PADDLE_MAX_PRICE_ID_YEARLY`).
+- Cloud: Plan & billing has a billing history with the date, plan, amount and status of each payment, and a **Download Invoice** button for the Paddle invoice PDF.
+- Workspace: a new **Team** page. The account owner adds admins by username. An admin manages every project of the owner (settings, websites, members, join requests, and moving or deleting any comment) but cannot delete projects, change billing, or add and remove admins. Admins use a member seat in each project; Free has no room for admins. Admins leave a team on the same page. MCP owner tools follow the same rules.
+- Workspace: a new **Activity** tab in each project, for the owner and admins. It lists member, request, website, settings, team and agent connection changes, comments deleted by someone other than their author, and agent comment actions, newest first. Events are kept for one year.
+- `CommentUser.role` accepts `admin`. The widget lets an admin move and delete every comment, like the owner. Older widget versions treat an admin as a member.
+- Workspace: a new **Account** page. Turn on two-factor authentication with an authenticator app (TOTP) and 10 one-time recovery codes; sign-in then asks for a code after the password. Download your data as one JSON file. Delete your account and everything you own in one step (blocked while a paid subscription is active).
+- New **Security** page (`/security`) and `/.well-known/security.txt`, linked from every footer. The Privacy Notice covers export, deletion and two-factor data.
+- Self-hosting: optional `TWO_FACTOR_KEY` encrypts two-factor secrets; `community/disable-two-factor.ts` turns two-factor off for a locked-out user.
+- Project integrations in **Settings → Integrations**: Slack messages, signed webhooks (HMAC-SHA256), and issues in GitHub, Linear or Jira, created by hand with **Create Issue** or for every new comment. Tokens stay on the server and are encrypted when `INTEGRATIONS_KEY` is set. Each integration shows its last delivery and has **Send Test**. Migration `0014_notifications.sql` is required. See [Integrations](docs/INTEGRATIONS.md).
+- Cloud: comment email per member and project in the new **Notifications** tab: instant, a daily digest from the daily cron, or off (the default).
+
+## 3.11.0 — 2026-10-16
+
+- Workspace: the **Members** list shows each member's email under their name, in place of "Can comment" and "You". Only the project owner sees this list. MCP `list_members` still leaves emails out.
+- The project owner can move and delete every comment in the project, in the widget and through the service. Members still move and delete only their own comments. Only the author can change a comment's text, and MCP agents keep the author-only rule. `CommentUser` has an optional `role` (`"owner"` or `"member"`); the hosted service sets it.
+
+## 3.10.1 — 2026-10-16
+
+- Workspace: the **MCP server** page has a new design. One card shows the server switch, its address and three steps to connect an agent. Each connection shows its status, projects and permissions at a glance, with **Edit Access** and a **New Token** button. Project access and recent activity use the same rows as the rest of the workspace. The sidebar shows the MCP logo.
+- A note on an item in a closed menu now shows **Element hidden**, not **Element removed**. Many menus (Radix, Headless UI, MUI, Vue) take closed items out of the page. A note that saved how its menu opens counts as hidden while the menu's button is on the page. It shows **Element removed** only when that button is gone too, or opening the menu does not bring the item back.
+- MCP `list_comments` and `search_comments` accept `includeReplies` sent as text (`"true"`), as agents with an older tool list do.
+- MCP `remove_member` says "Member not found." for a user who is not in the project. Before, it reported success.
+
+## 3.10.0 — 2026-10-16
+
+- MCP `list_comments` and `search_comments` return each comment's reply count and last reply time. Set `includeReplies` to get replies in the same call. Omit `projectId` to read every included project at once.
+- MCP `get_project` and `list_projects` show whether a project allows only its listed websites.
+- Saved element selectors no longer start from IDs that frameworks make at run time, such as Radix (`radix-_r_3p_`) or React `useId`. These IDs change on each page load.
+- The MCP connect window is compact and shows only the request. **Authorize** and **Cancel** stay visible at the bottom of the window. Connection forms in MCP settings keep their save button in view too.
+
+## 3.9.0 — 2026-10-16
+
+- Connect coding agents through the new MCP server, with OAuth sign-in or a manual token. Select projects and permissions for each connection, pause or revoke access, and switch all account MCP access off.
+- Agents can read and search comments and replies, retrieve saved element context and activity, post replies, create or edit their own pins, resolve threads, and perform separately permitted project administration.
+- MCP comments and replies show the agent name. Comment links can open the exact thread, and revision checks protect against stale agent edits.
+- Add an MCP section to the landing page. Cloudflare and Community use the same MCP tools and access controls.
+
+## 3.8.1 — 2026-10-16
+
+- Dropping the floating **Comments** button after a drag no longer opens the sidebar. Only a click opens it. (3.8.0 broke this.)
+
+## 3.8.0 — 2026-10-16
+
+- Pick the color of the floating **Comments** button in **Settings → Comments button**: the default dark button, the site color, or one of 8 colors. A live sample shows the button, also while the sidebar hides it. Each person's choice is saved per project in this browser, like the pin color. **Reset to Defaults** brings back the dark button.
+- Notes in menus open the menu again. Leave a note on an item in a dropdown, hamburger menu, drawer, submenu, tab, popover or dialog. The note saves how the menu was opened, and opening the note later (from the sidebar or **Show Element**) repeats it and shows the item. It works with native HTML, CSS-only menus (`:hover`, `:focus-within`, the checkbox hack, `:target`), Bootstrap, Radix/shadcn, Headless UI, MUI, Vue and hand-written menus. Links to other pages and form submits are never repeated.
+- The opened menu stays open while you read and reply. Presses and focus in the widget no longer count as a click outside the page's menu, and the widget moves into an open modal dialog or popover while its note is open.
+- You can add a note in an open menu with the **Add Comment** button; the menu no longer closes first.
+- An element in a closed `<details>`, in a collapsed accordion (`max-height: 0`), at opacity 0 or in a drawer moved off the screen now shows **Element hidden**. Before, these counted as shown.
+- If the menu cannot open, the note says which button to press, for example *Open “Menu” to see it* (a phone menu seen at desktop width).
+- Menus that hide the page from screen readers (`aria-hidden` on other elements) no longer hide the widget.
+
+## 3.7.0 — 2026-10-15
+
+- A comment now says what happened to its element. **Element hidden** names the element and the menu, tab or section that holds it, such as *Checkbox “Peanuts” in Filters*, with **Show Element**. **Element removed** says nothing on the page matches it now. Both show a dashed pin where the note was left; drag the pin to attach the note again. The list carries the same flag.
+- Each note saves a readable name for its element, so people who did not write the note still know which element it is.
+- A dragged pin hides its comment card and outlines the component under it, the same as placing a new note.
+- The update notice has a clearer design: the new version, your version and the install command with **Copy**. **×** hides it until the next version.
+- A click that a script makes on the page, such as **Show Element** opening a menu, no longer closes the open comment card.
+
+## 3.6.0 — 2026-10-15
+
+- Dark theme. The panel, comment cards, menus, notices and the launcher have a dark version. Choose **Light**, **Dark** or **System** in **Settings → Appearance**. System follows the device.
+- New `theme` option (`'light'`, `'dark'` or `'system'`, default `'light'`) sets the site's default. New `setTheme()` changes it later, for example when your site switches to dark mode. A theme a person picks in Settings still wins.
+- A comment whose element is hidden opens it: closed `<details>`, popovers, menus and accordions (a button with `aria-controls` and `aria-expanded="false"`) and tabs. New `revealComponent(comment, element)` hook lets a site show it itself, for example zoom a map to a marker. Set `autoReveal: false` to turn the automatic part off.
+- Each comment card in the list has the number at the right and the status under it, so cards line up and nothing moves when counts change.
+- The pick outline is a plain stroke, without a label or fill.
+- 3 more pin colors: Violet, Amber and Red.
+- Buttons use Title Case, for example **Add Comment** and **Post Comment**.
+- Comment fields hide their scrollbars.
+- Page names in "All Comments" use the page's main heading when the document title is the same generic name on every route, and show the path next to the name.
+
+## 3.5.0 — 2026-10-15
+
+- The panel header holds your account and **Settings**, next to close. Your picture (or initials) opens a menu with your name, **Edit your name** for guests, **Settings** and **Sign out**. The bottom bar is gone; it shows only when a new version is available.
+- **Settings** are per project and per person, saved in this browser. Choose the pin color, green or gray resolved pins, regular or small pins, numbers or author initials on pins, where comments open (next to the pin or in the sidebar), whether the panel pushes the page aside, activity notices and the keyboard shortcut. **Reset to defaults** goes back to the site's configuration.
+- Site options such as `pushContent`, `showNotifications` and `enableKeyboardShortcuts` are now the defaults that each person can change.
+- Avatars use the first letters of the first and last name, for example "AS".
+
+## 3.4.1 — 2026-10-15
+
+- The comment card matches the website demo. The header shows the note number and "Open conversation" or "Resolved conversation", with close and a **⋯** menu. The menu holds **Open in the sidebar** and **Delete comment**.
+- The open card ends with one reply line and **Resolve**. Once you type, the button becomes **Send reply**. Enter sends, and Shift+Enter starts a new line. A resolved card shows **Resolved** and **Reopen conversation**.
+- Pins stay on screen. A dragged pin cannot leave the screen or go under the sidebar. A pin at the top edge points up from below its spot, and a pin at a side edge slides in.
+- The new comment field has space above it again.
+
+## 3.4.0 — 2026-10-15
+
+- A comment opens in a card next to its pin, beside the component it is about. The card has the note number, its status, the messages, **Resolve** or **Reopen**, and a reply field. A new comment opens in the same card.
+- Prefer the sidebar? The dock button in the card's header opens the comment in the sidebar instead. The widget remembers the choice in this browser. The same button in the sidebar brings the card back next to the pin.
+- A click on the page closes the card, unless it holds text you have not sent. Escape still closes it.
+- Picking works like a browser inspector: the outline is solid, and a label names the element, for example `td · Line circuit breaker`.
+- A `data-comment-anchor` region that covers more than a quarter of the screen, such as a whole dashboard or app frame, no longer takes every click. The row, cell or control inside it gets the note. Smaller anchors, such as a card, still win.
+- Paths for elements inside a unique `data-comment-anchor` start at that anchor, so they survive layout changes outside it.
+- On phones the card is a bottom sheet.
+
+## 3.3.0 — 2026-10-15
+
+- A click now attaches the note to the element under the pointer: the button, link, field, heading, paragraph, image or icon. Before, any parent with an `id` (such as `#root`, `#__next` or `#main`) took the click, so many notes attached to the whole page frame.
+- Text inside a paragraph or heading attaches to that paragraph or heading. Icon parts attach to the whole icon. Explicit `data-comment-anchor` keys still win.
+- While you place a note, a dashed outline shows the element the note will attach to.
+- A click on empty page space no longer fails with "Choose a visible page element". The note attaches to the page.
+- Comment cards in the sidebar are more compact. The note number and status sit on the right of the author line. Text shows two lines.
+- Hover or focus a comment in the sidebar to find it on the page: its pin pulses and its element gets a dashed outline.
+- **All comments** groups other pages by their page title. A comment saves `pageTitle` (the page's `document.title`). Older comments without a title still show the path.
+- Removed the "Feedback that stays in context." subtitle. Error messages have space above them again.
+- Hosted service: new migration `0007_comment_page_title.sql` stores the page title.
+
+## 3.2.0 — 2026-10-15
+
+- Drag a pin to move it. The **Move pin** button and its placement step are gone. A short click still opens the comment. `canMove` still decides who can drag.
+- The open comment has a clearer header: a "Comments" back link and close on one bar, then the note number with an Open or Resolved status chip.
+- While a comment is open, the other pins on the page fade to 30%. Hover a pin to see it at full strength.
+- **Resolve** has a green check and no longer wraps. Delete asks for confirmation with **Keep** and a red **Delete** button.
+- The sidebar shows **New update available** next to your name when npm has a newer version. A browser cannot update a site's code, so a click copies `npm install @commentwidget/core@latest`. By default only development hosts (`localhost`, `*.local`, `*.test`) check, at most every 12 hours. Set `updateNotice: true` or `false` to change this.
+
+## 3.1.0 — 2026-10-15
+
+- Comments open in a full-height sidebar instead of a small pop-up. Threads, replies and new comments use the whole sidebar, and the floating button hides while it is open, so nothing covers the comment field.
+- The open sidebar pushes the page aside instead of covering it, so you can still comment on every part of the page. Set `pushContent: false` to keep it above the page. On phones it fills the screen.
+- Drag the floating comment button anywhere on the screen. The widget remembers the place in this browser. A short press still opens the sidebar.
+- The sidebar has two views: **Page comments** (this page) and **All comments** (every page of the site, grouped by page). Select a comment from another page to go to that page. The sidebar opens there with the comment, and its pin and component are highlighted.
+- A clearer refresh icon, shown as an outlined button next to **Add a comment**.
+- Hosted service: `GET /api/comments` without `pageUrl` returns the comments of every page in the project. The widget uses it for **All comments**. Deploy the service together with the widget.
+- `hideSidebar: true` now shows the sidebar only for an open thread or a new comment, with no list.
+
+## 3.0.0 — 2026-10-15
+
+This is a major version because two defaults change for existing sites: the toggle shortcut, and the page ID for URLs with in-page anchors. To keep 2.x behavior, set `keyboardShortcut: 'c'` and a `getPageId` function that keeps the hash. Update install commands from `@^2` to `@^3`.
+
+- The overlay no longer flashes when comments refresh. The panel and thread keep their place, and only the refresh icon spins. A background check that finds no change does not redraw anything.
+- When someone else adds a comment or reply, a short notification appears near the comment button. It has no actions and hides after 7 seconds. Set `showNotifications: false` to turn it off.
+- The default toggle shortcut is now Alt+Shift+C (Option+Shift+C on Mac) instead of the single key C, so it is not triggered by accident (WCAG 2.1.4). `keyboardShortcut` accepts modifier combinations such as `ctrl+shift+k`. Set `keyboardShortcut: 'c'` to keep the old behavior.
+- The default page ID no longer includes in-page anchors such as `#pricing`, so pins stay visible after anchor links. Hash routes such as `#/settings` remain separate pages. Local notes saved with an anchor still show. Hosted notes saved with an anchor are stored under the old page ID; set `getPageId` to keep the previous behavior.
+- Searching comments and background updates no longer rebuild text fields while you type, so IME input, undo history and screen reader focus are kept. Errors are announced once.
+- The widget no longer fails to start on plain-HTTP pages outside localhost. It no longer needs `crypto.randomUUID`, which browsers offer only on HTTPS.
+- Placement instructions now explain the keyboard method: Tab to an element and press Enter.
+- Hosted sign-in survives network errors and HTML error pages from proxies. A 403 from an author-only action no longer signs the user out.
+- Community server: set `TRUSTED_PROXY=1` behind a reverse proxy so rate limits apply per client (`compose.yaml` sets it). Request bodies are read before the request is queued, so a slow upload no longer blocks other requests.
+
+## 2.0.0 — 2026-10-15
+
+- Replaced the React overlay with a framework-independent widget and isolated Shadow DOM styles. No runtime dependencies or separate CSS import are required.
+- Added hosted account sign-in and shared comments through `serverUrl` and a dashboard project ID. Custom REST and storage adapters remain available.
+- Attached pins to stable page components with relative positions. Pins follow responsive layouts, resizing, remounts and scrolling. Authors can move an existing pin without replacing the comment.
+- Increased text sizes and reduced the floating launcher to an icon and comment counter.
+- Added stable guest identities, author permissions, idempotent mutation retries and cross-tab local storage synchronization.
+- Kept drafts after save failures and added cleanup, route handling, safe navigation and SSR-safe imports.
+
+### Migration from 1.x
+
+- Initialize with `initCommentWidget(config)` after the page mounts, and call `destroy()` when it unmounts.
+- The widget no longer requires React/ReactDOM. Remove the old separate widget CSS import.
+- Use the hosted service, `APIAdapter`, or a working custom adapter instead of the former Firebase/Supabase placeholder adapters.
+- `usePortal` is deprecated. The overlay always uses an isolated portal; `container` restricts pin placement.
+- Existing local storage keys can be retained by explicitly constructing `LocalStorageAdapter` with the old key.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Overplay contributors
+
+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,139 @@
+<p align="center">
+  <img src="service/public/logo.svg" width="56" height="56" alt="Overplay logo">
+</p>
+
+<h1 align="center">Overplay</h1>
+
+<p align="center">
+  Leave comments on any element of your website. Your team sees them in context.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/overplay"><img src="https://img.shields.io/npm/v/overplay?color=575ce5" alt="npm version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-575ce5" alt="MIT license"></a>
+  <a href="https://overplay.app/"><img src="https://img.shields.io/badge/cloud-overplay.app-575ce5" alt="Cloud"></a>
+</p>
+
+<p align="center">
+  <a href="https://overplay.app/">Website</a> ·
+  <a href="https://overplay.app/docs">Docs</a> ·
+  <a href="docs/API.md">API reference</a> ·
+  <a href="docs/SELF_HOSTING.md">Self-host</a> ·
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
+
+---
+
+## Features
+
+- **Pins on components.** A note attaches to the element you click. It follows that element across layouts, resizes and re-renders.
+- **Notes in menus.** Leave a note on an item in a dropdown, hamburger menu, drawer, tab or popover. When someone opens the note later, the widget opens that menu again and shows the item. It works with any frontend: native HTML, CSS-only menus, Bootstrap, Radix/shadcn, Headless UI, MUI, Vue and hand-written menus.
+- **Full-height sidebar.** Read and reply to threads beside the page. Switch between **Page comments** and **All comments** for the whole site.
+- **Draggable launcher.** Move the comment button anywhere on the screen. Drag a pin to move a note.
+- **Team access.** Only project members can read and write. A new person who signs in sends a join request. The owner approves or declines it.
+- **Integrations and email.** Send comments to Slack or a signed webhook, and create issues in GitHub, Linear or Jira. Members choose instant email, a daily digest or none. See [Integrations](docs/INTEGRATIONS.md).
+- **AI Install.** The dashboard gives you a ready prompt. Paste it into Claude Code, Cursor, Copilot or another coding agent, and it installs the widget for you.
+- **No dependencies.** One script, no React and no CSS import. The UI lives in a Shadow DOM, so it does not change your page styles.
+
+## Quick start
+
+1. Create a free account at [overplay.app](https://overplay.app/) and create a project.
+2. Open **Install** in the project. Use **AI Install**, or follow the manual steps below.
+3. Open your site, sign in through the widget and leave a comment.
+
+### npm
+
+```sh
+npm install overplay
+```
+
+```ts
+import { initOverplay } from 'overplay';
+
+const widget = initOverplay({
+  serverUrl: 'https://overplay.app',
+  projectId: 'YOUR_PROJECT_ID',
+});
+
+// Call widget.destroy() when the page unmounts.
+```
+
+### Script tag
+
+```html
+<script src="https://overplay.app/widget.js"></script>
+<script>
+  Overplay.init({
+    serverUrl: 'https://overplay.app',
+    projectId: 'YOUR_PROJECT_ID',
+  });
+</script>
+```
+
+Place the script tag at the end of `<body>`, after your page content.
+
+The project ID is public. It grants no access by itself. On a new website address, a project member approves that address once at sign-in.
+
+**Tip:** add a stable `data-overplay-anchor` to your main components. Pins then stay on the right component across layouts.
+
+```html
+<section data-overplay-anchor="pricing">…</section>
+```
+
+### Without an account
+
+Omit `serverUrl` to keep notes in this browser only (localStorage). This is good for prototypes and private notes. You can also connect your own backend with the REST adapter or a custom storage adapter. See the [API reference](docs/API.md).
+
+## Pricing
+
+| | Community | Free | Pro | Max |
+| --- | --- | --- | --- | --- |
+| Price | Free, self-hosted | $0 | $15 / month | $30 / month |
+| Comments and replies per month | No limit | 10 | 1,000 | 5,000 |
+| Projects | No limit | 1 | 5 | 25 |
+| Members per project | No limit | 1 | 5 | 25 |
+| Hosting | Your server (Node.js or Docker) | Cloud | Cloud | Cloud |
+
+Cloud prices are in USD, before tax. Max has five times the Pro limits. Reading, moving and resolving comments is free. See [pricing](https://overplay.app/pricing).
+
+## Self-host (Community)
+
+Run the same service on your own server with Node.js 24+ or Docker and SQLite. There are no plans, quotas or license keys. You manage hosting, backups and updates. The MCP server for AI agents runs on your server too: add `https://your-server/mcp` as a remote MCP server (Claude connectors need HTTPS).
+
+```sh
+docker compose up --build -d
+```
+
+Read the [self-hosting guide](docs/SELF_HOSTING.md).
+
+## Keyboard
+
+| Key | Action |
+| --- | --- |
+| <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>C</kbd> (<kbd>Option</kbd> on Mac) | Open or close the widget |
+| <kbd>Esc</kbd> | Cancel |
+| <kbd>Enter</kbd> | Place a pin on the focused element |
+
+## Development
+
+```sh
+npm ci
+npm run dev        # demo page with local storage
+npm run typecheck
+npm run lint
+npm test
+npm run build
+```
+
+`npm run test:reveal` checks notes in menus in a real browser on 24 kinds of menus. It needs the `playwright`
+package and Chromium (`npm i --no-save playwright && npx playwright install chromium`).
+
+The hosted service (Cloudflare Worker + D1) is in [`service/`](service/README.md).
+
+## License
+
+[MIT](./LICENSE)
+
+## Connect a coding agent
+
+Overplay includes an account-level MCP server for reading feedback, retrieving saved element context, replying, and resolving threads. Choose projects and permissions in **MCP server**, directly below Projects. You can switch access off at any time. See [MCP setup and permissions](docs/MCP.md).

package/dist/index.d.ts

@@ -0,0 +1,229 @@
+/** A REST contract, not a hosted service. See README for server routes. */
+export declare class APIAdapter implements StorageAdapter {
+    private config;
+    constructor(config: APIAdapterConfig);
+    private request;
+    loadComments(): Promise<Comment_2[]>;
+    saveComments(comments: Comment_2[]): Promise<void>;
+    upsertComment(comment: Comment_2): Promise<void>;
+    deleteComment(id: string): Promise<void>;
+    addReply(id: string, reply: Reply): Promise<void>;
+    setResolved(id: string, resolved: boolean): Promise<void>;
+}
+
+export declare interface APIAdapterConfig {
+    baseUrl: string;
+    /** Called per request, allowing refreshed authentication tokens. */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    credentials?: RequestCredentials;
+    projectId?: string;
+    endpoints?: {
+        load?: string;
+        save?: string;
+    };
+}
+
+declare interface Comment_2 {
+    via?: string;
+    revision?: number;
+    updatedAt?: string;
+    id: string;
+    x: number;
+    y: number;
+    text: string;
+    author: string;
+    authorId?: string;
+    avatarUrl?: string;
+    timestamp: Date;
+    replies: Reply[];
+    resolved: boolean;
+    pageUrl: string;
+    /** The page's document title when the comment was made. Shown in "All comments". */
+    pageTitle?: string;
+    selector?: string;
+    /** Relative position inside the attached element, from 0 to 1. */
+    anchor?: {
+        x: number;
+        y: number;
+    };
+    /** A readable name for the attached element, saved when the note is made. It names the element after it is hidden or removed. */
+    element?: ElementInfo;
+}
+export { Comment_2 as Comment }
+
+export declare interface CommentPosition {
+    x: number;
+    y: number;
+}
+
+/** Hosted mode supplies the account. Custom adapters use stable IDs from the host app. */
+export declare interface CommentUser {
+    id: string;
+    name: string;
+    avatarUrl?: string;
+    /** "owner" and "admin" may move and delete every comment in the project; others only their own. The hosted service sets it. */
+    role?: 'owner' | 'admin' | 'member';
+}
+
+/** Such as { label: 'Checkbox “Peanuts”', place: 'Filters' }. `reveal` holds the steps that opened its menu when the note was made. */
+export declare interface ElementInfo {
+    label: string;
+    place?: string;
+    reveal?: RevealStep[];
+}
+
+/** Authenticated storage for the hosted Overplay service. Tokens are scoped to one project and website origin. */
+export declare class HostedAdapter implements StorageAdapter {
+    private projectId;
+    private page;
+    private sessionChanged;
+    private base;
+    private key;
+    private accessToken;
+    private expiresAt;
+    private initialized;
+    private pending?;
+    private cancelSignIn?;
+    user?: CommentUser;
+    constructor(serverUrl: string, projectId: string, page: () => string, sessionChanged: (user?: CommentUser) => void);
+    get signedIn(): boolean;
+    private clear;
+    private request;
+    private initialize;
+    signIn(): Promise<void>;
+    signOut(): Promise<void>;
+    destroy(): void;
+    loadComments(): Promise<Comment_2[]>;
+    subscribeToChanges(callback: (comments: Comment_2[]) => void): () => void;
+    saveComments(): Promise<void>;
+    upsertComment(comment: Comment_2): Promise<void>;
+    deleteComment(id: string): Promise<void>;
+    addReply(id: string, reply: Reply): Promise<void>;
+    setResolved(id: string, resolved: boolean): Promise<void>;
+}
+
+export declare const init: typeof initOverplay;
+
+/** Call after the document body exists, or in your framework's mount effect. */
+export declare function initOverplay(config?: OverplayConfig): OverplayAPI;
+
+export declare class LocalStorageAdapter implements StorageAdapter {
+    private storageKey;
+    constructor(storageKey?: string);
+    loadComments(): Promise<Comment_2[]>;
+    saveComments(comments: Comment_2[]): Promise<void>;
+    upsertComment(comment: Comment_2): Promise<void>;
+    deleteComment(id: string): Promise<void>;
+    addReply(id: string, reply: Reply): Promise<void>;
+    setResolved(id: string, resolved: boolean): Promise<void>;
+    private change;
+    subscribeToChanges(callback: (comments: Comment_2[]) => void): () => void;
+}
+
+export declare interface OverplayAPI {
+    /** Initial storage load. Errors are shown in the UI and sent to onError. */
+    ready: Promise<void>;
+    destroy(): void;
+    show(): void;
+    hide(): void;
+    startComment(position?: CommentPosition): void;
+    getAllComments(): Comment_2[];
+    getUser(): CommentUser;
+    /** Call on sign-in, sign-out, or account changes. Omit to restore the saved guest. */
+    setUser(user?: CommentUser): void;
+    signIn(): Promise<void>;
+    signOut(): Promise<void>;
+    refresh(): Promise<void>;
+    navigateToComment(id: string): void;
+    /** Changes the site's default theme, for example when the page switches to dark mode. A theme the person chose in Settings still wins. */
+    setTheme(theme: 'light' | 'dark' | 'system'): void;
+}
+
+export declare interface OverplayConfig {
+    /** Namespaces local comments and guest identity. Use a stable project ID. */
+    projectId?: string;
+    /** Defaults to localStorage. Supply an adapter for shared comments. */
+    storage?: StorageAdapter;
+    /** Hosted service origin. Requires its dashboard project ID; handles account sign-in. */
+    serverUrl?: string;
+    /** Without serverUrl, omit to create a guest identity saved in this browser. */
+    user?: CommentUser;
+    primaryColor?: string;
+    /** Color theme of the panel, cards and notices. "system" follows the device. Defaults to "light". Each person can change it in Settings. */
+    theme?: 'light' | 'dark' | 'system';
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    enableKeyboardShortcuts?: boolean;
+    keyboardShortcut?: string;
+    /** Only allow pins inside this element. UI stays in an isolated portal. */
+    container?: HTMLElement | null;
+    hideButton?: boolean;
+    hideSidebar?: boolean;
+    /** The open sidebar pushes the page aside instead of covering it. Defaults to true. Phones always show it full screen. */
+    pushContent?: boolean;
+    /** Show "New update available" in the sidebar when npm has a newer version. Defaults to development hosts only (localhost, *.local, *.test). */
+    updateNotice?: boolean;
+    /** Show a short notification when someone else adds a comment or reply. Defaults to true. */
+    showNotifications?: boolean;
+    /** @deprecated The isolated overlay always uses a portal. */
+    usePortal?: boolean;
+    /** Override route identity, for example to ignore tracking parameters. */
+    getPageId?: () => string;
+    onChange?: (comments: Comment_2[]) => void;
+    onError?: (error: Error) => void;
+    /**
+     * Called when someone opens a comment, before the widget looks for its component. Use it to show what hides the
+     * component, for example zoom a map to a marker with a data-overplay-anchor key. Return true when you handled it.
+     */
+    revealComponent?: (comment: Comment_2, element: Element | null) => boolean | void | Promise<boolean | void>;
+    /**
+     * Open the menu, drawer, tab or popover that hides a comment's component. A note saves the presses and hovers that
+     * opened it, and the widget repeats them. Older notes fall back to closed <details>, popovers and ARIA menus and tabs.
+     * Defaults to true. False also stops recording.
+     */
+    autoReveal?: boolean;
+    /** UI permission only. Enforce permissions again in your backend. */
+    canDelete?: (comment: Comment_2, user: CommentUser) => boolean;
+    /** Defaults to the comment author. Enforce this permission in your backend too. */
+    canMove?: (comment: Comment_2, user: CommentUser) => boolean;
+    /** CSP nonce for the style element inside the shadow root. */
+    nonce?: string;
+}
+
+export declare interface Reply {
+    via?: string;
+    id: string;
+    text: string;
+    author: string;
+    authorId?: string;
+    avatarUrl?: string;
+    timestamp: Date;
+    commentId: string;
+}
+
+/** One step that opens the menu, drawer, tab or popover holding a note's element. */
+declare interface RevealStep {
+    action: 'press' | 'hover' | 'focus';
+    target: RevealTarget;
+}
+
+/** An element to press or hover again: a selector, with its role and name as a second way to find it. */
+declare interface RevealTarget {
+    selector: string;
+    role?: string;
+    name?: string;
+    tag?: string;
+}
+
+export declare interface StorageAdapter {
+    loadComments(): Promise<Comment_2[]>;
+    /** Legacy snapshot fallback. For collaboration, implement individual mutations. */
+    saveComments(comments: Comment_2[]): Promise<void>;
+    upsertComment?(comment: Comment_2): Promise<void>;
+    deleteComment?(id: string): Promise<void>;
+    /** Implement atomically on a backend to avoid concurrent reply overwrites. */
+    addReply?(commentId: string, reply: Reply): Promise<void>;
+    setResolved?(commentId: string, resolved: boolean): Promise<void>;
+    subscribeToChanges?(callback: (comments: Comment_2[]) => void): () => void;
+}
+
+export { }