@c15t/browser 3.0.0-alpha.0

package/dist-types/headless.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `@c15t/browser/headless` — the client without any UI or CSS.
+ *
+ * For sites that render their own banner: subscribe to the client, call
+ * `acceptAll()` / `rejectAll()` / `save()`, or mark page elements with
+ * `data-c15t-action` and let the client wire them.
+ *
+ * @example
+ * ```ts
+ * import { init } from '@c15t/browser/headless';
+ *
+ * const c15t = init({ backendURL: 'https://your-instance.c15t.dev' });
+ * c15t.on('ui', (surface) => banner.hidden = surface !== 'banner');
+ * ```
+ */
+import type { ConsentClient, ConsentClientOptions } from './types';
+/**
+ * Create the page's client without starting it. `mountUI()` throws.
+ *
+ * @param options - Client options.
+ * @returns The client.
+ */
+export declare const createConsentClient: (options?: ConsentClientOptions) => ConsentClient;
+/**
+ * Create and start the page's client with no UI.
+ *
+ * @param options - Client options.
+ * @returns The started client.
+ */
+export declare const init: (options?: ConsentClientOptions) => ConsentClient;
+export { ACTION_ATTRIBUTE, custom, hosted, PREFERENCES_HASH } from './client';
+export type { PageAction } from './client';
+export { resolveRules } from './client';
+export { ACTIVATED_ATTRIBUTE, activateGatedScripts, CATEGORY_ATTRIBUTE, } from './gated-scripts';
+export { manifest, manifestNeedsLocation } from './transports/manifest';
+export type { ManifestModeOptions } from './transports/manifest';
+export { offline } from './transports/offline';
+export type { OfflineModeOptions } from './transports/offline';
+export type { ConsentClient, ConsentClientEventMap, ConsentClientOptions, ConsentModeName, PolicyPresetName, } from './types';
+export { version } from './version';
+export type { ConsentSnapshot, ConsentState } from '@c15t/core';

package/dist-types/iab/mount.d.ts

@@ -0,0 +1,8 @@
+import type { ConsentClient, ConsentUIHandle, ConsentUIOptions } from '../types';
+/**
+ * Mount IAB UI alongside the ordinary UI for non-IAB policy regions.
+ * @param client - The IAB-capable client to render.
+ * @param options - Theme, CSS, and mount settings.
+ * @returns The shared UI host and its teardown.
+ */
+export declare const mountIABConsentUI: (client: ConsentClient, options?: ConsentUIOptions) => ConsentUIHandle;

package/dist-types/iab/preferences.d.ts

@@ -0,0 +1,9 @@
+import type { ConsentSnapshot } from '@c15t/core';
+import type { SurfaceContext } from '../ui/surface';
+/** Preference content preserves focused controls while the IAB draft changes. */
+export interface IABPreferences {
+    element: HTMLElement;
+    sync: (snapshot: ConsentSnapshot) => void;
+}
+/** Render purpose, special-feature, and vendor choices from the shared model. */
+export declare const createIABPreferences: (ctx: SurfaceContext, vendorsFirst: boolean, moreVendorsText?: string) => IABPreferences;

package/dist-types/iab/styles.d.ts

