@untheme/core 0.1.0

package/.dist/index.d.mts

@@ -0,0 +1,267 @@
+import { SchemaError, Issue, Template, Theme, Input, Overrides, Layer, Schema, Modifier, Token, Binding, Values, Open, Type, Context, Patch, Contract } from '@untheme/schema';
+import { Diff } from '@untheme/utils';
+
+/**
+ * Raised when the base theme handed to {@link defineUntheme} violates its own
+ * contract. Extends {@link SchemaError}, so it carries the underlying
+ * {@link Issue}s while naming *which* boundary rejected the value.
+ */
+declare class InvalidThemeError extends SchemaError {
+    constructor(issues: Issue[]);
+}
+/**
+ * Raised when a layer — a registry seed, or an argument to {@link apply} /
+ * {@link create} — steps outside the contract. Carries the {@link Issue}s of
+ * the failed {@link SchemaError} it wraps.
+ */
+declare class InvalidLayerError extends SchemaError {
+    constructor(issues: Issue[]);
+}
+/**
+ * Raised when a patch handed to {@link update} steps outside the contract.
+ * Carries the {@link Issue}s of the failed {@link SchemaError} it wraps.
+ */
+declare class InvalidPatchError extends SchemaError {
+    constructor(issues: Issue[]);
+}
+/**
+ * Raised when {@link Untheme.select} is handed a key that names no theme in the
+ * registry. Unlike the validation errors above this carries no {@link Issue}s —
+ * a missing key is a lookup miss, not a contract violation — so it extends the
+ * plain {@link Error} while still giving the failure a semantic identity and
+ * the offending `key`.
+ */
+declare class UnknownThemeError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+/**
+ * Raised when {@link Untheme.contexts} is handed a name the contract declares
+ * no modifier under. Like {@link UnknownThemeError} this is a lookup miss, not
+ * a contract violation, so it extends the plain {@link Error} while carrying
+ * the offending `modifier`.
+ */
+declare class UnknownModifierError extends Error {
+    readonly modifier: string;
+    constructor(modifier: string);
+}
+/**
+ * Raised when {@link Untheme.resolve} follows an alias chain that loops back on
+ * itself. Like {@link UnknownThemeError} it carries no {@link Issue}s — a cycle
+ * is a resolution failure, not a contract violation — so it extends the plain
+ * {@link Error}, carrying the `chain` of token names up to and including the
+ * repeat. Detected by tracking visited tokens, so the stack never overflows.
+ */
+declare class CircularAliasError extends Error {
+    readonly chain: string[];
+    constructor(chain: string[]);
+}
+/**
+ * Runs `fn`, and if it throws a {@link SchemaError}, re-throws it as the given
+ * semantic subclass carrying the same {@link Issue}s; anything else propagates
+ * untouched. Lets the service speak in {@link InvalidThemeError} /
+ * {@link InvalidLayerError} / {@link InvalidPatchError} while the schema layer
+ * stays generic.
+ */
+declare const reframe: <T>(Semantic: new (issues: Issue[]) => SchemaError, fn: () => T) => T;
+
+/**
+ * The caller-owned live state an {@link Untheme} service reads and writes: the
+ * active theme definition, the active selection (one context per modifier), and
+ * the user override layer that `set` populates. Pass a plain object for inert
+ * state, or a reactive proxy to have reads and writes tracked.
+ *
+ * `theme` reads as the caller's own contract type but writes accept any
+ * complete {@link Theme} of that contract: `update` and `apply` store merged
+ * themes, which satisfy the contract without being the caller's exact type. A
+ * plain `{ theme, input, override }` object satisfies both sides.
+ */
+type Config<T extends Template> = {
+    get theme(): T;
+    set theme(value: Theme<T>);
+    input: Input<T>;
+    override: Overrides<T>;
+};
+/**
+ * Read/write middleware over the state container. Each slot intercepts the
+ * matching `config` field or catalog entry and transforms the value as it
+ * passes through — the integration's hook for instrumenting state without the
+ * service knowing about it. Omit a slot to pass the value through untouched.
+ */
+type Options<T extends Template> = {
+    get?: {
+        config?: {
+            theme?: (theme: T) => T;
+            input?: (input: Input<T>) => Input<T>;
+            override?: (override: Overrides<T>) => Overrides<T>;
+        };
+        themes?: {
+            [key: string]: (layer: Layer<T>) => Layer<T>;
+        };
+    };
+    set?: {
+        config?: {
+            theme?: (theme: Theme<T>) => Theme<T>;
+            input?: (input: Input<T>) => Input<T>;
+            override?: (override: Overrides<T>) => Overrides<T>;
+        };
+        themes?: {
+            [key: string]: (layer: Layer<T>) => Layer<T>;
+        };
+    };
+};
+/**
+ * A runtime theme service over a contract. Reads resolve the active selection
+ * with the user override on top; `set` writes the override; switching a context
+ * or applying a definition change updates the active state in `config`.
+ */
+interface Untheme<T extends Template> {
+    /**
+     * The caller-owned live state — the single place state is read or written raw.
+     */
+    config: Config<T>;
+    /**
+     * The catalog of switchable layers `select` / `create` / `remove` operate on.
+     */
+    themes: Record<string, Layer<T>>;
+    /**
+     * The validation bundle for the contract.
+     */
+    schema: Schema<T>;
+    /**
+     * The modifiers (axes) the contract declares, in composition order.
+     */
+    modifiers: () => Modifier<T>[];
+    /**
+     * The context names a modifier offers. Throws `UnknownModifierError` when
+     * the contract declares no modifier under the name.
+     */
+    contexts: (modifier: Modifier<T>) => string[];
+    /**
+     * The flat token map for a selection (default: the active one), each token
+     * bound to its `$value`, with the user override applied on top. Does not
+     * change the active state.
+     */
+    tokens: (input?: Input<T>) => {
+        [K in Token<T>]: Binding;
+    };
+    /**
+     * A token's effective binding: the override if set, else the composed value.
+     */
+    get: (token: Token<T>) => Binding;
+    /**
+     * A token's fully dereferenced value: whole-value references are followed to
+     * their target and references nested inside composite values resolve in
+     * place, so the result carries no references at any depth. Throws
+     * `CircularAliasError` on a reference loop.
+     */
+    resolve: (token: Token<T>) => Values<Open>[Type];
+    /**
+     * Selects a context for a modifier — the cheap runtime swap. Throws
+     * `InvalidThemeError` when the context names no declared context of the
+     * modifier.
+     */
+    swap: <M extends Modifier<T>, C extends Context<T, M>>(modifier: M, context: C) => void;
+    /**
+     * Writes a token into the user override layer. A write outside the contract —
+     * an unknown token, or a value invalid for that token's declared type — is a
+     * silent no-op. The override holds a detached copy of the value.
+     */
+    set: (token: Token<T>, value: Binding) => void;
+    /**
+     * The effective drift from the baseline as a re-appliable patch: the active
+     * theme with the user override baked in, diffed against the theme the service
+     * was built on. Token and context bindings that match the baseline drop out;
+     * what remains is everything `set` / `update` / `apply` changed. Identity is
+     * not compared. Feeding the result back through `update` reproduces the drift.
+     */
+    delta: () => Diff<T>;
+    /**
+     * Whether the user override holds any edits.
+     */
+    dirty: () => boolean;
+    /**
+     * Clears the user override.
+     */
+    reset: () => void;
+    /**
+     * Merges a patch into the active theme; identity and the override are
+     * unchanged.
+     */
+    update: (patch: Patch<T>) => void;
+    /**
+     * Becomes the layer resolved against the baseline, and clears the override.
+     */
+    apply: (layer: Layer<T>) => void;
+    /**
+     * Switches to the catalog layer filed under `key`, and clears the override.
+     */
+    select: (key: string) => void;
+    /**
+     * Files a layer in the catalog under its id and returns it resolved against
+     * the baseline as a complete theme. The active theme is not touched.
+     */
+    create: (layer: Layer<T>) => Theme<T>;
+    /**
+     * Snapshots the active theme and override as a detached theme; not
+     * registered. Throws `InvalidThemeError` when the identity leaves the
+     * snapshot invalid.
+     */
+    extract: (id: string, name: string) => Theme<T>;
+    /**
+     * Drops a layer from the catalog by id; the active theme is unaffected.
+     */
+    remove: (id: string) => void;
+}
+
+/**
+ * Builds the runtime {@link Untheme} service over a state container, for
+ * any complete theme of a contract — an authored contract via
+ * {@link defineUntheme}, or a machine-built theme (a `configure`-widened
+ * preset, a merged theme) whose slot bindings only the runtime schema can
+ * rule on. The theme is validated against its own contract up front either
+ * way.
+ *
+ * Every read and write goes through `proxy`, so the caller decides whether
+ * state is plain (tests, node) or a reactive proxy (Vue); `options` can
+ * intercept and transform each read and write on the way through. Reads resolve
+ * the active selection — base tokens overlaid with the selected context of each
+ * modifier in `order` — then apply the user override on top. `set` writes only
+ * the override; `swap` selects a modifier's context; `update` / `apply` /
+ * `select` change the definition. Switching theme (`apply` / `select`) clears
+ * the override.
+ *
+ * The baseline — a snapshot of the theme at construction — is what `apply` and
+ * `create` resolve layers against.
+ *
+ * @param config - The caller-owned container: active theme, selection, override.
+ * @param themes - The catalog of switchable layers, validated up front; the
+ *   target of `select`, `create`, and `remove`.
+ * @param options - Read/write middleware over `config` and `themes`.
+ * @returns An {@link Untheme} service bound to the container.
+ * @throws InvalidThemeError when the theme or selection violates the contract.
+ * @throws InvalidLayerError when a registry layer steps outside the contract.
+ */
+declare const makeUntheme: <T extends Theme<T>>(config: Config<T>, themes?: Record<string, Layer<T>>, options?: Options<T>) => Untheme<T>;
+
+/**
+ * Creates a runtime {@link Untheme} service from an authored contract — the
+ * front door for defining a theme inline. `Tok` is inferred from the token
+ * keys: token slots are discriminated by their declared `$type`, and modifier
+ * overrides suggest the contract's tokens at their key positions. Booting
+ * from a machine-built theme instead — a `configure`-widened preset, a merged
+ * theme — goes through {@link makeUntheme}, whose slots carry
+ * runtime-validated bindings.
+ *
+ * @param config - The caller-owned container: active theme, selection, override.
+ * @param themes - The catalog of switchable layers, validated up front; the
+ *   target of `select`, `create`, and `remove`.
+ * @param options - Read/write middleware over `config` and `themes`.
+ * @returns An {@link Untheme} service bound to the container.
+ * @throws InvalidThemeError when the theme or selection violates the contract.
+ * @throws InvalidLayerError when a registry layer steps outside the contract.
+ */
+declare const defineUntheme: <Tok extends string, Mod extends Record<string, Record<string, Partial<Record<NoInfer<Tok>, Binding>>>>>(config: Config<Contract<Tok, Mod>>, themes?: Record<string, Layer<Contract<Tok, Mod>>>, options?: Options<Contract<Tok, Mod>>) => Untheme<Contract<Tok, Mod>>;
+
+export { CircularAliasError, InvalidLayerError, InvalidPatchError, InvalidThemeError, UnknownModifierError, UnknownThemeError, defineUntheme, makeUntheme, reframe };
+export type { Config, Options, Untheme };

