@c15t/scripts 3.0.0-alpha.1 → 3.0.0-alpha.3

package/docs/frameworks/tanstack-start/network-blocker.md

@@ -0,0 +1,145 @@
+---
+title: Network blocker
+description: Hold fetch and XMLHttpRequest calls in a TanStack Start app until
+  their consent category is allowed, with networkBlocker rules on ConsentRoot.
+group: frameworks
+---
+
+## Add rules
+
+Pass `networkBlocker` rules to `ConsentRoot` to stop `fetch` and
+`XMLHttpRequest` calls to a domain until its category is allowed. Use it as a
+backstop for beacons an SDK sends itself. Load vendor SDKs through
+[`scripts`](./scripts.md) first, so they do not run
+at all before consent.
+
+```tsx title="src/routes/__root.tsx"
+const networkBlocker = {
+	rules: [
+		{
+			id: 'google-analytics',
+			domain: 'google-analytics.com',
+			category: 'measurement',
+		},
+		{
+			id: 'meta-pixel',
+			domain: 'facebook.com',
+			pathIncludes: '/tr',
+			category: 'marketing',
+		},
+	],
+};
+
+<ConsentRoot
+	state={consent}
+	backendURL={backendURL}
+	initRoute={false}
+	scripts={scripts}
+	networkBlocker={networkBlocker}
+>
+```
+
+The blocker runs in the browser only. It does not see requests your server
+functions or server routes make.
+
+## Match requests with rules
+
+Each rule names a `domain` and the consent `category` a request needs. The
+domain also matches its subdomains: `google-analytics.com` covers
+`www.google-analytics.com`. `pathIncludes` narrows the rule to paths that
+contain a substring, and `methods` narrows it to HTTP methods. A request is
+blocked when a matching rule's condition is not met by the visitor's
+effective permissions.
+
+`category` takes the same conditions as scripts:
+
+```ts
+{ category: 'measurement' }
+{ category: { and: ['measurement', 'marketing'] } }
+{ category: { or: ['measurement', 'marketing'] } }
+```
+
+Add `vendor` to also block the request while the visitor has turned that
+vendor off. IAB TCF rules use `vendorId` and the `iab*` purpose fields
+instead.
+
+| Option               | Default  | Purpose                                                      |
+| -------------------- | -------- | ------------------------------------------------------------ |
+| `rules`              | required | Rules described above                                        |
+| `enabled`            | `true`   | Set `false` to keep the rules but stop blocking              |
+| `logBlockedRequests` | `true`   | Log each blocked request with `console.warn`                 |
+| `onRequestBlocked`   | none     | Called with `{ method, url, rule }` for each blocked request |
+
+## What a blocked request looks like
+
+The blocker wraps `window.fetch` and `XMLHttpRequest`. A blocked `fetch`
+resolves to a `451` response with the status text
+`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
+and fires an `error` event. Requests that match no rule are not delayed.
+
+## When blocking starts
+
+The provider holds matching requests from its first render in the browser,
+before any of its children render or run effects. That covers requests from
+child components, including their mount effects, and from effects in
+components rendered next to the provider. The blocker module itself loads
+after mount and decides each held request. Apps without `networkBlocker` do
+not download it.
+
+The standalone `useNetworkBlocker` hook works the same way from the first
+render of the component that calls it. That render patches `fetch` and
+`XMLHttpRequest`. If React throws the render away and never commits it, the
+hold ends after 10 seconds. Nothing checked consent for the requests it held,
+so they fail the way the blocker fails a blocked request: a 451 response for
+`fetch`, a failed XHR. The same happens when the component unmounts before
+the blocker loads.
+
+While consent is unknown, a matching request that would be blocked waits
+instead of failing. Consent is unknown until the policy has loaded, which is
+also when a returning visitor's stored choice takes effect. The request is
+then sent if the choice allows it and blocked otherwise. If the policy fails
+to load, optional categories stay denied and waiting requests are blocked.
+If the policy request never finishes, they keep waiting and are never sent.
+
+A synchronous XHR cannot wait. Before the blocker module has loaded, a
+matching one throws a `NetworkError` from `send()`. After that, one that
+consent does not allow yet is blocked.
+
+## What the network blocker cannot stop
+
+The blocker only sees requests made after the provider starts rendering in
+the browser, through `fetch` or `XMLHttpRequest`. It cannot stop:
+
+* Code that runs before the provider renders: inline scripts in the HTML,
+  third-party tags in `<head>`, scripts loaded before hydration (such as
+  `next/script` with `beforeInteractive`), and client modules that evaluate
+  earlier. Webpack builds evaluate a route's client component modules when
+  its chunk loads, so their top-level code runs first. Turbopack evaluates a
+  client component module when its first element renders, which inside the
+  provider is after blocking starts.
+* Code that saved its own reference to `fetch` or `XMLHttpRequest` before the
+  provider rendered.
+* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
+  `<img>`, `<script>` or `<iframe>` elements, web workers and service
+  workers.
+* With the standalone `useNetworkBlocker` hook instead of the provider
+  option, requests sent before the component that calls it renders.
+  Blocking starts in that component's first render, not the provider's.
+
+Keep tracking calls out of that window:
+
+* Send them from an effect or an event handler, never at module top level.
+* Load vendor SDKs through `scripts` instead of a `<script>` tag or
+  `next/script`, so they wait for consent before they run at all.
+* Check `useConsent('measurement')` (or the category you need) before you
+  call a vendor from your own code, and treat the blocker as a backstop.
+
+## Verify the blocked requests
+
+Open DevTools Network in a private window, under a policy that asks for
+consent.
+
+1. Before a choice, requests matching a rule are absent, and the console logs
+   each blocked request.
+2. Allow the rule's category and save. Matching requests go out.
+3. Reject, reload, and check that they stay absent.

package/docs/frameworks/tanstack-start/scripts.md

@@ -0,0 +1,103 @@
+---
+title: Scripts
+description: Load vendor scripts by consent category in a TanStack Start app
+  with ConsentRoot, and clear stored data or reload the page when a visitor
+  withdraws consent.
+group: frameworks
+---
+
+## Register vendor scripts
+
+Pass vendor loaders to `ConsentRoot` through its `scripts` prop. `ConsentRoot`
+loads each script in the browser when its category is allowed and removes it
+when the category is denied. The [quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart)
+registers PostHog and X Pixel in `src/scripts.ts`:
+
+```ts title="src/scripts.ts"
+import { posthog } from '@c15t/integrations/posthog';
+import { xPixel } from '@c15t/integrations/x-pixel';
+
+export const scripts = [
+	posthog({
+		id: 'phc_your_project_key',
+		initOptions: { cookieless_mode: 'never' },
+		loadMode: 'after-consent',
+		region: 'eu',
+	}),
+	xPixel({ pixelId: 'your-pixel-id' }),
+];
+```
+
+The root route imports that module and passes it on:
+
+```tsx title="src/routes/__root.tsx"
+import { scripts } from '../scripts';
+
+<ConsentRoot
+	state={consent}
+	backendURL={backendURL}
+	initRoute={false}
+	scripts={scripts}
+>
+```
+
+Import vendor helpers in route modules, not in a server function. A server
+function's return value must be serializable, and vendor loaders contain
+functions. Scripts only load in the browser, so importing them in the root
+route adds nothing to the server HTML.
+
+Each helper from `@c15t/integrations` sets its own category and a stable `id`.
+Remove every other loader for the same vendor, such as a `scripts` entry in a
+route's `head()` or an SDK you initialize at module level, so the vendor loads
+once and only through c15t. [Integrations](../../integrations/overview.md) lists
+every helper, and [building integrations](../../integrations/building-integrations.md)
+covers a vendor without one.
+
+## What happens when consent changes
+
+* **Allowed.** The script loads, or its SDK starts, the first time its category
+  is allowed. With an awaited root loader, a returning visitor's allowed
+  scripts start right after hydration.
+* **Denied later.** The script element is removed. Code that already ran keeps
+  running, so after the visitor turns off a category they had allowed, the page
+  reloads once the save finishes. Set `reloadOnConsentRevoked: false` in
+  `ConsentRoot`'s `options` only if every gated vendor stops itself.
+* **`alwaysLoad` helpers.** Some integrations, such as Google Consent Mode,
+  load before consent and pass the visitor's choice to the vendor. Read the
+  vendor's guide; a category on a script does not always mean zero requests.
+
+## Embeds and other requests
+
+Scripts cover vendor code c15t loads for you. For the rest:
+
+* [Embeds](./embeds.md) keeps iframes out of the
+  page with `ConsentGate` or the iframe blocker.
+* [Network blocker](./network-blocker.md) holds
+  `fetch` and XHR calls that match a rule until their category is allowed.
+
+## Clear stored data after revocation
+
+Removing a script does not delete the cookies or storage entries it wrote. Pass
+`clearOnRevocation` to `ConsentRoot` to delete the entries you list for each
+category when it is denied. `ConsentRoot` reads it once, when it mounts.
+[Clear on revocation](https://c15t.com/docs/frameworks/tanstack-start/clear-on-revocation) covers
+configuration and browser limits.
+
+## Let visitors turn off one vendor
+
+A visitor can allow marketing and still switch off one vendor in it. Pass
+`vendors` to `ConsentRoot`. Helpers from `@c15t/integrations` already carry
+their vendor slug. See [vendor consent](https://c15t.com/docs/frameworks/tanstack-start/vendor-consent).
+
+## Check the scripts
+
+Open DevTools Network in a private window, filter by each vendor's domain and
+reload.
+
+1. Before a choice under an opt-in policy, no vendor script loads. The page
+   source has no vendor `<script>` tags.
+2. Allow one category. Only that category's vendors load.
+3. Turn the category off. The page reloads and the vendor stays absent.
+4. Reload again. The rejection holds, and the server HTML shows no banner.
+
+[Verify consent](../../guides/verify-consent.md) has the full checklist.

package/docs/frameworks/vue/embeds.md

@@ -0,0 +1,84 @@
+---
+title: Embeds
+description: Keep YouTube videos, maps and other iframes out of a Vue page until
+  their consent category is allowed, with ConsentGate or the iframe blocker.
+group: frameworks
+---
+
+## Pick a method
+
+| Method             | Use it when                                                                                                   |
+| ------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `ConsentGate`      | You render the iframe in a Vue component and want a placeholder with a way to open preferences.               |
+| The iframe blocker | The iframe comes from markup you do not render with a component, such as CMS content, or you want no wrapper. |
+
+Both remove the iframe's `src` until the category is allowed, so the embed's
+host receives no request before consent.
+
+## Gate an embed with ConsentGate
+
+Wrap the iframe in [`ConsentGate`](https://c15t.com/docs/frameworks/vue/components/consent-gate)
+from `c15t/vue/runtime/components/consent-gate.vue`:
+
+```vue title="src/VideoEmbed.vue"
+<script setup lang="ts">
+import ConsentGate from 'c15t/vue/runtime/components/consent-gate.vue';
+import ConsentPreferencesLink from 'c15t/vue/runtime/components/consent-preferences-link.vue';
+</script>
+
+<template>
+	<ConsentGate category="measurement">
+		<iframe
+			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
+			title="YouTube video"
+			loading="lazy"
+			allowfullscreen
+		/>
+		<template #placeholder>
+			<p>Allow measurement to load this YouTube video.</p>
+			<ConsentPreferencesLink>Choose video permissions</ConsentPreferencesLink>
+		</template>
+	</ConsentGate>
+</template>
+```
+
+The iframe does not exist in the page until the visitor allows measurement.
+The `placeholder` slot shows a message and a
+[`ConsentPreferencesLink`](https://c15t.com/docs/frameworks/vue/components/consent-preferences-link)
+until then. When the visitor withdraws measurement, Vue removes the iframe.
+
+Pick the category that matches what the embed does. The example uses
+measurement for YouTube because its player measures views. A map or chat
+widget usually belongs under functionality or experience.
+
+## Gate an iframe with the iframe blocker
+
+The Vue plugin runs the iframe blocker by default. Give an iframe `data-src`
+instead of `src`, and a `data-category`:
+
+```vue title="src/MapEmbed.vue"
+<template>
+	<iframe
+		data-src="https://www.google.com/maps/embed?pb=YOUR_EMBED_ID"
+		data-category="functionality"
+		title="Store map"
+	/>
+</template>
+```
+
+c15t sets `src` from `data-src` when the category is allowed and removes it
+when the category is withdrawn. It watches the page, so iframes added later,
+for example by a route change, are handled too. The iframe element stays in
+the page while blocked, empty. Add `data-vendor` with a vendor ID to also
+block the iframe while the visitor has turned that vendor off.
+
+Pass `iframeBlocker: false` to the plugin to turn the blocker off.
+
+## Verify
+
+Open the page in a private window with the Network tab open, under a policy
+that asks for consent. No request goes to `youtube-nocookie.com` or
+`google.com/maps`. Allow the category and save: the iframe loads. Withdraw it
+and save: the page reloads without the embed. The
+[YouTube](../../integrations/youtube.md) and
+[Google Maps](../../integrations/google-maps.md) guides cover sizing and titles.

package/docs/frameworks/vue/network-blocker.md

@@ -0,0 +1,99 @@
+---
+title: Network blocker
+description: Hold fetch and XMLHttpRequest calls in a Vue app until their
+  consent category is allowed, with rules passed to the c15t Vue plugin.
+group: frameworks
+---
+
+## Add rules
+
+The network blocker stops `fetch` and `XMLHttpRequest` calls that match a
+rule until the rule's category is allowed. Use it as a backstop for tracking
+calls your own code or a vendor SDK makes. Load vendor SDKs through
+[`scripts`](./scripts.md) first, so they do not run at all
+before consent.
+
+Define the rules in their own file:
+
+```ts title="src/network-blocker.ts"
+import type { UseNetworkBlockerOptions } from 'c15t/vue/vue-plugin';
+
+export const networkBlocker = {
+	onRequestBlocked: (info) => {
+		console.info('Blocked until consent', info.method, info.url);
+	},
+	rules: [
+		{ category: 'measurement', domain: 'google-analytics.com' },
+		{
+			category: 'marketing',
+			domain: 'facebook.com',
+			methods: ['POST'],
+			pathIncludes: '/tr',
+		},
+	],
+} satisfies UseNetworkBlockerOptions;
+```
+
+Pass them to the plugin in `src/main.ts`:
+
+```ts title="src/main.ts"
+app.use(c15tVue, {
+	backendURL: 'https://your-project.inth.app',
+	networkBlocker,
+	scripts,
+});
+```
+
+## Match requests with rules
+
+Each rule names a `domain` and the consent `category` a request needs. The
+domain also matches its subdomains, so `google-analytics.com` covers
+`www.google-analytics.com`. `pathIncludes` narrows a rule to paths that
+contain a substring, and `methods` narrows it to HTTP methods. `category`
+also takes conditions such as `{ and: ['measurement', 'marketing'] }`.
+
+Add `vendor` with a vendor ID to also block the request while the visitor has
+turned that vendor off. Rules for IAB TCF vendors use `vendorId` and the
+`iabPurposes` fields instead.
+
+| Option               | Default  | Purpose                                                       |
+| -------------------- | -------- | ------------------------------------------------------------- |
+| `rules`              | Required | The rules above.                                              |
+| `enabled`            | `true`   | `false` keeps the rules but stops blocking.                   |
+| `logBlockedRequests` | `true`   | Logs each blocked request with `console.warn`.                |
+| `onRequestBlocked`   | Unset    | Called with `{ method, url, rule }` for each blocked request. |
+
+## What a blocked request looks like
+
+A blocked `fetch` resolves to a `451` response with the status text
+`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
+and fires an `error` event. Requests that match no rule are not delayed.
+
+## When blocking starts
+
+The plugin starts holding matching requests when `app.use(c15tVue, ...)`
+runs, before your app mounts. While consent is unknown, a matching request
+waits instead of failing. Once the policy has loaded and the stored choice
+applies, a waiting request is sent if consent allows it and blocked
+otherwise. If the policy fails to load, optional categories stay denied and
+waiting requests are blocked.
+
+## What it cannot stop
+
+The blocker sees only `fetch` and `XMLHttpRequest` calls made after
+`app.use()` runs. It cannot stop:
+
+* Scripts in `index.html` and modules that run before `src/main.ts`.
+* Code that saved its own reference to `fetch` before the plugin installed.
+* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests from
+  `<img>`, `<script>` and `<iframe>` elements, web workers and service
+  workers.
+
+Check `useConsent()` before you call a vendor from your own code, and treat
+the blocker as a backstop.
+
+## Verify
+
+Open the Network tab, clear site data and reload. Requests that match a rule
+do not appear until you allow their category, and the console lists each
+blocked request. Reject, reload, and check that they still do not appear.