@@ -0,0 +1,2 @@
+/** Native disclosure and touch-target adjustments for the IAB DOM adapter. */
+export declare const adapterStyles = "\n[data-testid=\"iab-consent-banner-root\"], [data-testid=\"iab-consent-dialog-root\"] { pointer-events: none; }\n[data-testid=\"iab-consent-banner-card\"], [data-testid=\"iab-consent-dialog-card\"] { pointer-events: auto; }\n[data-testid=\"iab-consent-banner-root\"][data-variant=\"floating\"][data-position^=\"top\"] { align-items: flex-start; }\n[data-testid=\"iab-consent-banner-root\"][data-variant=\"floating\"][data-position^=\"bottom\"] { align-items: flex-end; }\n[data-testid=\"iab-consent-banner-root\"][data-variant=\"floating\"][data-position$=\"left\"] { justify-content: flex-start; }\n[data-testid=\"iab-consent-banner-root\"][data-variant=\"floating\"][data-position$=\"right\"] { justify-content: flex-end; }\n[data-testid=\"iab-consent-banner-root\"][data-variant=\"bar\"] { --iab-consent-banner-max-width: 100%; align-items: flex-end; }\n[data-testid=\"iab-consent-banner-root\"][data-variant=\"bar\"][data-position=\"top\"] { align-items: flex-start; }\n[data-testid=\"iab-consent-banner-card\"] { max-height: calc(100dvh - 4rem); overflow-y: auto; }\n[data-c15t-iab-disclosure] > summary { box-sizing: border-box; min-height: 44px; cursor: pointer; list-style: none; justify-content: flex-start; align-items: center; }\n[data-c15t-iab-disclosure] > summary > :last-child { flex: 1; }\n[data-c15t-iab-disclosure] > summary::-webkit-details-marker { display: none; }\n[data-c15t-iab-chevron] { display: inline-block; color: var(--c15t-text-muted); }\n[data-c15t-iab-disclosure][open] > summary [data-c15t-iab-chevron] { transform: rotate(90deg); }\n[data-testid^=\"iab-consent-\"] button { min-height: 44px; touch-action: manipulation; }\n[data-c15t-iab-toggle] { width: 44px; height: 44px; padding: 12px 6px; }\n[data-c15t-iab-vendor-details] { display: block; padding: 0 0.75rem 0.75rem; font-size: 0.875rem; line-height: 1.5; }\n[data-c15t-iab-vendor-details] h3 { margin: 1rem 0 0.375rem; font-size: 0.875rem; font-weight: 600; }\n[data-c15t-iab-vendor-details] p { margin: 0.5rem 0; }\n[data-c15t-iab-vendor-details] ul { margin: 0.375rem 0; padding-inline-start: 1.25rem; }\n[data-testid^=\"iab-consent-\"] summary:focus-visible { outline: 2px solid var(--c15t-primary); outline-offset: 2px; }\n[data-testid=\"iab-consent-dialog-root\"] input[type=\"search\"] { font-size: 16px; }\n";

package/dist-types/iab/surface.d.ts

@@ -0,0 +1,4 @@
+import type { ConsentUIOptions } from '../types';
+import type { Surface, SurfaceContext } from '../ui/surface';
+/** One IAB banner/dialog lifecycle on the client's existing kernel. */
+export declare const createIABSurface: (ctx: SurfaceContext, options: ConsentUIOptions) => Surface;

package/dist-types/iab/vendor-disclosures.d.ts

@@ -0,0 +1,14 @@
+import type { ConsentSnapshot, GlobalVendorList, NonIABVendor } from '@c15t/core';
+import type { SurfaceCopy } from '../ui/copy';
+type Vendor = GlobalVendorList['vendors'][number] | NonIABVendor;
+/**
+ * Render the vendor's declared policies, data use, storage, and retention.
+ * Missing durations remain undisclosed rather than becoming zero days.
+ *
+ * @param snapshot - Current consent state containing the GVL definitions.
+ * @param vendor - Registered or custom vendor to describe.
+ * @param copy - Resolved translations and preferred language.
+ * @returns Disclosure content to append after the vendor's consent controls.
+ */
+export declare const createVendorDisclosures: (snapshot: ConsentSnapshot, vendor: Vendor, copy: SurfaceCopy) => DocumentFragment;
+export {};

package/dist-types/iab.d.ts

@@ -0,0 +1,20 @@
+import type { ConsentClient, ConsentClientOptions } from './types';
+/**
+ * Create an IAB-capable browser client without starting it.
+ * @param options - Transport, CMP, and presentation settings.
+ * @returns The client, with one runtime shared by ordinary and IAB UI.
+ */
+export declare const createConsentClient: (options?: ConsentClientOptions) => ConsentClient;
+/**
+ * Create and start an IAB-capable browser client.
+ * @param options - Transport, CMP, and presentation settings.
+ * @returns The started client. CMP controls are on `client.runtime.iab`.
+ */
+export declare const init: (options?: ConsentClientOptions) => ConsentClient;
+export { custom, hosted } from './client';
+export { offline } from './transports/offline';
+export { manifest } from './transports/manifest';
+export { mountIABConsentUI } from './iab/mount';
+export type { ConsentClient, ConsentClientOptions, ConsentUIOptions, } from './types';
+export { iab } from '@c15t/iab';
+export { version } from './version';

