@untheme/utils 0.1.0

package/.dist/index.d.mts

@@ -0,0 +1,181 @@
+import * as _untheme_schema from '@untheme/schema';
+import { Template, Overrides, Modifier, Context, Binding, Authored, Theme, Contract, Definition, Modifiers } from '@untheme/schema';
+
+/**
+ * Deep copy of a theme, facet by facet: identity, tokens, modifiers, and order
+ * are each rebuilt through {@link copy}, so no definition object, nested
+ * `$value` structure, or override map is shared with the source. Mutating the
+ * clone at any depth never reaches the original.
+ *
+ * Because {@link copy} reaches every value through plain property access,
+ * cloning a reactive proxy yields an inert, plain snapshot.
+ */
+declare const clone: <T extends Template>(theme: T) => T;
+
+/**
+ * Deep copy of plain data: records and arrays are rebuilt from fresh
+ * containers, so mutating the copy never reaches the source. Every value is
+ * reached through plain property access, so copying a reactive proxy yields an
+ * inert, plain snapshot detached from the proxy.
+ *
+ * Non-plain values — functions and class instances, such as those a token's
+ * `$extensions` may carry — pass through by reference rather than being
+ * duplicated. `structuredClone` is never used: it throws on functions and
+ * detaches proxies through a mechanism this copy deliberately avoids.
+ */
+declare const copy: <T>(value: T) => T;
+
+/**
+ * The entries of `to` that deviate from `from`: every key `to` holds whose
+ * value is not structurally equal to the one `from` holds. Emitted values are
+ * copies, so the result shares no structure with `to`. Keys with structurally
+ * equal values drop out; two objects that bind identically yield an empty
+ * result.
+ */
+declare const delta: <T extends object>(from: T, to: T) => Partial<T>;
+
+/**
+ * A contract extension for {@link extend}: new tokens (`XTok`) and new modifiers
+ * (`XMod`), plus optional overrides of the base's tokens and of its existing
+ * modifier contexts.
+ *
+ * An existing base token accepts an optional bare binding — a value or a
+ * `{reference}` that rebinds its `$value` only, never its `$type`. A new token
+ * requires a full {@link Authored} definition. Every value position draws its
+ * reference suggestions from the union of the base tokens and the extension's
+ * own new tokens, so a binding may reference either set.
+ *
+ * `Tok` is inferred from the base contract and `XTok` from the new-token keys
+ * alone; the reference arm of every {@link Binding} carries `NoInfer`, so
+ * a reference sitting in a value position never drives inference and never
+ * collapses the token union.
+ *
+ * `XTok` infers as every key present in `tokens`, base overrides included, since
+ * a mapped type cannot subtract the known `Tok` keys during inference. The
+ * `K extends Tok` guard routes those leaked base keys back to a bare binding, so
+ * only genuinely new keys demand a full definition. The arm stays optional: a
+ * required arm stops `XTok` from inferring when `tokens` is empty, and the
+ * fallback to `string` disables every token-name check.
+ *
+ * `modifiers` admits overrides of an existing axis's contexts and new axes
+ * carrying their complete context maps.
+ */
+type Extension<Tok extends string, Mod extends Record<string, Record<string, object>>, XTok extends string, XMod extends Record<string, Record<string, object>>> = {
+    id: string;
+    name: string;
+    tokens: {
+        [K in NoInfer<Tok>]?: Binding;
+    } & {
+        [K in XTok]?: K extends Tok ? Binding : Authored;
+    };
+    modifiers: {
+        [M in keyof Mod]?: {
+            [C in keyof Mod[M]]?: {
+                [K in NoInfer<Tok | XTok>]?: Binding;
+            };
+        };
+    } & {
+        [M in keyof XMod]: {
+            [C in keyof XMod[M]]: {
+                [K in NoInfer<Tok | XTok>]?: Binding;
+            };
+        };
+    };
+    order: ((keyof Mod | keyof XMod) & (string & {}))[];
+};
+/**
+ * The deviation between two themes, as produced by {@link diff}: a token
+ * override map and per-modifier, per-context override maps, all present (empty
+ * when nothing deviates) so consumers can inspect them without guards.
+ */
+type Diff<T extends Template> = {
+    tokens: Overrides<T>;
+    modifiers: {
+        [M in Modifier<T>]: {
+            [C in Context<T, M>]: Overrides<T>;
+        };
+    };
+};
+/**
+ * A partial overlay of a theme: any subset of identity, tokens, modifiers, and
+ * order. Both a `Layer` (identity plus partial overrides) and a `Patch`
+ * (anonymous overrides) fit this shape, so one merge serves them all.
+ */
+type Overlay<T extends Template> = {
+    id?: string;
+    name?: string;
+    tokens?: Overrides<T>;
+    modifiers?: {
+        [M in Modifier<T>]?: {
+            [C in Context<T, M>]?: Overrides<T>;
+        };
+    };
+    order?: NoInfer<Modifier<T>>[];
+};
+
+/**
+ * Computes the patch that turns `from` into `to`: every binding `to` holds that
+ * deviates from `from`, token by token and context by context. At the token
+ * level the bound `$value` is compared and emitted — a token's metadata cannot
+ * drift through the patch pipeline, so only the binding is carried. Identity and
+ * order are not compared. Empty maps mean the themes bind identically; applying
+ * the result to `from` via `merge` restores every binding `to` carries. A
+ * binding `from` holds that `to` dropped is not restored — a patch can add and
+ * override, never remove.
+ */
+declare const diff: <T extends Template>(from: Theme<T>, to: Theme<T>) => Diff<T>;
+
+/**
+ * Widens a base contract with an {@link Extension} into a fresh contract over
+ * the union token and modifier sets. Neither input is mutated.
+ *
+ * Tokens compose two ways: an extension key that already names a base token
+ * rebinds that token's `$value`, preserving its `$type` and metadata; an
+ * extension key beyond the base inserts its full definition as a new token.
+ * Modifiers spread the new axes over the base's, then deep-merge each context
+ * the two share, the extension's bindings winning per token.
+ *
+ * The base may be an authored contract or any complete {@link Theme} of one —
+ * a machine-built theme (a prior extension's output) widens the same way.
+ */
+declare const extend: <Tok extends string, Mod extends Record<string, Record<string, object>>, XTok extends string, XMod extends Record<string, Record<string, object>>>(base: Contract<Tok, Mod> | Theme<Contract<Tok, Mod>>, extension: Extension<Tok, Mod, XTok, XMod>) => {
+    id: string;
+    name: string;
+    tokens: { [K in Tok | XTok | (NoInfer<Tok> & string)]: Definition; };
+    modifiers: { [M in keyof Mod]?: { [C in keyof Mod[M]]?: { [K_1 in NoInfer<Tok | XTok>]?: Binding | undefined; } | undefined; } | undefined; } & { [M_1 in keyof XMod]: { [C in keyof XMod[M_1]]: { [K_1 in NoInfer<Tok | XTok>]?: Binding | undefined; }; }; } & { [M_2 in _untheme_schema.Modifier<Contract<Tok, Mod>>]: { [C in _untheme_schema.Context<Contract<Tok, Mod>, M_2>]: Overrides<Contract<Tok, Mod>>; }; };
+    order: ((keyof Mod | keyof XMod) & string)[];
+};
+
+declare const guard: (v: unknown) => v is Template;
+
+/**
+ * Merges overlays over a complete theme into a fresh theme, left to right:
+ * later overlays win where they bind the same token, token by token and context
+ * by context. Identity and order transfer from the last overlay that carries
+ * them. No input is mutated; with no overlays the result is a plain copy.
+ *
+ * A token override rebinds a slot's `$value` and nothing else — the slot's
+ * `$type`, description, and other metadata are preserved, and the incoming
+ * binding replaces the old `$value` whole rather than merging into it. An
+ * overlay key with no matching base slot is skipped: there is no `$type` to
+ * inherit, so no definition can be fabricated for it.
+ *
+ * A `Layer` overlay adopts its identity (apply semantics); a `Patch` overlay
+ * has none, so the prevailing identity is preserved (update semantics).
+ */
+declare const merge: <T extends Template>(theme: Theme<T>, ...overlays: Overlay<T>[]) => Theme<T>;
+
+/**
+ * Rebuilds a modifiers structure leaf by leaf: every context of every modifier
+ * mapped through the callback, each modifier keeping its own context keys. The
+ * callback's `at` indexes any other modifiers structure at the leaf's own
+ * coordinates, so a leaf can be combined with its counterpart elsewhere; a
+ * sparse structure — a layer's or patch's partial modifier map — may hold
+ * nothing there, so `at` yields the overrides or `undefined`. The
+ * modifier/context pairing is carried generically here, checked once; callers
+ * supply only the leaf operation.
+ */
+declare const traverse: <T extends Template, R>(modifiers: Modifiers<T>, fn: (overrides: Overrides<T>, at: (other: { [M in Modifier<T>]?: { [C in Context<T, M>]?: Overrides<T>; }; }) => Overrides<T> | undefined) => R) => { [M in Modifier<T>]: { [C in Context<T, M>]: R; }; };
+
+export { clone, copy, delta, diff, extend, guard, merge, traverse };
+export type { Diff, Extension, Overlay };

