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

package/docs/frameworks/next/script-loader.md

@@ -1,216 +0,0 @@
----
-title: Load scripts with consent
-description: Register vendor scripts in your existing Next.js ConsentRoot and
-  handle loading and revocation.
-group: frameworks
----
-
-## Keep one owner for vendor scripts
-
-The [App Router](https://c15t.com/docs/frameworks/next/app-router) and
-[Pages Router](https://c15t.com/docs/frameworks/next/pages-router) setups already register scripts
-in a client wrapper. Keep that wrapper and add vendors to `lib/scripts.ts`.
-If you are adding scripts to an existing c15t setup, install the helpers and
-use the same registration pattern below.
-
-| Package manager | Command                     |
-| :-------------- | :-------------------------- |
-| npm             | `npm install @c15t/scripts` |
-| pnpm            | `pnpm add @c15t/scripts`    |
-| yarn            | `yarn add @c15t/scripts`    |
-| bun             | `bun add @c15t/scripts`     |
-
-Keep `c15t.config.ts` and the manifest route from your router setup. These shared
-URLs connect initialization and consent submissions to the same backend.
-
-## Register scripts in a client wrapper
-
-The [runnable Next.js example](https://c15t.com/docs/examples) uses PostHog for measurement and
-X Pixel for marketing. Set `NEXT_PUBLIC_POSTHOG_KEY` and
-`NEXT_PUBLIC_X_PIXEL_ID` to your own project identifiers before building.
-`NEXT_PUBLIC_POSTHOG_HOST` optionally selects your PostHog region's API host.
-Omit a vendor's ID to leave that integration disabled, or replace its helper
-with the [integration](../../integrations/overview.md) your application uses. Include the
-measurement and marketing categories in your policy for these two vendors.
-
-Create `lib/scripts.ts` with the example's script configuration:
-
-```ts title="lib/scripts.ts"
-import { posthog } from '@c15t/scripts/posthog';
-import { xPixel } from '@c15t/scripts/x-pixel';
-import type { Script } from 'c15t';
-
-export const posthogConfigured = Boolean(process.env.NEXT_PUBLIC_POSTHOG_KEY);
-export const xPixelConfigured = Boolean(process.env.NEXT_PUBLIC_X_PIXEL_ID);
-
-export const scripts: Script[] = [];
-
-if (process.env.NEXT_PUBLIC_POSTHOG_KEY) {
-	scripts.push(
-		posthog({
-			apiHost: process.env.NEXT_PUBLIC_POSTHOG_HOST,
-			id: process.env.NEXT_PUBLIC_POSTHOG_KEY,
-			initOptions: { cookieless_mode: 'never' },
-			loadMode: 'after-consent',
-		})
-	);
-}
-
-if (process.env.NEXT_PUBLIC_X_PIXEL_ID) {
-	scripts.push(xPixel({ pixelId: process.env.NEXT_PUBLIC_X_PIXEL_ID }));
-}
-```
-
-PostHog waits for measurement consent here. `cookieless_mode: 'never'` disables
-cookieless capture after rejection. X Pixel waits for marketing consent. Remove
-any existing loader for these vendors, including `next/script` and tag-manager
-entries, so each integration loads once.
-
-Create this client wrapper. It keeps scripts and browser callbacks in the client
-while the router supplies the visitor's resolved state through `state`:
-
-```tsx title="components/consent.tsx"
-'use client';
-
-import type { ReactNode } from 'react';
-import {
-  ConsentBanner,
-  ConsentDialog,
-  ConsentDialogLink,
-  ConsentRoot,
-} from 'c15t/next';
-import type { ConsentRootProps } from 'c15t/next';
-import { consentConfig } from '../c15t.config';
-import { scripts } from '../lib/scripts';
-
-export function Consent({
-  children,
-  state,
-}: {
-  children: ReactNode;
-  state: ConsentRootProps['state'];
-}) {
-  return (
-    <ConsentRoot state={state} config={consentConfig} scripts={scripts}>
-      {children}
-      <ConsentBanner />
-      <ConsentDialog />
-      <footer>
-        <ConsentDialogLink>Privacy settings</ConsentDialogLink>
-      </footer>
-    </ConsentRoot>
-  );
-}
-```
-
-`ConsentRoot` already provides the consent runtime. Mount this wrapper once;
-do not add a second provider. Keep your site's content and footer inside it.
-
-## Pass prepared consent through your router
-
-In the App Router, the root layout from the
-[App Router guide](https://c15t.com/docs/frameworks/next/app-router) passes the pending
-`resolveConsent` result to this wrapper. This partial example is that call;
-keep the `html`, `body` and stylesheet from your existing layout:
-
-```tsx
-import { resolveConsent } from 'c15t/next/server';
-import { consentConfig } from '../c15t.config';
-import { Consent } from '../components/consent';
-
-// Inside the existing synchronous root layout:
-const state = resolveConsent({ config: consentConfig });
-
-<Consent state={state}>{children}</Consent>
-```
-
-No script loads until the browser has applied the resolved policy and the
-visitor's choice allows it. With the
-[awaited layout](https://c15t.com/docs/frameworks/next/app-router#render-the-banner-in-the-server-html),
-pass the awaited result from `ResolvedConsent` to the same wrapper instead.
-
-Pages Router passes `state={pageProps.consentState ?? {}}` to this wrapper
-in `_app.tsx`. Keep `getServerSideProps` and its `c15t/next/pages` helper.
-The router guides contain complete layout and `_app.tsx` files.
-
-For static export or browser-only initialization, pass `state={{}}` and keep
-that setup's existing transport. Register scripts on its existing `ConsentRoot`;
-do not introduce server prefetch or local routes just to add a vendor.
-
-## Check each vendor's loading behavior
-
-The example explicitly configures PostHog to load after consent and disables
-cookieless capture. Those settings are deliberate; its default helper can load
-before consent and use the SDK's consent controls. Read the
-[PostHog guide](../../integrations/posthog.md) before changing them.
-
-Ordinary scripts wait for their category's effective permission. Give each
-script a stable unique `id` and remove any other loader for the same vendor.
-Helpers with `alwaysLoad` may load an SDK before permission is granted; a
-category field alone does not guarantee no requests. See the
-[vendor guides](../../integrations/overview.md) for their exact contracts.
-
-Removing a script element cannot undo executed JavaScript or requests already
-sent. PostHog exposes capture controls; X Pixel has no consent-update API.
-Stop future event calls after revocation and test a change from allowed to
-denied, as well as initial denial.
-
-## Verify the integration
-
-With an opt-in policy and no saved choice, neither configured example vendor
-should load. Allow measurement only: PostHog loads and X Pixel remains blocked.
-Reject, reload, and reopen Privacy settings to confirm the choice persists.
-
-Use the [runnable example](https://c15t.com/docs/examples) to inspect the same script definitions
-with DevTools, or follow [verification](../../guides/verify-consent.md) in your app.
-Use [custom integrations](../../integrations/building-integrations.md) for an
-unlisted vendor. Google helpers have a separate
-[Consent Mode contract](../../integrations/google-tag-manager.md).
-
-## Granular consent
-
-A visitor can grant marketing and still turn one vendor off. Declare the
-vendors next to the scripts in `lib/scripts.ts`, with the `vendor` slug each
-script already carries, and pass both to `ConsentRoot`:
-
-```ts title="lib/scripts.ts"
-import type { Vendor } from 'c15t';
-
-export const vendors: Vendor[] = [
-  {
-    id: 'x-pixel',
-    name: 'X Pixel',
-    category: 'marketing',
-    privacyPolicyUrl: 'https://x.com/privacy',
-  },
-];
-```
-
-```tsx title="components/consent.tsx"
-import { scripts, vendors } from '../lib/scripts';
-
-<ConsentRoot state={state} config={consentConfig} scripts={scripts} vendors={vendors}>
-  {children}
-</ConsentRoot>
-```
-
-The preference center lists each vendor under its category with a switch.
-Integrations from `@c15t/scripts` set `vendor` to their manifest slug, so
-`xPixel()` needs no extra wiring; give a hand-written script the same slug
-in its `vendor` field. A backend manifest can declare vendors too. See
-[granular consent](../../integrations/granular-consent.md) for storage,
-bulk actions and the hooks a custom control uses.
-
-## Clear stored tracking data
-
-Script gating does not remove cookies or Web Storage entries that a script
-already wrote. Add `clearOnRevocation` to your `ConsentRoot` or provider
-options to remove declared data when its category is denied. See
-[clear on revocation](../../integrations/clear-on-revocation.md) for configuration
-and browser limits.
-
-## Shared lifecycle controls
-
-See [shared consent controls](../../guides/shared-consent-controls.md) for external CMPs,
-preference delegation, withdrawal reloads, and application events. These controls
-use the same core runtime across frameworks.

package/docs/frameworks/react/script-loader.md

@@ -1,69 +0,0 @@
----
-title: Load scripts with consent
-description: Register vendor scripts once and let effective permissions control loading.
-group: frameworks
----
-
-## Register scripts on the provider
-
-Install `@c15t/scripts` for vendor helpers. This React-compatible client component
-uses Inth as the backend. Set the URL to the endpoint supplied by your Inth
-project and keep the component mounted around your application.
-
-```tsx title="components/consent.tsx"
-'use client';
-
-import type { ReactNode } from 'react';
-import { ConsentProvider, ConsentBanner, ConsentDialog, ConsentDialogLink, hosted } from 'c15t/react';
-import { metaPixel } from '@c15t/scripts/meta-pixel';
-
-const mode = hosted({ url: 'https://your-project.inth.app' });
-const scripts = [metaPixel({ pixelId: '123456789012345' })];
-
-export function Consent({ children }: { children: ReactNode }) {
-  return (
-    <ConsentProvider options={{ mode, scripts }}>
-      {children}
-      <ConsentBanner />
-      <ConsentDialog />
-      <ConsentDialogLink>Privacy settings</ConsentDialogLink>
-    </ConsentProvider>
-  );
-}
-```
-
-Import your adapter's stylesheet globally, as in the framework quickstart. For
-an existing server-resolved `ConsentRoot`, keep that root and pass
-`scripts` as a top-level prop instead of mounting a second provider.
-
-## Understand loading and revocation
-
-Ordinary scripts wait for their category's effective permission. Give each
-script a stable unique `id` and remove any other loader for the same vendor.
-Some helpers use `alwaysLoad` to load the SDK and signal consent through its own
-API. Read the vendor guide; a category field alone does not guarantee no
-requests.
-
-Removing a script element cannot undo JavaScript that already executed or
-requests already sent. Use the vendor's supported consent and cleanup behavior,
-and stop future event calls after revocation. Test both initial denial and a
-change from allowed to denied.
-
-Use [custom integrations](../../integrations/building-integrations.md) for an
-unlisted vendor and [verification](../../guides/verify-consent.md) for the network
-checks. Google helpers have a separate
-[Consent Mode contract](../../integrations/google-tag-manager.md).
-
-## Clear stored tracking data
-
-Script gating does not remove cookies or Web Storage entries that a script
-already wrote. Add `clearOnRevocation` to `ConsentProvider.options` to remove
-declared data when its category is denied. See
-[clear on revocation](../../integrations/clear-on-revocation.md) for configuration
-and browser limits.
-
-## Shared lifecycle controls
-
-See [shared consent controls](../../guides/shared-consent-controls.md) for external CMPs,
-preference delegation, withdrawal reloads, and application events. These controls
-use the same core runtime across frameworks.

package/docs/guides/deployment-modes.md

@@ -1,75 +0,0 @@
----
-title: Choose a deployment mode
-description: Choose who runs your consent backend, then select manifest, init or
-  offline resolution for your deployment.
-group: guides
----
-
-## Use Inth for managed policy and records
-
-Start with [Inth](https://inth.com) unless you need to operate the consent
-service yourself or deliberately need only local browser records. Configure
-policy rules and trusted origins in the project, then use its exact backend
-endpoint in your framework setup.
-
-| Backend ownership         | Policy source                                          | Record storage                           | Use when                                                                  |
-| ------------------------- | ------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------- |
-| Inth hosted service       | Centrally managed policy through a manifest or `/init` | Browser records plus backend submissions | You want managed policy and consent records                               |
-| Self-hosted c15t          | Your backend's manifest or `/init`                     | Browser records plus your database       | You need to operate the service and its infrastructure                    |
-| Browser-only offline mode | Bundled `policyRules`                                  | Browser persistence                      | Local development and tests. Not recommended for production environments. |
-
-Hosted and self-hosted c15t use the same transport protocol. Switching who runs
-the backend does not require switching from manifests to `/init`.
-
-## Choose data fetching separately
-
-For Next.js deployments with a runtime server, use the
-[manifest setup](https://c15t.com/docs/frameworks/next/data-fetching). It reuses public policy data
-in your application while consent writes still go to Inth. Regular backend
-`/init` is available when you want backend-owned request resolution or a simpler
-browser setup. See [data fetching and transports](./data-fetching.md) for
-the comparison, including custom transports and offline mode.
-
-Manifest resolution removes the per-visitor `/init` request, and with it the
-backend's only count of visitors. The server adapters replace it with a session
-report: after each resolution, on a server-rendered page or the same-origin
-init route, the host posts a small report to the backend's `POST /sessions`,
-server-to-server and detached from the response. The browser makes no request
-and the report stores no identity; the visitor's IP and user agent travel as
-forwarded headers under the backend's usual IP handling. Each report is one
-resolution; a page view can produce a `render` and a `route` report, and the
-consuming side groups them into sessions by address and user agent within a
-window. Static output resolves in the browser and sends none. Set `reportSessions: false` on an adapter to turn
-it off.
-
-## Match initialization to your application output
-
-| Application output | Initial state             | Required setup                                              |
-| ------------------ | ------------------------- | ----------------------------------------------------------- |
-| Request SSR        | Prepared for this visitor | Adapter request helper and matching client configuration    |
-| Static HTML or SPA | Resolved in the browser   | Reachable external URLs or deliberately bundled local rules |
-
-Request SSR can include the visitor's prompt in the initial HTML. Pass the
-prepared records and policy resolution through to hydration. Do not convert
-effective permissions into new stored choices.
-
-Static HTML is shared across visitors. It cannot contain a choice resolved from
-each visitor's cookies or geography at build time. A static site can still use
-Inth through browser requests. A same-origin `/api/c15t` URL only works if a
-service actually serves it; a Next.js static export does not run API routes.
-
-A manifest contains reusable public policy data. A resolved init response and
-personalized consent HTML belong to a request. Do not give them the same shared
-cache treatment.
-
-## Handle initialization and storage failures
-
-While no policy resolves, optional permissions stay denied and the stock
-consent UI stays hidden. No banner can mean pending or failed initialization.
-It does not mean permission to load analytics. Observe errors before changing
-presentation, and do not silently switch to offline policy after a hosted
-request fails.
-
-Browser storage can also be unavailable. A working in-memory interaction does
-not prove the choice survives reload. Use
-[verification](./verify-consent.md) to test the actual deployment.

package/docs/guides/shared-consent-controls.md

@@ -1,158 +0,0 @@
----
-title: Share consent controls across frameworks
-description: Use the same c15t script lifecycle, external consent source, and
-  event controls in every framework.
-group: guides
----
-
-## Choose one consent authority
-
-c15t owns script loading, consent gates, lifecycle callbacks, and optional cleanup
-through its framework-independent core. React, Vue, Svelte, Astro, and the browser
-client connect to that core. Next.js and TanStack Start use the React provider;
-Nuxt uses Vue; SvelteKit uses Svelte. None requires Astro for these controls.
-
-With c15t as the consent authority, keep your framework's hosted, self-hosted, or
-offline setup. Offline mode keeps choices in the browser; a hosted backend can
-store records. The script SDK and event dispatcher work with either mode.
-
-To keep another CMP, provide a `consentSource`. It owns the banner, preferences,
-records, expiration, privacy signals, and category mapping. c15t follows its
-current permissions without creating a second choice record. Optional categories
-start denied, including during SSR. An unavailable source or a failed read denies
-them again. Initialize the CMP independently, or register its loader as an
-explicitly early-loading script so it does not wait for its own consent.
-
-The source contract is exported from `@c15t/core/runtime`:
-
-```ts title="src/consent-source.ts — adapter skeleton"
-import type { ExternalConsentSource } from 'c15t/runtime';
-import { provider } from './existing-cmp';
-
-export const consentSource: ExternalConsentSource = {
-  getPermissions: () => provider.getCategoryPermissions(),
-  subscribe: (notify) => provider.subscribe(notify),
-  openPreferences: () => provider.openPreferences(),
-};
-```
-
-`provider` is your application's adapter for the existing CMP, not a c15t export.
-Map its categories to c15t's `measurement`, `marketing`, `functionality`, and
-`experience` booleans. Missing categories are denied; `necessary` stays true.
-Return `null` until the CMP is ready. `subscribe` must notify on initialization,
-changes, withdrawal, and expiration, and return a function that removes listeners.
-Keep browser access inside these functions so importing the adapter during SSR is safe.
-
-If `subscribe` throws, c15t reports the failure through `callbacks.onError` and
-continues startup with optional categories denied. The failed connection ignores
-later notifications and does not forward preference requests. Recreate the owner
-after the CMP is available to connect again.
-
-## Pass the controls to your framework
-
-The `consentSource` option is available at these registration points. Register your SDK configurations through the same owner's
-`scripts` option. Do not create an additional runtime beside an existing provider.
-
-| Framework                   | Registration point                                                                                                             |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| React                       | `ConsentProvider options={{ mode, consentSource, scripts }}`                                                                   |
-| Next.js / TanStack Start    | `ConsentRoot options={{ consentSource }}` with `scripts` as a top-level prop; `ConsentProvider` also accepts the React options |
-| Vue                         | `app.use(c15tVue, { consentSource, scripts })`                                                                                 |
-| Nuxt                        | `app.config.ts` → `c15t: { consentSource, scripts }`                                                                           |
-| Svelte / SvelteKit          | `ConsentManagerProvider` options or corresponding top-level props                                                              |
-| Astro                       | `clientOptions.consentSource`                                                                                                  |
-| Browser client              | `createConsentClient({ consentSource, scripts })`                                                                              |
-| Headless JavaScript / Solid | `createConsentRuntime({ mode, consentSource, scripts })`                                                                       |
-
-For example, a React client boundary can use the source directly:
-
-```tsx title="src/Consent.tsx"
-'use client';
-
-import type { ReactNode } from 'react';
-import { ConsentProvider, offline, useSetActiveUI } from 'c15t/react';
-import { googleTagManager } from '@c15t/scripts/google-tag-manager';
-import { consentSource } from './consent-source';
-
-const mode = offline();
-const scripts = [googleTagManager({ id: 'GTM-EXAMPLE' })];
-
-function Preferences() {
-  const setActiveUI = useSetActiveUI();
-  return <button type="button" onClick={() => setActiveUI('dialog')}>Privacy settings</button>;
-}
-
-export function Consent({ children }: { children: ReactNode }) {
-  return (
-    <ConsentProvider options={{ mode, consentSource, scripts }}>
-      {children}
-      <Preferences />
-    </ConsentProvider>
-  );
-}
-```
-
-Replace the container ID. `mode` remains required by the provider API, but an
-external source bypasses c15t backend initialization and persistence. Omit c15t's
-banner and dialog. Preference links, hooks, and `kernel.set.activeUI('dialog')`
-delegate to the source. Preference-opening failures reach `callbacks.onError`;
-`kernel.commands.save()` rejects instead of recording a second choice.
-
-In Next.js, construct the source in the client boundary; do not pass functions
-from a Server Component. Existing `ConsentRoot` state can stay serializable, but
-c15t records do not establish external permissions. A client-owned
-`ConsentProvider` avoids a redundant server consent fetch for external-only setups.
-For Nuxt, use `app.config.ts` for the functions, not serialized public runtime
-configuration; the module skips its consent fetch and record hydration when a
-source is configured. Browser access remains deferred until mount.
-
-Solid currently ships UI primitives, not a lifecycle provider. Create the core
-runtime once, call `start()` from `onMount`, and `dispose()` from `onCleanup`.
-Other frameworks' providers perform that lifecycle automatically. A provider given
-an existing `runtime` borrows it: configure controls on the runtime owner, which
-also owns starting and disposing it.
-
-## Handle withdrawal and application events
-
-When the source withdraws an optional category that was granted, c15t reloads
-the page, as it does when a visitor revokes consent in c15t's own UI. Removing a
-script element cannot stop JavaScript that already ran, so the reload starts a
-page with only permitted code. The reload runs in the next task, after
-synchronous consent callbacks and `onBeforeConsentRevocationReload`. Disposing
-the owner cancels a pending reload.
-
-c15t cannot tell a visitor's withdrawal from expiry or a reset in the CMP, so
-any notification that turns off a granted category reloads. The CMP owns
-persistence: store the new decision before notifying c15t, or the reloaded page
-reads the old one. Set `reloadOnConsentRevoked: false` to handle withdrawal
-yourself. c15t still updates gates and calls script consent callbacks.
-
-`createEventDispatcher` from `@c15t/scripts/events` also has no framework dependency:
-
-```ts title="src/events.ts — attach to an existing runtime"
-import { createEventDispatcher } from '@c15t/scripts/events';
-
-const events = createEventDispatcher({
-  scripts,
-  getSnapshot: () => runtime.kernel.getSnapshot(),
-});
-events.track('docs_search', { resultCount: 4 });
-```
-
-Here `scripts` is the same configuration registered with the existing `runtime`.
-For a provider-owned kernel, use that kernel's live `getSnapshot` instead. The
-dispatcher sends only to configured integrations with supported event APIs when
-measurement and the script's own consent condition allow it. It discards denied
-events, isolates vendor failures, and deduplicates explicitly configured SPA
-pageviews. It does not subscribe to a framework router: notify it from your
-router's navigation hook. Use vendor-specific helpers for APIs outside the shared
-event contract.
-
-## Verify the integration
-
-Test an undecided visitor, an existing grant, withdrawal, expiry, and a source
-that cannot be read. Check that only permitted scripts execute, the preference
-control opens the existing CMP, c15t does not render another banner or persist
-another receipt, and unmounting removes the source listeners. Test your actual
-CMP category mapping and tag-manager container; shared gates do not validate
-those configurations or establish compliance by themselves.