package/dist-types/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `@c15t/browser` — consent for sites without a build step.
+ *
+ * Most sites load `dist/c15t.js` from a CDN and never import this module.
+ * Bundler users get the same client and UI as ES modules here; the
+ * headless subset lives at `@c15t/browser/headless`.
+ *
+ * @example
+ * ```ts
+ * import { init } from '@c15t/browser';
+ * import '@c15t/browser/styles.css'; // only with `ui: { shadow: false }`
+ *
+ * const c15t = init({ backendURL: 'https://your-instance.c15t.dev' });
+ * c15t.on('consent', (snapshot) => console.log(snapshot.effectivePermissions));
+ * ```
+ */
+import type { ConsentClient, ConsentClientOptions } from './types';
+/**
+ * Create the page's client without starting it.
+ *
+ * @param options - Client options.
+ * @returns The client. Call `start()` to resolve the policy and mount.
+ */
+export declare const createConsentClient: (options?: ConsentClientOptions) => ConsentClient;
+/**
+ * Create and start the page's client, mounting the UI unless `ui: false`.
+ *
+ * @param options - Client options.
+ * @returns The started client.
+ */
+export declare const init: (options?: ConsentClientOptions) => ConsentClient;
+export { ACTION_ATTRIBUTE, custom, hosted, PREFERENCES_HASH } from './client';
+export type { PageAction } from './client';
+export { resolveRules } from './client';
+export { ACTIVATED_ATTRIBUTE, activateGatedScripts, CATEGORY_ATTRIBUTE, } from './gated-scripts';
+export { manifest, manifestNeedsLocation } from './transports/manifest';
+export type { ManifestModeOptions } from './transports/manifest';
+export { offline } from './transports/offline';
+export type { OfflineModeOptions } from './transports/offline';
+export type { ConsentBannerOptions, ConsentClient, ConsentClientEventMap, ConsentClientOptions, ConsentDialogOptions, ConsentModeName, PolicyPresetName, ConsentTriggerOptions, ConsentUIHandle, ConsentUIOptions, TriggerPosition, } from './types';
+export { mountConsentUI } from './ui/mount';
+export { version } from './version';
+export type { ConsentSnapshot, ConsentState } from '@c15t/core';

package/dist-types/transports/manifest.d.ts

