@emplugins/emprivacy 1.0.0

package/docs/DEVELOPMENT.md

@@ -0,0 +1,36 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Development — dependencies and security
+
+## What EmPrivacy ships to npm
+
+Runtime dependencies for the published package are **`zod`** only. **EmDash** is a **peer dependency** (your site installs it). The **`emdash`** package in this repo’s `devDependencies` exists so local `typecheck` and tests can resolve `import … from "emdash"`.
+
+## Package manager
+
+This repo uses **pnpm** (`packageManager` in `package.json`). Install and CI:
+
+```bash
+pnpm install
+pnpm run typecheck
+pnpm test
+pnpm run build
+```
+
+## `pnpm audit` and the Kysely override
+
+The `emdash` dev dependency pulls in a SQL stack that historically resolved **`kysely@0.27.x`**, which is affected by advisories (for example [GHSA-wmrf-hv6w-mr66](https://github.com/advisories/GHSA-wmrf-hv6w-mr66) and [GHSA-8cpq-38p9-67gx](https://github.com/advisories/GHSA-8cpq-38p9-67gx)) until patched releases.
+
+**This repository pins a safe Kysely** via `pnpm.overrides` in `package.json` (currently `0.29.2`, above the patched range for known advisories). Regenerate the lockfile with `pnpm install` after changing overrides.
+
+- Full dev tree: `pnpm audit` should report **0 vulnerabilities** after a clean `pnpm install --frozen-lockfile`. If upstream `emdash` introduces new transitive advisories, track them here and adjust `pnpm.overrides` when a patched release exists.
+- Production install only: `pnpm audit --omit=dev` reflects **only** published runtime deps (currently `zod`).
+
+## Deprecation warnings you may still see
+
+`pnpm install` can still print **deprecated** messages for **transitive** packages **not** maintained by this repo, for example:
+
+- **`prebuild-install`** — pulled in by `better-sqlite3` (used by `emdash`). The [package is deprecated](https://www.npmjs.com/package/prebuild-install) pending upstream changes in native addons.
+- **`node-domexception`** — used under the [libsql / fetch](https://www.npmjs.com/package/node-domexception) client stack; the package is deprecated in favor of native `DOMException` in newer Node.
+
+Those warnings do not imply that EmPrivacy’s own source is outdated; they track **upstream** `emdash` and its dependencies. Re-run `pnpm audit` to confirm there are no known vulnerabilities for your install.

package/docs/GETTING_STARTED.md

@@ -0,0 +1,140 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Getting started with EmPrivacy
+
+This guide is for site builders who want cookie consent working on an **EmDash** site without reading plugin source.
+
+## What you get
+
+- A **banner** on first visit (or after you change **Policy / consent version**).
+- Toggles for **Analytics** and **Marketing** (essential/theme cookies are not blocked by this plugin—see the main README).
+- **Privacy and cookie policy links** you control: usually an EmDash **Page** via a short **path** (e.g. `/privacy`) or a full `https://` link. Paths are turned into full URLs using EmDash’s URL helper so they work in dev and production.
+- **Analytics** — choose a **platform** in admin (e.g. **Cloudflare Web Analytics** and your **site token**, or **Custom** with one `https://` script URL per line, or **None**). **Marketing** — `https` script URLs, one per line. Scripts load **after** consent for that category.
+
+## Before you begin
+
+1. An EmDash site with `emdash` in `astro.config` ([plugins overview](https://docs.emdashcms.com/plugins/overview/)).
+2. Ability to edit **`astro.config`** and redeploy (or run locally).
+
+---
+
+## Step 1 — Install the package
+
+```bash
+npm install @emplugins/emprivacy
+```
+
+The package is versioned with **semver** on npm; to pin a line, use a range such as `@emplugins/emprivacy@^1.0.0`. See [RELEASES.md](./RELEASES.md) for how releases are numbered.
+
+---
+
+## Step 2 — Add the plugin to Astro
+
+Open `astro.config.mjs` (or `.ts`).
+
+1. Import the plugin:
+
+   ```ts
+   import { emprivacyPlugin } from "@emplugins/emprivacy";
+   ```
+
+2. Add **`emprivacyPlugin()`** to **`emdash({ plugins: [...] })`**. Put **EmPrivacy first** if you use other plugins that inject scripts or metadata.
+
+   ```ts
+   emdash({
+     plugins: [
+       emprivacyPlugin(),
+       // ...other plugins
+     ],
+   }),
+   ```
+
+3. Save and restart the dev server (or rebuild).
+
+---
+
+## Step 3 — Layout must include EmDash hooks
+
+Your base layout must include EmDash’s head/body injection points (e.g. `<EmDashHead />`, `<EmDashBodyStart />`, `<EmDashBodyEnd />` or your theme’s equivalents). Otherwise the banner may not render. See [EmDash docs](https://docs.emdashcms.com/).
+
+---
+
+## Step 4 — Create or pick your Privacy Policy Page (EmDash)
+
+If you already have a **Page** for your privacy policy:
+
+1. Open that Page on the **public site** (or preview) and look at the **path** in the address bar — for example `https://yoursite.com/privacy` → use **`/privacy`**.  
+2. In **EmPrivacy** settings, paste that path into **Privacy policy — EmDash Page path or https URL** (or paste a full `https://…` URL if the policy is not an EmDash Page).
+
+If you still need a Page: create and publish a Page in EmDash, note its URL path, then enter that path in EmPrivacy as above.
+
+Same idea for an optional **Cookie policy** field: path (e.g. `/cookies`) or `https://…`.
+
+**Not accepted:** bare domains (`example.com`), `http://…` URLs, or protocol-relative links (`//…`). Use **`/your-path`** or **`https://…`**.
+
+---
+
+## Step 5 — Configure EmPrivacy in the admin
+
+1. Log into the **site admin**.
+2. Open **EmPrivacy** (shield icon).
+3. Set:
+   - **Privacy policy** — path or `https` (see Step 4).
+   - **Cookie policy** — optional; same rules.
+   - **Banner title** and **Short notice**.
+   - **Policy / consent version** — bump when you change legal text so visitors see the banner again.
+   - **Analytics platform** — *Cloudflare Web Analytics* (default), *None*, or *Custom* (see below).
+   - **Cloudflare** — In the [Cloudflare dashboard](https://dash.cloudflare.com/) → **Web Analytics**, copy the **site token** for your property and paste it into **Cloudflare Web Analytics site token**. EmPrivacy injects the standard `beacon.min.js` script with `data-cf-beacon='{"token":"…"}'` after the visitor consents to analytics.
+   - **Custom analytics** — If you pick **Custom**, one **`https://`** script URL per line, `src` only (not a full `<script>` block); see [Custom script URLs (not HTML)](#custom-script-urls-not-html) below.
+   - **Marketing script URLs** — one **`https://`** URL per line, or leave blank.
+4. Optional: **Strict defaults**, **Google Consent Mode v2**, **Log consent to server** (see main README).
+5. **Save settings**.
+
+**Custom script URLs (not HTML)** (only when **Analytics** is set to **Custom**)
+
+Each line must be a **full https URL** to a `.js` file (the script `src`). **Do not** paste HTML comments, tags, or attributes. EmPrivacy injects with `<script src="…">` only (no `data-*` for custom mode).
+
+---
+
+## Step 6 — Verify on the public site
+
+1. Use a **private/incognito** window (or clear site cookies).
+2. Confirm the **banner** appears. After you save a choice, a small **cookie button** stays in the bottom-left; click it to **change** analytics/marketing choices (the page reloads when you save from that panel so consent stays in sync with loaded scripts).
+3. Click **Privacy policy** (and **Cookie policy** if set): they should open the EmDash Page or external URL you configured.
+4. In **Developer tools → Network**: before accepting, listed third-party scripts should not load; after consent, they should load only for the categories you allowed.
+5. Reload: the banner should stay dismissed if the cookie matches your **Policy / consent version**.
+
+---
+
+## Step 7 — Testing before go-live
+
+Run automated checks if you develop the plugin or CI:
+
+```bash
+npm run typecheck && npm run build && npm test
+```
+
+For a full staging checklist (banner, strict mode, admin, optional logging, Google), see **[TESTING.md](./TESTING.md)**.
+
+---
+
+## Common problems
+
+| Problem | What to check |
+|--------|----------------|
+| Nothing appears | EmDash layout missing head/body components; plugin not in `plugins: []`; dev server restarted after config change |
+| Scripts load before consent | No hard-coded third-party scripts in the theme; EmPrivacy listed **before** those plugins in `plugins` |
+| EmPrivacy missing in admin | Plugin not installed or `astro.config` wrong; check build errors |
+| Save fails on privacy/cookie | Value must be a **root-relative path** (`/something`) or **`https://…`** (not `http://` or a bare hostname) |
+| Save fails: “Invalid … script URL” | For **Custom** analytics or **Marketing** URLs, enter one **https URL** per line (the script `src`), not a `<script>` tag. See [Custom script URLs (not HTML)](#custom-script-urls-not-html) |
+| Privacy link 404 or wrong page | Path must match the live EmDash route (compare with the address bar when viewing that Page) |
+| Link works on staging but path looks wrong | Paths are resolved with EmDash `ctx.url()`; ensure the Page is published and the path matches production routing |
+
+---
+
+## More reading
+
+- Main **[README](../README.md)** — disclaimer, features table, registration order, full testing section  
+- **[TESTING.md](./TESTING.md)** — pre-deploy QA and CI  
+- **[PLUGIN_SETTINGS.md](./PLUGIN_SETTINGS.md)** — what each admin setting does (with examples)
+- **[CONTRIBUTING.md](../CONTRIBUTING.md)** — how to contribute

package/docs/PLUGIN_SETTINGS.md

@@ -0,0 +1,181 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# EmPrivacy — Plugin settings reference
+
+This page documents every field on the **EmPrivacy** admin settings page (shield icon → **EmPrivacy**).
+
+It’s written for site owners and maintainers who want to understand:
+
+- What each setting **does**
+- What input format is expected (with **examples**)
+- What public-site behavior changes when you change it
+
+> Note: EmPrivacy is a technical implementation tool, not legal advice. You are responsible for configuring categories and scripts consistently with your privacy/cookie policies and applicable laws.
+
+---
+
+## Banner settings
+
+### Banner title
+
+- **What it is**: The heading shown at the top of the cookie banner and the reopen panel.
+- **Example**: `Cookies & privacy`
+- **Behavior**: Updates visible banner UI copy only (no effect on consent logic).
+
+### Short notice
+
+- **What it is**: The banner message text shown under the title.
+- **Example**: `We use cookies to run this site and optionally for analytics and marketing. You can accept or customize your choices.`
+- **Behavior**: Updates visible banner UI copy only (no effect on consent logic).
+
+---
+
+## Policy links (shown in the banner)
+
+These links are rendered as “Privacy policy” (and optionally “Cookie policy”) in the banner and reopen panel.
+
+### Privacy policy — EmDash Page path or https URL
+
+- **What it is**: Where your privacy policy lives.
+- **Allowed inputs**:
+  - A **root-relative path** to an EmDash Page (resolved to a full URL by EmDash at runtime), for example:
+    - `/privacy`
+  - A full **`https://…`** URL, for example:
+    - `https://example.com/privacy`
+- **Not accepted**:
+  - `http://…`
+  - `example.com/privacy` (missing scheme)
+  - `//example.com/privacy` (protocol-relative)
+  - paths without a leading slash like `privacy`
+- **Behavior**:
+  - Controls where the “Privacy policy” link in the banner opens.
+  - Does not change consent cookie format or script loading.
+
+### Cookie policy (optional) — path or https URL
+
+- **What it is**: Optional link to a separate cookie policy.
+- **Allowed inputs**: same rules as the privacy policy field.
+- **Example**: `/cookies` or `https://example.com/cookies`
+- **Behavior**:
+  - When set, the banner shows an additional “Cookie policy” link.
+  - When blank, no cookie-policy link is shown.
+
+---
+
+## Consent versioning
+
+### Policy / consent version
+
+- **What it is**: A version string stored into the consent cookie. When you change it, existing visitors are prompted again.
+- **Example values**:
+  - `1`
+  - `2026-04-25`
+  - `v3`
+- **Behavior**:
+  - EmPrivacy stores consent as a cookie like `{ v, a, m }` where `v` is your policy version and `a/m` represent analytics/marketing choices.
+  - If a visitor has an older cookie version (or no cookie), the banner will show again.
+  - Use this when you materially change your privacy/cookie policy text, tracking vendors, or categories.
+
+---
+
+## Defaults and consent UX
+
+### Strict defaults (require opt-in for analytics & marketing)
+
+- **What it is**: Controls whether the default state of the banner toggles is **off** (opt-in) or **on** (opt-out).
+- **Example**:
+  - Enabled: analytics + marketing start **off**
+  - Disabled: analytics + marketing start **on**
+- **Behavior**:
+  - **Enabled**: The initial banner loads with analytics and marketing toggles **unchecked** by default.
+  - **Disabled**: The initial banner loads with analytics and marketing toggles **checked** by default.
+  - This only affects the initial default state before the visitor makes a choice; once a cookie is set, the stored choice is used.
+
+---
+
+## Analytics settings
+
+Analytics scripts only load after the visitor consents to **Analytics** (unless you hard-code scripts elsewhere in your site/theme, which you should avoid).
+
+### Analytics platform
+
+- **What it is**: Chooses where analytics scripts come from.
+- **Options**:
+  - **Cloudflare Web Analytics**: loads Cloudflare’s beacon **after Analytics consent** (requires a site token).
+  - **None**: never loads third-party analytics scripts via EmPrivacy.
+  - **Custom**: loads your provided `https://` script URLs **after Analytics consent**.
+- **Behavior**:
+  - Changing this alters which scripts are injected when Analytics consent is granted.
+  - This does not affect Marketing scripts (those are separate).
+
+### Cloudflare Web Analytics site token
+
+- **What it is**: The token Cloudflare gives you for your site under Cloudflare → Web Analytics.
+- **Example**: a Cloudflare token string copied from your dashboard (do not add quotes).
+- **Behavior**:
+  - When Analytics consent is granted and **Analytics platform = Cloudflare**, EmPrivacy injects Cloudflare’s standard beacon script with the `data-cf-beacon` attribute.
+  - If the token is blank, EmPrivacy will have nothing to inject for Cloudflare analytics even if consent is granted.
+
+### Custom analytics script URLs (one https URL per line, not a `<script>` tag)
+
+- **What it is**: A list of third-party analytics scripts to load after Analytics consent, when **Analytics platform = Custom**.
+- **Format**: one full **`https://…`** URL per line (the script `src`), no HTML.
+- **Example**:
+
+  ```text
+  https://cdn.example.com/analytics.js
+  https://static.example.net/vendor/tracker.min.js
+  ```
+
+- **Behavior**:
+  - When Analytics consent is granted, EmPrivacy injects each URL as `<script src="…">` into the document.
+  - When Analytics consent is denied, these scripts are not injected by EmPrivacy.
+
+---
+
+## Marketing settings
+
+Marketing scripts only load after the visitor consents to **Marketing**.
+
+### Marketing script URLs (one https URL per line, not a `<script>` tag)
+
+- **What it is**: A list of third-party marketing scripts to load after Marketing consent.
+- **Format**: one full **`https://…`** URL per line (the script `src`), no HTML.
+- **Example**:
+
+  ```text
+  https://cdn.example.com/pixel.js
+  https://static.example.net/ads/retargeting.js
+  ```
+
+- **Behavior**:
+  - When Marketing consent is granted, EmPrivacy injects each URL as `<script src="…">`.
+  - When Marketing consent is denied, these scripts are not injected by EmPrivacy.
+
+---
+
+## Google integrations (optional)
+
+### Google Consent Mode v2 (denied defaults in head; updates after choice)
+
+- **What it is**: Enables Google Consent Mode v2 integration.
+- **Behavior**:
+  - When enabled, EmPrivacy emits a “denied by default” consent configuration early (in `<head>`).
+  - After the visitor chooses, EmPrivacy calls `gtag("consent","update", …)` to reflect Analytics/Marketing choices.
+  - This is only meaningful if your site uses `gtag`/Google tags; you should validate behavior using Google tooling/docs.
+
+---
+
+## Server-side logging (optional)
+
+### Log consent choices to the server (minimal record; no IP stored)
+
+- **What it is**: If enabled, EmPrivacy will send a minimal consent snapshot to the server when a visitor saves a choice.
+- **Behavior**:
+  - When enabled, the browser sends a POST to the EmPrivacy record endpoint with:
+    - the current policy version
+    - whether analytics was allowed
+    - whether marketing was allowed
+  - The settings page will additionally show **Recent consent records** (up to 15), newest first.
+  - When disabled, EmPrivacy does not attempt to log consent server-side and the “Recent consent records” section will not appear.
+

package/docs/RELEASES.md

@@ -0,0 +1,81 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Releases and versioning
+
+Published **npm** versions of [`@emplugins/emprivacy`](https://www.npmjs.com/package/@emplugins/emprivacy) follow **[Semantic Versioning 2.0.0](https://semver.org/)** (`MAJOR.MINOR.PATCH`).
+
+**Toolchain:** **pnpm** + **[Changesets](https://github.com/changesets/changesets)** + GitHub Actions (`release.yml`). Packages publish to the **[emplugins](https://www.npmjs.com/org/emplugins)** npm org via `pnpm publish`. Source: [EmPlugins/EmPrivacy](https://github.com/EmPlugins/EmPrivacy).
+
+## What each bump means
+
+| Level | When to use it |
+|--------|----------------|
+| **PATCH** | Bug fixes and safe internal refactors; no intentional behavior or API contract change for integrators. |
+| **MINOR** | New features, new optional admin fields, or additive exports; existing sites keep working without config changes unless they opt in. |
+| **MAJOR** | Breaking changes for site authors or the plugin contract (e.g. renamed exports, changed hook shapes, cookie JSON shape, required EmDash peer range). |
+
+**Pre-1.0 (`0.x.y`):** Per the semver spec, anything may change; in practice we still use **patch / minor / major** as above so upgrades are predictable. Treat **minor** bumps as the place we may ship breaking changes until `1.0.0`, and read the release notes before upgrading.
+
+**Policy / consent version** (in the EmDash admin) is separate from package semver: it only re-prompts visitors when your legal text or choices change.
+
+## Safe publishing
+
+These guards keep published tarballs consistent with `package.json` and avoid shipping stale or missing `dist/` output.
+
+- **`dist/` is not committed** — It is listed in `.gitignore`. Build artifacts are produced locally, in CI, and **immediately before publish** via `prepublishOnly`.
+- **`prepublishOnly`** — Runs `sync:version` (keeps `src/version.ts` aligned with `package.json`), `typecheck`, `build`, `test`, **`verify:exports`**, and `pnpm audit`.
+- **`kysely` override** — The dev-dependency `emdash` can resolve an older `kysely`; `pnpm.overrides` in `package.json` pins a **patched** Kysely so `pnpm audit` stays clean. See [docs/DEVELOPMENT.md](DEVELOPMENT.md).
+- **Install range** — Pin consumers with semver as needed, e.g. `@emplugins/emprivacy@^1.0.0`.
+
+Before publishing locally (usually unnecessary once CI is configured):
+
+```bash
+pnpm run build
+pnpm pack --dry-run
+```
+
+## Cutting a release (maintainers)
+
+### EmDash compatibility (fully agent-driven)
+
+In Cursor:
+
+```
+update to latest emdash release
+```
+
+Uses [`.cursor/skills/emdash-release/`](../.cursor/skills/emdash-release/SKILL.md) and [`.cursor/emdash-release.json`](../.cursor/emdash-release.json): conformance → compat PR → Version Packages merge → `pnpm release:publish` (npm + GitHub Release). Details: [maintainer-release.md](./maintainer-release.md).
+
+### Automated feature release (Changesets)
+
+1. On a feature PR, run `pnpm changeset` and commit the generated file under `.changeset/`.
+2. Merge to `main`. GitHub Actions opens a **Version Packages** PR when changesets are pending.
+3. Merge the Version Packages PR. CI runs `pnpm release:publish` and creates a GitHub Release.
+
+Requires **`NPM_TOKEN`** secret on the repo (publish rights for `@emplugins/emprivacy` on the [emplugins](https://www.npmjs.com/org/emplugins) org).
+
+### Local (fallback)
+
+```bash
+pnpm install
+pnpm changeset          # on feature branch
+pnpm changeset version  # on main after merge
+pnpm release:publish    # sync, build, test, verify, audit, publish
+git push --follow-tags
+```
+
+## Tags
+
+Release tags use the **`v` prefix** (e.g. `v0.3.1`) via Changesets / GitHub Releases.
+
+## EmDash compatibility
+
+See [EMDASH_COMPAT.md](../EMDASH_COMPAT.md) for tested upstream versions and upgrade playbook.
+
+## Consumers
+
+Pin with a range that matches your risk tolerance, for example:
+
+```bash
+pnpm add @emplugins/emprivacy@^1.0.0
+```

package/docs/RELEASE_NOTES.md

@@ -0,0 +1,109 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Unreleased
+
+# @emplugins/emprivacy v1.0.0 (pending Version Packages)
+
+## Breaking
+
+- **npm package renamed** — Install and import **`@emplugins/emprivacy`** ( [emplugins](https://www.npmjs.com/org/emplugins) org ). Legacy unscoped `emprivacy` is no longer the publish target.
+- **Sandbox entrypoint** — Descriptor uses `@emplugins/emprivacy/sandbox` (update only if you referenced the old entry string directly).
+
+## Unchanged
+
+- Runtime plugin id `emprivacy`, cookie `emprivacy_cc`, and API routes.
+- Source repository: [EmPlugins/EmPrivacy](https://github.com/EmPlugins/EmPrivacy).
+
+# emprivacy v0.3.0
+
+## Changes
+
+- **EmDash `>=0.14.0` required** — peer and dev dependency minimum raised from `^0.9.0`. Sites on EmDash 0.9–0.13 should stay on **emprivacy 0.2.x**.
+- **Plugin entry** — `src/sandbox-entry.ts` now default-exports a bare `{ hooks, routes } satisfies SandboxedPlugin` object (types from `emdash/plugin`), matching EmDash 0.13+ standard-format plugins and `@emdash-cms/plugin-audit-log`. No runtime `definePlugin()` import.
+- **CI** — matrix targets **EmDash `0.14.0`**.
+- **Kysely override** — Bumped to **`0.29.2`** so `npm audit` stays clean with `emdash@0.14.x` (see [docs/DEVELOPMENT.md](DEVELOPMENT.md)).
+
+# emprivacy v0.2.1
+
+## Changes
+
+- **Repository** — Canonical GitHub URLs now use **[EmPlugins/EmPrivacy](https://github.com/EmPlugins/EmPrivacy)** (`package.json` `repository` / `bugs` / `homepage`, admin plugin settings doc link, and permalinks in this file). No runtime behavior change.
+
+# emprivacy v0.1.6
+
+## Changes
+
+- Compatibility: CI and manual QA verified with **EmDash `0.7.0`**.
+
+# emprivacy v0.1.5
+
+## Changes
+
+- Fix Cloudflare Web Analytics when consent is granted from the initial banner by reloading after persisting choices (ensures the beacon runs in a normal page lifecycle).
+
+# emprivacy v0.1.4
+
+## Changes
+
+- **Re-open consent** — After the first choice, a floating **cookie** control (bottom-left) re-opens the consent panel. Changing choices and saving **reloads** the page so analytics/marketing script loading matches the new consent (including when revoking). Duplicate `<script src>` tags for the same URL on one page are avoided when possible.
+- **Analytics platforms** — Admin **radio**: **Cloudflare Web Analytics** (default), **None**, or **Custom** script URLs. For Cloudflare, paste the **site token** from the dashboard; EmPrivacy injects `https://static.cloudflareinsights.com/beacon.min.js` with `defer` and `data-cf-beacon='{"token":"…"}'` after analytics consent. Legacy configs with only `analyticsScriptUrls` in KV are treated as **Custom**.
+
+# emprivacy v0.1.3
+
+## Changes
+
+- Pin **Kysely** to a patched version via `overrides` so `npm audit` reports **0** high-severity issues from the `emdash` dev dependency tree (Kysely advisories).
+- Add `npm run audit` to CI and to `prepublishOnly` / `preversion` so releases fail if new audit findings appear.
+- New [docs/DEVELOPMENT.md](https://github.com/EmPlugins/EmPrivacy/blob/v0.1.3/docs/DEVELOPMENT.md) (dependency, audit, and deprecation context for maintainers).
+
+# emprivacy v0.1.2
+
+## Changes
+
+- `verify:exports` script: fail the release if `main` / `exports` paths are missing from `dist/` after build.
+- `publishConfig.access: "public"` for explicit npm visibility.
+- Documented safe-publishing workflow in `docs/RELEASES.md`; CI runs `verify:exports` after `build`.
+
+# emprivacy v0.1.1
+
+## Changes
+
+- Packaging/release safety improvements for npm publishing (publish-time checks + version sync).
+- Added CI workflow to run `typecheck`, `test`, and `build` on PRs/pushes.
+
+# emprivacy v0.1.0 — initial release
+
+First published **npm** release of **EmPrivacy**, an open source [EmDash](https://github.com/emdash-cms/emdash) plugin for cookie consent, category-based choices (essential / analytics / marketing), and **client-side** loading of third-party scripts only after consent.
+
+## Highlights
+
+- **Banner + categories** — Visitors choose analytics and marketing; essential is informational.
+- **Policy links** — Privacy (and optional cookie) policy as an EmDash **Page** path (e.g. `/privacy`) or external `https://` URL; paths resolved with EmDash `ctx.url()`.
+- **Script gating** — Only `https://` script URLs you configure in admin; injected as `<script src>` after consent (no arbitrary admin HTML on the public site).
+- **Consent cookie** — `emprivacy_cc` with JSON `{ v, a, m }` (policy/consent version, analytics, marketing).
+- **Optional server logging** — `POST /_emdash/api/plugins/emprivacy/record` and recent records in admin (no IP in v1).
+- **Optional Google Consent Mode v2** — Denied defaults in `<head>` and updates after choice (validate with [Google’s documentation](https://support.google.com/tagmanager/answer/13695607)).
+
+## Requirements
+
+- **EmDash** `^0.5.0` — test on the minor you deploy.
+- **Trusted plugins** in `astro.config` (`plugins: []`); EmPrivacy needs injection/fragments (not sandbox-only marketplace mode). See [EmDash plugin overview](https://docs.emdashcms.com/plugins/overview/).
+- **Node.js** `>= 20`.
+
+## Install
+
+```bash
+npm install emprivacy@^0.1.0
+```
+
+Register `emprivacyPlugin()` early in `emdash({ plugins: [...] })` and wire EmDash layout components (`EmDashHead`, body slots, etc.). Full quick start: [README](https://github.com/EmPlugins/EmPrivacy/blob/v0.1.0/README.md).
+
+## Documentation
+
+- [Getting started](https://github.com/EmPlugins/EmPrivacy/blob/v0.1.0/docs/GETTING_STARTED.md)
+- [Testing / pre-deploy checklist](https://github.com/EmPlugins/EmPrivacy/blob/v0.1.0/docs/TESTING.md)
+- [Releases & semver](https://github.com/EmPlugins/EmPrivacy/blob/v0.1.0/docs/RELEASES.md)
+
+## Legal
+
+EmPrivacy is a **technical** CMP-style building block. It is **not legal advice**. You remain responsible for notices, vendors, and compliance in your jurisdictions.

package/docs/TESTING.md

@@ -0,0 +1,53 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Testing EmPrivacy before deploy
+
+Testing is split into **automated** checks (CI-friendly) and **manual** checks that require a running EmDash site, because the plugin integrates with EmDash’s runtime, KV, storage, admin Block Kit, and public page pipeline.
+
+## Automated (in this repo)
+
+| Command | What it verifies |
+|--------|-------------------|
+| `npm run typecheck` | TypeScript types against `emdash` APIs |
+| `npm run build` | Bundles ESM + declarations (`dist/`) |
+| `npm test` | Unit tests for **pure** helpers in `src/config.ts` (validation, normalization, URL list parsing, JSON escaping) |
+
+These scripts do **not** start EmDash or exercise `page:fragments`, admin routes, or the consent cookie in a browser. They catch regressions in config/save validation and packaging early.
+
+## Manual integration QA (required before production)
+
+Use a **staging** EmDash **`0.14.0+`** Astro app with `emprivacyPlugin()` in `plugins: []`, layout wires (`EmDashHead` / body components), and the same EmDash version you plan to ship.
+
+Work through the checklist from the main [README](../README.md) (also copied below). Record pass/fail and browser + EmDash versions.
+
+### Core flows
+
+1. **Banner** — Incognito window: banner appears when there is no `emprivacy_cc` cookie or when **Policy / consent version** in admin does not match the cookie’s `v` field.
+2. **Re-open consent** — After dismissing the banner, confirm a **cookie button** appears (bottom-left). Click it: the same options appear; **Save choices** (or Accept/Reject) reloads the page. After reload, **Network** should list analytics scripts only if analytics is on; turn analytics off, save, reload, and those scripts should not run. If you use **Cloudflare Web Analytics** in admin, after consent confirm `beacon.min.js` loads and the tag includes `data-cf-beacon` with your token.
+3. **Strict defaults** — With strict mode on, deny non-essential and confirm configured analytics/marketing URLs do **not** appear in Network until the user accepts (or enables those categories in Customize).
+4. **Persistence** — After accept, reload: banner stays closed; scripts load according to saved choices (Network tab).
+5. **Admin** — EmPrivacy settings page loads, **Save** persists; public banner text and links match what you saved (after refresh / new request).
+6. **Optional server log** — Enable “Log consent…”; submit consent; confirm a row appears under recent records and `POST /_emdash/api/plugins/emprivacy/record` succeeds (200, `{ ok: true }`) in Network.
+7. **Optional Google Consent Mode** — Enable in admin; verify a denied-default snippet exists in `<head>` before interaction, and updates after choice (see [Google’s Consent Mode docs](https://support.google.com/tagmanager/answer/13695607)).
+
+### Regression triggers
+
+- Bump EmDash minor: re-run manual QA (plugin APIs and admin routing can change).
+- Bump this plugin’s **npm semver** after changing hooks or cookie shape: re-check banner and cookie JSON. Release numbering policy: [RELEASES.md](./RELEASES.md).
+
+## CI suggestion
+
+```bash
+npm ci
+npm run typecheck
+npm run build
+npm test
+```
+
+## Future improvements (not in v1)
+
+- **Integration tests** against EmDash’s `adaptSandboxEntry` + mock `PluginContext` (heavy; depends on EmDash test utilities if exposed).
+- **E2E** (Playwright) against a minimal EmDash fixture app in CI (slower, higher maintenance).
+
+For most teams, **automated unit tests + staging manual QA** is the right balance.
+