@satanwagen/reviewkit 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+## 0.1.3 — 2026-09-02
+
+Defaults tightened so a production build behaves the way its code reads.
+Several changes are breaking for hosts that relied on the old conveniences;
+each has a one-line migration below.
+
+### Breaking
+
+- **No activation without a token.** Previously an unset `token` meant "any
+  `?review=x` turns the layer on" (plus the `reviewkit` localStorage flag).
+  Now, without `token`, nothing activates. Migration: pass `token`. For a
+  reviewer-less dev loop pass `devAutoOn`.
+- **No `NODE_ENV === 'development'` auto-on.** The library never reads the
+  host's NODE_ENV any more. Migration:
+  `devAutoOn={import.meta.env.DEV}` (Vite) or
+  `devAutoOn={process.env.NODE_ENV === 'development'}` (Next/webpack).
+- **No default `syncUrl`.** The former default
+  `wss://agropolio.fucking.style/rk-sync` pointed at an expired domain. Sync
+  now runs only when **both** `syncUrl` and `syncToken` are set; otherwise
+  the layer is local-only, no socket. Migration: set `syncUrl` explicitly.
+  Same for the CLI: `reviewkit-emblema init --sync-url …` (the room bridge
+  stays disabled until both `--sync-url` and `--sync-token` are configured).
+- **CLI moved to `@satanwagen/reviewkit-cli`.** The main package no longer
+  ships a `bin`, so a host `npm install` does not pull the Emblema agent.
+  Migration: `npx @satanwagen/reviewkit-cli init …` / `serve` (the command
+  inside is still `reviewkit-emblema`).
+- **`emblema.repoPath` is optional.** The repo path is Emblema's local
+  knowledge (advertised in its `/intake/ping` answer, and present in
+  `.reviewkit/emblema-sync.json` for the agent) and no longer belongs in host
+  code. `emblema={{}}` now enables the bridge. The v1 dispatch payload keeps
+  `v: 1`, but `repoPath` became optional: an intake with a strict "required"
+  validator must relax it and fall back to its active project.
+- **Effect sounds moved off the expired domain.** `/ondro` now fetches
+  `rick.mp3` from `https://2-59-219-26.sslip.io/rk-assets` (the same VPS,
+  reached through a sslip.io hostname so no domain renewal can break it).
+  New prop `fxAssetsUrl` overrides the base for self-hosting. Add the origin
+  to CSP `media-src` if you send a policy.
+- Legacy activation keys (`review-kit:active`, `reviewkit`) are still cleaned
+  up on load but never consulted.
+- **Emblema intake must accept a batch without `repoPath`.** An Emblema build
+  that still validates it as required answers HTTP 400; the panel now shows
+  that as `emblema rejected` (new push status) instead of `emblema offline`.
+- **CLI:** a `.reviewkit/emblema-sync.json` written by 0.1.2 still carries the
+  retired default sync host. `serve` now detects it, logs a re-init hint and
+  runs with the bridge disabled instead of reconnecting forever; the local
+  `/status` endpoint reports `realtime.state: 'off'` whenever either sync
+  setting is missing (previously it said `connecting` with no URL).
+
+### Added
+
+- `enabled?: boolean` master switch (default `true`) so a wrapper can write
+  `<ReviewKit enabled={Boolean(TOKEN)} token={TOKEN} />` instead of
+  `if (!TOKEN) return null`.
+- `devAutoOn?: boolean` — host-controlled "always on for this load". Still
+  subject to `enabled`, `allowedHosts` and `?review=off`.
+- **`@satanwagen/reviewkit/next`** — `'use client'` component: render it from
+  a server `layout.tsx`; it evaluates URL + sticky session after mount and
+  only then dynamically imports the core. `examples/next-demo` shows it
+  together with the CSP headers.
+- **`@satanwagen/reviewkit/lazy`** — the same code-split component for Vite
+  and friends; no more hand-rolled `React.lazy` + `Suspense` gate.
+- **`@satanwagen/reviewkit/activate`** — `shouldActivate({ token, enabled,
+  allowedHosts, devAutoOn })`, React-free, ~200 B. The supported way for a
+  host to gate its own lazy import; the sessionStorage format stays private.
+- One-time console warning when a URL token activates the layer on a
+  non-loopback hostname with no `allowedHosts` (see README "Production
+  recipe").
+- The `/` command effects (~40 KB of source) load as a separate chunk on
+  first use instead of shipping in the core chunk.
+- `probeEmblema()` returns `{ port, repoPath? }`; `pingEmblema()` stays as a
+  port-only wrapper.
+- Activation matrix tests (`test/activate.test.mjs`) run against `dist/`
+  (`npm test` builds first via `pretest`).
+- A one-time console warning when `?review=<x>` does not match the configured
+  token (kept from 0.1.2, now also emitted by `shouldActivate`).
+- `/lazy` and `/next` are effectively ESM entries: the CJS builds exist for
+  `require()` consumers but inline the core (esbuild has no CJS code
+  splitting). Every modern bundler picks the ESM build.
+- README: activation-state table, CSP requirements, production recipe.
+
+### Bundle audit (unminified ESM, `dist/`)
+
+| Chunk | 0.1.2 | 0.1.3 |
+| --- | ---: | ---: |
+| core client chunk | 313 KB | 267 KB |
+| effects (lazy, on first `/command`) | in core | 41 KB |
+| `activate` entry | — | 0.2 KB |
+
+Largest remaining inputs: `styles.ts` (53 KB), `Panel.tsx` (46 KB). Schema
+validation and IndexedDB persistence are under 10 KB each and were not the
+weight.
+
+## 0.1.2
+
+- Delete endpoint for Emblema findings, idempotent for unknown ids.
+
+## 0.1.1
+
+- `reopen` status verb; realtime health in local state.
+
+## 0.1.0
+
+- First scoped release as `@satanwagen/reviewkit`.

package/README.md

@@ -13,35 +13,105 @@ npm install @satanwagen/reviewkit
 ## Two-line integration
 
 ```tsx
-import { ReviewKit } from '@satanwagen/reviewkit/client';
+import { ReviewKit } from '@satanwagen/reviewkit/lazy';   // Vite, CRA, Remix …
+// import { ReviewKit } from '@satanwagen/reviewkit/next'; // Next.js App Router ('use client' built in)
 
 // anywhere in your tree, rendered once:
-<ReviewKit />
+<ReviewKit token={import.meta.env.VITE_REVIEW_TOKEN} />
 ```
 
 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.
 
+Three entries, same props:
+
+| Entry | What it is | Use when |
+| --- | --- | --- |
+| `@satanwagen/reviewkit/lazy` | Component that decides after mount (URL + sticky session) and only then `import()`s the core chunk. | Vite / CRA / Remix / any client bundler. Visitors without a review link never download the core. |
+| `@satanwagen/reviewkit/next` | Same, with `'use client'` baked into the built file so a server `layout.tsx` can render it directly. | Next.js App Router. See `examples/next-demo`. |
+| `@satanwagen/reviewkit/client` | The core itself, eager. | You already have your own lazy boundary, or you want everything in one chunk. |
+
+The code split only exists in the ESM builds (what Vite, Next, webpack 5 pick); the CJS files of `/lazy` and `/next` inline the core for `require()` consumers.
+
+And a React-free helper for hosts that gate their own lazy import:
+
+```ts
+import { shouldActivate } from '@satanwagen/reviewkit/activate'; // ~200 B, no React, SSR-safe (false)
+if (shouldActivate({ token: TOKEN })) void import('./reviewHost');
+```
+
+`shouldActivate` is the supported API for "should this page load show review?"; the sessionStorage format behind the sticky session is private and may change. Its only side effect: `?review=off` clears the sticky opt-in.
+
 ### 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. |
+| `token` | `string` | **Required for any activation.** The layer turns on only via `?review=<token>` (or the per-tab session such a link starts). Without it nothing activates, whatever the URL says. |
+| `enabled` | `boolean` | Master switch, default `true`. `false` renders nothing, installs nothing. Lets you write `enabled={Boolean(TOKEN)}` instead of `if (!TOKEN) return null`. |
+| `devAutoOn` | `boolean` | Force the layer on for this page load, no link needed. Host-controlled dev convenience (`devAutoOn={import.meta.env.DEV}`); the library never reads `NODE_ENV`. Still subject to `enabled`, `allowedHosts` and `?review=off`. |
+| `allowedHosts` | `string[]` | Hostname allowlist with `*` wildcards (`['localhost', '*.staging.example']`). Outside it nothing activates, token or not. Unset = any host (with a one-time console warning on URL activation on a public host). |
+| `syncUrl` | `string` | WebSocket endpoint of your sync server (`realtime/server`), e.g. `wss://your-site.tld/rk-sync`. **No default.** |
+| `syncToken` | `string` | Shared secret of the sync server. Live collaboration (presence, cursors, shared items) runs only when **both** `syncUrl` and `syncToken` are set; otherwise solo mode, no network. Public in the bundle by nature — a gate against casual visitors, not a secret. |
+| `emblema` | `{ repoPath?: string; port?: number }` | Enables the Emblema bridge (`emblema={{}}` is enough). See "Pairing with Emblema". |
 | `defaultAuthor` | `string` | Pre-fills the reviewer name. |
+| `fxAssetsUrl` | `string` | Base URL for the `/` effect soundtracks (`<base>/rick.mp3` for `/ondro`). Default: the public ReviewKit assets host `https://2-59-219-26.sslip.io/rk-assets`. Override to self-host. Needs `media-src` in CSP. |
 | `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:**
+Rules, in order; the first that applies wins. No environment sniffing anywhere.
+
+| # | Condition | Result |
+| --- | --- | --- |
+| 1 | `enabled={false}` | off |
+| 2 | hostname not in `allowedHosts` (when given) | off |
+| 3 | `?review=off` in the URL | off, and the in-tab sticky session is cleared |
+| 4 | `devAutoOn` | **on** |
+| 5 | no `token` configured | off (`?review=x` logs a one-time warning and stays off) |
+| 6 | `?review=<token>` matches | **on**, starts the per-tab sticky session |
+| 7 | `?review=<something else>` | off |
+| 8 | valid sticky session (same token, < 4 h since last active load) | **on**, expiry renewed |
+| 9 | otherwise | off |
+
+Activation-state matrix for the common cases:
+
+| token | build | URL | sticky | result |
+| --- | --- | --- | --- | --- |
+| unset | dev or prod | none / `?review=x` | any | off |
+| unset | dev, with `devAutoOn` | any except `off` | any | on |
+| set | prod | `?review=<token>` | — | on (sticky starts) |
+| set | prod | none | valid | on |
+| set | prod | none | none / expired / other token | off |
+| set | prod | `?review=wrong` | valid | off |
+| set | any | `?review=off` | valid | off, sticky cleared |
+
+The sticky session is per tab (`sessionStorage`), bound to the token and renewed on every active load, so a reviewer who opened a review link keeps reviewing across full page loads on other routes. The gear menu's **Keep review on in this tab** toggles it explicitly; **End review** (or `?review=off`) clears everything and returns the clean site. Leftover keys from pre-0.1.3 versions (`review-kit:active`, `reviewkit`) are removed on load and never consulted.
+
+### Production recipe
+
+```tsx
+<ReviewKit
+  enabled={Boolean(TOKEN)}
+  token={TOKEN}
+  allowedHosts={['staging.your-site.tld', '*.preview.your-site.tld']}
+  syncUrl="wss://your-site.tld/rk-sync"
+  syncToken={SYNC_TOKEN}
+/>
+```
+
+`token` + `allowedHosts` together: the token says *who*, the allowlist says *where*. Without `allowedHosts` a URL activation on a non-loopback host logs one console warning. `TOKEN`/`SYNC_TOKEN` are public in the bundle by design; use the `/lazy` or `/next` entry so they at least live in the review chunk, not the main one.
 
-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.
+### CSP
 
-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.
+If the host sends a `Content-Security-Policy`, `connect-src` must allow:
 
-**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'`).
+- the sync server origin, as `wss://your-site.tld` (or the `ws:` origin in dev),
+- `http://127.0.0.1:*` when the `emblema` prop is set (intake ports 48752–48755, pairing agent 48770–48773).
+
+and `media-src` must allow `https://2-59-219-26.sslip.io` (or your `fxAssetsUrl`) for the `/` effect sounds; without it the effects run silent.
+
+With `connect-src 'self'` alone the WebSocket is blocked and the layer silently stays local-only. `examples/next-demo/next.config.ts` has a complete header.
 
 ## Using it (reviewer flow)
 
