XPath Recorder (Chrome Extension)

Version: 1.0.0
Purpose: Record user clicks across pages — capture each element's XPath and a screenshot (cropped or full viewport) and export as JSON or ZIP.

---

Features

• Record clicks anywhere on pages (XPaths + screenshots).
• Persist recording state across navigation and reloads.
• Toggle cropping: capture only element vs. full viewport with red outline.
• Popup UI with Start/Stop controls, recording status, item count.
• Export recorded items to:
  • JSON (metadata only)
  • ZIP (JSON metadata + screenshot image files)
• Simple modern UI with visual feedback and toast messages.
• Extension badge shows REC when active.

---

File Structure

xpath-recorder/
├── manifest.json
├── background.js
├── content.js
├── popup.html
├── popup.js
├── style.css
├── libs/
│   ├── jszip.min.js
│   └── FileSaver.min.js
└── icons/
  ├── icon16.png
  ├── icon48.png
  ├── icon128.png
  └── ...

---

Installation / Testing (Developer Mode)

1. Create a folder named xpath-recorder-extension/.
2. Copy each file from this repository into that folder, preserving the paths.
3. Make sure you add the third-party library files into libs/:
   • jszip.min.js (JSZip production build)
   • FileSaver.min.js (FileSaver production build)
4. Add simple images to icons/ (16x16, 48x48, 128x128).
5. Open Chrome and go to chrome://extensions/.
6. Enable Developer mode (toggle in top-right).
7. Click Load unpacked and select the xpath-recorder-extension folder.
8. The extension should appear in the toolbar. Click it to open the popup.

---

Usage

1. Open the popup and click Start Recording. Badge will show REC, and the popup shows "Recording…".
2. Navigate to any website (recording persists across pages).
3. Click elements you want to record — each click captures a screenshot and XPath.
4. In the popup, view the number of recorded items.
5. Use Download JSON to get metadata (XPaths, URL, timestamp, rect but without embedded images).
6. Use Download ZIP to get a ZIP that includes xpath-records.json and all screenshots (screenshot-...png).
7. Use Clear to delete recorded items.
8. Toggle "Crop to element" in popup to control whether screenshots are cropped to element or full viewport with an outlined rectangle.

---

Implementation Notes & Limitations

• The extension captures the visible viewport using chrome.tabs.captureVisibleTab in the background service worker and forwards the DataURL to the content script which performs cropping or outlines using canvas.
• Record items are stored in chrome.storage.local under key xr_records. Recording state is under xr_recording.
• Popup relies on the included jszip.min.js and FileSaver.min.js. Make sure to include the actual library files in libs/.
• The content script highlights the clicked element briefly for user feedback.
• This extension uses Manifest V3 (service worker background script). Some behaviors (like capture) rely on the active window/tab.

---

Troubleshooting

• If the popup shows count 0 after clicking elements, make sure recording is started (Start Recording).
• If screenshots are blank/partial, try capturing again or make sure you didn't block the tab's capture capabilities.
• If downloads fail, open DevTools for the popup (right-click popup → Inspect) to see console errors.

---

Security & Privacy

• This extension captures screenshots of web pages. Only enable recording when you want to capture content. Do not use on sensitive pages (banking, secure auth) unless you understand the implications.
• All captured data is stored locally in Chrome storage and exported files are created locally by your browser.

---

Development

• content.js handles click interception, XPath computation and element highlight, and receives screenshot data from background script.
• background.js handles recording state, captures viewport screenshots, and sends screenshots back to the content script.
• popup.html + popup.js is the control UI and export logic (JSON/ZIP using JSZip & FileSaver).

---

📜 License

MIT License – free to use and modify.