@themvora/core

Provides the theme model and store, the runtime and selection controller, persistence and cross-tab broadcast, sunrise/sunset scheduling, transitions and animation, DOM and CSS-variable bindings, the plugin system, library adapters, token resolution, validation, generation, and migration.

Generated from packages/core/src by apps/docs/scripts/generate-api-reference.mjs. Do not edit by hand — run pnpm --filter @themvora/docs api:generate.

Functions

auditActionProminence(theme): ActionProminence

Measure whether a theme's action fill reads as a control.

Why this is a third contract, not a fourth context

1. semantic pair — primary against primaryForeground must be readable.
2. context — where each role may be used, and with whose judgement.
3. prominence — a generated fill must separate from the canvas, because a fill that does not has stopped reading as a control.

It cannot be expressed as "primary must clear X:1 against background" globally, because that would condemn every dark brand anchor. Hence the anchored flag: the invariant binds generated fills and merely reports anchored ones — Slack's aubergine is 1.42:1 against the dark canvas, and that is the brand being the brand.

Returns ActionProminence — The measurement, with anchored telling the caller which rule applies.

auditSemanticContexts(theme): ContextResult[]

Evaluate every declared context against a theme.

Returns ContextResult[] — One result per context, in declaration order.

auto(tokenName, lookup): string

Resolve an auto() foreground token by deriving its value from a base color token.

Given a token name ending in Foreground/foreground (or Fg), the base token is looked up via the provided resolver and its contrast foreground is returned. When the base color cannot be resolved, #000000 is returned.

Returns string — A black or white foreground color string.

buildThemeCssMap<T extends ThemeDefinition<string>>(themes, options): Record<string, Record<string, string>>

Build a lookup map of theme keys to flat CSS variables.

Each theme is registered twice:

• under its own name (e.g. "sunrise-light")
• under a family:mode key (e.g. "sunrise:light") so that a persisted family + effective mode can be resolved without knowing theme names.

See also: createThemeBootstrapScript

Returns Record<string, Record<string, string>>

calculateSunTimes(date, args...): SunTimes

Compute today's sunrise and sunset using the standard NOAA solar algorithm (zenith-based, corrected for the equation of time and for longitude).

latitude and longitude are optional: when omitted (or when an options object is passed instead), the location is resolved from timeZone or the visitor's browser timezone via resolveSolarLocation. Passing neither coordinates nor a timezone means every visitor gets sunrise/sunset for their own location automatically.

// Explicit coordinates (unchanged behavior).
calculateSunTimes(date, 48.8566, 2.3522);

// Resolve from the visitor's timezone.
calculateSunTimes(date);

// Resolve from an explicit timezone.
calculateSunTimes(date, { timeZone: "Asia/Kathmandu" });

Returns SunTimes — The sunrise/sunset pair as absolute instants (see SunTimes).

The local-clock contract. Both returned Dates are absolute instants computed from the location's longitude and the day's solar declination. Their local representation is therefore the correct wall-clock time for that day, and it follows daylight-saving transitions because it is derived from the real UTC instant rather than from a fixed offset.

Longitude matters. Solar noon at a location occurs at 720 - 4·longitude - eqTime minutes UTC (east-positive longitude), and sunrise/sunset sit ±4·hourAngle minutes either side of it. Treating that result as local clock time — which the previous implementation did, because it never applied the longitude term — put the switch at the wrong hour wherever the local time-zone meridian differs from the location's longitude.

timeZone resolves coordinates, not the clock. It is used only to pick the latitude/longitude pair; the returned instants are read on the host's own clock. This API therefore does not support computing "sunrise in Tokyo" on a server in London: the coordinates would be Tokyo's but the day boundary and the displayed wall-clock time would be the server's. Pass explicit coordinates for the visitor's location, or run the calculation in the visitor's browser.

Polar day and polar night are reported through SunTimes.polar. The hour-angle formula has no solution when the sun stays above or below the horizon, and the previous implementation clamped cosH into [-1, 1], which produced a zero-length day: sunrise equal to sunset, so the daytime test was never true and a polar-day visitor got the dark theme at noon.

cancelThemeAnimation(target): void

Abort any in-flight theme animation for target and remove its styles.

Returns void

chooseForeground(role, background, ctx): Oklch

Choose the foreground for a role on a surface.

if the preferred ink meets the target:  use it
else if the other ink meets it:         use that
else:                                   use the better of the two, and let the solver repair it

Why the target, and not the floor

The internal target (4.75) is used here rather than the published floor (4.5), because that is what makes the preference free: whenever the preferred ink clears 4.75 it is also the higher-ratio ink, so honouring the preference and maximising contrast agree. The two rules only diverge in the narrow band where white measures 4.50–4.58, and there the fallback takes the higher ratio.

This is why the change is a refactor rather than a behaviour change for existing themes — see the note in theme-generation.md. What it buys is that the rule is now explicit, per-role and testable, instead of being an emergent property of a >= comparison inside bestInk.

Returns Oklch — The chosen ink.

clearMigrations(): void

Remove all registered migration steps, resetting the migration system to an empty state.

Returns void

composeTheme<TName extends string>(name, sources...): ThemeDefinition<TName>

Compose a theme by layering multiple sources (e.g. a family theme, a mode override, and local tokens), later sources winning.

See also: mergeThemeDefinitions, defineTheme

Returns ThemeDefinition<TName>

computeFingerprint(themes, defaultTheme?): string

Fingerprints a theme registry so a persisted selection from an older build — different themes, or a different defaultTheme — is ignored rather than applied against themes it was never valid for.

See also: ThemeBootstrapCookieSource, buildBootstrapPlan

Returns string — A stable fingerprint string, or "" when themes is empty.

The result is written to the theme-fingerprint cookie and compared on the next request, so it is part of the stable cookie contract documented in VERSIONING.md — changing the format invalidates every visitor's persisted selection on their next visit.

It lives here, in core, because four SSR integrations (Next, Nuxt, Astro, Remix) previously each carried a byte-identical private copy. Any edit to one of them would have silently broken cross-framework persistence with nothing to catch it.

contextFailures(theme): { advisory: ContextResult[]; required: ContextResult[] }

The contexts a theme fails, split by whether the generator promised them.

Returns { advisory: ContextResult[]; required: ContextResult[] } — required failures are bugs; advisory failures are declared gaps.

contrast(background): string

Compute a readable foreground color for a given background color.

Returns #000000 when the background is light enough (relative luminance above 0.179), otherwise #ffffff. Accepts a hex color with or without the leading #; non-hex input falls back to #000000.

Returns string — A black or white foreground color string.

createAccessibilityPlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Creates a plugin that validates theme contrast for accessibility.

The plugin runs a WCAG contrast check on the active theme after every theme change and reports any violations that fail AA normal contrast, either by emitting a TV_A11Y_CONTRAST_VIOLATION diagnostic or by invoking the onViolation callback.

See also: AccessibilityPluginOptions

Returns ThemePlugin<T> — An "accessibility" theme plugin.

Violations are reported only when the theme fails AA normal contrast and at least one check fails. warnOnly chooses the diagnostic's level. The failing checks travel as the diagnostic's structured context, so they stay available to the console and to any consumer of the diagnostics stream rather than being flattened into the message.

const manager = createPluginManager();
manager.use(createAccessibilityPlugin({
  warnOnly: true,
  onViolation: ({ themeName, checks }) => report(themeName, checks),
}));

createAdapterRegistry<T extends ThemeDefinition<string>>(runtime): AdapterRegistry<T>

Create the runtime-owned adapter registry for a theme runtime.

Registering an adapter installs it; the registry tracks reference counts so composition (React Strict Mode, Svelte lifecycles, nested providers) is deterministic. use is idempotent per adapter instance and returns an AdapterRegistration whose dispose() uninstalls exactly that instance when its own reference count drops to zero. Registering a different adapter instance under an already-used id replaces the previous one.

Returns AdapterRegistry<T> — The adapter registry bound to runtime.

const registry = createAdapterRegistry(runtime);
const handle = registry.use(adapter);
// ... later
handle.dispose();

createAnimationsPlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Creates a plugin that animates theme changes with CSS transitions.

The plugin applies a CSS transition to the target element before a theme change so the resulting token updates animate smoothly, and removes the transition when the plugin is destroyed.

See also: AnimationsPluginOptions

Returns ThemePlugin<T> — An "animations" theme plugin.

The plugin opts out of View Transitions by default; it provides CSS transition properties rather than page-level crossfades. onDestroy removes the transition from the target element.

const manager = createPluginManager();
manager.use(createAnimationsPlugin({ transition: { duration: 500 } }));

createBroadcastPlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Creates a plugin that synchronizes the theme selection across browser tabs and windows.

The plugin subscribes to incoming selection messages when the runtime is created and applies the received mode/family to the runtime, and broadcasts the selection after every persist. It uses a BroadcastChannel-based adapter by default when available.

See also: BroadcastPluginOptions

Returns ThemePlugin<T> — A "broadcast" theme plugin.

onDestroy unsubscribes from incoming messages and closes the default channel. When no adapter is available the plugin is inert.

const manager = createPluginManager();
manager.use(createBroadcastPlugin({ channelName: "my-app-theme" }));

createCSSVariablesBinding(store, options): { destroy: void; setTransition: void } | null

Create a binding that keeps CSS custom properties (--theme-*) on a target element (default <html>) in sync with the store. Applies the current theme immediately on creation and diffs updates.

See also: themeToCSSVariables, CSSVariablesOptions

Returns { destroy: void; setTransition: void } | null

createDebuggerPlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Creates a plugin that logs theme runtime activity to the console.

The plugin logs theme changes, active theme tokens, and persistence events (before and after) to the console, gated by the corresponding options.

See also: DebuggerPluginOptions

Returns ThemePlugin<T> — A "debugger" theme plugin.

const manager = createPluginManager();
manager.use(createDebuggerPlugin({ label: "[my-app]" }));

createDefaultPersistence(): ThemeSelectionPersistenceAdapter | null

Creates the default persistence adapter: a localStorage-backed selection adapter under the "theme-selection" key.

Returns null when window is unavailable (SSR) or storage access throws. Cross-tab changes are surfaced through the storage event.

See also: ThemeSelectionPersistenceAdapter, createThemePersistence

Returns ThemeSelectionPersistenceAdapter | null — A persistence adapter, or null when storage is unavailable.

createDevToolsPlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Creates a plugin that exposes the theme runtime to browser devtools.

When enabled, the plugin registers a devtools hook on window that exposes the current themes, selection, active theme, and history, so a devtools extension can inspect the runtime state.

See also: DevToolsPluginOptions

Returns ThemePlugin<T> — A "devtools" theme plugin.

The hook is only registered in browser environments. onDestroy clears the internal runtime reference.

Entries are added to the same window.__THEMVORA_DEVTOOLS__ set that @themvora/devtools's inspector plugin uses, and must satisfy that set's declared shape — getState(), getEntries(), getPerformance(). This plugin records no entries or performance samples, so those two return empty arrays; the point is that a consumer enumerating the set can call all three on every member without a type check. Use @themvora/devtools's createDevToolsPlugin instead when you want the recorded entries and timings.

const manager = createPluginManager();
manager.use(createDevToolsPlugin());

createDiagnostic(input): ThemeDiagnostic

Create a ThemeDiagnostic.

Pure: no console access, no environment reads, no deduplication. The docs link is derived from the code so call sites never repeat it.

See also: emitDiagnostic

Returns ThemeDiagnostic — A diagnostic value. Creating one has no side effects.

const diagnostic = createDiagnostic({
  code: "TV_MODE_INVALID",
  level: "warning",
  message: 'setMode() received an unknown mode "purple".',
  context: { api: "setMode", property: "mode", received: "purple", expected: "light | dark | system" },
  hint: "Pass one of the three valid modes, or omit the call.",
});

createDOMBinding(store, options): { apply: __type(theme: ThemeDefinition, emitOptions?: { suppressTransition?: boolean }): void; destroy: void; setTransition: void } | null

