rclone-jav Consolidation — Final Converged Plan

Status: execution in progress. Shipped: steps 1 (Sim Dupe delete), 2 (CSS extraction), 3 (Transfer Assistant delete + Diagnostics replacement), 5 (Recent Activity + Search Troubleshooting → new Debug Tools pane). Pending: steps 6 (options.js split — Cache & Dup Review paired, biggest), 7a (Bulk Check standalone window), 8 (fixtures), 9 (cache contract), 10 (rc-jav.py split), 11 (host fast-path decision). See D:\DEV\Extensions\Production\rclone-jav\AGENTS.md "Console consolidation refactor — execution status" for current state.

✓ Decided

Console / Settings / Support tri-split
Default landing = Duplicate Review
Status badges on tabs, no dashboard pane
Launcher pattern over toolbox
Keep Ranking nested in Dup Review
Sim Dupe → delete, samples/ HTML harness
Transfer wizard → delete after Diagnostics replacement verified
Bulk ID Check → detached chrome.windows popup, NOT a Console sidebar tab
Inline rule tests stay, standalone benches → Debug

✓ Shipped

Step 1: Sim Dupe deleted from popup. samples/sim-dupe.js preserves payload.
Step 2: CSS extracted → options.css. options.html 1179 → 794 lines.
Step 3: Transfer wizard deleted. Diagnostics → Native host registration now shows Extension ID + Copy button.
Step 5: Recent Activity + Search Troubleshooting moved to new Debug Tools pane. Scope verified by code read.

📋 Pending

Step 6: options.js split (Cache + Dup Review paired). 3133-line file. Biggest, riskiest.
Step 7a: bulk-check.html standalone + popup launcher.
Steps 8–10: fixtures, cache contract, rc-jav.py split.
Step 11: host fast-path benchmark + narrow/delete decision.

1. Primary recommended layout

