@emplugins/emprivacy 2.0.0 → 3.0.0

package/README.md

@@ -2,13 +2,34 @@
 ![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.38.0` (**tested with `0.38.0`**; re-test on your deployed minor when upgrading).
+- **EmDash** `^1.0.1` (**tested with `1.0.1`**). EmDash 0.x is not supported.
 - **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 scripts; that hook only runs for trusted in-process plugins. See [Page fragments](https://docs.emdashcms.com/plugins/creating-native-plugins/page-fragments/) and [Plugin overview](https://docs.emdashcms.com/plugins/overview/).
+- 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
 
@@ -20,13 +41,13 @@ 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). 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: [docs/RELEASES.md](docs/RELEASES.md). Org publish: [docs/NPM_ORG_PUBLISH.md](docs/NPM_ORG_PUBLISH.md).
+Use a **semver range** if you want controlled upgrades, for example `@emplugins/emprivacy@^3.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";
@@ -36,7 +57,10 @@ The legacy unscoped package `emprivacy` is deprecated; migrate imports to `@empl
    export default defineConfig({
      integrations: [
        emdash({
-         plugins: [emprivacyPlugin()],
+         plugins: [
+           emprivacyPlugin(),
+           // other native plugins…
+         ],
        }),
      ],
    });
@@ -44,29 +68,61 @@ The legacy unscoped package `emprivacy` is deprecated; migrate imports to `@empl
 
    Native descriptors belong in `plugins`, not `sandboxed`. EmDash loads the named `createPlugin()` export from the package at runtime.
 
-2. **Use EmDash page integration** in your layout so fragments render: include `<EmDashHead />`, `<EmDashBodyStart />`, `<EmDashBodyEnd />` (or your theme’s equivalents), typically with a shared `createPublicPageContext({ Astro, … })`. See [EmDash page fragments](https://docs.emdashcms.com/plugins/creating-native-plugins/page-fragments/).
+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
 
@@ -80,15 +136,18 @@ Settings, KV, and declared plugin storage need no extra capability. Native plugi
 
 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
 
@@ -100,7 +159,7 @@ pnpm test            # Unit tests (see Testing)
 pnpm run test:watch  # Vitest in watch mode (optional)
 ```
 
-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()`).
+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: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
 
@@ -110,45 +169,32 @@ Dependency, audit, and deprecation context: [docs/DEVELOPMENT.md](docs/DEVELOPME
 
 | 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)
-
-Details: [docs/TESTING.md](docs/TESTING.md).
+Validate on a **real EmDash site** (staging) at the EmDash version you deploy.
 
-- [ ] `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))
-- [ ] Native `plugins: []` registration (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.2.1`). See [docs/RELEASES.md](docs/RELEASES.md) for bump rules, `npm version` / `npm run release:*`, and publish checklist.
+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,25 +1,99 @@
-import * as emdash from "emdash";
 import { PluginDescriptor } from "emdash";
-
 //#region src/runtime.d.ts
-/**
- * Native EmDash runtime — loaded via the named `createPlugin` export.
- * Uses `page:fragments`, which requires trusted in-process (native) execution.
- */
-declare function createPlugin(): emdash.ResolvedPlugin<{
+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
-/**
- * EmPrivacy KV document (`consent:config`) and shared helpers.
- */
-declare const KV_KEY: "consent:config";
-declare const COOKIE_NAME: "emprivacy_cc";
-/** How analytics scripts are chosen after the user consents to analytics. */
-type AnalyticsProvider = "cloudflare" | "none" | "custom";
+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;
@@ -30,7 +104,7 @@ interface EmprivacyConfig {
   privacyPolicyUrl: string;
   /** Optional cookie policy: same rules as `privacyPolicyUrl` (https URL or path like `/cookies`) */
   cookiePolicyUrl: string;
-  /** When true, analytics/marketing require explicit opt-in in the UI */
+  /** 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;
@@ -39,49 +113,150 @@ interface EmprivacyConfig {
    * Public in the same way as a normal site embed. Empty means no Cloudflare script until a token is saved.
    */
   cloudflareWebAnalyticsToken: string;
-  /**
-   * Which analytics load path to use after consent. `cloudflare` = beacon + `cloudflareWebAnalyticsToken`;
-   * `custom` = `analyticsScriptUrls` only; `none` = no third-party analytics scripts.
-   */
   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;
 }
-declare const DEFAULT_CONFIG: EmprivacyConfig;
+export declare const DEFAULT_CONFIG: EmprivacyConfig;
 /** Reject characters that would break JSON or attributes; allow typical Cloudflare site token strings. */
-declare function assertValidCloudflareToken(t: string): void;
+export declare function assertValidCloudflareToken(t: string): void;
 /**
  * Root-relative public path (EmDash page route), e.g. `/privacy`.
  * Rejects protocol-relative URLs (`//…`) and whitespace.
  */
-declare function isRootRelativeSitePath(s: string): boolean;
+export declare function isRootRelativeSitePath(s: string): boolean;
 /** For hooks: turn stored path or absolute URL into a public absolute URL. */
-declare function resolvePolicyHref(stored: string, ctx: {
+export declare function resolvePolicyHref(stored: string, ctx: {
   url: (path: string) => string;
 }): string;
-declare function isValidPolicyHrefInput(s: string): boolean;
-declare function normalizeConfig(raw: unknown): EmprivacyConfig;
+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 native plugin descriptor — add to `plugins: []` in `emdash({ ... })` inside `astro.config`.
  *
- * EmPrivacy uses `page:fragments` (banner + consent scripts), which only runs for **native**
- * plugins registered in `plugins: []`. Do not place this descriptor in `sandboxed: []`.
- * See [Page fragments](https://docs.emdashcms.com/plugins/creating-native-plugins/page-fragments/).
+ * 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, createPlugin, createPlugin as default, 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 };