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

package/src/tree/__tests__/rules.test.ts

@@ -0,0 +1,1271 @@
+import {
+  ruleset,
+  sel,
+  el,
+  sellist,
+  rules,
+  decl,
+  vardecl,
+  spaced,
+  any,
+  call,
+  ref,
+  mixin,
+  fn,
+  condition,
+  expr,
+  Node,
+  type Rules,
+  List,
+  AssignmentType,
+  VarDeclaration,
+  style,
+  quoted,
+  atrule,
+  amp,
+  type Declaration,
+  type Selector
+} from '../index.js';
+import { vi } from 'vitest';
+import { Context, TreeContext } from '../../context.js';
+import type { FindOptions } from '../util/registry-utils.js';
+import { isNode } from '../util/is-node.js';
+import { getChildren, getParent, getSourceParent, markScopeDirty, setChildren, setParent, setSourceParent } from '../util/field-helpers.js';
+import { N } from '../node-type.js';
+import { EVAL } from '../node.js';
+import { addEdgeAt, getParentEdge } from '../util/cursor.js';
+
+let context: Context;
+
+function getPropWithContext(context: Context, n: Rules, key: string, opts: FindOptions = {}) {
+  context.rulesContext = n;
+  opts.searchParents = true;
+  opts.context = context;
+  return n.find('declaration', key, 'Declaration', opts);
+}
+
+function getVarWithContext(context: Context, n: Rules, key: string, opts: FindOptions = {}) {
+  context.rulesContext = n;
+  opts.searchParents = true;
+  opts.context = context;
+  let decl = n.find('declaration', key, 'VarDeclaration', opts);
+  return decl;
+}
+
+// function getSelectorWithContext(context: Context, n: Rules, key: Selector, opts: FindOptions = {}, start?: number) {
+//   context.rulesContext = n;
+//   opts.searchParents = true;
+//   let decl = n.findDeclaration(key, 'VarDeclaration', opts);
+//   return decl;
+// }
+
+describe('Rules', () => {
+  beforeAll(() => {
+    Node.prototype.fullRender = true;
+  });
+
+  afterAll(() => {
+    Node.prototype.fullRender = false;
+  });
+
+  let getProp = getPropWithContext.bind(context, context);
+  let getVar = getVarWithContext.bind(context, context);
+  // let getSelector = getSelectorWithContext.bind(context, context);
+  beforeEach(() => {
+    context = new Context();
+    getProp = getPropWithContext.bind(context, context);
+    getVar = getVarWithContext.bind(context, context);
+    // getSelector = getSelectorWithContext.bind(context, context);
+    context.id = 'testing';
+  });
+
+  it.skip('assigns position linearly for nested rules', async () => {
+    let node = rules([
+      vardecl({ name: 'one', value: any('one') }),
+      vardecl({ name: 'root', value: any('value') }),
+      rules([
+        vardecl({ name: 'foo', value: any('bar') }),
+        vardecl({ name: 'one', value: any('two') }),
+        rules([
+          vardecl({ name: 'one', value: any('three') })
+        ])
+      ])
+    ]);
+    node = await node.eval(context);
+    let index = node.index;
+    expect(index).toBe(0);
+    expect(node.at(1, context)?.index).toBeGreaterThan(index);
+    index = node.at(1, context)?.index ?? index;
+    expect(node.at(2, context)?.index).toBeGreaterThan(index);
+    index = node.at(2, context)?.index ?? index;
+    expect((node.at(2, context) as Rules).at(0, context)?.index).toBeGreaterThan(index);
+    index = (node.at(2, context) as Rules).at(1, context)?.index ?? index;
+    expect((node.at(2, context) as Rules).at(2, context)?.index).toBeGreaterThan(index);
+    expect(((node.at(2, context) as Rules).at(2, context) as Rules).at(0, context)?.index).toBeGreaterThan(index);
+  });
+
+  describe('Scope / lookups', () => {
+    describe('set / get vars & props', () => {
+      it('can do a normal get / set of properties', async () => {
+        let node = rules([
+          decl({ name: 'foo', value: any('bar') })
+        ]);
+        node = await node.eval(context);
+
+        expect(`${getProp(node, 'foo')}`).toBe('foo: bar');
+      });
+
+      it('can do a normal get / set of variables', async () => {
+        let node = rules([
+          vardecl({ name: 'foo', value: any('bar') })
+        ]);
+        node = await node.eval(context);
+        expect(`${getVar(node, 'foo')}`).toBe('$foo: bar');
+      });
+
+      it('replaces variable values', async () => {
+        let node = rules([
+          vardecl({ name: 'foo', value: any('one') }),
+          vardecl({ name: 'foo', value: any('two') })
+        ]);
+        node = await node.eval(context);
+        expect(`${getVar(node, 'foo')}`).toBe('$foo: two');
+      });
+
+      it.skip('will not set if defined', async () => {
+        let decl1 = vardecl({ name: 'first', value: any('one') }, { assign: AssignmentType.CondAssign });
+        let decl2 = vardecl({ name: 'first', value: any('two') }, { assign: AssignmentType.CondAssign });
+        let node = rules([
+          decl1,
+          decl2
+        ]);
+        node = await node.eval(context);
+        /** This won't have been resolved, so we need to evaluate it. */
+        let result = await getVar(node, 'first')!.eval(context);
+        expect(result.render(context)).toBe('$first: one');
+      });
+
+      // it('will skip normalization', () => {
+      //   scope.setVar('one', 'one', { isNormalized: true, protected: true })
+      //   expect(scope.getVar('one')).toEqual('one')
+      // })
+
+      it('throws if undefined', async () => {
+        let node = rules([
+          decl({ name: 'foo', value: ref({ key: 'first' }, { type: 'variable' }) })
+        ]);
+        expect(() => {
+          const result = node.eval(context);
+          if (result instanceof Promise) {
+            // This shouldn't happen for this test case
+            throw new Error('Expected synchronous evaluation');
+          }
+          return result;
+        }).toThrow('\'first\' is not defined');
+      });
+
+      it('doesn\'t throw error if there\'s a fallback', async () => {
+        let node = rules([
+          decl({ name: 'foo', value: ref({ key: 'first' }, { type: 'variable', fallbackValue: true }) })
+        ]);
+        const result = node.eval(context);
+        if (result instanceof Promise) {
+          await expect(result).resolves.not.toThrow();
+        } else {
+          // Synchronous result, no error thrown
+          expect(result).toBeDefined();
+        }
+      });
+
+      it('does not retry style imports when content evaluation fails', async () => {
+        let attempts = 0;
+        let node = rules([
+          style({ path: quoted(any('retry-target.jess')) }, { type: 'import' })
+        ]);
+        const target = node.at(0, context);
+        if (!target) {
+          throw new Error('Expected first rule to exist');
+        }
+        // Simulate a content evaluation error (not a path resolution error).
+        // Only path resolution errors (tagged with _isPathResolutionError)
+        // should be retried — content errors mean the tree was already cloned
+        // and retrying would wastefully re-clone it.
+        target.eval = (() => {
+          attempts += 1;
+          throw new Error('content-eval-failure');
+        }) as typeof target.eval;
+
+        await expect(async () => {
+          await node.eval(context);
+        }).rejects.toThrow('content-eval-failure');
+
+        // Content evaluation errors are not retried — only path resolution errors are
+        expect(attempts).toBe(1);
+      });
+    });
+
+    describe('scope inheritance', () => {
+      it('looks up parent scope', async () => {
+        let inherited = rules([]);
+        let node = rules([
+          vardecl({ name: 'foo', value: any('bar') }),
+          inherited
+        ]);
+
+        node = await node.eval(context);
+        expect(`${getVar(inherited, 'foo')}`).toBe('$foo: bar');
+      });
+
+      it('inherits values when set after', async () => {
+        let inherited = rules([]);
+        let node = rules([
+          inherited
+        ]);
+        node.push(vardecl({ name: 'foo', value: any('bar') }));
+
+        node = await node.eval(context);
+        expect(`${getVar(inherited, 'foo')}`).toBe('$foo: bar');
+      });
+
+      it('characterizes shallow Rules clones as keeping canonical parentage while exposing shared top-level children through render-key parent edges', () => {
+        const ctx = new Context();
+        const nestedBody = rules([
+          decl({ name: 'color', value: any('red') })
+        ]);
+        const nested = ruleset({
+          selector: sel([el('.item')]),
+          rules: nestedBody
+        });
+        const node = rules([nested]);
+
+        const cloned = node.clone(false, undefined, ctx);
+        const clonedRuleset = cloned.at(0, context) as typeof nested;
+        const activeCtx = new Context();
+        activeCtx.renderKey = cloned.renderKey;
+
+        expect(clonedRuleset).toBe(nested);
+        expect(getParent(clonedRuleset, ctx)).toBe(node);
+        expect(getParent(clonedRuleset, activeCtx)).toBe(cloned);
+        expect(clonedRuleset.parent).toBe(node);
+        expect(clonedRuleset.get('rules')).toBe(nestedBody);
+        expect(clonedRuleset.get('rules').parent).toBe(clonedRuleset);
+        expect(clonedRuleset.get('rules').at(0, context)).toBe(nestedBody.at(0, context));
+      });
+
+      it('cloneDetachedUnlockWrapper keeps canonical parentage while giving shared top-level children an unlock-wrapper state parent', () => {
+        const ctx = new Context();
+        const nestedBody = rules([
+          decl({ name: 'color', value: any('red') })
+        ]);
+        const nested = ruleset({
+          selector: sel([el('.item')]),
+          rules: nestedBody
+        });
+        const node = rules([nested]);
+
+        const wrapper = node.cloneDetachedUnlockWrapper(ctx);
+        const wrappedRuleset = wrapper.at(0, context) as typeof nested;
+
+        expect(wrapper).not.toBe(node);
+        expect(wrappedRuleset).toBe(nested);
+        expect(wrappedRuleset.parent).toBe(node);
+        expect(getParentEdge({ node: wrappedRuleset, renderKey: wrapper.renderKey })?.node).toBe(wrapper);
+        expect(wrappedRuleset.get('rules')).toBe(nestedBody);
+        expect(wrappedRuleset.get('rules').parent).toBe(wrappedRuleset);
+      });
+
+      it('cloneVisibilityIsolationWrapper isolates rulesVisibility writes while keeping shared top-level children canonically parented', () => {
+        const ctx = new Context();
+        const nestedBody = rules([
+          decl({ name: 'color', value: any('red') })
+        ]);
+        const nested = ruleset({
+          selector: sel([el('.item')]),
+          rules: nestedBody
+        });
+        const node = rules([nested]);
+        node.options.rulesVisibility.VarDeclaration = 'optional';
+
+        const wrapper = node.cloneVisibilityIsolationWrapper(ctx);
+        const wrappedRuleset = wrapper.at(0, context) as typeof nested;
+
+        wrapper.options.rulesVisibility.VarDeclaration = 'private';
+
+        expect(wrapper.options).not.toBe(node.options);
+        expect(wrapper.options.rulesVisibility).not.toBe(node.options.rulesVisibility);
+        expect(wrapper.options.rulesVisibility.VarDeclaration).toBe('private');
+        expect(node.options.rulesVisibility.VarDeclaration).toBe('optional');
+        expect(wrappedRuleset.parent).toBe(node);
+        expect(getParentEdge({ node: wrappedRuleset, renderKey: wrapper.renderKey })?.node).toBe(wrapper);
+        expect(wrappedRuleset.get('rules')).toBe(nestedBody);
+        expect(wrappedRuleset.get('rules').parent).toBe(wrappedRuleset);
+      });
+
+      it('createShallowBodyWrapper reuses the same top-level child array', () => {
+        const ctx = new Context();
+        const nestedBody = rules([
+          decl({ name: 'color', value: any('red') })
+        ]);
+        const nested = ruleset({
+          selector: sel([el('.item')]),
+          rules: nestedBody
+        });
+        const node = rules([nested]);
+
+        const wrapper = node.createShallowBodyWrapper(ctx);
+
+        expect(wrapper).not.toBe(node);
+        expect(wrapper.value).toBe(node.value);
+        expect(wrapper.renderKey).toBe(EVAL);
+        expect(wrapper.at(0, context)).toBe(nested);
+        expect(getParentEdge({ node: nested, renderKey: wrapper.renderKey })?.node).toBe(wrapper);
+        expect(nested.parent).toBe(node);
+      });
+
+      it('render-key child replacement on a shallow wrapper updates parentEdges without corrupting canonical parentage', () => {
+        const ctx = new Context();
+        const nested = ruleset({
+          selector: sel([el('.item')]),
+          rules: rules([
+            decl({ name: 'color', value: any('red') })
+          ])
+        });
+        const node = rules([nested]);
+        const wrapper = node.createShallowBodyWrapper(ctx);
+        const replacement = ruleset({
+          selector: sel([el('.other')]),
+          rules: rules([
+            decl({ name: 'color', value: any('blue') })
+          ])
+        });
+
+        ctx.renderKey = wrapper.renderKey;
+        setChildren(wrapper, [replacement], ctx, { markDirty: false });
+
+        expect(wrapper.value[0]).toBe(replacement);
+        expect(getParent(replacement, ctx)).toBe(wrapper);
+        expect(getParent(nested, ctx)).toBe(node);
+        expect(node.value[0]).toBe(nested);
+      });
+
+      it('characterizes returned param-mixin nested bodies as correctly parented and already source-rooted in provenance', async () => {
+        const paramMixin = mixin({
+          name: any('.with-param'),
+          params: new List([
+            vardecl({ name: 'shade', value: any('red') }, { paramVar: true })
+          ]),
+          rules: rules([
+            ruleset({
+              selector: sel([el('.item')]),
+              rules: rules([
+                decl({ name: 'color', value: ref({ key: 'shade' }, { type: 'variable' }) })
+              ])
+            })
+          ])
+        });
+        const node = rules([
+          paramMixin,
+          call({
+            name: ref({ key: '.with-param' }, { type: 'mixin' }),
+            args: new List([any('blue')])
+          })
+        ]);
+
+        const evald = await node.eval(context);
+        expect(evald.toTrimmedString({ context })).toContain('.item {\n  color: blue;\n}');
+      });
+
+      it('guarded mixin passes guard check and produces correct output', async () => {
+        const root = rules([
+          mixin({
+            name: any('.guarded'),
+            params: new List([
+              any('color', { role: 'property' })
+            ]),
+            guard: condition([
+              expr(ref({ key: 'color' }, { type: 'variable' })),
+              '=',
+              any('blue')
+            ]),
+            rules: rules([
+              ruleset({
+                selector: sel([el('.inner')]),
+                rules: rules([
+                  decl({ name: 'color', value: ref({ key: 'color' }, { type: 'variable' }) })
+                ])
+              })
+            ])
+          }),
+          call({
+            name: ref({ key: '.guarded' }, { type: 'mixin' }),
+            args: new List([any('blue')])
+          })
+        ]);
+        const ctx = new Context();
+        const evald = await root.eval(ctx);
+
+        expect(evald.toTrimmedString({ context: ctx })).toContain('.inner');
+        expect(evald.toTrimmedString({ context: ctx })).toContain('color: blue');
+      });
+
+      it('peeks into optional child scope', async () => {
+        let node = rules([
+          rules([
+            vardecl({ name: 'one', value: any('two') })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'optional'
+            }
+          })
+        ]);
+
+        node = await node.eval(context);
+        expect(`${getVar(node, 'one')}`).toBe('$one: two');
+      });
+
+      it('fails to get private child scope', async () => {
+        let node = rules([
+          rules([
+            vardecl({ name: 'one', value: any('two') })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'private'
+            }
+          })
+        ]);
+
+        node = await node.eval(context);
+        expect(getVar(node, 'one')).toBeUndefined();
+      });
+
+      it('skips an optional value', async () => {
+        let node = rules([
+          vardecl({ name: 'one', value: any('one') }),
+          rules([
+            vardecl({ name: 'one', value: any('two') })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'optional'
+            }
+          })
+        ]);
+
+        node = await node.eval(context);
+        expect(`${getVar(node, 'one')}`).toBe('$one: one');
+      });
+
+      it('returns optional value when no public value found', async () => {
+        let node = rules([
+          rules([
+            vardecl({ name: 'one', value: any('optional-value') })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'optional'
+            }
+          }),
+          rules([
+            vardecl({ name: 'two', value: any('public-value') })
+          ])
+        ]);
+
+        node = await node.eval(context);
+        // Should find optional value since no public value exists
+        expect(`${getVar(node, 'one')}`).toBe('$one: optional-value');
+        // Should find public value
+        expect(`${getVar(node, 'two')}`).toBe('$two: public-value');
+      });
+
+      it('handles optional values with mixed positions and start parameter', async () => {
+        let node = rules([
+          vardecl({ name: 'var', value: any('first') }),
+          vardecl({ name: 'var', value: any('second') }),
+          rules([
+            vardecl({ name: 'var', value: any('optional-early') })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'optional'
+            }
+          }),
+          vardecl({ name: 'var', value: any('third') }),
+          rules([
+            vardecl({ name: 'var', value: any('optional-late') })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'optional'
+            }
+          })
+        ]);
+
+        node = await node.eval(context);
+        // Should find the last public value (third), not optional values
+        expect(`${getVar(node, 'var')}`).toBe('$var: third');
+
+        // Test with start parameter - should find value before start position
+        const thirdVar = node.value.find(n => isNode(n, N.VarDeclaration) && n.get('name').valueOf() === 'var' && n.get('value').valueOf() === 'third');
+        if (thirdVar && 'index' in thirdVar) {
+          const result = getVar(node, 'var', { start: thirdVar.index });
+          expect(result).toBeDefined();
+          expect(result.render(context)).toBe('$var: second');
+        }
+      });
+
+      it('handles nested optional Rules with different indexing', async () => {
+        let node = rules([
+          rules([
+            vardecl({ name: 'nested', value: any('nested-optional') }),
+            rules([
+              vardecl({ name: 'deep', value: any('deep-optional') })
+            ], {
+              rulesVisibility: {
+                VarDeclaration: 'optional'
+              }
+            })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'optional'
+            }
+          }),
+          vardecl({ name: 'nested', value: any('public-nested') }),
+          vardecl({ name: 'deep', value: any('public-deep') })
+        ]);
+
+        node = await node.eval(context);
+        // Should find public value, not optional nested value
+        expect(`${getVar(node, 'nested')}`).toBe('$nested: public-nested');
+        // Should find public value, not optional deep value
+        expect(`${getVar(node, 'deep')}`).toBe('$deep: public-deep');
+      });
+
+      it('selects last optional value when multiple optionals found and no public', async () => {
+        let node = rules([
+          rules([
+            vardecl({ name: 'var', value: any('optional-first') })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'optional'
+            }
+          }),
+          rules([
+            vardecl({ name: 'var', value: any('optional-second') })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'optional'
+            }
+          }),
+          rules([
+            vardecl({ name: 'var', value: any('optional-third') })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'optional'
+            }
+          })
+        ]);
+
+        node = await node.eval(context);
+        // Should find the last optional value by source order (comparePosition)
+        expect(`${getVar(node, 'var')}`).toBe('$var: optional-third');
+      });
+
+      it('handles optional values with start parameter in different Rules', async () => {
+        let node = rules([
+          vardecl({ name: 'var', value: any('root-first') }),
+          rules([
+            vardecl({ name: 'var', value: any('optional-in-child') })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'optional'
+            }
+          }),
+          vardecl({ name: 'var', value: any('root-second') }),
+          vardecl({ name: 'var', value: any('root-third') })
+        ]);
+
+        node = await node.eval(context);
+        // Find the last public value
+        expect(`${getVar(node, 'var')}`).toBe('$var: root-third');
+
+        // Test with start parameter pointing to root-third
+        const thirdVar = node.value.find(n => isNode(n, N.VarDeclaration) && n.get('name').valueOf() === 'var' && n.get('value').valueOf() === 'root-third');
+        if (thirdVar && 'index' in thirdVar) {
+          const result = getVar(node, 'var', { start: thirdVar.index });
+          expect(result).toBeDefined();
+          // Should find root-second (before start), not optional value
+          expect(result.render(context)).toBe('$var: root-second');
+        }
+      });
+
+      it('handles complex scenario: public, optional, then public again', async () => {
+        let node = rules([
+          vardecl({ name: 'var', value: any('public-1') }),
+          rules([
+            vardecl({ name: 'var', value: any('optional-1') }),
+            vardecl({ name: 'var', value: any('optional-2') })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'optional'
+            }
+          }),
+          vardecl({ name: 'var', value: any('public-2') })
+        ]);
+
+        node = await node.eval(context);
+        // Should find the last public value, ignoring optional values
+        expect(`${getVar(node, 'var')}`).toBe('$var: public-2');
+      });
+
+      it('handles optional values in Rules with different indices from parent', async () => {
+        // Create a scenario where child Rules have different indexing
+        let childRules = rules([
+          vardecl({ name: 'var', value: any('child-optional') })
+        ], {
+          rulesVisibility: {
+            VarDeclaration: 'optional'
+          }
+        });
+
+        let node = rules([
+          vardecl({ name: 'var', value: any('parent-1') }),
+          childRules,
+          vardecl({ name: 'var', value: any('parent-2') })
+        ]);
+
+        node = await node.eval(context);
+        // Should find parent-2 (last public), not child-optional
+        expect(`${getVar(node, 'var')}`).toBe('$var: parent-2');
+
+        // Test lookup from within child Rules - should find its own value
+        // Optional declarations are fallback-only and should not overtake public declarations
+        // that are reachable in the lookup chain.
+        const childVar = getVar(childRules, 'var');
+        expect(childVar).toBeDefined();
+        expect(`${childVar}`).toBe('$var: parent-2');
+      });
+
+      it('handles multiple optional Rules with declarations at different positions', async () => {
+        let node = rules([
+          rules([
+            vardecl({ name: 'a', value: any('optional-a-1') }),
+            vardecl({ name: 'b', value: any('optional-b-1') })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'optional'
+            }
+          }),
+          vardecl({ name: 'a', value: any('public-a') }),
+          rules([
+            vardecl({ name: 'b', value: any('optional-b-2') }),
+            vardecl({ name: 'c', value: any('optional-c') })
+          ], {
+            rulesVisibility: {
+              VarDeclaration: 'optional'
+            }
+          }),
+          vardecl({ name: 'b', value: any('public-b') })
+        ]);
+
+        node = await node.eval(context);
+        // Should find public-a, ignoring optional-a-1
+        expect(`${getVar(node, 'a')}`).toBe('$a: public-a');
+        // Should find public-b, ignoring optional-b-1 and optional-b-2
+        expect(`${getVar(node, 'b')}`).toBe('$b: public-b');
+        // Should find optional-c since no public c exists
+        expect(`${getVar(node, 'c')}`).toBe('$c: optional-c');
+      });
+
+      it('shadows variables #1', async () => {
+        let node = rules([
+          vardecl({ name: 'one', value: any('one') }),
+          rules([
+            vardecl({ name: 'one', value: any('three') })
+          ])
+        ]);
+
+        node = await node.eval(context);
+        let inherited = node.at(1, context);
+        expect(`${getVar(inherited as Rules, 'one')}`).toBe('$one: three');
+      });
+
+      it('shadows variables #2', async () => {
+        let node = rules([
+          vardecl({ name: 'one', value: any('one') }),
+          rules([
+            vardecl({ name: 'one', value: any('two') }),
+            vardecl({ name: 'one', value: any('three') })
+          ])
+        ]);
+
+        node = await node.eval(context);
+        let inherited = node.at(1, context);
+        expect(`${getVar(inherited as Rules, 'one')}`).toBe('$one: three');
+      });
+
+      it.skip('sets existing variables', async () => {
+        let node = rules([
+          vardecl({ name: 'one', value: any('one') }),
+          rules([
+            vardecl({ name: 'one', value: any('three') }, { setDefined: true })
+          ])
+        ]);
+
+        node = await node.eval(context);
+        // With registry-based setDefined, the Rules node stays at index 1 (no array changes)
+        let inherited = node.at(1, context);
+        expect(`${getVar(node, 'one')}`).toBe('$one: three');
+        expect(`${getVar(inherited as Rules, 'one')}`).toBe('$one := three');
+      });
+
+      it.skip('demonstrates setDefined behavior like Sass !global', async () => {
+        let node = rules([
+          // Original variable declaration
+          vardecl({ name: 'color', value: any('red') }),
+
+          // First rule that uses the original value
+          rules([
+            decl({ name: 'background', value: ref('color', { type: 'variable', resolution: 'linear' }) })
+          ]),
+
+          // Nested rule that sets the variable with setDefined
+          rules([
+            vardecl({ name: 'color', value: any('blue') }, { setDefined: true })
+          ]),
+
+          // Subsequent rule that should use the updated value
+          rules([
+            decl({ name: 'border-color', value: ref('color', { type: 'variable', resolution: 'linear' }) })
+          ])
+        ]);
+
+        node = await node.eval(context);
+
+        // The first rule should use the original value (red) - setDefined shouldn't affect earlier references
+        let firstRule = node.at(1, context) as Rules; // First rule (background)
+        let firstDecl = firstRule.at(0, context) as Declaration;
+        let firstResult = await firstDecl.eval(context);
+        expect(`${firstResult}`).toBe('background: red');
+
+        // The last rule should also use the updated value (blue)
+        let lastRule = node.at(3, context) as Rules; // Last rule (border-color)
+        let lastDecl = lastRule.at(0, context) as Declaration;
+        let lastResult = await lastDecl.eval(context);
+        expect(`${lastResult}`).toBe('border-color: blue');
+
+        // The root should have the updated value
+        expect(`${getVar(node, 'color')}`).toBe('$color: blue');
+      });
+
+      it.skip('demonstrates Sass !global behavior with mixins - mixin resolves variables at include time', async () => {
+        // This test demonstrates the Sass behavior where:
+        // 1. A mixin is defined that uses a variable
+        // 2. The mixin is included before a !global assignment - it uses the original value
+        // 3. The mixin is included after a !global assignment - it uses the new value
+        //
+        // In Sass:
+        //   $color: red;
+        //   @mixin my-mixin() { color: $color; }
+        //   .box { color: $color; @include my-mixin(); }
+        //   .box2 { $color: blue !global; }
+        //   .box3 { color: $color; @include my-mixin(); }
+        //
+        // Output:
+        //   .box { color: red; color: red; }
+        //   .box3 { color: blue; color: blue; }
+        //
+        // This test demonstrates Sass !global behavior with mixins using call-time resolution.
+        //
+        // Solution implemented: `$~color` syntax for call-time resolution.
+        // - `$color` = scoped lookup (Less-style)
+        // - `$^color` = linear lookup from definition position (Sass-style for regular code)
+        // - `$~color` = linear lookup from call site position (Sass-style for mixins/functions)
+        //
+        // When a mixin uses `$~color`, the variable is resolved at the call site, allowing
+        // !global assignments to affect mixin behavior correctly.
+
+        let node = rules([
+          // Global variable declaration
+          vardecl({ name: 'color', value: any('red') }),
+
+          // Mixin definition that uses the variable with call-time resolution
+          // In Jess, this would be: my-mixin() { color: $~color; }
+          // This makes the mixin resolve the variable at call time, not definition time
+          mixin({
+            name: any('my-mixin'),
+            rules: rules([
+              decl({ name: 'color', value: ref('color', { type: 'variable', resolution: 'call-time' }) })
+            ], { rulesVisibility: { VarDeclaration: 'optional' } })
+          }),
+
+          // .box uses the variable directly and includes the mixin (both should be red)
+          ruleset({
+            selector: sellist([sel([el('.box')])]),
+            rules: rules([
+              decl({ name: 'color', value: ref('color', { type: 'variable', resolution: 'linear' }) }),
+              call({ name: ref('my-mixin', { type: 'mixin' }) })
+            ])
+          }),
+
+          // .box2 sets the variable with !global (setDefined)
+          ruleset({
+            selector: sellist([sel([el('.box2')])]),
+            rules: rules([
+              vardecl({ name: 'color', value: any('blue') }, { setDefined: true })
+            ])
+          }),
+
+          // .box3 uses the variable directly and includes the mixin (both should be blue)
+          ruleset({
+            selector: sellist([sel([el('.box3')])]),
+            rules: rules([
+              decl({ name: 'color', value: ref('color', { type: 'variable', resolution: 'linear' }) }),
+              call({ name: ref('my-mixin', { type: 'mixin' }) })
+            ])
+          })
+        ]);
+
+        node = await node.eval(context);
+
+        // Structure after eval: [vardecl (0), mixin (1), boxRuleset (2), box2Ruleset (3), box3Ruleset (4)]
+        // Access rulesets directly by index
+        let boxRuleset = node.at(2, context);
+        if (!boxRuleset || !isNode(boxRuleset, N.Ruleset)) {
+          throw new Error(`Expected Ruleset at index 2, got ${boxRuleset?.type || 'undefined'}`);
+        }
+        // After evaluation, rulesets are still Rulesets, access via .value.rules
+        let boxRules = boxRuleset.get('rules');
+        if (!boxRules) {
+          throw new Error('Expected .box ruleset to have rules');
+        }
+        // Rules is a Node with a value array, so use .value.length or check if it's a Rules node
+        if (!isNode(boxRules, N.Rules)) {
+          throw new Error(`Expected Rules, got ${(boxRules as any)?.type || 'undefined'}`);
+        }
+        expect(boxRules.value.length).toBe(2);
+
+        // First declaration: color: $color
+        let boxDecl1 = await boxRules.at(0, context)!.eval(context);
+        expect(`${boxDecl1}`).toBe('color: red');
+
+        // Second: mixin call
+        let boxMixinCall = boxRules.at(1, context);
+        if (!boxMixinCall) {
+          throw new Error('Expected mixin call at index 1');
+        }
+        let boxMixinResult = await boxMixinCall.eval(context);
+        // Mixin call returns Rules containing the mixin's rules
+        if (!isNode(boxMixinResult, N.Rules)) {
+          throw new Error('Expected mixin call to return Rules');
+        }
+        let boxMixinRules = boxMixinResult;
+        expect(boxMixinRules.value.length).toBeGreaterThan(0);
+        let boxMixinDecl = await boxMixinRules.at(0, context)!.eval(context);
+        expect(`${boxMixinDecl}`).toBe('color: red');
+
+        // Find the .box3 ruleset (index 4)
+        let box3Ruleset = node.at(4, context);
+        if (!box3Ruleset || !isNode(box3Ruleset, N.Ruleset)) {
+          throw new Error(`Expected Ruleset at index 4, got ${box3Ruleset?.type || 'undefined'}`);
+        }
+        let box3Rules = box3Ruleset.get('rules');
+        if (!box3Rules) {
+          throw new Error('Expected .box3 ruleset to have rules');
+        }
+        if (!isNode(box3Rules, N.Rules)) {
+          throw new Error(`Expected Rules, got ${(box3Rules as any)?.type || 'undefined'}`);
+        }
+        expect(box3Rules.value.length).toBe(2);
+
+        // First declaration: color: $color
+        let box3Decl1 = await box3Rules.at(0, context)!.eval(context);
+        expect(`${box3Decl1}`).toBe('color: blue');
+
+        // Second: mixin call
+        let box3MixinCall = box3Rules.at(1, context);
+        if (!box3MixinCall) {
+          throw new Error('Expected mixin call at index 1');
+        }
+        let box3MixinResult = await box3MixinCall.eval(context);
+        if (!isNode(box3MixinResult, N.Rules)) {
+          throw new Error('Expected mixin call to return Rules');
+        }
+        let box3MixinRules = box3MixinResult;
+        expect(box3MixinRules.value.length).toBeGreaterThan(0);
+        let box3MixinDecl = await box3MixinRules.at(0, context)!.eval(context);
+        // With call-time resolution ($~color), the mixin should resolve the variable
+        // at the call site, so it should be 'blue' (the value after !global assignment)
+        expect(`${box3MixinDecl}`).toBe('color: blue');
+
+        // The root should have the updated value
+        let rootColor = getVar(node, 'color');
+        if (!rootColor) {
+          throw new Error('Expected color variable to be defined');
+        }
+        expect(`${rootColor}`).toBe('$color: blue');
+      });
+
+      it('fails to set if existing variable is readonly', async () => {
+        let node = rules([
+          vardecl({ name: 'one', value: any('one') }, { readonly: true }),
+          rules([
+            vardecl({ name: 'one', value: any('three') }, { setDefined: true })
+          ])
+        ]);
+
+        await expect(async () => {
+          await node.eval(context);
+        }).rejects.toThrowError('"one" is readonly');
+      });
+
+      // @todo: Fix nested readonly rules inheritance - variables in nested readonly Rules aren't being found
+      it.skip('fails to set if existing variable is in readonly rules', async () => {
+        let node = rules([
+          rules([
+            vardecl({ name: 'one', value: any('one') })
+          ], {
+            readonly: true,
+            rulesVisibility: { VarDeclaration: 'public' }
+          }),
+          rules([
+            vardecl({ name: 'one', value: any('three') }, { setDefined: true })
+          ])
+        ]);
+
+        await expect(async () => {
+          await node.eval(context);
+        }).rejects.toThrowError('"one" is readonly');
+      });
+
+      // @todo: Fix nested readonly rules inheritance - variables in nested readonly Rules aren't being found
+      it.skip('fails to set if existing variable is in nested readonly rules #1', async () => {
+        let node = rules([
+          rules([
+            rules([
+              vardecl({ name: 'one', value: any('one') })
+            ], {
+              readonly: true,
+              rulesVisibility: { VarDeclaration: 'public' }
+            })
+          ], {
+            rulesVisibility: { VarDeclaration: 'public' }
+          }),
+          rules([
+            vardecl({ name: 'one', value: any('three') }, { setDefined: true })
+          ])
+        ]);
+
+        await expect(async () => {
+          await node.eval(context);
+        }).rejects.toThrowError('"one" is readonly');
+      });
+
+      // @todo: Fix nested readonly rules inheritance - variables in nested readonly Rules aren't being found
+      it.skip('fails to set if existing variable is in nested readonly rules #2', async () => {
+        let node = rules([
+          rules([
+            rules([
+              vardecl({ name: 'one', value: any('one') })
+            ], {
+              rulesVisibility: { VarDeclaration: 'public' }
+            })
+          ], {
+            readonly: true,
+            rulesVisibility: { VarDeclaration: 'public' }
+          }),
+          rules([
+            vardecl({ name: 'one', value: any('three') }, { setDefined: true })
+          ])
+        ]);
+
+        await expect(async () => {
+          await node.eval(context);
+        }).rejects.toThrowError('"one" is readonly');
+      });
+
+      it('doesn\'t preserve readonly later', async () => {
+        let node = rules([
+          rules([
+            vardecl({ name: 'one', value: any('one') })
+          ], {
+            readonly: true,
+            rulesVisibility: { VarDeclaration: 'public' }
+          }),
+          rules([
+            vardecl({ name: 'one', value: any('two') })
+          ], {
+            rulesVisibility: { VarDeclaration: 'public' }
+          }),
+          rules([
+            /** This will set after the second rules value */
+            vardecl({ name: 'one', value: any('three') }, { setDefined: true })
+          ])
+        ]);
+
+        const result = node.eval(context);
+        if (result instanceof Promise) {
+          await expect(result).resolves.not.toThrow();
+        } else {
+          // Synchronous result, no error thrown
+          expect(result).toBeDefined();
+        }
+      });
+
+      it('looks upwards from position', async () => {
+        let node = rules([
+          vardecl({ name: 'one', value: any('one') }),
+          vardecl({ name: 'one', value: any('two') }),
+          vardecl({ name: 'one', value: any('three') })
+        ]);
+        node = await node.eval(context);
+
+        expect(`${getVar(node, 'one', { start: node.at(1, context)?.index })}`).toBe('$one: one');
+        expect(`${getVar(node, 'one', { start: node.at(2, context)?.index })}`).toBe('$one: two');
+        expect(`${getVar(node, 'one', { start: 10 })}`).toBe('$one: three');
+      });
+
+      it('won\'t find variables in sub-rules of local rules', async () => {
+        let node = rules([ // root.jess
+          rules([ // @-compose('child1.jess')
+            vardecl({ name: 'foo', value: any('bar') }),
+            rules([ // @-compose('child2.jess')
+              vardecl({ name: 'one', value: any('two') })
+            ], {
+              local: true,
+              rulesVisibility: { VarDeclaration: 'public' }
+            })
+          ], {
+            local: true,
+            rulesVisibility: { VarDeclaration: 'public' }
+          })
+        ]);
+        node = await node.eval(context);
+
+        // child1.jess should see child2.jess's vars because it owns the `@use`
+        expect(`${getVar(node.at(0, context) as Rules, 'one')}`).toBe('$one: two');
+        // child1.jess can still see its own vars
+        expect(`${getVar(node.at(0, context) as Rules, 'foo')}`).toBe('$foo: bar');
+        // root.jess can see child1.jess's vars but not child2.jess's
+        expect(`${getVar(node, 'foo')}`).toBe('$foo: bar');
+        expect(getVar(node, 'one')).toBeUndefined();
+      });
+    });
+  });
+
+  /** IT IS TIME */
+  // describe('lookup selectors', () => {
+  //   it('can lookup a simple ruleset', async () => {
+  //     let node = rules([
+  //       ruleset({
+  //         selector: el('.foo'),
+  //         rules: rules([
+  //           decl({ name: 'foo', value: any('bar') })
+  //         ])
+  //       })
+  //     ]);
+  //     node = await node.eval(context);
+
+  //     expect(getSelector(node, 'foo')).toBe('foo: bar');
+  //   });
+  // });
+
+  it('should flatten rules when serializing', async () => {
+    let node = rules([
+      ruleset({
+        selector: sellist([sel([el('.collapse')])]),
+        rules: rules([
+          decl({ name: 'chungus', value: spaced([any('foo'), any('bar')]) }),
+          rules([
+            decl({ name: 'bird', value: spaced([any('in'), any('hand')]) })
+          ])
+        ])
+      })
+    ]);
+    let evald = await node.eval(context);
+    expect(evald.render(context)).toBe('.collapse {\n  chungus: foo bar;\n  bird: in hand;\n}\n');
+  });
+
+  // Deleted: registry cache tests — tested globalRegistryCache infrastructure
+  // which was removed in the NodeState-scoped registry refactor.
+
+  describe.skip('eval state registry delta — registry deltas removed with EvalSession', () => {
+    it('prefers state-only declaration entries over the canonical cache', () => {
+      const root = rules([
+        vardecl({ name: 'foo', value: any('bar') })
+      ]);
+      const ctx = new Context();
+      const injected = vardecl({ name: 'bar', value: any('baz') });
+
+      root.getRegistry('declaration');
+      root.register('declaration', injected, ctx);
+
+      expect(root.find('declaration', 'bar', 'VarDeclaration', {
+        context: ctx,
+        searchParents: false
+      })).toBe(injected);
+      expect(root.find('declaration', 'bar', 'VarDeclaration', {
+        searchParents: false
+      })).toBeUndefined();
+    });
+
+    it('clears state-only registry entries when the scope is marked dirty', () => {
+      const root = rules([
+        vardecl({ name: 'foo', value: any('bar') })
+      ]);
+      const ctx = new Context();
+      const injected = vardecl({ name: 'bar', value: any('baz') });
+
+      root.getRegistry('declaration');
+      root.register('declaration', injected, ctx);
+      markScopeDirty(root, ctx);
+
+      expect(root.find('declaration', 'bar', 'VarDeclaration', {
+        context: ctx,
+        searchParents: false
+      })).toBeUndefined();
+    });
+
+    it('keeps canonical parent pointers intact when unshifting shared nodes', () => {
+      const shared = vardecl({ name: 'foo', value: any('bar') });
+      const source = rules([shared]);
+      const target = rules([]);
+      const ctx = new Context();
+      target.unshift(ctx, shared);
+
+      expect(shared.parent).toBe(source);
+      expect(getParent(shared, ctx)).toBe(target);
+    });
+
+    it('keeps canonical parent pointers intact when splicing shared nodes', () => {
+      const shared = vardecl({ name: 'foo', value: any('bar') });
+      const source = rules([shared]);
+      const target = rules([]);
+      const ctx = new Context();
+      target.splice(ctx, 0, 0, shared);
+
+      expect(shared.parent).toBe(source);
+      expect(getParent(shared, ctx)).toBe(target);
+    });
+
+    it('keeps canonical children intact when unshifting', () => {
+      const original = vardecl({ name: 'foo', value: any('bar') });
+      const inserted = vardecl({ name: 'bar', value: any('baz') });
+      const target = rules([original]);
+      const ctx = new Context();
+      target.unshift(ctx, inserted);
+
+      expect(target.value).toHaveLength(1);
+      expect(target.at(0, context)).toBe(original);
+      expect(target.at(0, ctx)).toBe(inserted);
+      expect(target.at(1, ctx)).toBe(original);
+      expect(inserted.parent).toBeUndefined();
+      expect(getParent(inserted, ctx)).toBe(target);
+    });
+
+    it('keeps canonical children intact when splicing', () => {
+      const original = vardecl({ name: 'foo', value: any('bar') });
+      const replacement = vardecl({ name: 'bar', value: any('baz') });
+      const target = rules([original]);
+      const ctx = new Context();
+      const removed = target.splice(ctx, 0, 1, replacement);
+
+      expect(removed).toEqual([original]);
+      expect(target.value).toHaveLength(1);
+      expect(target.at(0, context)).toBe(original);
+      expect(target.at(0, ctx)).toBe(replacement);
+      expect(replacement.parent).toBeUndefined();
+      expect(getParent(replacement, ctx)).toBe(target);
+    });
+
+    it('preEval keeps charset replacement parented only in the eval state', async () => {
+      const charset = any('@charset "utf-8"', { role: 'charset' });
+      const root = rules([charset]);
+      const ctx = new Context();
+      const preEvald = await root.preEval(ctx);
+      const replaced = preEvald.at(0, ctx);
+
+      expect(isNode(replaced as Node, N.Nil)).toBe(true);
+      expect(getParent(replaced as Node, ctx)).toBe(root);
+      expect((replaced as Node).parent).toBeUndefined();
+      expect(preEvald.at(0, context)).toBe(charset);
+      expect(root.value[0]).toBe(charset);
+      expect(ctx.currentCharset).toBe(charset);
+    });
+    it('coalesces merged declarations using state-parent scope boundaries', async () => {
+      const base = decl({ name: 'color', value: any('red') });
+      const merged = decl(
+        { name: 'color', value: any('blue') },
+        { assign: AssignmentType.Add }
+      );
+      const root = rules([base, merged]);
+      const foreignScope = rules([]);
+      const ctx = new Context();
+      const preEvald = await root.preEval(ctx);
+      const mergedPreEvald = preEvald.at(1, ctx);
+      if (!mergedPreEvald) {
+        throw new Error('Expected merged declaration at index 1');
+      }
+      setParent(mergedPreEvald, foreignScope, ctx);
+
+      const evald = await preEvald.eval(ctx);
+      const mergedEvald = evald.at(1, ctx);
+
+      expect(mergedEvald?.toTrimmedString({ context: ctx })).toBe('color: red, blue');
+      expect(merged.toTrimmedString()).toContain('+:');
+    });
+
+    it('preEval keeps cloned Rules parents in the eval state on eval reset', async () => {
+      const child = rules([
+        decl({ name: 'color', value: any('red') })
+      ]);
+      const root = rules([child]);
+      const ctx = new Context();
+      const preEvald = await child.preEval(ctx);
+
+      expect(preEvald).not.toBe(child);
+      expect(getParent(preEvald as Rules, ctx)).toBe(root);
+      expect((preEvald as Rules).parent).toBeUndefined();
+    });
+
+    it('preEval detects nestable at-rule wrappers through the state parent chain', async () => {
+      const wrapper = rules([
+        ruleset({
+          selector: amp(),
+          rules: rules([
+            decl({ name: 'color', value: any('red') })
+          ])
+        })
+      ]);
+      const media = atrule({
+        name: any('@media', { role: 'atkeyword' }),
+        prelude: any('screen')
+      });
+      const ctx = new Context();
+      setParent(wrapper, media, ctx);
+      const preEvald = await wrapper.preEval(ctx);
+
+      expect(preEvald).toBe(wrapper);
+      expect(getParent(wrapper, ctx)).toBe(media);
+      expect(wrapper.parent).toBeUndefined();
+    });
+
+    it('reorders call-produced declaration-only Rules using the state sourceParent without mutating canonical children', () => {
+      const nested = ruleset({
+        selector: sellist([sel([el('.nested')])]),
+        rules: rules([
+          decl({ name: any('color'), value: any('red') })
+        ])
+      });
+      const callProduced = rules([
+        decl({ name: any('margin'), value: any('0') })
+      ]);
+      const root = rules([nested, callProduced]);
+      const caller = call({ name: any('each') });
+      const ctx = new Context();
+      setSourceParent(callProduced, caller, ctx);
+      (root as any)._normalizeCallDeclarationRulesOrder(root, ctx);
+
+      expect(getSourceParent(callProduced, ctx)).toBe(caller);
+      expect(callProduced.sourceParent).toBeUndefined();
+      expect(getChildren(root, ctx)[0]).toBe(callProduced);
+      expect(root.value[0]).toBe(nested);
+      expect(root.value[1]).toBe(callProduced);
+    });
+  });
+});