@cleverops/toolbar

The CleverOps review toolbar. One npm package covers:

Runtime widget — <CleverOpsToolbar /> React component. Activates only when a reviewer link contains ?cleverops=<token>. Otherwise it renders null and does no work.
CDN script — self-contained IIFE bundle at https://markup.cleverops.dev/toolbar.js for non-React sites (Webflow, WordPress, static HTML).
Babel plugin — @cleverops/toolbar/source-loc adds data-cleverops-loc="path:line:col" to JSX DOM elements at build time so element picks capture exact source locations for Claude Code.

Dashboard + API live at markup.cleverops.dev.

Quick start for Claude Code users

Paste a CLEVEROPS_API_KEY into your repo's .env.local (grab one from markup.cleverops.dev → Settings → API keys), then tell Claude Code:

Set up CleverOps review. API key is in .env.local.

Claude Code reads node_modules/@cleverops/toolbar/CLAUDE.md and takes care of installing the package, wiring the Babel plugin, calling the bootstrap API, and printing the reviewer link. Everything below is for manual setups.

Install (React / Next.js)

npm install @cleverops/toolbar

Render once in your root layout:

// app/layout.tsx
import { CleverOpsToolbar } from '@cleverops/toolbar';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <CleverOpsToolbar />
      </body>
    </html>
  );
}

Custom API host (staging / self-hosted)

<CleverOpsToolbar apiHost="https://staging.markup.cleverops.dev" />

Defaults to https://markup.cleverops.dev.

Install (script tag — any site)

Add to <head> or before </body>:

<script src="https://markup.cleverops.dev/toolbar.js" defer></script>

With a custom API host:

<script
  src="https://markup.cleverops.dev/toolbar.js"
  data-api-host="https://staging.markup.cleverops.dev"
  defer
></script>

Source-location Babel plugin

Lets the element picker report exact path:line:col from the source repo — Claude Code picks up Linear issues and knows which file to edit.

npm install --save-dev @babel/core

// babel.config.js
module.exports = {
  plugins: ['@cleverops/toolbar/source-loc'],
};

Next.js with a babel.config.js automatically switches from SWC to Babel for that project. Attribute persists into production HTML (~30 bytes per element, negligible).

Plugin options

option	default	effect
`include`	everything under cwd	glob patterns or RegExp — only instrument matching files
`exclude`	`['node_modules/**']`	skip matches
`attrName`	`'data-cleverops-loc'`	override attribute name
`includeColumn`	`true`	when false, emit `path:line` instead of `path:line:col`

Example:

module.exports = {
  plugins: [
    ['@cleverops/toolbar/source-loc', {
      exclude: ['node_modules/**', '**/*.stories.tsx', '**/*.test.tsx'],
    }],
  ],
};

How it works

Component (or CDN script) mounts silently on page load.
If the URL does not contain ?cleverops=<token>, nothing else happens.
If it does, the toolbar:
- POSTs the token to <apiHost>/api/widget/validate
- Caches the resolved config in sessionStorage (tab-scoped)
- Strips the token from the address bar via history.replaceState
- Mounts a shadow-DOM toolbar
Reviewer picks elements, sketches via Excalidraw, drops replacement images, writes comments.
Submissions go to <apiHost>/api/annotations + /api/screenshots. Each annotation auto-creates a Linear issue with selector, screenshot, source-loc, and the replacement file attached.
On SPA navigation within the same origin, the toolbar stays mounted. On cross-origin navigation it unmounts.

Gotchas

Load synchronously in <head> or with defer in the body. Don't lazy-load — reviewer may click before the toolbar attaches event listeners.
Strict CSP: script-src needs markup.cleverops.dev for the script-tag build; connect-src needs your chosen apiHost.
The widget mounts in a shadow DOM to isolate styles. It won't be affected by your site's CSS.

Bundle sizes

dist/index.js / .cjs — ~8 MB. Self-contained npm entry (React/ReactDOM peer, everything else bundled — Excalidraw, html-to-image, Buffer polyfill). One install, no extra peer deps.
dist/toolbar.global.js — ~8 MB minified. CDN IIFE, React bundled in.
dist/source-loc.js / .cjs — ~3 KB. Babel plugin, Node-only.

Development

npm install
npm run -w @cleverops/toolbar build
npm run -w @cleverops/toolbar dev        # watch mode
npm run -w @cleverops/toolbar typecheck