FittsLab

FittsLab is a local-first website journey crawler, interaction recorder, Fitts’s-law analyzer, and evidence-to-implementation workspace. It helps a team observe how a product is actually used, explain interaction friction, iterate on a prototype with preserved design decisions, and hand the approved result to a coding agent without losing the route, behavior, or product intent.

Why FittsLab exists

FittsLab started with a real piece of feedback from someone using vvavy.io:

“The output is amazing, but the UI feels legacy.”

That was the problem. The product could create something people loved, but the interface made its power harder to discover and use. The feedback was honest and useful, yet still too broad to turn directly into a thoughtful product change.

We needed a way to move from a human reaction like that to evidence: watch the real journey, find where the interface creates friction, shape a clear design direction, and carry that direction into the actual product without losing what users already love. That need became FittsLab.

_{The recommended VVavy workspace, now implemented on the real /app route.}

Example: from evidence to a real change

VVavy example · July 26, 2026 Live site: vvavy.io and /app

VVavy is a browser-based audio visualizer. We used FittsLab to follow this real journey:

Launch the visualizer → accept the safety warning → choose audio and a visual → adjust the scene → record or share

The example uses only what was seen or recorded on that journey. It does not present guessed timings as measured results.

1. Gather evidence

The recording showed that the visual stays front and center, but its controls are spread across the top and bottom of the screen. Labels such as Sources and Settings do not tell a new user where to choose a visual, prepare a show, or publish it. The record action also competes with several nearby controls.

2. Turn the evidence into a design direction

FittsLab turned the evidence into a short set of changes:

Evidence	Suggested change
Main tasks are spread across small controls.	Add clear destinations for Visuals, Live tools, Playlist, and Studio.
Choosing a visual pulls attention away from the canvas.	Open the visual browser beside the canvas so the current scene stays visible.
Setup, performance, and publishing tools are mixed together.	Group live controls under Live tools and finishing steps under Studio.
Record is easy to lose among other actions.	Keep one clear record button in the main bar.

The result keeps the stage and player visible while giving each major task a clear home. The screenshot above shows that direction running in the real application, with the visual browser beside the active canvas instead of replacing it.

3. Carry the direction into the real app

After review, FittsLab carried the approved design, supporting evidence, target /app route, and behavior requirements into the VVavy codebase.

The implementation is complete only after the real route runs and its checks pass. For this example, the final review confirms that:

• /app uses the new task-based navigation.
• The canvas and player stay visible while a panel is open.
• The safety warning still blocks entry until it is accepted.
• Visual selection, playback, recording, streaming, and sharing still use the app's real behavior.
• The project's type checks, tests, and build pass.

The recommendation is no longer a standalone demo. It is part of the application and uses VVavy's real visual selection, playback, recording, streaming, and sharing behavior.

---

The FittsLab workspace

What it does

• Safely crawls same-origin application states with configurable origin, URL, selector, depth, action, and runtime boundaries.
• Records real browser journeys across pages, frames, popups, tabs, pointer movement, scrolling, and named inputs.
• Replays journeys deterministically without AI using layered locators and stop-on-failure diagnostics.
• Calculates target distance, effective width, index of difficulty, acquisition time, path efficiency, reversals, overshoots, regression, and throughput.
• Previews and redacts the exact payload before optional AI analysis, then requires explicit consent before transmission.
• Produces findings and information-architecture proposals linked to observed evidence.
• Saves product intent and carries it through analysis, prototyping, feedback, and implementation.
• Versions prototype iterations so feedback can add improvements while explicit “keep” items preserve accepted decisions.
• Hands implementation agents the prototype source and a structured design specification—not only screenshots.
• Locates the actual framework, router, and SPA source entry so a route such as /app is changed instead of treating index.html as the application screen.

Requirements