@@ -121,70 +191,64 @@ Programmatic helpers are exported too: `parseSessionJson` / `parseSession` (vali
 // src/main.tsx
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import { ReviewKit } from '@satanwagen/reviewkit/client';
+import { ReviewKit } from '@satanwagen/reviewkit/lazy';
 import { App } from './App';
 
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
     <App />
-    <ReviewKit token={import.meta.env.VITE_REVIEW_TOKEN} />
+    <ReviewKit token={import.meta.env.VITE_REVIEW_TOKEN} devAutoOn={import.meta.env.DEV} />
   </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>`.
+No Vite config changes are needed — `reviewkit` ships prebuilt ESM/CJS with types. In `vite dev` the layer is on thanks to `devAutoOn`; in production reviewers open `https://your-site.tld/?review=<token>`, and visitors without the link never download the review chunk (the `/lazy` entry splits it automatically).
 
-Until the npm release lands you can also depend on it via a file path — this is exactly what the demo does:
+Until the npm release lands you can also depend on it via a file path — this is exactly what the demos do:
 
 ```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/`.
+npm symlinks the folder, so after editing reviewkit run `npm run build` in it and restart/reload Vite. With React 18 add `resolve: { dedupe: ['react', 'react-dom'] }` to `vite.config.ts` so the linked package's own `node_modules` cannot introduce a second React. 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)
+### Gating a hand-rolled lazy boundary
 
-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):
+If you keep your own wrapper (for example to keep `syncToken` in a chunk you control), gate it with `shouldActivate` instead of reading ReviewKit's storage keys:
 
