API 参考 · 浏览器 Runtime

@oriatheme/runtime-dom

浏览器端外部 store、原子 DOM 应用、持久化、Bootstrap 与 View Transition。

包与运行环境

SSR 导入安全；start、Storage 和 DOM 写入只在浏览器执行。

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

选择使用方项目已有的一种包管理器和 lockfile；示例只使用 package root export，不要从 src、dist 或 registry template 深层导入。

工厂与首屏 API

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.

重要类型与边界

OriaThemeConfig 要求 presets 和 defaultThemeId；contract 默认 oria-standard@2，migrations 显式注册后才接受 v1 持久化主题（否则安全拒绝）。BootstrapOptions.contract 声明后只恢复完全匹配的 snapshot。ThemeSnapshot 提供 preference、resolvedMode、resolvedTheme、preset/custom 列表和 error。ThemeStorage 可替换默认持久化，ThemeChangeOptions 的 animate 只用于显式用户操作。persist appearance，绝不持久化 resolvedMode。