@hraness/sponge 0.6.7 → 0.6.9

package/README.md

@@ -41,6 +41,48 @@ websites.
 `doctor` reports runtime integrity and pending cleanup. Private-network capture
 requires `--allow-private-network` with `--wait` or `run --drain`.
 
+### Dead, blocked and paywalled pages
+
+`sponge status` counts saved web articles under 200 words (social posts aside),
+and `list --short` names them: usually a paywall stub, an error page or a page
+that needed scripts. `refresh ITEM --archive` (or `add URL --archive`) captures
+the newest Internet Archive copy instead, found through the Wayback Machine's CDX
+index, and fetches the raw saved bytes (`id_`) without the replay toolbar. The
+item keeps its original URL; the capture's `source_url` names the snapshot. Only
+`--archive` sends the URL to archive.org. No copy fails with `unavailable` and
+leaves the saved revision alone.
+
+archive.today (archive.ph, archive.is) has no API, answers automated clients with
+a CAPTCHA, and gives wrong DNS answers to some public resolvers, so Sponge does not
+fetch from it. To use one of its copies, open it in a browser and save it as a PDF;
+then `sponge add FILE.pdf` keeps it.
+
+### Signed-in pages through your browser
+
+The Sponge extension lets captures use the sign-ins you already have in Chrome
+(or Brave, Edge, Arc, Vivaldi, Chromium). Sponge asks the extension for a page;
+the extension loads it inside your browser and hands back only the page. Sponge
+never reads cookies, passwords or the browser's profile.
+
+1. `sponge browser setup` registers Sponge with each installed browser.
+2. In `chrome://extensions`, turn on Developer mode, choose "Load unpacked" and
+   pick the `extension/` folder that `setup` prints.
+3. `sponge browser status` (or `sponge doctor`) should say `connected`.
+
+Once the extension is connected, a page that comes back thin from the public web
+is tried again through the browser: first a plain fetch with your cookies, then a
+muted background tab that runs the page's scripts and closes afterwards.
+`refresh ITEM --browser` (or `add URL --browser`) skips the public web and reads
+only through the browser. Its popup and right-click menu save the current page or
+a link. If no browser is connected, a `--browser` job fails as `browser-offline`
+and can be retried.
+
+Pages captured through the browser start private. Any program running as you can
+ask the extension for a page through Sponge's local socket, the same reach it
+already has over your files. Turning off "Let Sponge load pages" in the popup
+stops all background captures. `sponge browser remove` unregisters Sponge from
+every browser.
+
 Images use `sponge-asset:SHA256` references. `asset ITEM SHA256 > image.png`
 retrieves verified bytes offline; `asset ITEM SHA256 --json` returns its metadata.
 Unresolved remote images become unavailable markers, and captures retain partial