• Node.js 22.5 or newer
• npm 11 or newer
• Playwright Chromium
• macOS or Linux; WSL folder selection is supported through the Windows picker
• A graphical desktop session for visible recording and replay
• Optional: Codex CLI for the default AI analysis, prototype, and implementation workflow

Chromium is the MVP browser. Firefox, WebKit, touch-specific models, CAPTCHA bypass, anti-bot circumvention, and native dialogs are outside the current scope.

Quick start

git clone <repository-url>
cd fittslaw
npm install
npm run browsers:install
npm run doctor
npm run dev

Open http://127.0.0.1:5173. The local API listens only on 127.0.0.1:4317.

npm run doctor checks the Node.js version, Playwright Chromium executable, and Codex CLI. Missing capabilities include an exact remediation command. The server repeats these warnings during startup, and browser/agent failures surface the same actionable guidance in the dashboard.

For an optimized local build:

npm run build
npm start

Then open http://127.0.0.1:4317.

Instructions for automated agents and CLIs

An automated setup should not silently skip unavailable capabilities:

1. Run npm install when dependencies are absent.
2. Run npm run doctor and inspect every failed check.
3. If Chromium is missing, request any required network/filesystem permission and run npm run browsers:install.
4. If Codex-backed work is requested and Codex is missing, request permission and run npm install -g @openai/codex@latest, then have the user authenticate with codex login when necessary.
5. Report a blocked installation clearly instead of claiming browser or agent verification succeeded.

These rules are also recorded in AGENTS.md so repository-aware coding agents receive them as durable project guidance.

Typical workflow

1. Create a project

Provide the starting URL, allowed origins, and optional high-level product intent. Intent should describe the experience the product is trying to protect, for example: “The canvas is the primary experience, so controls should remain visually quiet until needed.”

2. Observe behavior

• Auto crawl maps conservative navigation paths and records blocked or review-required targets. Crawl maps are graph evidence, not interaction replays.
• Record journey opens a managed Chromium profile so a person can demonstrate the real flow.
• Replay reruns a human-recorded journey, including its pointer path, clicks, inputs, and scrolling, without calling an AI provider.

The crawl route allowlist accepts path patterns as well as full URLs. When the project URL is https://example.com and the first concrete include is /app, the crawler starts at https://example.com/app. The dashboard shows the latest crawl graph while retaining older runs in crawl history.

Browser cookies and storage remain in the project-specific local profile under .fittslaw/.

3. Review metrics and analysis

FittsLab derives pointer-acquisition metrics locally. Before AI analysis it shows the exact sanitized payload, reports redactions, and requires an explicit consent checkbox. Findings must cite evidence IDs from that payload.

4. Prototype and refine

The prototype agent creates a standalone interactive HTML screen, a full-page image, and a validated design-spec.json. The specification covers:

• Product and experience principles
• Target route paths and source hints
• Layout regions and layering
• Components and visible states
• Interaction and accessibility behavior
• Responsive rules and visual tokens
• Required content and asset roles
• Existing behavior to preserve
• Observable acceptance criteria

Feedback starts a separate saved iteration. Free-form changes and one-per-line “keep” decisions are stored with a parent prototype reference, so restarting FittsLab does not discard the accepted direction.

Prototype validation failures are repaired in the same temporary Codex session when possible. If a job still fails, Continue failed prototype resumes that session with optional recovery direction; older jobs without a saved session continue from their existing artifact files and reconstructed evidence prompt. Successful prototypes delete the temporary Codex session after validation and screenshot capture.

5. Implement in the real application

After explicit folder authorization, the implementation agent receives the approved prototype HTML, structured specification, project intent, iteration decisions, evidence manifest, and recorded locator hints. It must inspect the selected repository’s framework and router, identify the source component serving the analyzed route, apply the smallest cohesive change, and run relevant tests and builds.

Implementation attempts default to a two-hour timeout, configurable per attempt in the dashboard. A timed-out or otherwise failed implementation retains its authorized workspace and temporary Codex session so Continue implementation can resume with optional recovery direction. Older failed jobs without a saved session reconstruct the complete handoff and continue from the existing workspace diff. Successful implementations delete the temporary Codex session.

