@elastic/distillate 0.0.0 → 0.1.0

package/dist/styles/registry.js

@@ -0,0 +1,182 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+import { cssVarName } from '../names.js';
+/**
+ * Registered style modules for one distillery. Throws on duplicate module names or colliding readable class/var names.
+ */
+export class StyleRegistry {
+    prefix;
+    reservedVarOwners;
+    sharedVarPaths;
+    modulesByName = new Map();
+    targetedKeys;
+    constructor(prefix, reservedVarOwners = new Map(), sharedVarPaths = new Set()) {
+        this.prefix = prefix;
+        this.reservedVarOwners = reservedVarOwners;
+        this.sharedVarPaths = sharedVarPaths;
+    }
+    /**
+     * Adds `module` to this registry.
+     *
+     * @throws If another module already uses this name, or if a readable class or CSS-variable name collides (including `themeVars` and `sharedVars`).
+     */
+    registerModule(module) {
+        const existing = this.modulesByName.get(module.name);
+        if (existing === module) {
+            return;
+        }
+        if (existing) {
+            throw new Error(`Style module "${module.name}" is already registered.`);
+        }
+        assertReadableNameCollisions(this.prefix, this.reservedVarOwners, this.sharedVarPaths, this.modulesByName.values(), module);
+        this.modulesByName.set(module.name, module);
+        this.targetedKeys = undefined;
+    }
+    /**
+     * True when some rule, or some inner rule of an `@media` / `@container` block, reads `key` in its selector.
+     *
+     * A nested `&` rule records its owning handle through `recordRuleDeps`, so a handle with an empty self block but real nested rules is targeted. A rule-less nested block targets nothing.
+     */
+    targetsHandle(key) {
+        return this.targetedHandleKeys().has(key);
+    }
+    targetedHandleKeys() {
+        if (this.targetedKeys) {
+            return this.targetedKeys;
+        }
+        const keys = new Set();
+        for (const module of this.modulesByName.values()) {
+            for (const entry of module.entries) {
+                if (entry.kind === 'rule') {
+                    entry.dependsOn.forEach((dep) => keys.add(dep));
+                }
+                else if (entry.kind === 'media') {
+                    for (const inner of entry.rules) {
+                        inner.dependsOn.forEach((dep) => keys.add(dep));
+                    }
+                }
+            }
+        }
+        this.targetedKeys = keys;
+        return keys;
+    }
+    /** Registered modules, sorted by name. */
+    get modules() {
+        return [...this.modulesByName.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /** Looks up a module by the name passed to `createStyleModule`. */
+    module(name) {
+        return this.modulesByName.get(name);
+    }
+    /** Handle keys across all modules. Compact-name domain for a full stylesheet. */
+    get classKeys() {
+        return this.modules.flatMap((module) => module.handleList.map((handle) => handle.key));
+    }
+    /** Theme and contextual-var keys across all modules. */
+    get cssVarKeys() {
+        const keys = new Set();
+        for (const module of this.modules) {
+            module.themeDeps.forEach((path) => keys.add(path));
+            module.varDeps.forEach((path) => keys.add(path));
+        }
+        return [...keys].sort();
+    }
+    /**
+     * Frozen class and CSS-var keys for a {@link StyleNameResolver}.
+     *
+     * @param options Overrides the registry-wide key sets when compact-naming a subset.
+     */
+    freeze(options = {}) {
+        return Object.freeze({
+            classKeys: Object.freeze(sortedUnique(options.classKeys ?? this.classKeys)),
+            cssVarKeys: Object.freeze(sortedUnique(options.cssVarKeys ?? this.cssVarKeys)),
+        });
+    }
+}
+const sortedUnique = (values) => [...new Set(values)].sort();
+const claimReadableVar = (owners, name, owner) => {
+    const prior = owners.get(name);
+    if (prior) {
+        throw new Error(`Readable CSS variable "${name}" collides between ${prior} and ${owner}.`);
+    }
+    owners.set(name, owner);
+};
+/** Readable custom-property names already claimed by `themeVars` / `sharedVars`. */
+export const readableVarOwnersFromEnvironment = (environment) => {
+    const owners = new Map();
+    const { prefix } = environment;
+    for (const path of Object.keys(environment.themeVars)) {
+        claimReadableVar(owners, cssVarName(prefix, path), `theme var "${path}"`);
+    }
+    for (const path of environment.sharedVars ?? []) {
+        claimReadableVar(owners, cssVarName(prefix, path), `shared var "${path}"`);
+    }
+    return owners;
+};
+const assertReadableNameCollisions = (prefix, reservedVarOwners, sharedVarPaths, existing, incoming) => {
+    const classOwners = new Map();
+    const reservedOwners = new Map(reservedVarOwners);
+    const localVarOwners = new Map();
+    const index = (module) => {
+        for (const handle of module.handleList) {
+            const prior = classOwners.get(handle.readableName);
+            if (prior) {
+                throw new Error(`Readable class name "${handle.readableName}" collides between ${prior} and module "${module.name}" handle "${handle.localName}".`);
+            }
+            classOwners.set(handle.readableName, `module "${module.name}" handle "${handle.localName}"`);
+        }
+        for (const path of localVarPathsOf(module, sharedVarPaths)) {
+            const name = cssVarName(prefix, path);
+            const owner = `module "${module.name}" var "${path}"`;
+            const reserved = reservedOwners.get(name);
+            if (reserved) {
+                throw new Error(`Readable CSS variable "${name}" collides between ${reserved} and ${owner}.`);
+            }
+            const prior = localVarOwners.get(name);
+            if (prior && prior.path !== path) {
+                throw new Error(`Readable CSS variable "${name}" collides between ${prior.owner} and ${owner}.`);
+            }
+            localVarOwners.set(name, { path, owner });
+        }
+    };
+    for (const module of existing) {
+        index(module);
+    }
+    index(incoming);
+};
+// `deps.vars` records every contextual var a module *references*, which includes
+// shared ones the module does not own. A shared path synthesizes the same
+// readable name as a local var would, so leaving them in makes two modules that
+// merely reference one shared var collide on it. The same exclusion is applied
+// when compaction maps readable names to compact ones.
+const localVarPathsOf = (module, sharedVarPaths) => {
+    const paths = new Set();
+    const addFrom = (declarations) => {
+        declarations.deps.vars.forEach((path) => {
+            if (!sharedVarPaths.has(path)) {
+                paths.add(path);
+            }
+        });
+        for (const group of declarations.deps.defaults) {
+            for (const item of group.keys) {
+                paths.add(item.path);
+            }
+        }
+    };
+    for (const entry of module.entries) {
+        if (entry.kind === 'handle' || entry.kind === 'rule') {
+            addFrom(entry.declarations);
+        }
+        else {
+            for (const nested of entry.rules) {
+                addFrom(nested.declarations);
+            }
+        }
+    }
+    return [...paths];
+};
+//# sourceMappingURL=registry.js.map

package/dist/styles/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/styles/registry.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport type { DistilleryEnvironment } from '../environment';\nimport { cssVarName } from '../names';\n\nimport type {\n  ContextualVarPath,\n  CssVarPath,\n  Declarations,\n  StyleRegistrySnapshot,\n  StylesModule,\n} from './types';\n\n/**\n * Registered style modules for one distillery. Throws on duplicate module names or colliding readable class/var names.\n */\nexport class StyleRegistry {\n  private readonly modulesByName = new Map<string, StylesModule>();\n  private targetedKeys: Set<string> | undefined;\n\n  constructor(\n    private readonly prefix: string,\n    private readonly reservedVarOwners: ReadonlyMap<string, string> = new Map(),\n    private readonly sharedVarPaths: ReadonlySet<string> = new Set()\n  ) {}\n\n  /**\n   * Adds `module` to this registry.\n   *\n   * @throws If another module already uses this name, or if a readable class or CSS-variable name collides (including `themeVars` and `sharedVars`).\n   */\n  registerModule(module: StylesModule): void {\n    const existing = this.modulesByName.get(module.name);\n    if (existing === module) {\n      return;\n    }\n    if (existing) {\n      throw new Error(`Style module \"${module.name}\" is already registered.`);\n    }\n    assertReadableNameCollisions(\n      this.prefix,\n      this.reservedVarOwners,\n      this.sharedVarPaths,\n      this.modulesByName.values(),\n      module\n    );\n    this.modulesByName.set(module.name, module);\n    this.targetedKeys = undefined;\n  }\n\n  /**\n   * True when some rule, or some inner rule of an `@media` / `@container` block, reads `key` in its selector.\n   *\n   * A nested `&` rule records its owning handle through `recordRuleDeps`, so a handle with an empty self block but real nested rules is targeted. A rule-less nested block targets nothing.\n   */\n  targetsHandle(key: string): boolean {\n    return this.targetedHandleKeys().has(key);\n  }\n\n  private targetedHandleKeys(): Set<string> {\n    if (this.targetedKeys) {\n      return this.targetedKeys;\n    }\n    const keys = new Set<string>();\n    for (const module of this.modulesByName.values()) {\n      for (const entry of module.entries) {\n        if (entry.kind === 'rule') {\n          entry.dependsOn.forEach((dep) => keys.add(dep));\n        } else if (entry.kind === 'media') {\n          for (const inner of entry.rules) {\n            inner.dependsOn.forEach((dep) => keys.add(dep));\n          }\n        }\n      }\n    }\n    this.targetedKeys = keys;\n    return keys;\n  }\n\n  /** Registered modules, sorted by name. */\n  get modules(): readonly StylesModule[] {\n    return [...this.modulesByName.values()].sort((a, b) =>\n      a.name.localeCompare(b.name)\n    );\n  }\n\n  /** Looks up a module by the name passed to `createStyleModule`. */\n  module(name: string): StylesModule | undefined {\n    return this.modulesByName.get(name);\n  }\n\n  /** Handle keys across all modules. Compact-name domain for a full stylesheet. */\n  get classKeys(): readonly string[] {\n    return this.modules.flatMap((module) =>\n      module.handleList.map((handle) => handle.key)\n    );\n  }\n\n  /** Theme and contextual-var keys across all modules. */\n  get cssVarKeys(): readonly CssVarPath[] {\n    const keys = new Set<CssVarPath>();\n    for (const module of this.modules) {\n      module.themeDeps.forEach((path) => keys.add(path));\n      module.varDeps.forEach((path) => keys.add(path));\n    }\n    return [...keys].sort();\n  }\n\n  /**\n   * Frozen class and CSS-var keys for a {@link StyleNameResolver}.\n   *\n   * @param options Overrides the registry-wide key sets when compact-naming a subset.\n   */\n  freeze(\n    options: {\n      /** Compact class-name domain override. */\n      classKeys?: Iterable<string>;\n      /** Compact CSS-var domain override. */\n      cssVarKeys?: Iterable<CssVarPath>;\n    } = {}\n  ): StyleRegistrySnapshot {\n    return Object.freeze({\n      classKeys: Object.freeze(\n        sortedUnique(options.classKeys ?? this.classKeys)\n      ),\n      cssVarKeys: Object.freeze(\n        sortedUnique(options.cssVarKeys ?? this.cssVarKeys)\n      ),\n    });\n  }\n}\n\nconst sortedUnique = <TValue extends string>(\n  values: Iterable<TValue>\n): readonly TValue[] => [...new Set(values)].sort();\n\nconst claimReadableVar = (\n  owners: Map<string, string>,\n  name: string,\n  owner: string\n): void => {\n  const prior = owners.get(name);\n  if (prior) {\n    throw new Error(\n      `Readable CSS variable \"${name}\" collides between ${prior} and ${owner}.`\n    );\n  }\n  owners.set(name, owner);\n};\n\n/** Claimed readable custom-property name and the owner that registered it. */\ninterface ReadableLocalVarOwner {\n  /** Canonical variable path. */\n  readonly path: ContextualVarPath;\n  /** Human-readable owner used in collision errors. */\n  readonly owner: string;\n}\n\n/** Readable custom-property names already claimed by `themeVars` / `sharedVars`. */\nexport const readableVarOwnersFromEnvironment = (\n  environment: Pick<\n    DistilleryEnvironment,\n    'prefix' | 'themeVars' | 'sharedVars'\n  >\n): ReadonlyMap<string, string> => {\n  const owners = new Map<string, string>();\n  const { prefix } = environment;\n  for (const path of Object.keys(environment.themeVars)) {\n    claimReadableVar(owners, cssVarName(prefix, path), `theme var \"${path}\"`);\n  }\n  for (const path of environment.sharedVars ?? []) {\n    claimReadableVar(owners, cssVarName(prefix, path), `shared var \"${path}\"`);\n  }\n  return owners;\n};\n\nconst assertReadableNameCollisions = (\n  prefix: string,\n  reservedVarOwners: ReadonlyMap<string, string>,\n  sharedVarPaths: ReadonlySet<string>,\n  existing: Iterable<StylesModule>,\n  incoming: StylesModule\n): void => {\n  const classOwners = new Map<string, string>();\n  const reservedOwners = new Map(reservedVarOwners);\n  const localVarOwners = new Map<string, ReadableLocalVarOwner>();\n  const index = (module: StylesModule): void => {\n    for (const handle of module.handleList) {\n      const prior = classOwners.get(handle.readableName);\n      if (prior) {\n        throw new Error(\n          `Readable class name \"${handle.readableName}\" collides between ${prior} and module \"${module.name}\" handle \"${handle.localName}\".`\n        );\n      }\n      classOwners.set(\n        handle.readableName,\n        `module \"${module.name}\" handle \"${handle.localName}\"`\n      );\n    }\n    for (const path of localVarPathsOf(module, sharedVarPaths)) {\n      const name = cssVarName(prefix, path);\n      const owner = `module \"${module.name}\" var \"${path}\"`;\n      const reserved = reservedOwners.get(name);\n      if (reserved) {\n        throw new Error(\n          `Readable CSS variable \"${name}\" collides between ${reserved} and ${owner}.`\n        );\n      }\n      const prior = localVarOwners.get(name);\n      if (prior && prior.path !== path) {\n        throw new Error(\n          `Readable CSS variable \"${name}\" collides between ${prior.owner} and ${owner}.`\n        );\n      }\n      localVarOwners.set(name, { path, owner });\n    }\n  };\n  for (const module of existing) {\n    index(module);\n  }\n  index(incoming);\n};\n\n// `deps.vars` records every contextual var a module *references*, which includes\n// shared ones the module does not own. A shared path synthesizes the same\n// readable name as a local var would, so leaving them in makes two modules that\n// merely reference one shared var collide on it. The same exclusion is applied\n// when compaction maps readable names to compact ones.\nconst localVarPathsOf = (\n  module: StylesModule,\n  sharedVarPaths: ReadonlySet<string>\n): readonly ContextualVarPath[] => {\n  const paths = new Set<ContextualVarPath>();\n  const addFrom = (declarations: Declarations): void => {\n    declarations.deps.vars.forEach((path) => {\n      if (!sharedVarPaths.has(path)) {\n        paths.add(path);\n      }\n    });\n    for (const group of declarations.deps.defaults) {\n      for (const item of group.keys) {\n        paths.add(item.path);\n      }\n    }\n  };\n  for (const entry of module.entries) {\n    if (entry.kind === 'handle' || entry.kind === 'rule') {\n      addFrom(entry.declarations);\n    } else {\n      for (const nested of entry.rules) {\n        addFrom(nested.declarations);\n      }\n    }\n  }\n  return [...paths];\n};\n"]}

package/dist/styles/types.d.ts

@@ -0,0 +1,211 @@
+import type { LocalVarDefaultMarker, LocalVarGroup, LocalVarMarker, LocalVarOverrideMarker, LocalVarRef } from '../local_vars.js';
+import type { SelectorAlternative } from '../nesting.js';
+import type { ContextualCssVar, ContextualCssVarName, CssToken, ScaleToken } from '../tokens/index.js';
+export type { LocalVarDefaultMarker, LocalVarGroup, LocalVarMarker, LocalVarOverrideMarker, LocalVarRef, };
+/** Canonical `vars/<group>/<key>` path for a contextual or module-local CSS variable. */
+export type ContextualVarPath = `vars/${string}`;
+/** Theme-token path or any other CSS-var key the resolver knows. */
+export type CssVarPath = string;
+/** Values accepted by `t.vars(...)` defaults and `.set(...)`. */
+export type CssValue = string | number | CssToken | ContextualCssVar | ContextualCssVarName | ScaleToken | LocalVarRef;
+/** Reachability sets captured while authoring a declaration block. */
+export interface StyleDeps {
+    /** Theme-token paths interpolated into this block. */
+    readonly theme: ReadonlySet<string>;
+    /** Unconditional writes and reads. Default-marker keys land here only when reachable. */
+    readonly vars: ReadonlySet<ContextualVarPath>;
+    /** Read-side `var(...)` paths. Drives default-emission reachability. */
+    readonly refs: ReadonlySet<ContextualVarPath>;
+    /** `t.vars(...)` default-emission sites, resolved after collection. */
+    readonly defaults: ReadonlyArray<DefaultGroupDeps>;
+}
+/** One `t.vars(...)` group's default-emission metadata. */
+export interface DefaultGroupDeps {
+    /** Target variable namespace group. */
+    readonly groupPath: `vars/${string}`;
+    /** Defaults registered within this group. */
+    readonly keys: ReadonlyArray<DefaultKeyDeps>;
+}
+/** One key inside a {@link DefaultGroupDeps} group. */
+export interface DefaultKeyDeps {
+    /** The specific variable key within the group. */
+    readonly key: string;
+    /** Full CSS variable path (e.g. `vars/group/key`). */
+    readonly path: ContextualVarPath;
+    /** Theme/var paths referenced by the default value. Kept if the key is reachable. */
+    readonly valueDeps: {
+        /** Theme-token paths the default value interpolates. */
+        readonly theme: ReadonlySet<string>;
+        /** Contextual-var paths the default value interpolates. */
+        readonly vars: ReadonlySet<ContextualVarPath>;
+    };
+}
+/** Mutable twin of {@link StyleDeps} used while scanning interpolations. */
+export interface MutableStyleDeps {
+    /** Theme-token paths interpolated into this block. */
+    theme: Set<string>;
+    /** Unconditional writes and reads. */
+    vars: Set<ContextualVarPath>;
+    /** Read-side `var(...)` paths. */
+    refs: Set<ContextualVarPath>;
+    /** `t.vars(...)` default-emission sites. */
+    defaults: DefaultGroupDeps[];
+}
+/** Literal CSS text or a local-var interpolation marker. */
+export type DeclarationSegment = string | LocalVarMarker;
+/** Authored CSS plus the deps the collector uses for reachability. */
+export interface Declarations {
+    /** Interleaved literal CSS and local variable markers. */
+    readonly css: readonly DeclarationSegment[];
+    /** Reachability tracking dependencies. */
+    readonly deps: StyleDeps;
+}
+/** A named class: readable name, declarations, and collection identity. */
+export interface StyleHandle {
+    /** Discriminant for {@link StyleEntry}. */
+    readonly kind: 'handle';
+    /** The registered module name this handle belongs to. */
+    readonly moduleName: string;
+    /** Leaf key if at root, or composed path for nested handles. */
+    readonly localName: string;
+    /** Full path joined by dots. */
+    readonly key: string;
+    /** Predictable name used for output CSS classes. */
+    readonly readableName: string;
+    /** CSS properties for this handle. */
+    readonly declarations: Declarations;
+    /** `true` when produced inside `variants(...)`. Skipped by {@link index.StylesCollector#use | StylesCollector.use}. */
+    readonly variant: boolean;
+    /** Produces the final class name via the provided resolver context. */
+    resolveClassName(context: {
+        /** Joins one or more handles into a class-name string. */
+        resolveClassName: (...handles: StyleHandle[]) => string;
+    }): string;
+}
+/** A selector plus declarations, optionally auto-collected from handle deps. */
+export interface StyleRule {
+    /** Discriminant for {@link StyleEntry}. */
+    readonly kind: 'rule';
+    /** The registered module name this rule belongs to. */
+    readonly moduleName: string;
+    /** Unique key for this rule within the module. */
+    readonly key: string;
+    /** Selector string factory receiving a resolver for `&` and other handles. */
+    readonly selector: (h: StyleSelectorResolver) => string;
+    /** CSS properties for this rule. */
+    readonly declarations: Declarations;
+    /** `true` when produced inside `variants(...)`. */
+    readonly variant: boolean;
+    /** Handle keys this selector reads. Empty until `assignEntries` fills it. */
+    readonly dependsOn: ReadonlySet<string>;
+    /** When `false`, skip auto-collection; the caller must `use` the rule. */
+    readonly auto: boolean;
+}
+/** Options for {@link rule}. */
+export interface RuleOptions {
+    /** When `false`, the collector must `use` this rule explicitly. Defaults to `true`. */
+    auto?: boolean;
+}
+/** `@media` or `@container` block wrapping inner {@link StyleRule}s. */
+export interface StyleMedia {
+    /** Discriminant for {@link StyleEntry}. */
+    readonly kind: 'media';
+    /**
+     * At-rule this entry emits. `kind` stays `'media'` so collector rank and deps apply uniformly; see finding `media-block-ordering`.
+     */
+    readonly atRule?: 'media' | 'container';
+    /** Stable identity for deduplication across multiple renders. */
+    readonly key: string;
+    /** The registered module name this media block belongs to. */
+    readonly moduleName: string;
+    /** The conditional query (e.g. `(min-width: 600px)`). */
+    readonly query: string;
+    /** Inner rules collected inside this block. */
+    readonly rules: readonly StyleRule[];
+    /** `true` when produced inside `variants(...)`. */
+    readonly variant: boolean;
+}
+/** One registered handle, selector rule, or at-rule block. */
+export type StyleEntry = StyleHandle | StyleRule | StyleMedia;
+/** Selector factory: call with a handle, or read sibling local names as `.class` strings. */
+export type StyleSelectorResolver = ((handle: StyleHandle) => string) & Record<string, string>;
+/** Named handle tree plus flat entries after `createStyleModule`. */
+export interface StylesModule<TStyles = StylesObject> {
+    /** The unique registered name of the module. */
+    readonly name: string;
+    /** Authored tree of handles, rules, and media; variants nest as records. */
+    readonly handles: TStyles;
+    /** Flat list of style entries (handles, rules, media) defined in this module. */
+    readonly entries: readonly StyleEntry[];
+    /** Flat list of just the style handles defined in this module. */
+    readonly handleList: readonly StyleHandle[];
+    /** Aggregated theme dependencies across all entries. */
+    readonly themeDeps: ReadonlySet<string>;
+    /** Aggregated variable dependencies across all entries. */
+    readonly varDeps: ReadonlySet<ContextualVarPath>;
+}
+/** Authored module tree before {@link ResolvedStyles} substitution. */
+export type StylesObject = Record<string, unknown>;
+/** Class and CSS-var key snapshot used to build a {@link StyleNameResolver}. */
+export interface StyleRegistrySnapshot {
+    /** Collected readable class names from registered modules. */
+    readonly classKeys: readonly string[];
+    /** Collected custom property (CSS variable) keys. */
+    readonly cssVarKeys: readonly CssVarPath[];
+}
+/** Resolves nested pending handles, rules, and medias into their runtime types. */
+export type ResolvedStyles<TValue> = TValue extends PendingStyleHandle ? StyleHandle : TValue extends StyleRule ? StyleRule : TValue extends StyleMedia ? StyleMedia : TValue extends readonly (infer TItem)[] ? readonly ResolvedStyles<TItem>[] : TValue extends Record<string, unknown> ? {
+    [TKey in keyof TValue]: ResolvedStyles<TValue[TKey]>;
+} : TValue;
+/** Authoring API passed to `createStyleModule` factories. */
+export interface StyleAuthoringApi<TTokens = unknown> {
+    /** Creates a handle template where nested `&` and `@media` flatten into sibling rules. */
+    css: (strings: TemplateStringsArray, ...values: readonly unknown[]) => PendingStyleHandle;
+    /** Creates a declaration block template for direct CSS properties. */
+    decls: (strings: TemplateStringsArray, ...values: readonly unknown[]) => Declarations;
+    /** Module-local CSS variable group. Interpolate `${group}`, `${group.key}`, or `${group.set({...})}`. */
+    vars: <TKey extends string>(group: string, defaults: Record<TKey, CssValue>) => LocalVarGroup<TKey>;
+    /** Environment token tree. */
+    tokens: TTokens;
+}
+/** Authoring-time handle before module registration rewrites it to a {@link StyleHandle}. */
+export interface PendingStyleHandle {
+    /** Discriminant for pending templates. */
+    readonly kind: 'pending-handle';
+    /** Declaration properties authored on this pending handle. */
+    readonly declarations: Declarations;
+    /** Nested `&` / `@media` rules expanded into sibling entries at registration. */
+    readonly nested?: readonly PendingNested[];
+}
+/** Nested `&` rule captured on a pending handle. */
+export interface PendingNestedRule {
+    /** Discriminant for pending nested entries. */
+    readonly kind: 'nested-rule';
+    /** Comma alternatives relative to the parent handle. */
+    readonly alternatives: readonly SelectorAlternative[];
+    /** CSS properties for this nested rule. */
+    readonly declarations: Declarations;
+}
+/** Nested `@media` captured on a pending handle. */
+export interface PendingNestedMedia {
+    /** Discriminant for pending nested entries. */
+    readonly kind: 'nested-media';
+    /** Media query text. */
+    readonly query: string;
+    /** Bare declarations inside the block, applied to the parent handle. */
+    readonly self?: Declarations;
+    /** Nested `&` rules inside this media block. */
+    readonly rules: readonly PendingNestedRule[];
+}
+/** Nested `&` rule or `@media` on a pending handle. */
+export type PendingNested = PendingNestedRule | PendingNestedMedia;
+/** Pending handle or already-resolved rule/media during registration. */
+export type PendingEntry = PendingStyleHandle | StyleRule | StyleMedia;
+/** Narrow `t` for `primitiveStyles`: handles and tokens only. */
+export interface PrimitiveStyleAuthoringApi<TTokens = unknown> {
+    /** Creates named style handles using the same template tag as `css`. */
+    style: StyleAuthoringApi<TTokens>['css'];
+    /** Environment token tree. */
+    tokens: TTokens;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/styles/types.d.ts.map

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

package/dist/styles/types.js

@@ -0,0 +1,8 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/styles/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/styles/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport type {\n  LocalVarDefaultMarker,\n  LocalVarGroup,\n  LocalVarMarker,\n  LocalVarOverrideMarker,\n  LocalVarRef,\n} from '../local_vars';\nimport type { SelectorAlternative } from '../nesting';\nimport type {\n  ContextualCssVar,\n  ContextualCssVarName,\n  CssToken,\n  ScaleToken,\n} from '../tokens';\n\nexport type {\n  LocalVarDefaultMarker,\n  LocalVarGroup,\n  LocalVarMarker,\n  LocalVarOverrideMarker,\n  LocalVarRef,\n};\n\n/** Canonical `vars/<group>/<key>` path for a contextual or module-local CSS variable. */\nexport type ContextualVarPath = `vars/${string}`;\n/** Theme-token path or any other CSS-var key the resolver knows. */\nexport type CssVarPath = string;\n\n/** Values accepted by `t.vars(...)` defaults and `.set(...)`. */\nexport type CssValue =\n  | string\n  | number\n  | CssToken\n  | ContextualCssVar\n  | ContextualCssVarName\n  | ScaleToken\n  | LocalVarRef;\n\n/** Reachability sets captured while authoring a declaration block. */\nexport interface StyleDeps {\n  /** Theme-token paths interpolated into this block. */\n  readonly theme: ReadonlySet<string>;\n  /** Unconditional writes and reads. Default-marker keys land here only when reachable. */\n  readonly vars: ReadonlySet<ContextualVarPath>;\n  /** Read-side `var(...)` paths. Drives default-emission reachability. */\n  readonly refs: ReadonlySet<ContextualVarPath>;\n  /** `t.vars(...)` default-emission sites, resolved after collection. */\n  readonly defaults: ReadonlyArray<DefaultGroupDeps>;\n}\n\n/** One `t.vars(...)` group's default-emission metadata. */\nexport interface DefaultGroupDeps {\n  /** Target variable namespace group. */\n  readonly groupPath: `vars/${string}`;\n  /** Defaults registered within this group. */\n  readonly keys: ReadonlyArray<DefaultKeyDeps>;\n}\n\n/** One key inside a {@link DefaultGroupDeps} group. */\nexport interface DefaultKeyDeps {\n  /** The specific variable key within the group. */\n  readonly key: string;\n  /** Full CSS variable path (e.g. `vars/group/key`). */\n  readonly path: ContextualVarPath;\n  /** Theme/var paths referenced by the default value. Kept if the key is reachable. */\n  readonly valueDeps: {\n    /** Theme-token paths the default value interpolates. */\n    readonly theme: ReadonlySet<string>;\n    /** Contextual-var paths the default value interpolates. */\n    readonly vars: ReadonlySet<ContextualVarPath>;\n  };\n}\n\n/** Mutable twin of {@link StyleDeps} used while scanning interpolations. */\nexport interface MutableStyleDeps {\n  /** Theme-token paths interpolated into this block. */\n  theme: Set<string>;\n  /** Unconditional writes and reads. */\n  vars: Set<ContextualVarPath>;\n  /** Read-side `var(...)` paths. */\n  refs: Set<ContextualVarPath>;\n  /** `t.vars(...)` default-emission sites. */\n  defaults: DefaultGroupDeps[];\n}\n\n/** Literal CSS text or a local-var interpolation marker. */\nexport type DeclarationSegment = string | LocalVarMarker;\n\n/** Authored CSS plus the deps the collector uses for reachability. */\nexport interface Declarations {\n  /** Interleaved literal CSS and local variable markers. */\n  readonly css: readonly DeclarationSegment[];\n  /** Reachability tracking dependencies. */\n  readonly deps: StyleDeps;\n}\n\n/** A named class: readable name, declarations, and collection identity. */\nexport interface StyleHandle {\n  /** Discriminant for {@link StyleEntry}. */\n  readonly kind: 'handle';\n  /** The registered module name this handle belongs to. */\n  readonly moduleName: string;\n  /** Leaf key if at root, or composed path for nested handles. */\n  readonly localName: string;\n  /** Full path joined by dots. */\n  readonly key: string;\n  /** Predictable name used for output CSS classes. */\n  readonly readableName: string;\n  /** CSS properties for this handle. */\n  readonly declarations: Declarations;\n  /** `true` when produced inside `variants(...)`. Skipped by {@link index.StylesCollector#use | StylesCollector.use}. */\n  readonly variant: boolean;\n  /** Produces the final class name via the provided resolver context. */\n  resolveClassName(context: {\n    /** Joins one or more handles into a class-name string. */\n    resolveClassName: (...handles: StyleHandle[]) => string;\n  }): string;\n}\n\n/** A selector plus declarations, optionally auto-collected from handle deps. */\nexport interface StyleRule {\n  /** Discriminant for {@link StyleEntry}. */\n  readonly kind: 'rule';\n  /** The registered module name this rule belongs to. */\n  readonly moduleName: string;\n  /** Unique key for this rule within the module. */\n  readonly key: string;\n  /** Selector string factory receiving a resolver for `&` and other handles. */\n  readonly selector: (h: StyleSelectorResolver) => string;\n  /** CSS properties for this rule. */\n  readonly declarations: Declarations;\n  /** `true` when produced inside `variants(...)`. */\n  readonly variant: boolean;\n  /** Handle keys this selector reads. Empty until `assignEntries` fills it. */\n  readonly dependsOn: ReadonlySet<string>;\n  /** When `false`, skip auto-collection; the caller must `use` the rule. */\n  readonly auto: boolean;\n}\n\n/** Options for {@link rule}. */\nexport interface RuleOptions {\n  /** When `false`, the collector must `use` this rule explicitly. Defaults to `true`. */\n  auto?: boolean;\n}\n\n/** `@media` or `@container` block wrapping inner {@link StyleRule}s. */\nexport interface StyleMedia {\n  /** Discriminant for {@link StyleEntry}. */\n  readonly kind: 'media';\n  /**\n   * At-rule this entry emits. `kind` stays `'media'` so collector rank and deps apply uniformly; see finding `media-block-ordering`.\n   */\n  readonly atRule?: 'media' | 'container';\n  /** Stable identity for deduplication across multiple renders. */\n  readonly key: string;\n  /** The registered module name this media block belongs to. */\n  readonly moduleName: string;\n  /** The conditional query (e.g. `(min-width: 600px)`). */\n  readonly query: string;\n  /** Inner rules collected inside this block. */\n  readonly rules: readonly StyleRule[];\n  /** `true` when produced inside `variants(...)`. */\n  readonly variant: boolean;\n}\n\n/** One registered handle, selector rule, or at-rule block. */\nexport type StyleEntry = StyleHandle | StyleRule | StyleMedia;\n/** Selector factory: call with a handle, or read sibling local names as `.class` strings. */\nexport type StyleSelectorResolver = ((handle: StyleHandle) => string) &\n  Record<string, string>;\n\n/** Named handle tree plus flat entries after `createStyleModule`. */\nexport interface StylesModule<TStyles = StylesObject> {\n  /** The unique registered name of the module. */\n  readonly name: string;\n  /** Authored tree of handles, rules, and media; variants nest as records. */\n  readonly handles: TStyles;\n  /** Flat list of style entries (handles, rules, media) defined in this module. */\n  readonly entries: readonly StyleEntry[];\n  /** Flat list of just the style handles defined in this module. */\n  readonly handleList: readonly StyleHandle[];\n  /** Aggregated theme dependencies across all entries. */\n  readonly themeDeps: ReadonlySet<string>;\n  /** Aggregated variable dependencies across all entries. */\n  readonly varDeps: ReadonlySet<ContextualVarPath>;\n}\n\n/** Authored module tree before {@link ResolvedStyles} substitution. */\nexport type StylesObject = Record<string, unknown>;\n/** Class and CSS-var key snapshot used to build a {@link StyleNameResolver}. */\nexport interface StyleRegistrySnapshot {\n  /** Collected readable class names from registered modules. */\n  readonly classKeys: readonly string[];\n  /** Collected custom property (CSS variable) keys. */\n  readonly cssVarKeys: readonly CssVarPath[];\n}\n\n/** Resolves nested pending handles, rules, and medias into their runtime types. */\nexport type ResolvedStyles<TValue> = TValue extends PendingStyleHandle\n  ? StyleHandle\n  : TValue extends StyleRule\n    ? StyleRule\n    : TValue extends StyleMedia\n      ? StyleMedia\n      : TValue extends readonly (infer TItem)[]\n        ? readonly ResolvedStyles<TItem>[]\n        : TValue extends Record<string, unknown>\n          ? { [TKey in keyof TValue]: ResolvedStyles<TValue[TKey]> }\n          : TValue;\n\n/** Authoring API passed to `createStyleModule` factories. */\nexport interface StyleAuthoringApi<TTokens = unknown> {\n  /** Creates a handle template where nested `&` and `@media` flatten into sibling rules. */\n  css: (\n    strings: TemplateStringsArray,\n    ...values: readonly unknown[]\n  ) => PendingStyleHandle;\n  /** Creates a declaration block template for direct CSS properties. */\n  decls: (\n    strings: TemplateStringsArray,\n    ...values: readonly unknown[]\n  ) => Declarations;\n  /** Module-local CSS variable group. Interpolate `${group}`, `${group.key}`, or `${group.set({...})}`. */\n  vars: <TKey extends string>(\n    group: string,\n    defaults: Record<TKey, CssValue>\n  ) => LocalVarGroup<TKey>;\n  /** Environment token tree. */\n  tokens: TTokens;\n}\n\n/** Authoring-time handle before module registration rewrites it to a {@link StyleHandle}. */\nexport interface PendingStyleHandle {\n  /** Discriminant for pending templates. */\n  readonly kind: 'pending-handle';\n  /** Declaration properties authored on this pending handle. */\n  readonly declarations: Declarations;\n  /** Nested `&` / `@media` rules expanded into sibling entries at registration. */\n  readonly nested?: readonly PendingNested[];\n}\n\n/** Nested `&` rule captured on a pending handle. */\nexport interface PendingNestedRule {\n  /** Discriminant for pending nested entries. */\n  readonly kind: 'nested-rule';\n  /** Comma alternatives relative to the parent handle. */\n  readonly alternatives: readonly SelectorAlternative[];\n  /** CSS properties for this nested rule. */\n  readonly declarations: Declarations;\n}\n\n/** Nested `@media` captured on a pending handle. */\nexport interface PendingNestedMedia {\n  /** Discriminant for pending nested entries. */\n  readonly kind: 'nested-media';\n  /** Media query text. */\n  readonly query: string;\n  /** Bare declarations inside the block, applied to the parent handle. */\n  readonly self?: Declarations;\n  /** Nested `&` rules inside this media block. */\n  readonly rules: readonly PendingNestedRule[];\n}\n\n/** Nested `&` rule or `@media` on a pending handle. */\nexport type PendingNested = PendingNestedRule | PendingNestedMedia;\n\n/** Pending handle or already-resolved rule/media during registration. */\nexport type PendingEntry = PendingStyleHandle | StyleRule | StyleMedia;\n\n/** Narrow `t` for `primitiveStyles`: handles and tokens only. */\nexport interface PrimitiveStyleAuthoringApi<TTokens = unknown> {\n  /** Creates named style handles using the same template tag as `css`. */\n  style: StyleAuthoringApi<TTokens>['css'];\n  /** Environment token tree. */\n  tokens: TTokens;\n}\n"]}

package/dist/testing.d.ts

@@ -0,0 +1,10 @@
+export { assertVarRefsHaveDeclarations, findVarRefViolations, type VarInvariantViolation, } from './var_invariant.js';
+/**
+ * Emits a TypeScript `interface` for a derived token tree, for Monaco extraLib text.
+ *
+ * @param typeName Interface identifier.
+ * @param tree Derived {@link CssToken} / {@link ScaleToken} tree.
+ * @param leafType Identifier used for every leaf. Defaults to `CssInterpolable`.
+ */
+export declare const tokenTreeDts: (typeName: string, tree: object, leafType?: string) => string;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AASA,OAAO,EACL,6BAA6B,EAC7B,oBAAoB,EACpB,KAAK,qBAAqB,GAC3B,MAAM,iBAAiB,CAAC;AAEzB;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GACvB,UAAU,MAAM,EAChB,MAAM,MAAM,EACZ,iBAA4B,KAC3B,MAAuE,CAAC"}

package/dist/testing.js

@@ -0,0 +1,31 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+import { isCssToken, isScaleToken } from './tokens/index.js';
+export { assertVarRefsHaveDeclarations, findVarRefViolations, } from './var_invariant.js';
+/**
+ * Emits a TypeScript `interface` for a derived token tree, for Monaco extraLib text.
+ *
+ * @param typeName Interface identifier.
+ * @param tree Derived {@link CssToken} / {@link ScaleToken} tree.
+ * @param leafType Identifier used for every leaf. Defaults to `CssInterpolable`.
+ */
+export const tokenTreeDts = (typeName, tree, leafType = 'CssInterpolable') => `interface ${typeName} ${emitTokenObject(tree, 0, leafType)}`;
+const emitTokenObject = (value, indent, leafType) => {
+    const pad = '  '.repeat(indent);
+    const inner = '  '.repeat(indent + 1);
+    const lines = Object.entries(value).map(([key, child]) => {
+        if (isCssToken(child) || isScaleToken(child)) {
+            return `${inner}readonly ${key}: ${leafType};`;
+        }
+        if (child && typeof child === 'object') {
+            return `${inner}readonly ${key}: ${emitTokenObject(child, indent + 1, leafType)};`;
+        }
+        throw new Error(`tokenTreeDts: unexpected leaf at "${key}"`);
+    });
+    return `{\n${lines.join('\n')}\n${pad}}`;
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEpD,OAAO,EACL,6BAA6B,EAC7B,oBAAoB,GAErB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,QAAgB,EAChB,IAAY,EACZ,QAAQ,GAAG,iBAAiB,EACpB,EAAE,CAAC,aAAa,QAAQ,IAAI,eAAe,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC;AAE3E,MAAM,eAAe,GAAG,CACtB,KAAa,EACb,MAAc,EACd,QAAgB,EACR,EAAE;IACV,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,CAAC,GAAG,CAChE,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QACf,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7C,OAAO,GAAG,KAAK,YAAY,GAAG,KAAK,QAAQ,GAAG,CAAC;QACjD,CAAC;QACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvC,OAAO,GAAG,KAAK,YAAY,GAAG,KAAK,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC;QACrF,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,qCAAqC,GAAG,GAAG,CAAC,CAAC;IAC/D,CAAC,CACF,CAAC;IACF,OAAO,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC;AAC3C,CAAC,CAAC","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport { isCssToken, isScaleToken } from './tokens';\n\nexport {\n  assertVarRefsHaveDeclarations,\n  findVarRefViolations,\n  type VarInvariantViolation,\n} from './var_invariant';\n\n/**\n * Emits a TypeScript `interface` for a derived token tree, for Monaco extraLib text.\n *\n * @param typeName Interface identifier.\n * @param tree Derived {@link CssToken} / {@link ScaleToken} tree.\n * @param leafType Identifier used for every leaf. Defaults to `CssInterpolable`.\n */\nexport const tokenTreeDts = (\n  typeName: string,\n  tree: object,\n  leafType = 'CssInterpolable'\n): string => `interface ${typeName} ${emitTokenObject(tree, 0, leafType)}`;\n\nconst emitTokenObject = (\n  value: object,\n  indent: number,\n  leafType: string\n): string => {\n  const pad = '  '.repeat(indent);\n  const inner = '  '.repeat(indent + 1);\n  const lines = Object.entries(value as Record<string, unknown>).map(\n    ([key, child]) => {\n      if (isCssToken(child) || isScaleToken(child)) {\n        return `${inner}readonly ${key}: ${leafType};`;\n      }\n      if (child && typeof child === 'object') {\n        return `${inner}readonly ${key}: ${emitTokenObject(child, indent + 1, leafType)};`;\n      }\n      throw new Error(`tokenTreeDts: unexpected leaf at \"${key}\"`);\n    }\n  );\n  return `{\\n${lines.join('\\n')}\\n${pad}}`;\n};\n"]}

package/dist/theme.d.ts

@@ -0,0 +1,85 @@
+import type { ThemeVarDefinition } from './environment.js';
+import { type CssToken, type ScaleToken, type SchemePair } from './tokens/index.js';
+/** One authoring leaf: invariant string, {@link lightDark} pair, or {@link ScaleToken}. */
+export type ThemeLeaf = string | SchemePair | ScaleToken;
+/** Nested authoring tree. Keys must match `/^[A-Za-z_][A-Za-z0-9_]*$/`. */
+export type ThemeTree = {
+    readonly [key: string]: ThemeLeaf | ThemeTree;
+};
+/** Per-scheme value tree accepted by {@link zipSchemes}. */
+export type SchemeValueTree = {
+    readonly [key: string]: string | ScaleToken | SchemeValueTree;
+};
+/** Token tree derived from an authoring {@link ThemeTree}. */
+export type TokensOf<T> = T extends ScaleToken ? ScaleToken : T extends SchemePair | string ? CssToken : T extends object ? {
+    readonly [K in keyof T]: TokensOf<T[K]>;
+} : never;
+/** Literal-value tree for one scheme. {@link ScaleToken} leaves use `.value`. */
+export type ValuesOf<T> = T extends ScaleToken ? string : T extends SchemePair | string ? string : T extends object ? {
+    readonly [K in keyof T]: ValuesOf<T[K]>;
+} : never;
+/** Slash-delimited theme-var paths (excludes {@link ScaleToken} leaves). */
+export type PathsOf<T, Prefix extends string = ''> = T extends ScaleToken ? never : T extends SchemePair | string ? Prefix extends '' ? never : Prefix : T extends object ? {
+    [K in keyof T & string]: PathsOf<T[K], Prefix extends '' ? K : `${Prefix}/${K}`>;
+}[keyof T & string] : never;
+/** {@link zipSchemes} output: equal strings collapse; differing strings become {@link SchemePair}. */
+export type Zipped<T> = T extends ScaleToken ? ScaleToken : T extends string ? string | SchemePair : T extends object ? {
+    readonly [K in keyof T]: Zipped<T[K]>;
+} : never;
+/** Partial variation of a {@link ThemeTree}. Leaves may change kind between `string` and {@link SchemePair}. */
+export type DeepPartialTheme<T> = T extends ScaleToken ? ScaleToken : T extends SchemePair | string ? string | SchemePair : T extends object ? {
+    readonly [K in keyof T]?: DeepPartialTheme<T[K]>;
+} : never;
+/** Media-conditioned variation. `media` is intrinsic; it is not a selector. */
+export interface MediaThemeVariation<T extends ThemeTree = ThemeTree> {
+    /** Media query wrapping this variation's emitted diffs. */
+    readonly media: string;
+    /** Partial variation of the base theme. */
+    readonly variation: DeepPartialTheme<T>;
+}
+/** Named variation: a partial of the base, or a media-conditioned partial. */
+export type ThemeVariation<T extends ThemeTree = ThemeTree> = DeepPartialTheme<T> | MediaThemeVariation<T>;
+/** One named variation resolved against the base at construction. */
+export interface ResolvedThemeVariation {
+    /** Name passed in `variations`. */
+    readonly name: string;
+    /** Intrinsic media query, when declared. */
+    readonly media?: string;
+    /** Base theme vars with this variation applied. */
+    readonly themeVars: Readonly<Record<string, ThemeVarDefinition>>;
+    /** Paths whose serialized value differs from the base. */
+    readonly diffs: Readonly<Record<string, ThemeVarDefinition>>;
+}
+/**
+ * Folds two per-scheme trees into one authoring tree. Equal string leaves stay bare; differing strings become {@link lightDark}. {@link ScaleToken} leaves must agree.
+ *
+ * @param light Light-scheme value tree.
+ * @param dark Dark-scheme value tree.
+ * @throws If shapes, leaf kinds, or scale values disagree, or if a differing string pair is not a CSS `<color>`.
+ */
+export declare const zipSchemes: <T extends SchemeValueTree>(light: T, dark: T) => Zipped<T>;
+/** Walks `theme` into a {@link CssToken} / {@link ScaleToken} tree and a `themeVars` registry. */
+export declare const deriveTheme: <T extends ThemeTree>(prefix: string, theme: T) => {
+    tokens: TokensOf<T>;
+    themeVars: Record<string, ThemeVarDefinition>;
+};
+/**
+ * Nested literal values for one scheme. Walks `theme` so {@link ScaleToken} leaves resolve to `.value`.
+ *
+ * @param theme Authoring tree that produced `themeVars`.
+ * @param themeVars Base registry from {@link Distillery.themeVars}.
+ * @param scheme Which side of each {@link ThemeVarDefinition} to read.
+ * @param variation When set, overridden paths come from `variation.diffs`; everything else stays on `themeVars`.
+ */
+export declare const resolveThemeValues: <T extends ThemeTree>(theme: T, themeVars: Readonly<Record<string, ThemeVarDefinition>>, scheme: "light" | "dark", variation?: ResolvedThemeVariation) => ValuesOf<T>;
+/** Looks up a declared variation. @throws If `name` is not in `variations`. */
+export declare const requireThemeVariation: (variations: Readonly<Record<string, ResolvedThemeVariation>> | undefined, name: string) => ResolvedThemeVariation;
+/** Serialized `light` / `light-dark(light, dark)` form used in emission and diffs. */
+export declare const serializedThemeValue: ({ light, dark, }: ThemeVarDefinition) => string;
+/**
+ * Resolves named `variations` against `base`. Variations extend the base only (no chains).
+ *
+ * @throws If a variation introduces an unknown path, a leaf-kind mismatch, or a diverging {@link ScaleToken}.
+ */
+export declare const resolveThemeVariations: (prefix: string, base: ThemeTree, baseVars: Readonly<Record<string, ThemeVarDefinition>>, variations: Readonly<Record<string, ThemeVariation>> | undefined) => Readonly<Record<string, ResolvedThemeVariation>>;
+//# sourceMappingURL=theme.d.ts.map

package/dist/theme.d.ts.map

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