package/.dist/index.d.ts

@@ -0,0 +1,267 @@
+import { SchemaError, Issue, Template, Theme, Input, Overrides, Layer, Schema, Modifier, Token, Binding, Values, Open, Type, Context, Patch, Contract } from '@untheme/schema';
+import { Diff } from '@untheme/utils';
+
+/**
+ * Raised when the base theme handed to {@link defineUntheme} violates its own
+ * contract. Extends {@link SchemaError}, so it carries the underlying
+ * {@link Issue}s while naming *which* boundary rejected the value.
+ */
+declare class InvalidThemeError extends SchemaError {
+    constructor(issues: Issue[]);
+}
+/**
+ * Raised when a layer — a registry seed, or an argument to {@link apply} /
+ * {@link create} — steps outside the contract. Carries the {@link Issue}s of
+ * the failed {@link SchemaError} it wraps.
+ */
+declare class InvalidLayerError extends SchemaError {
+    constructor(issues: Issue[]);
+}
+/**
+ * Raised when a patch handed to {@link update} steps outside the contract.
+ * Carries the {@link Issue}s of the failed {@link SchemaError} it wraps.
+ */
+declare class InvalidPatchError extends SchemaError {
+    constructor(issues: Issue[]);
+}
+/**
+ * Raised when {@link Untheme.select} is handed a key that names no theme in the
+ * registry. Unlike the validation errors above this carries no {@link Issue}s —
+ * a missing key is a lookup miss, not a contract violation — so it extends the
+ * plain {@link Error} while still giving the failure a semantic identity and
+ * the offending `key`.
+ */
+declare class UnknownThemeError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+/**
+ * Raised when {@link Untheme.contexts} is handed a name the contract declares
+ * no modifier under. Like {@link UnknownThemeError} this is a lookup miss, not
+ * a contract violation, so it extends the plain {@link Error} while carrying
+ * the offending `modifier`.
+ */
+declare class UnknownModifierError extends Error {
+    readonly modifier: string;
+    constructor(modifier: string);
+}
+/**
+ * Raised when {@link Untheme.resolve} follows an alias chain that loops back on
+ * itself. Like {@link UnknownThemeError} it carries no {@link Issue}s — a cycle
+ * is a resolution failure, not a contract violation — so it extends the plain
+ * {@link Error}, carrying the `chain` of token names up to and including the
+ * repeat. Detected by tracking visited tokens, so the stack never overflows.
+ */
+declare class CircularAliasError extends Error {
+    readonly chain: string[];
+    constructor(chain: string[]);
+}
+/**
+ * Runs `fn`, and if it throws a {@link SchemaError}, re-throws it as the given
+ * semantic subclass carrying the same {@link Issue}s; anything else propagates
+ * untouched. Lets the service speak in {@link InvalidThemeError} /
+ * {@link InvalidLayerError} / {@link InvalidPatchError} while the schema layer
+ * stays generic.
+ */
+declare const reframe: <T>(Semantic: new (issues: Issue[]) => SchemaError, fn: () => T) => T;
+
+/**
+ * The caller-owned live state an {@link Untheme} service reads and writes: the
+ * active theme definition, the active selection (one context per modifier), and
+ * the user override layer that `set` populates. Pass a plain object for inert
+ * state, or a reactive proxy to have reads and writes tracked.
+ *
+ * `theme` reads as the caller's own contract type but writes accept any
+ * complete {@link Theme} of that contract: `update` and `apply` store merged
+ * themes, which satisfy the contract without being the caller's exact type. A
+ * plain `{ theme, input, override }` object satisfies both sides.
+ */
+type Config<T extends Template> = {
+    get theme(): T;
+    set theme(value: Theme<T>);
+    input: Input<T>;
+    override: Overrides<T>;
+};
+/**
+ * Read/write middleware over the state container. Each slot intercepts the
+ * matching `config` field or catalog entry and transforms the value as it
+ * passes through — the integration's hook for instrumenting state without the
+ * service knowing about it. Omit a slot to pass the value through untouched.
+ */
+type Options<T extends Template> = {
+    get?: {
+        config?: {
+            theme?: (theme: T) => T;
+            input?: (input: Input<T>) => Input<T>;
+            override?: (override: Overrides<T>) => Overrides<T>;
+        };
+        themes?: {
+            [key: string]: (layer: Layer<T>) => Layer<T>;
+        };
+    };
+    set?: {
+        config?: {
+            theme?: (theme: Theme<T>) => Theme<T>;
+            input?: (input: Input<T>) => Input<T>;
+            override?: (override: Overrides<T>) => Overrides<T>;
+        };
+        themes?: {
+            [key: string]: (layer: Layer<T>) => Layer<T>;
+        };
+    };
+};
+/**
+ * A runtime theme service over a contract. Reads resolve the active selection
+ * with the user override on top; `set` writes the override; switching a context
+ * or applying a definition change updates the active state in `config`.
+ */
+interface Untheme<T extends Template> {
+    /**
+     * The caller-owned live state — the single place state is read or written raw.
+     */
+    config: Config<T>;
+    /**
+     * The catalog of switchable layers `select` / `create` / `remove` operate on.
+     */
+    themes: Record<string, Layer<T>>;
+    /**
+     * The validation bundle for the contract.
+     */
+    schema: Schema<T>;
+    /**
+     * The modifiers (axes) the contract declares, in composition order.
+     */
+    modifiers: () => Modifier<T>[];
+    /**
+     * The context names a modifier offers. Throws `UnknownModifierError` when
+     * the contract declares no modifier under the name.
+     */
+    contexts: (modifier: Modifier<T>) => string[];
+    /**
+     * The flat token map for a selection (default: the active one), each token
+     * bound to its `$value`, with the user override applied on top. Does not
+     * change the active state.
+     */
+    tokens: (input?: Input<T>) => {
+        [K in Token<T>]: Binding;
+    };
+    /**
+     * A token's effective binding: the override if set, else the composed value.
+     */
+    get: (token: Token<T>) => Binding;
+    /**
+     * A token's fully dereferenced value: whole-value references are followed to
+     * their target and references nested inside composite values resolve in
+     * place, so the result carries no references at any depth. Throws
+     * `CircularAliasError` on a reference loop.
+     */
+    resolve: (token: Token<T>) => Values<Open>[Type];
+    /**
+     * Selects a context for a modifier — the cheap runtime swap. Throws
+     * `InvalidThemeError` when the context names no declared context of the
+     * modifier.
+     */
+    swap: <M extends Modifier<T>, C extends Context<T, M>>(modifier: M, context: C) => void;
+    /**
+     * Writes a token into the user override layer. A write outside the contract —
+     * an unknown token, or a value invalid for that token's declared type — is a
+     * silent no-op. The override holds a detached copy of the value.
+     */
+    set: (token: Token<T>, value: Binding) => void;
+    /**
+     * The effective drift from the baseline as a re-appliable patch: the active
+     * theme with the user override baked in, diffed against the theme the service
+     * was built on. Token and context bindings that match the baseline drop out;
+     * what remains is everything `set` / `update` / `apply` changed. Identity is
+     * not compared. Feeding the result back through `update` reproduces the drift.
+     */
+    delta: () => Diff<T>;
+    /**
+     * Whether the user override holds any edits.
+     */
+    dirty: () => boolean;
+    /**
+     * Clears the user override.
+     */
+    reset: () => void;
+    /**
+     * Merges a patch into the active theme; identity and the override are
+     * unchanged.
+     */
+    update: (patch: Patch<T>) => void;
+    /**
+     * Becomes the layer resolved against the baseline, and clears the override.
+     */
+    apply: (layer: Layer<T>) => void;
+    /**
+     * Switches to the catalog layer filed under `key`, and clears the override.
+     */
+    select: (key: string) => void;
+    /**
+     * Files a layer in the catalog under its id and returns it resolved against
+     * the baseline as a complete theme. The active theme is not touched.
+     */
+    create: (layer: Layer<T>) => Theme<T>;
+    /**
+     * Snapshots the active theme and override as a detached theme; not
+     * registered. Throws `InvalidThemeError` when the identity leaves the
+     * snapshot invalid.
+     */
+    extract: (id: string, name: string) => Theme<T>;
+    /**
+     * Drops a layer from the catalog by id; the active theme is unaffected.
+     */
+    remove: (id: string) => void;
+}
+
+/**
+ * Builds the runtime {@link Untheme} service over a state container, for
+ * any complete theme of a contract — an authored contract via
+ * {@link defineUntheme}, or a machine-built theme (a `configure`-widened
+ * preset, a merged theme) whose slot bindings only the runtime schema can
+ * rule on. The theme is validated against its own contract up front either
+ * way.
+ *
+ * Every read and write goes through `proxy`, so the caller decides whether
+ * state is plain (tests, node) or a reactive proxy (Vue); `options` can
+ * intercept and transform each read and write on the way through. Reads resolve
+ * the active selection — base tokens overlaid with the selected context of each
+ * modifier in `order` — then apply the user override on top. `set` writes only
+ * the override; `swap` selects a modifier's context; `update` / `apply` /
+ * `select` change the definition. Switching theme (`apply` / `select`) clears
+ * the override.
+ *
+ * The baseline — a snapshot of the theme at construction — is what `apply` and
+ * `create` resolve layers against.
+ *
+ * @param config - The caller-owned container: active theme, selection, override.
+ * @param themes - The catalog of switchable layers, validated up front; the
+ *   target of `select`, `create`, and `remove`.
+ * @param options - Read/write middleware over `config` and `themes`.
+ * @returns An {@link Untheme} service bound to the container.
+ * @throws InvalidThemeError when the theme or selection violates the contract.
+ * @throws InvalidLayerError when a registry layer steps outside the contract.
+ */
+declare const makeUntheme: <T extends Theme<T>>(config: Config<T>, themes?: Record<string, Layer<T>>, options?: Options<T>) => Untheme<T>;
+
+/**
+ * Creates a runtime {@link Untheme} service from an authored contract — the
+ * front door for defining a theme inline. `Tok` is inferred from the token
+ * keys: token slots are discriminated by their declared `$type`, and modifier
+ * overrides suggest the contract's tokens at their key positions. Booting
+ * from a machine-built theme instead — a `configure`-widened preset, a merged
+ * theme — goes through {@link makeUntheme}, whose slots carry
+ * runtime-validated bindings.
+ *
+ * @param config - The caller-owned container: active theme, selection, override.
+ * @param themes - The catalog of switchable layers, validated up front; the
+ *   target of `select`, `create`, and `remove`.
+ * @param options - Read/write middleware over `config` and `themes`.
+ * @returns An {@link Untheme} service bound to the container.
+ * @throws InvalidThemeError when the theme or selection violates the contract.
+ * @throws InvalidLayerError when a registry layer steps outside the contract.
+ */
+declare const defineUntheme: <Tok extends string, Mod extends Record<string, Record<string, Partial<Record<NoInfer<Tok>, Binding>>>>>(config: Config<Contract<Tok, Mod>>, themes?: Record<string, Layer<Contract<Tok, Mod>>>, options?: Options<Contract<Tok, Mod>>) => Untheme<Contract<Tok, Mod>>;
+
+export { CircularAliasError, InvalidLayerError, InvalidPatchError, InvalidThemeError, UnknownModifierError, UnknownThemeError, defineUntheme, makeUntheme, reframe };
+export type { Config, Options, Untheme };