Create a binding that syncs the store theme to the DOM: data-theme, data-theme-mode, data-theme-family, the dark class, and the color-scheme style — with transition support.

See also: DOMBindingOptions, createCSSVariablesBinding

Returns { apply: __type(theme: ThemeDefinition, emitOptions?: { suppressTransition?: boolean }): void; destroy: void; setTransition: void } | null

createGenerationPlugin<T extends ThemeDefinition<string>>(options?): GenerationPlugin<T>

Creates a plugin that participates in theme generation.

The plugin is inert until GenerationPlugin.generate is called: it registers no tokens of its own and its transformTokens hook is the identity. Generating goes through generateTheme, so the plugin and the runtime cannot disagree about what a seed produces.

See also: GenerationPluginOptions

Returns GenerationPlugin<T> — A "theme-generation" plugin with a generate method.

const plugin = createGenerationPlugin({ seed: "#6366f1" });
const { light, dark } = plugin.generate({ family: "brand", style: "brand" });

createHistoryPlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Creates a plugin that configures the runtime's theme history.

The plugin applies the given history options (notably maxSteps) to the runtime's history when the runtime is created.

See also: HistoryPluginOptions

Returns ThemePlugin<T> — A "history" theme plugin.

const manager = createPluginManager();
manager.use(createHistoryPlugin({ maxSteps: 20 }));

createMultiWindowSync(options): ThemeSelectionBroadcastAdapter

Sync theme selection across browser tabs/windows via BroadcastChannel (with a SharedWorker + storage fallback).

Returns ThemeSelectionBroadcastAdapter

createNoopSync(): ThemeSelectionBroadcastAdapter

Create a no-op theme-selection sync adapter.

Every method is a safe no-op: post discards the value, subscribe returns an unsubscribe that does nothing, and destroy does nothing. Used as the final fallback when no cross-tab strategy is available.

Returns ThemeSelectionBroadcastAdapter — A ThemeSelectionBroadcastAdapter that performs no synchronization.

createOverlayScrollbar(store, options): OverlayScrollbarHandle | null

Framework-agnostic, theme-aware scrollbar overlay engine.

The browser performs all scrolling — this only renders + animates a visual overlay that tracks it, so inertia, touch, wheel, keyboard and accessibility remain native. Colors come from Themvora tokens, so the overlay re-themes with the rest of the app (no flashes). It tracks the document plus every scrollable element on the page by default (anywhere a native scrollbar would appear); the native track is hidden automatically — no manual CSS required.

Returns OverlayScrollbarHandle | null

createPersistencePlugin<T extends ThemeDefinition<string>>(options?): ThemePlugin<T>

Creates a plugin that persists the theme selection and restores it on startup.

The plugin reads the saved selection when the runtime is created (if readOnInit is enabled) and writes the selection to the adapter after every persist. It uses a localStorage-backed adapter by default in the browser and is inert in non-browser environments unless a custom adapter is given.

See also: PersistencePluginOptions

Returns ThemePlugin<T> — A "persistence" theme plugin.

The default adapter also subscribes to cross-tab storage events so the selection stays in sync across tabs. onDestroy releases the adapter and runtime references.

const manager = createPluginManager();
manager.use(createPersistencePlugin({ key: "my-app-theme" }));

createPluginManager<T extends ThemeDefinition<string>>(): PluginManager<T>

Creates a PluginManager for registering and coordinating theme plugins.

The returned manager stores plugins by name, orders them by ascending priority (default 10) for hook dispatch, and coordinates destruction.

See also: PluginManager, ThemePlugin

Returns PluginManager<T> — A new, empty plugin manager.

Registering a plugin whose name is already present is skipped with a console warning and returns a no-op disposer. destroy invokes onDestroy on every plugin (in priority order) and clears the registry.

destroy is failure-isolated: a plugin whose onDestroy throws is reported with TV_PLUGIN_DESTROY_FAILED and the remaining plugins are still destroyed, so one broken plugin cannot leak the rest.

const manager = createPluginManager<MyTheme>();
const dispose = manager.use(createPersistencePlugin());
manager.list(); // [persistence plugin]
dispose();      // removes it

createPrePaintScrollbarCSS(): string

The hiding CSS, for SSR output (e.g. Next inlines it as a <style> in <head>). Use together with the tv-scrollbar class on <html>.

Returns string

createPrePaintScrollbarScript(options): string

Generate a blocking <script> that hides the native scrollbar before first paint. The script is idempotent — calling it multiple times is safe. On coarse-pointer devices it returns early (unless touch is forced), so native scrollbars are kept.

Returns string

createProvidedThemesSource<T extends ThemeDefinition<string>>(runtime): ProvidedThemesSource<T>

Create a reactive source over one provider's theme collection.

The derivation runs once per settled change to the provider's registry and is cached in between, so:

• the returned array is referentially stable while nothing changes,
• a register / unregister / use / configure is reflected on the next read,
• two providers never share a collection.

See also: normalizeProvidedThemes

Returns ProvidedThemesSource<T> — A source with get() and subscribe().

const source = createProvidedThemesSource(runtime);
source.subscribe(() => console.log(source.get().length));

createScheduledPlugin<T extends ThemeDefinition<string>>(options): ThemePlugin<T>

Creates a plugin that switches the theme selection by time of day.

The plugin resolves a light/dark theme pair and installs a scheduled theme binding that applies the appropriate theme based on the visitor's local sunrise/sunset times. It re-resolves the pair when the theme family changes so auto-derived themes follow the current selection.

See also: ScheduledPluginOptions

Returns ThemePlugin<T> — A "scheduled" theme plugin.

When the light/dark pair cannot be resolved, the plugin emits a TV_SCHEDULE_THEME_UNRESOLVED diagnostic and does not install a binding. onDestroy destroys the binding, unsubscribes from the store, and clears all internal state.

const manager = createPluginManager();
manager.use(createScheduledPlugin({
  lightTheme: "day",
  darkTheme: "night",
  timeZone: "Asia/Kathmandu",
}));

createScheduledThemeBinding<T>(store, options): { destroy: void; getEnabled: void; getLocation: void; setEnabled: void; setLastSyncTime: void }

Create a scheduled theme binding that applies a light theme during daytime and a dark theme at night.

The binding resolves a location (explicit coordinates, an explicit timeZone, or browser auto-detection), computes sunrise/sunset, applies the matching theme immediately, and re-checks on checkInterval. It can be toggled at runtime via setEnabled and stopped via destroy (which is idempotent and clears the timer).

See also: ScheduledThemeBindingOptions

Returns { destroy: void; getEnabled: void; getLocation: void; setEnabled: void; setLastSyncTime: void } — A controller exposing destroy, setLastSyncTime, setEnabled, getEnabled and getLocation.

const binding = createScheduledThemeBinding(store, {
  lightTheme,
  darkTheme,
  timeZone: "Asia/Kathmandu",
});
// ... later
binding.destroy();

createScopedThemeBinding<T extends ThemeDefinition<string>>(themes, target, selection, options): { destroy: void; getTheme: void; refresh: void; setLocalThemes: void; setTransition: void; update: void }

Create a scoped-theme binding for an element: applies the scoped theme's CSS variables inline on the element and cleans them up on destroy.

See also: ScopedThemeBindingOptions

Returns { destroy: void; getTheme: void; refresh: void; setLocalThemes: void; setTransition: void; update: void }

createSharedWorkerSync(): ThemeSelectionBroadcastAdapter | null

Create a theme-selection broadcast adapter backed by a SharedWorker.

The adapter relays theme selections between tabs/windows through a shared worker, so every tab connected to the same worker receives the selection. It requires SharedWorker support; when unavailable (or when the worker cannot be created) it returns null (e.g. during SSR).

See also: destroySharedWorkerUrl

Returns ThemeSelectionBroadcastAdapter | null — A ThemeSelectionBroadcastAdapter, or null when SharedWorker is unavailable.

const sync = createSharedWorkerSync();
sync?.post({ mode: "dark", family: "plum" });

createStorageEventSync(key, view): ThemeSelectionBroadcastAdapter

Create a theme-selection sync adapter backed by localStorage and the storage event.

The adapter writes the selection as JSON under a single key and notifies subscribers of cross-tab changes through the storage event. It requires a Window; when none is available it returns a no-op adapter (e.g. during SSR).

See also: createThemeBroadcast, MultiWindowSyncOptions

Returns ThemeSelectionBroadcastAdapter — A ThemeSelectionBroadcastAdapter.

const sync = createStorageEventSync();
sync.post({ mode: "dark", family: "plum" });

createSyncFirstRoot<TRoot extends SyncFirstRenderRoot>(createRoot, flushSync, options): CreateRootLike<TRoot>

Wraps a React createRoot so the first render call on each root it creates is committed synchronously.

See also: themvoraVitePlugin

Returns CreateRootLike<TRoot> — A createRoot that commits its first render synchronously.

React's concurrent root schedules the initial commit, so the browser can paint a frame with the container still empty before React commits — one frame, ~33 ms, visible as the UI blinking on reload. flushSync around that first render closes it, and it has to happen at the root: the offending frame is painted before any of the application's React code runs, so no provider, insertion effect or layout effect is in time.

Only the first render of each root is flushed. Every later render keeps React's normal concurrent scheduling, so transitions, Suspense and time-slicing behave exactly as before.

This is deliberately a plain function of its dependencies rather than something that reaches for React globals, so it can be unit-tested against stubs — the behaviour it encodes (first render flushed, later renders not) is otherwise only observable in a real browser.

createSystemThemeBinding<T extends ThemeDefinition<string>>(store, options): { destroy: void } | null

Create a binding that applies the theme for "system" mode, following prefers-color-scheme live.

See also: SystemThemeBindingOptions

Returns { destroy: void } | null

createThemeBootstrapScript<T extends ThemeDefinition<string>>(options): string

Generate an inline, blocking script that applies the persisted theme before first paint, preventing a flash of the wrong (or missing) theme on reload.

The script reads the saved selection from localStorage, resolves the theme for the effective mode ("system" is resolved against prefers-color-scheme), and writes the CSS variables plus DOM effects onto document.documentElement.

See also: buildThemeCssMap, createPrePaintScrollbarScript

Returns string

createThemeBroadcast(options): ThemeBroadcastAdapter | null

Create a theme-mode broadcast adapter backed by BroadcastChannel.

The adapter publishes the mode to a channel and notifies subscribers of modes broadcast by other tabs/windows. It requires BroadcastChannel support (or a custom channel); when neither is available it returns null (e.g. during SSR).

See also: createStorageEventSync, ThemeSelectionBroadcastAdapter

Returns ThemeBroadcastAdapter | null — A ThemeBroadcastAdapter, or null when no channel is available.

const broadcast = createThemeBroadcast({ channelName: "my-theme-mode" });
broadcast?.post("dark");

createThemeDebugger<T extends ThemeDefinition<string>>(store, options?): ThemeDebugger<T>

Create a debugger that records theme changes on a theme store.

The debugger subscribes to the store and records an event whenever the current theme changes. Call ThemeDebugger.record before a change to attribute it to a specific source and label; otherwise the change is attributed to "user". History is capped at maxEvents entries.

See also: ThemeDebugger

Returns ThemeDebugger<T> — A ThemeDebugger bound to the store.

const debugger = createThemeDebugger(store, { maxEvents: 100 });
debugger.record("user", "switched to dark");

createThemeDiff(prev, next, prefix?): ThemeDiff

Theme Diff Engine.

Compares the previously applied CSS variables against the incoming theme's variables per token group. Comparing the final resolved values (rather than raw theme definitions) means two themes that resolve to identical colors produce no diff — and nothing animates.

Returns ThemeDiff

createThemeHistory<T extends ThemeDefinition<string>>(store, options?): ThemeHistory<T>

Creates an undo/redo history controller for a theme store.

See also: ThemeHistory, ThemeStore

