@animus-ui/system 0.1.1 → 0.1.2

package/README.md

@@ -136,12 +136,133 @@ ds.styles()    → @layer base
 
 The type system prevents calling methods out of order. `.variant()` after `.states()` is a type error.
 
+## Color Modes
+
+`addColorModes(initialMode, modeConfig)` emits a `[data-color-mode="…"]` block
+per mode. An optional third argument opts the theme into OS participation:
+
+```tsx
+const tokens = createTheme()
+  .addColors({ gray: { 100: '#f0f0f0', 800: '#1a1a1a' } })
+  .addColorModes(
+    'dark',
+    {
+      dark: { bg: 'gray.800', text: 'gray.100' },
+      light: { bg: 'gray.100', text: 'gray.800' },
+    },
+    {
+      // OS preference → declared mode name.
+      systemPreference: { light: 'light', dark: 'dark' },
+      // CSS `color-scheme` per mode. The two mapped modes default to
+      // 'light'/'dark' (the mapping forces them), so `{}` is the whole
+      // opt-in here; classify any ADDITIONAL modes explicitly.
+      browserColorScheme: {},
+    }
+  )
+  .build();
+```
+
+**`systemPreference`** enables guarded fallback emission:
+
+```css
+@media (prefers-color-scheme: dark) {
+  :root:not([data-color-mode]) {
+    /* the dark mode's declarations */
+  }
+}
+```
+
+The `:not([data-color-mode])` guard is what makes an explicit attribute win — in
+CSS alone, with no script. Both values must name declared modes.
+
+**`browserColorScheme`** adds the CSS `color-scheme` property so native
+scrollbars, form controls, and UA styling track the active mode. When supplied it
+must classify _every_ declared mode, otherwise a mode would silently inherit the
+previous one's native scheme — with one carve-out: the two modes named by
+`systemPreference` are forced to `light`/`dark` by validation anyway, so they
+default and may be omitted. An explicit entry on a mapped mode is honored and
+still conflict-checked.
+
+A theme that opts into neither emits exactly the bytes it emitted before.
+
+### "System" is the absence of the attribute
+
+There is no `data-color-mode="system"` — the OS-following state is the attribute
+being **absent**, which is the only value the media guard above can fall through.
+`system` is a reserved mode name and is rejected.
+
+### The appearance record
+
+Persisted appearance lives under one versioned key, `animus:appearance`:
+
+```
+{ "v": 1, "mode": "system" | "<mode name>", "theme": "default" }
+```
+
+The `theme` axis is reserved and currently ignored — a writer that owns only the
+mode axis must preserve the fields it does not own. The package ships that
+write discipline so you don't hand-roll it: `@animus-ui/system/appearance` is a
+tiny, storage-only runtime subpath (no React, no listeners, no DOM — applying
+`data-color-mode` stays yours):
+
+```ts
+import {
+  SYSTEM_MODE,
+  migrateLegacyModeKey,
+  persistColorMode,
+} from '@animus-ui/system/appearance';
+
+persistColorMode('midnight'); // read-modify-write; unowned fields survive
+persistColorMode(SYSTEM_MODE); // "follow the OS" — bootstrap restores absence
+
+// One-shot: move YOUR app's old key into the record, then delete it.
+migrateLegacyModeKey('my-app-color-mode', ['midnight', 'paper']);
+```
+
+It refuses to downgrade a record written by a newer version, and refuses to
+migrate the shared `color-mode` key (that one may belong to another app on your
+origin; the bootstrap already reads it, read-only).
+
+To restore it before first paint, generate an inline snippet from the **built**
+theme:
+
+```ts
+import { createAppearanceBootstrap } from '@animus-ui/system/bootstrap';
+
+const { code, cspHash } = createAppearanceBootstrap(tokens, {
+  storageKey: 'animus:appearance', // default
+});
+```
+
+`code` is a dependency-free IIFE for the document head: it reads the record,
+validates `mode` against the theme's declared names, sets `data-color-mode` for a
+valid explicit mode, and **removes** the attribute for `"system"`, a missing
+record, or an unrecognized value — handing control back to the media query. It
+never writes storage and never calls `matchMedia` (materializing the OS answer
+into the attribute would freeze it against later OS changes). The pre-record
+plain-string `color-mode` key is read once, only when the record is absent, and
+is never written.
+
+`cspHash` authorizes that exact script. Derive the header from the artifact at
+build time and **single-quote** the value — `script-src 'sha256-…'`. Unquoted it
+parses as a host source and silently blocks the script; hand-copied, it goes
+stale the moment a mode is renamed.
+
+This subpath is build tooling. It is never imported by the component or runtime
+entries, so it cannot reach an extracted application bundle — generate the
+artifact in your bundler config and hand it to the plugin
+([`@animus-ui/vite-plugin`](https://github.com/codecaaron/animus/tree/main/packages/vite-plugin)
+accepts `appearanceBootstrap`; in Next.js the application places `code` itself,
+so it can control CSP nonce and ordering).
+
 ## Exports
 
-| Path                       | What's in it                                                                                                                                     |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `@animus-ui/system`        | Full API — builder, theme, runtime, types                                                                                                        |
-| `@animus-ui/system/groups` | Pre-built prop groups: `space`, `color`, `typography`, `layout`, `flex`, `grid`, `border`, `shadows`, `background`, `positioning`, `transitions` |
+| Path                           | What's in it                                                                                                                                     |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@animus-ui/system`            | Full API — builder, theme, runtime, types                                                                                                        |
+| `@animus-ui/system/groups`     | Pre-built prop groups: `space`, `color`, `typography`, `layout`, `flex`, `grid`, `border`, `shadows`, `background`, `positioning`, `transitions` |
+| `@animus-ui/system/bootstrap`  | `createAppearanceBootstrap` — build-time only, never imported by application code                                                                |
+| `@animus-ui/system/appearance` | `persistColorMode`, `migrateLegacyModeKey`, `SYSTEM_MODE` — storage-only appearance record write path (runtime, client-safe)                     |
 
 ## License
 

package/dist/Animus.d.ts

@@ -1,3 +1,4 @@
+import type { ComponentType } from 'react';
 import { AnimusExtended } from './AnimusExtended';
 import { AbstractParser, CompoundEntry, CSSPropMap, CSSProps, CustomPropConfig, Prop, SystemProps, ThemedCSSPropMap, ThemedCSSProps, VariantConfig } from './types/config';
 import { AbstractProps } from './types/props';
@@ -14,9 +15,7 @@ export declare class AnimusWithAll<PropRegistry extends Record<string, Prop>, Gr
     constructor(props: PropRegistry, groups: GroupRegistry, base: BaseStyles, variants: Variants, states: States, activeGroups: ActiveGroups, custom: CustomProps, compounds?: CompoundEntry[]);
     extend(): AnimusExtended<PropRegistry, GroupRegistry, BaseStyles, Variants, States, ActiveGroups, CustomProps>;
     asElement<El extends keyof JSX.IntrinsicElements>(component: El): AnimusComponent<El, PropRegistry, GroupRegistry, BaseStyles, Variants, States, ActiveGroups, CustomProps>;
-    asComponent<C extends (props: {
-        className?: string;
-    }) => any>(AsComponent: C): AnimusWrappedComponent<PropRegistry, GroupRegistry, BaseStyles, Variants, States, ActiveGroups, CustomProps>;
+    asComponent<C extends ComponentType<any>>(AsComponent: C): AnimusWrappedComponent<C, PropRegistry, GroupRegistry, BaseStyles, Variants, States, ActiveGroups, CustomProps>;
     asClass(): (props?: Record<string, unknown>) => string;
     _buildComponentConfig(): {
         variants: Record<string, {

package/dist/Animus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Animus.d.ts","sourceRoot":"","sources":["../src/Animus.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Animus.d.ts","sourceRoot":"","sources":["../src/Animus.ts"],"names":[],"mappings":"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"}

package/dist/AnimusExtended.d.ts

@@ -1,3 +1,4 @@
+import type { ComponentType } from 'react';
 import { AbstractParser, CompoundEntry, CSSPropMap, CSSProps, CustomPropConfig, Prop, SystemProps, ThemedCSSPropMap, ThemedCSSProps, VariantConfig } from './types/config';
 import { AbstractProps } from './types/props';
 import type { AnimusComponent, AnimusWrappedComponent } from './types/component';
@@ -13,9 +14,7 @@ export declare class AnimusExtendedWithAll<PropRegistry extends Record<string, P
     constructor(props: PropRegistry, groups: GroupRegistry, base: BaseStyles, variants: Variants, states: States, activeGroups: ActiveGroups, custom: CustomProps, compounds?: CompoundEntry[]);
     extend(): AnimusExtended<PropRegistry, GroupRegistry, BaseStyles, Variants, States, ActiveGroups, CustomProps>;
     asElement<El extends keyof JSX.IntrinsicElements>(component: El): AnimusComponent<El, PropRegistry, GroupRegistry, BaseStyles, Variants, States, ActiveGroups, CustomProps>;
-    asComponent<C extends (props: {
-        className?: string;
-    }) => any>(AsComponent: C): AnimusWrappedComponent<PropRegistry, GroupRegistry, BaseStyles, Variants, States, ActiveGroups, CustomProps>;
+    asComponent<C extends ComponentType<any>>(AsComponent: C): AnimusWrappedComponent<C, PropRegistry, GroupRegistry, BaseStyles, Variants, States, ActiveGroups, CustomProps>;
     asClass(): (props?: Record<string, unknown>) => string;
     _buildComponentConfig(): {
         variants: Record<string, {

package/dist/AnimusExtended.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimusExtended.d.ts","sourceRoot":"","sources":["../src/AnimusExtended.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AnimusExtended.d.ts","sourceRoot":"","sources":["../src/AnimusExtended.ts"],"names":[],"mappings":"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"}

package/dist/SystemBuilder.d.ts

@@ -1,4 +1,5 @@
 import { Animus } from './Animus';
+import { type ConditionAliasMap, type RegistryBrand } from './conditions';
 import { type KeyframeFrameMap, type Keyframes } from './keyframes';
 import { type SelectorAliasMap } from './selectors';
 import { NamedTransform } from './transforms/createTransform';
@@ -25,26 +26,44 @@ type IncludableSystem = {
 export interface CreateSystemConfig {
     includes?: readonly IncludableSystem[];
 }
-export declare class SystemBuilder<PropReg extends Record<string, Prop> = {}, GroupReg extends Record<string, (keyof PropReg)[]> = {}> {
+export declare class SystemBuilder<PropReg extends Record<string, Prop> = {}, GroupReg extends Record<string, (keyof PropReg)[]> = {}, Conds extends string = never, Sels extends string = never> {
     #private;
-    constructor(propRegistry?: PropReg, groupRegistry?: GroupReg, selectorRegistry?: SelectorAliasMap, includesRegistry?: readonly IncludableSystem[]);
-    addSelectors(selectors: Record<string, string>): SystemBuilder<PropReg, GroupReg>;
-    addGroup<Name extends string, Conf extends Record<string, Prop>>(name: Name extends keyof PropReg ? never : Name, config: Conf): SystemBuilder<PropReg & Conf, GroupReg & Record<Name, (keyof Conf)[]>>;
-    addProps<Conf extends Record<string, Prop> & Partial<Record<Extract<keyof GroupReg, string>, never>>>(config: Conf): SystemBuilder<PropReg & Conf, GroupReg>;
+    constructor(propRegistry?: PropReg, groupRegistry?: GroupReg, selectorRegistry?: SelectorAliasMap, includesRegistry?: readonly IncludableSystem[], conditionRegistry?: ConditionAliasMap);
+    addSelectors<S extends Record<`_${string}`, string>>(selectors: S): SystemBuilder<PropReg, GroupReg, Conds, Sels | Extract<keyof S, string>>;
+    /**
+     * Register condition aliases (`_motionReduce`, `_cardSm`, …) → at-rule
+     * condition strings (`@media …` / `@container …` / `@supports …`).
+     * Recognized as block keys in style objects; user aliases override built-ins
+     * of the same name (design D3). Keys are constrained to `_`-prefixed aliases
+     * and values to `@`-prefixed at-rule strings — a value that does not begin
+     * with an at-rule name is a compile-time type error (design D9; the runtime
+     * `inferConditionKind` throw is defense-in-depth). The registered keys are
+     * accumulated into the phantom `Conds` union and surfaced on `build()`.
+     */
+    addConditions<C extends Record<`_${string}`, `@media${string}` | `@container${string}` | `@supports${string}`>>(conditions: C): SystemBuilder<PropReg, GroupReg, Conds | Extract<keyof C, string>, Sels>;
+    addGroup<Name extends string, Conf extends Record<string, Prop>>(name: Name extends keyof PropReg ? never : Name, config: Conf): SystemBuilder<PropReg & Conf, GroupReg & Record<Name, (keyof Conf)[]>, Conds, Sels>;
+    addProps<Conf extends Record<string, Prop> & Partial<Record<Extract<keyof GroupReg, string>, never>>>(config: Conf): SystemBuilder<PropReg & Conf, GroupReg, Conds, Sels>;
     build(): {
-        system: SystemInstance<PropReg, GroupReg>;
+        system: SystemInstance<PropReg, GroupReg, Conds, Sels>;
         createGlobalStyles: GlobalStylesFactory<PropReg>;
         createKeyframes: CreateKeyframesFactory<PropReg>;
     };
 }
-export type SystemInstance<PropReg extends Record<string, Prop>, GroupReg extends Record<string, (keyof PropReg)[]>> = Animus<PropReg, GroupReg> & {
+export type SystemInstance<PropReg extends Record<string, Prop>, GroupReg extends Record<string, (keyof PropReg)[]>, Conds extends string = never, Sels extends string = never> = Animus<PropReg, GroupReg> & {
     toConfig(): SerializedConfig;
-};
+} & RegistryBrand<Conds, Sels>;
 export interface SerializedConfig {
     propConfig: string;
     groupRegistry: string;
     transforms: Record<string, NamedTransform>;
     selectorAliases: string;
+    /**
+     * Condition alias map JSON (inc 03 — NEW field): `alias → { value, order,
+     * kind }`. `"{}"` when the system registers no conditions (built-ins are
+     * empty this increment). Distinct from `selectorAliases`, which stays
+     * byte-for-byte unchanged.
+     */
+    conditionAliases: string;
 }
 export declare function createSystem(config?: CreateSystemConfig): SystemBuilder;
 export {};

package/dist/SystemBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SystemBuilder.d.ts","sourceRoot":"","sources":["../src/SystemBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SystemBuilder.d.ts","sourceRoot":"","sources":["../src/SystemBuilder.ts"],"names":[],"mappings":"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"}

package/dist/appearance/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Appearance record write path — the CLIENT half of the contract the generated
+ * bootstrap reads (openspec: color-mode-bootstrap, "Appearance record
+ * contract").
+ *
+ * This module is runtime application code: it ships in client bundles and owns
+ * only the record WRITE path. It deliberately imports nothing from
+ * `@animus-ui/system/bootstrap` — that subpath is build tooling, reaches
+ * `node:crypto`, and must never enter an application bundle — so the two
+ * modules re-state the key and shape they agree on, and the round-trip tests
+ * pin the agreement (a record written here is restored by the generated
+ * snippet).
+ *
+ * Record: `animus:appearance` → `{"v":1,"mode":…,"theme":…}`.
+ *
+ * Two axes share one record. A writer that changes ONE axis reads, modifies
+ * and writes back, so fields it does not own (`theme`, plus anything a future
+ * version adds) survive untouched.
+ */
+/**
+ * Mode value meaning "follow the OS". It is never a declared mode and never
+ * reaches `data-color-mode` — the OS is followed by the attribute's ABSENCE,
+ * which the generated bootstrap restores when it reads this value.
+ */
+export declare const SYSTEM_MODE = "system";
+export interface AppearanceStorageOptions {
+    /**
+     * Overrides the record key. MUST match the `storageKey` the bootstrap
+     * artifact was generated with, or the snippet restores from a key this
+     * module never writes. Defaults to `animus:appearance`.
+     */
+    storageKey?: string;
+}
+/**
+ * Persists the mode axis, preserving every field this call does not own
+ * (`v`, `theme`, and any additional keys already in the record).
+ *
+ * Pass {@link SYSTEM_MODE} to persist "follow the OS" — the generated
+ * bootstrap restores it as attribute absence. Applying the mode to the
+ * document (setting or removing `data-color-mode`) stays the caller's job:
+ * this module is storage-only and never touches the DOM.
+ *
+ * REFUSAL RULE: when the stored record carries a version this code does not
+ * understand, NOTHING is written. Downgrading it to a v1 shape would drop
+ * whatever fields the newer writer keeps there, and this axis is not worth
+ * that. A caller that has already updated the attribute keeps the user's
+ * choice for the session — only its persistence is skipped.
+ *
+ * Storage failures are likewise swallowed: persistence is a convenience, and
+ * the attribute write that accompanies it has already taken effect.
+ */
+export declare function persistColorMode(mode: string, options?: AppearanceStorageOptions): void;
+/**
+ * One-shot migration of an application's OWN historical mode key into the
+ * record.
+ *
+ * The generated bootstrap only knows the record and the contract's `color-mode`
+ * key — an app that persisted under its own key before adopting the record
+ * would silently drop every returning visitor's mode without this. Run it
+ * post-paint from the app entry: the visit on which it migrates still paints
+ * in the OS-resolved mode before correcting itself — one accepted flash, once
+ * — and every later load restores pre-paint through the bootstrap.
+ *
+ * It writes only when there is nothing to lose (no record) and something worth
+ * keeping (a value in `declaredModes`), then DELETES the old key so the
+ * migration cannot run twice or resurrect a stale value. Deleting is
+ * legitimate precisely because the key is the application's own; the
+ * contract's `color-mode` key may belong to another app on this origin and is
+ * refused, as is the record key itself.
+ *
+ * @returns the migrated mode name, so the caller can apply it to the document
+ *   for this one visit, or `null` when nothing was migrated.
+ */
+export declare function migrateLegacyModeKey(legacyKey: string, declaredModes: readonly string[], options?: AppearanceStorageOptions): string | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/appearance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/appearance/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAgBH;;;;GAIG;AACH,eAAO,MAAM,WAAW,WAAW,CAAC;AASpC,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAkFD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,wBAAwB,GACjC,IAAI,CAWN;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,OAAO,CAAC,EAAE,wBAAwB,GACjC,MAAM,GAAG,IAAI,CAmDf"}

package/dist/appearance/index.js

@@ -0,0 +1,179 @@
+//#region src/appearance/index.ts
+/**
+* Appearance record write path — the CLIENT half of the contract the generated
+* bootstrap reads (openspec: color-mode-bootstrap, "Appearance record
+* contract").
+*
+* This module is runtime application code: it ships in client bundles and owns
+* only the record WRITE path. It deliberately imports nothing from
+* `@animus-ui/system/bootstrap` — that subpath is build tooling, reaches
+* `node:crypto`, and must never enter an application bundle — so the two
+* modules re-state the key and shape they agree on, and the round-trip tests
+* pin the agreement (a record written here is restored by the generated
+* snippet).
+*
+* Record: `animus:appearance` → `{"v":1,"mode":…,"theme":…}`.
+*
+* Two axes share one record. A writer that changes ONE axis reads, modifies
+* and writes back, so fields it does not own (`theme`, plus anything a future
+* version adds) survive untouched.
+*/
+/** The single versioned appearance record key. */
+const DEFAULT_STORAGE_KEY = "animus:appearance";
+/**
+* The CONTRACT's pre-record key. The generated bootstrap reads it once, only
+* when the record is absent, and never writes it — it may belong to another
+* app on this origin, so this module refuses to migrate (and therefore
+* delete) it. See {@link migrateLegacyModeKey}.
+*/
+const CONTRACT_LEGACY_KEY = "color-mode";
+/** The only appearance-record version this module writes or read-modify-writes. */
+const RECORD_VERSION = 1;
+/**
+* Mode value meaning "follow the OS". It is never a declared mode and never
+* reaches `data-color-mode` — the OS is followed by the attribute's ABSENCE,
+* which the generated bootstrap restores when it reads this value.
+*/
+const SYSTEM_MODE = "system";
+/** Applied when nothing is stored: OS-driven mode, default theme. */
+const DEFAULT_RECORD = {
+	v: RECORD_VERSION,
+	mode: SYSTEM_MODE,
+	theme: "default"
+};
+function storageOf() {
+	return globalThis.localStorage;
+}
+function keyOf(options) {
+	const key = options?.storageKey ?? DEFAULT_STORAGE_KEY;
+	if (typeof key !== "string" || key === "") throw new Error("appearance: storageKey must be a non-empty string.");
+	return key;
+}
+/**
+* Reads the stored record.
+*
+* READ FAILURE vs. ABSENT: a `getItem` that THROWS (blocked or partitioned
+* storage) — or no storage object at all — is reported as `absent`, not
+* `foreign`, deliberately. "Absent" here means "this code has no knowledge of
+* a stored record", and a store we cannot read at all is indistinguishable
+* from an empty one. The asymmetry is safe because the accompanying write is
+* wrapped in its own try/catch: a store that throws on read throws on write
+* too, so the `absent` classification can never actually clobber anything.
+* Only a store we CAN read and whose content we cannot interpret yields
+* `foreign`.
+*
+* A present-but-corrupt value (not JSON, not an object) is `absent`: it is
+* nobody's live state, so replacing it with a clean record is a repair. A
+* present record carrying an unrecognized `v` is `foreign`: that is a future
+* writer's data, and v1-shaped fields written over it would destroy fields
+* this version does not know exist.
+*/
+function readRecord(storageKey) {
+	let raw = null;
+	try {
+		raw = storageOf()?.getItem(storageKey) ?? null;
+	} catch {
+		return { kind: "absent" };
+	}
+	if (typeof raw !== "string" || raw === "") return { kind: "absent" };
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return { kind: "absent" };
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { kind: "absent" };
+	const record = parsed;
+	if (record.v !== RECORD_VERSION) return { kind: "foreign" };
+	return {
+		kind: "record",
+		record
+	};
+}
+/**
+* Persists the mode axis, preserving every field this call does not own
+* (`v`, `theme`, and any additional keys already in the record).
+*
+* Pass {@link SYSTEM_MODE} to persist "follow the OS" — the generated
+* bootstrap restores it as attribute absence. Applying the mode to the
+* document (setting or removing `data-color-mode`) stays the caller's job:
+* this module is storage-only and never touches the DOM.
+*
+* REFUSAL RULE: when the stored record carries a version this code does not
+* understand, NOTHING is written. Downgrading it to a v1 shape would drop
+* whatever fields the newer writer keeps there, and this axis is not worth
+* that. A caller that has already updated the attribute keeps the user's
+* choice for the session — only its persistence is skipped.
+*
+* Storage failures are likewise swallowed: persistence is a convenience, and
+* the attribute write that accompanies it has already taken effect.
+*/
+function persistColorMode(mode, options) {
+	const storageKey = keyOf(options);
+	const outcome = readRecord(storageKey);
+	if (outcome.kind === "foreign") return;
+	const base = outcome.kind === "record" ? outcome.record : DEFAULT_RECORD;
+	try {
+		storageOf()?.setItem(storageKey, JSON.stringify({
+			...base,
+			mode
+		}));
+	} catch {}
+}
+/**
+* One-shot migration of an application's OWN historical mode key into the
+* record.
+*
+* The generated bootstrap only knows the record and the contract's `color-mode`
+* key — an app that persisted under its own key before adopting the record
+* would silently drop every returning visitor's mode without this. Run it
+* post-paint from the app entry: the visit on which it migrates still paints
+* in the OS-resolved mode before correcting itself — one accepted flash, once
+* — and every later load restores pre-paint through the bootstrap.
+*
+* It writes only when there is nothing to lose (no record) and something worth
+* keeping (a value in `declaredModes`), then DELETES the old key so the
+* migration cannot run twice or resurrect a stale value. Deleting is
+* legitimate precisely because the key is the application's own; the
+* contract's `color-mode` key may belong to another app on this origin and is
+* refused, as is the record key itself.
+*
+* @returns the migrated mode name, so the caller can apply it to the document
+*   for this one visit, or `null` when nothing was migrated.
+*/
+function migrateLegacyModeKey(legacyKey, declaredModes, options) {
+	const storageKey = keyOf(options);
+	if (legacyKey === CONTRACT_LEGACY_KEY) throw new Error(`appearance: '${CONTRACT_LEGACY_KEY}' is the contract's shared legacy key — the generated bootstrap reads it read-only and it may belong to another app on this origin. Migrate only keys your application owns.`);
+	if (legacyKey === storageKey) throw new Error(`appearance: legacyKey '${legacyKey}' is the record key itself — nothing to migrate.`);
+	const forget = () => {
+		try {
+			storageOf()?.removeItem(legacyKey);
+		} catch {}
+	};
+	if (readRecord(storageKey).kind !== "absent") {
+		forget();
+		return null;
+	}
+	let legacy = null;
+	try {
+		legacy = storageOf()?.getItem(legacyKey) ?? null;
+	} catch {
+		return null;
+	}
+	if (typeof legacy !== "string" || !declaredModes.includes(legacy)) {
+		if (legacy !== null) forget();
+		return null;
+	}
+	try {
+		storageOf()?.setItem(storageKey, JSON.stringify({
+			...DEFAULT_RECORD,
+			mode: legacy
+		}));
+	} catch {
+		return null;
+	}
+	forget();
+	return legacy;
+}
+//#endregion
+export { SYSTEM_MODE, migrateLegacyModeKey, persistColorMode };

package/dist/bootstrap/createAppearanceBootstrap.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The slice of a built theme the generator reads: the declared mode names.
+ * Structural on purpose — the generator reads mode KEYS only and never touches
+ * the theme's pipeline wire (guardrail G5).
+ */
+export interface AppearanceBootstrapTheme {
+    manifest: {
+        /** Mode name → resolved tokens. Only the KEYS are read. */
+        modes?: Record<string, unknown>;
+    };
+}
+export interface AppearanceBootstrapOptions {
+    /** Overrides the record key. Defaults to `animus:appearance`. */
+    storageKey?: string;
+}
+export interface AppearanceBootstrapArtifact {
+    /** Dependency-free inline IIFE, safe to embed in a document head. */
+    code: string;
+    /**
+     * `sha256-<base64>` — the CSP hash of `code`, ready for a `script-src`
+     * source list.
+     *
+     * The source expression MUST be SINGLE-QUOTED in the header, exactly as
+     * returned:
+     *
+     * ```
+     * Content-Security-Policy: script-src 'sha256-<the artifact hash>'
+     * ```
+     *
+     * Unquoted, it is parsed as a host source and silently fails to authorize
+     * the script.
+     *
+     * Always derive the header from this field at build time — never hand-copy
+     * it. Any theme edit that changes the declared mode names (or a changed
+     * `storageKey`) changes `code` and therefore this hash; a stale literal in a
+     * config file turns into a blocked script and a flash of the wrong mode.
+     */
+    cspHash: string;
+}
+/**
+ * Builds the inline appearance-restoration script for a built theme.
+ *
+ * The generated snippet, before first paint:
+ * 1. reads the appearance record from `storageKey`, falling back to the legacy
+ *    `color-mode` key ONLY when the record is absent (missing key, or an empty
+ *    string, which is not a record);
+ * 2. accepts the record only at version `1` — a future or absent version is
+ *    treated as NO record, because an older snippet cannot interpret a newer
+ *    record and absence is the neutral fail-safe;
+ * 3. sets `data-color-mode` when the resulting name is a declared mode;
+ * 4. removes the attribute for `system`, no record, an unreadable store, or an
+ *    unknown mode — absence is how "follow the OS" is represented, so later OS
+ *    changes apply with no script running.
+ *
+ * The failure semantics are deliberately asymmetric:
+ * - storage that THROWS on read (private browsing, blocked storage) means "no
+ *   knowledge", so the attribute is REMOVED and the media-query fallback takes
+ *   over; freezing a server-rendered mode would defeat that fallback;
+ * - a record that is PRESENT but unparseable means "storage is telling us
+ *   something we cannot read", so the snippet exits leaving the server-rendered
+ *   markup exactly as it was.
+ *
+ * It never writes storage, never calls `matchMedia`, and ignores the record's
+ * `theme` axis. Identical inputs always yield byte-identical output.
+ *
+ * @throws if the theme declares no color modes (a bootstrap without a mode
+ *   allowlist could not validate anything), declares the reserved name
+ *   `system`, or declares a blank mode name.
+ */
+export declare function createAppearanceBootstrap(theme: AppearanceBootstrapTheme, options?: AppearanceBootstrapOptions): AppearanceBootstrapArtifact;
+//# sourceMappingURL=createAppearanceBootstrap.d.ts.map