@windmorph/react 0.0.0-stage → 0.1.1

package/dist/theme/ThemeProvider.d.ts

@@ -0,0 +1,72 @@
+import { BuiltInThemeName, ColorMode, ContrastLevel } from "../tokens/color.js";
+import { Density } from "../tokens/density.js";
+import { MotionScheme } from "../tokens/motion.js";
+import { ThemeDefinition } from "./create-theme.js";
+import { ThemeStorage } from "./state.js";
+import { ReactNode } from "react";
+//#region src/theme/ThemeProvider.d.ts
+export interface ThemeProviderProps {
+  children?: ReactNode;
+  /**
+   * Themes available to `setTheme`: built-in names and/or `createTheme()` results.
+   * Defaults to all six built-in themes.
+   */
+  themes?: ReadonlyArray<BuiltInThemeName | ThemeDefinition>;
+  /** Controlled colour theme. */
+  theme?: string;
+  /** Initial colour theme when uncontrolled. @default "baseline" */
+  defaultTheme?: string;
+  /** Called with the new colour theme when it changes. */
+  onThemeChange?: (theme: string) => void;
+  /** Controlled colour mode. */
+  mode?: ColorMode;
+  /** Initial colour mode when uncontrolled. @default "system" */
+  defaultMode?: ColorMode;
+  /** Called with the new colour mode when it changes. */
+  onModeChange?: (mode: ColorMode) => void;
+  /** Controlled contrast level. */
+  contrast?: ContrastLevel;
+  /** Initial contrast level when uncontrolled. @default "standard" */
+  defaultContrast?: ContrastLevel;
+  /** Called with the new contrast level when it changes. */
+  onContrastChange?: (contrast: ContrastLevel) => void;
+  /** Controlled motion scheme. */
+  motion?: MotionScheme;
+  /** Initial motion scheme when uncontrolled. @default "expressive" */
+  defaultMotion?: MotionScheme;
+  /** Called with the new motion scheme when it changes. */
+  onMotionChange?: (motion: MotionScheme) => void;
+  /**
+   * Controlled web density, `0` to `-3`: each step takes 4px off the height of fields, menus
+   * and other dense-capable components. M3 asks for density to be the reader's choice, not a
+   * default, so offer it as a setting; keep the control that changes it at 48px or more.
+   */
+  density?: Density;
+  /** Initial web density when uncontrolled. @default 0 */
+  defaultDensity?: Density;
+  /** Called with the new density when it changes. */
+  onDensityChange?: (density: Density) => void;
+  /**
+   * Where the selection is remembered. Use `"cookie"` (default) with
+   * `getThemeFromCookies` or `ThemeScript` for flash-free server rendering. Nothing is written
+   * until the selection changes from the one the page loaded with, so a visitor who never
+   * picks a setting gets no cookie.
+   * @default "cookie"
+   */
+  storage?: ThemeStorage;
+  /** Cookie or localStorage key. @default "windmorph-theme" */
+  storageKey?: string;
+  /**
+   * Whether the theme attributes are written to `<html>`. Set to `false` when you
+   * render them yourself or theme a subtree with `ThemeScope` instead.
+   * @default true
+   */
+  applyToDocument?: boolean;
+}
+/**
+ * Provides the colour theme, mode, contrast level, motion scheme and density to the app,
+ * mirrors them as `data-*` attributes on `<html>` and remembers the selection.
+ */
+export declare function ThemeProvider({ children, themes: themeList, theme: themeProp, defaultTheme, onThemeChange, mode: modeProp, defaultMode, onModeChange, contrast: contrastProp, defaultContrast, onContrastChange, motion: motionProp, defaultMotion, onMotionChange, density: densityProp, defaultDensity, onDensityChange, storage, storageKey, applyToDocument }: ThemeProviderProps): import("react").JSX.Element;
+//#endregion
+//# sourceMappingURL=ThemeProvider.d.ts.map

package/dist/theme/ThemeProvider.js