Returns ThemeHistory<T> — A new theme history controller.

const history = createThemeHistory(store, { maxSteps: 20 });
history.undo();

createThemeLifecycle<T extends ThemeDefinition<string>>(): ThemeLifecycle<T>

Creates a typed lifecycle event emitter for runtime events.

See also: ThemeLifecycle, ThemeLifecycleEventMap

Returns ThemeLifecycle<T> — A new lifecycle controller.

const lifecycle = createThemeLifecycle();
const off = lifecycle.on("afterThemeChange", ({ theme }) => log(theme));
lifecycle.emit("afterThemeChange", { theme });
off();

createThemeModeController<T extends ThemeDefinition<string>>(options): { setMode: __type(nextMode: ThemeMode): void; destroy: void; getMode: void }

Create a theme-mode controller that resolves a mode into a concrete theme and keeps it applied to the store.

In system mode it follows the OS color-scheme preference live via a system binding; in light/dark mode it applies the corresponding theme directly. setMode refuses a value that is not "light", "dark" or "system": the call is ignored — nothing is applied, persisted or broadcast — and a TV_MODE_INVALID diagnostic is emitted, so getMode() never reports a mode the runtime cannot render. Mode changes are persisted and broadcast when the corresponding adapters are provided. The returned controller is safe to destroy: after destroy() its methods become no-ops and all subscriptions are released.

A persistence or broadcast adapter that throws does not abort the change: the resolved theme is still applied and the failure is reported as a TV_SYNC_FAILED diagnostic, so getMode() never reports a mode the screen is not showing.

See also: ThemeSelectionState, createThemePersistence

Returns { setMode: __type(nextMode: ThemeMode): void; destroy: void; getMode: void } — A controller exposing getMode, setMode and destroy.

const controller = createThemeModeController({
  store,
  lightTheme,
  darkTheme,
  persistence: createThemePersistence(),
});
controller.setMode("dark");

createThemePersistence(options): ThemePersistenceAdapter | null

Create a theme-mode persistence adapter backed by Storage.

The adapter reads/writes the mode under a single key and notifies subscribers of cross-tab changes through the storage event. It requires a Window; when none is available it returns null (e.g. during SSR).

See also: createDefaultPersistence, ThemeSelectionPersistenceAdapter

Returns ThemePersistenceAdapter | null — A ThemePersistenceAdapter, or null when no Window is available.

const persistence = createThemePersistence({ key: "my-theme-mode" });
persistence?.set("dark");

createThemeReadoutScript(): string

Builds the inline script that fills in bootstrap readouts and reconciles selection controls: the parts of the page that display or reflect a theme-derived value the server cannot know.

See also: createThemeBootstrapScript, readBootstrapState

Returns string — The script body to emit at the end of <body>, after the elements it patches exist.

Three kinds of element opt in, and all three are reconciled from the same three values — the resolved theme, the mode selection and the family selection — because a control that lags the canvas by one value is the same bug in a smaller window:

Why this exists: a server-rendered readout or control can only show the server's resolution, and for "system" mode — or for any prerendered page, which has no request to read a cookie from — that is a fallback the browser overrides before the first paint. The canvas is corrected by the bootstrap, but the text and the pressed state are not, so they settle once after hydration, which is the last visible difference on an otherwise static page. On a page that reloads repeatedly it reads as the label "fluctuating" between the two themes.

data-tv-pressed writes aria-pressed and nothing else. That is the whole point: the accessible state is the visual state, so a token class keyed off aria-pressed needs no second attribute to keep in step, and a screen reader can never announce a pressed option the page does not show as pressed.

Patching before the first paint closes that, but only if the framework then leaves the element alone. In React that means pairing a readout with suppressHydrationWarning on the same element: React renders its own value during hydration, sees the DOM already differs, and — with the attribute — neither warns nor rewrites. The framework's own post-hydration render then produces the live value, which is the same value the script wrote, so nothing moves. Without the suppression React would rewrite the text back to the server's fallback and re-introduce the settle.

It is deliberately placed at the end of the body: the blocking script runs in <head>, before these elements have been parsed, so it cannot patch them.

It reads the live document, not the page's build-time state. The values come from <html>'s own data-theme / data-theme-selection-* attributes, which by this point describe what the visitor is actually looking at, and only fall back to the published bootstrap payload when those attributes are absent. That is what makes the script idempotent, and idempotence is load-bearing rather than tidy: <ClientRouter /> re-executes inline body scripts on a client-side navigation, so this runs again on every navigation — after the incoming page's readouts have already been brought up to date. A script that wrote the initial selection would undo that, and every readout would revert to the page-build default until the next theme change. Measured on the example app: with the payload as the source, navigating from / with cocoa-dark selected left the readouts at mint-light / system / mint while the document was painted cocoa-dark.

createThemeRegistry<T extends ThemeDefinition<string>>(options?): ThemeRegistry<T>

Creates a theme registry.

See also: ThemeRegistry, resolveThemeRegistry

Returns ThemeRegistry<T> — A new ThemeRegistry.

const registry = createThemeRegistry({ themes: [lightTheme, darkTheme] });
registry.get("light");

createThemeRuntime<T extends ThemeDefinition<string>>(options): ThemeRuntime<T>

Creates an independent Themvora runtime — the single entry point for theming.

The runtime wires together the theme store, selection controller (mode/family/system binding), persistence, broadcast (cross-tab sync), history, scheduling, the DOM + CSS-variable bindings, and the adapter registry.

See also: ThemeRuntime, createThemeStore

Returns ThemeRuntime<T> — A new ThemeRuntime instance.

The returned runtime must be destroyed when its owning application lifecycle ends.

const runtime = createThemeRuntime({
  themes: [lightTheme, darkTheme],
  defaultTheme: "light",
  initialMode: "system",
});
runtime.selection.setMode("dark");

createThemeSchedule<T extends ThemeDefinition<string>>(store, themes, options): ThemeSchedule

Framework-neutral sunrise/sunset scheduling controller. Wraps the core createScheduledThemeBinding engine with an explicit on/off switch and a reactive state snapshot (sunrise, sunset, nextTransition, ...) so frameworks can expose it through their native accessors.

lightTheme and darkTheme are optional: when omitted the schedule derives them from the currently selected theme's family (e.g. current plum-dark → scheduled plum-light/plum-dark) and falls back to the built-in neutral light/dark themes, re-resolving whenever the user switches theme family.

The engine itself lives entirely in core — every framework wrapper talks to this single contract.

Returns ThemeSchedule

createThemeScrollbar(store, options): OverlayScrollbarHandle | null

Alias landing in the public API.

Returns OverlayScrollbarHandle | null

createThemeSelectionBroadcast(options): ThemeSelectionBroadcastAdapter | null

Create a broadcast adapter that publishes selection changes to other tabs/windows and applies incoming changes.

Returns ThemeSelectionBroadcastAdapter | null

createThemeStore<T extends ThemeDefinition<string>>(options): ThemeStore<T>

Creates a theme store: a framework-free container for the active theme.

The store holds the current theme and notifies subscribers when it changes. Use the higher-level createThemeRuntime for the full runtime; use the store directly when you only need a reactive current-theme container.

See also: ThemeStore, createThemeRuntime

Returns ThemeStore<T> — A new theme store.

const store = createThemeStore({ initialTheme: lightTheme });
store.subscribe((theme) => console.log(theme.name));
store.set(darkTheme);

createTransitionPlan(diff, options?, env?): TransitionPlan | null

Transition Planner.

Turns a ThemeDiff into a concrete TransitionPlan:

• colors animate through the registered theme custom properties on :root,
• every other changed group contributes the concrete CSS properties it maps to (radius → border-radius, spacing → padding/margin/gap, …).

Returns null when there is nothing animatable: transitions disabled, reduced motion, an "instant" preset, or a diff where only non-animatable groups (layout/z-index/breakpoints) changed.

Returns TransitionPlan | null

darkModeCSSTemplate(variables): string

Generate a @media (prefers-color-scheme: dark) CSS block carrying the given variables.

See also: systemModeCSSTemplate

Returns string — A @media (prefers-color-scheme: dark) block targeting :root, escaped so it cannot terminate a <style> element (</ becomes </, which CSS parses identically).

This is a pre-script fallback only, and it cannot beat an inline style on the same element: inline declarations outrank every stylesheet rule regardless of specificity. So it is only safe when nothing inlines the light variables — do not pair it with a server render that writes them onto <html>, or an OS-dark visitor keeps the light ones and this block is inert. When the resolved mode is "system", use systemModeCSSTemplate instead: it emits both schemes and expects no inline variables.

defineTheme<Name extends string, T extends ThemeDefinition<Name>>(theme): T

Define a theme. Currently returns the definition unchanged; it exists to give themes a consistent shape and future validation.

See also: extendTheme, composeTheme

Returns T

defineThemvoraConfig<T extends ThemeDefinition<string>>(config): ThemvoraConfig<T>

Declares the application's Themvora configuration.

See also: ThemvoraConfig

Returns ThemvoraConfig<T> — The same object, typed.

An identity function. Its job is to give the configuration a name, a type and a validation point, so the Vite plugin can discover it by convention and the provider can consume the same object rather than a copy of it.

// At the project root
import { defineTheme, defineThemvoraConfig } from "@themvora/core";

const themes = [
  defineTheme({
    name: "brand-light",
    meta: { family: "brand", mode: "light" },
    tokens: { colors: { background: "#ffffff" } },
  }),
  defineTheme({
    name: "brand-dark",
    meta: { family: "brand", mode: "dark" },
    tokens: { colors: { background: "#101014" } },
  }),
];

export default defineThemvoraConfig({
  themes,
  defaultTheme: "brand-light",
  initialMode: "system",
});

describeRoleUsage(role): { advisory: { description: string; owner: ContextOwner }[]; restricted: string[]; supported: string[] }

What a role is for — the "safe usage" description.

The docs and Theme Studio show this instead of a bare hex, because how a token may be used is the thing a reader actually needs. A ratio answers "is it readable here"; this answers "is it readable here on purpose".

Returns { advisory: { description: string; owner: ContextOwner }[]; restricted: string[]; supported: string[] } — Where the role is supported, and where it is not.

destroySharedWorkerUrl(): void

Release the shared worker's blob URL.

Revokes the object URL created for the shared worker script and resets the cached URL, so a subsequent createSharedWorkerSync call creates a fresh worker. Safe to call multiple times; it is a no-op when no URL is cached.

Returns void

diffThemes(a, b, options): ThemeDiffReport

Diff two themes, or two light/dark theme sets.

Accepts a single theme or a { light, dark } pair on either side. Resolves inheritance through options.themes when a definition declares extends, and resolves a mode: "system" selector through the same registry.

Only light and dark are visual modes. "system" is a selector over that pair, resolved before any comparison, and never appears in the report.

hasChanges reflects token changes only. Provenance differences are reported separately, because two themes with identical tokens but different seeds render identically.

Returns ThemeDiffReport — The diff report.

const report = diffThemes(mintLight, irisLight);
report.modes.light?.changes.forEach((c) => {
  console.log(c.path, c.before, "→", c.after);
});

disposeThemeTransitionStyles(target): void

Release every transition style the coordinator owns for target: cancels an in-flight run and detaches the persistent :root transition stylesheet and the descendant-suppression stylesheet.

cancelThemeAnimation deliberately leaves the :root { transition } rule in place between runs — it is written once and reused, so every subsequent change keeps animating. That rule must go when the feature is turned off or the owner is disposed, otherwise later variable swaps still interpolate through it: a theme switch after transition: false would animate despite the plan being null. Scoped targets never install the :root rule (it is document-wide), so for them this only clears the suppression node and the animating flag.

Returns void

emitDiagnostic(diagnostic, options): void

Emit a diagnostic to the console.

Developer-facing Themvora diagnostics go through here rather than calling console directly, so that the level, the code, the deduplication and the development/production formatting stay consistent across packages.