@@ -0,0 +1,62 @@
+import type { ProviderTransportFactory } from '@c15t/core';
+import type { ConsentManifest, ResolveInitFromManifestInputs } from '@c15t/schema/types';
+/** Options for {@link manifest}. */
+export interface ManifestModeOptions {
+    /**
+     * The manifest itself, inlined. With it the first render needs no
+     * request at all for a policy that does not depend on location.
+     */
+    manifest?: ConsentManifest;
+    /** Where to fetch the manifest when it is not inlined. */
+    manifestURL?: string;
+    /**
+     * Backend origin for `POST /subjects`, and for `GET /init` when the
+     * policy depends on a location the browser does not know. Derived only
+     * from a `manifestURL` ending in `/manifest`. Required for other URLs
+     * and inline-only manifests. Use `''` for this origin.
+     */
+    backendURL?: string;
+    /**
+     * Decision inputs known ahead of time, typically the country an edge
+     * worker injected into the page. Kernel overrides win over these.
+     */
+    inputs?: ResolveInitFromManifestInputs;
+    /** Fetch implementation. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Whether resolving this manifest needs to know where the visitor is.
+ *
+ * A manifest whose packs all match by default or fallback — "one banner
+ * for everyone" — resolves the same everywhere, so the browser can do it
+ * without a round trip. Anything keyed by country or region, or the
+ * jurisdiction defaults that apply without packs, needs a location.
+ *
+ * @param manifest - The manifest.
+ * @returns `true` when a country is required for a faithful answer.
+ */
+export declare const manifestNeedsLocation: (manifest: ConsentManifest) => boolean;
+/**
+ * Resolve `/init` in the browser from the backend's consent manifest.
+ *
+ * The manifest is the geo-independent half of the backend's decision:
+ * policy packs, translations, branding. Inlining it into the page (or
+ * fetching it once, cached at the CDN) lets the banner render without a
+ * per-visitor `/init` round trip. Saves still go to the backend.
+ *
+ * When the policy depends on location and no country is known, the
+ * transport falls back to `GET /init` so the answer stays faithful.
+ *
+ * @param options - Manifest source and backend.
+ * @returns A transport factory for `mode`.
+ * @throws {Error} When neither `manifest` nor `manifestURL` is given,
+ * or a backend cannot be derived and `backendURL` is omitted.
+ *
+ * @example
+ * ```ts
+ * init({
+ *   mode: manifest({ manifest: window.__c15tManifest, backendURL: 'https://x.c15t.dev' }),
+ * });
+ * ```
+ */
+export declare const manifest: (options: ManifestModeOptions) => ProviderTransportFactory;

package/dist-types/transports/offline.d.ts

@@ -0,0 +1,18 @@
+import type { ProviderTransportFactory } from '@c15t/core';
+import type { PolicyRule } from '@c15t/schema/types';
+/** Policy rules evaluated locally when initialization runs. */
+export interface OfflineModeOptions {
+    /**
+     * Rules to resolve locally. Omit them to use `recommendedPolicyRules()`:
+     * strict opt-in for Europe, the UK, Quebec and unknown locations, opt-out
+     * for the US states with a privacy law, and `none` everywhere else.
+     * Passing rules replaces that pack entirely.
+     */
+    policyRules?: PolicyRule[];
+}
+/**
+ * Resolve local rules outside render and hydration.
+ * @param options - Explicit policy rules; absence resolves the recommended pack.
+ * @returns A provider transport with no network requests.
+ */
+export declare const offline: (options?: OfflineModeOptions) => ProviderTransportFactory;

package/dist-types/types.d.ts

@@ -0,0 +1,290 @@
+import type { AllConsentNames, Callbacks, ConsentPresentation, SaveResult, NoticeDismissResult, ConsentKernel, ConsentSnapshot, ConsentState, HasCondition, I18nConfig, KernelActiveUI, KernelConfig, KernelOverrides, KernelUser, LegalLinks, PolicyRule, policyRulePresets, ProviderTransportFactory, Script, StorageConfig, Unsubscribe } from '@c15t/core';
+import type { ConsentRuntime, ConsentRuntimeOptions, RuntimeNetworkBlockerOptions } from '@c15t/core/runtime';
+import type { ConsentManifest } from '@c15t/schema/types';
+import type { Theme } from '@c15t/ui/theme';
+/**
+ * The transports a script-tag site can name without importing anything.
+ *
+ * - `hosted` — `GET /init` and `POST /subjects` against `backendURL`.
+ * - `offline` — no backend; policy resolved from `policies` (or a default
+ *   opt-in banner) and consent kept in the browser only.
+ * - `manifest` — the backend's cacheable `/manifest` inlined or fetched,
+ *   resolved locally so the banner can render without waiting on `/init`.
+ */
+export type ConsentModeName = 'hosted' | 'offline' | 'manifest';
+/** A built-in policy pack, by the name `policyRulePresets` exports it under. */
+export type PolicyPresetName = keyof typeof policyRulePresets;
+/** Corner the floating preferences button docks to. */
+export type TriggerPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+/** Copy and behaviour overrides for the cookie banner. */
+export interface ConsentBannerOptions {
+    /** Heading. Defaults to the resolved translation. */
+    title?: string;
+    /** Body copy. Defaults to the resolved translation. */
+    description?: string;
+    /** "Accept all" label. */
+    acceptButtonText?: string;
+    /** "Reject all" label. */
+    rejectButtonText?: string;
+    /** "Customize" label. */
+    customizeButtonText?: string;
+    /** Drop the "Secured by c15t" tag. The IAB banner always retains its tag. */
+    hideBranding?: boolean;
+    /** Which legal links to render inline. `null` renders none. */
+    legalLinks?: (keyof LegalLinks)[] | null;
+    /** Dim the page and stop it scrolling while the banner is up. */
+    scrollLock?: boolean;
+    /** Legacy blocking override. Prefer `presentation.prompt.blocking`. */
+    trapFocus?: boolean;
+}
+/** Overrides for the preference centre dialog. */
+export interface ConsentDialogOptions {
+    /** Drop the "Secured by c15t" tag. */
+    hideBranding?: boolean;
+    /** Which legal links to render inline. `null` renders none. */
+    legalLinks?: (keyof LegalLinks)[] | null;
+}
+/** The floating button that reopens the preference centre. */
+export interface ConsentTriggerOptions {
+    /** Corner to dock to. Defaults to `bottom-right`. */
+    position?: TriggerPosition;
+    /** Button size. Defaults to `md`. */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * When to show it. `always` (default) whenever no other surface is
+     * open; `after-consent` only once the visitor has decided.
+     */
+    showWhen?: 'always' | 'after-consent';
+    /** Accessible name. */
+    ariaLabel?: string;
+    /** Remember a dragged-to corner in localStorage. Defaults to `true`. */
+    persistPosition?: boolean;
+}
+/** How and where the prebuilt UI mounts. */
+export interface ConsentUIOptions {
+    /** Copy for browser-specific IAB loading, saving, and pagination states. */
+    iab?: {
+        loadErrorText?: string;
+        saveErrorText?: string;
+        moreVendorsText?: string;
+    };
+    /**
+     * Element (or selector) to append the UI host to. Defaults to
+     * `document.body`.
+     */
+    container?: HTMLElement | string;
+    /**
+     * Render inside a shadow root so the host page's CSS cannot restyle the
+     * banner and vice versa. Defaults to `true`; set `false` when you want
+     * to override the styles with your own stylesheet.
+     */
+    shadow?: boolean;
+    /** Colour scheme. Defaults to `system`. */
+    colorScheme?: 'light' | 'dark' | 'system';
+    /** Theme token overrides, the same shape `@c15t/react` accepts. */
+    theme?: Theme;
+    /** Extra CSS appended after the bundled stylesheet. */
+    css?: string;
+    /**
+     * Include the bundled stylesheet. Defaults to `true`. With `shadow: false`,
+     * set `false` when the page loads `@c15t/browser/styles.css`.
+     */
+    styles?: boolean;
+    /** Ship the DOM without any class names, for fully custom CSS. */
+    noStyle?: boolean;
+    /** Skip enter and exit transitions. */
+    disableAnimation?: boolean;
+    /** Render the banner. Defaults to `true`. */
+    banner?: boolean | ConsentBannerOptions;
+    /** Render the preference centre. Defaults to `true`. */
+    dialog?: boolean | ConsentDialogOptions;
+    /** Render the floating reopen button. Defaults to `false`. */
+    trigger?: boolean | ConsentTriggerOptions;
+}
+/**
+ * Everything `init()` accepts. Queue serializable options, transport
+ * factories, callbacks, and DOM containers through `c15t.push(['config', {...}])` on a no-code site.
+ */
+export interface ConsentClientOptions {
+    /** IAB configuration. Requires the `@c15t/browser/iab` entry. */
+    iab?: ConsentRuntimeOptions['iab'];
+    /**
+     * Transport. A name picks one of the built-in modes; a factory from
+     * `hosted()`, `offline()`, `manifest()` or `custom()` is used as is.
+     * Defaults to `manifest` when a manifest is given, `hosted` when a
+     * `backendURL` is given, otherwise `offline`.
+     */
+    mode?: ProviderTransportFactory | ConsentModeName;
+    /** Backend origin for `hosted` and `manifest` modes. */
+    backendURL?: string;
+    /** Inline consent manifest for `manifest` mode. */
+    manifest?: ConsentManifest;
+    /**
+     * Manifest URL for `manifest` mode. URLs other than the backend's
+     * `/manifest` endpoint require an explicit `backendURL`.
+     */
+    manifestURL?: string;
+    /**
+     * Policy rules for `offline` mode. A preset name such as
+     * `'europeOptIn'` stands in for `policyRulePresets.europeOptIn()`, so a
+     * JSON config or a `data-policy-rules` attribute can name them.
+     */
+    policyRules?: (PolicyRule | PolicyPresetName)[];
+    /** Categories the UI offers. Defaults to every category the policy allows. */
+    consentCategories?: AllConsentNames[];
+    /** Third-party scripts to load once their category is granted. */
+    scripts?: Script[];
+    /** Lifecycle callbacks. */
+    callbacks?: Callbacks;
+    /** Cookie and storage settings. */
+    storageConfig?: StorageConfig;
+    /** Known country, region, language or GPC signal. */
+    overrides?: KernelOverrides;
+    /**
+     * A server-resolved init answer. When it carries a policy and a
+     * decision the runtime renders from it and never calls `/init`.
+     */
+    prefetch?: KernelConfig;
+    /** Identified visitor. */
+    user?: KernelUser;
+    /** Locale and custom messages. */
+    i18n?: Partial<I18nConfig>;
+    /** Privacy policy, cookie policy and terms links. */
+    legalLinks?: LegalLinks;
+    /** Block network requests by URL until consent. */
+    networkBlocker?: RuntimeNetworkBlockerOptions | false;
+    /** Gate iframes by category. On by default. */
+    iframeBlocker?: ConsentRuntimeOptions['iframeBlocker'];
+    /** `false` grants every category and mounts nothing. */
+    enabled?: boolean;
+    /** Host layout and behavior, resolved under the active policy constraints. */
+    presentation?: ConsentPresentation;
+    /** UI options, or `false` for headless use. */
+    ui?: ConsentUIOptions | false;
+    /** Package name reported on `window.c15t`. */
+    pkg?: string;
+}
+/** Handle on a mounted UI. */
+export interface ConsentUIHandle {
+    /** The element appended to the container. */
+    readonly host: HTMLElement;
+    /** Where the surfaces render: the shadow root, or the host itself. */
+    readonly root: ShadowRoot | HTMLElement;
+    /** Re-render against the current snapshot. */
+    update: () => void;
+    /** Remove every surface and the host. */
+    destroy: () => void;
+}
+/** Mounts the prebuilt UI for a client. */
+export type ConsentUIMounter = (client: ConsentClient, options?: ConsentUIOptions) => ConsentUIHandle;
+/** Events a client emits, and their payloads. */
+export interface ConsentClientEventMap {
+    /** The policy resolved and the runtime is ready to render. */
+    ready: ConsentSnapshot;
+    /** A consent value changed. */
+    consent: ConsentSnapshot;
+    /** The surface the runtime wants shown changed. */
+    ui: KernelActiveUI;
+    /** A transport call failed. */
+    error: unknown;
+}
+/** The page's consent client. */
+export interface ConsentClient {
+    /** The runtime that owns this page's kernel. */
+    readonly runtime: ConsentRuntime;
+    /** The kernel: snapshot, commands and events. */
+    readonly kernel: ConsentKernel;
+    /** The options the client was created with. */
+    readonly options: ConsentClientOptions;
+    /** Which transport is in use. */
+    readonly mode: ConsentModeName | 'custom';
+    /** Categories the UI should offer, after policy filtering. */
+    readonly consentCategories: AllConsentNames[];
+    /** The mounted UI, if any. */
+    readonly ui: ConsentUIHandle | null;
+    /** Whether `start()` has run. */
+    readonly started: boolean;
+    /** The current consent snapshot. */
+    getSnapshot: () => ConsentSnapshot;
+    /**
+     * Observe every snapshot change.
+     *
+     * @param listener - Called with each new snapshot.
+     * @returns An unsubscribe function.
+     */
+    subscribe: (listener: (snapshot: ConsentSnapshot) => void) => Unsubscribe;
+    /**
+     * Resolves once the policy is resolved and the UI can render. A
+     * returning visitor with stored consent resolves as soon as init lands
+     * too, so callers can rely on `hasConsented()` afterwards.
+     */
+    ready: () => Promise<ConsentSnapshot>;
+    /**
+     * Whether the given category (or condition) is granted.
+     *
+     * @param condition - A category name or a `has()` condition.
+     */
+    has: (condition: HasCondition<AllConsentNames>) => boolean;
+    /** Whether the visitor has already made a choice. */
+    hasConsented: () => boolean;
+    /** Grant every offered category and close the UI. */
+    acceptAll: () => Promise<SaveResult>;
+    /** Grant only strictly necessary and close the UI. */
+    rejectAll: () => Promise<SaveResult>;
+    /**
+     * Persist a specific set of consents and close the UI.
+     *
+     * @param consents - Categories to grant or deny.
+     */
+    save: (consents: Partial<ConsentState>) => Promise<SaveResult>;
+    /** Confirm the current IAB vendor/purpose draft through the CMP. */
+    saveIAB: () => Promise<SaveResult>;
+    /** Acknowledge a notice without recording category choices. */
+    dismissNotice: () => Promise<NoticeDismissResult>;
+    /** Show the banner. */
+    showBanner: () => void;
+    /** Open the preference centre. */
+    openDialog: () => void;
+    /** Close the preference centre (or banner). */
+    closeDialog: () => void;
+    /**
+     * Switch language and re-resolve translations.
+     *
+     * @param code - A BCP 47 language tag.
+     */
+    setLanguage: (code: string) => void;
+    /**
+     * Replace the geo, language and GPC context.
+     *
+     * @param overrides - The new context.
+     */
+    setOverrides: (overrides: KernelOverrides) => void;
+    /**
+     * Associate the consent record with an external identity.
+     *
+     * @param user - The external user.
+     */
+    identify: (user: KernelUser) => Promise<void>;
+    /**
+     * Listen for a client event.
+     *
+     * Once the policy is resolved, a new `ready` listener runs at once and
+     * a new `ui` listener receives the surface currently up, so wiring
+     * attached after a fast init misses nothing.
+     *
+     * @param event - The event name.
+     * @param listener - Called with the event payload.
+     * @returns An unsubscribe function.
+     */
+    on: <EventName extends keyof ConsentClientEventMap>(event: EventName, listener: (payload: ConsentClientEventMap[EventName]) => void) => Unsubscribe;
+    /**
+     * Mount the prebuilt UI. Throws in the headless build.
+     *
+     * @param options - UI options; defaults to `options.ui`.
+     */
+    mountUI: (options?: ConsentUIOptions) => ConsentUIHandle;
+    /** Start the runtime and mount the UI. Idempotent. */
+    start: () => void;
+    /** Tear everything down. */
+    dispose: () => void;
+}

package/dist-types/ui/actions.d.ts

@@ -0,0 +1,29 @@
+import type { ConsentSnapshot, ConsentPresentation, PromptPresentation, PresentationAction, ResolvedConsentPresentation } from '@c15t/core';
+/** Resolve buttons and geometry with the same policy constraints as React. */
+export declare const resolveActions: (snapshot: ConsentSnapshot, surface: 'prompt' | 'preferences', presentation?: ConsentPresentation, override?: PromptPresentation) => ResolvedConsentPresentation;
+/** What {@link renderActionFooter} needs. */
+export interface ActionFooterParams {
+    /** The resolved actions. */
+    actions: ResolvedConsentPresentation;
+    /** Extra class on the footer root (the surface's `footer`). */
+    footerClassName: string;
+    /** Ship the DOM without class names. */
+    noStyle: boolean;
+    /** Test id for the footer. */
+    testId: string;
+    /** Test id for each sub group. */
+    subGroupTestId: string;
+    /** Label for an action. */
+    label: (action: PresentationAction) => string;
+    /** Test id for an action's button. */
+    buttonTestId: (action: PresentationAction) => string;
+    /** Click handler. */
+    onAction: (action: PresentationAction) => void;
+}
+/**
+ * Render a surface's button footer.
+ *
+ * @param params - Actions, classes and handlers.
+ * @returns The footer element.
+ */
+export declare const renderActionFooter: (params: ActionFooterParams) => HTMLElement;

package/dist-types/ui/banner.d.ts

@@ -0,0 +1,13 @@
+import type { ConsentBannerOptions } from '../types';
+import type { Surface, SurfaceContext } from './surface';
+/**
+ * The cookie banner.
+ *
+ * Reuses the framework banners' stylesheet classes and test IDs.
+ * Shows when the kernel requests a category choice or notice prompt.
+ *
+ * @param ctx - The mount context.
+ * @param options - Copy and behaviour overrides.
+ * @returns The surface.
+ */
+export declare const createBanner: (ctx: SurfaceContext, options: ConsentBannerOptions) => Surface;

package/dist-types/ui/branding.d.ts

@@ -0,0 +1,25 @@
+import type { ConsentSnapshot } from '@c15t/core';
+/** Which surface a branding tag belongs to. */
+export type BrandingVariant = 'footer' | 'dialog-tag' | 'banner-tag';
+/** What {@link renderBranding} needs. */
+export interface BrandingParams {
+    /** The brand the transport resolved. */
+    branding: ConsentSnapshot['branding'];
+    /** Which surface the tag belongs to. */
+    variant: BrandingVariant;
+    /** "Secured by", already translated. */
+    securedBy: string;
+    /** Drop the tag. */
+    hide: boolean;
+    /** Ship the DOM without class names. */
+    noStyle: boolean;
+    /** Test id, so each surface keeps its own. */
+    testId: string;
+}
+/**
+ * Render the "Secured by c15t" tag, or nothing.
+ *
+ * @param params - Branding, placement and copy.
+ * @returns The anchor, or `null` when hidden.
+ */
+export declare const renderBranding: (params: BrandingParams) => HTMLElement | null;

package/dist-types/ui/copy.d.ts

@@ -0,0 +1,28 @@
+import type { ConsentSnapshot } from '@c15t/core';
+import type { CompleteTranslations } from '@c15t/translations';
+/** The copy a surface renders from. */
+export interface SurfaceCopy {
+    /** The resolved bundle, bundled English filling any gaps. */
+    t: CompleteTranslations;
+    /** The resolved language, if the transport reported one. */
+    language: string | undefined;
+    /** Text direction for the resolved language. */
+    dir: 'ltr' | 'rtl';
+}
+/**
+ * Resolve the translations a surface should render.
+ *
+ * Mirrors what the React and Svelte surfaces do: the snapshot's resolved
+ * bundle wins, bundled English fills anything it lacks.
+ *
+ * @param snapshot - The kernel snapshot.
+ * @returns The copy.
+ */
+export declare const resolveCopy: (snapshot: ConsentSnapshot) => SurfaceCopy;
+/**
+ * Title-case a category name for categories without a translation.
+ *
+ * @param name - The category name.
+ * @returns A readable label.
+ */
+export declare const formatCategoryName: (name: string) => string;

package/dist-types/ui/dialog.d.ts

@@ -0,0 +1,14 @@
+import type { ConsentDialogOptions } from '../types';
+import type { Surface, SurfaceContext } from './surface';
+/**
+ * The preference centre dialog.
+ *
+ * Opens when the kernel says `activeUI === 'dialog'`. Modal: focus is
+ * trapped, the page stops scrolling, Escape closes. Clicking the backdrop
+ * does not, matching the other adapters.
+ *
+ * @param ctx - The mount context.
+ * @param options - Dialog options.
+ * @returns The surface.
+ */
+export declare const createDialog: (ctx: SurfaceContext, options: ConsentDialogOptions) => Surface;