@emplugins/emprivacy 1.0.0 → 2.1.0

package/README.md

@@ -2,95 +2,166 @@
 ![EmPrivacy Logo](./artwork/logo/EmPrivacy.png)
 # EmPrivacy
 
-**EmPrivacy** is an open source [EmDash](https://github.com/emdash-cms/emdash) plugin that adds a cookie consent banner, category-based choices (essential / analytics / marketing), and **client-side** loading of third-party scripts only after consent. It aligns with common regulatory expectations when you configure it honestly and pair it with proper legal documents—but **this software is not legal advice** (see [Disclaimer](#legal-disclaimer)).
+**EmPrivacy** is an open source [EmDash](https://github.com/emdash-cms/emdash) plugin that adds a cookie consent banner, category-based choices (essential / functional / analytics / marketing), **client-side** loading of configured third-party scripts only after consent, and optional placeholders for official EmDash embed blocks. It aligns with common regulatory expectations when you configure it honestly and pair it with proper legal documents—but **this software is not legal advice** (see [Disclaimer](#legal-disclaimer)).
+
+## What it does
+
+- Shows a first-visit banner (and a reopen control) with **Accept all**, **Reject non-essential**, and **Customize**.
+- Stores choices in the first-party `emprivacy_cc` cookie as `{ v, f, a, m }` (policy version, functional, analytics, marketing).
+- Loads **only the analytics and marketing scripts you configure** after the matching category is allowed.
+- Optionally replaces official EmDash embed blocks (YouTube, Vimeo, X, Bluesky, Mastodon, Gist, link preview) with a placeholder until the chosen category is allowed.
+- Exposes `window.emprivacy` so themes and other plugins can read consent without parsing the cookie.
+- Builds a **vendor list** from your settings (admin + `GET /_emdash/api/plugins/emprivacy/vendors`).
+- Localizes banner chrome for `en`, `de`, `fr`, `es`, `it`, `nl`, `pt`, and `pl`, with optional JSON overrides for title and message.
+- Lets you theme the banner with hex CSS variables.
+
+## What it does not do
+
+- **Does not write or generate a privacy policy, cookie policy, or DPA.** You create those as EmDash Pages (or host them elsewhere) and paste the path or `https` URL.
+- **Does not scan the theme** for leftover `gtag`, pixels, or iframes you pasted yourself. Scripts and iframes outside EmPrivacy still load.
+- **Does not geo-locate visitors** or switch EU/US banners automatically.
+- **Does not block first-party EmDash comments**, sessions, or other essential site cookies.
+- **Does not iframe arbitrary hosts.** Mastodon, Gist, Bluesky, X, and link-preview blocks become **https links** (or a YouTube/Vimeo iframe from an allowlisted player host) after consent.
+- **Is not a sandbox.** It is a **native** plugin (`plugins: []`) and runs with the same trust as your site code.
+- **Is not legal advice** and does not certify GDPR/CCPA/CIPA compliance.
 
 ## Requirements
 
-- **EmDash** `>=0.14.0` (**tested with `0.14.0` and `0.29.0`**; see [EMDASH_COMPAT.md](./EMDASH_COMPAT.md)). Sites on EmDash 0.9–0.13: use **emprivacy 0.2.x**.
-- Plugins registered in **`astro.config`** in **trusted** mode (the `plugins: []` array).  
-  **Sandboxed** marketplace plugins **cannot** use `page:fragments`; EmPrivacy needs the `hooks.page-fragments:register` capability so head/body contributions run on public pages. See [Plugin System Overview](https://docs.emdashcms.com/plugins/overview/).
+- **EmDash** `^0.38.0` (**tested with `0.38.0`**; re-test on your deployed minor when upgrading).
+- **Node.js** `>= 22.16` (matches EmDash’s engine requirement).
+- Register as a **native** plugin in **`astro.config`** via `plugins: []` (not `sandboxed: []`). EmPrivacy uses `page:fragments` for the public banner and `componentsEntry` for embed placeholders. See [Page fragments](https://docs.emdashcms.com/plugins/creating-native-plugins/page-fragments/) and [Plugin overview](https://docs.emdashcms.com/plugins/overview/).
 
 ## Install
 
 ```bash
+pnpm add @emplugins/emprivacy
+# or
 npm install @emplugins/emprivacy
 ```
 
-Published under the [emplugins](https://www.npmjs.com/org/emplugins) npm org. Source: [github.com/EmPlugins/EmPrivacy](https://github.com/EmPlugins/EmPrivacy).
+Published under the [emplugins](https://www.npmjs.com/org/emplugins) npm org. Source: [github.com/EmPlugins/EmPrivacy](https://github.com/EmPlugins/EmPrivacy). See [EMDASH_COMPAT.md](./EMDASH_COMPAT.md) for EmDash version mapping.
 
-Use a **semver range** if you want controlled upgrades, for example `@emplugins/emprivacy@^1.0.0`. Versioning policy and maintainer release steps: [docs/RELEASES.md](docs/RELEASES.md). Org publish / `NPM_TOKEN` setup: [docs/NPM_ORG_PUBLISH.md](docs/NPM_ORG_PUBLISH.md).
+Use a **semver range** if you want controlled upgrades, for example `@emplugins/emprivacy@^1.0.0`. Versioning: [docs/RELEASES.md](docs/RELEASES.md). Org publish: [docs/NPM_ORG_PUBLISH.md](docs/NPM_ORG_PUBLISH.md).
 
 The legacy unscoped package `emprivacy` is deprecated; migrate imports to `@emplugins/emprivacy`.
 
-## Quick start
+## Quick start (site managers)
 
-1. **Register the plugin** in `astro.config.mjs` (or `.ts`) **before** other plugins that inject marketing or analytics, so consent runs first:
+1. **Register the plugin** in `astro.config.mjs` (or `.ts`):
 
    ```ts
    import { defineConfig } from "astro/config";
-   import { emdash } from "emdash/astro";
+   import emdash from "emdash/astro";
    import { emprivacyPlugin } from "@emplugins/emprivacy";
 
    export default defineConfig({
      integrations: [
        emdash({
-         plugins: [emprivacyPlugin()],
+         plugins: [
+           emprivacyPlugin(),
+           // other native plugins…
+         ],
        }),
      ],
    });
    ```
 
-2. **Use EmDash page integration** in your layout so fragments render: include `<EmDashHead />`, `<EmDashBodyStart />`, `<EmDashBodyEnd />` (or your theme’s equivalents). See [EmDash docs](https://docs.emdashcms.com/).
+   Native descriptors belong in `plugins`, not `sandboxed`. EmDash loads the named `createPlugin()` export from the package at runtime.
+
+2. **Put EmPrivacy first** when other plugins inject `gtag` / analytics in `<head>` (Google Consent Mode must run first).
+
+3. **Put EmPrivacy last** when you want automatic YouTube/Vimeo placeholders (later `blockComponents` win). If you need **both** Consent Mode-first **and** gated embeds, keep EmPrivacy first and pass the wrappers on your Portable Text renderer:
+
+   ```ts
+   import { PortableText } from "emdash/ui";
+   import { blockComponents as emprivacyEmbeds } from "@emplugins/emprivacy/astro";
+   ```
+
+   ```astro
+   <PortableText value={entry.data.content} components={{ type: emprivacyEmbeds }} />
+   ```
+
+   Site-level `components` always win over every plugin.
 
-3. **Configure EmPrivacy in the admin** (shield → **EmPrivacy**):
-   - **Privacy policy** — Point to your existing EmDash **Page** using its **public path** (what you see in the address bar when that Page is open, e.g. `/privacy`), **or** a full `https://…` URL if the policy is hosted elsewhere. Root-relative paths are resolved with EmDash `ctx.url()` so links stay correct across environments.
-   - **Cookie policy** (optional) — Same rules: EmDash Page path or `https://…`.
-   - Set banner copy, **Policy / consent version**, **Analytics** (Cloudflare site token, **None**, or **Custom** `https` URLs), and **Marketing** script URLs (`https`, one per line). See [GETTING_STARTED](docs/GETTING_STARTED.md#step-5--configure-emprivacy-in-the-admin).
+4. **Use EmDash page integration** in your layout: `<EmDashHead />`, `<EmDashBodyStart />`, `<EmDashBodyEnd />` with `createPublicPageContext({ Astro, … })`.
 
-See [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) for a step-by-step path from “create a Page” to “verify the link in the banner.”
+5. **Create a Privacy Policy Page** (and optional Cookie Policy Page) in EmDash, then in admin (shield → **EmPrivacy**) set the public path (`/privacy`) or an `https://` URL.
 
-Visitors see a banner on first visit (or when you bump **Policy / consent version**). Configured analytics (e.g. Cloudflare beacon) and marketing scripts load only **after** the user consents to the matching category.
+6. Pick an analytics preset (Cloudflare, Plausible, Fathom, Umami, Simple Analytics, GA4, GTM, None, or Custom), optional marketing script URLs, and **Save**.
+
+Visitors see a banner on first visit, when **Policy / consent version** changes, or when an older cookie is missing the functional flag (`f`). Existing `{ v, a, m }` cookies are treated as expired so visitors choose the new category.
+
+## Public JavaScript API
+
+After the banner script runs:
+
+```ts
+window.emprivacy.get();
+// { v, essential: true, functional, analytics, marketing } | null
+
+window.emprivacy.has("analytics"); // boolean
+window.emprivacy.open();           // reopen the panel
+const stop = window.emprivacy.onChange((state) => { /* … */ });
+stop();
+```
+
+`document` also receives `emprivacy:change` with the same state in `event.detail`. Other plugins should gate their own scripts with this API instead of adding a second banner.
 
 ## Features
 
 | Feature | Description |
 |--------|-------------|
-| Categories | Essential (informational), **Analytics**, **Marketing** |
-| Privacy / cookie links | EmDash **Page** as a root path (e.g. `/privacy`) or external `https://` URL; paths resolve via `ctx.url()` in hooks so public URLs stay correct when the site origin changes |
-| Analytics platforms | **Cloudflare Web Analytics** — enter your site token; the beacon is injected with `data-cf-beacon` after consent. **None** / **Custom** (`https` URLs) also supported; more platforms can be added over time |
-| Marketing scripts | Only **https** URLs you list are injected as `<script src>` after marketing consent—no arbitrary admin HTML |
-| Re-open preferences | After the first choice, a **cookie button** (bottom-left) re-opens the same options; saving from that panel **reloads** the page so script loading matches the latest consent (including revoking) |
-| Consent cookie | `emprivacy_cc` (`path=/`, `SameSite=Lax`, `Secure` on HTTPS), JSON `{ v, a, m }` (version, analytics, marketing) |
-| Optional server log | POST consent snapshots to `/_emdash/api/plugins/emprivacy/record` + optional storage rows (no IP in v1) |
-| Google Consent Mode v2 | Optional denied defaults in `<head>` + `gtag('consent','update',…)` — validate with [Google’s docs](https://support.google.com/tagmanager/answer/13695607) |
+| Categories | Essential (always on), **Functional**, **Analytics**, **Marketing** |
+| Privacy / cookie links | EmDash **Page** path or `https://` URL; resolved with `ctx.url()` |
+| Analytics presets | Cloudflare Web Analytics, Plausible, Fathom, Umami, Simple Analytics, GA4, **GTM (Marketing)**, None, Custom `https` URLs (+ optional SRI / host allowlist) |
+| Marketing scripts | Only **https** URLs you list, injected as `<script src>` after marketing consent |
+| Official embeds | Optional placeholders for `@emdash-cms/plugin-embeds` block types; YouTube/Vimeo use allowlisted player URLs (`youtube-nocookie`, `player.vimeo.com`); client re-checks URLs before mount |
+| Re-open preferences | Cookie button (bottom-left); saving reloads so script loading matches the latest choice |
+| Consent cookie | `emprivacy_cc` (`path=/`, `SameSite=Lax`, `Secure` on HTTPS, configurable `Max-Age`, default 180 days), JSON `{ v, f, a, m }` |
+| Vendor list | Derived from settings; shown under Customize; JSON at `/_emdash/api/plugins/emprivacy/vendors` (no tokens) |
+| Optional server log | POST `{ policyVersion, functional, analytics, marketing }` to `/_emdash/api/plugins/emprivacy/record` (Origin / Sec-Fetch-Site, rate-limited, no IP) |
+| Google Consent Mode v2 | Optional denied defaults in `<head>` + `gtag('consent','update',…)` including `functionality_storage` |
+| i18n | Built-in chrome for common locales; optional JSON title/message overrides |
+| Theme | Hex CSS variables (`--emprivacy-bg`, `--emprivacy-text`, `--emprivacy-accent`, `--emprivacy-radius`) |
+
+## Capabilities
+
+| Capability | Why |
+|------------|-----|
+| `hooks.page-fragments:register` | Public banner, styles, and consent bootstrap scripts |
+
+Settings, KV, and declared plugin storage need no extra capability. Native plugins are not an isolation boundary: review and install this package like first-party site code.
 
 ## Legal disclaimer
 
 EmPrivacy helps you implement **technical** consent UX and script loading patterns used for regulations such as **GDPR** and **CCPA/CIPA**. **You** remain responsible for:
 
-- Privacy notices, cookie policies, and lawful bases  
-- What data your analytics/marketing vendors collect  
-- Whether your configuration meets obligations in your jurisdictions  
+- Privacy notices, cookie policies, and lawful bases
+- What data your analytics/marketing vendors collect
+- Whether your configuration meets obligations in your jurisdictions
+- Any scripts, pixels, or iframes you add outside this plugin
 
 **This project does not provide legal advice.** If you need certainty, consult a qualified attorney or privacy professional.
 
 ## Registration order
 
-Put **`emprivacyPlugin()` early** in the `plugins` array so `page:metadata` / `page:fragments` run before other plugins that add trackers or metadata.
+- **Consent Mode / other head scripts:** `emprivacyPlugin()` **first** in `plugins`.
+- **Automatic embed placeholders:** `emprivacyPlugin()` **after** `@emdash-cms/plugin-embeds`.
+- **Both:** EmPrivacy first + site-level `PortableText` `components` (see Quick start).
 
 ## Development
 
 ```bash
-npm install
-npm run typecheck   # TypeScript
-npm run build       # ESM + types in dist/
-npm test            # Unit tests (see Testing)
-npm run test:watch  # Vitest in watch mode (optional)
+pnpm install
+pnpm run typecheck   # TypeScript
+pnpm run build       # ESM + types in dist/
+pnpm test            # Unit tests (see Testing)
+pnpm run test:watch  # Vitest in watch mode (optional)
 ```
 
-Outputs ESM under `dist/` with typings, matching the [plugin layout](https://www.npmjs.com/package/@emdash-cms/plugin-audit-log) used by other EmDash packages.
+Outputs ESM under `dist/` with typings. Layout follows EmDash’s [native plugin packaging](https://docs.emdashcms.com/plugins/creating-native-plugins/distributing/) (`emprivacyPlugin()` descriptor + named `createPlugin()`, plus `./astro` for Portable Text).
 
-Dependency, audit, and deprecation context (Kysely override, `npm audit`): [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
+Dependency, audit, and deprecation context: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
 
 ## Testing
 
@@ -98,47 +169,32 @@ Dependency, audit, and deprecation context (Kysely override, `npm audit`): [docs
 
 | Command | Purpose |
 |---------|---------|
-| `npm run typecheck` | Types against `emdash` and this package |
-| `npm run build` | `tsdown` → `dist/` and `exports` |
-| `npm test` | [Vitest](https://vitest.dev/) tests for `src/config.ts`: URL lists, `normalizeConfig`, policy **path vs https** validation, `resolvePolicyHref`, `jsonForHtmlScript` |
+| `pnpm run typecheck` | Types against `emdash` and this package |
+| `pnpm run build` | `tsdown` → `dist/` and `exports` |
+| `pnpm test` | Vitest: config validation, embed URL allowlists, i18n, vendors, JSON escaping |
 
 Automation does **not** start EmDash or a browser; it guards packaging and validation logic.
 
 **Suggested CI:**
 
 ```bash
-npm ci
-npm run typecheck
-npm run build
-npm test
+pnpm install --frozen-lockfile
+pnpm run typecheck
+pnpm run build
+pnpm test
 ```
 
 ### Staging / manual (before production)
 
-EmPrivacy uses EmDash KV, admin Block Kit, `page:fragments`, and plugin routes. Validate on a **real EmDash site** (staging) at the EmDash version you deploy.
-
-- **[docs/TESTING.md](docs/TESTING.md)** — Full pre-deploy checklist, flows to exercise, limits of automation.  
-- **No E2E in this repo** — nothing here launches EmDash or drives a browser.
-
-### Acceptance checklist (manual QA)
+Validate on a **real EmDash site** (staging) at the EmDash version you deploy.
 
-Details: [docs/TESTING.md](docs/TESTING.md).
-
-- [ ] `typecheck`, `build`, and `npm test` pass
-- [ ] Banner when no cookie or **Policy / consent version** mismatch
-- [ ] **Privacy (and cookie) links** open the right EmDash Page or external URL; paths match what you see in the browser for that Page
-- [ ] Strict mode: no analytics/marketing scripts until consent (Network tab)
-- [ ] Cookie persists; bumping policy version shows the banner again
-- [ ] Admin save updates the public banner
-- [ ] Optional: server logging + recent records in admin
-- [ ] Optional: Google Consent Mode (Tag Assistant / [Google](https://support.google.com/tagmanager/answer/13695607))
-- [ ] **Trusted** `plugins: []` (see [Requirements](#requirements))
+- **[docs/TESTING.md](docs/TESTING.md)** — Full pre-deploy checklist.
+- **[docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)** — Install and configure as a site manager.
+- **[docs/PLUGIN_SETTINGS.md](docs/PLUGIN_SETTINGS.md)** — Every admin field.
 
 ## Releases
 
-npm releases follow **[Semantic Versioning](https://semver.org/)** (`MAJOR.MINOR.PATCH`). Tags are `v`-prefixed (e.g. `v0.1.0`). See [docs/RELEASES.md](docs/RELEASES.md).
-
-**EmDash upgrades:** say `update to latest emdash release` in Cursor (skill: [`.cursor/skills/emdash-release`](.cursor/skills/emdash-release/SKILL.md)) to bump, test, and publish to npm + GitHub without a manual merge gate.
+npm releases follow **[Semantic Versioning](https://semver.org/)** (`MAJOR.MINOR.PATCH`). Tags are `v`-prefixed (e.g. `v1.0.0`). See [docs/RELEASES.md](docs/RELEASES.md).
 
 ## License
 

package/dist/index.d.mts

@@ -1,11 +1,262 @@
-import { a as EmprivacyConfig, c as isRootRelativeSitePath, d as resolvePolicyHref, i as DEFAULT_CONFIG, l as isValidPolicyHrefInput, n as COOKIE_NAME, o as KV_KEY, r as ConsentRecordPayload, s as assertValidCloudflareToken, t as AnalyticsProvider, u as normalizeConfig } from "./config-CqOtRoQR.mjs";
 import { PluginDescriptor } from "emdash";
-
+//#region src/runtime.d.ts
+export declare function createPlugin(): import("emdash").ResolvedPlugin<{
+  consentEvents: {
+    indexes: string[];
+  };
+}>;
+//#endregion
+//#region src/vendors.d.ts
+type ConsentCategory = "essential" | "functional" | "analytics" | "marketing";
+interface VendorRow {
+  id: string;
+  name: string;
+  category: ConsentCategory;
+  purpose: string;
+  /** First-party docs we control the URL for — never taken from admin HTML */
+  policyUrl?: string;
+}
+type AnalyticsLoader = {
+  type: "none";
+} | {
+  type: "cloudflare";
+  token: string;
+} | {
+  type: "custom";
+  scripts: {
+    src: string;
+    integrity: string | null;
+  }[];
+} | {
+  type: "plausible";
+  src: string;
+  domain: string;
+} | {
+  type: "fathom";
+  src: string;
+  siteId: string;
+} | {
+  type: "umami";
+  src: string;
+  websiteId: string;
+} | {
+  type: "simpleanalytics";
+  src: string;
+} | {
+  type: "ga4";
+  measurementId: string;
+} |
+/** Loaded only after Marketing consent — GTM can fire advertising tags. */
+{
+  type: "gtm";
+  containerId: string;
+};
+export declare function buildAnalyticsLoader(cfg: EmprivacyConfig): AnalyticsLoader;
+export declare function buildVendorList(cfg: EmprivacyConfig): VendorRow[];
+//#endregion
+//#region src/i18n.d.ts
+interface EmprivacyChromeStrings {
+  acceptAll: string;
+  rejectNonEssential: string;
+  customize: string;
+  saveChoices: string;
+  close: string;
+  essential: string;
+  functional: string;
+  analytics: string;
+  marketing: string;
+  essentialNote: string;
+  privacyPolicy: string;
+  cookiePolicy: string;
+  cookieSettings: string;
+  loadEmbed: string;
+  embedBlocked: string;
+  embedNeedConsent: string;
+  vendorsHeading: string;
+  whatWeUse: string;
+}
+interface EmprivacyLocaleCopy {
+  bannerTitle: string;
+  bannerMessage: string;
+}
+type LocaleOverrides = Record<string, Partial<EmprivacyLocaleCopy>>;
+//#endregion
+//#region src/theme.d.ts
+interface EmprivacyTheme {
+  bg: string;
+  text: string;
+  accent: string;
+  radiusPx: number;
+}
+//#endregion
+//#region src/config.d.ts
+export declare const KV_KEY: "consent:config";
+export declare const COOKIE_NAME: "emprivacy_cc";
+type AnalyticsProvider = "cloudflare" | "none" | "custom" | "plausible" | "fathom" | "umami" | "simpleanalytics" | "ga4" | "gtm";
+type EmbedCategory = "functional" | "marketing";
+interface EmprivacyConfig {
+  bannerTitle: string;
+  bannerMessage: string;
+  /**
+   * Privacy policy location: full `https://…` URL **or** a root-relative path to an EmDash **Page**
+   * (e.g. `/privacy`) resolved with `ctx.url()` on the server.
+   */
+  privacyPolicyUrl: string;
+  /** Optional cookie policy: same rules as `privacyPolicyUrl` (https URL or path like `/cookies`) */
+  cookiePolicyUrl: string;
+  /** When true, analytics/marketing/functional require explicit opt-in in the UI */
+  strictDefaults: boolean;
+  /** Bump to invalidate client consent cookies and re-show the banner */
+  policyVersion: string;
+  /**
+   * Analytics when `cloudflare` — **site token** from Cloudflare → Web Analytics (injected with `data-cf-beacon`).
+   * Public in the same way as a normal site embed. Empty means no Cloudflare script until a token is saved.
+   */
+  cloudflareWebAnalyticsToken: string;
+  analyticsProvider: AnalyticsProvider;
+  /** Provider-specific id (domain, site id, G-…, GTM-…). */
+  analyticsId: string;
+  /** Required when `analyticsProvider` is `umami` — https script src only. */
+  umamiScriptUrl: string;
+  /** When `analyticsProvider` is `custom`, these https script URLs load after analytics consent. */
+  analyticsScriptUrls: string[];
+  /** Third-party script URLs loaded only after marketing consent (https only) */
+  marketingScriptUrls: string[];
+  /** Optional SRI hashes keyed by script src (sha256/384/512-…) */
+  scriptIntegrity: Record<string, string>;
+  /**
+   * When non-empty, Custom analytics and marketing script hosts must be on this list.
+   * Preset CDN hosts remain allowed for built-in providers.
+   */
+  scriptHostAllowlist: string[];
+  /** Consent cookie Max-Age in days (1–365, default 180) */
+  cookieMaxAgeDays: number;
+  /** Emit Google Consent Mode v2 defaults (denied) in head; updates after choice */
+  googleConsentMode: boolean;
+  /** POST consent snapshots to the plugin record route and optional storage */
+  logConsentToServer: boolean;
+  /** Category that official embed placeholders require */
+  embedCategory: EmbedCategory;
+  /** When true, EmPrivacy Portable Text components gate official embed blocks */
+  gateEmbeds: boolean;
+  /** Hide the first-visit banner on privacy/cookie policy paths */
+  hideBannerOnPolicyPages: boolean;
+  defaultLocale: string;
+  localeOverrides: LocaleOverrides;
+  theme: EmprivacyTheme;
+}
+export declare const DEFAULT_CONFIG: EmprivacyConfig;
+/** Reject characters that would break JSON or attributes; allow typical Cloudflare site token strings. */
+export declare function assertValidCloudflareToken(t: string): void;
+/**
+ * Root-relative public path (EmDash page route), e.g. `/privacy`.
+ * Rejects protocol-relative URLs (`//…`) and whitespace.
+ */
+export declare function isRootRelativeSitePath(s: string): boolean;
+/** For hooks: turn stored path or absolute URL into a public absolute URL. */
+export declare function resolvePolicyHref(stored: string, ctx: {
+  url: (path: string) => string;
+}): string;
+export declare function isValidPolicyHrefInput(s: string): boolean;
+/** True when the public page is the configured privacy or cookie policy. */
+export declare function isPolicyPagePath(pagePath: string, cfg: Pick<EmprivacyConfig, "privacyPolicyUrl" | "cookiePolicyUrl">): boolean;
+export declare function normalizeConfig(raw: unknown): EmprivacyConfig;
+interface ConsentRecordPayload {
+  createdAt: string;
+  policyVersion: string;
+  functional: boolean;
+  analytics: boolean;
+  marketing: boolean;
+}
+interface ConsentState {
+  v: string;
+  essential: true;
+  functional: boolean;
+  analytics: boolean;
+  marketing: boolean;
+}
+interface VendorPublicRow {
+  id: string;
+  name: string;
+  category: "essential" | "functional" | "analytics" | "marketing";
+  purpose: string;
+  policyUrl?: string;
+}
+interface EmprivacyPublicRuntimeConfig {
+  bannerTitle: string;
+  bannerMessage: string;
+  privacyPolicyUrl: string;
+  cookiePolicyUrl: string;
+  strictDefaults: boolean;
+  policyVersion: string;
+  googleConsentMode: boolean;
+  logConsent: boolean;
+  recordPath: string;
+  embedCategory: EmbedCategory;
+  gateEmbeds: boolean;
+  hideBanner: boolean;
+  theme: EmprivacyTheme;
+  ui: EmprivacyChromeStrings;
+  loader: AnalyticsLoader;
+  marketingScripts: {
+    src: string;
+    integrity: string | null;
+  }[];
+  scriptHostAllowlist: string[];
+  scriptIntegrity: Record<string, string>;
+  cookieMaxAge: number;
+  vendors: VendorPublicRow[];
+}
+//#endregion
+//#region src/public-api.d.ts
+type EmprivacyCategory = "essential" | "functional" | "analytics" | "marketing";
+/**
+ * Public browser API attached to `window.emprivacy`.
+ * Other plugins and themes should use this instead of reading the cookie directly.
+ */
+interface EmprivacyBrowserApi {
+  get(): ConsentState | null;
+  has(category: EmprivacyCategory): boolean;
+  onChange(cb: (state: ConsentState) => void): () => void;
+  open(): void;
+}
+declare global {
+  interface Window {
+    emprivacy?: EmprivacyBrowserApi;
+  }
+}
+//#endregion
+//#region src/astro/embed-resolve.d.ts
+/**
+ * Validate official EmDash embed block payloads and produce a first-party
+ * placeholder plan. Never returns a URL we did not construct or allowlist.
+ */
+export declare const EMBED_BLOCK_TYPES: readonly ["youtube", "vimeo", "tweet", "bluesky", "mastodon", "linkPreview", "gist"];
+type EmbedBlockType = (typeof EMBED_BLOCK_TYPES)[number];
+type EmbedRenderMode = "iframe" | "link";
+interface ResolvedEmbed {
+  kind: EmbedBlockType;
+  mode: EmbedRenderMode;
+  /** https iframe src or link href — always produced by this module */
+  src: string;
+  label: string;
+  poster: string | null;
+}
+export declare function resolveEmbed(node: {
+  _type?: unknown;
+  id?: unknown;
+  poster?: unknown;
+  title?: unknown;
+}): ResolvedEmbed | null;
+//#endregion
 //#region src/index.d.ts
 /**
- * EmDash plugin descriptor — add to `plugins: []` in `emdash({ ... })` inside `astro.config`.
- * Requires **trusted** registration so `page:metadata` / `page:fragments` run (sandboxed plugins cannot inject fragments).
+ * EmDash native plugin descriptor — add to `plugins: []` in `emdash({ ... })` inside `astro.config`.
+ *
+ * EmPrivacy uses `page:fragments` (banner + consent scripts) and optional Portable Text
+ * embed placeholders, which only run for **native** plugins in `plugins: []`.
+ * Do not place this descriptor in `sandboxed: []`.
  */
-declare function emprivacyPlugin(): PluginDescriptor;
+export declare function emprivacyPlugin(): PluginDescriptor;
 //#endregion
-export { type AnalyticsProvider, COOKIE_NAME, type ConsentRecordPayload, DEFAULT_CONFIG, type EmprivacyConfig, KV_KEY, assertValidCloudflareToken, emprivacyPlugin, isRootRelativeSitePath, isValidPolicyHrefInput, normalizeConfig, resolvePolicyHref };
+export { type AnalyticsLoader, type AnalyticsProvider, type ConsentRecordPayload, type ConsentState, type EmbedCategory, type EmprivacyBrowserApi, type EmprivacyCategory, type EmprivacyConfig, type EmprivacyPublicRuntimeConfig, type ResolvedEmbed, type VendorPublicRow, type VendorRow, createPlugin as default };