-```jsonc
-// Fable/package.json
-"dependencies": { "@satanwagen/reviewkit": "file:../../ReviewKit" }
-```
+```tsx
+// ReviewLayer.tsx
+import { lazy, Suspense, useEffect, useState } from 'react';
+import { shouldActivate } from '@satanwagen/reviewkit/activate';
 
-```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'] }
-```
+const TOKEN = import.meta.env.VITE_REVIEW_TOKEN;
+const ReviewHost = lazy(() => import('./reviewHost')); // renders <ReviewKit token={TOKEN} syncUrl=… syncToken=… />
 
-```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 }
+export function ReviewLayer() {
+  const [load, setLoad] = useState(false);
+  useEffect(() => { if (shouldActivate({ token: TOKEN })) setLoad(true); }, []);
+  return load ? <Suspense fallback={null}><ReviewHost /></Suspense> : null;
 }
+```
 
-const ReviewKit = lazy(() => import('@satanwagen/reviewkit/client').then((m) => ({ default: m.ReviewKit })))
+## Integrating into a Next.js site (App Router)
 
-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>
+```tsx
+// app/layout.tsx (a server component — that's fine)
+import { ReviewKit } from '@satanwagen/reviewkit/next';
+
+export default function RootLayout({ children }) {
+  return (
+    <html><body>
+      {children}
+      <ReviewKit token={process.env.NEXT_PUBLIC_REVIEW_TOKEN} devAutoOn={process.env.NODE_ENV === 'development'} />
+    </body></html>
+  );
 }
 ```
 
-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.
+The `/next` entry is a client component; it renders nothing on the server and evaluates the URL/sticky session after mount before importing the core. Add the CSP `connect-src` entries above if you send a policy. Full example: `examples/next-demo`.
 
 ## Adding ReviewKit to another site (with live collaboration)
 
@@ -203,19 +267,19 @@ Step by step, for any site on any hosting (nginx, IIS, Vercel, …).
 
 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:**
+**2. Integrate — two lines, done:**
 
 ```tsx