Repeated identical diagnostics are suppressed by default; see EmitDiagnosticOptions.dedupe. Use resetDiagnosticEmission to clear that memory.

See also: createDiagnostic, formatDiagnostic

Returns void

emitInvalidOptionDiagnostic(option): void

Report an unusable transition/scheduling option supplied to configure().

level: "warning" — the runtime keeps the previous setting for the affected subsystem (a defined state) rather than corrupting a healthy runtime or throwing. Deduplicated by emitDiagnostic, so an adapter that forwards the same invalid value on every render logs it once.

Returns void

emitNeutralFallbackDiagnostic(): void

Report that no usable theme was available and the neutral fallback was used.

level: "warning" — the runtime recovers safely, so this is reported, not thrown. Deduplicated like every other diagnostic.

Returns void

emitScheduledThemeUnresolvedDiagnostic(names): void

Report that a scheduled configuration named light/dark themes that are not registered, so the schedule cannot drive the selection.

level: "warning" — the schedule is installed but reports no light/dark pair, matching the existing TV_SCHEDULE_THEME_UNRESOLVED contract used by the scheduled plugin. Deduplicated by emitDiagnostic.

Returns void

emitUnknownFamilyDiagnostic(requested, resolved, themes): void

Report a family that is not registered in the effective catalog.

level: "error" because an explicitly requested family that cannot resolve is a configuration mistake, not a supported absence. Deduplication is handled by emitDiagnostic: the same invalid value reports once, a new invalid value reports again.

Returns void

evaluateExpression(expr): string

Evaluate a numeric arithmetic expression and return the result as a string.

Supports +, -, *, /, parentheses, and an optional trailing CSS unit (e.g. "1.5 * 2rem" → "3rem"). Integer results are returned without a decimal point; non-integer results are rounded to two decimals. When the input is not a valid expression, or evaluation fails, the original string is returned unchanged.

See also: isExpression

Returns string — The evaluated result string, or expr unchanged when it cannot be evaluated.

extendTheme<TName extends string, TBase extends ThemeDefinition<string>>(name, base, overrides?): ThemeDefinition<TName>

Create a new theme by extending a base theme with overrides, merging token groups recursively.

See also: defineTheme, mergeTokens

Returns ThemeDefinition<TName>

findGeneratedTheme<T extends ThemeDefinition<string>>(themes, active?): GeneratedThemeLookup<T>

Locate the generated theme among a provider's registered themes.

Deterministic and non-throwing:

• No generated theme registered → "missing".
• Exactly one → "found".
• More than one → "found" for the one whose name matches active (the current active selection); otherwise "ambiguous". The first candidate is never returned on a tie.

See also: resolveGeneratedTheme

Returns GeneratedThemeLookup<T> — The lookup result.

flattenTokens(tokens): Record<string, string>

Flatten a theme's token groups into a single dot-path → value map.

Nested token objects are flattened with dot-separated paths (e.g. colors.primary, typography.fontSizes.base). Only string values are included; non-string values are skipped. The result is the lookup surface used to resolve token references.

See also: resolveTokens

Returns Record<string, string> — A flat map of dot-path keys to string token values.

formatDiagnostic(diagnostic, options): string

Render a diagnostic as a single log line.

This is the environment-specific half of the model: the diagnostic itself is plain data, and this decides how much of it a given environment should see. In development the context, hint and docs link are appended, because that is where they are actionable. Outside development the message is emitted alone — the failure is never hidden, but the surrounding detail is not shipped to end users.

See also: emitDiagnostic

Returns string — A single-line, prefixed string.

generateTheme(options): GeneratedThemePair

Generate a cohesive light/dark theme pair from a single seed color.

Light and dark are generated independently from the same identity — the dark theme is not an inversion of the light one — so the brand hue survives the mode change. Every semantic pair is solved to the contrast contract with a safety margin before the theme is returned, and the seed is recorded in meta.generation as provenance.

See also: validateTheme, defineTheme

Returns GeneratedThemePair — A { light, dark } pair of theme definitions sharing one family.

const { light, dark } = generateTheme({ seed: "#d97706", family: "brand" });

getAccessibilityProfiles(): { meta: { label: "High Contrast Light" | "High Contrast Dark"; mode: "light" | "dark"; order: 30 | 40; tags: ["accessibility", "high-contrast"] }; name: "high-contrast-light" | "high-contrast-dark"; tokens: { colors: { accent: "#0000ee" | "#4488ff"; accentForeground: "#ffffff" | "#000000"; background: "#ffffff" | "#000000"; border: "#000000"; card: "#ffffff" | "#000000"; cardForeground: "#ffffff" | "#000000"; destructive: "#cc0000" | "#dc2626"; destructiveForeground: "#ffffff"; foreground: "#ffffff" | "#000000"; input: "#000000"; muted: "#e0e0e0" | "#333333"; mutedForeground: "#111111" | "#eeeeee"; popover: "#ffffff" | "#000000"; popoverForeground: "#ffffff" | "#000000"; primary: "#0000ee" | "#4488ff"; primaryForeground: "#ffffff" | "#000000"; ring: "#0000ee" | "#4488ff"; secondary: "#e0e0e0" | "#333333"; secondaryForeground: "#ffffff" | "#000000"; success: "#008000" | "#16a34a"; successForeground: "#ffffff" }; radius: { lg: "4px" } } } | { meta: { label: "Large Text Light" | "Large Text Dark"; mode: "light" | "dark"; order: 35 | 45; tags: ["accessibility", "large-text"] }; name: "large-text-light" | "large-text-dark"; tokens: { colors: { accent: "#4488ff" | "#0055cc"; accentForeground: "#ffffff"; background: "#fafafa" | "#0a0a0a"; border: "#cccccc" | "#444444"; card: "#ffffff" | "#111111"; cardForeground: "#000000" | "#f0f0f0"; destructive: "#cc0000" | "#dc2626"; destructiveForeground: "#ffffff"; foreground: "#000000" | "#f0f0f0"; input: "#cccccc" | "#444444"; muted: "#e8e8e8" | "#2a2a2a"; mutedForeground: "#333333" | "#cccccc"; popover: "#ffffff" | "#111111"; popoverForeground: "#000000" | "#f0f0f0"; primary: "#4488ff" | "#0055cc"; primaryForeground: "#ffffff"; ring: "#4488ff" | "#0055cc"; secondary: "#e8e8e8" | "#2a2a2a"; secondaryForeground: "#000000" | "#f0f0f0"; success: "#008000" | "#16a34a"; successForeground: "#ffffff" }; radius: { lg: "8px" }; typography: { fontFamilies: { mono: "monospace"; sans: "system-ui, sans-serif" }; fontSizes: { 2xl: "2.25rem"; 3xl: "3rem"; 4xl: "3.75rem"; 5xl: "4.5rem"; 6xl: "6rem"; base: "1.25rem"; lg: "1.5rem"; sm: "1.125rem"; xl: "1.875rem"; xs: "1rem" }; lineHeights: { normal: "1.8"; relaxed: "2.0"; tight: "1.4" } } } }[]

Build the accessibility profile theme set: high-contrast and large-text themes for both light and dark modes.

Returns { meta: { label: "High Contrast Light" | "High Contrast Dark"; mode: "light" | "dark"; order: 30 | 40; tags: ["accessibility", "high-contrast"] }; name: "high-contrast-light" | "high-contrast-dark"; tokens: { colors: { accent: "#0000ee" | "#4488ff"; accentForeground: "#ffffff" | "#000000"; background: "#ffffff" | "#000000"; border: "#000000"; card: "#ffffff" | "#000000"; cardForeground: "#ffffff" | "#000000"; destructive: "#cc0000" | "#dc2626"; destructiveForeground: "#ffffff"; foreground: "#ffffff" | "#000000"; input: "#000000"; muted: "#e0e0e0" | "#333333"; mutedForeground: "#111111" | "#eeeeee"; popover: "#ffffff" | "#000000"; popoverForeground: "#ffffff" | "#000000"; primary: "#0000ee" | "#4488ff"; primaryForeground: "#ffffff" | "#000000"; ring: "#0000ee" | "#4488ff"; secondary: "#e0e0e0" | "#333333"; secondaryForeground: "#ffffff" | "#000000"; success: "#008000" | "#16a34a"; successForeground: "#ffffff" }; radius: { lg: "4px" } } } | { meta: { label: "Large Text Light" | "Large Text Dark"; mode: "light" | "dark"; order: 35 | 45; tags: ["accessibility", "large-text"] }; name: "large-text-light" | "large-text-dark"; tokens: { colors: { accent: "#4488ff" | "#0055cc"; accentForeground: "#ffffff"; background: "#fafafa" | "#0a0a0a"; border: "#cccccc" | "#444444"; card: "#ffffff" | "#111111"; cardForeground: "#000000" | "#f0f0f0"; destructive: "#cc0000" | "#dc2626"; destructiveForeground: "#ffffff"; foreground: "#000000" | "#f0f0f0"; input: "#cccccc" | "#444444"; muted: "#e8e8e8" | "#2a2a2a"; mutedForeground: "#333333" | "#cccccc"; popover: "#ffffff" | "#111111"; popoverForeground: "#000000" | "#f0f0f0"; primary: "#4488ff" | "#0055cc"; primaryForeground: "#ffffff"; ring: "#4488ff" | "#0055cc"; secondary: "#e8e8e8" | "#2a2a2a"; secondaryForeground: "#000000" | "#f0f0f0"; success: "#008000" | "#16a34a"; successForeground: "#ffffff" }; radius: { lg: "8px" }; typography: { fontFamilies: { mono: "monospace"; sans: "system-ui, sans-serif" }; fontSizes: { 2xl: "2.25rem"; 3xl: "3rem"; 4xl: "3.75rem"; 5xl: "4.5rem"; 6xl: "6rem"; base: "1.25rem"; lg: "1.5rem"; sm: "1.125rem"; xl: "1.875rem"; xs: "1rem" }; lineHeights: { normal: "1.8"; relaxed: "2.0"; tight: "1.4" } } } }[] — An array of four accessibility theme definitions.

getBrandPresets(): ThemeDefinition<string>[]

Build the brand preset theme set: a light and dark theme for each brand (Apple, GitHub, Vercel, Slack, Discord).

Returns ThemeDefinition<string>[] — An array of brand theme definitions, one light and one dark per brand.

getBrowserTimeZone(): string | null

Detect the visitor's IANA timezone, e.g. "Asia/Kathmandu". Returns null when Intl is unavailable or reports an empty zone.

Returns string | null

