patch-mark: annotations that compile to prompts

Try the live demo — the whole landing page is interactive. Full docs (EN / 中文): lkrcharon.github.io/patch-mark/docs/

UI feedback for AI coding agents. Point at an element on a preview page, write a comment, and your coding agent gets structured untrusted evidence to verify — selector, element name, position, visible text, and feedback. No more "the button on the left" screenshots.

This is not an annotation library for human review — it's specifically the feedback channel between a human and an AI coding agent.

Quick start

<script type="module" src="https://unpkg.com/patch-mark"></script>
<patch-mark visible></patch-mark>

Click the floating button, hover an element, click to select, write your comment. Annotations persist in localStorage. The visible attribute is off by default on the raw element — enable it on preview/staging only. (patch-mark/react renders visible by default.)

npm

npm install patch-mark

import 'patch-mark';
import { createFetchStore } from 'patch-mark';
const tool = document.querySelector('patch-mark')!;
tool.store = createFetchStore({ endpoint: '/api/annotations' });

React / Next.js

'use client';
import { useMemo } from 'react';
import { PatchMark } from 'patch-mark/react';
import { createFetchStore } from 'patch-mark';

export default function PatchMarkClient() {
  const store = useMemo(() => createFetchStore({ endpoint: '/api/annotations' }), []);
  return <PatchMark store={store} />;
}

Gate it by environment where you render it: {process.env.NODE_ENV !== 'production' && <PatchMarkClient />}.

Let the agent read annotations itself (MCP)

With a REST store (createFetchStore), agents that speak MCP — Claude Code, Cursor, Codex — can read open annotations without copy-pasting:

{
  "mcpServers": {
    "patch-mark": {
      "command": "npx",
      "args": ["-y", "patch-mark-mcp", "--endpoint", "http://localhost:3000/api/annotations"]
    }
  }
}

The default server exposes only list_open_annotations. It labels annotation fields as untrusted user input and supports both legacy MCP 2025-03-26 clients and stateless MCP 2026-07-28 clients. After human approval, opt into the mutating resolver explicitly:

{
  "mcpServers": {
    "patch-mark-write": {
      "command": "npx",
      "args": ["-y", "patch-mark-mcp", "--endpoint", "http://localhost:3000/api/annotations", "--allow-resolve"]
    }
  }
}

resolve_annotation then requires a summary, changed files, and checks run. It is never a substitute for review or backend authorization. No MCP? The list panel's handoff bar copies a trust-bounded prompt that treats annotations as data, not instructions.

Themes

| Theme | Accent | Works well on | | --- | --- | --- | | blue (default) | #0058d0 | neutral SaaS dashboards | | violet | #7c3aed | creative / AI tools | | emerald | #059669 | docs, fintech, admin panels | | orange | #ea580c | marketing sites | | rose | #e11d48 | bold consumer brands |

<patch-mark theme="emerald" visible></patch-mark>

Every color token is a CSS custom property — see the theming docs for the full variable table and custom presets.

Properties

| Property | Default | Description | |----------|---------|-------------| | store | createLocalStorageStore() | Where annotations are persisted/sent | | visible | false | Show the launcher (attribute: visible) | | themeName | 'blue' | Preset theme (attribute: theme) | | pageKey | current path + query + hash | Stable page identity; set it from a pushState router on route changes | | requireAuth | false | Server-validated token session (attribute: require-auth) | | onError | null | Error reporter for failed store ops |

Full API reference, REST contract, access control, and framework recipes (Vue, vanilla HTML) are in the docs.

Links

• Live demo · Docs (EN) · 中文文档
• GitHub · npm
• CHANGELOG · Release checklist · Next.js example

License

MIT