package/.dist/index.d.ts

@@ -0,0 +1,181 @@
+import * as _untheme_schema from '@untheme/schema';
+import { Template, Overrides, Modifier, Context, Binding, Authored, Theme, Contract, Definition, Modifiers } from '@untheme/schema';
+
+/**
+ * Deep copy of a theme, facet by facet: identity, tokens, modifiers, and order
+ * are each rebuilt through {@link copy}, so no definition object, nested
+ * `$value` structure, or override map is shared with the source. Mutating the
+ * clone at any depth never reaches the original.
+ *
+ * Because {@link copy} reaches every value through plain property access,
+ * cloning a reactive proxy yields an inert, plain snapshot.
+ */
+declare const clone: <T extends Template>(theme: T) => T;
+
+/**
+ * Deep copy of plain data: records and arrays are rebuilt from fresh
+ * containers, so mutating the copy never reaches the source. Every value is
+ * reached through plain property access, so copying a reactive proxy yields an
+ * inert, plain snapshot detached from the proxy.
+ *
+ * Non-plain values — functions and class instances, such as those a token's
+ * `$extensions` may carry — pass through by reference rather than being
+ * duplicated. `structuredClone` is never used: it throws on functions and
+ * detaches proxies through a mechanism this copy deliberately avoids.
+ */
+declare const copy: <T>(value: T) => T;
+
+/**
+ * The entries of `to` that deviate from `from`: every key `to` holds whose
+ * value is not structurally equal to the one `from` holds. Emitted values are
+ * copies, so the result shares no structure with `to`. Keys with structurally
+ * equal values drop out; two objects that bind identically yield an empty
+ * result.
+ */
+declare const delta: <T extends object>(from: T, to: T) => Partial<T>;
+
+/**
+ * A contract extension for {@link extend}: new tokens (`XTok`) and new modifiers
+ * (`XMod`), plus optional overrides of the base's tokens and of its existing
+ * modifier contexts.
+ *
+ * An existing base token accepts an optional bare binding — a value or a
+ * `{reference}` that rebinds its `$value` only, never its `$type`. A new token
+ * requires a full {@link Authored} definition. Every value position draws its
+ * reference suggestions from the union of the base tokens and the extension's
+ * own new tokens, so a binding may reference either set.
+ *
+ * `Tok` is inferred from the base contract and `XTok` from the new-token keys
+ * alone; the reference arm of every {@link Binding} carries `NoInfer`, so
+ * a reference sitting in a value position never drives inference and never
+ * collapses the token union.
+ *
+ * `XTok` infers as every key present in `tokens`, base overrides included, since
+ * a mapped type cannot subtract the known `Tok` keys during inference. The
+ * `K extends Tok` guard routes those leaked base keys back to a bare binding, so
+ * only genuinely new keys demand a full definition. The arm stays optional: a
+ * required arm stops `XTok` from inferring when `tokens` is empty, and the
+ * fallback to `string` disables every token-name check.
+ *
+ * `modifiers` admits overrides of an existing axis's contexts and new axes
+ * carrying their complete context maps.
+ */
+type Extension<Tok extends string, Mod extends Record<string, Record<string, object>>, XTok extends string, XMod extends Record<string, Record<string, object>>> = {
+    id: string;
+    name: string;
+    tokens: {
+        [K in NoInfer<Tok>]?: Binding;
+    } & {
+        [K in XTok]?: K extends Tok ? Binding : Authored;
+    };
+    modifiers: {
+        [M in keyof Mod]?: {
+            [C in keyof Mod[M]]?: {
+                [K in NoInfer<Tok | XTok>]?: Binding;
+            };
+        };
+    } & {
+        [M in keyof XMod]: {
+            [C in keyof XMod[M]]: {
+                [K in NoInfer<Tok | XTok>]?: Binding;
+            };
+        };
+    };
+    order: ((keyof Mod | keyof XMod) & (string & {}))[];
+};
+/**
+ * The deviation between two themes, as produced by {@link diff}: a token
+ * override map and per-modifier, per-context override maps, all present (empty
+ * when nothing deviates) so consumers can inspect them without guards.
+ */
+type Diff<T extends Template> = {
+    tokens: Overrides<T>;
+    modifiers: {
+        [M in Modifier<T>]: {
+            [C in Context<T, M>]: Overrides<T>;
+        };
+    };
+};
+/**
+ * A partial overlay of a theme: any subset of identity, tokens, modifiers, and
+ * order. Both a `Layer` (identity plus partial overrides) and a `Patch`
+ * (anonymous overrides) fit this shape, so one merge serves them all.
+ */
+type Overlay<T extends Template> = {
+    id?: string;
+    name?: string;
+    tokens?: Overrides<T>;
+    modifiers?: {
+        [M in Modifier<T>]?: {
+            [C in Context<T, M>]?: Overrides<T>;
+        };
+    };
+    order?: NoInfer<Modifier<T>>[];
+};
+
+/**
+ * Computes the patch that turns `from` into `to`: every binding `to` holds that
+ * deviates from `from`, token by token and context by context. At the token
+ * level the bound `$value` is compared and emitted — a token's metadata cannot
+ * drift through the patch pipeline, so only the binding is carried. Identity and
+ * order are not compared. Empty maps mean the themes bind identically; applying
+ * the result to `from` via `merge` restores every binding `to` carries. A
+ * binding `from` holds that `to` dropped is not restored — a patch can add and
+ * override, never remove.
+ */
+declare const diff: <T extends Template>(from: Theme<T>, to: Theme<T>) => Diff<T>;
+
+/**
+ * Widens a base contract with an {@link Extension} into a fresh contract over
+ * the union token and modifier sets. Neither input is mutated.
+ *
+ * Tokens compose two ways: an extension key that already names a base token
+ * rebinds that token's `$value`, preserving its `$type` and metadata; an
+ * extension key beyond the base inserts its full definition as a new token.
+ * Modifiers spread the new axes over the base's, then deep-merge each context
+ * the two share, the extension's bindings winning per token.
+ *
+ * The base may be an authored contract or any complete {@link Theme} of one —
+ * a machine-built theme (a prior extension's output) widens the same way.
+ */
+declare const extend: <Tok extends string, Mod extends Record<string, Record<string, object>>, XTok extends string, XMod extends Record<string, Record<string, object>>>(base: Contract<Tok, Mod> | Theme<Contract<Tok, Mod>>, extension: Extension<Tok, Mod, XTok, XMod>) => {
+    id: string;
+    name: string;
+    tokens: { [K in Tok | XTok | (NoInfer<Tok> & string)]: Definition; };
+    modifiers: { [M in keyof Mod]?: { [C in keyof Mod[M]]?: { [K_1 in NoInfer<Tok | XTok>]?: Binding | undefined; } | undefined; } | undefined; } & { [M_1 in keyof XMod]: { [C in keyof XMod[M_1]]: { [K_1 in NoInfer<Tok | XTok>]?: Binding | undefined; }; }; } & { [M_2 in _untheme_schema.Modifier<Contract<Tok, Mod>>]: { [C in _untheme_schema.Context<Contract<Tok, Mod>, M_2>]: Overrides<Contract<Tok, Mod>>; }; };
+    order: ((keyof Mod | keyof XMod) & string)[];
+};
+
+declare const guard: (v: unknown) => v is Template;
+
+/**
+ * Merges overlays over a complete theme into a fresh theme, left to right:
+ * later overlays win where they bind the same token, token by token and context
+ * by context. Identity and order transfer from the last overlay that carries
+ * them. No input is mutated; with no overlays the result is a plain copy.
+ *
+ * A token override rebinds a slot's `$value` and nothing else — the slot's
+ * `$type`, description, and other metadata are preserved, and the incoming
+ * binding replaces the old `$value` whole rather than merging into it. An
+ * overlay key with no matching base slot is skipped: there is no `$type` to
+ * inherit, so no definition can be fabricated for it.
+ *
+ * A `Layer` overlay adopts its identity (apply semantics); a `Patch` overlay
+ * has none, so the prevailing identity is preserved (update semantics).
+ */
+declare const merge: <T extends Template>(theme: Theme<T>, ...overlays: Overlay<T>[]) => Theme<T>;
+
+/**
+ * Rebuilds a modifiers structure leaf by leaf: every context of every modifier
+ * mapped through the callback, each modifier keeping its own context keys. The
+ * callback's `at` indexes any other modifiers structure at the leaf's own
+ * coordinates, so a leaf can be combined with its counterpart elsewhere; a
+ * sparse structure — a layer's or patch's partial modifier map — may hold
+ * nothing there, so `at` yields the overrides or `undefined`. The
+ * modifier/context pairing is carried generically here, checked once; callers
+ * supply only the leaf operation.
+ */
+declare const traverse: <T extends Template, R>(modifiers: Modifiers<T>, fn: (overrides: Overrides<T>, at: (other: { [M in Modifier<T>]?: { [C in Context<T, M>]?: Overrides<T>; }; }) => Overrides<T> | undefined) => R) => { [M in Modifier<T>]: { [C in Context<T, M>]: R; }; };
+
+export { clone, copy, delta, diff, extend, guard, merge, traverse };
+export type { Diff, Extension, Overlay };