-import { ReviewKit } from '@satanwagen/reviewkit/client';
+import { ReviewKit } from '@satanwagen/reviewkit/lazy';
 
-<ReviewKit token="my-site-token" syncToken="<the sync server's shared secret>" />
+<ReviewKit token="my-site-token" syncUrl="wss://your-site.tld/rk-sync" 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.
+Live collaboration (presence, live cursors, instantly shared items) runs only when **both** `syncUrl` and `syncToken` are set — there is no default server. 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 either prop 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).
+**What a shared 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. Run the server for your own sites only; 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:
+**3. Run the sync server** — `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):
 
@@ -233,7 +297,7 @@ That's the whole setup. `syncUrl` **defaults to the always-on ReviewKit sync ser
 
   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).
+**4. Token caveat:** don't reuse secrets that protect anything else, and keep tokens out of the main bundle (use the `/lazy` or `/next` entry). Add `allowedHosts` in production (see "Production recipe").
 
 **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.
 
@@ -241,15 +305,17 @@ That's the whole setup. `syncUrl` **defaults to the always-on ReviewKit sync ser
 
 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.
+Sync is automatic and realtime — no manual step. With `emblema={{}}` 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.
+
+**Which repo gets edited** is Emblema's knowledge, not the website's: the intake advertises its `repoPath` in the `/intake/ping` answer, and the local agent has it in `.reviewkit/emblema-sync.json` (`init --repo`, default: the directory you ran it in). `emblema.repoPath` remains as an optional override only; an absolute path from a reviewer's laptop has no place in host code.
 
 **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):
+**Set up and generate a key** (in the project repo; the CLI is its own package so host installs stay CLI-free):
 
 ```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