Codex and alternative AI providers

Codex CLI is the default provider and reuses the local Codex authentication:

npm install -g @openai/codex@latest
codex --version
codex login
npm run doctor

No FittsLab API-key environment variables are required for this path. Analysis uses an ephemeral read-only workspace and a strict JSON output schema. Prototype generation uses an isolated artifact workspace. Implementation receives write access only to the folder the user selects.

Optional Codex overrides:

export FITTSLAW_CODEX_BIN=/absolute/path/to/codex
export FITTSLAW_CODEX_MODEL=your-codex-model

To use an OpenAI-compatible HTTP provider for analysis instead:

export FITTSLAW_ANALYSIS_PROVIDER=openai-compatible
export FITTSLAW_AI_BASE_URL=https://your-provider.example/v1
export FITTSLAW_AI_API_KEY=your-key
export FITTSLAW_AI_MODEL=your-model

Prototype and implementation jobs still require Codex CLI because they operate on local files.

Configuration

Variable	Purpose	Default
PORT	Production API/dashboard port	4317
FITTSLAW_DATA_DIR	SQLite database, browser profiles, and artifacts	.fittslaw/
FITTSLAW_HEADLESS	1 makes replay headless; 0 makes crawl visible	Recording/replay visible, crawl headless
FITTSLAW_CODEX_BIN	Codex executable path	codex
FITTSLAW_CODEX_MODEL	Optional Codex model override	Local Codex default
FITTSLAW_AGENT_TIMEOUT_MS	General Codex task timeout in milliseconds	3600000
FITTSLAW_IMPLEMENTATION_TIMEOUT_MS	Default implementation timeout when the API does not provide one	7200000
FITTSLAW_PROTOTYPE_REPAIR_ATTEMPTS	Same-session validation repair attempts, from 0 to 5	2
FITTSLAW_ANALYSIS_PROVIDER	codex-cli or openai-compatible	codex-cli

Safety and privacy

• Automatic crawling blocks non-GET traffic, downloads, form controls, destructive labels, and non-allowlisted origins by default.
• Per-target Allow and Block decisions are persisted and remain visible under Explore → Safety decisions.
• Input values are replaced by named variables. Secret replay values stay in memory.
• Replay never invokes an AI model.
• Failure artifacts contain a screenshot and redacted DOM excerpt, not cookies or authorization headers.
• Cloud analysis sends derived evidence and sanitized text only after payload review and consent.
• Workspace authorization tokens are short-lived and single-use. Agents are instructed not to commit, push, or rewrite unrelated files.

Repository layout

packages/
  shared/   Zod contracts, metrics, crawl policy, and privacy helpers
  server/   Fastify API, SQLite store, Playwright browser service, and agents
  web/      React and Vite dashboard
docs/images/  README screenshots and diagrams intended for source control
.fittslaw/    Local runtime data; ignored by Git

Development and verification

npm run doctor
npm run typecheck
npm test
npm run build

The test suite covers metric math, crawl policy, redaction, SQLite persistence, consent boundaries, agent handoffs, prototype feedback lineage, API behavior, and real Playwright crawl/recording integration.

Troubleshooting

Playwright says the Chromium executable does not exist

npm run browsers:install
npm run doctor

In restricted environments, the installing agent must request network or filesystem approval before running the browser installation.

Codex cannot be found

npm install -g @openai/codex@latest
codex login
npm run doctor

Alternatively, point FITTSLAW_CODEX_BIN at an existing executable or configure the OpenAI-compatible analysis provider. The Codex installation command is also shown in OpenAI’s official Codex automation example.

Folder selection fails on Linux

FittsLab tries zenity, then kdialog. Install one of those desktop helpers or run in a supported WSL environment with Windows folder selection available.