Margin

Review HTML in the browser, comment on elements or highlighted text, and turn the result into precise, agent-readable feedback.

The hosted app uses Next.js on Vercel and Supabase for invite-only authentication, Postgres metadata, and private HTML storage. A separate local CLI keeps files on your machine.

Hosted setup

Requirements:

• Node.js 22.13 or newer
• A Supabase project
• A Vercel account connected to this GitHub repository

1. Configure Supabase

Install the Supabase CLI, link the project, and apply the migration:

npx supabase login
npx supabase link --project-ref YOUR_PROJECT_REF
npx supabase db push

The migration creates:

• A hard limit of six accounts: the owner and five collaborators.
• profiles, reviews, and review_members tables with Row Level Security.
• A private html-reviews Storage bucket.
• Thirty-day review expiry metadata.

In the Supabase dashboard:

1. Keep public sign-ups disabled.
2. Set the Site URL to the production Vercel URL.
3. Add both https://YOUR_PROJECT.vercel.app/auth/confirm and https://YOUR_PROJECT.vercel.app/auth/invite to the allowed redirect URLs.
4. Invite the owner account from Authentication → Users. The first account becomes the Margin owner.

After that bootstrap invitation, the owner can invite the other five collaborators from My reviews inside Margin. The database rejects a seventh account even if an additional invitation is attempted externally.

2. Configure environment variables

Copy .env.example to .env.local for development. Add the same values to the Vercel project:

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
SUPABASE_SECRET_KEY

The secret key is server-only. Never expose it through a NEXT_PUBLIC_ variable.

3. Deploy

Import the GitHub repository into Vercel. Vercel detects Next.js automatically; no custom build settings are required. Every push to main creates a production deployment.

A custom domain is optional. The generated *.vercel.app address works for authentication and sharing.

Hosted workflow

1. Sign in through the invitation email or request a magic link.
2. Load an HTML file by clicking the filename or dropping it onto Margin.
3. Add comments to elements or selected text.
4. Choose Share and send the collaborator link to another invited user, or the Agent link to an AI agent.
5. Use My reviews to return to reviews you own or have joined.

Uploaded HTML is stored in a private bucket. Review membership and annotations are stored in Postgres. Margin renders reviewed pages as passive content in a sandboxed iframe: document scripts, forms, embeds, and network requests are disabled. Margin's isolated review bridge remains available for selecting elements and placing comments.

Agent API

The Agent link is a private, self-describing API URL. An agent can GET that URL to receive the HTML snapshot, current annotations, and the comment request schema without using a browser or signing in.

To add comments, send the key from the Agent link as a bearer credential to the same endpoint without its query string:

POST /api/agent/reviews/REVIEW_ID
Authorization: Bearer AGENT_LINK_KEY
Content-Type: application/json

{
  "agentName": "Codex",
  "comments": [
    {
      "comment": "Increase the heading contrast.",
      "target": {
        "type": "element",
        "selector": "main > h1",
        "tag": "h1",
        "text": "Overview"
      }
    }
  ]
}

Text-selection targets use "type": "text" and must also provide the exact quote; prefix and suffix are optional context. A request can add up to 20 comments, and a review can contain up to 500 annotations.

Agent access is limited to reading the snapshot and appending open comments. It cannot change, resolve, or remove existing feedback. The link expires with the review, and creating a new share link immediately invalidates the previous Agent link. Treat the link as a secret while it is active.

Local CLI

npx margin-html-review ./page.html

Or install it globally:

npm install --global margin-html-review
margin-review ./page.html

Margin opens locally and writes comments to page.feedback.json beside the source HTML. The original HTML is never modified.

The CLI prints two local URLs: Review opens the visual interface, while Agent is a private loopback API credential for agents running on the same computer. The local Agent API can read the current HTML and annotations, append comments, and mark comments resolved or open.

GET http://127.0.0.1:PORT/api/agent/local?key=PRIVATE_KEY

Append comments with POST, using the key as a Bearer credential and the same JSON shape as the hosted Agent API. Resolve or reopen a comment with:

PATCH /api/agent/local
Authorization: Bearer PRIVATE_KEY
Content-Type: application/json

{"annotationId":"COMMENT_ID","status":"resolved"}

The browser polls revisioned local feedback, so agent changes appear without restarting Margin. Stale browser saves are rejected and reconciled rather than overwriting newer agent work. The local Agent URL works only while that CLI process is running, is bound to 127.0.0.1, and receives a new random key each time. Do not expose it through a tunnel or port-forward.

Options:

-p, --port <number>   Local port (default: 3210)
-o, --output <path>   Choose the feedback JSON path
    --share           Upload through the configured hosted Margin service
    --no-open         Do not open the browser automatically
-v, --version         Print the version
-h, --help            Show help

Hosted CLI uploads target https://margin-rouge.vercel.app by default. The first time you share, Margin opens a secure browser window so you can sign in and authorize that computer. Users never need to create or copy a token. Both --share and the local review desk's Share button use this flow.

The hosted-sharing credential is limited to reading and writing reviews and expires after 90 days. On Windows it is encrypted for the current Windows account with DPAPI; on other platforms ~/.margin/config.json is restricted to the current user. You can invalidate it at any time from My reviews → Revoke local access. Browser saves and hosted proxy requests also require a browser-session cookie and strict origin checks. The separate local Agent credential is random, process-scoped, and accepted only by the loopback Agent endpoint.

MARGIN_ACCESS_TOKEN remains available as an optional override for unattended automation, and MARGIN_SHARE_ORIGIN overrides the hosted destination. Treat any manually supplied token as a secret.

Development

npm install
npm run dev
npm run lint
npm test

The npm package name is margin-html-review; its executable commands are margin-review and margin-html-review.

Publishing to npm

Publishing is handled by .github/workflows/publish-npm.yml. The workflow runs only when a GitHub release is published and requires its tag to exactly match the version in package.json (for example, version 0.2.2 uses tag v0.2.2). It installs dependencies, runs the package's prepack checks, and publishes the public package with provenance.

Configure npm Trusted Publishing for organization/user tgran43, repository Margin, and workflow publish-npm.yml, allowing npm publish. Releases authenticate through GitHub's short-lived OIDC credentials without a stored publishing token.