getBuiltInThemes(): ThemeDefinition<string> | { meta: { label: "High Contrast Light" | "High Contrast Dark"; mode: "light" | "dark"; order: 30 | 40; tags: ["accessibility", "high-contrast"] }; name: "high-contrast-light" | "high-contrast-dark"; tokens: { colors: { accent: "#0000ee" | "#4488ff"; accentForeground: "#ffffff" | "#000000"; background: "#ffffff" | "#000000"; border: "#000000"; card: "#ffffff" | "#000000"; cardForeground: "#ffffff" | "#000000"; destructive: "#cc0000" | "#dc2626"; destructiveForeground: "#ffffff"; foreground: "#ffffff" | "#000000"; input: "#000000"; muted: "#e0e0e0" | "#333333"; mutedForeground: "#111111" | "#eeeeee"; popover: "#ffffff" | "#000000"; popoverForeground: "#ffffff" | "#000000"; primary: "#0000ee" | "#4488ff"; primaryForeground: "#ffffff" | "#000000"; ring: "#0000ee" | "#4488ff"; secondary: "#e0e0e0" | "#333333"; secondaryForeground: "#ffffff" | "#000000"; success: "#008000" | "#16a34a"; successForeground: "#ffffff" }; radius: { lg: "4px" } } } | { meta: { label: "Large Text Light" | "Large Text Dark"; mode: "light" | "dark"; order: 35 | 45; tags: ["accessibility", "large-text"] }; name: "large-text-light" | "large-text-dark"; tokens: { colors: { accent: "#4488ff" | "#0055cc"; accentForeground: "#ffffff"; background: "#fafafa" | "#0a0a0a"; border: "#cccccc" | "#444444"; card: "#ffffff" | "#111111"; cardForeground: "#000000" | "#f0f0f0"; destructive: "#cc0000" | "#dc2626"; destructiveForeground: "#ffffff"; foreground: "#000000" | "#f0f0f0"; input: "#cccccc" | "#444444"; muted: "#e8e8e8" | "#2a2a2a"; mutedForeground: "#333333" | "#cccccc"; popover: "#ffffff" | "#111111"; popoverForeground: "#000000" | "#f0f0f0"; primary: "#4488ff" | "#0055cc"; primaryForeground: "#ffffff"; ring: "#4488ff" | "#0055cc"; secondary: "#e8e8e8" | "#2a2a2a"; secondaryForeground: "#000000" | "#f0f0f0"; success: "#008000" | "#16a34a"; successForeground: "#ffffff" }; radius: { lg: "8px" }; typography: { fontFamilies: { mono: "monospace"; sans: "system-ui, sans-serif" }; fontSizes: { 2xl: "2.25rem"; 3xl: "3rem"; 4xl: "3.75rem"; 5xl: "4.5rem"; 6xl: "6rem"; base: "1.25rem"; lg: "1.5rem"; sm: "1.125rem"; xl: "1.875rem"; xs: "1rem" }; lineHeights: { normal: "1.8"; relaxed: "2.0"; tight: "1.4" } } } }[]

Build the complete set of built-in themes shipped with Themvora.

Combines the neutral themes, preset themes, brand presets, and accessibility profiles into a single array ready to be registered with a theme runtime.

Every theme passes through ensureReadableContrast on the way out, so a semantic foreground that would fail AA is corrected before any consumer sees it.

Returns ThemeDefinition<string> | { meta: { label: "High Contrast Light" | "High Contrast Dark"; mode: "light" | "dark"; order: 30 | 40; tags: ["accessibility", "high-contrast"] }; name: "high-contrast-light" | "high-contrast-dark"; tokens: { colors: { accent: "#0000ee" | "#4488ff"; accentForeground: "#ffffff" | "#000000"; background: "#ffffff" | "#000000"; border: "#000000"; card: "#ffffff" | "#000000"; cardForeground: "#ffffff" | "#000000"; destructive: "#cc0000" | "#dc2626"; destructiveForeground: "#ffffff"; foreground: "#ffffff" | "#000000"; input: "#000000"; muted: "#e0e0e0" | "#333333"; mutedForeground: "#111111" | "#eeeeee"; popover: "#ffffff" | "#000000"; popoverForeground: "#ffffff" | "#000000"; primary: "#0000ee" | "#4488ff"; primaryForeground: "#ffffff" | "#000000"; ring: "#0000ee" | "#4488ff"; secondary: "#e0e0e0" | "#333333"; secondaryForeground: "#ffffff" | "#000000"; success: "#008000" | "#16a34a"; successForeground: "#ffffff" }; radius: { lg: "4px" } } } | { meta: { label: "Large Text Light" | "Large Text Dark"; mode: "light" | "dark"; order: 35 | 45; tags: ["accessibility", "large-text"] }; name: "large-text-light" | "large-text-dark"; tokens: { colors: { accent: "#4488ff" | "#0055cc"; accentForeground: "#ffffff"; background: "#fafafa" | "#0a0a0a"; border: "#cccccc" | "#444444"; card: "#ffffff" | "#111111"; cardForeground: "#000000" | "#f0f0f0"; destructive: "#cc0000" | "#dc2626"; destructiveForeground: "#ffffff"; foreground: "#000000" | "#f0f0f0"; input: "#cccccc" | "#444444"; muted: "#e8e8e8" | "#2a2a2a"; mutedForeground: "#333333" | "#cccccc"; popover: "#ffffff" | "#111111"; popoverForeground: "#000000" | "#f0f0f0"; primary: "#4488ff" | "#0055cc"; primaryForeground: "#ffffff"; ring: "#4488ff" | "#0055cc"; secondary: "#e8e8e8" | "#2a2a2a"; secondaryForeground: "#000000" | "#f0f0f0"; success: "#008000" | "#16a34a"; successForeground: "#ffffff" }; radius: { lg: "8px" }; typography: { fontFamilies: { mono: "monospace"; sans: "system-ui, sans-serif" }; fontSizes: { 2xl: "2.25rem"; 3xl: "3rem"; 4xl: "3.75rem"; 5xl: "4.5rem"; 6xl: "6rem"; base: "1.25rem"; lg: "1.5rem"; sm: "1.125rem"; xl: "1.875rem"; xs: "1rem" }; lineHeights: { normal: "1.8"; relaxed: "2.0"; tight: "1.4" } } } }[] — An array of all built-in theme definitions.

getContrastRatio(foreground, background): number

Compute the WCAG contrast ratio between two colors.

The ratio is (L1 + 0.05) / (L2 + 0.05) where L1/L2 are the relative luminances of the lighter and darker colors, yielding a value in the range 1 (identical colors) to 21 (black on white). Colors are parsed as hex.

See also: validateThemeContrast

Returns number — The contrast ratio, a number between 1 and 21.

getDefaultThemes(): ThemeDefinition<string>[]

Build the default theme family set: a light and dark theme for each of the original six built-in color families (oat, berry, mint, citrus, cocoa, plum).

Returns ThemeDefinition<string>[] — An array of ThemeDefinition objects, one light and one dark per family, ready to be registered with a theme runtime.

getFallbackThemes<T extends ThemeDefinition<string>>(): readonly T[]

The canonical neutral fallback catalog.

A single source shared by every adapter: the framework packages never define their own fallback palette.

Returns readonly T[]

getHighContrastTheme(mode): { meta: { label: "High Contrast Light" | "High Contrast Dark"; mode: "light" | "dark"; order: 30 | 40; tags: ["accessibility", "high-contrast"] }; name: "high-contrast-light" | "high-contrast-dark"; tokens: { colors: { accent: "#0000ee" | "#4488ff"; accentForeground: "#ffffff" | "#000000"; background: "#ffffff" | "#000000"; border: "#000000"; card: "#ffffff" | "#000000"; cardForeground: "#ffffff" | "#000000"; destructive: "#cc0000" | "#dc2626"; destructiveForeground: "#ffffff"; foreground: "#ffffff" | "#000000"; input: "#000000"; muted: "#e0e0e0" | "#333333"; mutedForeground: "#111111" | "#eeeeee"; popover: "#ffffff" | "#000000"; popoverForeground: "#ffffff" | "#000000"; primary: "#0000ee" | "#4488ff"; primaryForeground: "#ffffff" | "#000000"; ring: "#0000ee" | "#4488ff"; secondary: "#e0e0e0" | "#333333"; secondaryForeground: "#ffffff" | "#000000"; success: "#008000" | "#16a34a"; successForeground: "#ffffff" }; radius: { lg: "4px" } } }

Build a high-contrast theme for the given mode.

Uses maximum-contrast colors (pure black/white surfaces, saturated primary) to maximize legibility for users with low vision.

Returns { meta: { label: "High Contrast Light" | "High Contrast Dark"; mode: "light" | "dark"; order: 30 | 40; tags: ["accessibility", "high-contrast"] }; name: "high-contrast-light" | "high-contrast-dark"; tokens: { colors: { accent: "#0000ee" | "#4488ff"; accentForeground: "#ffffff" | "#000000"; background: "#ffffff" | "#000000"; border: "#000000"; card: "#ffffff" | "#000000"; cardForeground: "#ffffff" | "#000000"; destructive: "#cc0000" | "#dc2626"; destructiveForeground: "#ffffff"; foreground: "#ffffff" | "#000000"; input: "#000000"; muted: "#e0e0e0" | "#333333"; mutedForeground: "#111111" | "#eeeeee"; popover: "#ffffff" | "#000000"; popoverForeground: "#ffffff" | "#000000"; primary: "#0000ee" | "#4488ff"; primaryForeground: "#ffffff" | "#000000"; ring: "#0000ee" | "#4488ff"; secondary: "#e0e0e0" | "#333333"; secondaryForeground: "#ffffff" | "#000000"; success: "#008000" | "#16a34a"; successForeground: "#ffffff" }; radius: { lg: "4px" } } } — A high-contrast theme definition tagged "accessibility" and "high-contrast".

getLargeTextTheme(mode): { meta: { label: "Large Text Light" | "Large Text Dark"; mode: "light" | "dark"; order: 35 | 45; tags: ["accessibility", "large-text"] }; name: "large-text-light" | "large-text-dark"; tokens: { colors: { accent: "#4488ff" | "#0055cc"; accentForeground: "#ffffff"; background: "#fafafa" | "#0a0a0a"; border: "#cccccc" | "#444444"; card: "#ffffff" | "#111111"; cardForeground: "#000000" | "#f0f0f0"; destructive: "#cc0000" | "#dc2626"; destructiveForeground: "#ffffff"; foreground: "#000000" | "#f0f0f0"; input: "#cccccc" | "#444444"; muted: "#e8e8e8" | "#2a2a2a"; mutedForeground: "#333333" | "#cccccc"; popover: "#ffffff" | "#111111"; popoverForeground: "#000000" | "#f0f0f0"; primary: "#4488ff" | "#0055cc"; primaryForeground: "#ffffff"; ring: "#4488ff" | "#0055cc"; secondary: "#e8e8e8" | "#2a2a2a"; secondaryForeground: "#000000" | "#f0f0f0"; success: "#008000" | "#16a34a"; successForeground: "#ffffff" }; radius: { lg: "8px" }; typography: { fontFamilies: { mono: "monospace"; sans: "system-ui, sans-serif" }; fontSizes: { 2xl: "2.25rem"; 3xl: "3rem"; 4xl: "3.75rem"; 5xl: "4.5rem"; 6xl: "6rem"; base: "1.25rem"; lg: "1.5rem"; sm: "1.125rem"; xl: "1.875rem"; xs: "1rem" }; lineHeights: { normal: "1.8"; relaxed: "2.0"; tight: "1.4" } } } }

Build a large-text theme for the given mode.

Enlarges the typography scale and uses high-contrast colors so text remains readable for users who need larger type.

Returns { meta: { label: "Large Text Light" | "Large Text Dark"; mode: "light" | "dark"; order: 35 | 45; tags: ["accessibility", "large-text"] }; name: "large-text-light" | "large-text-dark"; tokens: { colors: { accent: "#4488ff" | "#0055cc"; accentForeground: "#ffffff"; background: "#fafafa" | "#0a0a0a"; border: "#cccccc" | "#444444"; card: "#ffffff" | "#111111"; cardForeground: "#000000" | "#f0f0f0"; destructive: "#cc0000" | "#dc2626"; destructiveForeground: "#ffffff"; foreground: "#000000" | "#f0f0f0"; input: "#cccccc" | "#444444"; muted: "#e8e8e8" | "#2a2a2a"; mutedForeground: "#333333" | "#cccccc"; popover: "#ffffff" | "#111111"; popoverForeground: "#000000" | "#f0f0f0"; primary: "#4488ff" | "#0055cc"; primaryForeground: "#ffffff"; ring: "#4488ff" | "#0055cc"; secondary: "#e8e8e8" | "#2a2a2a"; secondaryForeground: "#000000" | "#f0f0f0"; success: "#008000" | "#16a34a"; successForeground: "#ffffff" }; radius: { lg: "8px" }; typography: { fontFamilies: { mono: "monospace"; sans: "system-ui, sans-serif" }; fontSizes: { 2xl: "2.25rem"; 3xl: "3rem"; 4xl: "3.75rem"; 5xl: "4.5rem"; 6xl: "6rem"; base: "1.25rem"; lg: "1.5rem"; sm: "1.125rem"; xl: "1.875rem"; xs: "1rem" }; lineHeights: { normal: "1.8"; relaxed: "2.0"; tight: "1.4" } } } } — A large-text theme definition tagged "accessibility" and "large-text".