package/.dist/index.mjs

@@ -0,0 +1,261 @@
+import { SchemaError, defineSchema } from '@untheme/schema';
+import { values, map, isRecord } from '@untheme/common';
+import { clone, merge, copy, diff } from '@untheme/utils';
+
+class InvalidThemeError extends SchemaError {
+  constructor(issues) {
+    super(issues);
+    this.name = "InvalidThemeError";
+  }
+}
+class InvalidLayerError extends SchemaError {
+  constructor(issues) {
+    super(issues);
+    this.name = "InvalidLayerError";
+  }
+}
+class InvalidPatchError extends SchemaError {
+  constructor(issues) {
+    super(issues);
+    this.name = "InvalidPatchError";
+  }
+}
+class UnknownThemeError extends Error {
+  key;
+  constructor(key) {
+    super(`no theme registered under "${key}"`);
+    this.name = "UnknownThemeError";
+    this.key = key;
+  }
+}
+class UnknownModifierError extends Error {
+  modifier;
+  constructor(modifier) {
+    super(`no modifier declared under "${modifier}"`);
+    this.name = "UnknownModifierError";
+    this.modifier = modifier;
+  }
+}
+class CircularAliasError extends Error {
+  chain;
+  constructor(chain) {
+    super(`alias chain loops: ${chain.join(" \u2192 ")}`);
+    this.name = "CircularAliasError";
+    this.chain = chain;
+  }
+}
+const reframe = (Semantic, fn) => {
+  try {
+    return fn();
+  } catch (error) {
+    if (error instanceof SchemaError) {
+      throw new Semantic(error.issues);
+    }
+    throw error;
+  }
+};
+
+const makeUntheme = (config, themes = {}, options = {}) => {
+  const proxy = {
+    get theme() {
+      const through = options.get?.config?.theme;
+      if (through) {
+        return through(config.theme);
+      }
+      return config.theme;
+    },
+    set theme(value) {
+      const through = options.set?.config?.theme;
+      if (through) {
+        config.theme = through(value);
+        return;
+      }
+      config.theme = value;
+    },
+    get input() {
+      const through = options.get?.config?.input;
+      if (through) {
+        return through(config.input);
+      }
+      return config.input;
+    },
+    set input(value) {
+      const through = options.set?.config?.input;
+      if (through) {
+        config.input = through(value);
+        return;
+      }
+      config.input = value;
+    },
+    get override() {
+      const through = options.get?.config?.override;
+      if (through) {
+        return through(config.override);
+      }
+      return config.override;
+    },
+    set override(value) {
+      const through = options.set?.config?.override;
+      if (through) {
+        config.override = through(value);
+        return;
+      }
+      config.override = value;
+    }
+  };
+  const registry = new Proxy(themes, {
+    get(target, key, receiver) {
+      const value = Reflect.get(target, key, receiver);
+      if (typeof key === "string") {
+        const through = options.get?.themes?.[key];
+        if (through) {
+          return through(value);
+        }
+      }
+      return value;
+    },
+    set(target, key, value, receiver) {
+      if (typeof key === "string") {
+        const through = options.set?.themes?.[key];
+        if (through) {
+          return Reflect.set(target, key, through(value), receiver);
+        }
+      }
+      return Reflect.set(target, key, value, receiver);
+    }
+  });
+  const schema = reframe(
+    InvalidThemeError,
+    () => defineSchema(clone(proxy.theme))
+  );
+  reframe(InvalidThemeError, () => schema.assert.input(proxy.input));
+  reframe(InvalidLayerError, () => {
+    for (const layer of values(registry)) {
+      schema.assert.layer(layer);
+    }
+  });
+  const tokens = (input = proxy.input) => {
+    const flat = map(proxy.theme.tokens, (slot) => slot.$value);
+    for (const modifier of proxy.theme.order) {
+      Object.assign(flat, proxy.theme.modifiers[modifier]?.[input[modifier]]);
+    }
+    Object.assign(flat, proxy.override);
+    return flat;
+  };
+  const get = (token) => {
+    return tokens()[token];
+  };
+  const set = (token, value) => {
+    if (!schema.check.overrides({ [token]: value })) {
+      return;
+    }
+    proxy.override = { ...proxy.override, [token]: copy(value) };
+  };
+  const substitute = (value, chain) => {
+    if (schema.check.reference(value)) {
+      const inner = value.slice(1, -1);
+      if (schema.check.token(inner)) {
+        return follow(inner, chain);
+      }
+    }
+    if (Array.isArray(value)) {
+      return value.map((entry) => substitute(entry, chain));
+    }
+    if (isRecord(value)) {
+      return map(value, (entry) => substitute(entry, chain));
+    }
+    return value;
+  };
+  const follow = (token, chain) => {
+    if (chain.has(token)) {
+      throw new CircularAliasError([...chain, token]);
+    }
+    return substitute(get(token), new Set(chain).add(token));
+  };
+  const resolve = (token) => {
+    return schema.parse.value(follow(token, /* @__PURE__ */ new Set()));
+  };
+  const modifiers = () => proxy.theme.order;
+  const contexts = (modifier) => {
+    const axis = proxy.theme.modifiers[modifier];
+    if (!axis) {
+      throw new UnknownModifierError(modifier);
+    }
+    return Object.keys(axis);
+  };
+  const swap = (modifier, context) => {
+    const input = { ...proxy.input, [modifier]: context };
+    reframe(InvalidThemeError, () => schema.assert.input(input));
+    proxy.input = input;
+  };
+  const update = (patch) => {
+    reframe(InvalidPatchError, () => schema.assert.patch(patch));
+    proxy.theme = merge(proxy.theme, patch);
+  };
+  const apply = (layer) => {
+    reframe(InvalidLayerError, () => schema.assert.layer(layer));
+    proxy.theme = merge(schema.base, layer);
+    proxy.override = {};
+  };
+  const select = (key) => {
+    const layer = registry[key];
+    if (!layer) {
+      throw new UnknownThemeError(key);
+    }
+    apply(layer);
+  };
+  const create = (layer) => {
+    reframe(InvalidLayerError, () => schema.assert.layer(layer));
+    registry[layer.id] = copy(layer);
+    return merge(schema.base, layer);
+  };
+  const extract = (id, name) => {
+    const snapshot = merge(proxy.theme, {
+      id,
+      name,
+      tokens: proxy.override
+    });
+    reframe(InvalidThemeError, () => schema.assert.theme(snapshot));
+    return snapshot;
+  };
+  const remove = (id) => {
+    delete registry[id];
+  };
+  const delta = () => {
+    return diff(
+      schema.base,
+      merge(proxy.theme, { tokens: proxy.override })
+    );
+  };
+  const dirty = () => Object.keys(proxy.override).length > 0;
+  const reset = () => {
+    proxy.override = {};
+  };
+  return {
+    config: proxy,
+    themes: registry,
+    schema,
+    modifiers,
+    contexts,
+    tokens,
+    get,
+    resolve,
+    swap,
+    set,
+    delta,
+    dirty,
+    reset,
+    update,
+    apply,
+    select,
+    create,
+    extract,
+    remove
+  };
+};
+
+const defineUntheme = (config, themes = {}, options = {}) => {
+  return makeUntheme(config, themes, options);
+};
+
+export { CircularAliasError, InvalidLayerError, InvalidPatchError, InvalidThemeError, UnknownModifierError, UnknownThemeError, defineUntheme, makeUntheme, reframe };

