API reference · Browser runtime

@oriatheme/runtime-dom

Browser external store, atomic DOM application, persistence, Bootstrap, and View Transition.

Package and environment

SSR-safe to import; start, Storage, and DOM writes run only in the browser.

bash

pnpm add @oriatheme/presets @oriatheme/runtime-dom

bash

npm install @oriatheme/presets @oriatheme/runtime-dom

bash

yarn add @oriatheme/presets @oriatheme/runtime-dom

bash

bun add @oriatheme/presets @oriatheme/runtime-dom

Use the package manager and lockfile already chosen by the consumer project. Examples use package-root exports only; do not deep-import from src, dist, or registry templates.

Factory and first-paint APIs

Export	Signature	Description
`createOriaThemeRuntime`	`(config: OriaThemeConfig) => OriaThemeRuntime`	Creates the SSR-safe store and client DOM runtime.
`bootstrapTheme`	`(options?: BootstrapOptions) => void`	Applies one valid active snapshot before framework mount.
`createBootstrapScript`	`(options: BootstrapOptions) => string`	Creates a self-contained script for a caller-supplied snapshot.
`createBootstrapStorageScript`	`(options?) => string`	Creates a head-safe LocalStorage bootstrap script.

import { bootstrapTheme, createOriaThemeRuntime } from "@oriatheme/runtime-dom";
import { oriaPresetThemes } from "@oriatheme/presets";

bootstrapTheme({ contract: { name: "oria-standard", version: 2 } });
const runtime = createOriaThemeRuntime({
  presets: oriaPresetThemes,
  defaultThemeId: "oria-default",
});
runtime.start();

OriaThemeRuntime

Export	Signature	Description
`start / destroy`	`() => void`	Attach or release browser listeners and DOM ownership.
`getSnapshot / subscribe`	`() => ThemeSnapshot / (listener) => unsubscribe`	Read or subscribe to the external store.
`setTheme / setAppearance`	`(id \| mode, options?) => void`	Select an existing theme or user preference; can animate explicit actions.
`createCustomTheme`	`({ theme }) => ThemeDefinition`	Persists a complete valid custom theme.
`updateCustomTheme`	`(id, patch, options?) => ThemeDefinition`	Updates an existing custom theme only.
`duplicateTheme / removeCustomTheme`	`(id, identity) => ThemeDefinition / (id) => void`	Copies a preset/custom theme or removes a custom theme.
`previewTheme`	`(theme, mode?) => PreviewHandle`	Applies a valid in-memory preview; dispose restores formal state.
`exportTheme / importTheme`	`(id) => string / (json, options?) => ThemeDefinition`	Exports a saved theme or imports a fully validated custom theme.
`reset`	`() => void`	Returns runtime preference and custom state to its initial configuration.

Important types and boundaries

OriaThemeConfig requires presets and defaultThemeId; contract defaults to oria-standard@2, and persisted v1 themes are accepted only with an explicitly registered migrations entry (otherwise rejected safely). BootstrapOptions.contract, when declared, restores only exactly matching snapshots. ThemeSnapshot exposes preference, resolvedMode, resolvedTheme, preset/custom lists, and error. ThemeStorage can replace default persistence, and ThemeChangeOptions.animate is for explicit user actions only. Persist appearance, never resolvedMode.