@emplugins/emprivacy 1.0.0 → 2.1.0

package/docs/DEVELOPMENT.md

@@ -6,6 +6,8 @@
 
 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"`.
 
+EmPrivacy is a **native** EmDash plugin (`format: "native"`, named `createPlugin()` export), published as **`@emplugins/emprivacy`**. It must be registered in `plugins: []` because it uses `page:fragments`. The `./astro` export ships Portable Text embed placeholders (compiled by the host Astro app, not by `tsdown`).
+
 ## Package manager
 
 This repo uses **pnpm** (`packageManager` in `package.json`). Install and CI:
@@ -19,18 +21,12 @@ 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.
+`pnpm run audit` runs **`pnpm audit --prod`**, so it reflects **published runtime** dependencies only (currently `zod` 4.6.5).
 
-**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.
+The full install (including the `emdash` **dev** tree) can report transitive advisories from EmDash’s tooling stack. Those are owned by the site’s EmDash upgrade path, not by EmPrivacy’s published tarball.
 
-- 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`).
+**This repository pins Kysely** via `pnpm.overrides` in `package.json` (currently `0.29.6`, aligned with EmDash 0.38). Regenerate the lockfile with `pnpm install` after changing overrides.
 
 ## 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.
+`pnpm install` can still print **deprecated** messages for **transitive** packages **not** maintained by this repo (for example native-addon helpers under EmDash’s SQLite stack). Those warnings do not imply that EmPrivacy’s own source is outdated; they track **upstream** `emdash` and its dependencies.

package/docs/GETTING_STARTED.md

@@ -2,119 +2,128 @@
 
 # Getting started with EmPrivacy
 
-This guide is for site builders who want cookie consent working on an **EmDash** site without reading plugin source.
+This guide is for **EmDash site managers** who want cookie consent on a live 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.
+- A **banner** on first visit (or after you change **Policy / consent version**, or after an upgrade that adds the functional category).
+- Toggles for **Functional**, **Analytics**, and **Marketing**. Essential cookies stay on.
+- **Privacy and cookie policy links** you control (EmDash Page path or `https://`).
+- Analytics presets (Cloudflare, Plausible, Fathom, Umami, Simple Analytics, GA4, GTM under Marketing) plus Custom / None.
+- Optional **gated embeds** for official EmDash YouTube / Vimeo / social / Gist blocks.
+- A **vendor list** generated from your settings.
+
+## What you still do yourself
+
+- Write and publish the privacy policy (and cookie policy if you use one).
+- Keep third-party scripts **out of the theme** unless they go through EmPrivacy or `window.emprivacy.has(...)`.
+- Decide whether embeds are **Marketing** (default, typical for YouTube) or **Functional**.
 
 ## Before you begin
 
