@windmorph/react 0.0.0-stage → 0.1.1

package/dist/theme/create-theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-theme.js","names":[],"sources":["../../src/theme/create-theme.ts"],"sourcesContent":["import {\n  CONTRAST_LEVEL_NAMES,\n  type ContrastLevel,\n  type CustomColorName,\n  type SchemeVariant,\n  type ThemePalettes,\n} from '../tokens/color';\nimport { assertThemeName, generateThemeCss } from './css';\n\nexport interface CreateThemeOptions {\n  /** Theme name used in `data-theme`. Lowercase kebab-case, e.g. `\"acme\"`. */\n  name: string;\n  /** Seed colour as hex, e.g. `\"#0B57D0\"`. */\n  seed: string;\n  /** Colour scheme variant. Defaults to `\"tonal-spot\"`. */\n  variant?: SchemeVariant;\n  /**\n   * Takes some of the scheme's palettes from elsewhere: another variant of the same seed, or\n   * a hex colour. `{ neutral: 'tonal-spot', neutralVariant: 'tonal-spot' }` gives vivid\n   * accents on calm surfaces; `{ tertiary: '#00A07A' }` sets a brand's own tertiary colour.\n   */\n  palettes?: ThemePalettes;\n  /**\n   * The success and warning colours (docs/plans/custom-colors.md); each defaults to a green\n   * and an amber. Only hue and chroma matter: the tones follow M3's error roles.\n   */\n  customColors?: Partial<Record<CustomColorName, `#${string}`>>;\n  /** Turns the custom colours' hues toward the seed, as Material Theme Builder does. @default true */\n  harmonize?: boolean;\n  /** Contrast level(s) to generate. Defaults to all three. */\n  contrast?: ContrastLevel | readonly ContrastLevel[];\n}\n\n/** A generated colour theme, ready to pass to `ThemeProvider`'s `themes` prop. */\nexport interface ThemeDefinition {\n  name: string;\n  seed: string;\n  variant: SchemeVariant;\n  palettes: ThemePalettes;\n  customColors: Partial<Record<CustomColorName, `#${string}`>>;\n  harmonize: boolean;\n  contrast: readonly ContrastLevel[];\n  /** Light, dark and system-mode CSS for each contrast level. */\n  css: string;\n}\n\n/**\n * Generates a custom colour theme from a seed colour with the M3 2025 colour spec.\n * Works at runtime and on the server; for static sites prefer the CLI, which writes\n * the same CSS to a file.\n *\n * @example\n * const acme = createTheme({ name: 'acme', seed: '#0B57D0' });\n * <ThemeProvider themes={['baseline', acme]} defaultTheme=\"acme\">…</ThemeProvider>\n *\n * // Vivid accents on calm, nearly neutral surfaces.\n * createTheme({\n *   name: 'blue',\n *   seed: '#1877F2',\n *   variant: 'vibrant',\n *   palettes: { neutral: 'tonal-spot', neutralVariant: 'tonal-spot' },\n * });\n *\n * // A brand's own status colours, at their exact hues.\n * createTheme({ name: 'shop', seed: '#0B57D0', customColors: { success: '#0B8043' }, harmonize: false });\n */\nexport function createTheme({\n  name,\n  seed,\n  variant = 'tonal-spot',\n  palettes = {},\n  customColors = {},\n  harmonize = true,\n  contrast = CONTRAST_LEVEL_NAMES,\n}: CreateThemeOptions): ThemeDefinition {\n  assertThemeName(name);\n  const contrastLevels: readonly ContrastLevel[] =\n    typeof contrast === 'string' ? [contrast] : contrast;\n  return {\n    name,\n    seed,\n    variant,\n    palettes,\n    customColors,\n    harmonize,\n    contrast: contrastLevels,\n    css: generateThemeCss(\n      name,\n      { seed, variant, palettes, customColors, harmonize },\n      { contrastLevels },\n    ),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAkEA,SAAgB,YAAY,EAC1B,MACA,MACA,UAAU,cACV,WAAW,CAAC,GACZ,eAAe,CAAC,GAChB,YAAY,MACZ,WAAW,wBAC2B;CACtC,gBAAgB,IAAI;CACpB,MAAM,iBACJ,OAAO,aAAa,WAAW,CAAC,QAAQ,IAAI;CAC9C,OAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA,UAAU;EACV,KAAK,iBACH,MACA;GAAE;GAAM;GAAS;GAAU;GAAc;EAAU,GACnD,EAAE,eAAe,CACnB;CACF;AACF"}

package/dist/theme/css.js

@@ -0,0 +1,54 @@
+import { CONTRAST_LEVEL_NAMES } from "../tokens/color.js";
+import { generateSchemeColors } from "./scheme.js";
+//#region src/theme/css.ts
+const THEME_NAME = /^[a-z][a-z0-9-]*$/;
+function assertThemeName(name) {
+	if (!THEME_NAME.test(name)) throw new Error(`[@windmorph/react] Theme names must be lowercase kebab-case (e.g. "acme-blue"), received "${name}".`);
+}
+/**
+* Selectors for one theme × contrast × mode block.
+* A missing `data-contrast` behaves like `standard`; a missing `data-mode` like `light`;
+* the default theme also applies to a root without `data-theme`.
+*
+* Each selector is wrapped in `:where()`, so it has zero specificity and any plain consumer
+* rule (`:root { --md-sys-color-primary: … }`, `[data-theme='ocean'] { … }`) wins. Among the
+* theme's own rules, source order decides: an element matches one theme and one contrast
+* level, and {@link generateThemeCss} writes light before dark and system, so the mode rule
+* that also matches comes later and wins.
+*/
+function selectors(name, contrast, mode, isDefault) {
+	const themeParts = [`[data-theme="${name}"]`];
+	if (isDefault) themeParts.push(":root:not([data-theme])");
+	const contrastParts = [`[data-contrast="${contrast}"]`];
+	if (contrast === "standard") contrastParts.push(":not([data-contrast])");
+	const modePart = mode === "light" ? "" : `[data-mode="${mode}"]`;
+	return themeParts.flatMap((theme) => contrastParts.map((c) => `:where(${theme}${c}${modePart})`)).join(",\n");
+}
+function declarations(seed, mode, contrast) {
+	const colors = generateSchemeColors(seed, mode === "dark", contrast);
+	const lines = Object.entries(colors).map(([role, hex]) => `  --md-sys-color-${role}: ${hex};`);
+	lines.unshift(`  color-scheme: ${mode};`);
+	return lines.join("\n");
+}
+/**
+* CSS for one colour theme: light, dark and system mode for each contrast level,
+* keyed on the `data-theme`, `data-mode` and `data-contrast` attributes. Every selector has
+* zero specificity (`:where()`), so the order of the blocks matters: for each contrast level
+* the light block comes first, then dark, then system inside its media query.
+*/
+function generateThemeCss(name, seed, { contrastLevels = CONTRAST_LEVEL_NAMES, isDefault = false } = {}) {
+	assertThemeName(name);
+	const blocks = [];
+	for (const contrast of contrastLevels) {
+		const light = declarations(seed, "light", contrast);
+		const dark = declarations(seed, "dark", contrast);
+		blocks.push(`${selectors(name, contrast, "light", isDefault)} {\n${light}\n}`);
+		blocks.push(`${selectors(name, contrast, "dark", isDefault)} {\n${dark}\n}`);
+		blocks.push(`@media (prefers-color-scheme: dark) {\n${selectors(name, contrast, "system", isDefault)} {\n${dark}\n}\n}`);
+	}
+	return blocks.join("\n\n");
+}
+//#endregion
+export { assertThemeName, generateThemeCss };
+
+//# sourceMappingURL=css.js.map

package/dist/theme/css.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"css.js","names":[],"sources":["../../src/theme/css.ts"],"sourcesContent":["import {\n  CONTRAST_LEVEL_NAMES,\n  type ContrastLevel,\n  type ResolvedColorMode,\n  type ThemeSeed,\n} from '../tokens/color';\nimport { generateSchemeColors } from './scheme';\n\nconst THEME_NAME = /^[a-z][a-z0-9-]*$/;\n\nexport function assertThemeName(name: string): void {\n  if (!THEME_NAME.test(name)) {\n    throw new Error(\n      `[@windmorph/react] Theme names must be lowercase kebab-case (e.g. \"acme-blue\"), received \"${name}\".`,\n    );\n  }\n}\n\nexport interface ThemeCssOptions {\n  /** Contrast levels to emit. Defaults to all three. */\n  contrastLevels?: readonly ContrastLevel[];\n  /** Also apply this theme where no `data-theme` attribute is set. */\n  isDefault?: boolean;\n}\n\n/**\n * Selectors for one theme × contrast × mode block.\n * A missing `data-contrast` behaves like `standard`; a missing `data-mode` like `light`;\n * the default theme also applies to a root without `data-theme`.\n *\n * Each selector is wrapped in `:where()`, so it has zero specificity and any plain consumer\n * rule (`:root { --md-sys-color-primary: … }`, `[data-theme='ocean'] { … }`) wins. Among the\n * theme's own rules, source order decides: an element matches one theme and one contrast\n * level, and {@link generateThemeCss} writes light before dark and system, so the mode rule\n * that also matches comes later and wins.\n */\nfunction selectors(\n  name: string,\n  contrast: ContrastLevel,\n  mode: ResolvedColorMode | 'system',\n  isDefault: boolean,\n): string {\n  const themeParts = [`[data-theme=\"${name}\"]`];\n  if (isDefault) themeParts.push(':root:not([data-theme])');\n  const contrastParts = [`[data-contrast=\"${contrast}\"]`];\n  if (contrast === 'standard') contrastParts.push(':not([data-contrast])');\n  const modePart = mode === 'light' ? '' : `[data-mode=\"${mode}\"]`;\n\n  return themeParts\n    .flatMap((theme) => contrastParts.map((c) => `:where(${theme}${c}${modePart})`))\n    .join(',\\n');\n}\n\nfunction declarations(seed: ThemeSeed, mode: ResolvedColorMode, contrast: ContrastLevel): string {\n  const colors = generateSchemeColors(seed, mode === 'dark', contrast);\n  const lines = Object.entries(colors).map(([role, hex]) => `  --md-sys-color-${role}: ${hex};`);\n  lines.unshift(`  color-scheme: ${mode};`);\n  return lines.join('\\n');\n}\n\n/**\n * CSS for one colour theme: light, dark and system mode for each contrast level,\n * keyed on the `data-theme`, `data-mode` and `data-contrast` attributes. Every selector has\n * zero specificity (`:where()`), so the order of the blocks matters: for each contrast level\n * the light block comes first, then dark, then system inside its media query.\n */\nexport function generateThemeCss(\n  name: string,\n  seed: ThemeSeed,\n  { contrastLevels = CONTRAST_LEVEL_NAMES, isDefault = false }: ThemeCssOptions = {},\n): string {\n  assertThemeName(name);\n  const blocks: string[] = [];\n  for (const contrast of contrastLevels) {\n    const light = declarations(seed, 'light', contrast);\n    const dark = declarations(seed, 'dark', contrast);\n    blocks.push(`${selectors(name, contrast, 'light', isDefault)} {\\n${light}\\n}`);\n    blocks.push(`${selectors(name, contrast, 'dark', isDefault)} {\\n${dark}\\n}`);\n    blocks.push(\n      `@media (prefers-color-scheme: dark) {\\n${selectors(name, contrast, 'system', isDefault)} {\\n${dark}\\n}\\n}`,\n    );\n  }\n  return blocks.join('\\n\\n');\n}\n"],"mappings":";;;AAQA,MAAM,aAAa;AAEnB,SAAgB,gBAAgB,MAAoB;CAClD,IAAI,CAAC,WAAW,KAAK,IAAI,GACvB,MAAM,IAAI,MACR,6FAA6F,KAAK,GACpG;AAEJ;;;;;;;;;;;;AAoBA,SAAS,UACP,MACA,UACA,MACA,WACQ;CACR,MAAM,aAAa,CAAC,gBAAgB,KAAK,GAAG;CAC5C,IAAI,WAAW,WAAW,KAAK,yBAAyB;CACxD,MAAM,gBAAgB,CAAC,mBAAmB,SAAS,GAAG;CACtD,IAAI,aAAa,YAAY,cAAc,KAAK,uBAAuB;CACvE,MAAM,WAAW,SAAS,UAAU,KAAK,eAAe,KAAK;CAE7D,OAAO,WACJ,SAAS,UAAU,cAAc,KAAK,MAAM,UAAU,QAAQ,IAAI,SAAS,EAAE,CAAC,CAAC,CAC/E,KAAK,KAAK;AACf;AAEA,SAAS,aAAa,MAAiB,MAAyB,UAAiC;CAC/F,MAAM,SAAS,qBAAqB,MAAM,SAAS,QAAQ,QAAQ;CACnE,MAAM,QAAQ,OAAO,QAAQ,MAAM,CAAC,CAAC,KAAK,CAAC,MAAM,SAAS,oBAAoB,KAAK,IAAI,IAAI,EAAE;CAC7F,MAAM,QAAQ,mBAAmB,KAAK,EAAE;CACxC,OAAO,MAAM,KAAK,IAAI;AACxB;;;;;;;AAQA,SAAgB,iBACd,MACA,MACA,EAAE,iBAAiB,sBAAsB,YAAY,UAA2B,CAAC,GACzE;CACR,gBAAgB,IAAI;CACpB,MAAM,SAAmB,CAAC;CAC1B,KAAK,MAAM,YAAY,gBAAgB;EACrC,MAAM,QAAQ,aAAa,MAAM,SAAS,QAAQ;EAClD,MAAM,OAAO,aAAa,MAAM,QAAQ,QAAQ;EAChD,OAAO,KAAK,GAAG,UAAU,MAAM,UAAU,SAAS,SAAS,EAAE,MAAM,MAAM,IAAI;EAC7E,OAAO,KAAK,GAAG,UAAU,MAAM,UAAU,QAAQ,SAAS,EAAE,MAAM,KAAK,IAAI;EAC3E,OAAO,KACL,0CAA0C,UAAU,MAAM,UAAU,UAAU,SAAS,EAAE,MAAM,KAAK,OACtG;CACF;CACA,OAAO,OAAO,KAAK,MAAM;AAC3B"}

package/dist/theme/parse-palettes.js

@@ -0,0 +1,40 @@
+import { CUSTOM_COLORS, PALETTE_NAMES } from "../tokens/color.js";
+//#region src/theme/parse-palettes.ts
+/** `neutralVariant` → `neutral-variant`, the spelling the CLI shows. */
+function toKebabCase(name) {
+	return name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+/**
+* Reads `<name>=<source>` entries (the CLI's `--palette` values) into `ThemePalettes`.
+* Names may be kebab- or camel-case. Sources are checked later by `createTheme`.
+*/
+function parsePalettes(entries) {
+	const palettes = {};
+	for (const entry of entries) {
+		const separator = entry.indexOf("=");
+		const rawName = separator === -1 ? entry : entry.slice(0, separator);
+		const source = separator === -1 ? "" : entry.slice(separator + 1).trim();
+		const name = PALETTE_NAMES.find((candidate) => candidate === rawName.trim() || toKebabCase(candidate) === rawName.trim());
+		if (!name || source === "") throw new Error(`--palette expects <name>=<source> with a name from ${PALETTE_NAMES.map(toKebabCase).join(", ")}, received "${entry}".`);
+		palettes[name] = source;
+	}
+	return palettes;
+}
+/**
+* Reads `<name>=<hex>` entries (the CLI's `--custom` values) into custom colours, for
+* `success` and `warning`. Colours are checked later by `createTheme`.
+*/
+function parseCustomColors(entries) {
+	const colors = {};
+	for (const entry of entries) {
+		const [rawName = "", color = ""] = entry.split("=").map((part) => part.trim());
+		const name = CUSTOM_COLORS.find((candidate) => candidate === rawName);
+		if (!name || !color.startsWith("#")) throw new Error(`--custom expects <name>=<hex> with a name from ${CUSTOM_COLORS.join(", ")}, received "${entry}".`);
+		colors[name] = color;
+	}
+	return colors;
+}
+//#endregion
+export { parseCustomColors, parsePalettes, toKebabCase };
+
+//# sourceMappingURL=parse-palettes.js.map

package/dist/theme/parse-palettes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-palettes.js","names":[],"sources":["../../src/theme/parse-palettes.ts"],"sourcesContent":["import {\n  CUSTOM_COLORS,\n  PALETTE_NAMES,\n  type CustomColorName,\n  type PaletteSource,\n  type ThemePalettes,\n} from '../tokens/color';\n\n/** `neutralVariant` → `neutral-variant`, the spelling the CLI shows. */\nexport function toKebabCase(name: string): string {\n  return name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);\n}\n\n/**\n * Reads `<name>=<source>` entries (the CLI's `--palette` values) into `ThemePalettes`.\n * Names may be kebab- or camel-case. Sources are checked later by `createTheme`.\n */\nexport function parsePalettes(entries: readonly string[]): ThemePalettes {\n  const palettes: ThemePalettes = {};\n  for (const entry of entries) {\n    const separator = entry.indexOf('=');\n    const rawName = separator === -1 ? entry : entry.slice(0, separator);\n    const source = separator === -1 ? '' : entry.slice(separator + 1).trim();\n    const name = PALETTE_NAMES.find(\n      (candidate) => candidate === rawName.trim() || toKebabCase(candidate) === rawName.trim(),\n    );\n    if (!name || source === '') {\n      throw new Error(\n        `--palette expects <name>=<source> with a name from ${PALETTE_NAMES.map(toKebabCase).join(', ')}, received \"${entry}\".`,\n      );\n    }\n    palettes[name] = source as PaletteSource;\n  }\n  return palettes;\n}\n\n/**\n * Reads `<name>=<hex>` entries (the CLI's `--custom` values) into custom colours, for\n * `success` and `warning`. Colours are checked later by `createTheme`.\n */\nexport function parseCustomColors(\n  entries: readonly string[],\n): Partial<Record<CustomColorName, `#${string}`>> {\n  const colors: Partial<Record<CustomColorName, `#${string}`>> = {};\n  for (const entry of entries) {\n    const [rawName = '', color = ''] = entry.split('=').map((part) => part.trim());\n    const name = CUSTOM_COLORS.find((candidate) => candidate === rawName);\n    if (!name || !color.startsWith('#')) {\n      throw new Error(\n        `--custom expects <name>=<hex> with a name from ${CUSTOM_COLORS.join(', ')}, received \"${entry}\".`,\n      );\n    }\n    colors[name] = color as `#${string}`;\n  }\n  return colors;\n}\n"],"mappings":";;;AASA,SAAgB,YAAY,MAAsB;CAChD,OAAO,KAAK,QAAQ,WAAW,WAAW,IAAI,OAAO,YAAY,GAAG;AACtE;;;;;AAMA,SAAgB,cAAc,SAA2C;CACvE,MAAM,WAA0B,CAAC;CACjC,KAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,YAAY,MAAM,QAAQ,GAAG;EACnC,MAAM,UAAU,cAAc,KAAK,QAAQ,MAAM,MAAM,GAAG,SAAS;EACnE,MAAM,SAAS,cAAc,KAAK,KAAK,MAAM,MAAM,YAAY,CAAC,CAAC,CAAC,KAAK;EACvE,MAAM,OAAO,cAAc,MACxB,cAAc,cAAc,QAAQ,KAAK,KAAK,YAAY,SAAS,MAAM,QAAQ,KAAK,CACzF;EACA,IAAI,CAAC,QAAQ,WAAW,IACtB,MAAM,IAAI,MACR,sDAAsD,cAAc,IAAI,WAAW,CAAC,CAAC,KAAK,IAAI,EAAE,cAAc,MAAM,GACtH;EAEF,SAAS,QAAQ;CACnB;CACA,OAAO;AACT;;;;;AAMA,SAAgB,kBACd,SACgD;CAChD,MAAM,SAAyD,CAAC;CAChE,KAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,CAAC,UAAU,IAAI,QAAQ,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,SAAS,KAAK,KAAK,CAAC;EAC7E,MAAM,OAAO,cAAc,MAAM,cAAc,cAAc,OAAO;EACpE,IAAI,CAAC,QAAQ,CAAC,MAAM,WAAW,GAAG,GAChC,MAAM,IAAI,MACR,kDAAkD,cAAc,KAAK,IAAI,EAAE,cAAc,MAAM,GACjG;EAEF,OAAO,QAAQ;CACjB;CACA,OAAO;AACT"}

package/dist/theme/scheme.d.ts

@@ -0,0 +1,6 @@
+import { ColorRole, ContrastLevel, ThemeSeed } from "../tokens/color.js";
+//#region src/theme/scheme.d.ts
+/** Resolves every colour role to a hex value using the 2025 colour spec. */
+export declare function generateSchemeColors(seed: ThemeSeed, isDark: boolean, contrast: ContrastLevel): Record<ColorRole, string>;
+//#endregion
+//# sourceMappingURL=scheme.d.ts.map

package/dist/theme/scheme.js

@@ -0,0 +1,118 @@
+import { COLOR_ROLES, CONTRAST_LEVELS, CUSTOM_COLORS, CUSTOM_COLOR_ROLES, DEFAULT_CUSTOM_COLORS, PALETTE_NAMES, SCHEME_VARIANTS } from "../tokens/color.js";
+import { Hct } from "../vendor/material-color-utilities/hct/hct.js";
+import { Blend } from "../vendor/material-color-utilities/blend/blend.js";
+import { TonalPalette } from "../vendor/material-color-utilities/palettes/tonal_palette.js";
+import { MaterialDynamicColors } from "../vendor/material-color-utilities/dynamiccolor/material_dynamic_colors.js";
+import { DynamicScheme } from "../vendor/material-color-utilities/dynamiccolor/dynamic_scheme.js";
+import { SchemeExpressive } from "../vendor/material-color-utilities/scheme/scheme_expressive.js";
+import { SchemeNeutral } from "../vendor/material-color-utilities/scheme/scheme_neutral.js";
+import { SchemeTonalSpot } from "../vendor/material-color-utilities/scheme/scheme_tonal_spot.js";
+import { SchemeVibrant } from "../vendor/material-color-utilities/scheme/scheme_vibrant.js";
+import { argbFromHex, hexFromArgb } from "../vendor/material-color-utilities/utils/string_utils.js";
+import "../vendor/material-color-utilities/index.js";
+//#region src/theme/scheme.ts
+const SCHEMES = {
+	"tonal-spot": SchemeTonalSpot,
+	neutral: SchemeNeutral,
+	vibrant: SchemeVibrant,
+	expressive: SchemeExpressive
+};
+const HEX_COLOR = /^#(?:[0-9a-f]{3}){1,2}$/i;
+const toCamelCase = (role) => role.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+const dynamicColors = new MaterialDynamicColors();
+function roleColor(role) {
+	const method = toCamelCase(role);
+	const factory = dynamicColors[method];
+	if (typeof factory !== "function") throw new Error(`[@windmorph/react] Unknown colour role "${role}".`);
+	const color = factory.call(dynamicColors);
+	if (!color) throw new Error(`[@windmorph/react] Colour role "${role}" is not defined by the 2025 spec.`);
+	return color;
+}
+function assertHexColor(value) {
+	if (!HEX_COLOR.test(value)) throw new Error(`[@windmorph/react] Expected a hex colour like "#6750A4", received "${value}".`);
+}
+const isSchemeVariant = (source) => SCHEME_VARIANTS.includes(source);
+/** The `DynamicScheme` field that holds each palette. */
+const PALETTE_FIELDS = {
+	primary: "primaryPalette",
+	secondary: "secondaryPalette",
+	tertiary: "tertiaryPalette",
+	error: "errorPalette",
+	neutral: "neutralPalette",
+	neutralVariant: "neutralVariantPalette"
+};
+function assertPalettes(palettes) {
+	for (const [name, source] of Object.entries(palettes)) {
+		if (!PALETTE_NAMES.includes(name)) throw new Error(`[@windmorph/react] Unknown palette "${name}". Use one of ${PALETTE_NAMES.join(", ")}.`);
+		if (typeof source !== "string" || !isSchemeVariant(source) && !HEX_COLOR.test(source)) throw new Error(`[@windmorph/react] The ${name} palette needs a scheme variant (${SCHEME_VARIANTS.join(", ")}) or a hex colour like "#00A07A", received "${String(source)}".`);
+	}
+}
+function variantScheme(seed, variant, isDark, contrast) {
+	return new SCHEMES[variant](seed, isDark, CONTRAST_LEVELS[contrast], "2025");
+}
+function createScheme({ seed, variant, palettes }, isDark, contrast) {
+	assertHexColor(seed);
+	const sourceColor = Hct.fromInt(argbFromHex(seed));
+	const scheme = variantScheme(sourceColor, variant, isDark, contrast);
+	const overrides = Object.entries(palettes ?? {});
+	if (overrides.length === 0) return scheme;
+	assertPalettes(palettes ?? {});
+	const paletteFrom = (name, source) => isSchemeVariant(source) ? variantScheme(sourceColor, source, isDark, contrast)[PALETTE_FIELDS[name]] : TonalPalette.fromInt(argbFromHex(source));
+	const chosen = Object.fromEntries(PALETTE_NAMES.map((name) => [PALETTE_FIELDS[name], scheme[PALETTE_FIELDS[name]]]));
+	for (const [name, source] of overrides) chosen[PALETTE_FIELDS[name]] = paletteFrom(name, source);
+	return new DynamicScheme({
+		sourceColorHct: sourceColor,
+		variant: scheme.variant,
+		isDark,
+		contrastLevel: CONTRAST_LEVELS[contrast],
+		specVersion: scheme.specVersion,
+		platform: scheme.platform,
+		...chosen
+	});
+}
+/** The same scheme with another palette in the error slot. */
+function withErrorPalette(scheme, palette) {
+	return new DynamicScheme({
+		sourceColorHct: scheme.sourceColorHct,
+		variant: scheme.variant,
+		isDark: scheme.isDark,
+		contrastLevel: scheme.contrastLevel,
+		specVersion: scheme.specVersion,
+		platform: scheme.platform,
+		primaryPalette: scheme.primaryPalette,
+		secondaryPalette: scheme.secondaryPalette,
+		tertiaryPalette: scheme.tertiaryPalette,
+		neutralPalette: scheme.neutralPalette,
+		neutralVariantPalette: scheme.neutralVariantPalette,
+		errorPalette: palette
+	});
+}
+/**
+* A custom colour's four roles (docs/plans/custom-colors.md): its tonal palette, harmonised
+* toward the seed unless turned off, takes the error roles' tone rules, so it has the
+* contrast M3 guarantees for error in every mode and at every contrast level.
+*/
+function customColorRoles(scheme, name, color, harmonize) {
+	assertHexColor(color);
+	const argb = argbFromHex(color);
+	const custom = withErrorPalette(scheme, TonalPalette.fromInt(harmonize ? Blend.harmonize(argb, scheme.sourceColorHct.toInt()) : argb));
+	const tone = (color) => hexFromArgb(color.getArgb(custom));
+	return {
+		[name]: tone(dynamicColors.error()),
+		[`on-${name}`]: tone(dynamicColors.onError()),
+		[`${name}-container`]: tone(dynamicColors.errorContainer()),
+		[`on-${name}-container`]: tone(dynamicColors.onErrorContainer())
+	};
+}
+const isCustomRole = (role) => CUSTOM_COLOR_ROLES.includes(role);
+/** Resolves every colour role to a hex value using the 2025 colour spec. */
+function generateSchemeColors(seed, isDark, contrast) {
+	const scheme = createScheme(seed, isDark, contrast);
+	const colors = Object.fromEntries(COLOR_ROLES.filter((role) => !isCustomRole(role)).map((role) => [role, hexFromArgb(roleColor(role).getArgb(scheme))]));
+	for (const name of CUSTOM_COLORS) Object.assign(colors, customColorRoles(scheme, name, seed.customColors?.[name] ?? DEFAULT_CUSTOM_COLORS[name], seed.harmonize ?? true));
+	return colors;
+}
+//#endregion
+export { assertHexColor, generateSchemeColors };
+
+//# sourceMappingURL=scheme.js.map

package/dist/theme/scheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheme.js","names":[],"sources":["../../src/theme/scheme.ts"],"sourcesContent":["import {\n  Blend,\n  DynamicScheme,\n  Hct,\n  MaterialDynamicColors,\n  SchemeExpressive,\n  SchemeNeutral,\n  SchemeTonalSpot,\n  SchemeVibrant,\n  TonalPalette,\n  argbFromHex,\n  hexFromArgb,\n  type DynamicColor,\n} from '@material/material-color-utilities';\nimport {\n  COLOR_ROLES,\n  CONTRAST_LEVELS,\n  CUSTOM_COLORS,\n  CUSTOM_COLOR_ROLES,\n  DEFAULT_CUSTOM_COLORS,\n  PALETTE_NAMES,\n  SCHEME_VARIANTS,\n  type ColorRole,\n  type ContrastLevel,\n  type CustomColorName,\n  type PaletteName,\n  type PaletteSource,\n  type SchemeVariant,\n  type ThemePalettes,\n  type ThemeSeed,\n} from '../tokens/color';\n\nconst SCHEMES = {\n  'tonal-spot': SchemeTonalSpot,\n  neutral: SchemeNeutral,\n  vibrant: SchemeVibrant,\n  expressive: SchemeExpressive,\n} satisfies Record<SchemeVariant, unknown>;\n\nconst HEX_COLOR = /^#(?:[0-9a-f]{3}){1,2}$/i;\n\nconst toCamelCase = (role: string) => role.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());\n\nconst dynamicColors = new MaterialDynamicColors();\n\nfunction roleColor(role: ColorRole): DynamicColor {\n  const method = toCamelCase(role) as keyof MaterialDynamicColors;\n  const factory = dynamicColors[method];\n  if (typeof factory !== 'function') {\n    throw new Error(`[@windmorph/react] Unknown colour role \"${role}\".`);\n  }\n  const color = (factory as () => DynamicColor | undefined).call(dynamicColors);\n  if (!color)\n    throw new Error(`[@windmorph/react] Colour role \"${role}\" is not defined by the 2025 spec.`);\n  return color;\n}\n\nexport function assertHexColor(value: string): void {\n  if (!HEX_COLOR.test(value)) {\n    throw new Error(\n      `[@windmorph/react] Expected a hex colour like \"#6750A4\", received \"${value}\".`,\n    );\n  }\n}\n\nconst isSchemeVariant = (source: string): source is SchemeVariant =>\n  (SCHEME_VARIANTS as readonly string[]).includes(source);\n\n/** The `DynamicScheme` field that holds each palette. */\nconst PALETTE_FIELDS = {\n  primary: 'primaryPalette',\n  secondary: 'secondaryPalette',\n  tertiary: 'tertiaryPalette',\n  error: 'errorPalette',\n  neutral: 'neutralPalette',\n  neutralVariant: 'neutralVariantPalette',\n} as const satisfies Record<PaletteName, keyof DynamicScheme>;\n\nfunction assertPalettes(palettes: ThemePalettes): void {\n  for (const [name, source] of Object.entries(palettes)) {\n    if (!(PALETTE_NAMES as readonly string[]).includes(name)) {\n      throw new Error(\n        `[@windmorph/react] Unknown palette \"${name}\". Use one of ${PALETTE_NAMES.join(', ')}.`,\n      );\n    }\n    if (typeof source !== 'string' || (!isSchemeVariant(source) && !HEX_COLOR.test(source))) {\n      throw new Error(\n        `[@windmorph/react] The ${name} palette needs a scheme variant (${SCHEME_VARIANTS.join(', ')}) or a hex colour like \"#00A07A\", received \"${String(source)}\".`,\n      );\n    }\n  }\n}\n\nfunction variantScheme(\n  seed: Hct,\n  variant: SchemeVariant,\n  isDark: boolean,\n  contrast: ContrastLevel,\n): DynamicScheme {\n  return new SCHEMES[variant](seed, isDark, CONTRAST_LEVELS[contrast], '2025');\n}\n\nfunction createScheme(\n  { seed, variant, palettes }: Pick<ThemeSeed, 'seed' | 'variant' | 'palettes'>,\n  isDark: boolean,\n  contrast: ContrastLevel,\n): DynamicScheme {\n  assertHexColor(seed);\n  const sourceColor = Hct.fromInt(argbFromHex(seed));\n  const scheme = variantScheme(sourceColor, variant, isDark, contrast);\n  const overrides = Object.entries(palettes ?? {}) as [PaletteName, PaletteSource][];\n  if (overrides.length === 0) return scheme;\n  assertPalettes(palettes ?? {});\n\n  // Every palette starts as the variant's own; each override replaces one. Roles still take\n  // their tones from the theme's variant, so the spec's contrast rules hold.\n  const paletteFrom = (name: PaletteName, source: PaletteSource): TonalPalette =>\n    isSchemeVariant(source)\n      ? variantScheme(sourceColor, source, isDark, contrast)[PALETTE_FIELDS[name]]\n      : TonalPalette.fromInt(argbFromHex(source));\n  const chosen = Object.fromEntries(\n    PALETTE_NAMES.map((name) => [PALETTE_FIELDS[name], scheme[PALETTE_FIELDS[name]]]),\n  ) as Record<(typeof PALETTE_FIELDS)[PaletteName], TonalPalette>;\n  for (const [name, source] of overrides) chosen[PALETTE_FIELDS[name]] = paletteFrom(name, source);\n\n  return new DynamicScheme({\n    sourceColorHct: sourceColor,\n    variant: scheme.variant,\n    isDark,\n    contrastLevel: CONTRAST_LEVELS[contrast],\n    specVersion: scheme.specVersion,\n    platform: scheme.platform,\n    ...chosen,\n  });\n}\n\n/** The same scheme with another palette in the error slot. */\nfunction withErrorPalette(scheme: DynamicScheme, palette: TonalPalette): DynamicScheme {\n  return new DynamicScheme({\n    sourceColorHct: scheme.sourceColorHct,\n    variant: scheme.variant,\n    isDark: scheme.isDark,\n    contrastLevel: scheme.contrastLevel,\n    specVersion: scheme.specVersion,\n    platform: scheme.platform,\n    primaryPalette: scheme.primaryPalette,\n    secondaryPalette: scheme.secondaryPalette,\n    tertiaryPalette: scheme.tertiaryPalette,\n    neutralPalette: scheme.neutralPalette,\n    neutralVariantPalette: scheme.neutralVariantPalette,\n    errorPalette: palette,\n  });\n}\n\n/**\n * A custom colour's four roles (docs/plans/custom-colors.md): its tonal palette, harmonised\n * toward the seed unless turned off, takes the error roles' tone rules, so it has the\n * contrast M3 guarantees for error in every mode and at every contrast level.\n */\nfunction customColorRoles(\n  scheme: DynamicScheme,\n  name: CustomColorName,\n  color: string,\n  harmonize: boolean,\n): Partial<Record<ColorRole, string>> {\n  assertHexColor(color);\n  const argb = argbFromHex(color);\n  const palette = TonalPalette.fromInt(\n    harmonize ? Blend.harmonize(argb, scheme.sourceColorHct.toInt()) : argb,\n  );\n  const custom = withErrorPalette(scheme, palette);\n  const tone = (color: DynamicColor) => hexFromArgb(color.getArgb(custom));\n  return {\n    [name]: tone(dynamicColors.error()),\n    [`on-${name}`]: tone(dynamicColors.onError()),\n    [`${name}-container`]: tone(dynamicColors.errorContainer()),\n    [`on-${name}-container`]: tone(dynamicColors.onErrorContainer()),\n  };\n}\n\nconst isCustomRole = (role: ColorRole) =>\n  (CUSTOM_COLOR_ROLES as readonly ColorRole[]).includes(role);\n\n/** Resolves every colour role to a hex value using the 2025 colour spec. */\nexport function generateSchemeColors(\n  seed: ThemeSeed,\n  isDark: boolean,\n  contrast: ContrastLevel,\n): Record<ColorRole, string> {\n  const scheme = createScheme(seed, isDark, contrast);\n  const colors: Partial<Record<ColorRole, string>> = Object.fromEntries(\n    COLOR_ROLES.filter((role) => !isCustomRole(role)).map((role) => [\n      role,\n      hexFromArgb(roleColor(role).getArgb(scheme)),\n    ]),\n  );\n  for (const name of CUSTOM_COLORS) {\n    Object.assign(\n      colors,\n      customColorRoles(\n        scheme,\n        name,\n        seed.customColors?.[name] ?? DEFAULT_CUSTOM_COLORS[name],\n        seed.harmonize ?? true,\n      ),\n    );\n  }\n  return colors as Record<ColorRole, string>;\n}\n"],"mappings":"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"}

package/dist/theme/state.d.ts

@@ -0,0 +1,38 @@
+import { ColorMode, ContrastLevel } from "../tokens/color.js";
+import { Density } from "../tokens/density.js";
+import { MotionScheme } from "../tokens/motion.js";
+//#region src/theme/state.d.ts
+/** The theme dimensions, mirrored as `data-*` attributes. */
+export interface ThemeState {
+  /** The colour theme's name: a built-in (`baseline`, `ocean` …) or one made with `createTheme`. */
+  theme: string;
+  /** `light`, `dark` or `system` (follows `prefers-color-scheme`). */
+  mode: ColorMode;
+  /** `standard`, `medium` or `high`. */
+  contrast: ContrastLevel;
+  /** `expressive` (springs that overshoot) or `standard` (no visible overshoot). */
+  motion: MotionScheme;
+  /** Web density, `0` (default) to `-3` (densest); see `Density`. */
+  density: Density;
+}
+export declare const DEFAULT_THEME_STATE: ThemeState;
+/** Where the selected theme is remembered between visits. */
+export type ThemeStorage = 'cookie' | 'local-storage' | 'none';
+export declare const DEFAULT_STORAGE_KEY = "windmorph-theme";
+/** Serialises a theme state for a cookie or localStorage value. */
+export declare function serializeThemeState(state: ThemeState): string;
+/**
+ * Parses a stored theme state. Unknown or invalid values are dropped, so the
+ * result only contains fields that can be trusted.
+ */
+export declare function parseThemeState(raw: string | null | undefined, themes?: readonly string[]): Partial<ThemeState>;
+/** The `data-*` attributes for a theme state, for `<html>` or any themed element. */
+export declare function themeAttributes(state: ThemeState): {
+  readonly 'data-theme': string;
+  readonly 'data-mode': "light" | "dark" | "system";
+  readonly 'data-contrast': "standard" | "medium" | "high";
+  readonly 'data-motion': "standard" | "expressive";
+  readonly 'data-density': "0" | "-1" | "-2" | "-3";
+};
+//#endregion
+//# sourceMappingURL=state.d.ts.map

package/dist/theme/state.js

@@ -0,0 +1,93 @@
+import { COLOR_MODES, CONTRAST_LEVEL_NAMES, DEFAULT_THEME } from "../tokens/color.js";
+import { isDensity } from "../tokens/density.js";
+import { DEFAULT_MOTION_SCHEME, MOTION_SCHEMES } from "../tokens/motion.js";
+//#region src/theme/state.ts
+const DEFAULT_THEME_STATE = {
+	theme: DEFAULT_THEME,
+	mode: "system",
+	contrast: "standard",
+	motion: DEFAULT_MOTION_SCHEME,
+	density: 0
+};
+const DEFAULT_STORAGE_KEY = "windmorph-theme";
+const THEME_NAME = /^[a-z][a-z0-9-]*$/;
+const includes = (list, value) => typeof value === "string" && list.includes(value);
+/** Serialises a theme state for a cookie or localStorage value. */
+function serializeThemeState(state) {
+	return encodeURIComponent(new URLSearchParams({
+		theme: state.theme,
+		mode: state.mode,
+		contrast: state.contrast,
+		motion: state.motion,
+		density: String(state.density)
+	}).toString());
+}
+/**
+* Parses a stored theme state. Unknown or invalid values are dropped, so the
+* result only contains fields that can be trusted.
+*/
+function parseThemeState(raw, themes) {
+	if (!raw) return {};
+	let params;
+	try {
+		params = new URLSearchParams(decodeURIComponent(raw));
+	} catch {
+		return {};
+	}
+	const result = {};
+	const theme = params.get("theme");
+	if (theme && THEME_NAME.test(theme) && (!themes || themes.includes(theme))) result.theme = theme;
+	const mode = params.get("mode");
+	if (includes(COLOR_MODES, mode)) result.mode = mode;
+	const contrast = params.get("contrast");
+	if (includes(CONTRAST_LEVEL_NAMES, contrast)) result.contrast = contrast;
+	const motion = params.get("motion");
+	if (includes(MOTION_SCHEMES, motion)) result.motion = motion;
+	const density = params.get("density");
+	if (density !== null && isDensity(density)) result.density = Number(density);
+	return result;
+}
+/** The `data-*` attributes for a theme state, for `<html>` or any themed element. */
+function themeAttributes(state) {
+	return {
+		"data-theme": state.theme,
+		"data-mode": state.mode,
+		"data-contrast": state.contrast,
+		"data-motion": state.motion,
+		"data-density": `${state.density}`
+	};
+}
+/**
+* The `data-*` attributes an element needs to carry `state` inside an ancestor that already
+* carries `inherited` (2026-10-24): only the dimensions that differ, so the theme's rules don't
+* declare the same values again there and an app's own values for the system tokens (an
+* `:root` rule) still reach it. The colour dimensions go together, since one rule reads the
+* theme, mode and contrast of the same element. With no known `inherited` (a portal into an
+* app's own container, a provider that leaves `<html>` alone), every attribute. `restyled`
+* (an element with an app's own class or CSS variables, which may set a colour role) keeps the
+* colour dimensions too, so the values the theme derives from the roles on `[data-theme]` (the
+* elevation shadows, component tokens an app declares there) resolve again with its own.
+*/
+function themeAttributesOver(state, inherited, restyled = false) {
+	const all = themeAttributes(state);
+	if (!inherited) return all;
+	return {
+		...(restyled || state.theme !== inherited.theme || state.mode !== inherited.mode || state.contrast !== inherited.contrast) && {
+			"data-theme": all["data-theme"],
+			"data-mode": all["data-mode"],
+			"data-contrast": all["data-contrast"]
+		},
+		...state.motion !== inherited.motion && { "data-motion": all["data-motion"] },
+		...state.density !== inherited.density && { "data-density": all["data-density"] }
+	};
+}
+function readCookie(cookieString, name) {
+	for (const part of cookieString.split(";")) {
+		const [key, ...value] = part.trim().split("=");
+		if (key === name) return value.join("=");
+	}
+}
+//#endregion
+export { DEFAULT_STORAGE_KEY, DEFAULT_THEME_STATE, parseThemeState, readCookie, serializeThemeState, themeAttributes, themeAttributesOver };
+
+//# sourceMappingURL=state.js.map

package/dist/theme/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","names":[],"sources":["../../src/theme/state.ts"],"sourcesContent":["import {\n  COLOR_MODES,\n  CONTRAST_LEVEL_NAMES,\n  DEFAULT_THEME,\n  type ColorMode,\n  type ContrastLevel,\n} from '../tokens/color';\nimport { DEFAULT_DENSITY, isDensity, type Density } from '../tokens/density';\nimport { DEFAULT_MOTION_SCHEME, MOTION_SCHEMES, type MotionScheme } from '../tokens/motion';\n\n/** The theme dimensions, mirrored as `data-*` attributes. */\nexport interface ThemeState {\n  /** The colour theme's name: a built-in (`baseline`, `ocean` …) or one made with `createTheme`. */\n  theme: string;\n  /** `light`, `dark` or `system` (follows `prefers-color-scheme`). */\n  mode: ColorMode;\n  /** `standard`, `medium` or `high`. */\n  contrast: ContrastLevel;\n  /** `expressive` (springs that overshoot) or `standard` (no visible overshoot). */\n  motion: MotionScheme;\n  /** Web density, `0` (default) to `-3` (densest); see `Density`. */\n  density: Density;\n}\n\nexport const DEFAULT_THEME_STATE: ThemeState = {\n  theme: DEFAULT_THEME,\n  mode: 'system',\n  contrast: 'standard',\n  motion: DEFAULT_MOTION_SCHEME,\n  density: DEFAULT_DENSITY,\n};\n\n/** Where the selected theme is remembered between visits. */\nexport type ThemeStorage = 'cookie' | 'local-storage' | 'none';\n\nexport const DEFAULT_STORAGE_KEY = 'windmorph-theme';\n\nconst THEME_NAME = /^[a-z][a-z0-9-]*$/;\n\nconst includes = <T extends string>(list: readonly T[], value: unknown): value is T =>\n  typeof value === 'string' && (list as readonly string[]).includes(value);\n\n/** Serialises a theme state for a cookie or localStorage value. */\nexport function serializeThemeState(state: ThemeState): string {\n  return encodeURIComponent(\n    new URLSearchParams({\n      theme: state.theme,\n      mode: state.mode,\n      contrast: state.contrast,\n      motion: state.motion,\n      density: String(state.density),\n    }).toString(),\n  );\n}\n\n/**\n * Parses a stored theme state. Unknown or invalid values are dropped, so the\n * result only contains fields that can be trusted.\n */\nexport function parseThemeState(\n  raw: string | null | undefined,\n  themes?: readonly string[],\n): Partial<ThemeState> {\n  if (!raw) return {};\n  let params: URLSearchParams;\n  try {\n    params = new URLSearchParams(decodeURIComponent(raw));\n  } catch {\n    return {};\n  }\n  const result: Partial<ThemeState> = {};\n  const theme = params.get('theme');\n  if (theme && THEME_NAME.test(theme) && (!themes || themes.includes(theme))) result.theme = theme;\n  const mode = params.get('mode');\n  if (includes(COLOR_MODES, mode)) result.mode = mode;\n  const contrast = params.get('contrast');\n  if (includes(CONTRAST_LEVEL_NAMES, contrast)) result.contrast = contrast;\n  const motion = params.get('motion');\n  if (includes(MOTION_SCHEMES, motion)) result.motion = motion;\n  const density = params.get('density');\n  if (density !== null && isDensity(density)) result.density = Number(density) as Density;\n  return result;\n}\n\n/** The `data-*` attributes for a theme state, for `<html>` or any themed element. */\nexport function themeAttributes(state: ThemeState) {\n  return {\n    'data-theme': state.theme,\n    'data-mode': state.mode,\n    'data-contrast': state.contrast,\n    'data-motion': state.motion,\n    'data-density': `${state.density}`,\n  } as const;\n}\n\n/**\n * The `data-*` attributes an element needs to carry `state` inside an ancestor that already\n * carries `inherited` (2026-10-24): only the dimensions that differ, so the theme's rules don't\n * declare the same values again there and an app's own values for the system tokens (an\n * `:root` rule) still reach it. The colour dimensions go together, since one rule reads the\n * theme, mode and contrast of the same element. With no known `inherited` (a portal into an\n * app's own container, a provider that leaves `<html>` alone), every attribute. `restyled`\n * (an element with an app's own class or CSS variables, which may set a colour role) keeps the\n * colour dimensions too, so the values the theme derives from the roles on `[data-theme]` (the\n * elevation shadows, component tokens an app declares there) resolve again with its own.\n */\nexport function themeAttributesOver(\n  state: ThemeState,\n  inherited: ThemeState | null,\n  restyled = false,\n): Partial<ReturnType<typeof themeAttributes>> {\n  const all = themeAttributes(state);\n  if (!inherited) return all;\n  const colors =\n    restyled ||\n    state.theme !== inherited.theme ||\n    state.mode !== inherited.mode ||\n    state.contrast !== inherited.contrast;\n  return {\n    ...(colors && {\n      'data-theme': all['data-theme'],\n      'data-mode': all['data-mode'],\n      'data-contrast': all['data-contrast'],\n    }),\n    ...(state.motion !== inherited.motion && { 'data-motion': all['data-motion'] }),\n    ...(state.density !== inherited.density && { 'data-density': all['data-density'] }),\n  };\n}\n\nexport function readCookie(cookieString: string, name: string): string | undefined {\n  for (const part of cookieString.split(';')) {\n    const [key, ...value] = part.trim().split('=');\n    if (key === name) return value.join('=');\n  }\n  return undefined;\n}\n"],"mappings":";;;;AAwBA,MAAa,sBAAkC;CAC7C,OAAO;CACP,MAAM;CACN,UAAU;CACV,QAAQ;CACR,SAAA;AACF;AAKA,MAAa,sBAAsB;AAEnC,MAAM,aAAa;AAEnB,MAAM,YAA8B,MAAoB,UACtD,OAAO,UAAU,YAAa,KAA2B,SAAS,KAAK;;AAGzE,SAAgB,oBAAoB,OAA2B;CAC7D,OAAO,mBACL,IAAI,gBAAgB;EAClB,OAAO,MAAM;EACb,MAAM,MAAM;EACZ,UAAU,MAAM;EAChB,QAAQ,MAAM;EACd,SAAS,OAAO,MAAM,OAAO;CAC/B,CAAC,CAAC,CAAC,SAAS,CACd;AACF;;;;;AAMA,SAAgB,gBACd,KACA,QACqB;CACrB,IAAI,CAAC,KAAK,OAAO,CAAC;CAClB,IAAI;CACJ,IAAI;EACF,SAAS,IAAI,gBAAgB,mBAAmB,GAAG,CAAC;CACtD,QAAQ;EACN,OAAO,CAAC;CACV;CACA,MAAM,SAA8B,CAAC;CACrC,MAAM,QAAQ,OAAO,IAAI,OAAO;CAChC,IAAI,SAAS,WAAW,KAAK,KAAK,MAAM,CAAC,UAAU,OAAO,SAAS,KAAK,IAAI,OAAO,QAAQ;CAC3F,MAAM,OAAO,OAAO,IAAI,MAAM;CAC9B,IAAI,SAAS,aAAa,IAAI,GAAG,OAAO,OAAO;CAC/C,MAAM,WAAW,OAAO,IAAI,UAAU;CACtC,IAAI,SAAS,sBAAsB,QAAQ,GAAG,OAAO,WAAW;CAChE,MAAM,SAAS,OAAO,IAAI,QAAQ;CAClC,IAAI,SAAS,gBAAgB,MAAM,GAAG,OAAO,SAAS;CACtD,MAAM,UAAU,OAAO,IAAI,SAAS;CACpC,IAAI,YAAY,QAAQ,UAAU,OAAO,GAAG,OAAO,UAAU,OAAO,OAAO;CAC3E,OAAO;AACT;;AAGA,SAAgB,gBAAgB,OAAmB;CACjD,OAAO;EACL,cAAc,MAAM;EACpB,aAAa,MAAM;EACnB,iBAAiB,MAAM;EACvB,eAAe,MAAM;EACrB,gBAAgB,GAAG,MAAM;CAC3B;AACF;;;;;;;;;;;;AAaA,SAAgB,oBACd,OACA,WACA,WAAW,OACkC;CAC7C,MAAM,MAAM,gBAAgB,KAAK;CACjC,IAAI,CAAC,WAAW,OAAO;CAMvB,OAAO;EACL,IALA,YACA,MAAM,UAAU,UAAU,SAC1B,MAAM,SAAS,UAAU,QACzB,MAAM,aAAa,UAAU,aAEf;GACZ,cAAc,IAAI;GAClB,aAAa,IAAI;GACjB,iBAAiB,IAAI;EACvB;EACA,GAAI,MAAM,WAAW,UAAU,UAAU,EAAE,eAAe,IAAI,eAAe;EAC7E,GAAI,MAAM,YAAY,UAAU,WAAW,EAAE,gBAAgB,IAAI,gBAAgB;CACnF;AACF;AAEA,SAAgB,WAAW,cAAsB,MAAkC;CACjF,KAAK,MAAM,QAAQ,aAAa,MAAM,GAAG,GAAG;EAC1C,MAAM,CAAC,KAAK,GAAG,SAAS,KAAK,KAAK,CAAC,CAAC,MAAM,GAAG;EAC7C,IAAI,QAAQ,MAAM,OAAO,MAAM,KAAK,GAAG;CACzC;AAEF"}

package/dist/theme/storage.js

@@ -0,0 +1,21 @@
+import { readCookie, serializeThemeState } from "./state.js";
+//#region src/theme/storage.ts
+const ONE_YEAR = 31536e3;
+function readStoredTheme(storage, key) {
+	try {
+		if (storage === "cookie") return readCookie(document.cookie, key) ?? null;
+		if (storage === "local-storage") return window.localStorage.getItem(key);
+	} catch {}
+	return null;
+}
+function writeStoredTheme(storage, key, state) {
+	const value = serializeThemeState(state);
+	try {
+		if (storage === "cookie") document.cookie = `${key}=${value}; path=/; max-age=${ONE_YEAR}; samesite=lax`;
+		else if (storage === "local-storage") window.localStorage.setItem(key, value);
+	} catch {}
+}
+//#endregion
+export { readStoredTheme, writeStoredTheme };
+
+//# sourceMappingURL=storage.js.map

package/dist/theme/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","names":[],"sources":["../../src/theme/storage.ts"],"sourcesContent":["import { readCookie, serializeThemeState, type ThemeState, type ThemeStorage } from './state';\n\nconst ONE_YEAR = 60 * 60 * 24 * 365;\n\nexport function readStoredTheme(storage: ThemeStorage, key: string): string | null {\n  try {\n    if (storage === 'cookie') return readCookie(document.cookie, key) ?? null;\n    if (storage === 'local-storage') return window.localStorage.getItem(key);\n  } catch {\n    // Storage can be blocked (private mode, sandboxed iframes); fall back to defaults.\n  }\n  return null;\n}\n\nexport function writeStoredTheme(storage: ThemeStorage, key: string, state: ThemeState): void {\n  const value = serializeThemeState(state);\n  try {\n    if (storage === 'cookie') {\n      document.cookie = `${key}=${value}; path=/; max-age=${ONE_YEAR}; samesite=lax`;\n    } else if (storage === 'local-storage') {\n      window.localStorage.setItem(key, value);\n    }\n  } catch {\n    // Persisting is best-effort.\n  }\n}\n"],"mappings":";;AAEA,MAAM,WAAW;AAEjB,SAAgB,gBAAgB,SAAuB,KAA4B;CACjF,IAAI;EACF,IAAI,YAAY,UAAU,OAAO,WAAW,SAAS,QAAQ,GAAG,KAAK;EACrE,IAAI,YAAY,iBAAiB,OAAO,OAAO,aAAa,QAAQ,GAAG;CACzE,QAAQ,CAER;CACA,OAAO;AACT;AAEA,SAAgB,iBAAiB,SAAuB,KAAa,OAAyB;CAC5F,MAAM,QAAQ,oBAAoB,KAAK;CACvC,IAAI;EACF,IAAI,YAAY,UACd,SAAS,SAAS,GAAG,IAAI,GAAG,MAAM,oBAAoB,SAAS;OAC1D,IAAI,YAAY,iBACrB,OAAO,aAAa,QAAQ,KAAK,KAAK;CAE1C,QAAQ,CAER;AACF"}

package/dist/tokens/breakpoints.d.ts

@@ -0,0 +1,15 @@
+//#region src/tokens/breakpoints.d.ts
+/**
+ * M3 window size classes as Tailwind breakpoints (min-widths).
+ * Compact (< 600px) is the mobile-first default and has no prefix.
+ */
+export declare const BREAKPOINTS: {
+  readonly medium: "600px";
+  readonly expanded: "840px";
+  readonly large: "1200px";
+  readonly xlarge: "1600px";
+};
+export type BreakpointName = keyof typeof BREAKPOINTS;
+export declare const BREAKPOINT_NAMES: BreakpointName[];
+//#endregion
+//# sourceMappingURL=breakpoints.d.ts.map

package/dist/tokens/breakpoints.js

@@ -0,0 +1,16 @@
+//#region src/tokens/breakpoints.ts
+/**
+* M3 window size classes as Tailwind breakpoints (min-widths).
+* Compact (< 600px) is the mobile-first default and has no prefix.
+*/
+const BREAKPOINTS = {
+	medium: "600px",
+	expanded: "840px",
+	large: "1200px",
+	xlarge: "1600px"
+};
+const BREAKPOINT_NAMES = Object.keys(BREAKPOINTS);
+//#endregion
+export { BREAKPOINTS, BREAKPOINT_NAMES };
+
+//# sourceMappingURL=breakpoints.js.map

package/dist/tokens/breakpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakpoints.js","names":[],"sources":["../../src/tokens/breakpoints.ts"],"sourcesContent":["/**\n * M3 window size classes as Tailwind breakpoints (min-widths).\n * Compact (< 600px) is the mobile-first default and has no prefix.\n */\nexport const BREAKPOINTS = {\n  medium: '600px',\n  expanded: '840px',\n  large: '1200px',\n  xlarge: '1600px',\n} as const;\n\nexport type BreakpointName = keyof typeof BREAKPOINTS;\nexport const BREAKPOINT_NAMES = Object.keys(BREAKPOINTS) as BreakpointName[];\n"],"mappings":";;;;;AAIA,MAAa,cAAc;CACzB,QAAQ;CACR,UAAU;CACV,OAAO;CACP,QAAQ;AACV;AAGA,MAAa,mBAAmB,OAAO,KAAK,WAAW"}

package/dist/tokens/color.d.ts

@@ -0,0 +1,104 @@
+//#region src/tokens/color.d.ts
+/**
+ * M3 colour roles, built-in themes and contrast levels.
+ *
+ * Role names are the kebab-case form of the `MaterialDynamicColors` methods in
+ * `@material/material-color-utilities`, plus the custom-colour roles (`success`,
+ * `warning`; see {@link CUSTOM_COLOR_ROLES}). They become `--md-sys-color-<role>` CSS
+ * variables and `bg-<role>` / `text-<role>` / … Tailwind utilities.
+ */
+export declare const COLOR_ROLES: readonly ["primary", "on-primary", "primary-container", "on-primary-container", "inverse-primary", "primary-fixed", "primary-fixed-dim", "on-primary-fixed", "on-primary-fixed-variant", "secondary", "on-secondary", "secondary-container", "on-secondary-container", "secondary-fixed", "secondary-fixed-dim", "on-secondary-fixed", "on-secondary-fixed-variant", "tertiary", "on-tertiary", "tertiary-container", "on-tertiary-container", "tertiary-fixed", "tertiary-fixed-dim", "on-tertiary-fixed", "on-tertiary-fixed-variant", "error", "on-error", "error-container", "on-error-container", "background", "on-background", "surface", "surface-dim", "surface-bright", "surface-container-lowest", "surface-container-low", "surface-container", "surface-container-high", "surface-container-highest", "on-surface", "surface-variant", "on-surface-variant", "inverse-surface", "inverse-on-surface", "outline", "outline-variant", "shadow", "scrim", "surface-tint", "success", "on-success", "success-container", "on-success-container", "warning", "on-warning", "warning-container", "on-warning-container"];
+/** An M3 colour role, such as `primary` or `on-surface-variant` (`--md-sys-color-<role>`). */
+export type ColorRole = (typeof COLOR_ROLES)[number];
+/**
+ * Colours M3 has no key colour for, generated the way Material Theme Builder makes "custom
+ * colours": each gets colour, on-colour, container and on-container roles, with the error
+ * roles' tone rules (so the same contrast as error), harmonised toward the theme's seed.
+ */
+export declare const CUSTOM_COLORS: readonly ["success", "warning"];
+export type CustomColorName = (typeof CUSTOM_COLORS)[number];
+/** The four roles of each custom colour. */
+export declare const CUSTOM_COLOR_ROLES: ("primary" | "on-primary" | "primary-container" | "on-primary-container" | "inverse-primary" | "primary-fixed" | "primary-fixed-dim" | "on-primary-fixed" | "on-primary-fixed-variant" | "secondary" | "on-secondary" | "secondary-container" | "on-secondary-container" | "secondary-fixed" | "secondary-fixed-dim" | "on-secondary-fixed" | "on-secondary-fixed-variant" | "tertiary" | "on-tertiary" | "tertiary-container" | "on-tertiary-container" | "tertiary-fixed" | "tertiary-fixed-dim" | "on-tertiary-fixed" | "on-tertiary-fixed-variant" | "error" | "on-error" | "error-container" | "on-error-container" | "background" | "on-background" | "surface" | "surface-dim" | "surface-bright" | "surface-container-lowest" | "surface-container-low" | "surface-container" | "surface-container-high" | "surface-container-highest" | "on-surface" | "surface-variant" | "on-surface-variant" | "inverse-surface" | "inverse-on-surface" | "outline" | "outline-variant" | "shadow" | "scrim" | "surface-tint" | "success" | "on-success" | "success-container" | "on-success-container" | "warning" | "on-warning" | "warning-container" | "on-warning-container")[];
+/** The default custom colours; only their hue and chroma matter, not their lightness. */
+export declare const DEFAULT_CUSTOM_COLORS: Readonly<Record<CustomColorName, `#${string}`>>;
+/** Scheme variants supported by the 2025 colour spec. */
+export declare const SCHEME_VARIANTS: readonly ["tonal-spot", "neutral", "vibrant", "expressive"];
+export type SchemeVariant = (typeof SCHEME_VARIANTS)[number];
+/**
+ * The six tonal palettes an M3 scheme is built from: the "core colours" of Material Theme
+ * Builder. Every colour role takes its tone from one of them.
+ */
+export declare const PALETTE_NAMES: readonly ["primary", "secondary", "tertiary", "error", "neutral", "neutralVariant"];
+export type PaletteName = (typeof PALETTE_NAMES)[number];
+/**
+ * Where a palette comes from: a scheme variant (that palette from that variant of the same
+ * seed) or a hex colour (a palette built from its hue and chroma, as Material Theme Builder
+ * does for a core colour).
+ */
+export type PaletteSource = SchemeVariant | `#${string}`;
+/** Per-palette sources; any palette left out comes from the theme's own `variant`. */
+export type ThemePalettes = Partial<Record<PaletteName, PaletteSource>>;
+export interface ThemeSeed {
+  seed: string;
+  variant: SchemeVariant;
+  /**
+   * Takes some palettes from elsewhere, e.g. `{ neutral: 'tonal-spot', neutralVariant:
+   * 'tonal-spot' }` for vivid accents on calm surfaces, or `{ tertiary: '#00A07A' }` for a
+   * brand's own tertiary colour. Roles still take their tones from the M3 spec, so contrast
+   * is unchanged.
+   */
+  palettes?: ThemePalettes;
+  /** The success and warning colours; each defaults to {@link DEFAULT_CUSTOM_COLORS}. */
+  customColors?: Partial<Record<CustomColorName, `#${string}`>>;
+  /**
+   * Turns each custom colour's hue up to 15° toward the seed, as Material Theme Builder
+   * does, so it belongs to the theme. `false` keeps a brand's exact status colours.
+   * @default true
+   */
+  harmonize?: boolean;
+}
+/** The six built-in themes: each one's seed colour and scheme variant. */
+export declare const BUILT_IN_THEMES: {
+  readonly baseline: {
+    readonly seed: "#6750A4";
+    readonly variant: "tonal-spot";
+  };
+  readonly ocean: {
+    readonly seed: "#0061A4";
+    readonly variant: "tonal-spot";
+  };
+  readonly forest: {
+    readonly seed: "#386A20";
+    readonly variant: "tonal-spot";
+  };
+  readonly sunset: {
+    readonly seed: "#A04100";
+    readonly variant: "tonal-spot";
+  };
+  readonly rose: {
+    readonly seed: "#9C4146";
+    readonly variant: "tonal-spot";
+  };
+  readonly slate: {
+    readonly seed: "#545F71";
+    readonly variant: "neutral";
+  };
+};
+export type BuiltInThemeName = keyof typeof BUILT_IN_THEMES;
+/** The built-in themes' names, in order: `baseline`, `ocean`, `forest`, `sunset`, `rose`, `slate`. */
+export declare const BUILT_IN_THEME_NAMES: BuiltInThemeName[];
+export declare const DEFAULT_THEME: BuiltInThemeName;
+export declare const COLOR_MODES: readonly ["light", "dark", "system"];
+export type ColorMode = (typeof COLOR_MODES)[number];
+export type ResolvedColorMode = Exclude<ColorMode, 'system'>;
+/** Contrast levels and the `contrastLevel` passed to the colour library. */
+export declare const CONTRAST_LEVELS: {
+  readonly standard: 0;
+  readonly medium: 0.5;
+  readonly high: 1;
+};
+export type ContrastLevel = keyof typeof CONTRAST_LEVELS;
+/** The contrast levels' names: `standard`, `medium` and `high`. */
+export declare const CONTRAST_LEVEL_NAMES: ContrastLevel[];
+//#endregion
+//# sourceMappingURL=color.d.ts.map