sitedrift 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Severino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# sitedrift
+
+**Catch the drift between dev and live.** A zero-build, zero-dependency dev tool
+that frames your local site and production **side-by-side on the same route**,
+locked to the same scroll — then overlays them in `difference` mode so the only
+things that light up are the pixels that actually changed.
+
+```
+┌─────────────── sitedrift ───────────────┐
+│  DEV  ▸ /pricing      200   LIVE ▸ /pricing 200 │
+│ ┌───────────┐ │ ┌───────────┐  Overlay ▸ Diff   │
+│ │  $19      │ │ │  $29      │  ≠ meta           │
+│ │ [Start…]  │ │ │ [Get…]    │  ✓ author notes   │
+│ └───────────┘ │ └───────────┘                   │
+└──────────────────────────────────────────┘
+```
+
+---
+
+## Quick start
+
+No install — run it with `npx` (needs Node ≥ 18):
+
+```bash
+npx sitedrift /pricing \
+  --dev http://localhost:4321 \
+  --live https://example.com \
+  --open
+```
+
+That boots the viewer on `http://127.0.0.1:4178`, opens it at `/pricing`, and
+puts your dev build on the left and production on the right. Type any route in
+the toolbar and both panes follow.
+
+Install it globally if you reach for it often:
+
+```bash
+npm i -g sitedrift
+sitedrift /pricing -d http://localhost:4321 -l https://example.com -o
+```
+
+---
+
+## What it does
+
+- **One view switch** — Split (divider) · Solo (one pane, Swap flips) · Overlay
+  (stacked). In Overlay an opacity slider blends the panes and **Diff**
+  (`mix-blend-mode: difference`) lights up only the changed pixels. Overlay
+  force-locks scrolling so the panes can't drift. Keys: `O` overlay, `D` diff.
+- **Locked scrolling** with one controller (exact pixel or proportional) — no
+  duplicate scrollbars, no bounce. An internal link click mirrors to both panes.
+- **Metadata diff + status** — title / description / canonical compared across
+  sides (`≠ meta`), and a per-pane `200/3xx/4xx/5xx/ERR` badge refreshed on every
+  route load, so a route that 404s on one side jumps out.
+- **SEO panel** — Google-style snippet preview + a ~13-point checklist per pane
+  (title/description length, single H1, canonical, viewport, lang, Open Graph,
+  noindex, image alt…), with a flag showing how many checks fail.
+- **Review notes as a shared channel** — author/route/side-tagged notes in a JSON
+  file the viewer polls every 4s, so a teammate or an AI coding session can leave
+  notes that appear live. Click a note to jump to its route, copy a per-note
+  deep link, dock or float the drawer, and **Send to vault** or export Markdown.
+- **No dependencies.** Node standard library only.
+
+### Keyboard
+
+| Key | Action |
+|---|---|
+| `O` | Toggle Overlay |
+| `D` | Toggle the Overlay difference blend |
+| `S` | Swap sides |
+| `R` | Reload both panes |
+| `0` | Reset divider to 50/50 |
+| `/` | Focus the route field |
+| `Space` / `⇧Space` | Page down / up (when scrolling is linked) |
+| `↑` `↓` | Line scroll both panes |
+| `Esc` | Close the notes drawer / open popovers |
+
+Shortcuts work whether focus is in the viewer chrome or inside either pane.
+
+---
+
+## Options
+
+Every option is a CLI flag, and also reads a `SITEDRIFT_<NAME>` env var.
+Precedence is **flag > env > default**.
+
+| Flag | Env | Default | Purpose |
+|---|---|---|---|
+| `-d, --dev <url>` | `SITEDRIFT_DEV` | `http://127.0.0.1:4321` | Left-pane (dev) origin. |
+| `-l, --live <url>` | `SITEDRIFT_LIVE` | `https://example.com` | Right-pane (live) origin. |
+| `-p, --port <n>` | `SITEDRIFT_PORT` | `4178` | Listen port. |
+| `--host <addr>` | `SITEDRIFT_HOST` | `127.0.0.1` | Bind address. |
+| `-o, --open` | — | off | Open the viewer in your browser. |
+| `--http` | — | — | Force plain HTTP (ignore `--cert`/`--key`). |
+| `--cert <file>` / `--key <file>` | `SITEDRIFT_CERT` / `_KEY` | — | If both set, serve over HTTPS. |
+| `--notes <file>` | `SITEDRIFT_NOTES` | `$TMPDIR/sitedrift-notes.json` | Shared review-notes file. |
+| `--brand <text>` | `SITEDRIFT_BRAND` | — | Strip `\| <text>` from titles in pane headers. |
+| `--author <name>` | `SITEDRIFT_AUTHOR` | `you` | Byline for notes added in the viewer. |
+| `--vault <dir>` | `SITEDRIFT_VAULT` | — | Enable **Send to vault** (writes the review markdown here). |
+
+A positional `[path]` (e.g. `sitedrift /pricing`) sets the initial route.
+`-h, --help` and `-v, --version` do what you'd expect.
+
+### HTTP endpoints
+
+| Route | Purpose |
+|---|---|
+| `GET /` | The viewer. |
+| `GET /health` | `{ dev, live, version }`. |
+| `GET /notes` · `POST /notes` | Read / mutate notes (`op: add\|remove\|toggle\|clear`). |
+| `GET /notes.md` | Notes as a Markdown checklist. |
+| `POST /notes/save` | Write the notes markdown into `--vault`. |
+| `GET /icon.svg` | The app mark / favicon. |
+| `GET /__dev/*` · `GET /__live/*` | Proxied origins. |
+
+`POST /notes` requires `Content-Type: application/json`, so a cross-origin page
+can't forge a no-preflight write. Add a note from anywhere:
+
+```bash
+curl -X POST localhost:4178/notes -H 'content-type: application/json' \
+  -d '{"op":"add","text":"H1 on /about is larger on LIVE",
+       "author":"claude","route":"/about","side":"live"}'
+```
+
+Most viewer state (route, layout, scroll mode, focus) is mirrored into the URL
+query string, so a link reproduces the exact view.
+
+---
+
+## Security — local development only
+
+The proxy strips `Content-Security-Policy`, `X-Frame-Options`, and the
+Cross-Origin-{Embedder,Opener,Resource}-Policy headers so production can be
+framed next to dev. That is safe **only on loopback**:
+
+- It binds to `127.0.0.1` unless you override `--host`. **Do not** bind it to a
+  public interface or put it behind a public proxy.
+- Treat the notes file as plaintext shared scratch space.
+
+## Limitations
+
+- **URL rewriting is regex-based**, tuned for static sites (e.g. Astro builds).
+  It rewrites root-relative `href`/`src`/`srcset`/`url(...)` and Vite/`_astro`
+  paths, but won't catch URLs built in JS (`fetch`, dynamic `import`, import
+  maps). SPAs with client-side absolute fetches may need extra rules.
+- Designed for two origins of the *same* site, not arbitrary cross-site diffing.
+
+---
+
+## Docs
+
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — internals, invariants, and the
+  module map.
+
+## Credits
+
+Created by [Joe Severino](https://github.com/joeseverino).
+
+## License
+
+[MIT](LICENSE) © 2026 Joe Severino

package/assets/icon.svg

@@ -0,0 +1 @@
+<svg width="512" height="512" viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg"><rect width="512" height="512" rx="112.64" fill="#71d99e"/><g fill="#ffffff" transform="translate(256 256) scale(0.12348 -0.12348) translate(-1372.92 -745.00)"><path transform="translate(0.00 0)" d="M691.19921875 -24Q491.9996337890625 -24 352.39984130859375 36.300018310546875Q212.800048828125 96.60003662109375 139.80010986328125 212.39999389648438Q66.8001708984375 328.199951171875 66.8001708984375 492.7998046875H417.99761962890625Q420.3975830078125 423.5992431640625 454.49774169921875 373.8988342285156Q488.597900390625 324.19842529296875 549.9982604980469 297.6982116699219Q611.3986206054688 271.197998046875 695.1991577148438 271.197998046875Q769.7996826171875 271.197998046875 825.1000671386719 290.7981872558594Q880.4004516601562 310.39837646484375 911.4006652832031 345.7987365722656Q942.40087890625 381.1990966796875 942.40087890625 428.39959716796875Q942.40087890625 469.59991455078125 915.8008422851562 500.400146484375Q889.2008056640625 531.2003784179688 833.1006774902344 554.1005554199219Q777.0005493164062 577.000732421875 688.2002563476562 595.0008544921875L536.4000244140625 625.6010131835938Q317.9998779296875 669.6011962890625 206.60003662109375 777.2009887695312Q95.2001953125 884.80078125 95.2001953125 1048.0006103515625Q95.2001953125 1187.4004516601562 169.50003051757812 1292.1003112792969Q243.79986572265625 1396.8001708984375 376.599609375 1455.4000854492188Q509.39935302734375 1514 685.1990356445312 1514Q864.9986572265625 1514 995.0984191894531 1455.5000305175781Q1125.1981811523438 1397.0000610351562 1197.1980590820312 1287.400146484375Q1269.1979370117188 1177.8002319335938 1273.9979248046875 1024.400390625H932.8004150390625Q925.6004028320312 1114.8011474609375 860.3999938964844 1166.7015686035156Q795.1995849609375 1218.6019897460938 690.3988647460938 1218.6019897460938Q624.7984008789062 1218.6019897460938 573.8980407714844 1199.0018005371094Q522.9976806640625 1179.401611328125 494.09747314453125 1145.2012634277344Q465.197265625 1111.0009155273438 465.197265625 1065.8004760742188Q465.197265625 1025.4002075195312 489.59735107421875 996.7999877929688Q513.9974365234375 968.1997680664062 566.6976318359375 946.7995910644531Q619.3978271484375 925.3994140625 702.5982055664062 908.7992553710938L832.3988037109375 882.7990112304688Q956.5985717773438 858.198974609375 1046.5984191894531 820.9989624023438Q1136.5982666015625 783.7989501953125 1194.2981872558594 731.3989868164062Q1251.9981079101562 678.9990234375 1279.5980834960938 610.2991027832031Q1307.1980590820312 541.5991821289062 1307.1980590820312 454.79931640625Q1307.1980590820312 304.19964599609375 1234.09814453125 196.99978637695312Q1160.9982299804688 89.7999267578125 1023.0984802246094 32.89996337890625Q885.19873046875 -24 691.19921875 -24Z"/><path transform="translate(1281.84 0)" d="M651.1993408203125 0H253.199951171875V307.19775390625H632.7994384765625Q767.4002075195312 307.19775390625 854.000732421875 356.1980895996094Q940.6012573242188 405.19842529296875 982.9015197753906 502.7989501953125Q1025.2017822265625 600.3994750976562 1025.2017822265625 744.800048828125Q1025.2017822265625 890.4005737304688 982.3015441894531 987.7010803222656Q939.4013061523438 1085.0015869140625 851.2008666992188 1133.9019165039062Q763.0004272460938 1182.80224609375 627.1998291015625 1182.80224609375H246.7999267578125V1490H650.399658203125Q877.7994995117188 1490 1045.6993103027344 1398.6000366210938Q1213.59912109375 1307.2000732421875 1305.3989868164062 1139.9000854492188Q1397.1988525390625 972.60009765625 1397.1988525390625 744.800048828125Q1397.1988525390625 517.3999633789062 1305.9989624023438 350.2999572753906Q1214.799072265625 183.199951171875 1047.6991882324219 91.5999755859375Q880.5993041992188 0 651.1993408203125 0ZM462.39794921875 1490V0H93.600830078125V1490Z"/></g></svg>

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "sitedrift",
+  "version": "0.1.0",
+  "description": "Catch the drift between dev and live — frame your local site and production side-by-side on the same route, locked scroll, with a difference-blend overlay. Zero dependencies.",
+  "type": "module",
+  "bin": {
+    "sitedrift": "sitedrift.mjs"
+  },
+  "files": [
+    "sitedrift.mjs",
+    "assets/icon.svg",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node sitedrift.mjs",
+    "test": "node --check sitedrift.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "dev-tool",
+    "visual-diff",
+    "visual-regression",
+    "staging",
+    "production",
+    "side-by-side",
+    "proxy",
+    "seo",
+    "astro",
+    "overlay"
+  ],
+  "author": "Joe Severino (https://github.com/joeseverino)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joeseverino/sitedrift.git"
+  },
+  "homepage": "https://github.com/joeseverino/sitedrift#readme",
+  "bugs": {
+    "url": "https://github.com/joeseverino/sitedrift/issues"
+  }
+}