@perpetio/redline 2.1.1

package/README.md

@@ -0,0 +1,763 @@
+# Redline
+
+[![Redline — Point. Comment. Ship the fix. Visual website feedback with exact context for coding agents.](https://cdn.jsdelivr.net/npm/@perpetio/redline@2.1.1/docs/images/npm-banner.jpg)](https://redlinejs.com)
+
+**Point at the problem. Your agent ships the fix.**
+
+Redline adds visual feedback to any website. Highlight text, circle a detail,
+or pin a comment to the exact element. Share the feedback with your team, copy
+it into your coding agent, or connect the included MCP server so the agent can
+read, reply, and resolve comments directly.
+
+**No runtime dependencies · TypeScript included · No account needed for local reviews**
+
+[Try the live demo](https://redlinejs.com) · [Quick start](#quick-start) ·
+[Examples](#examples) · [Connect your agent](#ai-agents-mcp) ·
+[Configuration](#configuration) · [API](#javascript-api)
+
+## Quick start
+
+### Install from npm
+
+```bash
+npm install @perpetio/redline
+```
+
+Start Redline after your page has rendered:
+
+```js
+import Redline from '@perpetio/redline';
+
+Redline.init({
+  project: 'my-website',
+  startOpen: true,
+  spa: true,
+});
+
+// On unmount or hot reload, call Redline.destroy().
+```
+
+The review toolbar appears on your page. Press `P` and click an element to
+leave your first comment. Without `startOpen: true`, Redline starts as a small
+**Review** button. Use `spa: true` to keep separate comments for each route.
+
+### Or add one script tag
+
+No bundler needed. Paste this before `</body>`:
+
+```html
+<script
+  src="https://cdn.jsdelivr.net/npm/@perpetio/redline@2.1.1/redline.js"
+  data-project="my-website"
+  data-start-open="true"
+  defer
+></script>
+```
+
+That's the whole installation. Comments stay in the reviewer's browser until
+they export or send them. [Redline Cloud](https://app.redlinejs.com) is optional
+when you want a shared review with your team and clients.
+
+To self-host, download [redline.js](https://cdn.jsdelivr.net/npm/@perpetio/redline@2.1.1/redline.js)
+and use your own script URL. The same package is also available on
+[unpkg](https://unpkg.com/@perpetio/redline@2.1.1/redline.js).
+
+## From feedback to a fix
+
+![Redline running on a creative studio website: two comments anchored to page elements, a floating annotation toolbar, and the comments panel with Copy and Download controls.](https://cdn.jsdelivr.net/npm/@perpetio/redline@2.1.1/docs/images/npm-review.png)
+
+*An actual Redline review of the included playground. The comments are sample feedback.*
+
+| You do this | Redline carries the context |
+| --- | --- |
+| **Point at what needs changing.** Highlight text, draw a box, or pin a comment. | The element's label, selector, surrounding heading, position, and styles travel with the note. |
+| **Hand it to your coding agent.** Press `M` to copy Markdown, or connect over MCP. | In React, Vue, and Svelte development builds, the note can also name the component and source file. |
+| **Close the loop.** Your agent replies and updates the comment's status over MCP. | Reviewers see the reply and the resolved status on the same page. |
+
+## Examples
+
+The package includes a working playground and small integrations you can copy.
+
+| Start here | What you get |
+| --- | --- |
+| [Review playground](https://cdn.jsdelivr.net/npm/@perpetio/redline@2.1.1/examples/playground.html) | A complete HTML page to annotate, with **Pin a comment** and **Copy feedback for AI** buttons. |
+| [Minimal HTML](https://cdn.jsdelivr.net/npm/@perpetio/redline@2.1.1/examples/plain-html.html) | A small page with one CDN script tag. |
+| [React / Next.js component](https://cdn.jsdelivr.net/npm/@perpetio/redline@2.1.1/examples/react.jsx) | Mount once, follow route changes, and clean up on unmount. |
+| [Vue 3 component](https://cdn.jsdelivr.net/npm/@perpetio/redline@2.1.1/examples/vue.vue) | The same setup using `onMounted` and `onUnmounted`. |
+
+To run the playground after installing the package:
+
+```bash
+npx serve node_modules/@perpetio/redline --listen 4200
+```
+
+Open **http://localhost:4200/examples/playground.html**. This serves the installed
+package locally; no API key, build step, or review backend is required. The links
+above show the example source; use the local server to run the playground.
+
+### Add your own feedback button
+
+The public API also lets you connect review tools to your app's own controls:
+
+```js
+import Redline from '@perpetio/redline';
+
+Redline.init({ project: 'my-website', spa: true });
+
+// Call from your button's click handler:
+function leaveFeedback() {
+  Redline.setTool('pin');
+}
+
+// Read the open comments as Markdown for a coding agent:
+function getFeedbackForAgent() {
+  return Redline.markdown({ detail: 'detailed' });
+}
+```
+
+See [framework integration](#framework-integration) for React, Next.js, Vue,
+Svelte, Angular, WordPress, and other sites.
+
+---
+
+## Why Redline?
+
+- **One import or script tag.** No runtime dependencies, framework requirement, or account for local reviews.
+- **Useful context for coding agents.** Copy Markdown with element details, or use MCP to read, reply, and resolve feedback.
+- **Works everywhere.** Plain HTML, React, Vue, Svelte, WordPress, Webflow,
+  Shopify, static sites — anything that renders HTML in a browser.
+- **Local-first & private.** Comments stay on the reviewer's device until they
+  explicitly export or send feedback to an endpoint you configure.
+- **Portable.** Reviewers export their feedback as JSON and send it to you; you
+  import it with one click and see every note in place.
+- **Polished UI.** A floating toolbar, a Figma-style comments panel, light/dark
+  themes that auto-adapt to your page, and full keyboard shortcuts.
+- **Dependency-free.** Vanilla JavaScript with no runtime dependencies.
+
+---
+
+## Features
+
+| Tool | What it does |
+|------|--------------|
+| ✏️ **Highlight** | Select any text to highlight and comment on it |
+| ▭ **Rectangle** | Draw a box around any region |
+| ◯ **Circle** | Circle anything that needs attention |
+| 📍 **Pin** | Drop a point marker anywhere |
+| ⧉ **Several elements** | One comment on up to 20 elements: Shift+click them with the Pin tool, or turn on **Select several**, then **Comment on N elements** |
+| 〰️ **Freehand** | Sketch directly on the page |
+| ➕ **Section note** | Hover any paragraph/heading for a margin comment button |
+| ⏸ **Freeze motion** | Pause CSS animations, transitions, Web Animations and video to comment on a moving page (`F`). Not frozen: JavaScript loops (`requestAnimationFrame`, GSAP, canvas), content inside shadow roots, content inside iframes (same-origin ones as well as cross-origin YouTube and Vimeo embeds), SVG SMIL animations, and animated GIF and WebP images. Freezing is refused while the tools are hidden. |
+| ⠿ **Draggable toolbar** | Drag the grip to move the toolbar; it remembers the spot. With the grip focused, arrow keys move it, Shift moves it further, and Home resets it. Double-click the grip to reset it too. |
+
+Plus: threaded replies, resolve/reopen, search & filter, deep-links to a single
+comment (`#an=<id>`), an "off" mode that collapses to a small launcher, and a
+**Download / Copy / Import** round-trip for sharing. A built-in
+[MCP server](#ai-agents-mcp) lets your coding agent read, answer and resolve
+the comments itself.
+
+### Comment on several elements
+
+For notes like "these three cards have different padding":
+
+1. Press `P` for the Pin tool.
+2. Shift+click each element. On a touch screen, turn on **Select several** in
+   the hint at the top and tap them. Picking an element again drops it.
+3. Click **Comment on N elements** in the bar at the bottom, or press Enter.
+
+The comment gets one marker, on the first element. While it is open or
+hovered, every element is outlined with its number. Its card lists the
+elements; click one to scroll to it. Esc clears the selection, and a second
+Esc leaves the tool.
+
+With a review backend, these comments need one that knows the `group` type:
+the reference server from this release on. An older server answers `422`,
+and the comment stays in this browser; a toast says so.
+
+### Shadow DOM and iframes
+
+Annotations reach into open shadow roots and same-origin iframes. Each shadow
+root or iframe adds a segment to the selector, joined with ` >>> `:
+
+```
+#app-shell >>> div.shell > x-panel >>> button[aria-label="Save"]
+#checkout-frame >>> #pay-button
+```
+
+Each segment is looked up inside the shadow root or iframe the previous one
+found. The markers stay in your page and follow the iframe when it scrolls,
+reloads or changes. A marker whose element is scrolled out of the iframe's
+view is hidden until it scrolls back; opening its comment scrolls the iframe
+to it. Versions before 1.6 don't understand ` >>> `: they may show
+these comments as missing their anchor, or re-anchor one by its name to a
+matching element in the page's light DOM.
+
+| Where | Pin, rectangle, circle, freehand, several elements | Section note | Text highlight |
+|-------|-----|-----|-----|
+| Open shadow root | yes | yes | no |
+| Same-origin iframe (nested up to 3 deep) | yes | no | no |
+| Closed shadow root | the host element | the host's block | no |
+| Cross-origin iframe | the `<iframe>` element | no | no |
+
+Limits:
+
+- No text highlights inside shadow roots or iframes.
+- No section notes inside iframes.
+- A cross-origin iframe's contents can't be reached. While a drawing tool is
+  on, a transparent shield over the frame takes the click, so the pin or shape
+  lands on the `<iframe>` element itself. Page content drawn over the frame,
+  such as a fixed header, still takes its own clicks.
+- Shortcuts aren't seen while focus is inside a cross-origin iframe.
+- An iframe's padding, transforms and zoom aren't accounted for, so markers
+  are off in a scaled frame (a device preview, for example).
+- A closed shadow root can't be looked into, so a comment there is on its
+  host.
+- Iframes inside shadow roots aren't found.
+
+---
+
+## Configuration
+
+Configure with `data-` attributes on the script tag — all optional:
+
+```html
+<script
+  src="https://cdn.jsdelivr.net/npm/@perpetio/redline/redline.js"
+  data-project="marketing-site"
+  data-accent="#bd3426"
+  data-theme="auto"
+  data-position="bottom-right"
+  data-start-open="true"
+  data-note="Focus on the hero copy and pricing — flag anything off-brand."
+  data-spa="true"
+  data-post-url="https://feedback.example.com/feedback"
+  data-share-email="https://github.com/org/repo/issues/new?title=Review%20{page}&amp;body={summary}"
+  defer
+></script>
+```
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `data-project` | `""` | Namespace for stored comments. Keep separate sites apart. |
+| `data-page` | `location.pathname` | Page key comments are grouped under. |
+| `data-accent` | — | Brand color for primary buttons & the active tool. |
+| `data-theme` | `auto` | `light`, `dark`, or `auto` (sniffs your page background). |
+| `data-position` | `bottom-right` | `bottom-right` or `bottom-left`. |
+| `data-blocks` | sensible default | CSS selector for "section note" (+) targets. |
+| `data-start-open` | `false` | Set to `true` to show the review toolbar immediately instead of the collapsed Review pill. |
+| `data-note` | — | Author's note to reviewers — what should be reviewed. Shown when they start and atop the comments panel. |
+| `data-spa` | `false` | Watch `pushState`, `replaceState`, and `popstate` for page changes. |
+| `data-post-url` | — | URL that receives an explicit HTTP POST of the current page's export JSON. Adds **Send feedback**. |
+| `data-share-email` | — | Email address or URL template for **Share**. `{page}`, `{count}`, and `{summary}` become URL-encoded values for a prefilled GitHub, GitLab, Jira, or other issue URL. |
+| `data-capture` | `styles,components` | Extras each new comment records besides the element description: `styles`, `components`, both, or `off`. Component and source info only exists in development builds. |
+| `data-editor-url` | — | "Open in editor" link template, e.g. `vscode://file/Users/me/app/{path}:{line}`. `{path}`, `{line}`, `{column}` come from the comment's source file. |
+
+For programmatic setup, import the ES module and call `init(config)`:
+
+```bash
+npm install @perpetio/redline
+```
+
+```js
+import Redline from '@perpetio/redline';
+
+Redline.init({
+  project: 'marketing-site',
+  accent: '#bd3426',
+  spa: true,
+  postUrl: '/feedback',
+});
+// Call Redline.destroy() when unmounting or during hot reload.
+```
+
+The classic script still supports `window.RedlineConfig` set before it loads.
+For a script injected after page load, call `window.Redline.init(config)`.
+`init()` can be called again after `destroy()` without leaving listeners behind.
+TypeScript declarations are included in the package.
+
+---
+
+### Redline Cloud (`data-workspace`)
+
+With Redline Cloud, comments sync to a review instead of staying in the browser. Create the review at [app.redlinejs.com](https://app.redlinejs.com); its Setup tab has your workspace's snippet, the same for every site and review, and its Guests tab hands out the invite links:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@perpetio/redline/redline.js"
+        data-workspace="ws_…" defer></script>
+```
+
+Each site address in the workspace is linked to one review, and everyone who
+opens the tools on that site shares it: your team, guests and their invite
+links. Creating a review links its site. The Setup tab's **Linked sites** moves
+or removes a link, and **Settings → Connect to Redline** in the toolbar links a
+site that isn't linked yet. The widget asks Redline Cloud for the site's review
+only when someone opens the tools or arrives with an invite or sign-in link,
+and remembers the answer.
+
+| Attribute | Meaning |
+|---|---|
+| `data-workspace` | Your Redline Cloud workspace. Without it (and without `data-review-id`) the page stays local-only, exactly as above. |
+| `data-review-id` | Pins the page to one review instead of the site's linked review. `local` connects a page on `localhost` or `127.0.0.1` to your coding agent (see [AI agents](#ai-agents-mcp)). |
+| `data-post-retries` | `0` to `5`, default `3`. Retries for `data-post-url` after a network error, timeout, `408`, `429` or `5xx`. |
+| `data-credentials` | `omit` (default), `same-origin` or `include`. Whether `data-post-url` requests carry cookies. Requests to Redline Cloud never do. |
+
+Reviewers arrive through a personal link, `https://your-site/page?an_invite=…`.
+The token is stored for that review in the reviewer's browser and removed from
+the address bar, then exchanged for a 24-hour session on every load. Only the
+site addresses registered on the review may use it.
+
+- If the landing page forwards to another page before redline.js runs (a `/`
+  stub with a meta refresh, a script redirect) and drops the query string, the
+  token is recovered from the same-origin referrer, so the link still works.
+  Cross-origin referrers are never used.
+- When the backend refuses (link revoked or expired, review closed, address not
+  registered, or no link at all), the panel says why and what to do next, and
+  comments stay in the browser; Download or Copy sends them by email.
+- In a synced review there is nothing to submit: the footer reads "Sent to the
+  review" as soon as a comment is posted.
+
+**Settings** in the toolbar has two sections. **Redline Cloud** signs you in
+with your Redline account (**Connect to Redline**, also in the sign-in box as
+**Continue with Redline**) or links the site. **MCP** shows the review's coding
+agent and when it last connected, with a link to set it up, or on `localhost`
+the switch for your local agent.
+
+The backend is Redline Cloud: workspaces, members, guests and the agent are managed in the portal at [app.redlinejs.com](https://app.redlinejs.com). `server/redline-server.cjs` is internal: it runs the MCP server's local mode.
+
+#### Team reviews and mentions
+
+In a synced review, everyone in the review sees every comment and can reply.
+Type `@` in a comment or reply to mention someone: they get a count on the
+Redline button and a **Mentions** list across pages. Mention `@Agent` to hand
+a comment to your coding agent; its MCP tools take `mentioned: true` to work
+only on those. Only the creator and the review's authors can edit, resolve or
+delete a comment. To keep reviewers' comments private from each other, turn on **Private review** in the review's Setup tab.
+
+#### People and invites
+
+Authors invite people from the panel. Open **People** (the icon next to
+Import) and choose **Invite someone**. Enter a name, an optional email, a role,
+and when the link expires (30 days by default). Copy the link and send it;
+the person opens the site through it and is signed in.
+
+From the list you can copy a link again, replace it with **New link**, or
+revoke it, which signs the person out at once. Only authors who signed in with
+an invite see People. Authors manage the same guests in the portal's Guests tab.
+
+In Redline Cloud,
+authors can email invite links. People can also sign in on any device with a
+one-time email link, and mentioned people get one email per batch of
+mentions, which they can switch off.
+
+## Framework integration
+
+For a bundler, install `@perpetio/redline`, call `init()` after mount, and
+call `destroy()` on unmount. Use `spa: true` when your router changes paths
+through the History API. Dynamic content is watched and re-anchored after it
+renders. The classic script remains available for static pages.
+
+### React and Next.js
+
+Mount it once at the app root with a `useEffect`:
+
+```jsx
+// components/FeedbackLayer.jsx
+import { useEffect } from "react";
+import Redline from "@perpetio/redline";
+
+export default function FeedbackLayer() {
+  useEffect(() => {
+    Redline.init({ project: "my-react-app", accent: "#bd3426", spa: true });
+    return () => Redline.destroy();
+  }, []);
+  return null;
+}
+```
+
+```jsx
+// App.jsx
+import FeedbackLayer from "./components/FeedbackLayer";
+
+export default function App() {
+  return (
+    <>
+      <FeedbackLayer />
+      {/* your app */}
+    </>
+  );
+}
+```
+
+**Next.js (App Router):** mark `FeedbackLayer` as a client component with
+`"use client";` at the top, then render it inside `app/layout.jsx`.
+
+### Vue 3
+
+```vue
+<!-- App.vue -->
+<script setup>
+import { onMounted, onUnmounted } from "vue";
+import Redline from "@perpetio/redline";
+
+onMounted(() => {
+  Redline.init({ project: "my-vue-app", accent: "#10b981", spa: true });
+});
+onUnmounted(() => Redline.destroy());
+</script>
+```
+
+For a static Vue page, the classic `<script>` tag also works in `index.html`.
+
+### WordPress
+
+**Option A — no code.** Install a "header/footer scripts" plugin (e.g. *WPCode*
+or *Insert Headers and Footers*) and paste this into the **footer** box:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@perpetio/redline/redline.js" data-project="my-wp-site" defer></script>
+```
+
+**Option B — theme code.** Add to your theme's `functions.php`:
+
+```php
+function redline_enqueue() {
+  wp_enqueue_script(
+    'redline',
+    'https://cdn.jsdelivr.net/npm/@perpetio/redline/redline.js',
+    array(),
+    '2.1.1',
+    true // load in footer
+  );
+}
+add_action( 'wp_enqueue_scripts', 'redline_enqueue' );
+```
+
+> Tip: wrap the enqueue in `if ( current_user_can('edit_posts') )` to show the
+> review tools only to logged-in editors.
+
+### Svelte and SvelteKit
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import { onMount } from "svelte";
+  import Redline from "@perpetio/redline";
+  onMount(() => {
+    Redline.init({ spa: true });
+    return () => Redline.destroy();
+  });
+</script>
+
+<slot />
+```
+
+### Angular
+
+Add the classic script before `</body>` in `src/index.html`. Enable SPA mode
+so feedback stays grouped by route as the Angular router changes paths:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@perpetio/redline/redline.js"
+        data-project="my-angular-app" data-spa="true" defer></script>
+```
+
+### Plain HTML, Webflow, Shopify, and Squarespace
+
+Paste before `</body>` (or into the platform's "custom code / footer" field):
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@perpetio/redline/redline.js" defer></script>
+```
+
+---
+
+## Element identification and AI agents
+
+Every new comment records the element it is about: a readable label
+(`Button "Start free trial"`), a stable selector that prefers ids and
+`data-testid`, the nearest heading, its classes and size, computed styles,
+and, in React, Vue or Svelte development builds, the component chain and
+source file (`src/components/PlanCard.tsx:42:7`). The Pin tool outlines the
+element under the cursor before you click, and the click never reaches the
+page.
+
+**Copy → Copy for AI agent** puts Markdown made for coding agents on the
+clipboard, at Compact, Standard or Detailed level. Press `M` for the same.
+Paste it into Claude Code, Cursor or any agent:
+
+```markdown
+## 1. Button "Start free trial"
+Pin · open · Jane Doe
+> Should say "Start 14-day trial", legal asked for it.
+
+- Selector: `[data-testid="start-trial"]`
+- Component: `<Pricing> <PlanCard> <Button>` · `src/components/PlanCard.tsx:42:7`
+- Under heading: "Pricing"
+```
+
+Resolved and won't-fix comments are left out. From code:
+`Redline.markdown({ detail: "detailed" })` returns the text and
+`Redline.copy()` copies it.
+
+## AI agents (MCP)
+
+`redline-mcp` is an MCP server that gives your coding agent the review
+comments directly. The agent reads what reviewers left, replies, and moves
+each comment to in progress, resolved or won't fix. Reviewers see all of it in
+the panel, with the agent's replies labelled Agent. Connected to a review in
+Redline Cloud or running in local mode, it needs Node.js 20 or later.
+
+Anyone who can comment on a review can write to your agent. Don't pair an
+`open: true` review with an agent on a site that strangers can reach.
+
+### Quick start (local)
+
+1. In your project folder, register the server with your coding agent.
+   Local mode requires **Node.js 20 or later**.
+
+   **Claude Code:**
+
+   ```bash
+   claude mcp add redline -- npx -y -p @perpetio/redline@latest redline-mcp
+   ```
+
+   **Codex:**
+
+   ```bash
+   codex mcp add redline -- npx -y -p @perpetio/redline@latest redline-mcp
+   ```
+
+   Inside a project that already depends on `@perpetio/redline`,
+   `npx redline-mcp` works too.
+
+   It starts a review backend for the folder on `127.0.0.1:7335`, and keeps
+   its data in `.annotate/` in the project folder. That folder has its own
+   `.gitignore`, so nothing is committed.
+2. Open the page you are developing, on `localhost` or `127.0.0.1`, with any
+   Redline snippet that has no `data-review-id`:
+
+   ```html
+   <script src="https://unpkg.com/@perpetio/redline"></script>
+   ```
+
+   Click **Settings** (the gear) in the Redline toolbar and turn on **Send
+   comments to my coding agent**. The switch is remembered for that site, and
+   the dot next to MCP shows whether the agent's server is running. To turn it
+   on from code instead, add `data-review-id="local"`.
+3. Leave some comments, then tell the agent: "work through the Redline
+   comments".
+
+A second agent session in the same folder attaches to the first one's backend.
+The address is fixed, so one project at a time can use local mode; use a
+Redline Cloud review for another project.
+
+### Other clients
+
+Any MCP client that can start a stdio server works. The usual JSON config:
+
+```json
+{
+  "mcpServers": {
+    "redline": {
+      "command": "npx",
+      "args": ["-y", "-p", "@perpetio/redline@latest", "redline-mcp"]
+    }
+  }
+}
+```
+
+Local mode keeps its data in `.annotate/` in the folder the client starts the
+server in. Clients that don't start servers in the project folder (Claude
+Desktop starts them in `/`) need the folder given explicitly:
+`"args": ["-y", "-p", "@perpetio/redline@latest", "redline-mcp", "--data-dir", "/absolute/path/to/project/.annotate"]`,
+or the client's `cwd` setting.
+
+### Tools
+
+| Tool | What it does |
+|---|---|
+| `annotate_list_pending` | Open and in-progress comments, oldest first, as Markdown plus JSON. Optional `page` filter. |
+| `annotate_get_comment` | One comment in full: styles, position, replies and activity. |
+| `annotate_reply` | Adds a reply to a comment thread. |
+| `annotate_set_status` | Sets `in_progress`, `resolved`, `wont_fix` or `open`. A note is posted as a reply first, and `wont_fix` needs one. |
+| `annotate_watch` | Waits for new or changed comments, then returns them. |
+
+### Remote mode
+
+To work against a review in Redline Cloud instead of the local one, pass the
+review and the review's agent invite:
+
+```bash
+npx -y -p @perpetio/redline@latest redline-mcp --review rvw_… --invite agt_…
+```
+
+`REDLINE_REVIEW` and `REDLINE_INVITE` work in place of the flags. Create the agent token in the review's Agent tab at [app.redlinejs.com](https://app.redlinejs.com); it shows this command ready to copy.
+
+### Troubleshooting
+
+Run `npx -y -p @perpetio/redline@latest redline-mcp doctor` in the same folder (with
+the same flags or variables in remote mode). It prints a line per check, starting with the
+mode, and exits 1 if one fails.
+
+- **`127.0.0.1:7335 is used by redline-mcp for another project folder`**: one
+  project at a time can use local mode. Stop the other agent session, or use a
+  Redline Cloud review.
+- **`127.0.0.1:7335 is in use by another program`**: local mode needs that
+  port. Stop the program, or use a Redline Cloud review.
+- **`--port`, `--host` and `--api`** were removed in 2.0. Local mode always
+  runs on `127.0.0.1:7335`, and remote mode always connects to Redline Cloud.
+
+## Sharing comments
+
+Sharing is an explicit action:
+
+1. A reviewer opens the **Comments panel** (toolbar list icon or press `A`).
+2. They click **Download** (⬇) to save a `redline-<page>-<date>.json` file.
+3. They send you that file.
+4. You open the same page, click **Import** (⬆), pick the file — every comment
+   reappears anchored in place.
+
+Reviewing a whole site? When other pages have comments too, the footer offers
+**All pages** under the buttons: one file with every page's comments. Import it
+on any page of the site and each comment goes back to the page it was made on
+(the project name may differ between the two browsers).
+
+To paste feedback directly into another tool, click **Copy** to copy the same
+complete, import-compatible JSON payload to the clipboard.
+
+You can also drive this from code (see the API below).
+
+### Send feedback to your server
+
+Set `data-post-url` on the classic script or `postUrl` in `init(config)`.
+Reviewers will see a **Send feedback** button. It POSTs the same JSON export
+to your endpoint with `Content-Type: application/json`. A successful response
+must have a 2xx status. Sending does not delete the browser's local comments.
+
+Every POST body carries a top-level `deliveryId`. It stays the same across the
+retries of one submit, so store it and answer a repeat with success without
+saving twice (the example receiver does). Failed sends are retried up to
+`data-post-retries` times (default 3, at most 5) on network errors, timeouts,
+`408`, `429` and `5xx`; other statuses such as `400` are not retried. Waits are
+1 s, 2 s, 4 s…, or the receiver's `Retry-After` (seconds or an HTTP date, capped
+at 30 s). A cross-origin browser reads `Retry-After` only if the receiver lists
+it in `Access-Control-Expose-Headers`.
+
+```html
+<script src="/redline.js" data-post-url="https://feedback.example.com/feedback" defer></script>
+```
+
+Any endpoint that accepts a JSON `POST` works as the receiver. Answer `2xx`
+once the feedback is stored. Retries reuse the body's `deliveryId`, so a
+repeat can return the first result. Before exposing a receiver publicly, add
+your site's authentication and rate limits.
+
+### Prefill an issue
+
+`data-share-email` also accepts an issue creation URL. The values of
+`{page}`, `{count}`, and `{summary}` are URL encoded before substitution.
+For example:
+
+```html
+<script src="/redline.js"
+  data-share-email="https://github.com/org/repo/issues/new?title=Review%20{page}&amp;body={summary}"
+  defer></script>
+```
+
+The issue link contains a short comment summary. Download or send the full
+JSON when teammates need to import annotations and their anchors.
+
+---
+
+## JavaScript API
+
+A global `window.Redline` is available once the classic script loads. The
+ES module exports the same controller as default, plus named `init` and
+`destroy` functions. The module does not start until `init(config)` is called.
+
+```js
+Redline.open();              // show the review layer and open the comments panel
+Redline.close();
+Redline.toggle();
+Redline.enable();            // show the review layer
+Redline.disable();           // collapse to the launcher
+Redline.setTool("highlight");// show the layer, then choose cursor | highlight | rect | circle | pen | pin
+Redline.comments();          // → array of comment objects for this page
+Redline.focus(id);           // scroll to & highlight a comment
+Redline.export();            // trigger the JSON download for this page
+Redline.export({ scope: "site" }); // one file with every page's comments
+Redline.import();            // open the file picker
+await Redline.submit();      // POST the JSON export to postUrl
+Redline.refresh();           // manually re-read the current page when spa is off
+Redline.destroy();           // remove UI, observers, and event listeners
+Redline.init({ spa: true });  // start again with programmatic settings
+Redline.clear();             // delete all comments on this page (local)
+Redline.toast("Saved!");     // show a toast
+Redline.markdown({ detail: "standard" }); // Markdown for AI agents ("" when nothing is open)
+await Redline.copy();                     // copy that Markdown; { format: "json" } copies the export
+Redline.setFrozen(true);     // pause page animations, transitions and media; returns the new state
+Redline.isFrozen();          // true while motion is frozen
+window.addEventListener("annotate:freeze", e => console.log(e.detail.frozen));
+Redline.version;             // "2.1.1"
+```
+
+### Comment shape
+
+```json
+{
+  "id": "c…",
+  "page": "marketing-site:/pricing",
+  "url": "https://example.com/pricing",
+  "type": "highlight",
+  "author": "Jane Doe",
+  "text": "This price looks out of date.",
+  "color": "#f59e0b",
+  "anchor": { "exact": "…", "prefix": "…", "suffix": "…" },
+  "geom": null,
+  "target": { "label": "Paragraph \"…\"", "selector": "…", "…": "…" },
+  "resolved": false,
+  "replies": [],
+  "createdAt": "2026-06-16T10:00:00.000Z",
+  "updatedAt": "2026-06-16T10:00:00.000Z"
+}
+```
+
+`target` is present on comments made with 1.6 or later; see docs/backlog/wire-protocol.md for every field.
+
+---
+
+## Keyboard shortcuts
+
+| Key | Action | Key | Action |
+|-----|--------|-----|--------|
+| `V` | Browse | `P` | Pin |
+| `H` | Highlight | `A` | Comments panel |
+| `R` | Rectangle | `O` | Show / hide tools |
+| `C` | Circle | `Esc` | Cancel |
+| `D` | Freehand | `?` | Shortcuts card |
+| `M` | Copy for AI agent | `F` | Freeze motion |
+
+---
+
+## Browser support
+
+Modern evergreen browsers (Chrome, Edge, Firefox, Safari). Uses standard DOM
+APIs only — no polyfills required. Gracefully no-ops where `localStorage` is
+unavailable (private mode, sandboxed iframes).
+
+---
+
+## License
+
+The widget and local mode are free to use in personal and commercial
+projects under the terms in [LICENSE](https://cdn.jsdelivr.net/npm/@perpetio/redline@2.1.1/LICENSE).
+Redline is not open source.
+
+Redline is built on the source code of
+[annotate.js](https://reviewjs.github.io/annotate/), used under the MIT
+License. Its copyright notice, "Copyright (c) 2026 annotate.js contributors",
+is kept in [LICENSE](https://cdn.jsdelivr.net/npm/@perpetio/redline@2.1.1/LICENSE).
+
+Redline Cloud is a subscription service by Perpetio OÜ, provided under its
+[Terms of Service](https://redlinejs.com/terms) and
+[Privacy Policy](https://redlinejs.com/privacy).