# Site Snapshot — Chrome Extension

A simple, local-only site crawler + full-page screenshotter.

- Enter a start URL → it visits every linked page (BFS) up to a depth
  + page cap → saves a full-page PNG of each.
- Files land in your Downloads folder under `site-snapshot/<host>/`.
- **Nothing leaves your machine.** No upload, no cloud, no telemetry.

## Install (unpacked)

1. Open Chrome → `chrome://extensions/`
2. Toggle **Developer mode** (top right)
3. Click **Load unpacked**
4. Pick this directory: `/tmp/site-snapshot-ext/`
5. Pin the extension to the toolbar so the icon is visible

## Use

1. Click the toolbar icon
2. Either type the start URL or click **Use current tab**
3. Tweak:
   - **Max depth** — how far to follow links (1 = only the start page; 2 = start + linked pages; etc.)
   - **Max pages** — total page cap (safety against giant sites)
   - **Same-origin only** — leave on unless you want it to wander off-site
   - **Full-page screenshots** — uses the Chrome debugger API to capture the entire scrollable page in one PNG. Recommended.
4. Click **Start crawl**
5. Watch the log; click **Stop** any time
6. Output: `~/Downloads/site-snapshot/<host>/<path>__<timestamp>.png`

## Authenticated sites

The extension uses your existing browser session. If you're logged into
a site in this Chrome profile, the crawler sees the logged-in pages.

Works well for:
- Documenting your own admin panels (your portfolio of internal pages)
- Visual regression / archive of a site you control
- Capturing the structure of any web app for your own reference

The extension does **not** transmit any captured data anywhere. Whether
to share screenshots is your call, made after the fact, by manually
attaching files where you choose.

## Permissions justification

| Permission | Why |
|---|---|
| `tabs`, `activeTab` | Open the crawl tab; navigate to each URL |
| `scripting` | Run a tiny content script to extract `<a href>` from each page |
| `downloads` | Save the PNG files to disk |
| `debugger` | Full-page screenshot via `Page.captureScreenshot{captureBeyondViewport:true}`. While attached, Chrome shows the "is being debugged" yellow bar — that's the trade-off for full-page capture. Untoggle "Full-page screenshots" to skip the debugger entirely (visible-viewport only). |
| `storage` | Remember your last-used settings between popup opens |
| `host_permissions: <all_urls>` | Crawl is operator-driven; we don't know the target host upfront |

## Limitations

- No JavaScript-rendered SPAs that defer content load past the 800 ms
  grace period — bump the wait if needed
- No Single-Sign-On flows; relies on your already-logged-in session
- No PDF / report download — captures visible page only
- No clickstream / form interaction — pure crawl + capture

## Files

```
manifest.json      Chrome MV3 manifest
popup.html/css/js  UI shown when you click the toolbar icon
background.js      Service worker — owns the crawl state machine
icons/             Toolbar + extension-page icons
```

## Troubleshooting

- **"Debugger attach failed" in log**: another DevTools instance is
  attached to that tab/window. Close DevTools and retry, or untick
  "Full-page screenshots" to use viewport-only mode.
- **Pages keep redirecting to login**: you're not logged in to the
  site in this profile. Log in manually first, then start the crawl.
- **Filename collisions**: the extension uses `conflictAction:
  'uniquify'` so duplicates get auto-suffixed (`__1.png`, `__2.png`).
- **Too many pages queued**: lower **Max pages** before starting.
  Once the cap hits, crawling stops cleanly.