@satanwagen/reviewkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominik Majo
+
+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,284 @@
+# reviewkit
+
+Drop-in visual review & feedback layer for React sites. A reviewer opens the live page, clicks elements and proposes changes — rewrite copy, swap an image, leave a comment, mark for deletion, request a move or a style tweak. **Nothing is ever applied to the site.** Every proposal is recorded as a portable session (JSON) that you hand to a coding agent or developer, who applies the changes in source.
+
+## Install
+
+```sh
+npm install @satanwagen/reviewkit
+```
+
+`react` and `react-dom` (18 or 19) are peer dependencies.
+
+## Two-line integration
+
+```tsx
+import { ReviewKit } from '@satanwagen/reviewkit/client';
+
+// anywhere in your tree, rendered once:
+<ReviewKit />
+```
+
+That's it. The component renders `null` unless review mode is active, and all UI lives in a shadow root appended to `document.body` — your CSS never leaks in, reviewkit's CSS never leaks out. Safe to ship in production builds.
+
+### Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `token` | `string` | Restricts URL activation to `?review=<token>`. Without it, any `?review=x` activates (with a console warning). |
+| `syncToken` | `string` | Enables live collaboration via the realtime sync server (`realtime/`): presence avatars, live cursors, remote selections and instantly shared items. Unset = solo mode, no network. The value is public in the browser bundle by nature — treat it as a gate against casual visitors, not a secret. Keep it in the lazy review chunk of the host app, never in the main bundle. |
+| `defaultAuthor` | `string` | Pre-fills the reviewer name. |
+| `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | Initial corner of the floating badge (default `bottom-right`; draggable, persisted). |
+| `storageKey` | `string` | Persistence key (default: page origin). |
+| `onSessionChange` | `(session: ReviewSession) => void` | Called (debounced) whenever the session changes. |
+
+## How the layer activates
+
+**With a `token` configured (the production setup) the rules are strict:**
+
+1. `?review=<token>` in the URL — the only automatic way in.
+2. The reviewer's explicit **“Keep on in this tab”** toggle in the panel — a per-tab, token-bound opt-in that expires after ~4 hours. Nothing persists silently.
+
+Anything else shows nothing: no badge, no listeners, no WebSocket. **“End review”** in the panel (or `?review=off`) clears all persisted state and returns the clean site. Leftover activation keys from pre-strict versions (`review-kit:active`, `reviewkit`) are silently removed on the first token-less load.
+
+**Without a token** (zero-config/dev) the conveniences remain: any `?review=x` value (console warning), the in-tab opt-in, a `reviewkit` localStorage flag, or a dev build (`NODE_ENV === 'development'`).
+
+## Using it (reviewer flow)
+
+A **Review** badge floats in a corner (drag it to another corner; click it to open the panel).
+
+1. Click **Pick an element**, then click anything on the page.
+2. A toolbar appears on the selection: **Rewrite** (edit the text in place — the DOM is restored afterwards, only the diff is recorded), **Image** (propose a replacement image), **Comment**, **Style**, **Move**, **Delete**.
+3. Each item takes an optional note and a **Must / Nice to have** priority.
+4. The panel lists all items grouped by route, with search, type filters, inline editing, status (`open / accepted / rejected / applied`), and jump-to-element. Items whose element no longer exists are flagged **unanchored**.
+
+Sessions autosave locally (IndexedDB, falling back to `localStorage`), keyed per origin — a reviewer can close the tab and continue later.
+
+### Keyboard shortcuts
+
+| Keys | Action |
+| --- | --- |
+| `?` | Shortcut cheatsheet |
+| `Esc` | Close / deselect / exit pick mode (cascading) |
+| `⌘Z` / `Ctrl+Z` | Undo last capture |
+| `↑` `↓` | Move between items in the panel |
+| `↵` | Commit an inline rewrite (`⇧↵` = newline) |
+| `⌘↵` / `Ctrl+↵` | Save a comment/note composer |
+
+## Session format & export
+
+The panel footer has **Export** (downloads `review-<host>-<date>.json`), **Copy** (session JSON to clipboard), and **Import** (load a session file back — reviews can round-trip between people).
+
+**Deletion is permanent and room-wide.** Deleting an item (or using Clear) removes it for everyone in the live room, and the sync server keeps a tombstone for the id, so no stale client — offline, another tab, an old laptop — can upload it back. Tombstones survive server restarts and are pruned after 30 days (capped at 5000 per room). Importing a session file does **not** resurrect items that were deleted in the live room: the tombstone wins and the imported copy disappears again on sync. To genuinely bring a deleted item back, re-create it (it gets a new id).
+
+The JSON follows [`schema/review-session.schema.json`](./schema/review-session.schema.json) (`schemaVersion: 1`). Shape:
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "id": "…",
+  "createdAt": "…", "updatedAt": "…",
+  "site": { "origin": "…", "route": "/", "viewport": { "width": 0, "height": 0 }, "userAgent": "…" },
+  "author": "Marta from marketing",
+  "items": [
+    {
+      "id": "…", "createdAt": "…",
+      "type": "copy",              // copy | image | comment | delete | move | style
+      "status": "open",            // open | accepted | rejected | applied
+      "priority": "must",          // must | nice
+      "route": "/pricing",
+      "target": {                   // everything needed to find the element again
+        "selector": "#hero > p:nth-of-type(1)",
+        "tagName": "p", "textSnippet": "…",
+        "attrs": { "id": "…", "classList": ["…"], "data": {} },
+        "nthOfType": [1, 2, 1],
+        "boundingBox": { "x": 0, "y": 0, "width": 0, "height": 0 }
+      },
+      "payload": { "before": "old text", "after": "new text" },
+      "note": "optional free text"
+    }
+  ]
+}
+```
+
+Payload per type: `copy` `{before, after}` · `image` `{beforeSrc, afterSrc?, afterDataUrl?, description?}` · `comment` `{text}` · `delete` `{reason?}` · `move` `{direction?, targetDescription?}` · `style` `{description}`. Unknown fields and unknown item types are preserved on import (forward compatibility).
+
+For `image` items the replacement arrives in exactly one of two forms: **embedded** (`afterDataUrl`, a `data:` URL, capped at 2 MB at capture) or **linked** (`afterSrc`, an external URL — used when the reviewer pasted/dragged a link that couldn't be fetched because of CORS, or the file was too large to embed). An agent applying the session downloads `afterSrc` itself or writes the data URL to a file.
+
+Versioning rule: `schemaVersion` (currently `1`) is bumped only for breaking changes — removing/renaming fields or changing their meaning. Additive optional fields (like documenting `afterSrc` above) do not bump it; every valid v1 session stays valid and importable.
+
+### Handing the output to a coding agent
+
+Export (or Copy) the session and give the file to the agent with a prompt like:
+
+> Apply the feedback in `review-agropolio-2026-07-28.json` to this codebase. For each item, locate the source element using `target.selector`, `target.textSnippet` and `target.attrs`, apply the change described by `type`/`payload`/`note` (items with `"priority": "must"` first), and set its `status` to `"applied"`.
+
+Programmatic helpers are exported too: `parseSessionJson` / `parseSession` (validation), `isCopyItem` … type guards, and `sessionToJson` / `downloadSession` / `importSessionFile` from `reviewkit` (server-safe schema utilities also via `reviewkit/schema`).
+
+## Integrating into an existing Vite + React site
+
+```tsx
+// src/main.tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { ReviewKit } from '@satanwagen/reviewkit/client';
+import { App } from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+    <ReviewKit token={import.meta.env.VITE_REVIEW_TOKEN} />
+  </StrictMode>,
+);
+```
+
+No Vite config changes are needed — `reviewkit` ships prebuilt ESM/CJS with types. In dev the layer is always on; in production reviewers open `https://your-site.tld/?review=<token>`.
+
+Until the npm release lands you can also depend on it via a file path — this is exactly what the demo does:
+
+```jsonc
+// package.json
+"dependencies": { "@satanwagen/reviewkit": "file:../path/to/ReviewKit" }
+```
+
+npm symlinks the folder, so after editing reviewkit run `npm run build` in it and restart/reload Vite. Note that the deployed site only picks up library changes after a rebuild + deploy of the host app (Fable has `npm run deploy` for the whole chain) — the live sync server only carries review data, never code. Run `npm run build` in `ReviewKit/` at least once before installing, since the package resolves to `dist/`.
+
+### Real-world example: token-only activation + lazy loading (Agropolio landing page)
+
+The Agropolio landing page (`../Agropolio/Fable` relative to this repo) integrates reviewkit so that **only** `?review=agropolio` ever activates it — dev-build auto-activation is bypassed, and without the token the library code isn't even downloaded (separate lazy chunk):
+
+```jsonc
+// Fable/package.json
+"dependencies": { "@satanwagen/reviewkit": "file:../../ReviewKit" }
+```
+
+```ts
+// Fable/vite.config.ts — the linked package has its own node_modules,
+// dedupe guarantees a single React instance (Fable is on React 18):
+resolve: { dedupe: ['react', 'react-dom'] }
+```
+
+```tsx
+// Fable/src/ReviewLayer.tsx (rendered next to <App /> in main.tsx)
+import { lazy, Suspense, useEffect, useState } from 'react'
+
+const TOKEN = 'agropolio'
+const SESSION_KEY = 'review-kit:active' // same key reviewkit uses internally
+
+function shouldLoad(): boolean {
+  try {
+    const param = new URLSearchParams(window.location.search).get('review')
+    if (param === 'off') { window.sessionStorage.removeItem(SESSION_KEY); return false }
+    if (param === TOKEN) return true
+    return window.sessionStorage.getItem(SESSION_KEY) === '1' // survive reloads in-tab
+  } catch { return false }
+}
+
+const ReviewKit = lazy(() => import('@satanwagen/reviewkit/client').then((m) => ({ default: m.ReviewKit })))
+
+export function ReviewLayer() {
+  const [load, setLoad] = useState(false)
+  useEffect(() => { if (shouldLoad()) setLoad(true) }, [])
+  if (!load) return null
+  return <Suspense fallback={null}><ReviewKit token={TOKEN} /></Suspense>
+}
+```
+
+The gate outside `<ReviewKit />` is what keeps the layer invisible to normal visitors: no token → the wrapper renders `null`, no shadow root, no listeners, no network request for the reviewkit chunk.
+
+## Adding ReviewKit to another site (with live collaboration)
+
+Step by step, for any site on any hosting (nginx, IIS, Vercel, …).
+
+**1. Install the package** — pick one:
+
+```jsonc
+// a) local folder (this repo checked out next to your project):
+"dependencies": { "@satanwagen/reviewkit": "file:../ReviewKit" }
+// b) straight from git:
+"dependencies": { "@satanwagen/reviewkit": "git+ssh://git@your-git-host/review-kit.git" }
+// c) once published to npm:
+"dependencies": { "@satanwagen/reviewkit": "^0.1.0" }
+```
+
+Run `npm run build` inside ReviewKit at least once for the `file:`/git variants (the package resolves to `dist/`). With React 18 add `resolve.dedupe: ['react','react-dom']` to your bundler config when using a `file:` link.
+
+**2. Integrate — two lines, done. Live collaboration included:**
+
+```tsx
+import { ReviewKit } from '@satanwagen/reviewkit/client';
+
+<ReviewKit token="my-site-token" syncToken="<the sync server's shared secret>" />
+```
+
+That's the whole setup. `syncUrl` **defaults to the always-on ReviewKit sync server** (`wss://agropolio.fucking.style/rk-sync`), so presence, live cursors and instantly-shared items work on any site with no server-side step at all — no allowlist entry, no restart, nothing. Rooms are keyed by the page's origin + path, so different sites never see each other's feedback or presence. If the server is unreachable the tool silently runs local-only (no console errors); omit `syncToken` to disable networking entirely.
+
+**What the open server implies (honesty section):** the token and `syncToken` are readable in the browser bundle, so anyone holding a review URL can join and create rooms. The server is meant for the operator's own sites, not as a public service; it is guarded by the shared token, per-connection rate limits (40 msg/s, burst 80), 1 MiB frame cap, 16 clients and 2000 items per room, and a live-room ceiling (`RK_SYNC_MAX_ROOMS`, default 500).
+
+**3. Advanced: run your own sync server** (optional) — `realtime/server/`: `npm run build`, run `dist/server.js` with `RK_SYNC_TOKEN` (+ optional `RK_SYNC_PORT`, `RK_SYNC_DATA`, `RK_SYNC_MAX_ROOMS`, and `RK_SYNC_ORIGINS` if you *want* an origin allowlist — empty/unset means any origin, which is the default deployment) as a service, point `syncUrl` at it, then put a WebSocket-aware reverse proxy in front:
+
+  *nginx* (as deployed on satan):
+
+  ```nginx
+  location /rk-sync {
+      proxy_pass http://127.0.0.1:8787;
+      proxy_http_version 1.1;
+      proxy_set_header Upgrade $http_upgrade;
+      proxy_set_header Connection "upgrade";
+      proxy_read_timeout 120s;
+  }
+  ```
+
+  *IIS*: enable the **WebSocket Protocol** feature (Server Manager → Web Server → Application Development), install **Application Request Routing** + **URL Rewrite**, enable ARR proxying, and add a rewrite rule that forwards `^rk-sync` to `http://127.0.0.1:8787/rk-sync` — ARR carries the WebSocket upgrade automatically once the feature is on.
+
+  With an `RK_SYNC_ORIGINS` allowlist active, rejected origins are logged (`[origin] rejected …`) and closed with code 4005; the client quietly stays local.
+
+**4. Token caveat:** don't reuse secrets that protect anything else, and keep tokens out of the main bundle (load ReviewKit in a lazy chunk like the Agropolio integration does).
+
+**5. Verify it works:** open `https://your-site/?review=<token>` — the Review badge appears; the panel header shows **live** (green dot) when the sync server accepted you, or *local only* when not. In the Network tab you should see one WebSocket to `/rk-sync` with a `welcome` frame. Open the same URL in a second browser: avatars, live cursors and instantly-appearing items confirm collaboration.
+
+## Pairing with Emblema
+
+ReviewKit pairs with the [Emblema](https://emblema.app) desktop app: once paired, the local sync agent streams review items to Emblema, and the paired Emblema shows them as findings in its ReviewKit tile (statuses flow back to the page).
+
+Sync is automatic and realtime — no manual step. With `emblema` set in the `ReviewKit` config, the browser itself pushes every added or edited open item to a locally running Emblema (debounced 500 ms, silent-fail: an unreachable Emblema never blocks the reviewer; the panel header shows a small `emblema` status dot). The session menu keeps **Resend all to Emblema** as a one-click fallback that re-dispatches every open item on the page.
+
+**Where the key lives:** the pairing key and state are stored by the local sync agent in `<project>/.reviewkit/emblema-sync.json`. The key (`emk_…`) is a secret — the panel only ever displays it shortened (`emk_…last4`) and puts the full value on the clipboard.
+
+**Set up and generate a key** (in the project repo):
+
+```sh
+npx reviewkit-emblema init --origin https://your-site   # creates the state file, prints the key
+npx reviewkit-emblema serve                             # runs the local API + realtime bridge
+```
+
+Paste the printed key into Emblema. From the page UI the same lives in the panel's gear menu → **Connect to Emblema…** — the menu entry shows the live pairing status at a glance (green dot = paired, amber = the local agent isn't answering, red = key revoked, grey = not paired), and the dialog has **New key (rotate)**, **Copy key** and **Delete key (revoke)**.
+
+**Rotate / revoke from the CLI:**
+
+```sh
+npx reviewkit-emblema key      # print the current key
+npx reviewkit-emblema rotate   # issue a new secret — the old key stops working immediately
+npx reviewkit-emblema revoke   # disable the pairing entirely (rotate re-enables)
+```
+
+Rotate and revoke take effect immediately, including against an already-running `serve` process — authenticated requests always check the current on-disk key, so a rotated or revoked key can never keep authenticating.
+
+## Demo
+
+```sh
+cd examples/vite-demo
+npm install
+npm run dev   # http://localhost:3010 — dev build, so the layer is active immediately
+```
+
+Also try `http://localhost:3010/?review=demo` to exercise URL activation.
+
+## Development
+
+```sh
+npm install
+npm run typecheck
+npm run lint
+npm run build   # tsup → dist/ (ESM + CJS + d.ts)
+```