getLocationForTimeZone(timeZone): TimeZoneLocation | null

Look up the reference coordinates for an IANA timezone. Returns null when the zone is unknown (or Etc/GMT±n, which is derived from offset).

Returns TimeZoneLocation | null

getNeutralThemes(): [ThemeDefinition<string>, ThemeDefinition<string>]

Build the neutral light and dark themes.

These are the framework's baseline themes: a full token set (colors, radius, spacing, shadows, border widths, z-index, breakpoints, typography, and code) with no color family applied. They are the fallback when no family is selected. Their colors are generated, so they satisfy the same contrast contract as every preset.

Returns [ThemeDefinition<string>, ThemeDefinition<string>] — A [light, dark] tuple of neutral theme definitions.

getPresetCatalog(kind?): PresetCatalogEntry[]

The preset catalog, derived from the recipes.

Returns PresetCatalogEntry[] — The catalog entries, in recipe order.

getPresetThemes(overrides?): ThemeDefinition<string>[]

Build the curated preset theme set: a light and dark theme for each preset color family (oat, berry, mint, citrus, cocoa, plum, iris, sky, graphite).

Each preset is generated from a recipe — seed, style and radius — by the same semantic-v2 pipeline generateTheme() uses, so every preset already satisfies the contrast contract and the visual relationship checks before it is returned. Optional per-family, per-mode token overrides are applied on top, afterwards.

Returns ThemeDefinition<string>[] — An array of preset theme definitions, one light and one dark per family.

const themes = getPresetThemes({
  plum: { light: { tokens: { colors: { primary: "#6d28d9" } } } },
});

getThemeFamily(theme): string

Get a theme's family. Themes without meta.family belong to the "default" family.

See also: resolveThemeName

Returns string

getThemeMode(theme): ThemeMode

Get the color mode of a theme. Uses meta.mode when present; otherwise infers it from the theme name (e.g. "mint-dark" → "dark"). This keeps simple theme definitions working: [{ name: "light", ... }, { name: "dark", ... }] resolve and toggle correctly without requiring meta.mode.

See also: resolveThemeName

Returns ThemeMode

getTimeZoneList(): string[]

All known timezone ids, sorted alphabetically. Useful for building pickers (the docs site uses it for its timezone selector).

Returns string[]

hasForegroundPreference(role): boolean

Whether a foreground role's choice is governed by a declared preference.

Returns boolean — true when the role has a declared preference.

hideNativeScrollbar(): __type(): void

Hide the native scrollbar and register a claim that keeps it hidden.

Returns the release function for that claim. The hiding is applied idempotently (the class may already be server-rendered, the stylesheet may already exist), and it is released when the last claim goes away — so createOverlayScrollbar and its destroy() are a matched pair rather than a one-way switch.

Returns __type(): void

isCoreColor(key): key is CoreColor

Whether a colour key is part of the core contract.

Returns key is CoreColor

isExpression(value): boolean

Determine whether a string is a numeric arithmetic expression.

An expression is a string containing +, -, *, or / over numbers and parentheses, optionally ending in a CSS unit (e.g. "1.5 * 2rem"). Function calls such as contrast(...) and auto() are not treated as expressions.

Returns boolean — true when value is a numeric arithmetic expression.

isGeneratedTheme(theme): boolean

Whether a theme was produced by the public generateTheme call.

Matches on the explicit origin marker only. It deliberately does not infer from a theme's name, family, or colors: the built-in presets and the neutral baseline are produced by the same engine and would otherwise be mistaken for application-generated themes, and a hand-authored theme could impersonate one by adopting a familiar id.

See also: resolveGeneratedTheme

Returns boolean — true when the theme carries the generator's origin marker.

isOptionalSemantic(key): key is OptionalSemantic

Whether a colour key is an optional semantic capability.

Returns key is OptionalSemantic

isSelectionResolvable(themes, selection): boolean

Whether a selection can be resolved to a usable theme in a catalog.

A selection is resolvable when its family is registered in themes AND at least one theme for that family resolves the requested mode (treating "system" as the light variant for the check — the caller re-resolves the concrete mode).

Returns boolean

isSettled(current, target, epsilon): boolean

True when two positions are close enough to consider the thumb "settled".

Returns boolean

isThemeMode(value): value is ThemeMode

Narrow an unknown value to a ThemeMode.

This is the single shared predicate for the light/dark/system axis. It is exported so that adapters which receive a mode from outside the type system — storage, cookies, cross-tab messages, element attributes — validate it the same way instead of each re-implementing the comparison.

Returns value is ThemeMode — true when value is a valid mode.

if (!isThemeMode(input)) {
  emitDiagnostic(createDiagnostic({ code: "TV_MODE_INVALID", level: "warning", message: "..." }));
}

isUsableTheme(theme): theme is ThemeDefinition<string>

Whether a value is a usable theme entry.

Deliberately lenient — the runtime needs a stable identity (name) and an object to read meta/tokens from, not a fully-populated palette. A theme with partial tokens is still a valid registration (the CSS-variable binding simply emits what is present), so schema completeness is not required here.

Returns theme is ThemeDefinition<string>

loadThemeRegistry(source): RegistryLoadResult

Read a generated theme registry from its source.

Statically: the module is never imported, evaluated or transpiled.

Returns RegistryLoadResult — The themes it registers, or a structured failure.

The shape recognised is the one themvora init writes: a themvora array of defineTheme literals, a selection of family names, a sourceThemes array, and a themes export combining them. A module outside that shape — including a hand-written one — is reported as not-a-registry or unsupported-construct, never partially guessed.

measureThemeContrast(theme): MeasuredPair[]

Measure every contract pair in a resolved theme.

The canonical measurement — the scorecard's text-contrast and ui-contrast checks, the preset audit and the docs pages all read this, so a page cannot show a ratio the gate disagrees with. Anything that renders contrast numbers should call this rather than re-deriving them.

Returns MeasuredPair[] — One row per contract pair, in contract order.

mergePresetTokens(base, override?): ThemeTokens

Merge a partial token override into a base token set.

Each token group is merged shallowly, so override values replace individual keys while leaving unspecified keys from the base intact.

Returns ThemeTokens — A new token set combining base and override.

mergeThemeDefinitions<Name extends string>(base, override): ThemeDefinition<Name>

Merge two theme definitions, deep-merging their meta and tokens.

override wins for scalar fields; meta and tokens are merged via mergeTokens semantics.

Returns ThemeDefinition<Name> — A new merged definition. The inputs are not mutated.

mergeTokens(base, override): ThemeTokens | undefined

Merge two token objects, deep-merging the colors group and shallowly merging every other group.

override wins over base. Within colors, an explicit undefined value removes a key; nested color objects merge recursively. Groups not present in either input are omitted from the result.

See also: flattenTokens, resolveTokens

Returns ThemeTokens | undefined — The merged tokens, or undefined when both inputs are empty.

migrateTheme(theme, options): ThemeDefinition

Migrate a legacy theme to the current Themvora format using registered migrations.

See also: registerMigration

Returns ThemeDefinition

normalizeProvidedThemes<T extends ThemeDefinition<string>>(themes, previous): readonly ProvidedThemeFamily<T>[]

Group a provider's theme collection into discoverable families.

Preserves the supplied order of both families and variants, keeps light/dark (and any other mode) as siblings rather than flattening them, and never mutates or extends the input — a family appears only if a theme for it was supplied.

See also: createProvidedThemesSource

Returns readonly ProvidedThemeFamily<T>[] — The grouped collection, ordered by first appearance.

const families = normalizeProvidedThemes(runtime.themes);
const mint = families.find((family) => family.family === "mint");
mint?.variants.map((variant) => variant.tokens.colors?.background);

normalizeThemeCatalog<T extends ThemeDefinition<string>>(themes): readonly T[]

Normalize a theme catalog.