package/.dist/index.mjs

@@ -0,0 +1,133 @@
+import { isEqual, isRecord, entries, remap, map, isDefinition, isObject } from '@untheme/common';
+
+const copy = (value) => {
+  if (Array.isArray(value)) {
+    const result = value.map((entry) => copy(entry));
+    if (!isEqual(value, result)) {
+      throw new TypeError("could not copy array");
+    }
+    return result;
+  }
+  if (isRecord(value)) {
+    const result = {};
+    for (const key of Object.keys(value)) {
+      result[key] = copy(value[key]);
+    }
+    if (!isEqual(value, result)) {
+      throw new TypeError("could not copy record");
+    }
+    return result;
+  }
+  return value;
+};
+
+const clone = (theme) => {
+  const result = {
+    id: theme.id,
+    name: theme.name,
+    tokens: copy(theme.tokens),
+    modifiers: copy(theme.modifiers),
+    order: copy(theme.order)
+  };
+  if (!isEqual(theme, result)) {
+    throw new TypeError("unable to clone a theme");
+  }
+  return result;
+};
+
+const delta = (from, to) => {
+  const result = {};
+  for (const [key, value] of entries(to)) {
+    if (!isEqual(from[key], value)) {
+      result[key] = copy(value);
+    }
+  }
+  return result;
+};
+
+const traverse = (modifiers, fn) => remap(
+  modifiers,
+  (contexts, modifier) => remap(
+    contexts,
+    (overrides, context) => fn(overrides, (other) => other[modifier]?.[context])
+  )
+);
+
+const diff = (from, to) => {
+  const tokens = delta(
+    map(from.tokens, (slot) => slot.$value),
+    map(to.tokens, (slot) => slot.$value)
+  );
+  const modifiers = traverse(
+    to.modifiers,
+    (overrides, at) => delta(at(from.modifiers) ?? {}, overrides)
+  );
+  return { tokens, modifiers };
+};
+
+const extend = (base, extension) => {
+  const source = Object.assign({}, extension.tokens, base.tokens);
+  const tokens = map(source, (slot, token) => {
+    if (slot === void 0 || !isDefinition(slot)) {
+      throw new TypeError(`token "${token}" is not a definition`);
+    }
+    const definition = slot;
+    const incoming = extension.tokens[token];
+    if (incoming === void 0 || isDefinition(incoming)) {
+      return copy(definition);
+    }
+    const rebound = {
+      ...copy(definition),
+      $value: copy(incoming)
+    };
+    return rebound;
+  });
+  const modifiers = {
+    ...copy(extension.modifiers),
+    ...traverse(base.modifiers, (overrides, at) => ({
+      ...copy(overrides),
+      ...copy(at(extension.modifiers) ?? {})
+    }))
+  };
+  const listed = new Set(extension.order);
+  const order = [
+    ...base.order.filter((modifier) => !listed.has(modifier)),
+    ...extension.order
+  ];
+  const result = {
+    id: extension.id,
+    name: extension.name,
+    tokens,
+    modifiers,
+    order
+  };
+  return result;
+};
+
+const guard = (v) => {
+  return typeof v === "object" && v !== null && "id" in v && typeof v["id"] === "string" && "name" in v && typeof v["name"] === "string" && "tokens" in v && isObject(v["tokens"]) && "modifiers" in v && isRecord(v["modifiers"]) && "order" in v && Array.isArray(v["order"]);
+};
+
+const merge = (theme, ...overlays) => {
+  return overlays.reduce(
+    (acc, overlay) => ({
+      id: overlay.id ?? acc.id,
+      name: overlay.name ?? acc.name,
+      tokens: map(acc.tokens, (slot, token) => {
+        const binding = overlay.tokens?.[token];
+        if (binding === void 0) {
+          return slot;
+        }
+        return { ...slot, $value: copy(binding) };
+      }),
+      modifiers: traverse(acc.modifiers, (overrides, at) => ({
+        ...overrides,
+        ...copy(at(overlay.modifiers ?? {}) ?? {})
+      })),
+      order: copy(overlay.order ?? acc.order)
+    }),
+    clone(theme)
+  );
+};
+
+export { clone, copy, delta, diff, extend, guard, merge, traverse };

