Documentation · v0.5.2

Loupe

Pin feedback to the live UI — inspect any element, drop a comment, capture a screenshot — then hand it to Claude Code as an actionable backlog. Comments persist and re-anchor across redeploys.

What Loupe is

An embeddable visual-feedback platform. A product manager inspects any element on a running product, pins a comment to it, and captures a screenshot. Comments persist and re-anchor across redeploys, and are handed to Claude Code via MCP as an actionable, fully-contextualized backlog. A browser extension does the same on any site without an SDK install, and a Laravel package embeds the whole loop into a PHP app.

It's built like a product, not a prototype: an SDK, a backend, a triage board, an MCP server, and a browser extension — all open source, all TypeScript — plus a first-party Laravel package. Everything runs locally with no external services (embedded Postgres via PGlite).

The packages

Author: Mohamed Ashraf Elsaed. Published to npm (@loupekit/*), GitHub Packages, and Packagist (loupekit/laravel).

Quick start

Everything is orchestrated from the repo root. Build once, seed the demo project, and start the server — a single process hosts the API, dashboard, demo product, and SDK bundle on one port.

# install workspace deps
npm install

# build shared → sdk → dashboard → extension
npm run build

# create the demo project; prints its admin key + demo HMAC
npm run seed

# one process on http://localhost:8787 → API + dashboard + demo + SDK
npm start

Embed the SDK in your product

import { init } from "@loupekit/sdk";

init({
  projectKey: "pk_demo_acme",
  user: { id: "u_92", name: "Ada Lovelace" },
  userHmac: "<HMAC-SHA256(user.id, PROJECT_SECRET)>", // from your server
  apiBase: "http://localhost:8787", // omit → offline localStorage mode
});

Connect Claude Code over MCP

{
  "mcpServers": {
    "loupe": {
      "command": "node",
      "args": ["/abs/path/to/loupe/packages/mcp/index.ts"],
      "env": {
        "LOUPE_API": "http://localhost:8787",
        "LOUPE_PROJECT_KEY": "pk_demo_acme",
        "LOUPE_ADMIN_KEY": "<admin key>"
      }
    }
  }
}

Verify everything with npm test (Vitest) and npm run test:coverage for a v8 coverage report.

The feedback loop

SDK (in the product) → backend API → Postgres + object storage → dashboard (human triage) and MCP server (Claude reads it) → status flows back.

1. Inspect & comment. A PM clicks an element or drags a region. The SDK records a multi-signal anchor, the element's HTML and computed styles, and a screenshot.
2. Store. The screenshot uploads to POST /v1/blobs; the comment (with the returned URL) is written to Postgres against the normalized page URL.
3. Triage. A human works the Kanban board — open → in progress → done — with screenshots and the exact selector.
4. Ship with Claude. Claude Code reads the same backlog over MCP, makes the change, and marks it done. Status flows back either way.

Both capture surfaces (SDK and extension) and both triage surfaces (dashboard and MCP) share the same data and contracts — see Seams for the extension points.

Working in the repo

Loupe is an npm workspaces monorepo. Root scripts orchestrate the packages.

@loupekit/shared is a built package (tsc → dist) and must be built before the others. Keep changes behind the seams (StorageAdapter, db.ts, blobs.ts, the captureScreenshot hook) — change implementations, not contracts.

Re-anchoring — the crown jewel

The hardest problem Loupe solves: a comment pinned to an element must find that same element again after the product is redeployed and the markup has changed. fingerprint.ts records a multi-signal fingerprint with captureAnchor(el): Anchor, then re-locates it with resolveAnchor(anchor, root?): ResolveResult | null in tiers.

What the anchor records

Stable id / testid, a CSS path rooted at the nearest stable ancestor, XPath, normalized text, identifying attributes, nth-of-type, and the bounding rect + viewport.

Resolution tiers

The similarity scan weights are: text .34 · attrs .22 · testid .22 · cssPath .20 · tag .12 · position .10. If the best candidate scores below 0.5, the pin detaches rather than anchoring to the wrong element.

Authentication

Every project has a secret. There are two identities, and the browser never sees the secret.

The Laravel package swaps this whole scheme for Laravel's own session + CSRF + guard + Gate authorization — no shared secret. See Authorization.

URL normalization

Comments are keyed by normalized URL, so tracking params never fragment a page's feedback. normalizeUrl(input) strips utm_*, click ids (gclid, fbclid, msclkid, …), and Loupe dev params (api, key), sorts the remaining query pairs, and drops trailing slashes. It's applied server-side on both write and the list filter.

normalizeUrl("/checkout?utm_source=x&gclid=123&step=2")
// → "/checkout?step=2"

Screenshots & storage

The SDK uploads a PNG to POST /v1/blobs and stores only the returned URL on the comment. Two things are excluded before pixels ever leave the browser: any [data-loupe-redact] region and Loupe's own UI.

• Capture engine. The SDK uses modern-screenshot (DOM-based). The extension overrides this with chrome.tabs.captureVisibleTab for real pixels, then crops to the element/region and paints over redacted areas (accounting for devicePixelRatio).
• Font embedding. Capture awaits document.fonts.ready (capped at ~0.8s) with a 6s capture timeout and a hard outer timeout, so it renders with the right fonts but can never hang the widget. CORS-less fonts fall back to the pixel-perfect extension.
• Blobs seam. blobs.ts stores to local disk today (public by unguessable id); production swaps in S3/R2 with signed URLs.

Seams (extension points)

Four seams isolate the swappable parts. Change what's behind them, not their contracts.

Package

The contract layer — canonical data types and pure helpers. Everyone imports types from here; Node packages import the compiled JS.

Exported types

Helpers

• deviceType(width): DeviceType — mobile <768, tablet 768–1023, desktop ≥1024.
• normalizeUrl(input): string — see URL normalization.

Package

The embeddable browser widget — the thing a developer installs. Builds a Shadow-DOM host (#loupe-root) so its CSS never leaks into the host page or vice-versa.

Public API

• init(config: LoupeConfig): void — idempotent; requires projectKey and user.id. Starts on DOMContentLoaded. apiBase set → HttpAdapter; omitted → LocalStorageAdapter (offline mode).
• destroy(): void — tears down the toolbar and all listeners.

Toolbar modes: Inspect & comment, Note (a free page-level comment), Region shot, Comments. Drag the ◎ Loupe logo to move the whole bar anywhere on screen; click it to collapse. A moved bar expands edge-aware so it's always on-screen — vertical against a left/right edge, horizontal along the top/bottom.

LoupeConfig

Internal modules

The StorageAdapter contract: list(projectKey, url), save(comment), update(id, patch), remove(id). A demo product ("Acme Analytics") lives in demo/, served at /demo/.

Package

The API — node:http, Postgres, object storage, auth, and static hosting. index.ts exports handler and start(port = PORT), and only listens when run as the entry point (so tests mount handler on an ephemeral port).

HTTP routes

CORS echoes the request Origin; allows GET, POST, PATCH, DELETE, OPTIONS and headers Content-Type, X-Loupe-User, X-Loupe-Hmac, X-Loupe-Admin, X-Loupe-Project. Body limit 12 MB.

Environment variables

Package

The Kanban triage board — vanilla TypeScript, tsup-bundled. Three columns (Open · In progress · Done) with a page filter, screenshot thumbnails, status moves (PATCH), two-step delete, Copy for Claude, and a ~4s live refresh.

Package

The MCP stdio server that exposes the backlog to Claude Code. Authenticates to the API as admin. Install globally with npm i -g @loupekit/mcp (binary loupe-mcp), or point Claude Code at the source entry directly.

What Claude gets

The natural-language request, the page URL, the target element (stable id or CSS path), its outerHTML, a curated slice of computed styles, and the screenshot URL.

Tools

Environment

Transport is stdio via @modelcontextprotocol/sdk. The published package ships compiled JS (dist/index.js via tsup), so npm i -g @loupekit/mcp gives a working loupe-mcp binary; from a source checkout it runs directly with node index.ts. See Quick start for the .mcp.json.

Package

An MV3 browser extension that reuses the exact SDK core — Loupe on any site, no install on the target. The only difference from the SDK is the screenshot source: chrome.tabs.captureVisibleTab gives real pixels, cropped to the element/region with redaction, via the SDK's captureScreenshot override.

Loupe for Laravel

loupekit/laravel

A Composer package that installs the entire loop into any Laravel app: an in-app widget, comments in your database, per-user access control, a Laravel-served triage dashboard, and a first-party MCP server — session-authenticated, no HMAC wiring, no secrets in the browser.

Requirements

• PHP 8.4+; Laravel 11 / 12 / 13 (9/10 intentionally unsupported).
• Any Eloquent-supported database — MySQL, PostgreSQL, SQLite, SQL Server.
• MCP is optional (laravel/mcp ^0.8), guarded by class_exists.

Install

composer require loupekit/laravel
php artisan loupe:install   # config, migration, assets, provider stub
php artisan migrate
# add @loupeWidget before </body>, then open /loupe/dashboard
php artisan mcp:start loupe  # expose the backlog to Claude (optional)

loupe:install publishes the config, the migration, the browser assets to public/vendor/loupe, and app/Providers/LoupeServiceProvider.php (auto-registered in bootstrap/providers.php). The @loupeWidget directive injects the SDK <script> + Loupe.init({...}) — but only for users who pass loupe:use.

Publish individual pieces with the vendor:publish tags: loupe-config, loupe-migrations, loupe-assets, loupe-provider, loupe-views.

Routes

Authorization

Two abilities gate everything: loupe:use (see the widget, create/update comments) and loupe:admin (open the dashboard). Denied users never receive widget markup; API/dashboard return 403.

Authorization is decided in this order:

1. Loupe::useWhen() / Loupe::adminWhen() closures (registered in code).
2. Config closures authorize.use / authorize.dashboard.
3. Frictionless access in the local environment, if allow_in_local (default true).
4. Gate abilities loupe:use / loupe:admin — deny by default (secure in production).

Configuration

The dashboard is the exact @loupekit/dashboard bundle, vendored and configured via an injected window.__LOUPE__ (API base, project key, CSRF) — no secret in the browser. The data lands in a loupe_comments table (see the data model).

Multi-guard & CDN

Multiple auth guards

Apps using separate guards (e.g. web for users, admin for admins) could render the widget under one guard and authenticate the API under another, mismatching ids and producing a 403 "cannot post as another user". Set an ordered guard list and Loupe resolves identity the same way everywhere — widget author, gates, API middleware (loupe.auth), and the anti-spoof check.

LOUPE_GUARDS=web,admin   # unset = the app's default guard (backward compatible)

Behind a CDN / ASSET_URL

Loupe resolves its published assets from the app URL via Url::asset(), bypassing ASSET_URL — so apps pointing ASSET_URL at a CDN (with only their Vite build uploaded) don't get 404s and a silently missing widget. Serve public/vendor/loupe elsewhere? Point LOUPE_ASSET_URL at it and re-run vendor:publish --tag=loupe-assets --force.

MCP server (Laravel)

With laravel/mcp installed, a server named loupe is registered automatically. Start it with php artisan mcp:start loupe. Unlike the Node MCP server, the tools read the app's own database directly — no HTTP hop, no admin key.

• list_comments(status?, url?) — the backlog, newest first.
• get_comment(id) — request + element HTML + computed styles + screenshot URL (or region rect).
• update_status(id, status) — validates open / in_progress / done.

For different-subdomain SPA frontends (Sanctum), add EnsureFrontendRequestsAreStateful + auth:sanctum to middleware.api and use credentials: 'include'.

Troubleshooting

Feature guide

Cross-cutting SDK features ship simultaneously to the standalone SDK, the browser extension, and the Laravel widget — all three share the @loupekit/sdk core.

Data model

Two tables in Postgres. Comments are keyed by normalized URL.

CREATE TABLE projects (
  project_key     TEXT PRIMARY KEY,
  name            TEXT,
  secret          TEXT,
  allowed_origins TEXT[] DEFAULT '{}',
  created_at      TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE comments (
  id             TEXT PRIMARY KEY,
  project_key    TEXT REFERENCES projects ON DELETE CASCADE,
  url            TEXT,
  status         TEXT DEFAULT 'open',
  body           TEXT,
  author  JSONB,  anchor  JSONB,  context JSONB,  "offset" JSONB,
  kind    TEXT DEFAULT 'element',           -- additive
  region  JSONB,  viewport JSONB,             -- additive
  screenshot_url TEXT,
  created_at     TIMESTAMPTZ DEFAULT now()
);
CREATE INDEX comments_project_url ON comments (project_key, url);

Testing

Runner is Vitest + v8 coverage. DOM code runs under happy-dom (opt-in per file); the rest runs in Node.

npm test              # run the suite once
npm run test:watch    # watch mode
npm run test:coverage # text + HTML report in coverage/

Coverage is ~91% lines / ~85% statements. Pure-logic modules sit at or near 100% (server/store, server/blobs). Deliberately under-covered: db.ts's pg branch (needs a live Postgres), the modern-screenshot redaction filter, and the rAF/MutationObserver-driven app code that needs a real layout engine. The extension's content.src.ts is validated by the manifest test + build rather than executed (it needs Chrome APIs + canvas).

The Laravel package runs an Orchestra Testbench suite across every PHP × Laravel combination in CI, under a 100% line-coverage gate (composer test:coverage-100).

Releasing & publishing

Loupe uses Semantic Versioning and ships through GitHub Releases backed by annotated tags (vX.Y.Z). MAJOR = breaking change to a public contract (SDK init, HTTP routes, MCP tool shapes, DB schema); MINOR = compatible features; PATCH = compatible fixes.

Two channels, two registries

Publishable to npm: @loupekit/shared, @loupekit/sdk, @loupekit/mcp. Publish shared first — mcp imports it at runtime. The Laravel package is split to its own repo by CI and picked up by Packagist; one vX.Y.Z tag ships npm + Packagist together. The extension ships to the Chrome Web Store.

Changelog

Follows Keep a Changelog + Semantic Versioning. Current release: 0.5.2 (2026-07-15).