Kernel API

Get a kernel

The kernel holds consent state and runs commands. Every JavaScript setup has one:

• consent.kernel, from init() in @c15t/browser.
• runtime.kernel, from createConsentRuntime in c15t/runtime.
• A kernel you create yourself, as shown below.

The kernel alone supplies state and commands. It renders nothing, loads no script and reads no storage; the modules around it do that.

const unsubscribe = kernel.subscribe((snapshot) => {
	console.log(snapshot.resolution.status, snapshot.effectivePermissions);
});

This fragment assumes one of the kernels above. Keep unsubscribe and call it during teardown.

Read state

A snapshot keeps the same object for a field whose value did not change, so previous.effectivePermissions === next.effectivePermissions tells you permissions did not change.

Choose commands by intent

Commands are asynchronous and are the only way to record anything.

save(input, context) takes a second argument. context.categories narrows 'all', 'none' or an empty input to the categories your UI displays, which is how @c15t/browser limits Accept All to the dialog's categories. context.vendors records vendor-level grants.

A save updates permissions and notifies subscribers before the backend request starts. SaveResult.ok reports the request. When it fails, the choice stays in effect and the payload is queued for retry. Consent state documents the ordering.

Change inputs and UI state

set operations run synchronously and notify subscribers. None of them records a choice.

Apply stored records

Pass validated records as initialRecords to createConsentKernel(), such as a choice read from a cookie with readStoredRecordsFromCookieHeader(). They apply without counting as a visitor action. In the browser, createPersistence() reads storage into the kernel on mount and keeps tabs in step afterwards.

Events

kernel.events.on(type, listener) returns an unsubscribe function. Each listener receives the event object.

Use choice:recorded to react to a visitor's decision and permissions:changed to start and stop code. Callbacks explains the difference.

How listeners are notified

kernel.subscribe() and kernel.events.on() listeners run synchronously when a change commits, in registration order. Each receives the frozen snapshot that change produced.

• A listener that throws does not stop the listeners after it or fail the command that caused the change. In a browser page c15t passes the error to reportError. Everywhere else, including Bun and Deno servers where reportError would end the process, it logs the error with console.error.
• A listener can call commands and setters. Before the nested call returns, every other listener receives the change in progress and then the new one. No listener misses a change, such as a denial that another listener immediately reverses, or receives changes out of order.
• A listener added during a notification first receives the next change. A listener removed during a notification is not called again.
• Listeners that keep changing consent in response to each other are stopped after 100 nested notifications, and the error is reported. Notifications already queued still arrive, so other listeners end on the current snapshot. A listener that changes consent after that point is not called again.

Create a kernel yourself

Most apps should use createConsentRuntime or @c15t/browser, which connect the modules for you. Create the kernel directly only when you need to choose every module:

import { createConsentKernel, createHostedTransport } from 'c15t';
import { createPersistence } from 'c15t/modules/persistence';
import { createScriptLoader } from 'c15t/modules/script-loader';

import { scripts } from './scripts';

export const startConsentKernel = async function startConsentKernel(
	backendURL: string
) {
	const kernel = createConsentKernel({
		transport: createHostedTransport({ backendURL }),
	});
	// Each module is yours to create and dispose. This kernel has no iframe
	// blocker, network blocker, data clearing or reload after revocation.
	const persistence = createPersistence({ kernel });
	const loader = createScriptLoader({ kernel, scripts });
	await kernel.commands.init();
	return {
		dispose() {
			loader.dispose();
			persistence.dispose();
			kernel.dispose();
		},
		kernel,
	};
};

This kernel stores choices and loads scripts. It has no iframe blocker, network blocker or data clearing, and it does not reload the page when a visitor withdraws permission, so a vendor that already ran keeps running. Add each one you need from its c15t/modules/* entry point, and dispose it before the kernel:

watchRevocationReload({ kernel, isEnabled, getOnBeforeReload? }) reloads the page after a save turns off something that was allowed. It returns a disposer.

createConsentKernel(config) takes a transport, not a transport factory. Use createHostedTransport({ backendURL }) or createOfflineTransport() from c15t, or your own object with init and save. Other useful config fields:

Construction has no side effects, so a server can build a kernel and read its snapshot.

Check it works

1. Subscribe to the kernel and log policyPending and resolution.status. After commands.init(), policyPending is false and the status is matched.
2. Add an events.on('choice:recorded', …) listener. It logs once for each accept, reject or save, and not on reload.
3. Call kernel.dispose(). Background retries stop; getSnapshot() still works.