package/README.md

@@ -0,0 +1,86 @@
+# @untheme/utils
+
+Common structural helpers for untheme's theme shape. Types come from [`@untheme/schema`](../schema); guards and generic helpers come from [`@untheme/common`](../common).
+
+## Exports
+
+### `merge(theme, ...overlays)`
+
+Merges overlays over a complete theme into a fresh theme, left to right: later overlays win where they bind the same token, token by token and context by context. Identity and order transfer from the last overlay that carries them. No input is mutated; with no overlays the result is a plain copy.
+
+```ts
+import { merge } from "@untheme/utils";
+
+merge(theme, patch); // patch has no identity → identity preserved (update)
+merge(theme, layer); // layer carries id/name → identity adopted (apply)
+merge(theme, layer, patch); // layer applied, then patched — last binding wins
+```
+
+### `extend(base, extension)`
+
+Widens a base contract with an extension into a fresh contract over the union token and modifier sets. New tokens and new modifiers join; existing tokens are overridden; existing modifier contexts are deep-merged leaf by leaf, so the base's other tokens in that context are kept. The `order` the extension lists wins — any modifier it names is dropped from the base order, then the extension's order is appended. Neither input is mutated.
+
+```ts
+import { extend } from "@untheme/utils";
+
+const wide = extend(base, {
+  id: "wide",
+  name: "Wide",
+  tokens: { accent: "#0090ff", bg: "{accent}" }, // new token + override existing
+  modifiers: {
+    color: { dark: { fg: "{accent}" } }, // override an existing context (leaf)
+    density: { compact: {}, cozy: {} }, // a new modifier
+  },
+  order: ["density", "color"],
+});
+```
+
+Unlike `merge`, which stays within one contract, `extend` is the widening primitive: the result's token and modifier sets grow to include the extension's.
+
+### `diff(from, to)`
+
+Computes the patch that turns `from` into `to`: every binding `to` holds that deviates from `from`, token by token and context by context. At the token level only the bound `$value` is compared and emitted — a token's metadata cannot drift through the patch pipeline. Identity and order are not compared. Empty maps mean the themes bind identically; applying the result to `from` via `merge` restores every binding `to` carries. A patch can add and override, never remove — a context override `from` holds that `to` dropped survives the restoration, and identity, order, and slot metadata are not part of it.
+
+```ts
+import { diff, merge } from "@untheme/utils";
+
+const deviation = diff(pristine, edited);
+merge(pristine, deviation); // ≅ edited
+```
+
+## Primitives
+
+Supporting helpers that `merge`, `extend`, and `diff` are built on.
+
+### `clone(theme)`
+
+Deep copy of a theme, facet by facet: identity, tokens, modifiers, and order are each rebuilt through `copy`, so no definition object, nested `$value` structure, or override map is shared with the source. Because `copy` reaches every value through plain property access, cloning a reactive proxy yields an inert, plain snapshot. `clone` throws a `TypeError` if the rebuilt theme isn't structurally equal to the source.
+
+```ts
+import { clone } from "@untheme/utils";
+
+const snapshot = clone(theme); // detached from any reactive proxy
+```
+
+### `copy(value)`
+
+Deep copy of plain data: records and arrays are rebuilt from fresh containers, so mutating the copy never reaches the source. Non-plain values — functions and class instances, such as those a token's `$extensions` may carry — pass through by reference rather than being duplicated. `structuredClone` is never used: it throws on functions and detaches proxies through a mechanism `copy` deliberately avoids.
+
+### `delta(from, to)`
+
+The entries of `to` that deviate from `from`: every key `to` holds whose value is not structurally equal to the one `from` holds. Emitted values are copies, so the result shares no structure with `to`. Keys with structurally equal values drop out; two objects that bind identically yield an empty result.
+
+### `traverse(modifiers, fn)`
+
+Rebuilds a modifiers structure leaf by leaf: every context of every modifier is mapped through the callback, each modifier keeping its own context keys. The callback's `at` accessor indexes another (possibly sparse) modifiers structure at the same modifier/context coordinates, so a leaf can be combined with its counterpart elsewhere. This is the primitive `diff`, `merge`, and `extend` are all built on.
+
+## Types
+
+- `Overlay<T>` — the shape `merge` accepts: any subset of identity, tokens, modifiers, and order. Both a `Layer` and a `Patch` from [`@untheme/schema`](../schema) fit it.
+- `Extension<Tok, Mod, XTok, XMod>` — the shape `extend` accepts: new tokens (`XTok`) and new modifiers (`XMod`) over a base contract's tokens (`Tok`) and modifiers (`Mod`). An existing base token accepts an optional bare binding that rebinds its `$value` only; a new token requires a full slot definition. New modifier axes carry their complete context maps; existing axes take optional overrides.
+- `Diff<T>` — the shape `diff` returns: token and per-context override maps, always present (empty when nothing deviates).
+
+## Related
+
+- [`@untheme/schema`](../schema) — token contract types and runtime validation.
+- [`@untheme/core`](../core) — the runtime theme service.

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@untheme/utils",
+  "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"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "stub": "unbuild --stub",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}