+npx @satanwagen/reviewkit-cli init --origin https://your-site --sync-url wss://your-site/rk-sync --sync-token <secret>
+npx @satanwagen/reviewkit-cli serve      # local API + realtime bridge (bridge needs both sync flags)
 ```
 
 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)**.
@@ -257,22 +323,24 @@ Paste the printed key into Emblema. From the page UI the same lives in the panel
 **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)
+npx @satanwagen/reviewkit-cli key      # print the current key
+npx @satanwagen/reviewkit-cli rotate   # issue a new secret — the old key stops working immediately
+npx @satanwagen/reviewkit-cli 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
+If the host sends a CSP, the bridge needs `connect-src http://127.0.0.1:*` (see "CSP").
+
+## Demos
 
 ```sh
 cd examples/vite-demo
 npm install
-npm run dev   # http://localhost:3010 — dev build, so the layer is active immediately
+npm run dev   # http://localhost:3010 — devAutoOn keeps the layer on in dev
 ```
 
-Also try `http://localhost:3010/?review=demo` to exercise URL activation.
+Also try `http://localhost:3010/?review=demo` to exercise URL activation. `examples/next-demo` is the same site on Next.js (App Router, `/next` entry, CSP headers) on port 3011.
 
 ## Development
 
@@ -281,4 +349,7 @@ npm install
 npm run typecheck
 npm run lint
 npm run build   # tsup → dist/ (ESM + CJS + d.ts)