@@ -0,0 +1,144 @@
+"use client";
+import { BUILT_IN_THEME_NAMES } from "../tokens/color.js";
+import { DEFAULT_STORAGE_KEY, DEFAULT_THEME_STATE, parseThemeState, serializeThemeState, themeAttributes } from "./state.js";
+import { DocumentThemeContext, InheritedThemeContext, ThemeContext, ThemeScopeContext } from "./context.js";
+import { readStoredTheme, writeStoredTheme } from "./storage.js";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/theme/ThemeProvider.tsx
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+function subscribeToColorScheme(onChange) {
+	const query = window.matchMedia(DARK_QUERY);
+	query.addEventListener("change", onChange);
+	return () => query.removeEventListener("change", onChange);
+}
+const getSystemMode = () => window.matchMedia(DARK_QUERY).matches ? "dark" : "light";
+const subscribeToNothing = () => () => {};
+/** Re-reads localStorage when another tab changes the theme. Cookies have no change event. */
+function subscribeToStorage(storage, key, onChange) {
+	if (storage !== "local-storage") return () => {};
+	const listener = (event) => {
+		if (event.key === key) onChange();
+	};
+	window.addEventListener("storage", listener);
+	return () => window.removeEventListener("storage", listener);
+}
+/**
+* One theme dimension: the controlled prop wins, then the user's choice in this
+* session, then the stored selection, then the default.
+*/
+function useThemeValue(controlled, stored, defaultValue, onChange) {
+	const [selected, setSelected] = useState(void 0);
+	const value = controlled ?? selected ?? stored ?? defaultValue;
+	return [value, useCallback((next) => {
+		if (controlled === void 0) setSelected(next);
+		if (next !== value) onChange?.(next);
+	}, [
+		controlled,
+		value,
+		onChange
+	])];
+}
+/**
+* Provides the colour theme, mode, contrast level, motion scheme and density to the app,
+* mirrors them as `data-*` attributes on `<html>` and remembers the selection.
+*/
+function ThemeProvider({ children, themes: themeList, theme: themeProp, defaultTheme = DEFAULT_THEME_STATE.theme, onThemeChange, mode: modeProp, defaultMode = DEFAULT_THEME_STATE.mode, onModeChange, contrast: contrastProp, defaultContrast = DEFAULT_THEME_STATE.contrast, onContrastChange, motion: motionProp, defaultMotion = DEFAULT_THEME_STATE.motion, onMotionChange, density: densityProp, defaultDensity = DEFAULT_THEME_STATE.density, onDensityChange, storage = "cookie", storageKey = DEFAULT_STORAGE_KEY, applyToDocument = true }) {
+	const definitions = useMemo(() => (themeList ?? []).filter((entry) => typeof entry !== "string"), [themeList]);
+	const themeNames = useMemo(() => themeList ? themeList.map((entry) => typeof entry === "string" ? entry : entry.name) : BUILT_IN_THEME_NAMES, [themeList]);
+	const storedRaw = useSyncExternalStore(useCallback((onChange) => subscribeToStorage(storage, storageKey, onChange), [storage, storageKey]), () => readStoredTheme(storage, storageKey), () => null);
+	const isHydrated = useSyncExternalStore(subscribeToNothing, () => true, () => false);
+	const stored = useMemo(() => parseThemeState(storedRaw, themeNames), [storedRaw, themeNames]);
+	const [theme, setThemeState] = useThemeValue(themeProp, stored.theme, defaultTheme, onThemeChange);
+	const [mode, setMode] = useThemeValue(modeProp, stored.mode, defaultMode, onModeChange);
+	const [contrast, setContrast] = useThemeValue(contrastProp, stored.contrast, defaultContrast, onContrastChange);
+	const [motion, setMotion] = useThemeValue(motionProp, stored.motion, defaultMotion, onMotionChange);
+	const [density, setDensity] = useThemeValue(densityProp, stored.density, defaultDensity, onDensityChange);
+	const state = useMemo(() => ({
+		theme,
+		mode,
+		contrast,
+		motion,
+		density
+	}), [
+		theme,
+		mode,
+		contrast,
+		motion,
+		density
+	]);
+	const documentTheme = applyToDocument ? state : null;
+	useLayoutEffect(() => {
+		if (!isHydrated || !applyToDocument) return;
+		const root = document.documentElement;
+		for (const [name, value] of Object.entries(themeAttributes(state))) root.setAttribute(name, value);
+	}, [
+		isHydrated,
+		applyToDocument,
+		state
+	]);
+	const loaded = useRef(null);
+	const changed = useRef(false);
+	useEffect(() => {
+		if (!isHydrated || storage === "none") return;
+		const serialized = serializeThemeState(state);
+		loaded.current ??= serialized;
+		if (!changed.current && serialized === loaded.current) return;
+		changed.current = true;
+		writeStoredTheme(storage, storageKey, state);
+	}, [
+		isHydrated,
+		storage,
+		storageKey,
+		state
+	]);
+	const systemMode = useSyncExternalStore(subscribeToColorScheme, getSystemMode, () => "light");
+	const resolvedMode = mode === "system" ? systemMode : mode;
+	const setTheme = useCallback((next) => {
+		if (!themeNames.includes(next)) {
+			if (process.env.NODE_ENV !== "production") console.warn(`[@windmorph/react] setTheme("${next}") ignored: not one of ${themeNames.join(", ")}.`);
+			return;
+		}
+		setThemeState(next);
+	}, [themeNames, setThemeState]);
+	const value = useMemo(() => ({
+		...state,
+		resolvedMode,
+		themes: themeNames,
+		setTheme,
+		setMode,
+		setContrast,
+		setMotion,
+		setDensity
+	}), [
+		state,
+		resolvedMode,
+		themeNames,
+		setTheme,
+		setMode,
+		setContrast,
+		setMotion,
+		setDensity
+	]);
+	return /* @__PURE__ */ jsx(ThemeContext, {
+		value,
+		children: /* @__PURE__ */ jsx(ThemeScopeContext, {
+			value: state,
+			children: /* @__PURE__ */ jsx(DocumentThemeContext, {
+				value: documentTheme,
+				children: /* @__PURE__ */ jsxs(InheritedThemeContext, {
+					value: documentTheme,
+					children: [definitions.map((definition) => /* @__PURE__ */ jsx("style", {
+						href: `windmorph-theme-${definition.name}`,
+						precedence: "windmorph",
+						children: definition.css
+					}, definition.name)), children]
+				})
+			})
+		})
+	});
+}
+//#endregion
+export { ThemeProvider };
+
+//# sourceMappingURL=ThemeProvider.js.map