package/docs/frameworks/vue/scripts.md

@@ -0,0 +1,93 @@
+---
+title: Scripts
+description: Load vendor scripts by consent category in a Vue app with the c15t
+  Vue plugin, and what happens when a visitor withdraws consent.
+group: frameworks
+---
+
+## Register vendor scripts
+
+A banner does not stop a script you load with a `<script>` tag in
+`index.html` or a vendor SDK you initialize yourself. Remove those loaders and
+register the vendor with c15t instead, so c15t loads it only while its
+category is allowed.
+
+Create the script configuration with the helpers from `@c15t/integrations`:
+
+```ts title="src/scripts.ts"
+import { posthog } from '@c15t/integrations/posthog';
+import { xPixel } from '@c15t/integrations/x-pixel';
+
+export const scripts = [
+	posthog({
+		id: 'phc_your_project_key',
+		initOptions: { cookieless_mode: 'never' },
+		loadMode: 'after-consent',
+	}),
+	xPixel({ pixelId: 'your-pixel-id' }),
+];
+```
+
+Pass it to the plugin as `scripts`:
+
+```ts title="src/main.ts"
+import { c15tVue } from 'c15t/vue/vue-plugin';
+import { createApp } from 'vue';
+
+import App from './App.vue';
+import { scripts } from './scripts';
+
+createApp(App)
+	.use(c15tVue, { backendURL: 'https://your-project.inth.app', scripts })
+	.mount('#app');
+```
+
+The plugin starts one script loader when the app mounts, after it has applied
+the visitor's stored choice and privacy signals. Do not also call
+`createScriptLoader` from a component. A component's `onMounted` runs before
+the plugin has read the stored choice, and each script would load twice.
+
+Every vendor guide under [integrations](../../integrations/overview.md) gives the
+helper and options for that vendor.
+
+## Embeds and other requests
+
+Scripts cover vendor code c15t loads for you. For the rest:
+
+* [Embeds](./embeds.md) gates iframes with `ConsentGate` or
+  the iframe blocker.
+* [Network blocker](./network-blocker.md) holds `fetch` and
+  XHR calls that match a rule until their category is allowed.
+
+## When a visitor withdraws consent
+
+Removing a script tag cannot stop code that already ran. When a save turns off
+a category or vendor that was allowed, c15t reloads the page so the new
+document starts with only permitted code. Set `reloadOnConsentRevoked: false`
+to handle revocation yourself, or use the
+[`onBeforeConsentRevocationReload` callback](https://c15t.com/docs/frameworks/vue/callbacks#before-a-revocation-reload)
+to run code before the reload.
+
+`clearOnRevocation` deletes first-party cookies and storage keys that belong to
+a category when it is withdrawn. See
+[clear on revocation](https://c15t.com/docs/frameworks/vue/clear-on-revocation).
+
+## Let visitors turn off one vendor
+
+A visitor can allow marketing and still switch off one vendor in it. Declare
+the vendors in the `vendors` option; helpers from `@c15t/integrations` already carry
+their vendor slug. See [vendor consent](https://c15t.com/docs/frameworks/vue/vendor-consent).
+
+## Content Security Policy
+
+Allow each vendor's script host in `script-src`. The plugin's `nonce` option
+adds a nonce to every script the loader creates. See
+[Content Security Policy](https://c15t.com/docs/frameworks/vue/content-security-policy).
+
+## Verify gating
+
+In a private window, open the Network tab and load the app under a policy that
+asks for consent. Requests to your vendors are absent.
+Allow one category and save, and only that category's vendors load. Withdraw
+it, and the page reloads without loading the vendor again.
+[Verify consent](../../guides/verify-consent.md) has the full checklist.