Skip to content

Rewrite roadmap to match the code, complete M1 cleanup, and remove dead modules - #4

Draft
MadTinker wants to merge 3 commits into
mainfrom
claude/project-roadmap-review-qlb7j0
Draft

Rewrite roadmap to match the code, complete M1 cleanup, and remove dead modules#4
MadTinker wants to merge 3 commits into
mainfrom
claude/project-roadmap-review-qlb7j0

Conversation

@MadTinker

@MadTinker MadTinker commented Aug 22, 2026

Copy link
Copy Markdown
Collaborator

Why

The roadmap and readme had drifted roughly a year behind the implementation. The roadmap listed visual testing, network inspection, DOM tooling, and WebSocket control as unstarted while all four were built and shipping — and never mentioned the MCP server, by now one of the largest modules in the repo. The readme billed the project "production-ready" while marking built features as in-progress.

This PR rewrites the roadmap against the actual code, then executes its first milestone.

Three commits: rewrite the roadmapdo the M1 cleanupremove dead modules.

1. Roadmap rewrite

Reorganized into two tracks over a shared foundation, matching the project's two audiences:

  • Track A — agent surface (MCP, MQTT)
  • Track B — testing workbench (record, replay, diff)

Every "built" claim cites its implementing file and test count, so the next reader can spot-check instead of trusting prose.

On the multi-JS-engine item

The old "JavaScript Engine Workshop" proposed embedding V8, SpiderMonkey, and JavaScriptCore with a switching mechanism. That isn't reachable from wry, which delegates to the OS webview and its bundled engine.

The underlying goal — seeing whether a bug reproduces across engines — is real, and Tinker is closer to it than the roadmap suggested. wry binds the native webview per platform, so the macOS and Linux builds already run WebKit/JavaScriptCore and the Windows build runs Chromium/V8. Two engine families, already covered, never compared. That becomes M4: run the same recorded session across the CI matrix and diff results, reusing the comparison machinery in browser/visual.rs. Engine embedding is recorded under "Explicitly not doing" with reasoning so it doesn't get re-proposed.

2. M1 cleanup

  • Rewrote the readme status section: what works, what's missing, what's unproven.
  • Documented the undocumented API surface — the readme listed ~20 endpoints, the router has ~55. Performance, console, recording, and playback were entirely absent.
  • Added docs/getting-started.md with native dependencies, the exact build failure they cause, and package names for Debian/Fedora/Arch.
  • Retired CURRENT_STATUS.md (July 2025, wrong on nearly every point) and both point-in-time implementation summaries, superseded by the fuller guides in docs/.
  • Deleted fix_plan.md — its blockers were fixed in March 2026. Salvaged its profile-management idea into the roadmap as M6.
  • Untracked a committed session transcript and error_log.txt; extended .gitignore.
  • Moved seven root-level Python scripts into tests/integration/ with a README.

3. Dead module removal

Nine files, ~1,100 lines, none declared in lib.rs, main.rs, or any mod.rs — so none had ever compiled:

File Lines #[test] fns (never ran)
src/browser/state_manager.rs 199 4
src/browser/navigation.rs 167 5
src/browser/window_manager.rs 158 3
src/browser/error.rs 153 4
src/browser/native_ui.rs 137 3
src/platform/macos.rs 124 2
src/browser/menu.rs 50 0
src/browser/tests.rs 10 1
src/cli/ ~15 0

Two of these were more than clutter:

  • src/cli/mod.rs held a stub Args::parse() returning defaults and ignoring all input, shadowed by the real clap parser in main.rs — an easy trap for anyone who found it first.
  • browser/error.rs was imported only by navigation.rs, window_manager.rs, and state_manager.rs, themselves dead. The cluster was self-referential, so an "is this imported anywhere?" check finds real references and concludes the code is live. Only comparing files on disk against mod declarations reveals it.

native_ui.rs is worth a note: its tests build real windows via WindowBuilder and are #[ignore]d on macOS but not elsewhere. Had it ever been wired up, it would have failed on any CI runner without a display.

Every remaining file under src/browser/ now maps to a declared module.

Verification

Installed the native dependencies and built from cold on Linux, which also confirms the package names documented in the getting-started guide:

cargo build --all-targets → success
cargo test                → 167 passed, 0 failed, 0 ignored

The test count is identical before and after the dead-module removal, confirming the ~21 #[test] functions in those files were never executed.

Note on scope