Drops entries that are not usable themes, drops duplicate names (first wins, matching the registry's deduplication), and — when nothing usable remains — falls back to the canonical neutral themes. The input array is never mutated.

Returns readonly T[] — A non-empty, deduplicated catalog.

parseThemeJson(text): ParsedThemeJson

Parse a theme document, tolerating comments and trailing commas.

Returns ParsedThemeJson — The parsed value and the masked source.

preferredInk(role, ctx): Oklch | null

The preferred ink for a role, resolved for the mode.

"light" and "dark" are the two ink families, not literal white and black: the light ink is the theme's near-white, the dark ink its near-black. A role that prefers light ink gets the near-white in both modes, which is what keeps a button label consistent across a mode switch.

Returns Oklch | null — The preferred ink, or null when the role has no preference.

prefersReducedMotion(): boolean

Requested motion profile. Reduced motion snaps instantly.

Returns boolean

readBootstrapState<T extends ThemeDefinition<string>>(themes, target?): ThemeBootstrapState<T> | null

Reads the pre-paint bootstrap's state back off the DOM, validated against the theme registry.

See also: createThemeBootstrapScript

Returns ThemeBootstrapState<T> | null — The validated state, or null when there is no DOM, no data-theme, or the name is not in the registry.

This is the read half of the bootstrap handoff. The blocking script writes data-theme (resolved theme), data-theme-selection-mode / data-theme-selection-family (the selection, which is not recoverable from the resolved theme), data-theme-ready, and a window.__THEMVORA_BOOTSTRAP__ payload.

It exists so a client runtime can adopt what was already painted instead of re-deriving it: by the time a client renders, <html> is the authority on what the visitor is looking at, and anything that re-resolves can disagree with it. The result is validated against the registry rather than trusted as an arbitrary string, so a stale or hand-written attribute cannot inject a theme that does not exist.

readThemeDefinitions(source, options?): ThemeDefinitionReadResult

Read every defineTheme({ … }) literal in a source file.

defineTheme() returns its argument unchanged — it is a type-level helper, not a transformation — so reading the literal is reading the theme. That is what makes a static reader sufficient here, and it is why this function needs no knowledge of variants, defaults or provenance: there are none to apply.

Broader than loadThemeRegistry, which requires the canonical registry's exports. A project may define themes in any file it likes; this finds the definitions wherever they are, and reports the ones it cannot read rather than skipping them.

It also reads generateTheme({ … }) calls whose argument is a literal object. That is not executing project code: generateTheme is Themvora's own pure generator, and calling it with data read from the file is the same thing the application does at runtime. A call with any other argument is refused.

In strict mode every API name must come from bindings or namespaces; a local function with a catalog's spelling is not the catalog.

Returns ThemeDefinitionReadResult — The definitions found, and the candidates refused.

readTransportedConfig<T extends ThemeDefinition<string>>(): ThemeBootstrapConfig<T> | null

Reads the configuration a build integration transported to the runtime.

See also: resolveRuntimeOptions

Returns ThemeBootstrapConfig<T> | null — The transported configuration, or null when no integration ran.

A build integration (the Vite plugin, the Astro integration) puts the ThemeBootstrapConfig projection of theme.config.ts on the global scope before any application code runs. Reading it is what lets a provider take no theme props — and it is the mechanism that makes "one declaration, two consumers" true rather than aspirational.

globalThis rather than window, because the same read has to work during SSR and prerender, where there is no window. The server entries set the same global for exactly that reason.

registerMigration(step): void

Register a migration for the theme migration system.

See also: clearMigrations, migrateTheme

Returns void

resetDiagnosticEmission(): void

Forget which diagnostics have already been emitted.

Deduplication is process-wide by design, which makes it stateful across tests. Call this between test cases so each one observes its own emissions.

Returns void

beforeEach(() => resetDiagnosticEmission());

resolveEffectiveConfiguration<T extends ThemeDefinition<string>>(options): EffectiveConfiguration<T>

Resolve the effective selection + theme for a configuration update.

Precedence (shared by every adapter — there is no per-framework variant):

1. preserve and the previous selection is still resolvable → keep it. A catalog change that leaves the selection valid must not silently move the user to another theme.
2. Otherwise resolve from defaultTheme / initialFamily / initialMode against the effective catalog.
3. An unknown requested family normalizes to a resolvable family and emits a single TV_THEME_FAMILY_UNKNOWN diagnostic.

Returns EffectiveConfiguration<T> — The effective selection and its theme.

resolveGeneratedTheme<T extends ThemeDefinition<string>>(themes, active?): T

Resolve the single generated theme registered with a provider, or throw.

The throwing counterpart of findGeneratedTheme, for call sites that need a theme rather than a status — the framework accessors, which surface the failure to the caller.

See also: `- isGeneratedTheme

• findGeneratedTheme`

Returns T — The resolved generated theme.

resolveIconOptions<T>(icons?): OverlayScrollbarOptions

Map an icons group onto the engine's flat icon options, so every adapter resolves the group the same way. Only defined entries are copied.

Returns OverlayScrollbarOptions — Flat arrowIcon / arrow*Icon / iconSize values.

resolveInitialTheme<T extends ThemeDefinition<string>>(options): InitialThemeResolution<T>

Resolves the initial theme and selection for a runtime bootstrap.

Combines defaultTheme, family, mode, and prefersDark into a concrete theme, resolving "system" mode against prefersDark for the theme lookup while keeping the "system" mode in the returned selection.

See also: resolveSelection, resolveThemeName

Returns InitialThemeResolution<T> — The resolved theme and selection.

resolveRuntimeOptions<T extends ThemeDefinition<string>>(options): Partial<ThemeRuntimeOptions<T>>

Merges the transported configuration under a provider's own options.

See also: readTransportedConfig

Returns Partial<ThemeRuntimeOptions<T>> — The options a runtime should be created from.

The order is the contract: transported first, provider second. A provider that supplies themes is overriding the application configuration, which is legitimate for a test or a storybook but is otherwise the duplication this whole mechanism exists to remove.

Provider options whose value is undefined are dropped rather than spread. That is not a detail — Vue and Svelte hand the provider an object containing every declared prop, with undefined for the ones the app did not pass, so a plain spread would overwrite the transported value with undefined and the provider would silently fall back to the built-in themes.

themes is always resolved to a non-empty array. createThemeRuntime falls back to the built-in themes only when themes is undefined, so an empty array — a provider given themes={[]}, or a config whose registry was filtered to nothing — would otherwise produce a runtime with no registry at all, which throws on the first selection.

An explicit empty array counts as not set, not as "no themes": the Web Components provider parses an absent themes attribute into [], and treating that as an override would shadow the transported registry with nothing.

const resolved = resolveRuntimeOptions<T>(props);
const runtime = createThemeRuntime(resolved);

resolveScheduledThemePair<T extends ThemeDefinition<string>>(themes, options, current?): { dark: T | null; light: T | null }

Resolve the scheduled light/dark themes from the configured options and the currently selected theme. Priority: explicit lightTheme/darkTheme → same-family counterpart of the current theme → neutral light/dark. Shared by createThemeSchedule and createScheduledPlugin.

Returns { dark: T | null; light: T | null }

resolveScopedTheme<T extends ThemeDefinition<string>>(themes, selection, prefersDark): T

Resolve a scoped selection against a theme list. themes should already be the combined source: local themes FIRST, then the parent runtime's registry.

Resolution order:

1. exact theme-name match (local wins),
2. a name that matches a family → that family's theme for the mode,
3. explicit family + mode → exact match, else the family's light theme, else the family's first theme,
4. the first theme in the list as a last-resort fallback.

The resolved definition has its extends chain merged (like resolveTheme) so scoped CSS variables include every inherited token.

Returns T

resolveScopedThemePrePaint<T extends ThemeDefinition<string>>(themes, selection, options): ScopedThemePrePaint

Resolve everything a scope needs for its FIRST PAINT, generically from its theme data (no hardcoded colors — any user's scoped themes produce the same result). When the selection is OS-dependent (a system mode, or a family / boundary scope currently following a system selection), it returns a @media (prefers-color-scheme: dark) CSS block so the scoped region renders light OR dark correctly before hydration, with the live binding taking over through its own inline variables afterwards.

Returns ScopedThemePrePaint

resolveScopeTransition(parent, local): ThemeTransitionOptions | undefined

Merge a scope's transition over its parent runtime's transition.

The inheritance model is ThemeProvider transition → ThemeScope → inherited defaults → local overrides:

• local === undefined → inherit the parent's configuration unchanged,
• local === true → inherit the parent's configuration unchanged,
• local === false → transitions disabled for this scope only,
• local object → merged over the parent's (local keys win).

Frameworks use this so <ThemeScope transition={{ duration: 200 }}> flips just the duration without the user having to repeat the provider's easing / preset.

Returns ThemeTransitionOptions | undefined

resolveScrollbarOptions(grouped, flat): OverlayScrollbarOptions

Merge grouped settings (plus any deprecated flat aliases) into one canonical OverlayScrollbarOptions object.

Only keys that are actually defined are copied, so an explicitly-undefined value never overrides a core default, and the returned object is always a fresh one (the inputs are never mutated).

Returns OverlayScrollbarOptions — A canonical options object for createOverlayScrollbar.

resolveSelectedTheme<T extends ThemeDefinition<string>>(themes, selection): T

Resolve the registered theme that best matches a selection.

Prefers an exact family + mode match, then any theme in the family, then any theme of the requested mode, then the first registered theme. Never throws; the fallback chain guarantees a result for non-empty theme lists.

See also: resolveThemeName, ThemeSelection

Returns T — The selected theme definition.

resolveSelection<T extends ThemeDefinition<string>>(options): ThemeSelectionState

Resolves a selection state from configuration inputs.

Priority: persistedSelection wins; otherwise initialFamily (family or variant), then defaultTheme (family or variant), then the first theme.

See also: resolveInitialTheme, resolveThemeReference

Returns ThemeSelectionState — The resolved selection (family + mode).

resolveSelectionTheme<T extends ThemeDefinition<string>>(options): SelectionThemeResolution<T>

Resolves the theme that matches an existing selection state.

Convenience wrapper around resolveInitialTheme for the common case of re-applying a persisted or scoped selection.

See also: resolveSelection, resolveSelectedTheme

Returns SelectionThemeResolution<T> — The matching theme and the normalized selection.

resolveSolarLocation(input): ResolvedSolarLocation

Resolve the coordinates a solar calculation should use.

Priority: explicit latitude/longitude → explicit timeZone → browser timezone auto-detection → DEFAULT_TIMEZONE_LOCATION.

Returns ResolvedSolarLocation

resolveTheme<Name extends string>(themes, themeName, resolveTokenRefs): ThemeDefinition<Name>

Resolve a theme definition to its fully inherited form.

Walks the extends chain (multiple parents merge in order), producing the effective meta and tokens. When resolveTokenRefs is true, token references (${token.path}) and derived expressions are also resolved.

See also: mergeThemeDefinitions, resolveThemeRegistry

Returns ThemeDefinition<Name> — The resolved theme definition.

resolveThemeName<Name extends string>(themes, family, mode, prefersDark): Name

Resolve the theme name that best matches a family + mode selection.

Looks up the theme in family whose mode matches the requested mode, honoring prefersDark when mode is "system". Falls back to the family's light theme, then the family's first theme, then the first theme overall.

See also: getThemeFamily, getThemeMode, resolveSelectedTheme

Returns Name — The resolved theme name.

resolveThemeOverride<T extends ThemeDefinition<string>>(themes, override, base): ThemeSelectionState | null

Resolve an override against the provider's themes.

Pure: no side effects, no state. Returns a complete selection (both fields filled) or null when the override cannot be satisfied — the caller decides whether to report and ignore or to treat it as absent.

A string is a theme name and must match exactly. An object is a family/mode request; a missing field is inherited from base.

See also: ThemeOverride

Returns ThemeSelectionState | null — The resolved selection, or null when absent or unresolvable.

// `themes` is whatever registry the provider was given.
const themes = getBuiltInThemes();
const selection = { family: "mint", mode: "light" };

resolveThemeOverride(themes, "mint-dark", selection);      // { family: "mint", mode: "dark" }
resolveThemeOverride(themes, { family: "mint" }, selection); // keeps base.mode
resolveThemeOverride(themes, "nope", selection);            // null

resolveThemeReference<T extends ThemeDefinition<string>>(themes, reference, options): ResolvedThemeReference<T> | null

Resolve a theme reference against a provider's catalog.

See also: resolveThemeOverride, resolveSelection

Returns ResolvedThemeReference<T> | null — The resolution, or null when the reference names nothing available.

An exact variant name wins over a family name. A theme whose name equals another theme's family is therefore addressable as a variant — the explicit, more specific reading — and the family form of the other family keeps working. The two namespaces are otherwise independent: a family is meta.family ?? "default", a variant is name.

// `themes` is whatever registry the provider was given.
const themes = getBuiltInThemes();

resolveThemeReference(themes, "cocoa-dark"); // { kind: "variant", mode: "dark", … }
resolveThemeReference(themes, "cocoa", { mode: "dark" }); // { kind: "family", … cocoa-dark }
resolveThemeReference(themes, "nope"); // null

resolveThemeRegistry<T extends ThemeDefinition<string>>(options?): readonly T[]

Resolves the effective theme list for a registry configuration.

Returns the provided themes when non-empty; otherwise falls back to the built-in themes.

See also: ThemeRegistry, getBuiltInThemes

Returns readonly T[] — The effective theme definitions.

resolveTokens(tokens): ThemeTokens

Resolve a theme's token groups, evaluating expressions and references into concrete values.

See also: flattenTokens, evaluateExpression

Returns ThemeTokens

restoreNativeScrollbar(): void

Restore the platform's native scrollbars, discarding any outstanding claims.

Undoes the hiding completely: the tv-scrollbar class (and the tv-scrollbar-ready phase marker) come off <html>, and every hiding stylesheet is removed. Safe to call at any time and idempotent — a page that never hid anything is left untouched.

This is what makes the overlay's lifecycle symmetric. Without it, unmounting the overlay left the page with the native bar still hidden and nothing to replace it: an invisible scrollbar, not a native one.

It is also a hard reset: the claim count drops to zero, so an overlay that outlives the call no longer keeps the native bar hidden on its own. That is the point — it is the escape hatch for a page that has decided the overlay is gone (a teardown, a framework's beforeunload, a test), and it is why the count cannot drift upwards forever.

Returns void

runThemeAnimation(input): void

Run the animation for one theme change. Called by the CSS-variables binding only when the Transition Planner produced a non-null plan.

Returns void

scanForTransition(root, properties): HTMLElement[]

Collect elements that both (a) are visible and (b) actually use one of the provided CSS properties. Runs only when non-color groups are animating.

Returns HTMLElement[]

scopeToCSSVariables(themeVars, prefix): Record<string, string>

Mirror the scoped binding's aliases (the --color-* / --radius-* tokens Tailwind-style utilities resolve against) so styling utilities on scoped elements use the scoped theme's values, not the page theme's.

Returns Record<string, string>

scoreTheme(theme): PresetScore

Score a theme against the nine preset quality checks.

Returns PresetScore — The scorecard.

simulateCVD(hex, type): string

Simulate how a color appears to someone with the given color vision deficiency.

Converts the color to linear RGB, transforms it through the LMS cone space, collapses the affected cone channel (or, for achromatopsia, reduces to luminance), and converts back to a hex string. Non-hex input is returned unchanged.

Returns string — The simulated hex color, or hex unchanged when it is not a hex color.

simulateThemeForCVD(theme, type): ThemeDefinition

Produce a copy of a theme whose color tokens are simulated for the given color vision deficiency.

Every hex color in tokens.colors is passed through simulateCVD; non-color tokens and non-hex values are preserved. The returned theme is a new object and the input is not mutated. Themes without color tokens are returned unchanged.

Returns ThemeDefinition — A new theme definition with simulated color tokens.

systemModeCSSTemplate(light, dark): string

Generate the stylesheet that resolves a "system" selection with CSS alone — no script and no inline style.

See also: darkModeCSSTemplate

Returns string — Two media blocks, one per scheme, both targeting :root, escaped for <style>-element content exactly as darkModeCSSTemplate is.

Use this instead of inlining the resolved variables whenever the mode is "system". The two cannot be combined: an inline style on <html> outranks any stylesheet rule, so a page that inlines the light variables and also emits a dark media block paints light whatever the OS prefers. Measured on a production build with page scripts blocked and the OS set to dark, that combination painted rgb(248, 250, 252) (light); emitting both media blocks and no inline variables painted rgb(2, 6, 23).

prefers-color-scheme: light also matches when the visitor has expressed no preference — light is the specified default — so the light block doubles as the no-preference branch.

themeOverrideKey(override, themes?): string | null

The semantic identity of an override, for change detection.

Two overrides with the same key request the same theme, even when they are different objects — which is the normal case for an inline themeOverride={{ family: "mint" }} that is rebuilt on every render. Built from resolved primitives only: no object stringification, no identity.

Pass the provider's catalog to canonicalise a theme name against the family and mode it resolves to, so "mint-dark" and { family: "mint", mode: "dark" } compare equal — they are the same request written two ways, and re-applying one because the other was spelled differently is exactly the churn this function exists to prevent. Without a catalog the name form keys on the name alone.

A partially specified request ({ family: "mint" }) keys on what was asked for, never on the base selection it would inherit: otherwise a manual mode change would make an unchanged prop look like a new request and re-assert the family.

See also: resolveThemeOverride

Returns string | null — A stable string, or null when there is no override.

themeToCssDocument(theme): string

Render a theme, or a light/dark pair, as a CSS custom-property document.

This is the canonical formatting for Themvora's :root document convention, and the only place it exists: the CLI's export --format css and the VS Code extension's Copy CSS Variables both call it, so the CSS a user copies is the CSS the CLI writes.

A single theme is emitted under CSS_ROOT_SELECTOR. A pair is emitted as the light theme under :root followed by the dark theme under CSS_DARK_SELECTOR.

Output is deterministic: the variable order comes from themeToCSSVariables, which emits token groups in a fixed order, so the same theme always produces byte-identical CSS.

See also: themeToCSSVariables

Returns string — The document, ending with a newline.

const { light, dark } = generateTheme({ seed: "#4f46e5" });
const css = themeToCssDocument({ light, dark });
// :root { --theme-color-background: #fbfbff; … }
// .dark, [data-theme="dark"] { … }

themeToCSSVariables(theme, options): Record<string, string>

Flatten a theme's semantic tokens into CSS custom properties (--theme-*), optionally filtered by token group.

See also: flattenTokens, ThemeToCSSVariablesOptions

Returns Record<string, string> — A flat map of CSS custom property name → value.

Pass { groups: ["colors"] } to emit only specific token groups.

const vars = themeToCSSVariables(theme); // { "--theme-color-background": "#fff", ... }

toBootstrapConfig<T extends ThemeDefinition<string>>(config): ThemeBootstrapConfig<T>

Projects a ThemvoraConfig down to what crosses to the browser.

See also: ThemeBootstrapConfig

Returns ThemeBootstrapConfig<T> — The transported projection.

Copies the serializable runtime options as well as the bootstrap fields. A field omitted here is not merely unused in the browser — it is replaced by a default, which is how a declared transition: { enabled: false } still produced a view transition on every theme change. See ThemeBootstrapConfig.

validateTheme(theme, options): ValidationResult

Validate a theme definition against the Themvora schema.

Checks that the definition declares a tokens object and that every required semantic colour token is present. It deliberately does not resolve token references and does not check contrast: unresolved references are reported by token resolution (which throws), and contrast has its own validator, validateThemeContrast.

Returns issues rather than throwing, so a caller can report every problem at once — the CLI does exactly this.

See also: ValidationIssue, generateTheme

Returns ValidationResult — { valid, issues }, where valid is true when issues is empty.

validateThemeContrast(theme, options): ContrastValidationResult

Validate a theme's semantic color pairs against WCAG contrast thresholds.

Checks the standard foreground/background pairs (e.g. foreground on background, primaryForeground on primary) and reports each pair's ratio and whether it passes WCAG AA/AAA for normal and large text. Pairs whose colors are missing or not hex are skipped. The theme is considered valid when every checked pair passes WCAG AA for normal text.

See also: getContrastRatio

Returns ContrastValidationResult — A ContrastValidationResult with per-pair checks.

validateThemeLevels(theme, options): LevelIssue[]

Run the internal validation levels over a theme definition.

Returns LevelIssue[] — Every issue found, across the requested levels.

Classes

class ThemeError

Extends Error The error type thrown by Themvora for theme-related failures.

Extends the native Error and sets name to "ThemeError" so callers can distinguish Themvora failures from other errors via instanceof or the name property. The message carries the human-readable failure detail.

When the failure corresponds to a diagnostic, the error also carries the stable ThemeError.code and its structured context, so a caller can branch on the code rather than matching on prose. Both are optional: the single-argument form remains valid.

See also: ThemeError.fromDiagnostic

const diagnostic = createDiagnostic({
  code: "TV_MODE_INVALID",
  level: "warning",
  message: 'setMode() received an unknown mode "purple".',
  context: { api: "setMode", property: "mode", received: "purple" },
});

// A caller that treats this as fatal rather than recoverable:
throw ThemeError.fromDiagnostic(diagnostic);

class ThemeRegistry<T extends ThemeDefinition>

A collection of registered theme definitions with deduplication, inheritance-ready metadata stamps, and family queries.

The registry stores theme definitions; resolution of extends chains and token references happens separately via resolveTheme.

Interfaces

AccessibilityPluginOptions

Options for createAccessibilityPlugin.

ActionProminence

The prominence of the primary action fill against the canvas.

AdapterPlugin

A plugin that refines or transforms the output of a library adapter.

refine receives the refined semantic state and may return updates to it; transform receives the generated library variables and must return the final set. Both hooks are optional.

AdapterPluginContext

The context passed to an adapter plugin's hooks. Describes how faithfully the adapter should reproduce the target library's native feel and the current theme mode.

AdapterRegistration

A successful registration returned by AdapterRegistry.use. Calling dispose() removes exactly the adapter instance it was created for — but only when its own reference count drops to zero. This makes composition (React Strict Mode, Svelte lifecycles, nested providers) deterministic.

See also: AdapterRegistry

AdapterRegistry<T extends ThemeDefinition>

The runtime-owned adapter registry. Registering an adapter installs it; the runtime notifies the registry when the active theme changes.

use is idempotent per adapter instance and returns an AdapterRegistration whose dispose() uninstalls deterministically:

const handle = runtime.adapters.use(adapter);
// ... later
handle.dispose();

See also: ThemeAdapter

AnimationsPluginOptions

Options for createAnimationsPlugin.

BrandReferenceColor

One colour from a brand's reference material.

BrandSource

The reference material behind a brand preset.

BroadcastChannelLike<T>

A minimal subset of the BroadcastChannel API used by the broadcast adapters. Accepts any object with the same shape, enabling custom or polyfilled channels.

BroadcastPluginOptions

Options for createBroadcastPlugin.

BuildThemeCssMapOptions

Options for buildThemeCssMap.

CatalogBrand

The brand provenance for a catalog entry.

Three separate things, kept separate on purpose:

1. Identity — the published reference colours and where they came from.
2. Interpretation — the anchors Themvora pinned, and the roles it derived.
3. Normalization — anchors the solver had to move to keep the theme readable.

CodeTokens

Semantic colors for code and syntax surfaces.

Use this group when the application renders syntax-highlighted code, terminals, editors, or documentation code blocks.

This token group is opt-in. Themes that do not define code do not emit --theme-code-* CSS variables.

See also: ThemeTokens

ContextRestriction

A use the system explicitly does not promise, and what to do instead.

This is the half that makes the contract useful. Knowing that primary is not supported as body text is what turns "the brand colour looks weak on this page" into a decision with an obvious answer.

ContextResult

The outcome of evaluating one context against a theme.

ContrastCheck

The result of a single foreground/background contrast check.

ContrastValidationResult

The outcome of validating a theme's color contrast.

CreateDiagnosticInput

Input accepted by createDiagnostic.

code, level and message are required; everything else is optional so a diagnostic carries only what it knows.

CSSVariablesOptions

Options for createCSSVariablesBinding.

The binding keeps CSS custom properties (--theme-*) on a target element (default <html>) in sync with the store, applying the current theme immediately on creation and diffing subsequent updates. It can write variables inline on the target or into a single <style> element wrapped in a cascade layer.

DebuggerPluginOptions

Options for createDebuggerPlugin.

DevToolsPluginOptions

Options for createDevToolsPlugin.

DOMBindingOptions

Options for createDOMBinding.

The binding syncs the store theme to the DOM — data-theme, data-theme-mode, data-theme-family, the dark class and the color-scheme style — with optional transition support. It requires a target element; when none is available the binding is not created.

EffectiveConfiguration<T extends ThemeDefinition>

The outcome of resolving a configuration change: the effective selection and the theme it resolves to.

EmitDiagnosticOptions

Options for emitDiagnostic.

GeneratedThemeLookup<T extends ThemeDefinition>

The result of looking up the generated theme among registered themes.

GeneratedThemePair

The light and dark themes produced by generateTheme.

GenerateThemeOptions

Options for generateTheme.

GenerationPluginOptions

Options for createGenerationPlugin.

HistoryEntry<T extends ThemeDefinition>

A single recorded theme state.

HistoryPluginOptions

Options for createHistoryPlugin.

InitialThemeResolution<T extends ThemeDefinition>

The result of initial theme resolution: the resolved theme plus the resolved selection state.

InvalidOption

A single unusable option inside a live configuration update.

Used by the runtime's configure() validation so the diagnostic names the exact option and value rather than reporting the whole update as invalid.

LevelIssue

A problem found at a specific level.

MeasuredPair

One measured contract pair.

MigrateOptions

Options for migrateTheme.

MigrationStep

A single step in the theme migration chain, moving themes from one version to the next.

MultiWindowSyncOptions

Options for createMultiWindowSync.

Controls which cross-tab synchronization strategy is preferred and how fallbacks are reported.

NonTextCheck

The result of a single non-text UI component contrast check (WCAG 2.1 §1.4.11).

NormalizedAnchor

An anchor the solver had to move, rendered as hex.

OverlayScrollbarHandle

Runtime handle to a live overlay scrollbar instance.

Returned by the scrollbar factory, this handle lets callers force a re-synchronization of layout and physics, or tear down the scrollbar and release all of its DOM, observers, and listeners.

destroy is idempotent: calling it more than once is safe and has no further effect.

OverlayScrollbarOptions

Configuration for the overlay scrollbar engine.

All properties are optional; the engine applies sensible defaults for any omitted value. The browser always performs the actual scrolling — this engine only renders a theme-aware, animated overlay that represents the scrollbar and synchronizes with native scrolling.

Options are resolved once when the scrollbar is created. include/exclude scope which inner scrollables are tracked; the window is always tracked.

ParsedThemeJson

A parsed theme document.

PersistencePluginOptions

Options for createPersistencePlugin.

PluginManager<T extends ThemeDefinition>

Registry that manages the lifecycle of ThemePlugin instances.

The manager stores plugins by name, orders them by priority for hook dispatch, and coordinates creation and destruction. It is created by createPluginManager.

use is idempotent per name: registering an already-registered name is skipped with a warning. destroy invokes onDestroy for every plugin and clears the registry; after destruction the manager is empty.

PresetCatalogEntry

Everything a preset page needs about one preset family.