+npm test        # CLI tests + activation matrix (needs dist/)
 ```
+
+See `CHANGELOG.md` for the 0.1.3 default changes and migration notes.

package/dist/activate.cjs

@@ -0,0 +1,150 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/activate.ts
+var activate_exports = {};
+__export(activate_exports, {
+  STICKY_KEY: () => STICKY_KEY,
+  clearSticky: () => clearSticky,
+  hostAllowed: () => hostAllowed,
+  isLocalHost: () => isLocalHost,
+  isStickyEnabled: () => isStickyEnabled,
+  reviewParam: () => reviewParam,
+  setSticky: () => setSticky,
+  shouldActivate: () => shouldActivate
+});
+module.exports = __toCommonJS(activate_exports);
+var STICKY_KEY = "review-kit:sticky";
+var STICKY_TTL_MS = 4 * 60 * 60 * 1e3;
+function safeRemove(storage, key) {
+  try {
+    storage().removeItem(key);
+  } catch {
+  }
+}
+function readSticky() {
+  try {
+    const raw = window.sessionStorage.getItem(STICKY_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null && typeof parsed.token === "string" && typeof parsed.until === "number") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+function isStickyEnabled(token) {
+  if (token === void 0 || token === "") return false;
+  const sticky = readSticky();
+  if (!sticky) return false;
+  if (sticky.until < Date.now() || sticky.token !== token) {
+    safeRemove(() => window.sessionStorage, STICKY_KEY);
+    return false;
+  }
+  return true;
+}
+function setSticky(token, on) {
+  try {
+    if (on && token !== void 0 && token !== "") {
+      const value = { token, until: Date.now() + STICKY_TTL_MS };
+      window.sessionStorage.setItem(STICKY_KEY, JSON.stringify(value));
+    } else {
+      window.sessionStorage.removeItem(STICKY_KEY);
+    }
+  } catch {
+  }
+}
+function clearSticky() {
+  safeRemove(() => window.sessionStorage, STICKY_KEY);
+}
+function reviewParam() {
+  try {
+    return new URLSearchParams(window.location.search).get("review");
+  } catch {
+    return null;
+  }
+}
+function hostAllowed(allowedHosts) {
+  if (!allowedHosts || allowedHosts.length === 0) return true;
+  let host = "";
+  try {
+    host = window.location.hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  return allowedHosts.some((pattern) => {
+    const regex = new RegExp(
+      "^" + pattern.toLowerCase().split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$"
+    );
+    return regex.test(host);
+  });
+}
+function isLocalHost() {
+  try {
+    const host = window.location.hostname.toLowerCase();
+    return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.endsWith(".localhost");
+  } catch {
+    return false;
+  }
+}
+var warnedNoToken = false;
+var warnedMismatch = false;
+function shouldActivate(options = {}) {
+  if (typeof window === "undefined") return false;
+  if (options.enabled === false) return false;
+  if (!hostAllowed(options.allowedHosts)) return false;
+  const param = reviewParam();
+  if (param === "off") {
+    clearSticky();
+    return false;
+  }
+  if (options.devAutoOn === true) return true;
+  const token = options.token;
+  if (token === void 0 || token === "") {
+    if (param !== null && param !== "" && !warnedNoToken) {
+      warnedNoToken = true;
+      console.warn(
+        "[review-kit] `?review` is present but no `token` is configured; the layer stays off. Pass `token` to <ReviewKit /> (or `devAutoOn` for local development)."
+      );
+    }
+    return false;
+  }
+  if (param !== null && param !== "") {
+    if (param === token) return true;
+    if (!warnedMismatch) {
+      warnedMismatch = true;
+      console.warn("[review-kit] `?review` token does not match the configured token; staying inactive.");
+    }
+    return false;
+  }
+  return isStickyEnabled(token);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  STICKY_KEY,
+  clearSticky,
+  hostAllowed,
+  isLocalHost,
+  isStickyEnabled,
+  reviewParam,
+  setSticky,
+  shouldActivate
+});
+//# sourceMappingURL=activate.cjs.map

package/dist/activate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/activate.ts"],"sourcesContent":["/**\n * `@satanwagen/reviewkit/activate` — the activation decision, React-free.\n *\n * Hosts that lazy-load the review layer need to know BEFORE importing any\n * React code whether this page load should show the layer at all. This\n * module is that decision, and the only supported way to read ReviewKit's\n * persisted opt-in state (the sessionStorage format is private and may\n * change; `shouldActivate` will not).\n *\n * Rules (no exceptions, no environment sniffing):\n *\n *   - `enabled: false`            → never.\n *   - hostname ∉ `allowedHosts`   → never (when an allowlist is given).\n *   - `?review=off`               → never; also clears the in-tab opt-in.\n *   - no `token` configured       → never. `?review=x` without a token logs\n *                                   a warning and stays off.\n *   - `?review=<token>`           → yes.\n *   - valid in-tab sticky session → yes (started by an earlier `?review=<token>`\n *                                   load in this tab, bound to the token,\n *                                   ~4 h sliding expiry).\n *   - `devAutoOn: true`           → yes, regardless of URL/token. The host\n *                                   decides when (e.g. `import.meta.env.DEV`);\n *                                   the library never reads NODE_ENV.\n */\n\nexport interface ActivationOptions {\n  /** The review token. Without it the layer never activates (except `devAutoOn`). */\n  token?: string;\n  /** Master switch. `false` short-circuits everything. Default `true`. */\n  enabled?: boolean;\n  /** Hostname allowlist with `*` wildcards. Unset = any host. */\n  allowedHosts?: string[];\n  /** Force the layer on for this page load (dev convenience; host-controlled). */\n  devAutoOn?: boolean;\n}\n\n/** @internal sessionStorage key of the per-tab opt-in. Format is private. */\nexport const STICKY_KEY = 'review-kit:sticky';\nconst STICKY_TTL_MS = 4 * 60 * 60 * 1000;\n\ninterface Sticky {\n  token: string;\n  until: number;\n}\n\nfunction safeRemove(storage: () => Storage, key: string): void {\n  try {\n    storage().removeItem(key);\n  } catch {\n    /* storage unavailable */\n  }\n}\n\nfunction readSticky(): Sticky | null {\n  try {\n    const raw = window.sessionStorage.getItem(STICKY_KEY);\n    if (!raw) return null;\n    const parsed: unknown = JSON.parse(raw);\n    if (\n      typeof parsed === 'object' &&\n      parsed !== null &&\n      typeof (parsed as Sticky).token === 'string' &&\n      typeof (parsed as Sticky).until === 'number'\n    ) {\n      return parsed as Sticky;\n    }\n  } catch {\n    /* unreadable */\n  }\n  return null;\n}\n\n/** @internal Is the per-tab opt-in present, unexpired and bound to `token`? */\nexport function isStickyEnabled(token: string | undefined): boolean {\n  if (token === undefined || token === '') return false;\n  const sticky = readSticky();\n  if (!sticky) return false;\n  if (sticky.until < Date.now() || sticky.token !== token) {\n    safeRemove(() => window.sessionStorage, STICKY_KEY);\n    return false;\n  }\n  return true;\n}\n\n/** @internal Start / renew / end the per-tab opt-in. No-op without a token. */\nexport function setSticky(token: string | undefined, on: boolean): void {\n  try {\n    if (on && token !== undefined && token !== '') {\n      const value: Sticky = { token, until: Date.now() + STICKY_TTL_MS };\n      window.sessionStorage.setItem(STICKY_KEY, JSON.stringify(value));\n    } else {\n      window.sessionStorage.removeItem(STICKY_KEY);\n    }\n  } catch {\n    /* storage unavailable — the choice just won't persist */\n  }\n}\n\n/** @internal Clear the per-tab opt-in. */\nexport function clearSticky(): void {\n  safeRemove(() => window.sessionStorage, STICKY_KEY);\n}\n\n/** @internal The raw `?review` value of the current URL, or null. */\nexport function reviewParam(): string | null {\n  try {\n    return new URLSearchParams(window.location.search).get('review');\n  } catch {\n    return null;\n  }\n}\n\n/** Does the current hostname match one of the allowed patterns?\n *  '*' matches any characters ('*.dev.example' → a.dev.example, a.b.dev.example). */\nexport function hostAllowed(allowedHosts: string[] | undefined): boolean {\n  if (!allowedHosts || allowedHosts.length === 0) return true;\n  let host = '';\n  try {\n    host = window.location.hostname.toLowerCase();\n  } catch {\n    return false;\n  }\n  return allowedHosts.some((pattern) => {\n    const regex = new RegExp(\n      '^' +\n        pattern\n          .toLowerCase()\n          .split('*')\n          .map((part) => part.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&'))\n          .join('.*') +\n        '$',\n    );\n    return regex.test(host);\n  });\n}\n\n/** Loopback hosts where a missing allowlist is expected, not a smell. */\nexport function isLocalHost(): boolean {\n  try {\n    const host = window.location.hostname.toLowerCase();\n    return host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || host.endsWith('.localhost');\n  } catch {\n    return false;\n  }\n}\n\nlet warnedNoToken = false;\nlet warnedMismatch = false;\n\n/**\n * Should the review layer be active for this page load?\n *\n * Read-only except for one deliberate side effect: `?review=off` clears the\n * in-tab opt-in, so a host that gates a lazy import on this function still\n * honours \"off\" on the next load. Safe to call on the server (returns false).\n */\nexport function shouldActivate(options: ActivationOptions = {}): boolean {\n  if (typeof window === 'undefined') return false;\n  if (options.enabled === false) return false;\n  if (!hostAllowed(options.allowedHosts)) return false;\n\n  const param = reviewParam();\n  if (param === 'off') {\n    clearSticky();\n    return false;\n  }\n  if (options.devAutoOn === true) return true;\n\n  const token = options.token;\n  if (token === undefined || token === '') {\n    if (param !== null && param !== '' && !warnedNoToken) {\n      warnedNoToken = true;\n      console.warn(\n        '[review-kit] `?review` is present but no `token` is configured; the layer stays off. ' +\n          'Pass `token` to <ReviewKit /> (or `devAutoOn` for local development).',\n      );\n    }\n    return false;\n  }\n  if (param !== null && param !== '') {\n    if (param === token) return true;\n    if (!warnedMismatch) {\n      warnedMismatch = true;\n      console.warn('[review-kit] `?review` token does not match the configured token; staying inactive.');\n    }\n    return false;\n  }\n  return isStickyEnabled(token);\n}\n"],"mappings":"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","names":[]}