package/README.md

@@ -0,0 +1,88 @@
+# @untheme/core
+
+Runtime theme service for the untheme design token system.
+
+Provides the service that reads, resolves, and mutates tokens over a caller-owned state container. The token contract and its runtime guards live in [`@untheme/schema`](../schema); most apps depend on both transitively through the [`untheme`](../untheme) umbrella package.
+
+## The token model
+
+A theme is a flat map of tokens, each holding a `$type` and `$value`. On top of the base tokens, the contract declares any number of **modifiers** — independent axes like color scheme or density — each offering named **contexts** that override tokens for that axis. An **input** selects one context per modifier. Reading a token composes three layers in order: the base `$value`, then the selected context of each modifier (in the contract's `order`), then the user override last.
+
+## Usage
+
+```ts
+import { defineUntheme } from "@untheme/core";
+
+const ut = defineUntheme(
+  { theme, input: { color: "dark" }, override: {} },
+  { midnight },
+);
+
+ut.resolve("primary"); // follow the alias chain to a raw value
+ut.set("background", "blue"); // write to the override layer
+ut.swap("color", "light"); // switch the color modifier's context
+
+ut.dirty(); // true — the override holds edits
+ut.reset(); // clears the override
+
+ut.select("midnight"); // switch to a catalogued theme by key
+ut.create(draftLayer); // resolve + file a new theme into the catalog
+ut.remove("midnight"); // drop a theme from the catalog
+```
+
+Presets built with [`@untheme/kit`](../kit) produce the config for you: `defineUntheme(preset.use({ color: "dark" }))`. A `configure`-widened preset's theme is machine-built rather than authored, so it boots through the factory instead: `makeUntheme(app.use({ color: "dark" }))` — the same service, accepting any complete theme of a contract.
+
+## The state container
+
+The service is pure behavior: every read and write goes through `config`, the caller-owned container holding the active `theme`, the `input` (one selected context per modifier), and the `override` layer that `set` populates. Pass a plain object for inert state (tests, node), or a reactive proxy (Vue) to have every service read and write tracked — reactivity threads through property access on the container, never through the service itself.
+
+## The service
+
+`defineUntheme(state, registry?, options?)` returns an `Untheme<T>`:
+
+- `config` — the caller-owned container: `theme`, `input`, `override`.
+- `themes` — the mutable catalog of theme layers (optional second argument; defaults to empty). `select` switches to an entry by key, `create` files new themes into it, and `remove` deletes them.
+- `schema` — guard vocabulary for the theme's token contract, from [`defineSchema`](../schema).
+- `modifiers()` — the modifier axes the contract declares, in composition order.
+- `contexts(modifier)` — the context names a modifier offers.
+- `tokens(input?)` — the flat token map for a selection (default: the active one): every token's effective binding, override included, without touching `config.input`.
+- `get(token)` — a token's effective binding (alias name or raw value), unresolved.
+- `resolve(token)` — a token's fully dereferenced value: a whole-value reference is followed to its target, and references nested inside composite values resolve in place too. Throws `CircularAliasError` on a looping chain.
+- `swap(modifier, context)` — selects a context for a modifier.
+- `set(token, value)` — writes a token into the user override layer; validated against the token's declared type. A write outside the contract — an unknown token, or a value invalid for that token's type — is a silent no-op.
+- `delta()` — the drift from the baseline as a re-appliable patch: the active theme with the override baked in, diffed against the baseline.
+- `dirty()` — whether the user override holds any edits.
+- `reset()` — clears the user override.
+- `update(patch)` — merges a patch into the active theme; identity and the override are unchanged. Throws `InvalidPatchError` outside the contract.
+- `apply(layer)` — becomes that theme: the layer resolved against the baseline, and clears the override. Throws `InvalidLayerError` outside the contract.
+- `select(key)` — switches to the catalog layer filed under `key` (`apply` addressed by name), and clears the override. Throws `UnknownThemeError` when nothing is registered under `key`.
+- `create(layer)` — resolves a layer against the baseline into a complete theme and files it in the catalog under its id, where `select` can switch to it; the active theme is untouched. Throws `InvalidLayerError` outside the contract.
+- `extract(id, name)` — snapshots the active theme, including unsaved edits, as a detached theme under a new identity; returned, not filed in the catalog.
+- `remove(id)` — drops a theme from the catalog by id; a no-op when absent. The active theme is unaffected.
+
+## Baselines
+
+The service keeps exactly one baseline: a snapshot of the theme it was constructed with, captured once at creation. `apply` and `create` resolve layers against this baseline, so every theme produced this way carries the full token set, and `delta()` diffs the active theme against it. `dirty()` and `reset()` work directly on the user override — `dirty()` is true whenever the override holds any keys, `reset()` clears it — so edits made since the last `apply` / `select` / `create` are detectable and revertible.
+
+## Errors
+
+Every boundary throws a semantic error rather than a bare `Error`, in two families.
+
+**Contract violations** — subclasses of [`SchemaError`](../schema), carrying the underlying `issues` so callers can react to each failure:
+
+- `InvalidThemeError` — the baseline theme handed to `defineUntheme` violates its own contract.
+- `InvalidLayerError` — a layer (registry seed, `apply`, `create`) steps outside the contract.
+- `InvalidPatchError` — a patch handed to `update` steps outside the contract.
+
+**Resolution failures** — subclasses of plain `Error`, carrying the offending lookup:
+
+- `UnknownThemeError` — `select` was handed a `key` that names no theme in the catalog.
+- `CircularAliasError` — `resolve` hit an alias `chain` that loops back on itself; detected by tracking visited tokens, so the stack never overflows.
+
+`set` is the deliberate exception: as the hot-path interactive write it validates with the same guards but treats invalid writes as silent no-ops rather than throwing.
+
+## Related
+
+- [`@untheme/schema`](../schema) — token contract types and runtime guards.
+- [`@untheme/kit`](../kit) — authoring tool for reusable presets.
+- [`untheme`](../untheme) — umbrella package re-exporting core and schema.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@untheme/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./.dist/index.mjs",
+  "types": "./.dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./.dist/index.d.ts",
+      "import": "./.dist/index.mjs"
+    }
+  },
+  "files": [
+    ".dist"
+  ],
+  "dependencies": {
+    "@untheme/common": "0.1.0",
+    "@untheme/schema": "0.1.0",
+    "@untheme/utils": "0.1.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "stub": "unbuild --stub",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}