Default landing = Duplicate Review (user's most-frequent maintenance workflow). Sidebar tab labels carry live status badges — no dashboard pane needed. Launcher pattern: heavy tools open focused panes, not nested fieldsets.

rclone-jav

Duplicate Review 27 pending

After-upload workflow. Risky groups skipped by default. Keep Ranking lives here as configuration, not in a separate Settings tab.

Pending Review Skipped — Risky Keep Ranking Rules Delete History

Filter (this tool only)

Filters scoped — never exported as global settings.

Delete queue

12 files · 47.3 GiB

Safety: VIP folders + multipart-risk paths auto-excluded.

JBD-291 · 2 candidates

/JAV/clearjav/JBD-291 [1080p].mp4 4.94 GiB KEEP

/JAV/old/JBD-291.mp4 3.82 GiB

OFJE-195 · multipart risk

/JAV/OFJE-195_PART1.mp4 2.10 GiB REVIEW

/JAV/OFJE-195_PART2.mp4 2.08 GiB REVIEW

2. Decision table (refactor spec data)

Each current pane mapped to its future home, treatment, ship order, and replacement work (if any). Ship order = execution sequence within phase 3 (UI consolidation). Steps share PR scope where useful.

KEEP visible CONTEXTUAL (lives with feature) MOVE (relocate) DEBUG only DELETE

#	Current surface	Future home	Treatment	Replacement
1	Sim Dupe popup action	`samples/popup-states.html` (repo file)	DELETE	No product replacement. Repo HTML for layout testing only.
2	CSS embedded in options.html	Per-pane `.css` files alongside per-pane JS	EXTRACT	No behavior change. Reduces options.html before JS split.
3	Transfer Assistant wizard	(gone)	DELETE	Replacement = Diagnostics 3 actions (see §3 checklist). Delete after verification.
4	Cache & Scans pane	Console → Cache & Scans	KEEP	Paired with Dup Review extraction. State interface shared.
4	Duplicate Review pane	Console → Duplicate Review (default landing)	KEEP	Same PR as Cache & Scans. Reads cache state.
4	Keep Ranking Rules pane	Duplicate Review → Keep Ranking Rules (sub-tab)	CONTEXTUAL	Moves with Dup Review. Becomes nested sub-tab.
4	VIP folders config	Duplicate Review → Keep Ranking Rules	CONTEXTUAL	Feature-specific config moves with feature.
5	Recent Activity (search/page history)	Support → Debug Tools → Search Activity	DEBUG	If audit deletion events also present, split out (pending verification).
5	Search Troubleshooting	Support → Debug Tools	DEBUG	Standalone bench. No edit locality.
5	Page Extraction Test (standalone)	Support → Debug Tools	DEBUG	Inline "Pick Element" variant stays in Site Extraction settings.
5	Test ID Extraction (inline)	Settings → Matching Rules (collapsible per editor)	CONTEXTUAL	Editor feedback. Stays beside rule it tests.
5	Test ID Extraction (standalone bench)	Support → Debug Tools	DEBUG	Second row — split from inline version above.
6	Library Issues pane	Console → Library Issues	KEEP	Own tab + status badge. Rename UI nested as sub-tab.
6	Bulk ID Check	`bulk-check.html` — detached `chrome.windows` popup	RESHAPE	Removed from Console sidebar. Single entry path = popup launcher button → opens 640×540 detached window. Different tool type than Console panes (transient utility, no sidebar context).
7	Profiles, Scan Behavior, Overlays, Deletion settings	Settings → (separate sub-tabs)	KEEP	Settings sub-tabs split into separate JS files.
7	Matching Rules / Site Extraction	Settings → (separate sub-tabs, inline tests retained)	KEEP	Collapsible inline tester beside each rule.
8	(new) Shared fixture corpus	Top-level `fixtures/` (neutral location)	NEW	Contract between extension and Python. Both consume.
9	Cache contract design	CACHE_VERSION (exists) + ID_RULES_VERSION (new)	NEW	Schema bump = force rebuild. Rules bump = warn-and-mark-stale.
10	rc-jav.py monolith	`rcjav/` package (ids, cache, dupes, catalog, …)	SPLIT	After fixtures + tests + cache contract exist.
11	Host fast-path search	Narrow / Delete / Keep — based on §4 benchmark	DECIDE	Benchmark idle + under-scan latency first.

3. Pre-execution checklists (user handoffs)

Diagnostics replacement verification (gates step 3 — Transfer wizard delete)

Current extension ID shown as one-line text with copy-to-clipboard button

Replaces wizard's "your extension ID is…" step.

user opens
Diagnostics

Button labeled "Re-register host" that triggers register-host.bat path

Replaces wizard's "run this script" step.

user opens
Diagnostics

Verification result shown inline within 2s of register click

Replaces wizard's "now check the result" step.

user opens
Diagnostics

All three above visible without expanding collapsed sections (one screen)

If buried in expandable cards, write better UI first.

visual
inspection

Recent Activity scope test (settles split question)

Open Recent Activity. Note current entry types visible.

LIVE search, CACHE search, MATCH, NO_MATCH, NO_ID, page-check, etc.

user

Perform a delete in Duplicate Review. Refresh Recent Activity.

Single delete operation, any candidate.

user

If delete event appears → audit value exists. Split into Dup Review → Delete History.

If no → single role. Move entire log to Debug Tools.

user reports

Cosmetic remaining: popup launcher button label "Bulk Check" vs icon-only. Either works. Default to label until popup row gets crowded.

4. Bulk Check — detached window pattern

User clarified: Bulk Check is a transient utility, not a persistent Console surface. Doesn't fit sidebar-tab pattern alongside Dup Review / Cache & Scans / Library Issues. Decision: standalone bulk-check.html opened as detached chrome.windows popup, no Console sidebar entry. Single canonical entry path = popup launcher button.

Browser-action popup with launcher

Detached window (640×540) after launch

Detached window. No tab bar, no address bar. Closes cleanly when done. Sits over browser, stays visible across tab switches.

Why detached window, not Console tab

Other Console tools (Dup Review, Cache & Scans, Library Issues):

long workflows, multi-pass
need sidebar context (compare to other tools)
persistent state (review queue, scan job)
fit Options sidebar tab pattern

Bulk Check:

short workflow, one-shot
no sidebar context needed
transient state (last-paste persisted, results ephemeral)
fits detached-window pattern

Different tool type. Treating it like Dup Review was a category error. Single user knows the feature exists — discovery via popup button is enough.

Implementation notes

// Popup launcher click handler
chrome.windows.create({
  url: chrome.runtime.getURL('bulk-check.html'),
  type: 'popup',
  width: 640,
  height: 540
});

Window dedup: track open bulk-check window ID in chrome.storage.session. Second launcher click focuses existing window instead of spawning duplicate.
State persistence: last paste saved to chrome.storage.local key bulk_check_last_paste. Reopen restores. Results are ephemeral (re-run on reopen).
Backend reuse: calls native host via same messaging path popup search uses. No new backend code.
No back nav: window can't navigate. User closes when done. Ctrl+W closes the bulk window, not a browser tab.

Edge cases

Popup auto-closes after launcher click (Chrome behavior). Window survives. Good — that's the intent.
Window positioning unreliable. Chrome treats left/top as hints, multi-monitor users may get the window on the wrong screen. Acceptable for personal-use tool.
Brave / Edge variance. Detached popups behave slightly differently across Chromium forks. Test on user's actual browser before shipping. Fallback if broken: open bulk-check.html in a normal tab via chrome.tabs.create.

Does NOT generalize

Detached-window pattern fits Bulk Check because it's transient + no-sidebar-context + short. Doesn't apply to:

Diagnostics — reference info, lives in sidebar fine
Setup repair button — already inline in Diagnostics, small enough
Dup Review / Cache & Scans / Library Issues — long workflows, sidebar context useful
Settings — set-and-forget, not workflow

One-tool answer, not a pattern across the app.

5. Execution sequence (final)

Codex's revised order (triage first, boundary doc second) with my refinements. Risk and dependencies marked. Steps 1–4 are reversible single-file changes (warmup phase). Steps 5–10 = structural. Step 11 = final architectural call.

Per-pane triage — 30 min with user. Decision table above IS this artifact.

zero riskno deps

Boundary ownership doc — extension extracts query ID, Python owns filename semantics, host adapts. 1 hour, no code.

zero riskafter #1

Host fast-path benchmark — latency under idle Python AND under scanning Python. Result gates step 11.

measure onlyno deps

Delete confirmed surfaces — Sim Dupe popup button (no replacement), Transfer wizard (after Diagnostics verification passes).

trivialafter §3 checklist

CSS extraction from options.html — per-pane CSS files. No behavior change. Bisect-friendly.

lowafter #4

options.js split: Cache & Dup Review paired — Dup Review reads cache state. Single PR extracts both. Keep Ranking moves with Dup Review.

moderateafter #5

options.js split: Debug Tools + Library Issues + Settings sub-tabs — remaining Options extractions. Inline test components reused across rule editors. Bulk Check is NOT here — it's a new standalone file (step 7a).

moderateafter #6

Create bulk-check.html standalone + popup launcher button — new HTML file, own JS module, no Options dependency. Popup gets one button calling chrome.windows.create. Window dedup + state persistence in chrome.storage.

additiveparallel to #7

Shared fixture corpus — top-level fixtures/ (neutral). Python and extension both consume.

additiveno blocking

Cache contract design — CACHE_VERSION (exists) + ID_RULES_VERSION (new). Schema vs semantics, two concepts.

design decisionbefore #10

rc-jav.py module split — ids.py, cache.py, dupes.py, catalog.py, rclone_io.py, cli.py. Tests pre-exist via #8.

code churnafter #8, #9

Host narrow / keep / delete — based on #3 benchmark. If under-scan responsiveness depends on host = keep narrow. If not = delete.

behavior changeafter #3, #10

6. Acceptance criteria template

Each step in the sequence needs three things in the final spec: acceptance criterion, rollback procedure, touched-files list. Without these, "ship order N" is a wish not a plan. Template below — fill per step in spec doc.

Template per sequence step

step: 6
title: options.js split — Cache & Dup Review paired

touched_files:
  - options.html (script tag order changes)
  - options.js (DELETE: cache section, dup review section, keep ranking section)
  - options-cache.js (NEW)
  - options-review.js (NEW)
  - options-core.js (NEW: shared helpers, pane nav, save/load)

acceptance:
  - Fresh extension reload, options.html opens
  - Default landing = Duplicate Review tab
  - Cache & Scans tab loads, shows last scan timestamp
  - Run Duplicate Review on existing cache — same result set as pre-refactor
  - Keep Ranking Rules sub-tab inside Dup Review opens
  - No console errors on load or interaction

rollback:
  - git revert <sha>
  - No data migration. Cache schema unchanged. Storage keys unchanged.
  - Diagnostics-verified replacement of Transfer wizard remains intact (step 3 already shipped).

7. Out of scope (explicitly rejected)

Dashboard pane — tab badges replace. Adding a dashboard creates a feature sink.
After-Upload workflow wizard page — sidebar nav order already encodes the workflow.
Matching Lab consolidation page — inline tests cover editor needs, standalone bench in Debug covers diagnostic needs.
Mode switcher top bar (Console / Settings / Support segmented control) — sidebar groups do this.
In-extension Sim Dupe / Debug Preview page — repo HTML file is enough for single-user layout work.
Popup bulk mode toggle — popup stays single-job. Launcher button opens detached window, no inline bulk mode.
Bulk ID Check as Console sidebar tab — wrong tool type for sidebar pattern. Detached window matches its transient nature.
Bulk Check as Options-page deep-link tab — previously considered. Rejected: leaves a leftover tab open after use, Options sidebar adds noise to a one-shot tool.
Frontend framework (React/Vue/Svelte) — vanilla + ordered script files is correct for MV3 + project scale.
Console.log telemetry for usage audit — manual triage of single-user project beats instrumented signals.

8. Net position

Architecture decided. Three small user handoffs remain (Diagnostics verification, Recent Activity scope check, popup button label). After those, decision table expands into per-step spec with acceptance + rollback. Code work begins on step 1 (smallest, fastest, lowest risk). Total estimated execution span: phased over multiple PRs, no big-bang refactor.