Documentation

Quick start

Get from zero to your first audit in five steps.

1. Open /app/signup and create an account (first signup becomes superadmin).
2. Create a project. Copy the script tag or API config snippet with your ingest key.
3. Install the collector in your authenticated app (see Collector below).
4. Use the app for 15+ seconds, or run a synthetic test via POST /api/test.
5. Open the graded report in the dashboard. Copy the agent fix prompt and re-run after fixes.

Local development:

npm install
node server/server.js
node demo-app/app.js   # optional broken target app

Then open , sign up, and create a project.

Collector

The collector runs inside your authenticated app and streams batched telemetry to the ingest API. It never collects request or response bodies.

Script tag

Load the collector only from your Leaptr host. Do not self-host or copy the file. Production deployments serve a minified, versioned build (e.g. /collector.v1.0.0.js).

<script src="https://YOUR-HOST/collector.v1.0.0.js"
        data-endpoint="https://YOUR-HOST/api/ingest"
        data-key="YOUR_INGEST_KEY"
        data-domain="app.example.com"></script>

Unversioned /collector.js also works and tracks the latest build.

Integration security

• The collector is proprietary (see LICENSE-COLLECTOR). Licensed for use with an active Leaptr account only, not for redistribution.
• Ingest payloads are signed (HMAC-SHA256) with your project ingest key to reduce tampering and replay.
• Each project ingest key is bound to the domain set at registration. The snippet includes data-domain; the collector refuses to start on other hosts.
• Sessions must match the project's registered domain on every ingest batch.
• Set INGEST_REQUIRE_SIG=1 in production after all apps use a current collector.

API config (agent-built apps)

window.LEAPTR_CONFIG = {
  endpoint: "https://YOUR-HOST/api/ingest",
  apiKey: "YOUR_INGEST_KEY",
  domain: "app.example.com"
};
// then dynamically load https://YOUR-HOST/collector.js

Public API

After load, the collector exposes window.Leaptr with sessionId, flush(), and stop().

Defaults and opt-in features

Core breakage signals are on by default (errors, network calls, loading states, frustration, mobile UX). Product analytics and security heuristics are opt-in via LEAPTR_CONFIG:

window.LEAPTR_CONFIG = {
  endpoint: "https://YOUR-HOST/api/ingest",
  apiKey: "YOUR_INGEST_KEY",
  domain: "app.example.com",
  formTracking: true,       // form analytics
  searchTracking: true,     // search analytics
  scrollTracking: true,     // scroll depth
  featureTracking: true,    // requires data-feature attributes
  securitySignals: true     // DevTools / external script probes
};

CSP note

Strict Content-Security-Policy may block the script tag. Allow your Leaptr origin on script-src and connect-src (for ingest). Example:

script-src 'self' https://leaptr.com;
connect-src 'self' https://leaptr.com;

Or use the synthetic test path, which injects via headless browser.

Reports

Each session produces a graded client experience audit.

• Grade (A to F) with category scores for performance, reliability, and UX.
• Silent failures: spinners that never resolve, empty 200s, swallowed errors, dead interactions.
• Blind spots: session decay, concurrency risks, network reality, data shape issues.
• Scaling insights: workload projection from 100 to 1,000 concurrent users.
• Network simulation: estimated load on Fast 3G, Slow 3G, and other profiles.

Export formats:

• JSON: GET /api/report/:sessionId
• Markdown: GET /api/report/:sessionId.md
• Agent prompt: GET /api/report/:sessionId/agent-prompt
• Project overview prompt: GET /api/projects/:id/agent-prompt?daily=1
• Combined project markdown: GET /api/projects/:id.md (overview + all session audits)
• Regression diff: GET /api/projects/:id/regression

API reference

Discover all endpoints at /.well-known/leaptr.json.

Authentication

Dashboard UI: /app/login, /app/signup, /app/projects. Returns a JWT. Use as Authorization: Bearer <token> or httpOnly cookie after login.

New accounts must verify email before projects, reports, billing, or admin routes are available. Verification link: /app/verify?token=.. or GET /api/auth/verify-email?token=... Resend: POST /api/auth/resend-verification (authenticated).

Projects

Ingest (collector)

Sessions and reports

Synthetic test

{
  "url": "https://app.example.com/dashboard",
  "auth": { "username": "u", "password": "p", "postLoginPath": "/dashboard" },
  "projectId": "optional",
  "durationMs": 15000,
  "slowNetwork": false
}

Credentials are used transiently in a headless browser and never stored.

Agent loop

Use Leaptr with a coding agent (Cursor, Claude Code, etc.) to test, fix, and verify in a loop.

1. POST /api/test to get a baseline grade.
2. GET /api/report/:id/agent-prompt to get the fix task.
3. Agent applies fixes in your codebase.
4. POST /api/test again to verify the grade improved.
5. Repeat until your target grade is met.

The agent prompt includes silent failures first, navigation journey, silent-failure summary, measured baseline, prioritized findings, duplicate endpoints, and scaling stakes.

Deploy

Production deployment with Docker:

cp .env.example .env
# Set JWT_SECRET, PUBLIC_ORIGIN, MONGODB_URI
docker compose up -d --build
docker compose logs -f leaptr

Required environment variables

• JWT_SECRET: strong random value (sessions persist across restarts)
• PUBLIC_ORIGIN: public URL where Leaptr is reachable
• MONGODB_URI and MONGODB_DB: recommended for production

Resources

Allocate at least 1.5GB RAM. Synthetic tests use Chromium (~400MB each). Set shm_size: 1gb in docker-compose for browser stability.

Playwright version pinning

Keep package.json playwright version matched to the Dockerfile base image tag (currently 1.60.0).

Verify deploy

curl https://leaptr.yourdomain.com/healthz
curl https://leaptr.yourdomain.com/.well-known/leaptr.json

See docs/DEPLOY.md in the repo for the full production checklist.

Privacy

Leaptr uses two-layer PII redaction.

• Client-side: the collector scrubs emails, JWTs, API keys, cards, SSNs, and passwords. URL query strings are stripped before data leaves the browser.
• Server-side: ingest re-applies the same redaction as a backstop.
• Never collected: request and response bodies.

Sessions carry an expiresAt field. A TTL index auto-deletes them after RETENTION_HOURS (default 7 days).

Tenant isolation: every session is scoped to its owner. Cross-tenant reads return 404.