package/dist/theme/ThemeProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThemeProvider.js","names":[],"sources":["../../src/theme/ThemeProvider.tsx"],"sourcesContent":["'use client';\n\nimport {\n  useCallback,\n  useEffect,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n  type ReactNode,\n} from 'react';\nimport {\n  BUILT_IN_THEME_NAMES,\n  type BuiltInThemeName,\n  type ColorMode,\n  type ContrastLevel,\n  type ResolvedColorMode,\n} from '../tokens/color';\nimport type { Density } from '../tokens/density';\nimport type { MotionScheme } from '../tokens/motion';\nimport {\n  DocumentThemeContext,\n  InheritedThemeContext,\n  ThemeContext,\n  ThemeScopeContext,\n  type ThemeContextValue,\n} from './context';\nimport type { ThemeDefinition } from './create-theme';\nimport {\n  DEFAULT_STORAGE_KEY,\n  DEFAULT_THEME_STATE,\n  parseThemeState,\n  serializeThemeState,\n  themeAttributes,\n  type ThemeState,\n  type ThemeStorage,\n} from './state';\nimport { readStoredTheme, writeStoredTheme } from './storage';\n\nexport interface ThemeProviderProps {\n  children?: ReactNode;\n  /**\n   * Themes available to `setTheme`: built-in names and/or `createTheme()` results.\n   * Defaults to all six built-in themes.\n   */\n  themes?: ReadonlyArray<BuiltInThemeName | ThemeDefinition>;\n  /** Controlled colour theme. */\n  theme?: string;\n  /** Initial colour theme when uncontrolled. @default \"baseline\" */\n  defaultTheme?: string;\n  /** Called with the new colour theme when it changes. */\n  onThemeChange?: (theme: string) => void;\n  /** Controlled colour mode. */\n  mode?: ColorMode;\n  /** Initial colour mode when uncontrolled. @default \"system\" */\n  defaultMode?: ColorMode;\n  /** Called with the new colour mode when it changes. */\n  onModeChange?: (mode: ColorMode) => void;\n  /** Controlled contrast level. */\n  contrast?: ContrastLevel;\n  /** Initial contrast level when uncontrolled. @default \"standard\" */\n  defaultContrast?: ContrastLevel;\n  /** Called with the new contrast level when it changes. */\n  onContrastChange?: (contrast: ContrastLevel) => void;\n  /** Controlled motion scheme. */\n  motion?: MotionScheme;\n  /** Initial motion scheme when uncontrolled. @default \"expressive\" */\n  defaultMotion?: MotionScheme;\n  /** Called with the new motion scheme when it changes. */\n  onMotionChange?: (motion: MotionScheme) => void;\n  /**\n   * Controlled web density, `0` to `-3`: each step takes 4px off the height of fields, menus\n   * and other dense-capable components. M3 asks for density to be the reader's choice, not a\n   * default, so offer it as a setting; keep the control that changes it at 48px or more.\n   */\n  density?: Density;\n  /** Initial web density when uncontrolled. @default 0 */\n  defaultDensity?: Density;\n  /** Called with the new density when it changes. */\n  onDensityChange?: (density: Density) => void;\n  /**\n   * Where the selection is remembered. Use `\"cookie\"` (default) with\n   * `getThemeFromCookies` or `ThemeScript` for flash-free server rendering. Nothing is written\n   * until the selection changes from the one the page loaded with, so a visitor who never\n   * picks a setting gets no cookie.\n   * @default \"cookie\"\n   */\n  storage?: ThemeStorage;\n  /** Cookie or localStorage key. @default \"windmorph-theme\" */\n  storageKey?: string;\n  /**\n   * Whether the theme attributes are written to `<html>`. Set to `false` when you\n   * render them yourself or theme a subtree with `ThemeScope` instead.\n   * @default true\n   */\n  applyToDocument?: boolean;\n}\n\nconst DARK_QUERY = '(prefers-color-scheme: dark)';\n\nfunction subscribeToColorScheme(onChange: () => void) {\n  const query = window.matchMedia(DARK_QUERY);\n  query.addEventListener('change', onChange);\n  return () => query.removeEventListener('change', onChange);\n}\n\nconst getSystemMode = (): ResolvedColorMode =>\n  window.matchMedia(DARK_QUERY).matches ? 'dark' : 'light';\n\nconst subscribeToNothing = () => () => {};\n\n/** Re-reads localStorage when another tab changes the theme. Cookies have no change event. */\nfunction subscribeToStorage(storage: ThemeStorage, key: string, onChange: () => void) {\n  if (storage !== 'local-storage') return () => {};\n  const listener = (event: StorageEvent) => {\n    if (event.key === key) onChange();\n  };\n  window.addEventListener('storage', listener);\n  return () => window.removeEventListener('storage', listener);\n}\n\n/**\n * One theme dimension: the controlled prop wins, then the user's choice in this\n * session, then the stored selection, then the default.\n */\nfunction useThemeValue<T extends string | number>(\n  controlled: T | undefined,\n  stored: T | undefined,\n  defaultValue: T,\n  onChange: ((value: T) => void) | undefined,\n) {\n  const [selected, setSelected] = useState<T | undefined>(undefined);\n  const value = controlled ?? selected ?? stored ?? defaultValue;\n  const setValue = useCallback(\n    (next: T) => {\n      if (controlled === undefined) setSelected(next);\n      if (next !== value) onChange?.(next);\n    },\n    [controlled, value, onChange],\n  );\n  return [value, setValue] as const;\n}\n\n/**\n * Provides the colour theme, mode, contrast level, motion scheme and density to the app,\n * mirrors them as `data-*` attributes on `<html>` and remembers the selection.\n */\nexport function ThemeProvider({\n  children,\n  themes: themeList,\n  theme: themeProp,\n  defaultTheme = DEFAULT_THEME_STATE.theme,\n  onThemeChange,\n  mode: modeProp,\n  defaultMode = DEFAULT_THEME_STATE.mode,\n  onModeChange,\n  contrast: contrastProp,\n  defaultContrast = DEFAULT_THEME_STATE.contrast,\n  onContrastChange,\n  motion: motionProp,\n  defaultMotion = DEFAULT_THEME_STATE.motion,\n  onMotionChange,\n  density: densityProp,\n  defaultDensity = DEFAULT_THEME_STATE.density,\n  onDensityChange,\n  storage = 'cookie',\n  storageKey = DEFAULT_STORAGE_KEY,\n  applyToDocument = true,\n}: ThemeProviderProps) {\n  const definitions = useMemo(\n    () => (themeList ?? []).filter((entry): entry is ThemeDefinition => typeof entry !== 'string'),\n    [themeList],\n  );\n  const themeNames = useMemo(\n    () =>\n      themeList\n        ? themeList.map((entry) => (typeof entry === 'string' ? entry : entry.name))\n        : BUILT_IN_THEME_NAMES,\n    [themeList],\n  );\n\n  // The stored selection is external data that only exists in the browser. Reading it\n  // through useSyncExternalStore renders the server snapshot during hydration and then\n  // the stored value, without a hydration mismatch. `isHydrated` flips in the same pass.\n  const storedRaw = useSyncExternalStore(\n    useCallback(\n      (onChange: () => void) => subscribeToStorage(storage, storageKey, onChange),\n      [storage, storageKey],\n    ),\n    () => readStoredTheme(storage, storageKey),\n    () => null,\n  );\n  const isHydrated = useSyncExternalStore(\n    subscribeToNothing,\n    () => true,\n    () => false,\n  );\n  const stored = useMemo(() => parseThemeState(storedRaw, themeNames), [storedRaw, themeNames]);\n\n  const [theme, setThemeState] = useThemeValue(\n    themeProp,\n    stored.theme,\n    defaultTheme,\n    onThemeChange,\n  );\n  const [mode, setMode] = useThemeValue(modeProp, stored.mode, defaultMode, onModeChange);\n  const [contrast, setContrast] = useThemeValue(\n    contrastProp,\n    stored.contrast,\n    defaultContrast,\n    onContrastChange,\n  );\n  const [motion, setMotion] = useThemeValue(\n    motionProp,\n    stored.motion,\n    defaultMotion,\n    onMotionChange,\n  );\n\n  const [density, setDensity] = useThemeValue(\n    densityProp,\n    stored.density,\n    defaultDensity,\n    onDensityChange,\n  );\n\n  const state = useMemo<ThemeState>(\n    () => ({ theme, mode, contrast, motion, density }),\n    [theme, mode, contrast, motion, density],\n  );\n\n  // What `<html>` carries, for scopes and overlays to put only what differs on their elements.\n  const documentTheme = applyToDocument ? state : null;\n\n  useLayoutEffect(() => {\n    if (!isHydrated || !applyToDocument) return;\n    const root = document.documentElement;\n    for (const [name, value] of Object.entries(themeAttributes(state))) {\n      root.setAttribute(name, value);\n    }\n  }, [isHydrated, applyToDocument, state]);\n\n  // Stored only once the selection changes from the one the page loaded with (the stored one,\n  // or the defaults): a preference is remembered when someone sets it, and a visit that sets\n  // nothing leaves no cookie behind.\n  const loaded = useRef<string | null>(null);\n  const changed = useRef(false);\n  useEffect(() => {\n    if (!isHydrated || storage === 'none') return;\n    const serialized = serializeThemeState(state);\n    loaded.current ??= serialized;\n    if (!changed.current && serialized === loaded.current) return;\n    changed.current = true;\n    writeStoredTheme(storage, storageKey, state);\n  }, [isHydrated, storage, storageKey, state]);\n\n  const systemMode = useSyncExternalStore(\n    subscribeToColorScheme,\n    getSystemMode,\n    (): ResolvedColorMode => 'light',\n  );\n  const resolvedMode = mode === 'system' ? systemMode : mode;\n\n  const setTheme = useCallback(\n    (next: string) => {\n      if (!themeNames.includes(next)) {\n        if (process.env.NODE_ENV !== 'production') {\n          console.warn(\n            `[@windmorph/react] setTheme(\"${next}\") ignored: not one of ${themeNames.join(', ')}.`,\n          );\n        }\n        return;\n      }\n      setThemeState(next);\n    },\n    [themeNames, setThemeState],\n  );\n\n  const value = useMemo<ThemeContextValue>(\n    () => ({\n      ...state,\n      resolvedMode,\n      themes: themeNames,\n      setTheme,\n      setMode,\n      setContrast,\n      setMotion,\n      setDensity,\n    }),\n    [state, resolvedMode, themeNames, setTheme, setMode, setContrast, setMotion, setDensity],\n  );\n\n  return (\n    <ThemeContext value={value}>\n      <ThemeScopeContext value={state}>\n        <DocumentThemeContext value={documentTheme}>\n          <InheritedThemeContext value={documentTheme}>\n            {definitions.map((definition) => (\n              <style\n                key={definition.name}\n                href={`windmorph-theme-${definition.name}`}\n                precedence=\"windmorph\"\n              >\n                {definition.css}\n              </style>\n            ))}\n            {children}\n          </InheritedThemeContext>\n        </DocumentThemeContext>\n      </ThemeScopeContext>\n    </ThemeContext>\n  );\n}\n"],"mappings":"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"}

package/dist/theme/ThemeScope.d.ts

@@ -0,0 +1,32 @@
+import { ColorMode, ContrastLevel } from "../tokens/color.js";
+import { Density } from "../tokens/density.js";
+import { MotionScheme } from "../tokens/motion.js";
+import { ComponentPropsWithRef } from "react";
+//#region src/theme/ThemeScope.d.ts
+export interface ThemeScopeProps extends ComponentPropsWithRef<'div'> {
+  /** Colour theme for this subtree. Inherited when omitted. */
+  theme?: string;
+  /** Colour mode for this subtree. Inherited when omitted. */
+  mode?: ColorMode;
+  /** Contrast level for this subtree. Inherited when omitted. */
+  contrast?: ContrastLevel;
+  /** Motion scheme for this subtree. Inherited when omitted. */
+  motion?: MotionScheme;
+  /**
+   * Web density for this subtree, `0` to `-3` (e.g. a dense data table's filters). Inherited
+   * when omitted.
+   */
+  density?: Density;
+}
+/**
+ * Applies a different theme, mode, contrast level, motion scheme or density to a subtree.
+ * Scopes nest; unset dimensions are inherited from the nearest provider or scope.
+ * Renders a `div` with `text-on-surface` so text picks up the scope's colours.
+ *
+ * Overlays opened inside (menus, dialogs, tooltips) are portalled out of the `div`, so they
+ * get its theme attributes, its `className` and the CSS variables of its `style` on their own
+ * wrapper: component tokens set through the class or as inline variables reach them too.
+ */
+export declare function ThemeScope({ theme, mode, contrast, motion, density, className, style, children, ...props }: ThemeScopeProps): import("react").JSX.Element;
+//#endregion
+//# sourceMappingURL=ThemeScope.d.ts.map

package/dist/theme/ThemeScope.js

@@ -0,0 +1,67 @@
+"use client";
+import { themeAttributesOver } from "./state.js";
+import { InheritedThemeContext, ThemeScopeContext, ThemeScopeLayersContext, useThemeScope, useThemeScopeLayers } from "./context.js";
+import { cn } from "../utils/cn.js";
+import { useContext, useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/theme/ThemeScope.tsx
+/**
+* Applies a different theme, mode, contrast level, motion scheme or density to a subtree.
+* Scopes nest; unset dimensions are inherited from the nearest provider or scope.
+* Renders a `div` with `text-on-surface` so text picks up the scope's colours.
+*
+* Overlays opened inside (menus, dialogs, tooltips) are portalled out of the `div`, so they
+* get its theme attributes, its `className` and the CSS variables of its `style` on their own
+* wrapper: component tokens set through the class or as inline variables reach them too.
+*/
+function ThemeScope({ theme, mode, contrast, motion, density, className, style, children, ...props }) {
+	const parent = useThemeScope();
+	const inherited = useContext(InheritedThemeContext);
+	const parentLayers = useThemeScopeLayers();
+	const layers = useMemo(() => {
+		const variables = Object.fromEntries(Object.entries(style ?? {}).filter(([name, value]) => name.startsWith("--") && value !== void 0 && value !== null).map(([name, value]) => [name, String(value)]));
+		if (!className && Object.keys(variables).length === 0) return parentLayers;
+		return [...parentLayers, {
+			className: className ?? "",
+			variables
+		}];
+	}, [
+		parentLayers,
+		className,
+		style
+	]);
+	const state = useMemo(() => ({
+		theme: theme ?? parent.theme,
+		mode: mode ?? parent.mode,
+		contrast: contrast ?? parent.contrast,
+		motion: motion ?? parent.motion,
+		density: density ?? parent.density
+	}), [
+		theme,
+		mode,
+		contrast,
+		motion,
+		density,
+		parent
+	]);
+	return /* @__PURE__ */ jsx("div", {
+		...props,
+		...themeAttributesOver(state, inherited, layers !== parentLayers),
+		style,
+		className: cn("text-on-surface", className),
+		children: /* @__PURE__ */ jsx(ThemeScopeContext, {
+			value: state,
+			children: /* @__PURE__ */ jsx(InheritedThemeContext, {
+				value: state,
+				children: /* @__PURE__ */ jsx(ThemeScopeLayersContext, {
+					value: layers,
+					children
+				})
+			})
+		})
+	});
+}
+//#endregion
+export { ThemeScope };
+
+//# sourceMappingURL=ThemeScope.js.map

package/dist/theme/ThemeScope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThemeScope.js","names":[],"sources":["../../src/theme/ThemeScope.tsx"],"sourcesContent":["'use client';\n\nimport { useContext, useMemo, type ComponentPropsWithRef } from 'react';\nimport type { ColorMode, ContrastLevel } from '../tokens/color';\nimport type { Density } from '../tokens/density';\nimport type { MotionScheme } from '../tokens/motion';\nimport { cn } from '../utils/cn';\nimport {\n  InheritedThemeContext,\n  ThemeScopeContext,\n  ThemeScopeLayersContext,\n  useThemeScope,\n  useThemeScopeLayers,\n} from './context';\nimport { themeAttributesOver, type ThemeState } from './state';\n\nexport interface ThemeScopeProps extends ComponentPropsWithRef<'div'> {\n  /** Colour theme for this subtree. Inherited when omitted. */\n  theme?: string;\n  /** Colour mode for this subtree. Inherited when omitted. */\n  mode?: ColorMode;\n  /** Contrast level for this subtree. Inherited when omitted. */\n  contrast?: ContrastLevel;\n  /** Motion scheme for this subtree. Inherited when omitted. */\n  motion?: MotionScheme;\n  /**\n   * Web density for this subtree, `0` to `-3` (e.g. a dense data table's filters). Inherited\n   * when omitted.\n   */\n  density?: Density;\n}\n\n/**\n * Applies a different theme, mode, contrast level, motion scheme or density to a subtree.\n * Scopes nest; unset dimensions are inherited from the nearest provider or scope.\n * Renders a `div` with `text-on-surface` so text picks up the scope's colours.\n *\n * Overlays opened inside (menus, dialogs, tooltips) are portalled out of the `div`, so they\n * get its theme attributes, its `className` and the CSS variables of its `style` on their own\n * wrapper: component tokens set through the class or as inline variables reach them too.\n */\nexport function ThemeScope({\n  theme,\n  mode,\n  contrast,\n  motion,\n  density,\n  className,\n  style,\n  children,\n  ...props\n}: ThemeScopeProps) {\n  const parent = useThemeScope();\n  const inherited = useContext(InheritedThemeContext);\n  const parentLayers = useThemeScopeLayers();\n  const layers = useMemo(() => {\n    const variables = Object.fromEntries(\n      Object.entries(style ?? {})\n        .filter(([name, value]) => name.startsWith('--') && value !== undefined && value !== null)\n        .map(([name, value]) => [name, String(value)]),\n    );\n    if (!className && Object.keys(variables).length === 0) return parentLayers;\n    return [...parentLayers, { className: className ?? '', variables }];\n  }, [parentLayers, className, style]);\n  const state = useMemo<ThemeState>(\n    () => ({\n      theme: theme ?? parent.theme,\n      mode: mode ?? parent.mode,\n      contrast: contrast ?? parent.contrast,\n      motion: motion ?? parent.motion,\n      density: density ?? parent.density,\n    }),\n    [theme, mode, contrast, motion, density, parent],\n  );\n\n  return (\n    <div\n      {...props}\n      {...themeAttributesOver(state, inherited, layers !== parentLayers)}\n      style={style}\n      className={cn('text-on-surface', className)}\n    >\n      <ThemeScopeContext value={state}>\n        <InheritedThemeContext value={state}>\n          <ThemeScopeLayersContext value={layers}>{children}</ThemeScopeLayersContext>\n        </InheritedThemeContext>\n      </ThemeScopeContext>\n    </div>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAyCA,SAAgB,WAAW,EACzB,OACA,MACA,UACA,QACA,SACA,WACA,OACA,UACA,GAAG,SACe;CAClB,MAAM,SAAS,cAAc;CAC7B,MAAM,YAAY,WAAW,qBAAqB;CAClD,MAAM,eAAe,oBAAoB;CACzC,MAAM,SAAS,cAAc;EAC3B,MAAM,YAAY,OAAO,YACvB,OAAO,QAAQ,SAAS,CAAC,CAAC,CAAC,CACxB,QAAQ,CAAC,MAAM,WAAW,KAAK,WAAW,IAAI,KAAK,UAAU,KAAA,KAAa,UAAU,IAAI,CAAC,CACzF,KAAK,CAAC,MAAM,WAAW,CAAC,MAAM,OAAO,KAAK,CAAC,CAAC,CACjD;EACA,IAAI,CAAC,aAAa,OAAO,KAAK,SAAS,CAAC,CAAC,WAAW,GAAG,OAAO;EAC9D,OAAO,CAAC,GAAG,cAAc;GAAE,WAAW,aAAa;GAAI;EAAU,CAAC;CACpE,GAAG;EAAC;EAAc;EAAW;CAAK,CAAC;CACnC,MAAM,QAAQ,eACL;EACL,OAAO,SAAS,OAAO;EACvB,MAAM,QAAQ,OAAO;EACrB,UAAU,YAAY,OAAO;EAC7B,QAAQ,UAAU,OAAO;EACzB,SAAS,WAAW,OAAO;CAC7B,IACA;EAAC;EAAO;EAAM;EAAU;EAAQ;EAAS;CAAM,CACjD;CAEA,OACE,oBAAC,OAAD;EACE,GAAI;EACJ,GAAI,oBAAoB,OAAO,WAAW,WAAW,YAAY;EAC1D;EACP,WAAW,GAAG,mBAAmB,SAAS;EAE1C,UAAA,oBAAC,mBAAD;GAAmB,OAAO;GACxB,UAAA,oBAAC,uBAAD;IAAuB,OAAO;IAC5B,UAAA,oBAAC,yBAAD;KAAyB,OAAO;KAAS;IAAkC,CAAA;GACtD,CAAA;EACN,CAAA;CAChB,CAAA;AAET"}

package/dist/theme/ThemeScript.d.ts

@@ -0,0 +1,26 @@
+import { ThemeState, ThemeStorage } from "./state.js";
+//#region src/theme/ThemeScript.d.ts
+export interface ThemeScriptProps {
+  /** Values used when nothing is stored. Must match the `ThemeProvider` defaults. */
+  defaults?: Partial<ThemeState>;
+  /** Must match `ThemeProvider`'s `storage`. @default "cookie" */
+  storage?: Exclude<ThemeStorage, 'none'>;
+  /** Must match `ThemeProvider`'s `storageKey`. */
+  storageKey?: string;
+  /** CSP nonce for the inline script. */
+  nonce?: string;
+}
+/**
+ * Builds the inline script source. It runs before first paint, reads the stored
+ * selection and writes the `data-*` attributes on `<html>`, so static and exported
+ * sites never flash the wrong theme.
+ */
+export declare function getThemeScriptSource({ defaults, storage, storageKey }?: Omit<ThemeScriptProps, 'nonce'>): string;
+/**
+ * Prevents a theme flash on static or exported sites. Render it in `<head>` and add
+ * `suppressHydrationWarning` to `<html>`. With server rendering, prefer
+ * `getThemeFromCookies` from `@windmorph/react/next` instead.
+ */
+export declare function ThemeScript({ nonce, ...options }: ThemeScriptProps): import("react").JSX.Element;
+//#endregion
+//# sourceMappingURL=ThemeScript.d.ts.map

package/dist/theme/ThemeScript.js

@@ -0,0 +1,44 @@
+import { COLOR_MODES, CONTRAST_LEVEL_NAMES } from "../tokens/color.js";
+import { DENSITIES } from "../tokens/density.js";
+import { MOTION_SCHEMES } from "../tokens/motion.js";
+import { DEFAULT_STORAGE_KEY, DEFAULT_THEME_STATE } from "./state.js";
+import { jsx } from "react/jsx-runtime";
+//#region src/theme/ThemeScript.tsx
+/**
+* Builds the inline script source. It runs before first paint, reads the stored
+* selection and writes the `data-*` attributes on `<html>`, so static and exported
+* sites never flash the wrong theme.
+*/
+function getThemeScriptSource({ defaults, storage = "cookie", storageKey = DEFAULT_STORAGE_KEY } = {}) {
+	const config = {
+		defaults: {
+			...DEFAULT_THEME_STATE,
+			...defaults
+		},
+		storage,
+		key: storageKey,
+		cookie: `(?:^|; )${storageKey.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}=([^;]*)`,
+		allowed: {
+			mode: COLOR_MODES,
+			contrast: CONTRAST_LEVEL_NAMES,
+			motion: MOTION_SCHEMES,
+			density: DENSITIES.map(String)
+		}
+	};
+	return `(function(c){try{var r=null;if(c.storage==="cookie"){var m=document.cookie.match(new RegExp(c.cookie));r=m&&m[1]}else{r=localStorage.getItem(c.key)}var p=new URLSearchParams(r?decodeURIComponent(r):""),s={},k;for(k in c.defaults){var v=p.get(k);s[k]=v&&(k==="theme"?/^[a-z][a-z0-9-]*$/.test(v):c.allowed[k].indexOf(v)>-1)?v:c.defaults[k]}var e=document.documentElement;for(k in s)e.setAttribute("data-"+k,s[k])}catch(_){}})(${JSON.stringify(config).replace(/</g, "\\u003c")})`;
+}
+/**
+* Prevents a theme flash on static or exported sites. Render it in `<head>` and add
+* `suppressHydrationWarning` to `<html>`. With server rendering, prefer
+* `getThemeFromCookies` from `@windmorph/react/next` instead.
+*/
+function ThemeScript({ nonce, ...options }) {
+	return /* @__PURE__ */ jsx("script", {
+		nonce,
+		dangerouslySetInnerHTML: { __html: getThemeScriptSource(options) }
+	});
+}
+//#endregion
+export { ThemeScript, getThemeScriptSource };
+
+//# sourceMappingURL=ThemeScript.js.map

package/dist/theme/ThemeScript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThemeScript.js","names":[],"sources":["../../src/theme/ThemeScript.tsx"],"sourcesContent":["import { COLOR_MODES, CONTRAST_LEVEL_NAMES } from '../tokens/color';\nimport { DENSITIES } from '../tokens/density';\nimport { MOTION_SCHEMES } from '../tokens/motion';\nimport {\n  DEFAULT_STORAGE_KEY,\n  DEFAULT_THEME_STATE,\n  type ThemeState,\n  type ThemeStorage,\n} from './state';\n\nexport interface ThemeScriptProps {\n  /** Values used when nothing is stored. Must match the `ThemeProvider` defaults. */\n  defaults?: Partial<ThemeState>;\n  /** Must match `ThemeProvider`'s `storage`. @default \"cookie\" */\n  storage?: Exclude<ThemeStorage, 'none'>;\n  /** Must match `ThemeProvider`'s `storageKey`. */\n  storageKey?: string;\n  /** CSP nonce for the inline script. */\n  nonce?: string;\n}\n\n/**\n * Builds the inline script source. It runs before first paint, reads the stored\n * selection and writes the `data-*` attributes on `<html>`, so static and exported\n * sites never flash the wrong theme.\n */\nexport function getThemeScriptSource({\n  defaults,\n  storage = 'cookie',\n  storageKey = DEFAULT_STORAGE_KEY,\n}: Omit<ThemeScriptProps, 'nonce'> = {}): string {\n  const config = {\n    defaults: { ...DEFAULT_THEME_STATE, ...defaults },\n    storage,\n    key: storageKey,\n    cookie: `(?:^|; )${storageKey.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}=([^;]*)`,\n    allowed: {\n      mode: COLOR_MODES,\n      contrast: CONTRAST_LEVEL_NAMES,\n      motion: MOTION_SCHEMES,\n      density: DENSITIES.map(String),\n    },\n  };\n  return `(function(c){try{var r=null;if(c.storage===\"cookie\"){var m=document.cookie.match(new RegExp(c.cookie));r=m&&m[1]}else{r=localStorage.getItem(c.key)}var p=new URLSearchParams(r?decodeURIComponent(r):\"\"),s={},k;for(k in c.defaults){var v=p.get(k);s[k]=v&&(k===\"theme\"?/^[a-z][a-z0-9-]*$/.test(v):c.allowed[k].indexOf(v)>-1)?v:c.defaults[k]}var e=document.documentElement;for(k in s)e.setAttribute(\"data-\"+k,s[k])}catch(_){}})(${JSON.stringify(config).replace(/</g, '\\\\u003c')})`;\n}\n\n/**\n * Prevents a theme flash on static or exported sites. Render it in `<head>` and add\n * `suppressHydrationWarning` to `<html>`. With server rendering, prefer\n * `getThemeFromCookies` from `@windmorph/react/next` instead.\n */\nexport function ThemeScript({ nonce, ...options }: ThemeScriptProps) {\n  return (\n    <script nonce={nonce} dangerouslySetInnerHTML={{ __html: getThemeScriptSource(options) }} />\n  );\n}\n"],"mappings":";;;;;;;;;;;AA0BA,SAAgB,qBAAqB,EACnC,UACA,UAAU,UACV,aAAa,wBACsB,CAAC,GAAW;CAC/C,MAAM,SAAS;EACb,UAAU;GAAE,GAAG;GAAqB,GAAG;EAAS;EAChD;EACA,KAAK;EACL,QAAQ,WAAW,WAAW,QAAQ,uBAAuB,MAAM,EAAE;EACrE,SAAS;GACP,MAAM;GACN,UAAU;GACV,QAAQ;GACR,SAAS,UAAU,IAAI,MAAM;EAC/B;CACF;CACA,OAAO,2aAA2a,KAAK,UAAU,MAAM,CAAC,CAAC,QAAQ,MAAM,SAAS,EAAE;AACpe;;;;;;AAOA,SAAgB,YAAY,EAAE,OAAO,GAAG,WAA6B;CACnE,OACE,oBAAC,UAAD;EAAe;EAAO,yBAAyB,EAAE,QAAQ,qBAAqB,OAAO,EAAE;CAAI,CAAA;AAE/F"}

package/dist/theme/context.d.ts

@@ -0,0 +1,32 @@
+import { ColorMode, ContrastLevel, ResolvedColorMode } from "../tokens/color.js";
+import { Density } from "../tokens/density.js";
+import { MotionScheme } from "../tokens/motion.js";
+import { ThemeState } from "./state.js";
+//#region src/theme/context.d.ts
+export interface ThemeContextValue extends ThemeState {
+  /** `mode` with `"system"` resolved from `prefers-color-scheme`. */
+  resolvedMode: ResolvedColorMode;
+  /** Names of the themes available to `setTheme`. */
+  themes: readonly string[];
+  /** Switches the colour theme; a name not in `themes` is ignored (with a warning in development). */
+  setTheme: (theme: string) => void;
+  /** Switches the colour mode: `light`, `dark` or `system`. */
+  setMode: (mode: ColorMode) => void;
+  /** Switches the contrast level: `standard`, `medium` or `high`. */
+  setContrast: (contrast: ContrastLevel) => void;
+  /** Switches the motion scheme: `expressive` or `standard`. */
+  setMotion: (motion: MotionScheme) => void;
+  /** Switches the web density, `0` to `-3`. */
+  setDensity: (density: Density) => void;
+}
+/** The theme applied to the nearest `ThemeProvider` or `ThemeScope`. */
+export declare const ThemeScopeContext: import("react").Context<ThemeState>;
+/**
+ * Reads and changes the app theme set by `ThemeProvider`.
+ * @throws if called outside a `ThemeProvider`.
+ */
+export declare function useTheme(): ThemeContextValue;
+/** The theme state in effect at this point in the tree, including any `ThemeScope`. */
+export declare function useThemeScope(): ThemeState;
+//#endregion
+//# sourceMappingURL=context.d.ts.map

package/dist/theme/context.js

@@ -0,0 +1,47 @@
+"use client";
+import { DEFAULT_THEME_STATE } from "./state.js";
+import { createContext, useContext } from "react";
+//#region src/theme/context.ts
+const ThemeContext = createContext(null);
+/** The theme applied to the nearest `ThemeProvider` or `ThemeScope`. */
+const ThemeScopeContext = createContext(DEFAULT_THEME_STATE);
+/**
+* The classes and inline CSS variables of the `ThemeScope`s around this point, outermost first,
+* one layer per scope that sets either, so `Overlay` can repeat them around its portalled
+* content: component tokens an app sets through a scope's class or `style` then reach overlays
+* opened inside it (2026-10-17). Kept per scope (2026-10-24), so an inner scope's value wins
+* however each scope sets it, as on the page.
+*/
+const ThemeScopeLayersContext = createContext([]);
+/**
+* The theme the DOM already carries at this point through `data-*` attributes: the nearest
+* `ThemeScope`'s, or the `ThemeProvider`'s when it writes them on `<html>`; `null` when unknown.
+* A `ThemeScope` puts only the attributes that differ from it on its element.
+*/
+const InheritedThemeContext = createContext(null);
+/**
+* The theme `<html>` carries (the `ThemeProvider`'s, when it writes it there), for `Overlay`'s
+* wrapper in `document.body`; `null` when unknown.
+*/
+const DocumentThemeContext = createContext(null);
+/**
+* Reads and changes the app theme set by `ThemeProvider`.
+* @throws if called outside a `ThemeProvider`.
+*/
+function useTheme() {
+	const value = useContext(ThemeContext);
+	if (!value) throw new Error("[@windmorph/react] useTheme() must be used inside <ThemeProvider>.");
+	return value;
+}
+/** The classes and CSS variables of the `ThemeScope`s around this point (`ThemeScopeLayersContext`). */
+function useThemeScopeLayers() {
+	return useContext(ThemeScopeLayersContext);
+}
+/** The theme state in effect at this point in the tree, including any `ThemeScope`. */
+function useThemeScope() {
+	return useContext(ThemeScopeContext);
+}
+//#endregion
+export { DocumentThemeContext, InheritedThemeContext, ThemeContext, ThemeScopeContext, ThemeScopeLayersContext, useTheme, useThemeScope, useThemeScopeLayers };
+
+//# sourceMappingURL=context.js.map

package/dist/theme/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","names":[],"sources":["../../src/theme/context.ts"],"sourcesContent":["'use client';\n\nimport { createContext, useContext } from 'react';\nimport type { ColorMode, ContrastLevel, ResolvedColorMode } from '../tokens/color';\nimport type { Density } from '../tokens/density';\nimport type { MotionScheme } from '../tokens/motion';\nimport { DEFAULT_THEME_STATE, type ThemeState } from './state';\n\nexport interface ThemeContextValue extends ThemeState {\n  /** `mode` with `\"system\"` resolved from `prefers-color-scheme`. */\n  resolvedMode: ResolvedColorMode;\n  /** Names of the themes available to `setTheme`. */\n  themes: readonly string[];\n  /** Switches the colour theme; a name not in `themes` is ignored (with a warning in development). */\n  setTheme: (theme: string) => void;\n  /** Switches the colour mode: `light`, `dark` or `system`. */\n  setMode: (mode: ColorMode) => void;\n  /** Switches the contrast level: `standard`, `medium` or `high`. */\n  setContrast: (contrast: ContrastLevel) => void;\n  /** Switches the motion scheme: `expressive` or `standard`. */\n  setMotion: (motion: MotionScheme) => void;\n  /** Switches the web density, `0` to `-3`. */\n  setDensity: (density: Density) => void;\n}\n\nexport const ThemeContext = createContext<ThemeContextValue | null>(null);\n\n/** The theme applied to the nearest `ThemeProvider` or `ThemeScope`. */\nexport const ThemeScopeContext = createContext<ThemeState>(DEFAULT_THEME_STATE);\n\n/** One `ThemeScope`'s class and the CSS variables (`--*` keys) of its `style`. */\nexport interface ThemeScopeLayer {\n  className: string;\n  variables: Readonly<Record<string, string>>;\n}\n\n/**\n * The classes and inline CSS variables of the `ThemeScope`s around this point, outermost first,\n * one layer per scope that sets either, so `Overlay` can repeat them around its portalled\n * content: component tokens an app sets through a scope's class or `style` then reach overlays\n * opened inside it (2026-10-17). Kept per scope (2026-10-24), so an inner scope's value wins\n * however each scope sets it, as on the page.\n */\nexport const ThemeScopeLayersContext = createContext<readonly ThemeScopeLayer[]>([]);\n\n/**\n * The theme the DOM already carries at this point through `data-*` attributes: the nearest\n * `ThemeScope`'s, or the `ThemeProvider`'s when it writes them on `<html>`; `null` when unknown.\n * A `ThemeScope` puts only the attributes that differ from it on its element.\n */\nexport const InheritedThemeContext = createContext<ThemeState | null>(null);\n\n/**\n * The theme `<html>` carries (the `ThemeProvider`'s, when it writes it there), for `Overlay`'s\n * wrapper in `document.body`; `null` when unknown.\n */\nexport const DocumentThemeContext = createContext<ThemeState | null>(null);\n\n/**\n * Reads and changes the app theme set by `ThemeProvider`.\n * @throws if called outside a `ThemeProvider`.\n */\nexport function useTheme(): ThemeContextValue {\n  const value = useContext(ThemeContext);\n  if (!value) throw new Error('[@windmorph/react] useTheme() must be used inside <ThemeProvider>.');\n  return value;\n}\n\n/** The classes and CSS variables of the `ThemeScope`s around this point (`ThemeScopeLayersContext`). */\nexport function useThemeScopeLayers(): readonly ThemeScopeLayer[] {\n  return useContext(ThemeScopeLayersContext);\n}\n\n/** The theme state in effect at this point in the tree, including any `ThemeScope`. */\nexport function useThemeScope(): ThemeState {\n  return useContext(ThemeScopeContext);\n}\n"],"mappings":";;;;AAyBA,MAAa,eAAe,cAAwC,IAAI;;AAGxE,MAAa,oBAAoB,cAA0B,mBAAmB;;;;;;;;AAe9E,MAAa,0BAA0B,cAA0C,CAAC,CAAC;;;;;;AAOnF,MAAa,wBAAwB,cAAiC,IAAI;;;;;AAM1E,MAAa,uBAAuB,cAAiC,IAAI;;;;;AAMzE,SAAgB,WAA8B;CAC5C,MAAM,QAAQ,WAAW,YAAY;CACrC,IAAI,CAAC,OAAO,MAAM,IAAI,MAAM,oEAAoE;CAChG,OAAO;AACT;;AAGA,SAAgB,sBAAkD;CAChE,OAAO,WAAW,uBAAuB;AAC3C;;AAGA,SAAgB,gBAA4B;CAC1C,OAAO,WAAW,iBAAiB;AACrC"}

package/dist/theme/create-theme.d.ts

@@ -0,0 +1,60 @@
+import { ContrastLevel, CustomColorName, SchemeVariant, ThemePalettes } from "../tokens/color.js";
+//#region src/theme/create-theme.d.ts
+export interface CreateThemeOptions {
+  /** Theme name used in `data-theme`. Lowercase kebab-case, e.g. `"acme"`. */
+  name: string;
+  /** Seed colour as hex, e.g. `"#0B57D0"`. */
+  seed: string;
+  /** Colour scheme variant. Defaults to `"tonal-spot"`. */
+  variant?: SchemeVariant;
+  /**
+   * Takes some of the scheme's palettes from elsewhere: another variant of the same seed, or
+   * a hex colour. `{ neutral: 'tonal-spot', neutralVariant: 'tonal-spot' }` gives vivid
+   * accents on calm surfaces; `{ tertiary: '#00A07A' }` sets a brand's own tertiary colour.
+   */
+  palettes?: ThemePalettes;
+  /**
+   * The success and warning colours (docs/plans/custom-colors.md); each defaults to a green
+   * and an amber. Only hue and chroma matter: the tones follow M3's error roles.
+   */
+  customColors?: Partial<Record<CustomColorName, `#${string}`>>;
+  /** Turns the custom colours' hues toward the seed, as Material Theme Builder does. @default true */
+  harmonize?: boolean;
+  /** Contrast level(s) to generate. Defaults to all three. */
+  contrast?: ContrastLevel | readonly ContrastLevel[];
+}
+/** A generated colour theme, ready to pass to `ThemeProvider`'s `themes` prop. */
+export interface ThemeDefinition {
+  name: string;
+  seed: string;
+  variant: SchemeVariant;
+  palettes: ThemePalettes;
+  customColors: Partial<Record<CustomColorName, `#${string}`>>;
+  harmonize: boolean;
+  contrast: readonly ContrastLevel[];
+  /** Light, dark and system-mode CSS for each contrast level. */
+  css: string;
+}
+/**
+ * Generates a custom colour theme from a seed colour with the M3 2025 colour spec.
+ * Works at runtime and on the server; for static sites prefer the CLI, which writes
+ * the same CSS to a file.
+ *
+ * @example
+ * const acme = createTheme({ name: 'acme', seed: '#0B57D0' });
+ * <ThemeProvider themes={['baseline', acme]} defaultTheme="acme">…</ThemeProvider>
+ *
+ * // Vivid accents on calm, nearly neutral surfaces.
+ * createTheme({
+ *   name: 'blue',
+ *   seed: '#1877F2',
+ *   variant: 'vibrant',
+ *   palettes: { neutral: 'tonal-spot', neutralVariant: 'tonal-spot' },
+ * });
+ *
+ * // A brand's own status colours, at their exact hues.
+ * createTheme({ name: 'shop', seed: '#0B57D0', customColors: { success: '#0B8043' }, harmonize: false });
+ */
+export declare function createTheme({ name, seed, variant, palettes, customColors, harmonize, contrast }: CreateThemeOptions): ThemeDefinition;
+//#endregion
+//# sourceMappingURL=create-theme.d.ts.map

package/dist/theme/create-theme.js

@@ -0,0 +1,47 @@
+import { CONTRAST_LEVEL_NAMES } from "../tokens/color.js";
+import { assertThemeName, generateThemeCss } from "./css.js";
+//#region src/theme/create-theme.ts
+/**
+* Generates a custom colour theme from a seed colour with the M3 2025 colour spec.
+* Works at runtime and on the server; for static sites prefer the CLI, which writes
+* the same CSS to a file.
+*
+* @example
+* const acme = createTheme({ name: 'acme', seed: '#0B57D0' });
+* <ThemeProvider themes={['baseline', acme]} defaultTheme="acme">…</ThemeProvider>
+*
+* // Vivid accents on calm, nearly neutral surfaces.
+* createTheme({
+*   name: 'blue',
+*   seed: '#1877F2',
+*   variant: 'vibrant',
+*   palettes: { neutral: 'tonal-spot', neutralVariant: 'tonal-spot' },
+* });
+*
+* // A brand's own status colours, at their exact hues.
+* createTheme({ name: 'shop', seed: '#0B57D0', customColors: { success: '#0B8043' }, harmonize: false });
+*/
+function createTheme({ name, seed, variant = "tonal-spot", palettes = {}, customColors = {}, harmonize = true, contrast = CONTRAST_LEVEL_NAMES }) {
+	assertThemeName(name);
+	const contrastLevels = typeof contrast === "string" ? [contrast] : contrast;
+	return {
+		name,
+		seed,
+		variant,
+		palettes,
+		customColors,
+		harmonize,
+		contrast: contrastLevels,
+		css: generateThemeCss(name, {
+			seed,
+			variant,
+			palettes,
+			customColors,
+			harmonize
+		}, { contrastLevels })
+	};
+}
+//#endregion
+export { createTheme };
+
+//# sourceMappingURL=create-theme.js.map