-1. An EmDash site with `emdash` in `astro.config` ([plugins overview](https://docs.emdashcms.com/plugins/overview/)).
+1. An EmDash site on **`emdash@^0.38.0`** with the EmDash Astro integration in `astro.config`.
 2. Ability to edit **`astro.config`** and redeploy (or run locally).
+3. Register EmPrivacy as a **native** plugin (`plugins: []`, not `sandboxed: []`).
 
 ---
 
 ## Step 1 — Install the package
 
 ```bash
+pnpm add @emplugins/emprivacy
+# or
 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.
+Pin a line with a range such as `@emplugins/emprivacy@^1.0.0`. See [RELEASES.md](./RELEASES.md).
 
 ---
 
 ## Step 2 — Add the plugin to Astro
 
-Open `astro.config.mjs` (or `.ts`).
-
-1. Import the plugin:
-
-   ```ts
-   import { emprivacyPlugin } from "@emplugins/emprivacy";
-   ```
+```ts
+import emdash from "emdash/astro";
+import { emprivacyPlugin } from "@emplugins/emprivacy";
+
+export default defineConfig({
+  integrations: [
+    emdash({
+      plugins: [
+        emprivacyPlugin(),
+        // ...other native plugins
+      ],
+    }),
+  ],
+});
+```
 
-2. Add **`emprivacyPlugin()`** to **`emdash({ plugins: [...] })`**. Put **EmPrivacy first** if you use other plugins that inject scripts or metadata.
+Do **not** put it in `sandboxed: []`.
 
-   ```ts
-   emdash({
-     plugins: [
-       emprivacyPlugin(),
-       // ...other plugins
-     ],
-   }),
-   ```
+### Registration order
 
-3. Save and restart the dev server (or rebuild).
+| Goal | Where to put `emprivacyPlugin()` |
+|------|----------------------------------|
+| Google Consent Mode before other head tags | **First** in `plugins` |
+| Automatic placeholders for `@emdash-cms/plugin-embeds` | **After** the embeds plugin (last wins) |
+| Both | First in `plugins`, and pass `@emplugins/emprivacy/astro` `blockComponents` into `<PortableText />` (site components always win) |
 
 ---
 
 ## 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/).
+Your base layout must include `<EmDashHead page={page} />`, `<EmDashBodyStart page={page} />`, and `<EmDashBodyEnd page={page} />`, usually with `createPublicPageContext` from `emdash/page`. Otherwise the banner will not render.
 
 ---
 
-## Step 4 — Create or pick your Privacy Policy Page (EmDash)
-
-If you already have a **Page** for your privacy policy:
+## Step 4 — Create the legal Pages
 
-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).
+1. Create and **publish** a Page for your privacy policy. Open it on the public site and copy the path (`/privacy`).
+2. Optional: a cookie policy Page (`/cookies`).
+3. In EmPrivacy settings, paste those paths (or full `https://` URLs).
 
-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://…`**.
+**Not accepted:** `http://`, bare hostnames, or `//example.com/...`.
 
 ---
 
-## 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**.
+## Step 5 — Configure in the admin
 
-**Custom script URLs (not HTML)** (only when **Analytics** is set to **Custom**)
+1. Log into **site admin** → shield → **EmPrivacy**.
+2. Set banner title / short notice, policy paths, and **Policy / consent version**.
+3. Choose an **Analytics platform** and fill the matching ID or token. Leave it on **None** if you do not use analytics.
+4. Optional: marketing script URLs (one `https://` `src` per line — never a `<script>` tag).
+5. Optional: gate embeds; pick Functional vs Marketing.
+6. Optional: hex theme colors, locale JSON overrides, Google Consent Mode, server log.
+7. **Save settings**.
 
-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).
+The **What this site uses** table on the same page is generated from the saved config. You can copy it into the cookie policy. Tokens are never listed.
 
 ---
 
 ## 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**.
+1. Incognito window (or clear `emprivacy_cc`).
+2. Banner appears. **Reject non-essential**: no analytics/marketing scripts in Network; embed placeholders stay placeholders.
+3. **Accept all** (or Customize): scripts for allowed categories load; YouTube/Vimeo iframes use allowlisted player hosts after consent.
+4. Privacy / cookie links open the correct Page.
+5. Cookie button (bottom-left) reopens the panel. Saving reloads.
+6. Optional: `window.emprivacy.get()` in the console returns the current state.
 
 ---
 
-## 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
+## Using the public API in a theme
+
+```js
+if (window.emprivacy?.has("analytics")) {
+  // load a first-party or plugin script you own
+}
+window.emprivacy?.onChange((state) => {
+  if (state.marketing) {
+    // …
+  }
+});
 ```
 
-For a full staging checklist (banner, strict mode, admin, optional logging, Google), see **[TESTING.md](./TESTING.md)**.
+Do not read `emprivacy_cc` yourself. The JSON shape can change with a major release.
 
 ---
 
@@ -122,19 +131,18 @@ For a full staging checklist (banner, strict mode, admin, optional logging, Goog
 
 | 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 |
+| Nothing appears | Layout missing head/body components; plugin not in `plugins: []`; server not restarted |
+| Scripts load before consent | Theme still contains tracker snippets; another plugin is listed **before** EmPrivacy and injects tags immediately |
+| YouTube still loads immediately | Embeds plugin is registered **after** EmPrivacy, so its renderers win. Move EmPrivacy last or pass `blockComponents` on `PortableText`. |
+| Embeds stay blocked after accept | Category is Marketing but you only enabled Functional (or the reverse). |
+| Save fails on policy URL | Must be `/path` or `https://…` |
+| Save fails on analytics ID | Plausible wants `example.com` (no scheme). GA4 wants `G-…`. GTM wants `GTM-…`. Umami needs an https script URL. |
+| Privacy link 404 | Path must match the live Page route |
 
 ---
 
 ## 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
+- Main **[README](../README.md)** — does / does not, disclaimer, API
+- **[PLUGIN_SETTINGS.md](./PLUGIN_SETTINGS.md)** — every admin field
+- **[TESTING.md](./TESTING.md)** — staging QA

package/docs/PLUGIN_SETTINGS.md

@@ -2,63 +2,57 @@
 
 # EmPrivacy — Plugin settings reference
 
-This page documents every field on the **EmPrivacy** admin settings page (shield icon → **EmPrivacy**).
+Every field on **EmPrivacy** (shield → **EmPrivacy**) in the EmDash admin.
 
-It’s written for site owners and maintainers who want to understand:
+EmPrivacy is a technical consent tool, not legal advice. You are responsible for matching categories and vendors to your privacy/cookie policies.
 
-- What each setting **does**
-- What input format is expected (with **examples**)
-- What public-site behavior changes when you change it
+---
+
+## Plugin version
+
+- **Installed version**: the release running on this site
+- **Latest on npm**: current [`@emplugins/emprivacy`](https://www.npmjs.com/package/@emplugins/emprivacy)
 
-> 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.
+The rest of the page still loads if npm cannot be reached.
 
 ---
 
-## Banner settings
+## Banner copy and language
 
-### Banner title
+### Banner title / Short notice (fallback locale)
 
-- **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).
+Visible heading and body. Applied with `textContent` only (no HTML). Max 120 / 600 characters.
 
-### Short notice
+### Fallback locale code
 
-- **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).
+Used when the page has no locale or no built-in chrome pack. Example: `en`. Button labels ship for `en`, `de`, `fr`, `es`, `it`, `nl`, `pt`, `pl` (including `pt-BR` → `pt`).
 
----
+### Optional title/message translations (JSON)
+
+```json
+{
+  "de": {
+    "bannerTitle": "Cookies & Datenschutz",
+    "bannerMessage": "Wir verwenden Cookies, um die Website zu betreiben."
+  }
+}
+```
 
-## Policy links (shown in the banner)
+Keys must look like `en` or `pt-BR`. At most 32 locales. Invalid JSON is rejected on save.
 
-These links are rendered as “Privacy policy” (and optionally “Cookie policy”) in the banner and reopen panel.
+---
+
+## Policy links
 
 ### 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.
+Required. `/privacy` or `https://example.com/privacy`. Not `http://`, not `example.com/privacy`, not `//…`.
+
+### Cookie policy (optional)
+
+Same rules. Blank = no extra link.
+
+Paths are resolved with EmDash `ctx.url()` so they stay correct across environments.
 
 ---
 
@@ -66,116 +60,126 @@ These links are rendered as “Privacy policy” (and optionally “Cookie polic
 
 ### 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.
+Stored in the cookie as `v`. Change it when legal text or vendors change so returning visitors are asked again.
+
+The cookie is JSON `{ v, f, a, m }`. Cookies from older EmPrivacy releases that omit `f` are treated as missing, so the banner shows once after you upgrade.
 
 ---
 
 ## Defaults and consent UX
 
-### Strict defaults (require opt-in for analytics & marketing)
+### Strict defaults
+
+On: Functional, Analytics, and Marketing start **unchecked**. Off: they start **checked** (opt-out style). Stored choices always win after the first save.
+
+### Hide the first-visit banner on privacy and cookie policy pages
 
-- **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.
+On (default): visitors who open `/privacy` from the banner can read it without another overlay. The cookie button still appears so they can change choices.
 
 ---
 
-## Analytics settings
+## Analytics platform
+
+Scripts for **Analytics** presets load only after **Analytics** consent — except **Google Tag Manager**, which loads only after **Marketing** consent (containers commonly fire ads and remarketing).
+
+| Value | What you enter | What loads |
+|-------|----------------|------------|
+| Cloudflare Web Analytics | Site token | `beacon.min.js` + `data-cf-beacon` |
+| Plausible | Hostname `example.com` (no `https://`) | `https://plausible.io/js/script.js` with `data-domain` |
+| Fathom | Site ID (letters/digits) | `https://cdn.usefathom.com/script.js` with `data-site` |
+| Umami | Website ID **and** https script URL | Your tracker URL with `data-website-id` |
+| Simple Analytics | Optional hostname | `https://scripts.simpleanalyticscdn.com/latest.js` |
+| Google Analytics 4 | `G-…` measurement ID | `https://www.googletagmanager.com/gtag/js?id=…` then `gtag('config', …)` |
+| Google Tag Manager | `GTM-…` | `https://www.googletagmanager.com/gtm.js?id=…` after **Marketing** consent. Tags inside the container are still your responsibility. |
+| None | — | No analytics scripts |
+| Custom | One https script `src` per line (optional trailing SRI) | Those URLs only |
+
+IDs and URLs are validated on save and again in the browser before inject. Tokens are never shown in the public vendor list.
+
+### Script host allowlist (optional)
+
+One hostname per line (e.g. `cdn.example.com`). When non-empty, **Custom** analytics, **Umami**, and **Marketing** script hosts must appear on the list. Built-in preset CDNs (Plausible, Fathom, GTM, etc.) stay allowed for their presets.
+
+### Optional Subresource Integrity (SRI)
 
-Analytics scripts only load after the visitor consents to **Analytics** (unless you hard-code scripts elsewhere in your site/theme, which you should avoid).
+Append a hash after the URL on Custom or Marketing lines:
 
-### Analytics platform
+```
+https://cdn.example/a.js sha384-…
+https://cdn.example/b.js integrity=sha256-…
+```
 
-- **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).
+The browser sets `integrity` + `crossorigin=anonymous` when the hash is valid. Prefer pinning Custom scripts; many preset CDNs do not publish stable hashes.
 
-### Cloudflare Web Analytics site token
+---
+
+## Marketing scripts
 
-- **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.
+One **https** URL per line, `src` only (optional SRI as above). Loaded after **Marketing** consent. Max 50 lines, 2048 characters each. No HTML.
 
-### 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**:
+## Google Consent Mode v2
 
-  ```text
-  https://cdn.example.com/analytics.js
-  https://static.example.net/vendor/tracker.min.js
-  ```
+When enabled, a denied-by-default snippet runs in `<head>` (`analytics_storage`, `ad_*`, `functionality_storage`, `personalization_storage`). After a choice, EmPrivacy calls `gtag('consent','update', …)`. `security_storage` stays granted. Validate with [Google’s docs](https://support.google.com/tagmanager/answer/13695607).
 
-- **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.
+Put EmPrivacy **first** in `plugins` if other plugins also inject Google tags.
 
 ---
 
-## Marketing settings
+## Embeds
+
+### Gate official EmDash embed blocks
+
+When on (default), EmPrivacy’s Portable Text components replace YouTube, Vimeo, tweet, Bluesky, Mastodon, Gist, and link-preview blocks with a placeholder until the selected category is allowed.
 
-Marketing scripts only load after the visitor consents to **Marketing**.
+YouTube / Vimeo become allowlisted iframes (`youtube-nocookie.com`, `player.vimeo.com`). Social posts, Gists, and link previews become **https links** — EmPrivacy will not iframe an arbitrary Mastodon or unknown host.
 
-### Marketing script URLs (one https URL per line, not a `<script>` tag)
+This does **not** rewrite raw HTML `<iframe>` tags you paste in the theme or in an HTML block.
 
-- **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**:
+### Embeds require this category
 
-  ```text
-  https://cdn.example.com/pixel.js
-  https://static.example.net/ads/retargeting.js
-  ```
+**Marketing** (default) or **Functional**. Pick Marketing for YouTube/social if those vendors set advertising cookies.
 
-- **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.
+**Allow embeds and load** opens the cookie preferences panel with a short hint. It does **not** silently grant Functional or Marketing.
+
+Registration order: see [GETTING_STARTED](./GETTING_STARTED.md#registration-order).
 
 ---
 
-## Google integrations (optional)
+## Consent cookie lifetime
+
+### Consent cookie lifetime (days)
+
+`Max-Age` for `emprivacy_cc`, **1–365**, default **180**. Keep this aligned with how long you need to remember a choice under your policy.
+
+---
 
-### Google Consent Mode v2 (denied defaults in head; updates after choice)
+## Theme
 
-- **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.
+Hex colors only (`#111`, `#111111`). Corner radius is an integer **0–24**. Values become CSS variables on `#emprivacy-root`. Other CSS is ignored (no `url()`, no `expression`).
 
 ---
 
-## Server-side logging (optional)
+## Server-side logging
 
-### Log consent choices to the server (minimal record; no IP stored)
+When enabled, each save POSTs `{ policyVersion, functional, analytics, marketing }` to `/_emdash/api/plugins/emprivacy/record` (same origin, JSON). The handler requires a matching `Origin` **or** `Sec-Fetch-Site: same-origin`, fails closed if storage capacity cannot be checked, and rate-limits anonymous clients (~30/hour fingerprint). No IP is stored in the consent row. The page shows up to 15 recent rows. Logging stops at 500 rows.
+
+---
+
+## Content Security Policy
+
+EmPrivacy injects an **inline** bootstrap via EmDash `page:fragments`. Sites with a strict CSP must allow that script, typically:
+
+- `script-src 'unsafe-inline'` (or a hash/nonce of the emitted bootstrap if your host supports it), and
+- `script-src` / `connect-src` / `frame-src` entries for any presets and gated embeds you enable (e.g. `https://plausible.io`, `https://www.youtube-nocookie.com`, `https://player.vimeo.com`).
+
+YouTube/Vimeo placeholders use a tight iframe `sandbox` (`allow-scripts allow-same-origin allow-presentation`) after consent. Client hydration also re-checks allowlisted `data-src` values so a planted evil URL cannot become an iframe.
+
+A future hashed static bootstrap (no `'unsafe-inline'`) depends on EmDash fragment APIs exposing nonces or external script URLs.
+
+---
 
-- **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.
+## What this site uses
 
+Read-only table generated from the saved config. Same data as `GET /_emdash/api/plugins/emprivacy/vendors`. Use it in your cookie policy. It never includes tokens or measurement IDs.

package/docs/RELEASE_NOTES.md

@@ -2,26 +2,24 @@
 
 # Unreleased
 
-# @emplugins/emprivacy v1.0.0 (pending Version Packages)
+## Changes
 
-## Breaking
+_(none)_
 
-- **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).
+# emprivacy v2.1.0
 
-## Unchanged
+## Changes
 
-- Runtime plugin id `emprivacy`, cookie `emprivacy_cc`, and API routes.
-- Source repository: [EmPlugins/EmPrivacy](https://github.com/EmPlugins/EmPrivacy).
+- **Publisher consent features** — Functional category (`f` in `emprivacy_cc`; older cookies without `f` re-prompt), `window.emprivacy` API, gated official EmDash embed placeholders (`@emplugins/emprivacy/astro`), banner i18n + hex theme tokens, analytics presets (Plausible, Fathom, Umami, Simple Analytics, GA4, GTM), generated vendor list (admin + public `/vendors` route). Cookie JSON is now `{ v, f, a, m }`. Admin shows installed vs latest npm version.
+- **Security hardening** — Client re-validates embed `data-src` and script URLs before inject; tighter YouTube/Vimeo iframe `sandbox`; GTM loads under **Marketing**; optional script host allowlist + SRI on Custom/Marketing URLs; configurable consent cookie TTL (default 180 days); soft-consent opens preferences instead of silently granting; `/record` requires Origin or `Sec-Fetch-Site: same-origin`, fails closed on storage errors, and rate-limits writes. CSP notes in [PLUGIN_SETTINGS](./PLUGIN_SETTINGS.md#content-security-policy).
 
-# emprivacy v0.3.0
+# emprivacy v2.0.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)).
+- Compatibility: targets **EmDash `^0.38.0`** (tested with **`0.38.0`**); Node.js **`>= 22.16`**.
+- **Native plugin** — Switched from standard/sandbox entry packaging to EmDash’s native contract: `format: "native"`, named **`createPlugin()`** export, single-argument **`RouteContext`** route handlers, and no `./sandbox` export. Register **`emprivacyPlugin()`** from **`@emplugins/emprivacy`** in **`plugins: []`** (required for `page:fragments`).
+- Docs/README updated for scoped package install, `import emdash from "emdash/astro"`, layout page context, and native trust boundary.
 
 # emprivacy v0.2.1