@jesscss/core 2.0.0-alpha.4 → 2.0.0-alpha.6

package/src/tree/rules.ts

@@ -0,0 +1,2896 @@
+import {
+  Node,
+  defineType,
+  type NodeOptions,
+  type LocationInfo, type OptionalLocation,
+  type RenderKey,
+  CANONICAL,
+  EVAL,
+  type TreeContext,
+  F_STATIC,
+  F_VISIBLE,
+  isVisibleInContext
+} from './node.js';
+import { Context } from '../context.js';
+import { isNode } from './util/is-node.js';
+import { N } from './node-type.js';
+import { type Ruleset } from './ruleset.js';
+import { type Mixin } from './mixin.js';
+import type { Selector } from './selector.js';
+import { spaced, Sequence } from './sequence.js';
+import { type PrintOptions, getPrintOptions } from './util/print.js';
+
+import { atIndex } from './util/collections.js';
+import * as Registries from './util/registry-utils.js';
+import { processExtends } from './util/extend-roots.js';
+import { type MaybePromise, pipe, isThenable, serialForEach } from '@jesscss/awaitable-pipe';
+import { Nil } from './nil.js';
+import { VarDeclaration } from './declaration-var.js';
+import type { Declaration } from './declaration.js';
+import { Any } from './any.js';
+import { List } from './list.js';
+import { indent, normalizeIndent } from './util/serialize-helper.js';
+import { addEdge, addEdgeAt, addParentEdge, getEdgeAt } from './util/cursor.js';
+import { getCurrentParentNode } from './util/selector-utils.js';
+import {
+  getChildren,
+  getParent,
+  getSourceParent,
+  setChildren,
+  setChildAt,
+  getIndex,
+  setIndex,
+  setParent,
+  isPreEvaluated,
+  isEvaluated
+} from './util/field-helpers.js';
+import {
+  dispatchMixinEvalCandidates,
+  evaluateCandidateOutput,
+  evaluateMixinArgs,
+  filterAndSortMixinEvalCandidates,
+  finalizeMixinInvocationReturn,
+  getCandidateParent,
+  matchMixinCandidates,
+  type EvaluateCandidateOutputOptions
+} from './util/mixin-instance-primitives.js';
+import type { Func } from './function.js';
+import type { Call } from './call.js';
+const { isArray } = Array;
+
+export const enum Priority {
+  None = 0,
+  Low = 1,
+  Medium = 2,
+  High = 3,
+  Highest = 4
+}
+export type RulesVisibility = 'public' | 'optional' | 'private';
+export type FlatRulePosition = {
+  renderKey?: RenderKey;
+};
+
+export type RulesOptions = {
+  /**
+   * - public   = all members are considered in lookup algorithms
+   * - optional = members are only considered if not found in the lookup tree
+   * - private  = can't be looked up
+   * - local    = only visible in the current scope
+   *
+   * Different types may have different defaults
+   *
+   * For Less:
+   *   - When mixins are parsed, their rules body is set to:
+   *     visibility: {
+   *       Ruleset: 'public',
+   *       Declaration: 'public',
+   *       VarDeclaration: 'optional',
+   *       Mixin: 'public'
+   *     }
+   *  - When detached rulesets are parsed, their rules body is set to:
+   *    visibility: {
+   *      Ruleset: 'public',
+   *      Declaration: 'public',
+   *      VarDeclaration: 'private', <-- the one notable difference
+   *      Mixin: 'public'
+   *    }
+   * @note - The reason Less has "optionality" is likely because it tries
+   * to eagerly resolve variables, so even though its in a
+   * child scope, it will still be considered if nothing else in the
+   * scope is found. I'm guessing this is because "overwriting" a local
+   * variable from something like a mixin call would be counter-intuitive,
+   * but at the same time, I guess Alexis thought that eagerly resolving
+   * the variable might be useful.
+   *
+   * Note that right now, only Declarations being set to "optional"
+   * are supported. Everything else must be public or private.
+   *
+   * For Imports, the rules body is set to:
+   *     visibility: {
+   *       Ruleset: 'public',
+   *       Declaration: 'public',
+   *       VarDeclaration: 'public',
+   *       Mixin: 'public'
+   *    }
+   */
+  rulesVisibility?: Record<string, RulesVisibility>;
+  /**
+   * If true, this Rules node is output from a mixin call.
+   * References with a target (e.g., #ns[@foo]) have public access to all nodes in these Rules.
+   * References without a target (e.g., @foo) cannot access these Rules.
+   */
+  isMixinOutput?: boolean;
+  readonly?: boolean;
+  /**
+   * all imports other than classic `@import` set returned rules to local.
+   * The reason is that variables are not transitive, and you need to re-use
+   * modules to get the same variables.
+   */
+  local?: boolean;
+  /**
+   * Sass `@forward` semantics: this Rules node exists as an export surface for downstream
+   * consumers, but should not be visible to lookups within the current stylesheet scope.
+   */
+  forward?: boolean;
+  /** Render gating marker for referenced imports/usages (serializer-time only). */
+  referenceMode?: boolean;
+  /** Explicit reference imports may render extended descendants; deduped imports may not. */
+  referenceRenderOnExtend?: boolean;
+};
+
+export interface Rules extends Node<Node[], RulesOptions & NodeOptions> {
+  readonly value: readonly Node[];
+  get options(): RulesOptions & NodeOptions & {
+    rulesVisibility: Record<string, RulesVisibility>;
+  };
+  set options(options: RulesOptions & NodeOptions & {
+    rulesVisibility: Record<string, RulesVisibility>;
+  });
+  eval(context: Context): MaybePromise<this>;
+}
+
+export type InvocationBindingFactory = (rules: Rules, context?: Context) => VarDeclaration;
+
+export type InvocationBinding = {
+  template?: VarDeclaration;
+  factory?: InvocationBindingFactory;
+  declaration?: VarDeclaration;
+};
+/**
+ * The class representing a "declaration list".
+ * CSS calls it this even though CSS Nesting
+ * adds a bunch more things that aren't declarations.
+ *
+ * Used by Ruleset and Mixin. Additionally, imports / use statements
+ * return rules.
+ *
+ * @example
+ * [
+ *   (Declaration color: black;)
+ *   (Declaration background-color: white;)
+ * ]
+ */
+export interface Rules {
+  type: 'Rules' | 'RawRules' | 'Collection';
+  shortType: 'rules' | 'rules-raw' | 'coll';
+  renderKey: RenderKey;
+}
+export class Rules extends Node<Node[], RulesOptions & NodeOptions> {
+  static override childKeys = ['value'] as const;
+
+  readonly value!: readonly Node[];
+  declare renderKey: RenderKey;
+  private _wrapperRegistrySeeded = false;
+  private _wrapperRegistrySeeding = false;
+  private _invocationBindings?: Map<string, InvocationBinding>;
+
+  functionRegistry: Registries.FunctionRegistry | undefined;
+
+  private _withOwnRenderKey<T>(
+    context: Context | undefined,
+    fn: () => T
+  ): T {
+    if (!context) {
+      return fn();
+    }
+    const targetRenderKey = this.renderKey === CANONICAL
+      ? (context.renderKey ?? this.renderKey)
+      : this.renderKey;
+    const needsRenderKey = context.renderKey !== targetRenderKey;
+    const needsRulesContext = context.rulesContext !== this;
+    if (!needsRenderKey && !needsRulesContext) {
+      return fn();
+    }
+
+    const previousRenderKey = context.renderKey;
+    const previousRulesContext = context.rulesContext;
+    if (needsRenderKey) {
+      context.renderKey = targetRenderKey;
+    }
+    if (needsRulesContext) {
+      context.rulesContext = this;
+    }
+    try {
+      return fn();
+    } finally {
+      if (needsRulesContext) {
+        context.rulesContext = previousRulesContext;
+      }
+      if (needsRenderKey) {
+        context.renderKey = previousRenderKey;
+      }
+    }
+  }
+
+  private _cloneOptionsForContext(_context?: Context): (RulesOptions & NodeOptions) | undefined {
+    const options = this.options
+      ?? (this as any)._meta?.options as (RulesOptions & NodeOptions) | undefined;
+    if (!options) {
+      return undefined;
+    }
+    return {
+      ...options,
+      rulesVisibility: options.rulesVisibility
+        ? { ...options.rulesVisibility }
+        : options.rulesVisibility
+    };
+  }
+
+  private _cloneInvocationBindings(): Map<string, InvocationBinding> | undefined {
+    if (!this._invocationBindings || this._invocationBindings.size === 0) {
+      return undefined;
+    }
+    const next = new Map<string, InvocationBinding>();
+    for (const [key, binding] of this._invocationBindings) {
+      next.set(key, {
+        template: binding.declaration ?? binding.template,
+        factory: binding.factory
+      });
+    }
+    return next;
+  }
+
+  /**
+   * Rules are often cloned during `preEval()` when a session is active.
+   * If callers register functions/mixins/declarations on the parsed tree
+   * before evaluation (e.g. via visitors), those registries must survive cloning so
+   * lookups during evaluation work as expected.
+   */
+  override clone(deep?: boolean, cloneFn?: (n: Node) => Node, ctx?: Context): this {
+    const options = this._cloneOptionsForContext(ctx);
+    const location = Array.isArray(this.location) && this.location.length === 6
+      ? this.location as LocationInfo
+      : undefined;
+    const detachedRenderKey = (
+      !deep
+      && this.renderKey === CANONICAL
+      && ctx
+        ? ctx.nextRenderKey()
+        : this.renderKey
+    );
+    const newRules = deep
+      ? super.clone(deep, cloneFn, ctx)
+      : (() => {
+          const wrapper = new (this.constructor as typeof Rules)(
+            [],
+            options ? { ...options } : undefined,
+            location,
+            this.treeContext
+          ) as this;
+          wrapper._setValueArray(this.value as Node[]);
+          wrapper.inherit(this);
+          wrapper.renderKey = detachedRenderKey;
+          if (wrapper.renderKey !== CANONICAL) {
+            wrapper._connectSharedChildren(wrapper.renderKey);
+          }
+          return wrapper;
+        })();
+
+    if (deep && options) {
+      newRules.options = options as typeof newRules.options;
+    }
+
+    if (!deep) {
+      newRules.inherit(this);
+    }
+
+    const invocationBindings = this._cloneInvocationBindings();
+    if (invocationBindings) {
+      newRules._invocationBindings = invocationBindings;
+    }
+
+    if (ctx) {
+      const parent = getCurrentParentNode(this, ctx);
+      if (parent) {
+        if (newRules.renderKey !== CANONICAL) {
+          setParent(newRules, parent, { ...ctx, renderKey: newRules.renderKey });
+        } else {
+          setParent(newRules, parent, ctx);
+        }
+      }
+    }
+
+    // Only preserve *function* registry across clones.
+    // This supports Less plugin compat, where plugins can inject functions into the registry
+    // without creating AST nodes that would be re-registered on clone.
+    //
+    // Do NOT reuse declaration/mixin/ruleset registries across clones; those should always
+    // be rebuilt from AST nodes via lazy indexing.
+    if (this.functionRegistry) {
+      newRules.functionRegistry = this.functionRegistry.cloneForRules(newRules);
+    }
+
+    return newRules;
+  }
+
+  /**
+   * Detached ruleset calls unlock shared top-level children into the active
+   * lookup scope, but must not canonically reparent those children.
+   *
+   * Keep this seam local to Rules so the detached-ruleset path does not need
+   * to rely on raw clone(false) semantics.
+   */
+  cloneDetachedUnlockWrapper(ctx: Context): this {
+    const wrapper = this.createShallowBodyWrapper(ctx) as this;
+    return wrapper;
+  }
+
+  /**
+   * Scope-isolation callers need copied Rules options/visibility while keeping
+   * shared top-level children canonically parented. Active lookups should still
+   * resolve through the wrapper during the current session.
+   */
+  cloneVisibilityIsolationWrapper(ctx: Context): this {
+    const wrapper = this.createShallowBodyWrapper(ctx) as this;
+    return wrapper;
+  }
+
+  /**
+   * Lazily create registries for types as needed.
+   */
+  private static _registryKey(type: string): 'rulesetRegistry' | 'mixinRegistry' | 'declarationRegistry' | 'functionRegistry' {
+    return `${type}Registry` as any;
+  }
+
+  private static _registryClass(type: string) {
+    return Registries[`${type.charAt(0).toUpperCase()}${type.slice(1)}Registry` as 'RulesetRegistry' | 'MixinRegistry' | 'DeclarationRegistry' | 'FunctionRegistry'];
+  }
+
+  private _ensureDirectRegistry(
+    type: 'ruleset' | 'declaration' | 'mixin' | 'function',
+    context?: Context
+  ) {
+    const key = Rules._registryKey(type);
+    let registry = (this as any)[key];
+    if (!registry) {
+      registry = new (Rules._registryClass(type))(this, context);
+      (this as any)[key] = registry;
+    } else if (context && !(registry as any).context) {
+      (registry as any).context = context;
+    }
+    return registry;
+  }
+
+  private _isWrapperRegistryOwner(): boolean {
+    return this.renderKey !== CANONICAL;
+  }
+
+  private _connectSharedChildren(renderKey: RenderKey): void {
+    const seen = new Set<Node>();
+    const connectDescendants = (parent: Node, child: Node): void => {
+      addParentEdge(child, renderKey, parent);
+      if (seen.has(child)) {
+        return;
+      }
+      seen.add(child);
+      const childKeys = (child.constructor as typeof Node).childKeys;
+      if (!childKeys) {
+        return;
+      }
+      for (const key of childKeys) {
+        const value = (child as unknown as Record<string, unknown>)[key];
+        if (Array.isArray(value)) {
+          for (const item of value) {
+            if (item instanceof Node) {
+              connectDescendants(child, item);
+            }
+          }
+          continue;
+        }
+        if (value instanceof Node) {
+          connectDescendants(child, value);
+        }
+      }
+    };
+
+    for (const child of this.value) {
+      if (child instanceof Node) {
+        connectDescendants(this, child);
+      }
+    }
+  }
+
+  private _ensureWrapperRegistrySeeded(context?: Context): void {
+    if (!this._isWrapperRegistryOwner() || this._wrapperRegistrySeeded || this._wrapperRegistrySeeding) {
+      return;
+    }
+
+    this._wrapperRegistrySeeding = true;
+    try {
+      (this as any).rulesetRegistry = undefined;
+      (this as any).mixinRegistry = undefined;
+      (this as any).declarationRegistry = undefined;
+      this._rulesSet = [];
+
+      for (const child of this.getRegistryChildren(context)) {
+        this.registerNode(child, undefined, context);
+      }
+
+      this._wrapperRegistrySeeded = true;
+    } finally {
+      this._wrapperRegistrySeeding = false;
+    }
+  }
+
+  /**
+   * Register a child node into the appropriate registry.
+   * Creates the registry lazily on first registration.
+   * Wrapper/derived Rules own their registries directly.
+   * Canonical Rules still fall back to direct per-node registries until the
+   * remaining lookup paths are fully converged on render-path ownership.
+   */
+  register(
+    type: 'ruleset' | 'declaration' | 'mixin' | 'function',
+    node: Node,
+    context?: Context
+  ) {
+    return this._withOwnRenderKey(context, () => {
+      this._ensureWrapperRegistrySeeded(context);
+      const registry = this._ensureDirectRegistry(type, context);
+      return registry.add(node);
+    });
+  }
+
+  /**
+   * Get a registry for lookups. Read-only — returns undefined if no
+   * registry was ever created (meaning nothing was registered).
+   */
+  getRegistry(type: 'ruleset', context?: Context): Registries.RulesetRegistry;
+  getRegistry(type: 'declaration', context?: Context): Registries.DeclarationRegistry;
+  getRegistry(type: 'mixin', context?: Context): Registries.MixinRegistry;
+  getRegistry(type: 'function', context?: Context): Registries.FunctionRegistry;
+  getRegistry(type: 'ruleset' | 'declaration' | 'mixin' | 'function', context?: Context): Registries.RulesetRegistry | Registries.DeclarationRegistry | Registries.MixinRegistry | Registries.FunctionRegistry;
+  getRegistry(type: 'ruleset' | 'declaration' | 'mixin' | 'function', context?: Context) {
+    return this._withOwnRenderKey(context, () => {
+      this._ensureWrapperRegistrySeeded(context);
+      return this._ensureDirectRegistry(type, context);
+    });
+  }
+
+  getRegistryParent(context?: Context): Rules | undefined {
+    return this._withOwnRenderKey(context, () => {
+      let parent = getCurrentParentNode(this, context);
+      while (parent && parent.type !== 'Rules') {
+        parent = getCurrentParentNode(parent, context);
+      }
+      if (parent) {
+        return parent as Rules | undefined;
+      }
+      let sourceParent = getSourceParent(this, context);
+      while (sourceParent && sourceParent.type !== 'Rules') {
+        sourceParent = getCurrentParentNode(sourceParent, context);
+      }
+      return sourceParent as Rules | undefined;
+    });
+  }
+
+  /**
+   * This wrapper is used so we don't prematurely create a registry
+   * just to search it.
+   */
+  find(type: 'ruleset', keys: string | string[] | Set<string>, filterType?: string, options?: Registries.FindOptions): ReturnType<Registries.RulesetRegistry['find']> | undefined;
+  find(type: 'declaration', keys: string, filterType?: string, options?: Registries.DeclarationFindOptions): ReturnType<Registries.DeclarationRegistry['find']> | undefined;
+  find(type: 'mixin', keys: string | string[], filterType?: string, options?: Registries.FindOptions): ReturnType<Registries.MixinRegistry['find']> | undefined;
+  find(type: 'function', keys: string, filterType?: string, options?: Registries.FindOptions): ReturnType<Registries.FunctionRegistry['find']> | undefined;
+  find(type: 'ruleset' | 'declaration' | 'mixin' | 'function', key: string, filterType: string, options?: Registries.FindOptions): ReturnType<Registries.RulesetRegistry['find']> | ReturnType<Registries.DeclarationRegistry['find']> | ReturnType<Registries.MixinRegistry['find']> | ReturnType<Registries.FunctionRegistry['find']> | undefined;
+  find(
+    type: 'ruleset' | 'declaration' | 'mixin' | 'function',
+    keys: string | string[] | Set<string>,
+    filterType?: string,
+    options: Registries.FindOptions = {}
+  ): ReturnType<Registries.RulesetRegistry['find']> | ReturnType<Registries.DeclarationRegistry['find']> | ReturnType<Registries.MixinRegistry['find']> | ReturnType<Registries.FunctionRegistry['find']> | undefined {
+    return this._withOwnRenderKey(options.context, () => {
+      const registry = this.getRegistry(type, options.context);
+      return (registry.find as Function)(keys, filterType, options);
+    });
+  }
+
+  findStatePatchedFunction(
+    name: string,
+    options: Registries.FindOptions = {}
+  ): ReturnType<Registries.FunctionRegistry['find']> | undefined {
+    const { filter, context, searchParents = true } = options;
+    return this._withOwnRenderKey(context, () => {
+      let rules: Rules | undefined = this;
+      let findRoot = false;
+
+      while (rules) {
+        for (const child of rules.getRegistryChildren(context)) {
+          if (!isNode(child, N.Func)) {
+            continue;
+          }
+          if (filter && !filter(child)) {
+            continue;
+          }
+          if ((child as Func).getNameKey(context) === name) {
+            return child as Func;
+          }
+        }
+
+        if (!searchParents) {
+          break;
+        }
+
+        do {
+          rules = rules?.getRegistryParent(context);
+          if (findRoot && rules?.type === 'Rules' && rules.getRegistryParent(context) === undefined) {
+            break;
+          }
+          if (rules && rules.sourceNode?.type === 'StyleImport' && rules.sourceNode.options.type !== 'import') {
+            findRoot = true;
+          }
+        } while (!findRoot && rules && rules.type !== 'Rules');
+      }
+
+      return undefined;
+    });
+  }
+
+  override toString(options?: PrintOptions): string {
+    if (!isVisibleInContext(this, options?.context) && !this.fullRender) {
+      return '';
+    }
+    options = getPrintOptions(options);
+    const w = options.writer!;
+    const depth = options.depth!;
+    const mark = w.mark();
+
+    const ctx = options.context;
+    return this._withOwnRenderKey(ctx, () => {
+      const suppressedLeadingComments: Array<{ node: Node; visible: boolean }> = [];
+      if (depth === 0) {
+      // Snapshot global emit-tracking so repeated `.toString()` calls remain stable.
+        const prevCharsetEmitted = ctx?.charsetEmitted;
+        const prevTopImports = ctx?.topImports ? [...ctx.topImports] : undefined;
+        // @charset must be first
+        if (ctx?.currentCharset && !ctx.charsetEmitted) {
+          const charset = ctx.currentCharset;
+          // Use capture to avoid double-writing (toTrimmedString writes to writer AND returns the string)
+          const charsetStr = w.capture(() => charset.toTrimmedString(options));
+          w.add(charsetStr, charset);
+          w.add('\n');
+          // Do not permanently flip `charsetEmitted` here; restore at end.
+          ctx.charsetEmitted = true;
+        }
+        // Less keeps leading comments before hoisted @import output.
+        const isCommentLike = (node: Node): boolean => {
+          const text = String(node.valueOf?.() ?? '').trimStart();
+          if (!text.startsWith('/*')) {
+            return false;
+          }
+          return isNode(node, N.Comment) || isNode(node, N.Any);
+        };
+        if (ctx?.topImports?.length) {
+          for (const node of this._getRenderChildren(ctx)) {
+            if (!isCommentLike(node)) {
+              break;
+            }
+            const commentStr = w.capture(() => node.toTrimmedString(options));
+            w.add(normalizeIndent(commentStr, ''), node);
+            w.add('\n');
+            const wasVisible = node.hasFlag(F_VISIBLE);
+            suppressedLeadingComments.push({ node, visible: wasVisible });
+            if (wasVisible) {
+              node.removeFlag(F_VISIBLE);
+            }
+          }
+        }
+        // @import must come after @charset but before other rules
+        if (ctx?.topImports?.length) {
+          for (const importRule of ctx.topImports) {
+            const importStr = w.capture(() => importRule.toString(options));
+            w.add(normalizeIndent(importStr, ''), importRule);
+            w.add('\n');
+          }
+          // Do not permanently clear; restore at end.
+        }
+        // Restore global tracking (we only needed it during this print).
+        if (ctx) {
+          ctx.charsetEmitted = prevCharsetEmitted;
+          if (prevTopImports) {
+            ctx.topImports = prevTopImports;
+          }
+        }
+      }
+
+      this.processPrePost('pre', '', options);
+      const bodyMark = w.mark();
+      const bodyStr = this.toTrimmedString(options);
+      const bodyEmitted = w.getSince(bodyMark);
+      if (bodyEmitted.length === 0 && bodyStr) {
+        w.add(bodyStr);
+      }
+      // At root level, ensure output ends with a single newline (standard for CSS files)
+      // Don't propagate all the last child's post content (which may have extra whitespace)
+      if (depth === 0) {
+        for (const suppressed of suppressedLeadingComments) {
+          if (suppressed.visible) {
+            suppressed.node.addFlag(F_VISIBLE);
+          }
+        }
+        const result = w.getSince(mark).trimEnd();
+        // Ensure exactly one trailing newline (only if there's content)
+        return result ? result + '\n' : '';
+      }
+      return w.getSince(mark);
+    });
+  }
+
+  pendingExtends = new Set<[find: Selector, extendWith: Selector, partial: boolean]>();
+
+  _setValueArray(value: Node[]): void {
+    (this as unknown as { value: Node[] }).value = value;
+  }
+
+  prependWrapperChildren(...items: Node[]): void {
+    if (items.length === 0) {
+      return;
+    }
+    this._setValueArray([...items, ...(this.value as Node[])]);
+    for (const item of items) {
+      if (item instanceof Node) {
+        this.adopt(item);
+        this.registerNode(item);
+      }
+    }
+  }
+
+  /**
+   * Create a shallow body wrapper for mixin eval.
+   *
+   * Creates a new Rules that SHARES the current children array and does NOT adopt
+   * children canonically (their canonical `.parent` stays unchanged). Render-key
+   * parent edges carry the per-placement parent chain.
+   *
+   * This replaces clone(true) in the mixin body path for massive perf improvement:
+   * a mixin body with 100 declarations creates 1 Rules wrapper
+   * instead of recursively cloning all 100+ nodes.
+   */
+  createShallowBodyWrapper(ctx?: Context, renderKey?: RenderKey): Rules {
+    const options = this._cloneOptionsForContext(ctx);
+    const location = Array.isArray(this.location) && this.location.length === 6
+      ? this.location as LocationInfo
+      : undefined;
+    const nextRenderKey = renderKey ?? EVAL;
+    // Create a new Rules with empty children — bypass constructor adoption
+    const wrapper = new (this.constructor as typeof Rules)(
+      [],
+      options ? { ...options } : undefined,
+      location,
+      this.treeContext
+    );
+    // Reuse the same child array directly — NOT through the constructor
+    // so adopt() is NOT called on canonical children.
+    wrapper._setValueArray(this.value as Node[]);
+    wrapper.inherit(this);
+    wrapper.renderKey = nextRenderKey;
+    const invocationBindings = this._cloneInvocationBindings();
+    if (invocationBindings) {
+      wrapper._invocationBindings = invocationBindings;
+    }
+    if (this.functionRegistry) {
+      wrapper.functionRegistry = this.functionRegistry.cloneForRules(wrapper);
+    }
+    wrapper._connectSharedChildren(wrapper.renderKey);
+    const sourceValueEdges = (this as unknown as { valueEdges?: Array<Map<RenderKey, Node> | undefined> }).valueEdges;
+    if (sourceValueEdges) {
+      for (let index = 0; index < sourceValueEdges.length; index++) {
+        const override = sourceValueEdges[index]?.get(nextRenderKey);
+        if (!override) {
+          continue;
+        }
+        addEdgeAt(wrapper, 'value', index, nextRenderKey, override);
+        addParentEdge(override, nextRenderKey, wrapper);
+      }
+    }
+    return wrapper;
+  }
+
+  createPlacementWrapper(ctx?: Context, renderKey?: RenderKey): Rules {
+    const options = this._cloneOptionsForContext(ctx);
+    const location = Array.isArray(this.location) && this.location.length === 6
+      ? this.location as LocationInfo
+      : undefined;
+    const nextRenderKey = renderKey ?? EVAL;
+    const wrapper = new (this.constructor as typeof Rules)(
+      [],
+      options ? { ...options } : undefined,
+      location,
+      this.treeContext
+    );
+    const previousRenderKey = ctx?.renderKey;
+    if (ctx && this.renderKey !== CANONICAL) {
+      ctx.renderKey = this.renderKey;
+    }
+    try {
+      wrapper._setValueArray([...getChildren(this, ctx)] as Node[]);
+    } finally {
+      if (ctx) {
+        ctx.renderKey = previousRenderKey;
+      }
+    }
+    wrapper.inherit(this);
+    wrapper.renderKey = nextRenderKey;
+    const invocationBindings = this._cloneInvocationBindings();
+    if (invocationBindings) {
+      wrapper._invocationBindings = invocationBindings;
+    }
+    if (this.functionRegistry) {
+      wrapper.functionRegistry = this.functionRegistry.cloneForRules(wrapper);
+    }
+    wrapper._connectSharedChildren(wrapper.renderKey);
+    return wrapper;
+  }
+
+  createPlacementWrapperWithChildren(children: readonly Node[], renderKey: RenderKey = EVAL): Rules {
+    const options = this._cloneOptionsForContext(undefined);
+    const location = Array.isArray(this.location) && this.location.length === 6
+      ? this.location as LocationInfo
+      : undefined;
+    const wrapper = new (this.constructor as typeof Rules)(
+      [],
+      options ? { ...options } : undefined,
+      location,
+      this.treeContext
+    );
+    wrapper._setValueArray([...children] as Node[]);
+    wrapper.inherit(this);
+    wrapper.renderKey = renderKey;
+    const invocationBindings = this._cloneInvocationBindings();
+    if (invocationBindings) {
+      wrapper._invocationBindings = invocationBindings;
+    }
+    if (this.functionRegistry) {
+      wrapper.functionRegistry = this.functionRegistry.cloneForRules(wrapper);
+    }
+    wrapper._connectSharedChildren(wrapper.renderKey);
+    return wrapper;
+  }
+
+  withRenderOwner(
+    owner: Node,
+    renderKey?: RenderKey,
+    context?: Context
+  ): Rules {
+    let rules: Rules = this;
+    const effectiveRenderKey = renderKey ?? owner.renderKey;
+    if (effectiveRenderKey !== undefined && effectiveRenderKey !== CANONICAL && rules.renderKey === CANONICAL) {
+      const existing = ((owner as unknown as Record<string, unknown>).rulesEdge as Map<RenderKey, Rules> | undefined)
+        ?.get(effectiveRenderKey);
+      if (existing) {
+        rules = existing;
+      } else {
+        const wrapped = rules.createShallowBodyWrapper(undefined, effectiveRenderKey);
+        wrapped.parent = owner;
+        addEdge(owner, 'rules', effectiveRenderKey, wrapped);
+        if (owner.renderKey === effectiveRenderKey) {
+          (owner as unknown as { rules: Rules }).rules = wrapped;
+        }
+        rules = wrapped;
+      }
+    }
+    if (context && getCurrentParentNode(rules, context) !== owner) {
+      owner.adopt(rules, context);
+    }
+    return rules;
+  }
+
+  constructor(
+    value: readonly Node[],
+    options?: RulesOptions & NodeOptions,
+    location?: OptionalLocation,
+    context?: Context | TreeContext
+  ) {
+    const treeContext = context instanceof Context
+      ? context.treeContext
+      : context;
+    const ctx = context instanceof Context
+      ? context
+      : undefined;
+
+    let rulesVisibility = options?.rulesVisibility ?? {};
+    rulesVisibility.Declaration ??= 'public';
+    rulesVisibility.Ruleset ??= 'public';
+    rulesVisibility.VarDeclaration ??= 'public';
+    rulesVisibility.Mixin ??= 'public';
+    const mergedOptions = { ...options, rulesVisibility };
+    const normalized = (value ?? []) as Node[];
+    super(normalized, mergedOptions, location, treeContext);
+    this._setValueArray(normalized);
+    for (const child of normalized) {
+      if (child instanceof Node) {
+        this.adopt(child, ctx);
+        this.registerNode(child);
+      }
+    }
+    this.allowRoot = true;
+    this.allowRuleRoot = true;
+  }
+
+  setInvocationBinding(name: string, binding: InvocationBinding): void {
+    (this._invocationBindings ??= new Map()).set(name, { ...binding });
+  }
+
+  getInvocationBinding(name: string, context?: Context): VarDeclaration | undefined {
+    const binding = this._invocationBindings?.get(name);
+    if (!binding) {
+      return undefined;
+    }
+    if (binding.declaration) {
+      return binding.declaration;
+    }
+    const bindingContext = context
+      ? {
+          ...context,
+          rulesContext: this,
+          renderKey: context.renderKey ?? this.renderKey
+        } as Context
+      : undefined;
+    const declaration = binding.factory
+      ? binding.factory(this, bindingContext)
+      : binding.template?.clone(false, undefined, bindingContext);
+    if (!declaration) {
+      return undefined;
+    }
+    declaration.renderKey = bindingContext?.renderKey ?? this.renderKey ?? declaration.renderKey;
+    if (bindingContext) {
+      setParent(declaration, this, bindingContext);
+    } else {
+      declaration.parent = this;
+    }
+    binding.declaration = declaration;
+    return declaration;
+  }
+
+  * [Symbol.iterator]() {
+    let value = this.value;
+    /**
+     * This should always be the case? But at one point something somewhere
+     * set the value to undefined I think, so just leaving this defensively.
+     */
+    if (isArray(value)) {
+      yield* value.entries();
+    }
+  }
+
+  private _getRenderVisibleChildAt(index: number, _context?: Context): Node | undefined {
+    const canonical = this.value[index];
+    if (this.renderKey === CANONICAL) {
+      return canonical;
+    }
+
+    const cursor = { node: this as Node, renderKey: this.renderKey };
+    const existing = getEdgeAt(cursor, 'value', index)?.node;
+    if (existing) {
+      return existing;
+    }
+
+    return canonical;
+  }
+
+  private _getRenderChildren(context?: Context): readonly Node[] {
+    return this._withOwnRenderKey(context, () => {
+      if (this.renderKey === CANONICAL) {
+        return context ? getChildren(this, context) : this.value;
+      }
+
+      const children: Node[] = [];
+      for (let i = 0; i < this.value.length; i++) {
+        const child = this._getRenderVisibleChildAt(i, context);
+        if (child) {
+          children.push(child);
+        }
+      }
+      return children;
+    });
+  }
+
+  getRegistryChildren(context?: Context): readonly Node[] {
+    return this._getRenderChildren(context);
+  }
+
+  ensureCurrentRenderRulesRegistered(context?: Context): void {
+    const currentRenderRules = this
+      .getRegistryChildren(context)
+      .filter((child): child is Rules => isNode(child, N.Rules));
+
+    for (let i = this.rulesSet.length; i < currentRenderRules.length; i++) {
+      this.registerNode(currentRenderRules[i]!, undefined, context);
+    }
+  }
+
+  private _setChildren(value: readonly Node[], context?: Context, markDirty: boolean = true): void {
+    if (context) {
+      setChildren(this, value, context, { markDirty });
+      return;
+    }
+    const nextValue = [...value];
+    this._setValueArray(nextValue);
+    for (const child of nextValue) {
+      this.adopt(child);
+    }
+  }
+
+  private _setChildAt(index: number, node: Node, context?: Context, markDirty: boolean = true): void {
+    if (context) {
+      setChildAt(this, index, node, context, { markDirty });
+      return;
+    }
+    const nextValue = [...this.value];
+    nextValue[index] = node;
+    this._setValueArray(nextValue);
+    this.adopt(node);
+  }
+
+  /**
+   * Used by Ruleset, Mixins, and AtRules etc to render
+   * rules with braces.
+   */
+  toBraced(options?: PrintOptions) {
+    let opts = getPrintOptions(options);
+    // Use options.depth if provided, otherwise calculate from frameState
+    const depth = opts.depth!;
+    const w = opts.writer!;
+    const mark = w.mark();
+    let space = ''.padStart(depth * 2);
+    return this._withOwnRenderKey(opts.context, () => {
+      w.add('{');
+      // Children render one level deeper inside braces.
+      const childOptions = { ...opts, depth: depth + 1 };
+      childOptions.writer!.add('\n');
+      Rules.prototype.toTrimmedString.call(this, childOptions);
+      // ensure closing brace is on its own properly indented line
+      w.add('\n');
+      if (depth !== 0) {
+        w.add(space);
+      }
+      w.add('}');
+      // At root level (depth === 0), don't add a newline after the closing brace
+      // The parent _emitRulesBody will add the newline before the next item
+      // For nested rules (depth > 0), the newline is handled by the parent's _emitRulesBody
+      return w.getSince(mark);
+    });
+  }
+
+  override toTrimmedString(options?: PrintOptions) {
+    options = getPrintOptions(options);
+    const w = options.writer!;
+    const mark = w.mark();
+    const ctx = options.context;
+    return this._withOwnRenderKey(ctx, () => {
+      const depth = options.depth ?? 0;
+      const space = indent(depth);
+      const value = this._getRenderChildren(options.context);
+      const referenceMode = Boolean(options.referenceMode);
+      const referenceRenderEnabled = referenceMode ? Boolean(options.referenceRenderEnabled) : true;
+      const items = value.filter(n => isVisibleInContext(n, options.context));
+
+      const isInlineSourceRules = (node: Node): boolean => {
+        if (node.type !== 'Rules') {
+          return false;
+        }
+        const rulesNode = node as Rules;
+        const rulesValue = rulesNode._getRenderChildren(options.context);
+        if (rulesValue.length !== 1) {
+          return false;
+        }
+        const only = rulesValue[0]!;
+        return only.type === 'Any' && (only as Any).role === 'any';
+      };
+
+      let emittedCount = 0;
+      let lastEmittedType: string | undefined;
+      let lastEmittedWasInlineSourceRules = false;
+      for (const n of items) {
+        const isContainer = n.type === 'Ruleset' || n.type === 'AtRule' || n.type === 'Rules';
+        if (referenceMode && !referenceRenderEnabled && !isContainer) {
+          continue;
+        }
+        if (emittedCount > 0) {
+          const currentBuffer = w.getSince(0);
+          const bufferEndsWithNewline = currentBuffer.endsWith('\n');
+          const needsInlineBoundarySpacing = (
+            (lastEmittedType === 'Any' && n.type !== 'Any')
+            || (lastEmittedWasInlineSourceRules && n.type !== 'Any')
+          );
+          if (!bufferEndsWithNewline || needsInlineBoundarySpacing) {
+            w.add('\n');
+          }
+        }
+
+        const isChildRules = n.type === 'Rules';
+        const isRulesetOrAtRule = n.type === 'Ruleset' || n.type === 'AtRule';
+        if (!isChildRules && !isRulesetOrAtRule && depth !== 0) {
+          w.add(space);
+        }
+
+        let childOptions = { ...options, depth };
+        if (isChildRules) {
+          if (referenceMode && referenceRenderEnabled) {
+            childOptions = {
+              ...childOptions,
+              referenceMode: false,
+              referenceRenderEnabled: true
+            };
+          } else {
+            const ownReferenceMode = (n.options as any)?.referenceMode === true;
+            const childReferenceMode = referenceMode || ownReferenceMode;
+            const enteringReferenceMode = !referenceMode && ownReferenceMode;
+            const ownReferenceRenderOnExtend = (n.options as RulesOptions | undefined)?.referenceRenderOnExtend !== false;
+            const childReferenceRenderOnExtend = childReferenceMode
+              ? (enteringReferenceMode ? ownReferenceRenderOnExtend : options.referenceRenderOnExtend !== false)
+              : true;
+            const childReferenceRenderEnabled = childReferenceMode
+              ? (enteringReferenceMode ? false : referenceRenderEnabled)
+              : true;
+            childOptions = {
+              ...childOptions,
+              referenceMode: childReferenceMode,
+              referenceRenderEnabled: childReferenceRenderEnabled,
+              referenceRenderOnExtend: childReferenceRenderOnExtend
+            };
+          }
+        } else if (
+          referenceMode
+          && referenceRenderEnabled
+          && isRulesetOrAtRule
+        ) {
+          const keepReferenceFiltering = (
+            isNode(n, N.Ruleset)
+            && (() => {
+              const ownSelector = (n as Ruleset).getOwnSelector();
+              return Boolean(
+                ownSelector
+                && !(ownSelector instanceof Nil)
+                && isBareAmpersandOwnSelector(ownSelector)
+              );
+            })()
+          );
+          childOptions = {
+            ...childOptions,
+            referenceMode: keepReferenceFiltering,
+            referenceRenderEnabled: true
+          };
+        }
+
+        const rule = w.capture(() => n.toTrimmedString(childOptions));
+        if (!rule && isContainer) {
+          continue;
+        }
+        w.add(rule, n);
+        const needsSemi = isNode(n, N.Declaration | N.VarDeclaration)
+          ? (n as Declaration).requiresSemi(childOptions.context)
+          : (n as Node).requiredSemi;
+        if (needsSemi && n.options.semi !== false) {
+          w.add(';', n);
+        }
+        emittedCount++;
+        lastEmittedType = n.type;
+        lastEmittedWasInlineSourceRules = isInlineSourceRules(n);
+      }
+      return w.getSince(mark);
+    });
+  }
+
+  /** All rules, with nested rules flattened */
+  flatRules(visibleOnly: boolean = false, context?: Context, positionMap?: WeakMap<Node, FlatRulePosition>) {
+    const finalRules: Node[] = [];
+    const iterateRules = (
+      rules: Rules,
+      inheritedRenderKey?: RenderKey
+    ) => {
+      type DeferredEntry =
+        | {
+          kind: 'node';
+          node: Node;
+          renderKey?: RenderKey;
+        }
+        | {
+          kind: 'flatten';
+          rules: Rules;
+          inheritedRenderKey?: RenderKey;
+        };
+      const renderKey = rules.renderKey ?? inheritedRenderKey;
+      const scopedContext = context
+        ? (
+            renderKey !== undefined
+            && context.renderKey !== renderKey
+              ? { ...context, renderKey, rulesContext: rules } as Context
+              : (context.rulesContext !== rules
+                  ? { ...context, rulesContext: rules } as Context
+                  : context)
+          )
+        : undefined;
+      const pendingDescendants: DeferredEntry[] = [];
+      let hasEmittedLocalNonContainer = false;
+      const emitNode = (node: Node, nodeRenderKey?: RenderKey): void => {
+        if (positionMap && nodeRenderKey !== CANONICAL && nodeRenderKey !== undefined) {
+          positionMap.set(node, { renderKey: nodeRenderKey });
+        }
+        if (!isNode(node, N.Ruleset | N.AtRule | N.Rules)) {
+          hasEmittedLocalNonContainer = true;
+        }
+        finalRules.push(node);
+      };
+      const flushPendingDescendants = (): void => {
+        for (const entry of pendingDescendants) {
+          if (entry.kind === 'flatten') {
+            iterateRules(entry.rules, entry.inheritedRenderKey);
+            continue;
+          }
+          emitNode(entry.node, entry.renderKey);
+        }
+        pendingDescendants.length = 0;
+      };
+
+      for (let n of rules._getRenderChildren(scopedContext)) {
+        if (isNode(n, N.Rules)) {
+          if ((n.options as RulesOptions)?.referenceMode === true) {
+            flushPendingDescendants();
+            emitNode(
+              n,
+              (n as Rules).renderKey ?? renderKey
+            );
+          } else {
+            if (pendingDescendants.length > 0 && !hasEmittedLocalNonContainer) {
+              pendingDescendants.push({
+                kind: 'flatten',
+                rules: n as Rules,
+                inheritedRenderKey: renderKey
+              });
+            } else {
+              iterateRules(n, renderKey);
+            }
+          }
+          continue;
+        }
+        if (
+          visibleOnly
+          && isNode(n, N.Ruleset)
+          && !isVisibleInContext(n, scopedContext)
+          && !n.fullRender
+        ) {
+          pendingDescendants.push({
+            kind: 'flatten',
+            rules: (n as Ruleset).enterRules(scopedContext),
+            inheritedRenderKey: renderKey
+          });
+          continue;
+        }
+        if (!visibleOnly || isVisibleInContext(n, scopedContext) || n.fullRender) {
+          if (isNode(n, N.Ruleset)) {
+            pendingDescendants.push({
+              kind: 'node',
+              node: n,
+              renderKey
+            });
+          } else if (isNode(n, N.AtRule)) {
+            flushPendingDescendants();
+            emitNode(n, renderKey);
+          } else {
+            emitNode(n, renderKey);
+          }
+        }
+      }
+
+      flushPendingDescendants();
+    };
+    iterateRules(this);
+    return finalRules;
+  }
+
+  visibleRules(context?: Context) {
+    return this._getRenderChildren(context).filter(n => isVisibleInContext(n, context));
+  }
+
+  /**
+   * Return an object representation of a ruleset
+   */
+  toObject(convertToPrimitives: true, context?: Context): Record<string, string | number | boolean>;
+  toObject(convertToPrimitives: false, context?: Context): Record<string, Node>;
+  toObject(convertToPrimitives?: boolean, context?: Context): Record<string, string | number  | boolean | Node>;
+  toObject(convertToPrimitives: boolean = true, context?: Context): Record<string, string | number | boolean | Node> {
+    let output = new Map<string, boolean | string | number | Node>();
+    const iterateRules = (rules: Rules) => {
+      for (let n of rules._getRenderChildren(context)) {
+        if (isNode(n, N.Declaration)) {
+          let { name, value, important } = n as any;
+          if (convertToPrimitives) {
+            let primitive = value.valueOf();
+            let outputValue = important ? `${primitive} ${important}` : primitive;
+            if (outputValue === undefined) {
+              continue;
+            }
+            output.set(name.toString(), outputValue);
+          } else {
+            let outputValue = important ? new Sequence([n, important]) : n;
+            output.set(name.toString(), outputValue);
+          }
+        } else if (n instanceof Rules) {
+          iterateRules(n);
+        }
+      }
+    };
+    iterateRules(this as unknown as Rules);
+    return Object.fromEntries(output);
+  }
+
+  /** @todo - Refactor? */
+  _rulesSet: RulesEntry[] | undefined;
+  get rulesSet(): RulesEntry[] {
+    return (this._rulesSet ??= []);
+  }
+
+  registerNode(node: Node, options?: Record<string, any>, context?: Context) {
+    if (isNode(node, N.Rules)) {
+      const nodeOptions = (node as Rules).options;
+      // Use options if provided, otherwise use node's settings, otherwise empty
+      // Then merge with node's settings to preserve any values not in options
+      let optionsVisibility = options?.rulesVisibility;
+      let nodeVisibility = nodeOptions.rulesVisibility ?? {};
+      let rulesVisibility = optionsVisibility
+        ? { ...nodeVisibility, ...optionsVisibility }
+        : nodeVisibility;
+
+      /** Only Declaration and Ruleset are public by default.
+       * VarDeclaration visibility should be set by the parser (optional for Less, private for Jess/Sass).
+       * Mixin visibility should be set by the parser.
+       */
+      rulesVisibility.Declaration ??= 'public';
+      rulesVisibility.Ruleset ??= 'public';
+      rulesVisibility.Mixin ??= 'public';
+
+      /** Either one set as readonly will win */
+      let readonly = Boolean(options?.readonly || nodeOptions.readonly);
+      this.rulesSet.push({
+        node,
+        rulesVisibility,
+        readonly
+      });
+
+      // Note: Rulesets from imported Rules are registered in treeRoot's registry
+      // after evaluation completes (in evalNode), when treeRoot is guaranteed to be set
+    } else if (isNode(node, N.Declaration)) {
+      /**
+       * setDefined works like Sass's !default flag - it finds the original variable
+       * declaration and inserts a new declaration at the same rules level as the
+       * found variable, but before the current nested node.
+       */
+      if (node.options?.setDefined && context) {
+        const key = (node as any).name?.toString();
+        const sourceNode = node.sourceNode ?? node;
+        let opts: Registries.FindOptions = {};
+        opts.searchParents = true;
+        opts.context = context;
+        opts.start = undefined;
+        // Exclude the current declaration by source identity so a derived eval node
+        // cannot resolve its own canonical registry entry as the "existing" declaration.
+        opts.filter = (n: Node) => (n.sourceNode ?? n) !== sourceNode;
+        let result = this.find('declaration', key, node.type as 'VarDeclaration' | 'Declaration', opts);
+        if (result) {
+          if (result.options?.readonly || opts.readonly) {
+            throw new ReferenceError(`"${key}" is readonly`);
+          }
+
+          // Find the Rules node that contains the found declaration
+          let foundRules = getCurrentParentNode(result, context) as Rules | undefined;
+
+          if (!foundRules) {
+            throw new Error(`Could not find parent Rules for declaration '${key}'`);
+          }
+
+          // Create a new declaration with the same name but our value
+          const newDeclaration = node.copy();
+          newDeclaration.options = { ...newDeclaration.options };
+          newDeclaration.options.setDefined = undefined; // Remove setDefined flag
+
+          // Adopt the new declaration to the found Rules
+          foundRules.adopt(newDeclaration);
+
+          // Add to the value array AFTER the found declaration
+          // This ensures it shadows the original and is evaluated after it
+          const foundIndex = foundRules.value.indexOf(result);
+          if (foundIndex !== -1) {
+            if (context) {
+              foundRules.splice(context, foundIndex + 1, 0, newDeclaration);
+            } else {
+              foundRules.splice(foundIndex + 1, 0, newDeclaration);
+            }
+          } else {
+            // If not found in array, add at the beginning
+            if (context) {
+              foundRules.unshift(context, newDeclaration);
+            } else {
+              foundRules.unshift(newDeclaration);
+            }
+          }
+
+          // Register it via registerNode to ensure it's properly indexed
+          // Note: registerNode will call register('declaration', ...) which adds to registry
+          // We skip setDefined processing since we already removed the flag
+          foundRules.registerNode(newDeclaration, undefined, context);
+        } else {
+          throw new ReferenceError(`"${key}" is not defined`);
+        }
+      }
+
+      this.register('declaration', node, context);
+    } else if (isNode(node, N.Ruleset)) {
+      // Register to 'mixin' for mixin calls
+      // Always register - guard filtering happens at call time in getFunctionFromMixins
+      // Note: 'ruleset' registration for extends now happens in Ruleset.preEval to the extend root's registry
+      this.register('mixin', node, context);
+    } else if (isNode(node, N.Mixin)) {
+      this.register('mixin', node, context);
+    } else if (isNode(node, N.Func)) {
+      this.register('function', node, context);
+    }
+  }
+
+  override push(...nodes: Node[]): void;
+  override push(ctx: Context, ...nodes: Node[]): void;
+  override push(...args: [Context, ...Node[]] | Node[]): void {
+    const hasCtx = args.length > 0 && args[0] instanceof Context;
+    const ctx = hasCtx ? args[0] as Context : undefined;
+    const nodes = (hasCtx ? args.slice(1) : args) as Node[];
+    // Route through _getChildren/_setChildren overlay when context is active
+    if (ctx) {
+      const nextValue = [...this._getRenderChildren(ctx)];
+      for (const node of nodes) {
+        this.adopt(node, ctx);
+        nextValue.push(node);
+      }
+      this._setChildren(nextValue, ctx);
+      for (const node of nodes) {
+        this.registerNode(node, undefined, ctx);
+      }
+      return;
+    }
+    this._setValueArray([...this.value]);
+    for (const node of nodes) {
+      this.adopt(node, ctx);
+      (this.value as Node[]).push(node);
+      this.registerNode(node, undefined, ctx);
+    }
+  }
+
+  override splice(start: number, deleteCount: number, ...items: Node[]): Node[];
+  override splice(ctx: Context, start: number, deleteCount: number, ...items: Node[]): Node[];
+  override splice(...args: [Context, number, number, ...Node[]] | [number, number, ...Node[]]): Node[] {
+    const hasCtx = args[0] instanceof Context;
+    const ctx = hasCtx ? args[0] as Context : undefined;
+    const [start, deleteCount, ...items] = (hasCtx ? args.slice(1) : args) as [number, number, ...Node[]];
+    // Route through overlay when context is active
+    if (ctx) {
+      const nextValue = [...this._getRenderChildren(ctx)];
+      const removed = nextValue.splice(start, deleteCount, ...items);
+      for (const item of items) {
+        if (item instanceof Node) {
+          this.adopt(item, ctx);
+        }
+      }
+      this._setChildren(nextValue, ctx);
+      for (const item of items) {
+        if (item instanceof Node) {
+          this.registerNode(item, undefined, ctx);
+        }
+      }
+      (this as unknown as { _invalidateValueOf: () => void })._invalidateValueOf();
+      return removed as Node[];
+    }
+    const nextValue = [...this.value];
+    const removed = nextValue.splice(start, deleteCount, ...items);
+    this._setValueArray(nextValue);
+    for (const item of items) {
+      if (item instanceof Node) {
+        this.adopt(item, ctx);
+        this.registerNode(item, undefined, ctx);
+      }
+    }
+    (this as unknown as { _invalidateValueOf: () => void })._invalidateValueOf();
+    return removed as Node[];
+  }
+
+  override unshift(...items: Node[]): void;
+  override unshift(ctx: Context, ...items: Node[]): void;
+  override unshift(...args: [Context, ...Node[]] | Node[]): void {
+    const hasCtx = args.length > 0 && args[0] instanceof Context;
+    const ctx = hasCtx ? args[0] as Context : undefined;
+    const items = (hasCtx ? args.slice(1) : args) as Node[];
+    // Route through overlay when context is active
+    if (ctx) {
+      for (const item of items) {
+        if (item instanceof Node) {
+          this.adopt(item, ctx);
+        }
+      }
+      this._setChildren([...items, ...this._getRenderChildren(ctx)], ctx);
+      for (const item of items) {
+        if (item instanceof Node) {
+          this.registerNode(item, undefined, ctx);
+        }
+      }
+      (this as unknown as { _invalidateValueOf: () => void })._invalidateValueOf();
+      return;
+    }
+    this._setValueArray([...this.value]);
+    (this.value as Node[]).unshift(...items);
+    for (const item of items) {
+      if (item instanceof Node) {
+        this.adopt(item, ctx);
+        this.registerNode(item, undefined, ctx);
+      }
+    }
+    (this as unknown as { _invalidateValueOf: () => void })._invalidateValueOf();
+  }
+
+  at(index: number, context?: Context) {
+    return atIndex(this._getRenderChildren(context), index);
+  }
+
+  /**
+   * This traverses deeply to visit all nodes, but indexes locally.
+   */
+  override preEval(context: Context) {
+    if (!this.preEvaluated) {
+      context.depth++;
+      let rules = this;
+      // When this is the nestable at-rule wrapper (one child Ruleset(&)), do not clone so
+      // inner rulesets register to the same object we push and register as extend root.
+      const nestableAtRuleNames = new Set(['@media', '@supports', '@layer', '@container', '@scope']);
+      const activeParent = getCurrentParentNode(this, context);
+      const sourceParent = getSourceParent(this, context);
+      const parentAtRule = activeParent?.type === 'AtRule'
+        ? activeParent
+        : (sourceParent?.type === 'AtRule' ? sourceParent : null);
+      const isNestableAtRuleBody =
+        parentAtRule
+        && nestableAtRuleNames.has(String((parentAtRule as any).name?.valueOf?.() ?? ''));
+      const children = rules._getRenderChildren(context);
+      const first = children[0];
+      const isWrapper =
+        isNestableAtRuleBody
+        && children.length === 1
+        && isNode(first, N.Ruleset)
+        && isNode((first as Ruleset).get('selector'), N.Ampersand);
+      if (isWrapper) {
+        rules = this;
+      }
+      rules.preEvaluated = true;
+      // Save current context and set up new context for variable lookups during preEval
+      const saved = this._snapshotContext(context);
+      this._setupContextForRules(context, rules);
+
+      // Set context.root early if this is the main root
+      const isMainRoot = !context.root;
+      if (isMainRoot) {
+        context.root = rules;
+      }
+
+      /**
+       * I think maybe we can just set the index to the actual order?
+       */
+      for (let i = 0; i < children.length; i++) {
+        let n = children[i]!;
+        setIndex(n, i, context);
+      }
+      // Preserve parent when cloning - if this Rules is inside a ruleset, maintain the parent relationship
+      const parent = getCurrentParentNode(this, context);
+      if (parent && !getCurrentParentNode(rules, context)) {
+        parent.adopt(rules, context);
+      }
+
+      // Set context.root if not already set (needed for preEval visitors)
+      if (!context.root) {
+        context.root = rules;
+      }
+      // When getTree() set context.root to the original Rules but we're processing a clone,
+      // use the clone as context.root so registerRoot/pushExtendRoot run and rulesets register to the clone (extend fix).
+      if (context.root === this && this !== rules) {
+        context.root = rules;
+      }
+
+      // Register main root as extend root if this is the root (needed for extends in preEval)
+      // Check rules === context.root at registration time (not using stale isMainRoot)
+      if (rules === context.root && !context.extendRoots.root) {
+        context.extendRoots.registerRoot(rules);
+        context.extendRoots.pushExtendRoot(rules);
+      }
+
+      // Always push nestable at-rule body so inner rulesets register to it (not document root).
+      // Needed for both: wrapper (collapseNesting) and direct body (collapseNesting: false).
+      if (isNestableAtRuleBody) {
+        context.extendRoots.pushExtendRoot(rules);
+      }
+
+      // Multi-pass registration system for handling interpolated names
+      const mp = this._multiPassPreEval(rules, context, saved);
+      const popNestableBody = () => {
+        if (isNestableAtRuleBody) {
+          context.extendRoots.popExtendRoot();
+        }
+      };
+      if (isThenable(mp)) {
+        return (mp as Promise<this>).then((result) => {
+          popNestableBody();
+          return result;
+        });
+      }
+      popNestableBody();
+      return mp;
+    }
+    return this;
+  }
+
+  /**
+   * Multi-pass preEval system to handle interpolated names and dependencies
+   */
+  private _multiPassPreEval(rules: Rules, context: Context, saved: any): MaybePromise<this> {
+    // First pass: Only register nodes with static names
+    const staticNodes: Node[] = [];
+    const dynamicNodes: Node[] = [];
+
+    // Process each node with static name, handling both sync and async preEval
+    const processResult = serialForEach(rules._getRenderChildren(context), (node, index) => {
+      // Check if node has a static name (can be registered immediately)
+      if (node.type === 'Any' && (node as any).role === 'charset') {
+        /** Special case where we register the charset node immediately */
+        const charsetNode = (node as Any).preEval(context);
+        rules._setChildAt(index, charsetNode, context, false);
+        rules.adopt(charsetNode, context);
+        return;
+      }
+      // Nodes that don't register by name (Call, Expression, etc.) skip
+      // both preEval and dynamic resolution — they're handled by the eval queue.
+      if (!this._isRegisterableType(node)) {
+        setIndex(node, index, context);
+        return;
+      }
+      if (this._hasStaticName(node, context)) {
+        // Pre-evaluate nodes with static names before registration
+        // This ensures selectors are evaluated and keySets are available for rulesets
+        const preEvald = node.preEval(context);
+        if (isThenable(preEvald)) {
+          return (preEvald as Promise<Node>).then((preEvaldNode) => {
+            rules._setChildAt(index, preEvaldNode, context, false);
+            rules.adopt(preEvaldNode, context);
+            setIndex(preEvaldNode as Node, index, context);
+            // After async preEval, check if it still has a static name
+            if (this._hasStaticName(preEvaldNode, context)) {
+              staticNodes.push(preEvaldNode);
+              this._registerNodeIfEligible(rules, preEvaldNode, context);
+            } else {
+              dynamicNodes.push(preEvaldNode);
+            }
+          });
+        }
+        rules._setChildAt(index, preEvald as Node, context, false);
+        rules.adopt(preEvald as Node, context);
+        setIndex(preEvald as Node, index, context);
+        const nodeToRegister = preEvald as Node;
+        staticNodes.push(nodeToRegister);
+        this._registerNodeIfEligible(rules, nodeToRegister, context);
+      } else {
+        dynamicNodes.push(node);
+      }
+    });
+
+    const finish = () => {
+      // If no dynamic nodes, we're done
+      if (dynamicNodes.length === 0) {
+        // Restore context after preEval is complete
+        context.rulesContext = saved.rulesContext;
+        context.renderKey = saved.renderKey;
+        context.treeRoot = saved.treeRoot;
+        // Only restore context.root if saved.root is defined (not the outermost root)
+        // If saved.root is undefined, it means we're at the outermost level, so keep context.root as is
+        if (saved.root !== undefined) {
+          context.root = saved.root;
+        }
+        return rules as this;
+      }
+      // Multi-pass resolution of dynamic nodes
+      return this._resolveDynamicNodes(rules, context, saved, dynamicNodes);
+    };
+
+    if (isThenable(processResult)) {
+      return (processResult as Promise<void>).then(() => finish());
+    }
+    return finish();
+  }
+
+  /**
+   * Helper to check if a value is static (either a Node with F_STATIC flag or a primitive value)
+   */
+  private _isStatic(value: any): boolean {
+    if (value && typeof value.hasFlag === 'function') {
+      return value.hasFlag(F_STATIC);
+    }
+    // Primitive values (strings, numbers, etc.) are considered static
+    return true;
+  }
+
+  /**
+   * Check if a node type participates in name-based registration.
+   * Only these node types have names/selectors that _resolveDynamicNodes
+   * needs to resolve. Everything else (Call, Expression, Comment, etc.)
+   * goes straight to the eval queue without preEval.
+   */
+  private _isRegisterableType(node: Node): boolean {
+    return isNode(node, N.VarDeclaration | N.Declaration | N.Mixin | N.Ruleset) || (node as Node).type === 'StyleImport';
+  }
+
+  /**
+   * Check if a node has a static name that can be registered immediately
+   */
+  private _hasStaticName(node: Node, context?: Context): boolean {
+    if (isNode(node, N.VarDeclaration)) {
+      return this._isStatic(node.get('name'));
+    }
+    if (isNode(node, N.Mixin)) {
+      // Check position-patched name: preEval may have resolved an interpolated name
+      const name = node.get('name', context);
+      return this._isStatic(name);
+    }
+    if (isNode(node, N.Declaration)) {
+      return this._isStatic(node.get('name'));
+    }
+    if (node.type === 'StyleImport') {
+      return this._isStatic((node as Node & { path: unknown }).path);
+    }
+    if (isNode(node, N.Ruleset)) {
+      const selector: Node = (node as Ruleset).get('selector');
+      if (isNode(selector, N.BasicSelector | N.CompoundSelector | N.ComplexSelector | N.SelectorList | N.Nil)) {
+        return true;
+      }
+      if (context && isPreEvaluated(node, context)) {
+        return true;
+      }
+      return (selector as Node).hasFlag(F_STATIC);
+    }
+    return node.hasFlag(F_STATIC);
+  }
+
+  /**
+   * Register a node if it's eligible for registration
+   */
+  private _registerNodeIfEligible(rules: Rules, node: Node, context: Context) {
+    if (isNode(node, N.Declaration)) {
+      rules.registerNode(node, undefined, context);
+    } else if (isNode(node, N.Mixin)) {
+      rules.registerNode(node, undefined, context);
+    } else if (isNode(node, N.Ruleset)) {
+      // registerNode handles both 'mixin' and 'ruleset' registries
+      rules.registerNode(node, undefined, context);
+    }
+  }
+
+  /**
+   * Multi-pass resolution of dynamic nodes with interpolated names
+   */
+  private _resolveDynamicNodes(rules: Rules, context: Context, saved: any, dynamicNodes: Node[]): MaybePromise<this> {
+    const resolvedNodes: Node[] = [];
+
+    const handleResolvedNode = (resolvedNode: Node, node: Node, stillUnresolved: Node[]): boolean => {
+      if (resolvedNode.index === undefined) {
+        resolvedNode.index = node.index;
+      }
+      if (!resolvedNode.sourceNode) {
+        resolvedNode.sourceNode = node.sourceNode ?? node;
+      }
+      if (resolvedNode.type === 'Ruleset') {
+        rules.registerNode(resolvedNode, undefined, context);
+      }
+      if (isNode(resolvedNode, N.Nil) || this._hasStaticName(resolvedNode, context)) {
+        resolvedNodes.push(resolvedNode);
+        this._registerNodeIfEligible(rules, resolvedNode, context);
+        return true; // made progress
+      } else {
+        stillUnresolved.push(resolvedNode);
+        return false;
+      }
+    };
+
+    const applyResolvedNodes = () => {
+      const children = rules._getRenderChildren(context);
+      for (let i = 0; i < children.length; i++) {
+        const node = children[i]!;
+        const nodeIdx = getIndex(node, context);
+        const resolvedNode = resolvedNodes.find(n => getIndex(n, context) === nodeIdx);
+        if (resolvedNode && resolvedNode !== node) {
+          rules._setChildAt(i, resolvedNode.inherit(node), context, false);
+          rules.adopt(resolvedNode, context);
+        }
+      }
+    };
+
+    const finishResolution = (): this => {
+      applyResolvedNodes();
+      context.rulesContext = saved.rulesContext;
+      context.renderKey = saved.renderKey;
+      context.treeRoot = saved.treeRoot;
+      if (saved.root !== undefined) {
+        context.root = saved.root;
+      }
+      return rules as this;
+    };
+
+    // Separate declarations (whose dynamic names might depend on each other)
+    // from non-declarations (which depend on declaration VALUES, not names,
+    // so retrying during preEval won't help).
+    const isDeclarationType = (n: Node) =>
+      isNode(n, N.VarDeclaration) || isNode(n, N.Declaration);
+
+    const dynamicDeclarations: Node[] = [];
+    const otherDynamic: Node[] = [];
+    for (const node of dynamicNodes) {
+      if (isDeclarationType(node)) {
+        dynamicDeclarations.push(node);
+      } else {
+        otherDynamic.push(node);
+      }
+    }
+
+    // Phase 1: Resolve declarations with dynamic names.
+    // Retry because one declaration's name might depend on another's being registered.
+    const MAX_DECL_RETRIES = 5;
+    let declRetries = 0;
+    const unresolvedDecls: Node[] = [...dynamicDeclarations];
+
+    const resolveDeclarations = (): MaybePromise<void> => {
+      declRetries++;
+      if (declRetries > MAX_DECL_RETRIES || unresolvedDecls.length === 0) {
+        return;
+      }
+      const stillUnresolved: Node[] = [];
+      let madeProgress = false;
+
+      for (let i = 0; i < unresolvedDecls.length; i++) {
+        const node = unresolvedDecls[i]!;
+        try {
+          const result = node.preEval(context);
+
+          if (isThenable(result)) {
+            const remaining = unresolvedDecls.slice(i + 1);
+            return (result as Promise<Node>).then((resolvedNode) => {
+              if (handleResolvedNode(resolvedNode, node, stillUnresolved)) {
+                madeProgress = true;
+              }
+              unresolvedDecls.length = 0;
+              unresolvedDecls.push(...stillUnresolved, ...remaining);
+              if (madeProgress && unresolvedDecls.length > 0) {
+                return resolveDeclarations();
+              }
+            });
+          }
+
+          if (handleResolvedNode(result as Node, node, stillUnresolved)) {
+            madeProgress = true;
+          }
+        } catch {
+          stillUnresolved.push(node);
+        }
+      }
+
+      if (madeProgress && stillUnresolved.length > 0) {
+        unresolvedDecls.length = 0;
+        unresolvedDecls.push(...stillUnresolved);
+        return resolveDeclarations();
+      }
+    };
+
+    // Phase 2: Try non-declarations once. Their interpolated names typically
+    // depend on declaration VALUES (e.g. @infix from breakpoint-infix()),
+    // which aren't evaluated until the eval phase. Retrying won't help.
+    const resolveOtherOnce = (): MaybePromise<void> => {
+      for (let i = 0; i < otherDynamic.length; i++) {
+        const node = otherDynamic[i]!;
+        try {
+          const result = node.preEval(context);
+
+          if (isThenable(result)) {
+            const remaining = otherDynamic.slice(i + 1);
+            return (result as Promise<Node>).then((resolvedNode) => {
+              handleResolvedNode(resolvedNode, node, []);
+              // Continue with remaining nodes
+              otherDynamic.length = 0;
+              otherDynamic.push(...remaining);
+              return resolveOtherOnce();
+            });
+          }
+
+          handleResolvedNode(result as Node, node, []);
+        } catch {
+          // Can't resolve during preEval — leave in place for eval phase
+        }
+      }
+    };
+
+    return pipe(
+      () => resolveDeclarations(),
+      () => {
+        applyResolvedNodes();
+        return resolveOtherOnce();
+      },
+      () => finishResolution()
+    );
+  }
+
+  /**
+   * Helper method to continue preEval'ing remaining children after an async preEval.
+   */
+  private _preEvalRemainingChildren(rules: Rules, context: Context, startIndex: number, saved?: any): MaybePromise<this> {
+    const children = rules._getRenderChildren(context);
+    for (let i = startIndex; i < children.length; i++) {
+      const node = children[i]!;
+
+      // Always call preEval to ensure deep traversal and name resolution
+      const result = node.preEval(context);
+      if (isThenable(result)) {
+        // Handle async preEval by returning a promise that resolves after all children
+        return result.then((resolvedNode) => {
+          // Update the node if preEval returned a different instance
+          if (resolvedNode !== node) {
+            rules._setChildAt(i, resolvedNode, context, false);
+            rules.adopt(resolvedNode, context);
+          }
+
+          // Register the node after preEval (name resolution) if not already registered
+          if (!isNode(node, N.VarDeclaration)) {
+            rules.registerNode(resolvedNode, undefined, context);
+          }
+
+          // Continue with the rest of the children
+          return this._preEvalRemainingChildren(rules, context, i + 1, saved);
+        });
+      }
+
+      // Update the node if preEval returned a different instance
+      if (result !== node) {
+        rules._setChildAt(i, result, context, false);
+        rules.adopt(result, context);
+      }
+
+      // Register the node after preEval (name resolution) if not already registered
+      if (!isNode(node, N.VarDeclaration)) {
+        rules.registerNode(result, undefined, context);
+      }
+    }
+
+    // Restore context after preEval is complete (for async case)
+    if (saved) {
+      context.rulesContext = saved.rulesContext;
+      context.renderKey = saved.renderKey;
+      context.treeRoot = saved.treeRoot;
+      // Only restore context.root if saved.root is defined (not the outermost root)
+      // If saved.root is undefined, it means we're at the outermost level, so keep context.root as is
+      if (saved.root !== undefined) {
+        context.root = saved.root;
+      }
+    }
+    return rules as this;
+  }
+
+  /** Save current context roots to restore later */
+  private _snapshotContext(context: Context) {
+    return {
+      rulesContext: context.rulesContext,
+      renderKey: context.renderKey,
+      treeContext: context.treeContext,
+      treeRoot: context.treeRoot,
+      root: context.root,
+      extendRootStackLength: context.extendRoots.extendRootStack.length
+    } as const;
+  }
+
+  /** Setup context for evaluating these rules */
+  private _setupContextForRules(context: Context, rules: Rules) {
+    const treeContext = context.treeContext;
+    // Only switch treeContext if the rules have one AND it's different
+    // Dynamically created Rules (e.g., mixin parameter wrappers) may not have treeContext
+    // and we don't want to lose leakyRules and other settings
+    // Check _meta.treeContext (private field) not treeContext (getter that lazily creates)
+    const rulesTreeContext = (rules as any)._meta?.treeContext as TreeContext | undefined;
+    if (rulesTreeContext && (!treeContext || treeContext !== rulesTreeContext)) {
+      context.allRoots.push(rules);
+      context.treeContext = rulesTreeContext;
+      context.treeRoot = rules;
+    }
+    // Always set root if not set - needed for extends to work with API-created Rules
+    context.root ??= rules;
+    context.rulesContext = rules;
+    if (rules.renderKey !== CANONICAL) {
+      context.renderKey = rules.renderKey;
+    }
+  }
+
+  /** Assign depth-first document order to every Ruleset under the given Rules (single walk, source order). */
+  private _assignDocumentOrderDepthFirst(
+    rules: Rules,
+    map: WeakMap<Ruleset, number>,
+    counter: { value: number },
+    context?: Context
+  ): void {
+    const value = rules._getRenderChildren(context);
+    if (!isArray(value)) {
+      return;
+    }
+    for (const node of value) {
+      if (isNode(node, N.Ruleset)) {
+        map.set(node as Ruleset, counter.value);
+        counter.value++;
+      }
+      const innerRules = (node as any).rules;
+      if (innerRules && isNode(innerRules, N.Rules)) {
+        this._assignDocumentOrderDepthFirst(innerRules as Rules, map, counter, context);
+      }
+    }
+  }
+
+  /** Build the evaluation queue partitioned by priority */
+  private _buildEvalQueue(rules: Rules, context: Context): EvalQueueMap {
+    let evalQueue: EvalQueueMap = new Map();
+    for (const item of rules._getRenderChildren(context).entries()) {
+      let [idx, rule] = item;
+      if (rule.index === undefined) {
+        rule.index = idx;
+      }
+      let priority = NodeTypeToPriority.get(rule.type) ?? Priority.None;
+      // Less variable-calls `@foo();` are parsed as Expression(Call(variable-ref)).
+      // We *selectively* boost only those calls that "unlock mixins" (i.e. calling a variable whose
+      // value is a detached ruleset containing mixin definitions). This avoids changing evaluation
+      // order for regular detached rulesets like `@ruleset()` used for property blocks.
+      if (priority === Priority.None && rules.treeContext?.leakyRules === true && isNode(rule, N.Expression)) {
+        const inner = (rule as any).value;
+        if (isNode(inner, N.Call) && isNode((inner as any).name, N.Reference)) {
+          const ref = (inner as any).name;
+          const refType = String(ref?.options?.type ?? '');
+          if (refType === 'variable') {
+            const raw = ref.key;
+            const keyStr = Array.isArray(raw) ? raw.join('') : String(raw?.valueOf?.() ?? raw ?? '');
+            // Only if variable exists and its value is a detached ruleset Mixin with nested Mixin definitions.
+            const decl = rules.find('declaration', keyStr, 'VarDeclaration', { context }) as any;
+            const val = decl?.value;
+            const hasNestedMixinDefinitions =
+              isNode(val, N.Mixin)
+              && isNode((val as any).rules, N.Rules)
+              && (val as any).rules._getRenderChildren(context).some((n: any) => n?.type === 'Mixin');
+            if (hasNestedMixinDefinitions) {
+              priority = Priority.High;
+            }
+          }
+        }
+      }
+      let queue = evalQueue.get(priority) ?? [];
+      queue.push(item as [number, Node]);
+      evalQueue.set(priority, queue);
+    }
+    return evalQueue;
+  }
+
+  /** Evaluate the built queues in priority order */
+  private _evaluateQueue(rules: Rules, evalQueue: EvalQueueMap, context: Context): MaybePromise<boolean> {
+    let rulesToHoist = false;
+    const scheduledPriority = new WeakMap<Node, Priority>();
+    const failuresByPriority = new WeakMap<Node, Map<Priority, number>>();
+
+    const priorities: Priority[] = Array.from({ length: Priority.Highest + 1 }).map((_, i) => (Priority.Highest - i) as Priority);
+    const runPriority = (p: Priority): MaybePromise<void> => {
+      const queue = evalQueue.get(p);
+      if (!queue) {
+        return;
+      }
+      const enqueueRetry = (priority: Priority, item: [number, Node], rule: Node): void => {
+        const retryQueue = evalQueue.get(priority) ?? [];
+        retryQueue.push(item);
+        evalQueue.set(priority, retryQueue);
+        scheduledPriority.set(rule, priority);
+      };
+      const countFailure = (rule: Node, priority: Priority): number => {
+        const byPriority = failuresByPriority.get(rule) ?? new Map<Priority, number>();
+        const nextCount = (byPriority.get(priority) ?? 0) + 1;
+        byPriority.set(priority, nextCount);
+        failuresByPriority.set(rule, byPriority);
+        return nextCount;
+      };
+      const runSingleEntry = (q: number): MaybePromise<void | undefined> => {
+        const [idx, rule] = queue[q]!;
+
+        /**
+         * Var declarations have late evaluation, so they are skipped.
+         * (Meaning: they are not evaluated until they are referenced.)
+         */
+        if (isNode(rule, N.VarDeclaration)) {
+          return;
+        }
+
+        // Skip stale entries for nodes that were re-queued to a different priority.
+        const expectedPriority = scheduledPriority.get(rule);
+        if (expectedPriority !== undefined && expectedPriority !== p) {
+          return;
+        }
+
+        const onEvalError = (error: unknown): Node | undefined => {
+          // Most node failures are semantic failures and should throw immediately.
+          // Retry scheduling is reserved for StyleImport ordering/interpolation cases.
+          if (rule.type !== 'StyleImport') {
+            throw error;
+          }
+          // Final pass: no retries remain.
+          if (p === Priority.None) {
+            throw error;
+          }
+
+          // Only retry when the import path itself couldn't be resolved
+          // (e.g. @import "@{theme}/file" where @theme isn't available yet).
+          // Path resolution is cheap (no cloning). Content evaluation errors
+          // (after cloning the import tree) are never retried — each retry
+          // would re-clone the entire tree, causing memory blowup.
+          const isPathError = error instanceof Error && (error as any)._isPathResolutionError;
+          if (!isPathError) {
+            throw error;
+          }
+
+          // Retry policy:
+          // 1) first failure at a priority -> retry once at same priority
+          // 2) second+ failure at that priority -> step down one level
+          const failures = countFailure(rule, p);
+          const nextPriority = failures === 1 ? p : (p - 1) as Priority;
+          enqueueRetry(nextPriority, [idx, rule], rule);
+          return;
+        };
+        const tryStepResult = (): MaybePromise<Node | undefined> => {
+          try {
+            const result = rule.eval(context);
+            if (isThenable(result)) {
+              return (result as Promise<Node>).catch(onEvalError);
+            }
+            return result as Node;
+          } catch (error) {
+            return onEvalError(error);
+          }
+        };
+        const stepResult = pipe(
+          tryStepResult,
+          (result: Node | undefined) => {
+            // Undefined means we re-queued this node for retry.
+            if (result === undefined) {
+              return;
+            }
+            scheduledPriority.delete(rule);
+            // Apply the result
+            if (result !== rule) {
+              rules._setChildAt(idx, result, context, false);
+              queue[q] = [idx, result];
+              // If a StyleImport evaluated to Rules, register them in the parent's _rulesSet
+              // so variables from the import can be found by the parent
+              // Also register Rules from Call results (mixin calls) in the same way
+              if (isNode(result, N.Rules)) {
+                // Set the index of the imported Rules to the StyleImport's index
+                // so we can compare Rules indices when determining which variable was declared later
+                setIndex(result, idx, context);
+                rules.adopt(result, context);
+                rules.registerNode(result, {
+                  rulesVisibility: result.options.rulesVisibility,
+                  readonly: result.options.readonly
+                }, context);
+                if (result.sourceNode?.type === 'StyleImport') {
+                  result.getRegistry('declaration')?.indexPendingItems();
+                  result.getRegistry('mixin')?.indexPendingItems();
+                }
+              } else {
+                // For non-Rules results, adopt them to set up parent chain
+                rules.adopt(result, context);
+              }
+            }
+            if (result.hoistToRoot) {
+              rulesToHoist = true;
+            }
+            return;
+          }
+        );
+        // If stepResult is a thenable, propagate any errors
+        if (isThenable(stepResult)) {
+          return stepResult;
+        }
+        return;
+      };
+      const runFromIndex = (q: number): MaybePromise<void> => {
+        if (q >= queue.length) {
+          return;
+        }
+        const step = runSingleEntry(q);
+        if (isThenable(step)) {
+          return (step as Promise<void>).then(() => runFromIndex(q + 1));
+        }
+        return runFromIndex(q + 1);
+      };
+      return runFromIndex(0);
+    };
+    const phaseRun = serialForEach(priorities, runPriority);
+
+    if (isThenable(phaseRun)) {
+      return (phaseRun as Promise<void>).then(() => {
+        return rulesToHoist;
+      }).catch((error) => {
+        throw error;
+      });
+    }
+    return rulesToHoist;
+  }
+
+  /**
+   * Coalesce assignment-normalized declaration chains in one stage after evaluation.
+   * This handles both in-scope merges and merges that span call-produced Rules blocks.
+   */
+  private _coalesceMergedDeclarations(rules: Rules, context?: Context): void {
+    const getDeclValue = (node: Declaration): Node => node.getCurrentValue(context);
+    const getDeclImportant = (node: Declaration): Node | undefined => node.getCurrentImportant(context);
+    const getDeclName = (node: Declaration): string => {
+      const name = node.getCurrentName(context);
+      return String(name?.valueOf?.() ?? name);
+    };
+    const getDeclAssign = (node: Declaration): string => {
+      const options = node.options;
+      return String(options?.normalizedFromAssign ?? '');
+    };
+    const setDeclValue = (node: Declaration, value: Node): void => {
+      node.setCurrentValue(value, context);
+    };
+    const setDeclImportant = (node: Declaration, value: Node | undefined): void => {
+      node.setCurrentImportant(value as Declaration['important'], context);
+    };
+    const removeVisibleFlag = (node: Node): void => {
+      if (context) {
+        node._removeFlag(F_VISIBLE, context);
+        return;
+      }
+      node.removeFlag(F_VISIBLE);
+    };
+    const isMergedAssign = (assign: unknown): boolean => (
+      assign === '+:' || assign === '&,:' || assign === '&_:'
+    );
+    const cloneMergeValuePart = (value: Node): Node => {
+      return context
+        ? value.clone(false, undefined, context)
+        : value.clone(false);
+    };
+    const collectAddMergeParts = (value: Node): Node[] => {
+      if (isNode(value, N.Nil)) {
+        return [];
+      }
+      if (isNode(value, N.List)) {
+        return value.get('value', context).map(part => cloneMergeValuePart(part as Node));
+      }
+      return [cloneMergeValuePart(value)];
+    };
+    const rebaseLinearMergedValue = (anchor: Declaration, value: Node, assign: string): Node | undefined => {
+      if (assign === '&_:') {
+        if (!isNode(value, N.Sequence)) {
+          return undefined;
+        }
+        const parts = value.get('value', context);
+        if (
+          parts.length < 2
+          || !isNode(parts[0]!, N.Reference)
+          || parts[0]!.options?.resolution !== 'linear'
+        ) {
+          return undefined;
+        }
+        return spaced([
+          getDeclValue(anchor),
+          ...parts.slice(1).map(part => cloneMergeValuePart(part as Node))
+        ]);
+      }
+      if (!isNode(value, N.List)) {
+        return undefined;
+      }
+      const parts = value.get('value', context);
+      if (
+        parts.length < 2
+        || !isNode(parts[0]!, N.Reference)
+        || parts[0]!.options?.resolution !== 'linear'
+      ) {
+        return undefined;
+      }
+      return new List([
+        getDeclValue(anchor),
+        ...parts.slice(1).map(part => cloneMergeValuePart(part as Node))
+      ]);
+    };
+    const appendMergedValue = (anchor: Declaration, value: Node, assign: string): Node => {
+      if (assign === '&_:') {
+        return isNode(value, N.Sequence)
+          ? spaced([getDeclValue(anchor), ...value.get('value', context).map(part => cloneMergeValuePart(part as Node))])
+          : spaced([getDeclValue(anchor), cloneMergeValuePart(value)]);
+      }
+      return isNode(value, N.List)
+        ? new List([
+            ...collectAddMergeParts(getDeclValue(anchor)),
+            ...value.get('value', context).map(part => cloneMergeValuePart(part as Node))
+          ])
+        : new List([
+            ...collectAddMergeParts(getDeclValue(anchor)),
+            cloneMergeValuePart(value)
+          ]);
+    };
+    const isDeclarationOnlyRules = (node: Node): node is Rules => (
+      isNode(node, N.Rules)
+      && node._getRenderChildren(context).length > 0
+      && node._getRenderChildren(context).every(child => isNode(child, N.Declaration | N.Comment))
+    );
+    const composeMergedValue = (decl: Declaration, prior: Declaration, assign: string): void => {
+      if (!isNode(decl, N.Declaration) || !isNode(prior, N.Declaration)) {
+        return;
+      }
+      const priorValue = getDeclValue(prior);
+      const nextValue = getDeclValue(decl);
+      setDeclValue(decl, assign === '&_:'
+        ? spaced([priorValue, nextValue])
+        : new List([priorValue, nextValue]));
+      if (!getDeclImportant(decl) && getDeclImportant(prior)) {
+        setDeclImportant(decl, getDeclImportant(prior));
+      }
+    };
+    const normalizeMergedDeclarationValue = (node: Node): void => {
+      if (!isNode(node, N.Declaration)) {
+        return;
+      }
+      const current = getDeclValue(node);
+      if (!isNode(current, N.List) || current.get('value').length === 0) {
+        return;
+      }
+      const [first, ...rest] = current.get('value');
+      const isEmptyPlaceholder = Boolean(
+        first
+        && (
+          isNode(first, N.Nil)
+          || (isNode(first, N.List) && first.get('value').length === 0)
+        )
+      );
+      if (!isEmptyPlaceholder) {
+        return;
+      }
+      if (rest.length === 0) {
+        setDeclValue(node, new Nil());
+        return;
+      }
+      if (rest.length === 1) {
+        setDeclValue(node, rest[0]!);
+        return;
+      }
+      setDeclValue(node, new List(rest));
+    };
+
+    const lastVisibleByName = new Map<string, Node>();
+    const mergedAnchorByName = new Map<string, Node>();
+    const stream: Node[] = [];
+
+    for (const node of rules._getRenderChildren(context)) {
+      if (isNode(node, N.Declaration)) {
+        stream.push(node);
+        continue;
+      }
+      if (isDeclarationOnlyRules(node)) {
+        for (const child of node._getRenderChildren(context)) {
+          if (isNode(child, N.Declaration)) {
+            stream.push(child);
+          }
+        }
+      }
+    }
+
+    for (const node of stream) {
+      if (!isNode(node, N.Declaration)) {
+        continue;
+      }
+      const name = getDeclName(node);
+      const assign = getDeclAssign(node);
+      const merged = isMergedAssign(assign);
+
+      if (!merged) {
+        mergedAnchorByName.delete(name);
+        if (isVisibleInContext(node, context)) {
+          lastVisibleByName.set(name, node);
+        }
+        continue;
+      }
+      normalizeMergedDeclarationValue(node);
+
+      const prior = lastVisibleByName.get(name);
+      if (
+        prior
+        && prior !== node
+        && (
+          context
+            ? getCurrentParentNode(prior, context) !== getCurrentParentNode(node, context)
+            : prior.parent !== node.parent
+        )
+      ) {
+        composeMergedValue(node, prior, assign);
+      }
+
+      const existingAnchor = mergedAnchorByName.get(name);
+      if (existingAnchor && existingAnchor !== node && isNode(existingAnchor, N.Declaration)) {
+        // @todo — copy(true) was used here for comment suppression (stripping
+        // pre/post comments from merged values). Need a position-aware
+        // alternative: either a serialization-time comment suppression flag
+        // or field patches on pre/post.
+        const currentValue = getDeclValue(node);
+        const nextAnchorValue = assign === '+:'
+          ? new List([
+            ...collectAddMergeParts(getDeclValue(existingAnchor)),
+            ...collectAddMergeParts(currentValue)
+          ])
+          : rebaseLinearMergedValue(existingAnchor, currentValue, assign)
+            ?? appendMergedValue(existingAnchor, currentValue, assign);
+        setDeclValue(
+          existingAnchor,
+          nextAnchorValue
+        );
+        if (!getDeclImportant(existingAnchor) && getDeclImportant(node)) {
+          setDeclImportant(existingAnchor, getDeclImportant(node));
+        }
+        removeVisibleFlag(node);
+        if (isVisibleInContext(existingAnchor, context)) {
+          lastVisibleByName.set(name, existingAnchor);
+        }
+        continue;
+      }
+
+      mergedAnchorByName.set(name, node);
+      if (isVisibleInContext(node, context)) {
+        lastVisibleByName.set(name, node);
+      }
+    }
+  }
+
+  /**
+   * Normalize call-produced declaration-only Rules ordering so declarations
+   * emitted from late-evaluated calls (e.g. each/$for) appear before nested
+   * rulesets/at-rules in the same parent Rules container.
+   *
+   * This runs after queue evaluation to avoid mutating rule indices mid-eval.
+   */
+  private _normalizeCallDeclarationRulesOrder(rules: Rules, context?: Context): void {
+    const children = rules._getRenderChildren(context);
+    const firstNestedIdx = children.findIndex(n => isNode(n, N.Ruleset | N.AtRule));
+    if (firstNestedIdx < 0) {
+      return;
+    }
+    const beforeNested = children.slice(0, firstNestedIdx);
+    const afterNested = children.slice(firstNestedIdx);
+    const shouldMove = (n: Node) => {
+      const sourceParent = context
+        ? getSourceParent(n, context)
+        : n.sourceParent;
+      if (
+        !isNode(n, N.Rules)
+        || !isNode(sourceParent, N.Call)
+        || n._getRenderChildren(context).length === 0
+        || !n._getRenderChildren(context).every(child => isNode(child, N.Declaration | N.Comment))
+      ) {
+        return false;
+      }
+      const sourceName = (sourceParent as any).name;
+      // Keep mixin-call declaration blocks in source order relative to nested rulesets.
+      if (
+        isNode(sourceName, N.Reference)
+        && (sourceName.options?.type === 'mixin'
+          || sourceName.options?.type === 'mixin-ruleset'
+          || sourceName.options?.type === 'ruleset')
+      ) {
+        return false;
+      }
+      return true;
+    };
+    const moved = afterNested.filter(shouldMove);
+    if (moved.length === 0) {
+      return;
+    }
+    const remainder = afterNested.filter(n => !shouldMove(n));
+    rules._setChildren([...beforeNested, ...moved, ...remainder], context, false);
+  }
+
+  private _evaluateQueuedTopImports(context: Context): MaybePromise<void> {
+    const queued = context.topImports;
+    if (!queued?.length) {
+      return;
+    }
+
+    const evaluated: Node[] = [];
+    const evaluateOne = (importRule: Node): MaybePromise<void> => {
+      if (!isNode(importRule, N.AtRule)) {
+        evaluated.push(importRule);
+        return;
+      }
+
+      const evaldImport = importRule.clone(false, undefined, context);
+      evaldImport.preEvaluated = true;
+      const out = evaldImport.eval(context);
+      if (isThenable(out)) {
+        return (out as Promise<Node | Nil>).then((result) => {
+          if (!(result instanceof Nil)) {
+            evaluated.push(result);
+          }
+        });
+      }
+      if (!(out instanceof Nil)) {
+        evaluated.push(out as Node);
+      }
+    };
+
+    const out = serialForEach(queued, evaluateOne);
+    if (isThenable(out)) {
+      return (out as Promise<void>).then(() => {
+        context.topImports = evaluated;
+      });
+    }
+    context.topImports = evaluated;
+  }
+
+  /**
+   * After preEval: ensure root on extend stack, build eval queue, run evaluation.
+   * Used by evalNode so that when eval() is called without preEval (e.g. jess compile()),
+   * we still have all rulesets registered and root set for extend lookups.
+   */
+  private _afterPreEvalStep(rules: Rules, context: Context): MaybePromise<{ rules: Rules; rulesToHoist: boolean }> {
+    if (
+      rules === context.root
+      && rules.renderKey === CANONICAL
+      && !rules.hasFlag(F_STATIC)
+      && (context.renderKey === undefined || context.renderKey === CANONICAL)
+      && getCurrentParentNode(rules, context) === undefined
+    ) {
+      const evalRoot = rules.createShallowBodyWrapper(context, EVAL);
+      context.root = evalRoot;
+      context.rulesContext = evalRoot;
+      context.renderKey = evalRoot.renderKey;
+      rules = evalRoot;
+    }
+
+    const isMainRoot = rules === context.root;
+    if (isMainRoot && context.extendRoots.extendRootStack.length === 0) {
+      if (!context.extendRoots.root) {
+        context.extendRoots.registerRoot(rules);
+      }
+      context.extendRoots.pushExtendRoot(rules);
+    }
+    if (isEvaluated(rules, context)) {
+      return { rules, rulesToHoist: false };
+    }
+    if (rules === context.root) {
+      const map = new WeakMap<Ruleset, number>();
+      context.documentOrderByRuleset = map;
+      this._assignDocumentOrderDepthFirst(rules, map, { value: 0 }, context);
+    }
+    const evalQueue = this._buildEvalQueue(rules, context);
+    const maybeHoist = this._evaluateQueue(rules, evalQueue, context);
+    if (isThenable(maybeHoist)) {
+      return (maybeHoist as Promise<boolean>).then((rulesToHoist) => {
+        const finalize = () => {
+          this._normalizeCallDeclarationRulesOrder(rules, context);
+          this._coalesceMergedDeclarations(rules, context);
+          return {
+            rules,
+            rulesToHoist
+          };
+        };
+        if (rules === context.root && context.topImports?.length) {
+          const maybeEvalTopImports = this._evaluateQueuedTopImports(context);
+          if (isThenable(maybeEvalTopImports)) {
+            return (maybeEvalTopImports as Promise<void>).then(finalize);
+          }
+        }
+        return finalize();
+      });
+    }
+    if (rules === context.root && context.topImports?.length) {
+      const maybeEvalTopImports = this._evaluateQueuedTopImports(context);
+      if (isThenable(maybeEvalTopImports)) {
+        return (maybeEvalTopImports as Promise<void>).then(() => {
+          this._normalizeCallDeclarationRulesOrder(rules, context);
+          this._coalesceMergedDeclarations(rules, context);
+          return { rules, rulesToHoist: maybeHoist as boolean };
+        });
+      }
+    }
+    this._normalizeCallDeclarationRulesOrder(rules, context);
+    this._coalesceMergedDeclarations(rules, context);
+    return { rules, rulesToHoist: maybeHoist as boolean };
+  }
+
+  override evalNode(context: Context): MaybePromise<this> {
+    const saved = this._snapshotContext(context);
+    context.rulesEvalStack.push(this.sourceNode as Rules);
+    const restoreContextOnError = () => {
+      context.rulesContext = saved.rulesContext;
+      context.renderKey = saved.renderKey;
+      if (saved.treeRoot !== undefined) {
+        context.treeRoot = saved.treeRoot;
+      }
+      if (saved.root !== undefined) {
+        context.root = saved.root;
+      }
+      const currentLength = context.extendRoots.extendRootStack.length;
+      if (saved.extendRootStackLength !== undefined && currentLength > saved.extendRootStackLength) {
+        while (context.extendRoots.extendRootStack.length > saved.extendRootStackLength) {
+          context.extendRoots.popExtendRoot();
+        }
+      }
+      if (context.rulesEvalStack[context.rulesEvalStack.length - 1] === (this.sourceNode as Rules)) {
+        context.rulesEvalStack.pop();
+      }
+      context.depth--;
+    };
+    let pipeResult: MaybePromise<this>;
+    try {
+      pipeResult = pipe(
+        () => {
+          this._setupContextForRules(context, this);
+          // Run preEval first if not yet run (e.g. when jess compile() calls eval() without preEval).
+          // preEval registers the root and all nested rulesets so extend lookups find targets in child roots (e.g. .ma inside @media).
+          const runPreEvalIfNeeded = (rules: Rules): MaybePromise<Rules> => {
+            if (rules.preEvaluated) {
+              return rules;
+            }
+            const result = rules.preEval(context);
+            return isThenable(result) ? (result as Promise<Rules>) : result;
+          };
+          const rulesAfterPreEval = runPreEvalIfNeeded(this);
+          const afterPreEval = (rules: Rules) => {
+            // When we're the outermost Rules, use the tree we're evaling as root (may differ from context.root set in getTree, or be preEval's clone).
+            if (context.rulesEvalStack.length === 1) {
+              context.root = rules;
+            }
+            return this._afterPreEvalStep(rules, context);
+          };
+          if (isThenable(rulesAfterPreEval)) {
+            return (rulesAfterPreEval as Promise<Rules>).then(afterPreEval);
+          }
+          return afterPreEval(rulesAfterPreEval as Rules);
+        },
+        ({ rules }: { rules: Rules; rulesToHoist: boolean }) => {
+        // Note: Rulesets from imported Rules are already registered to their own treeRoot
+        // during preEval when the imported Rules node is evaluated. The extend search
+        // loops through allRoots, so it should find them. The _searchRulesChildrenForRulesets
+        // method in RulesetRegistry also searches imported Rules' registries.
+
+          // After all evaluation stages, check if any variables in the current Rules
+          // shadow readonly variables from imported Rules (compose type) at the same level
+          // Only check direct children of the Rules node, not nested variables (e.g., inside rulesets)
+          if (rules.rulesSet.length > 0) {
+            for (const entry of rules.rulesSet) {
+              if (entry.readonly) {
+                const importedVars = Registries
+                  .getDirectDeclarationsByKey(entry.node, undefined, context)
+                  .filter((decl): decl is VarDeclaration => isNode(decl, N.VarDeclaration));
+                for (const decl of importedVars) {
+                  const key = decl.get('name').toString();
+                  const currentDeclarations = Registries.getDirectDeclarationsByKey(rules, key, context);
+                  for (const currentDecl of currentDeclarations) {
+                    if (isNode(currentDecl, N.VarDeclaration) && !currentDecl.options?.setDefined) {
+                      // Only throw if the variable is a direct child of the Rules node (same level)
+                      // Nested variables (e.g., inside rulesets) are allowed to shadow
+                      if (getCurrentParentNode(currentDecl, context) === rules) {
+                        throw new ReferenceError(`"${key}" is readonly`);
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+
+          // Check if we're at the outermost level BEFORE restoring context
+          // Only process extends at the TRUE outermost root (context.root)
+          // This ensures extends are processed AFTER all evaluation completes,
+          // including imports and nested Rules
+          const isOutermost = rules === context.root;
+
+          if (isOutermost) {
+            processExtends(context);
+          }
+          /** Restore contexts */
+          context.rulesContext = saved.rulesContext;
+          context.renderKey = saved.renderKey;
+          // Only restore context.treeRoot if saved.treeRoot is defined and we're not at the outermost level
+          // If saved.treeRoot is undefined, it means we're at the outermost level, so keep context.treeRoot as is
+          // This ensures extends evaluated during selector evaluation can still access the correct treeRoot
+          if (saved.treeRoot !== undefined && !isOutermost) {
+            context.treeRoot = saved.treeRoot;
+          }
+          // Only restore context.root if we're not at the outermost level (where it was originally set)
+          // If saved.root is undefined, it means we're at the outermost level, so keep context.root as is
+          if (saved.root !== undefined && !isOutermost) {
+            context.root = saved.root;
+          }
+          // Restore extend root stack to its original length (if we're not the main root)
+          // The main root manages its own push/pop, but nested Rules should restore the stack
+          if (!isOutermost && saved.extendRootStackLength !== undefined) {
+            const currentLength = context.extendRoots.extendRootStack.length;
+            if (currentLength > saved.extendRootStackLength) {
+            // Pop any extend roots that were pushed during this Rules evaluation
+              while (context.extendRoots.extendRootStack.length > saved.extendRootStackLength) {
+                context.extendRoots.popExtendRoot();
+              }
+            }
+          }
+          // Pop extend root if we pushed it (check if this is still the root)
+          if (rules === context.root) {
+            context.extendRoots.popExtendRoot();
+          }
+          context.rulesEvalStack.pop();
+          context.depth--;
+          return rules;
+        }
+      ) as MaybePromise<this>;
+    } catch (error) {
+      restoreContextOnError();
+      throw error;
+    }
+    if (isThenable(pipeResult)) {
+      return (pipeResult as Promise<this>).catch((error) => {
+        restoreContextOnError();
+        throw error;
+      });
+    }
+    return pipeResult as MaybePromise<this>;
+  }
+}
+
+export const rules = defineType(Rules, 'Rules');
+
+type EvalQueueMap = Map<Priority, Array<[number, Node]>>;
+
+/**
+ * @todo - Will need lots of massaging, to resolve things like
+ * mixins which rely on variables which have interpolated names,
+ * and variables with interpolated names that rely on mixins.
+ *
+ * @note - Registration of declaration names and mixins / selectors
+ * should have already happened in pre-eval.
+ */
+const NodeTypeToPriority = new Map([
+  /** First, resolve imports */
+  ['StyleImport', Priority.Highest],
+  /** Then, resolve calls */
+  ['Call', Priority.High],
+  /** Then, resolve declarations */
+  ['VarDeclaration', Priority.Medium],
+  ['Declaration', Priority.Medium],
+  /** Then... */
+  ['Mixin', Priority.Low],
+  ['Ruleset', Priority.Low],
+  /** Extend should evaluate at the same priority as Ruleset to ensure it evaluates before nested rulesets */
+  ['Extend', Priority.Low],
+  /** AtRule (e.g., @media) should evaluate at the same priority as Ruleset to preserve source order */
+  ['AtRule', Priority.Low]
+  /** Then, everything else? */
+]);
+
+// const TypeToNodeType = new Map([
+//   ['Mixin', NodeType.MIXIN],
+//   ['Ruleset', NodeType.RULESET],
+//   ['Declaration', NodeType.PROPERTY],
+//   ['VarDeclaration', NodeType.VARIABLE],
+//   ['Rules', NodeType.RULES]
+// ])
+
+// export const enum NodeTypeIndex {
+//   NONE             = 0b000000,
+//   MIXIN            = 0b000001,
+//   RULESET          = 0b000010,
+//   MIXIN_OR_RULESET = 0b000011,
+//   PROPERTY         = 0b000100,
+//   VARIABLE         = 0b001000,
+//   VAR_OR_PROP      = 0b001100,
+//   /**
+//    * Variables and mixins can leak
+//   */
+//   LEAKY_RULES      = 0b010000,
+//   /** @note - Properties and rulesets are always visible. */
+//   PRIVATE_RULES    = 0b100000,
+//   RULES            = 0b110000
+// }
+
+// type IndexKey = `${NodeType}${string}`
+
+interface RulesEntry {
+  node: Rules;
+  rulesVisibility?: RulesOptions['rulesVisibility'];
+  /**
+   * These are from use, from, and import statements. Can't be assigned with $$
+   * (verify that this is not possible with SCSS).
+   */
+  readonly?: boolean;
+}
+
+/**
+ * Right now, the only nodes that can be registered to the scope for lookups
+ */
+// type ScopeNodes = Declaration | VarDeclaration | Mixin | Ruleset | Rules
+export type MixinEntry = Mixin | Ruleset;
+
+/**
+ * Returns a plain JS function for calling a set of mixins
+ *
+ * This is in the same file as Rules to avoid circular dependencies.
+ *
+ * @note this will be called as a result after a mixin find is executed.
+ */
+export function getFunctionFromMixins(mixins: MixinEntry | MixinEntry[]) {
+  let mixinArr = isArray(mixins) ? mixins : [mixins];
+  /**
+   * This will be called by a mixin call or by JavaScript
+   *
+   * @note - Mixins resolve to async functions because they
+   * can contain dynamic imports.
+   */
+  async function returnFunc(this: unknown, ...args: any[]): Promise<Rules | Record<string, string>>;
+  async function returnFunc(this: Context, ...args: any[]): Promise<Rules>;
+  async function returnFunc(this: Context | unknown, ...args: any[]) {
+    // When called via callWithContext, 'this' is functionThis, not Context
+    // We need to extract the context from functionThis or use a fallback
+    let thisContext: Context;
+
+    if (this instanceof Context) {
+      thisContext = this;
+    } else if (this && typeof this === 'object' && 'context' in this) {
+      // This is functionThis from callWithContext
+      thisContext = (this as any).context;
+    } else {
+      thisContext = new Context();
+    }
+    let caller = thisContext.caller;
+    const callerSourceNode = (caller as any)?.name instanceof Node
+      ? (caller as any).name
+      : caller;
+    let sourceParent = callerSourceNode
+      ? getSourceParent(callerSourceNode, thisContext)
+      : undefined;
+    if (sourceParent && isNode(sourceParent, N.Reference | N.Call)) {
+      sourceParent = caller;
+    }
+    sourceParent ??= caller;
+    const invocationParent = thisContext.rulesContext
+      ?? (caller ? getParent(caller, thisContext) : undefined);
+
+    const nodeArgs = await evaluateMixinArgs(args, caller, thisContext);
+    const mixinCandidates = await matchMixinCandidates(mixinArr, nodeArgs, caller, sourceParent, thisContext);
+    const { evalCandidates, hasDefault } = filterAndSortMixinEvalCandidates(mixinCandidates, thisContext);
+
+    const outputRules: Rules[] = [];
+    const candidateOutputOpts: EvaluateCandidateOutputOptions = {
+      sourceParent,
+      invocationParent,
+      restrictMixinOutputLookup: thisContext.leakyRules !== true,
+      outputRules,
+      getCandidateParent: node => getCandidateParent(node, thisContext)
+    };
+
+    const output = await dispatchMixinEvalCandidates({
+      evalCandidates,
+      hasDefault,
+      nodeArgs,
+      sourceParent,
+      invocationParent,
+      caller,
+      restrictMixinOutputLookup: candidateOutputOpts.restrictMixinOutputLookup,
+      outputRules,
+      getCandidateParent: candidateOutputOpts.getCandidateParent,
+      evaluateCandidateOutput: (candidate, rules, outerRules, params) =>
+        evaluateCandidateOutput(candidate, rules, outerRules, params, thisContext, candidateOutputOpts)
+    }, thisContext);
+
+    return finalizeMixinInvocationReturn(output, this instanceof Context ? this : thisContext);
+  }
+
+  return returnFunc;
+}
+
+/**
+ * Direct mixin invocation — calls dispatch primitives without the
+ * getFunctionFromMixins → callWithContext → returnFunc indirection.
+ *
+ * The result is already fully evaluated (each candidate's body was
+ * evaluated before being assembled into the return Rules). Callers must NOT
+ * re-evaluate the result.
+ */
+export async function evalMixinDirect(
+  context: Context,
+  mixins: MixinEntry | MixinEntry[],
+  args: List<Node> | undefined
+): Promise<Rules | Nil> {
+  const mixinArr = isArray(mixins) ? mixins : [mixins];
+  const caller = context.caller;
+  const callerSourceNode = caller && isNode(caller, N.Call) && caller.get('name') instanceof Node
+    ? caller.get('name')
+    : caller;
+  let sourceParent = callerSourceNode
+    ? getSourceParent(callerSourceNode as Node, context)
+    : undefined;
+  if (sourceParent && isNode(sourceParent, N.Reference | N.Call)) {
+    sourceParent = caller;
+  }
+  sourceParent ??= caller;
+  const invocationParent = context.rulesContext
+    ?? (caller ? getParent(caller as Node, context) : undefined);
+
+  const nodeArgs = await evaluateMixinArgs(
+    args ? [...args.get('value', context)] : [],
+    caller,
+    context
+  );
+  const mixinCandidates = await matchMixinCandidates(
+    mixinArr, nodeArgs, caller, sourceParent, context
+  );
+  const { evalCandidates, hasDefault } = filterAndSortMixinEvalCandidates(
+    mixinCandidates, context
+  );
+
+  const outputRules: Rules[] = [];
+  if (process.env.JESS_DEBUG_LOCK === 'throw-direct') {
+    const callerName = caller && isNode(caller, N.Call) && (caller as Call).name instanceof Node
+      ? (caller as Call).name
+      : undefined;
+    const callerKey = isNode(callerName, N.Reference)
+      ? String(callerName.key?.valueOf?.() ?? '')
+      : '';
+    if (callerKey.includes('inner-locked-mixin')) {
+      throw new Error(`[lock-direct] ${JSON.stringify({
+        callerKey,
+        mixinCount: mixinArr.length,
+        matchedCount: mixinCandidates.length,
+        evalCandidateCount: evalCandidates.length,
+        hasDefault,
+        sourceParent: sourceParent?.type,
+        invocationParent: invocationParent?.type,
+        matchNames: mixinCandidates.map(candidate => String((candidate as Mixin).get?.('name')?.valueOf?.() ?? candidate.type))
+      })}`);
+    }
+  }
+  const candidateOutputOpts: EvaluateCandidateOutputOptions = {
+    sourceParent,
+    invocationParent,
+    restrictMixinOutputLookup: context.leakyRules !== true,
+    outputRules,
+    getCandidateParent: node => getCandidateParent(node, context)
+  };
+
+  const output = await dispatchMixinEvalCandidates({
+    evalCandidates,
+    hasDefault,
+    nodeArgs,
+    sourceParent,
+    invocationParent,
+    caller,
+    restrictMixinOutputLookup: candidateOutputOpts.restrictMixinOutputLookup,
+    outputRules,
+    getCandidateParent: candidateOutputOpts.getCandidateParent,
+    evaluateCandidateOutput: (candidate, rules, outerRules, params) =>
+      evaluateCandidateOutput(candidate, rules, outerRules, params, context, candidateOutputOpts)
+  }, context);
+
+  return finalizeMixinInvocationReturn(output, context) as Rules | Nil;
+}