One idea from fix_plan.md was deliberately not carried forward: it framed profile support partly as "anti-detection," spoofing fingerprints to evade bot detection. The roadmap keeps the testing half — configurable user agent, viewport, timezone, locale — and says why the evasion framing was dropped. Per discussion these were future/half-formed plans, so this is a deferral, not a rejection.

claude added 2 commits August 22, 2026 17:38
The roadmap had drifted about a year behind implementation. It listed
visual testing, network inspection, DOM tooling, and WebSocket control
as unstarted while all four were built and shipping, and never mentioned
the MCP server at all.

Changes:
- Verified status table citing implementing files and test counts
  (~70 BrowserCommand variants, 147 tests across 27 files)
- Restructure into dual tracks: agent surface and testing workbench,
  over a shared foundation
- M1 targets documentation drift; M2 adds CI, which no workflow covers
  today despite the existing test suite
- Reframe the multi-JS-engine goal as cross-engine comparison over the
  CI matrix: wry binds the OS webview, so macOS/Linux already run
  WebKit/JavaScriptCore and Windows runs Chromium/V8. Embedding V8 or
  SpiderMonkey is recorded under "Explicitly not doing" with reasoning
- Note the cold-clone build failure on missing GTK/WebKitGTK headers

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pg53xf5xcUV7oc5CkaiCpz
Documentation had drifted about a year behind the code. Verified every claim
against a real build and test run on Linux.

Docs:
- Rewrite readme status section; it billed the project "production-ready"
  while listing built features as in-progress. Now states what works, what's
  missing, and what's unproven.
- Document the undocumented API surface: the readme listed ~20 endpoints, the
  router has ~55. Performance, console, recording, and playback were absent.
- Add docs/getting-started.md with the native dependencies, the exact build
  failure they cause, and package names for Debian/Fedora/Arch. Verified by
  installing them and building from cold.
- Retire CURRENT_STATUS.md (July 2025, wrong on nearly every point) and the
  two point-in-time implementation summaries, superseded by docs/.
- Delete fix_plan.md; its blockers were fixed in March 2026. Salvaged its
  profile-management idea into the roadmap.

Dead code:
- Delete src/browser/tests.rs and src/cli/. Neither was declared in lib.rs or
  main.rs, so neither had ever compiled. src/cli/mod.rs was the riskier one:
  a stub Args::parse() that ignored all input, shadowed by the real clap
  parser in main.rs.

Housekeeping:
- Untrack a committed session transcript and error_log.txt; extend .gitignore.
- Move seven root-level Python scripts into tests/integration/ with a README
  covering prerequisites and what each exercises.

Roadmap updates from findings during this pass:
- keyboard.rs is reachable from neither the API nor MCP, so keyboard-driven
  testing (tab order, accessibility) isn't scriptable. Added to Track A.
- main.rs re-declares modules lib.rs already exports, so the crate compiles
  twice and shared tests run twice. Added to M2.
- A clean build emits 91 warnings. Added to M2.

Verified: cargo build succeeds; cargo test reports 164 passed, 0 failed,
3 ignored.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pg53xf5xcUV7oc5CkaiCpz
@MadTinker MadTinker changed the title Rewrite roadmap to match the code Rewrite roadmap to match the code, and complete the M1 cleanup Aug 22, 2026
None of these files was declared in lib.rs, main.rs, or any mod.rs, so none
had ever compiled:

  src/browser/navigation.rs      167 lines
  src/browser/state_manager.rs   199 lines
  src/browser/window_manager.rs  158 lines
  src/browser/error.rs           153 lines
  src/browser/native_ui.rs       137 lines
  src/platform/macos.rs          124 lines
  src/browser/menu.rs             50 lines

The cluster was self-referential: error.rs was imported only by navigation.rs,
window_manager.rs, and state_manager.rs, all themselves dead. A naive "is this
imported anywhere?" check finds references and concludes the code is live.

Every remaining file under src/browser/ now maps to a declared module.

Also corrects two errors in ROADMAP.md introduced when it was written from a
static scan rather than a build:

- It cited browser/navigation.rs as implementing per-tab navigation history.
  That file never compiled; the implementation is in browser/tabs.rs.
- Its per-module test counts included tests in files that never ran.

Verified: cargo build succeeds; cargo test reports 167 passed, 0 failed,
0 ignored — identical to before the removal, confirming the ~21 #[test]
functions in the deleted files were never executed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pg53xf5xcUV7oc5CkaiCpz
@MadTinker MadTinker changed the title Rewrite roadmap to match the code, and complete the M1 cleanup Rewrite roadmap to match the code, complete M1 cleanup, and remove dead modules Aug 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants