smiles-js 2.0.2 → 2.1.0

package/src/manipulation.test.js

@@ -1,5 +1,10 @@
 import { describe, test, expect } from 'bun:test';
-import { Ring, Linear, Molecule } from './constructors.js';
+import {
+  Ring, Linear, Molecule,
+} from './constructors.js';
+import {
+  repeat, fusedRepeat, linearMirror, moleculeMirror, ringMirror,
+} from './manipulation.js';
 
 describe('Ring.attach()', () => {
   test('attaches a linear chain to a ring', () => {
@@ -442,3 +447,356 @@ describe('Molecule methods', () => {
     expect(updated.components[1]).toBe(benzene);
   });
 });
+
+describe('repeat()', () => {
+  test('Linear repeat n=1 returns clone', () => {
+    const ethylene = Linear(['C', 'C']);
+    const result = ethylene.repeat(1, 1, 2);
+    expect(result.smiles).toBe('CC');
+    expect(result.type).toBe('linear');
+  });
+
+  test('Linear repeat n=3 (polyethylene trimer)', () => {
+    const ethylene = Linear(['C', 'C']);
+    const result = ethylene.repeat(3, 1, 2);
+    expect(result.smiles).toBe('CCCCCC');
+  });
+
+  test('Linear with attachments repeat preserves branches', () => {
+    const styrene = Linear(['C', 'C']).attach(2, Ring({ atoms: 'c', size: 6 }));
+    const dimer = styrene.repeat(2, 1, 2);
+    expect(dimer.smiles).toBe('CC(c1ccccc1)CC(c2ccccc2)');
+  });
+
+  test('Linear with attachments repeat trimer', () => {
+    const styrene = Linear(['C', 'C']).attach(2, Ring({ atoms: 'c', size: 6 }));
+    const trimer = styrene.repeat(3, 1, 2);
+    expect(trimer.smiles).toBe('CC(c1ccccc1)CC(c2ccccc2)CC(c3ccccc3)');
+  });
+
+  test('Ring repeat n=1 returns clone', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const result = benzene.repeat(1, 1, 6);
+    expect(result.smiles).toBe('c1ccccc1');
+    expect(result.type).toBe('ring');
+  });
+
+  test('Ring repeat n=2 (biphenyl)', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const result = benzene.repeat(2, 1, 6);
+    expect(result.smiles).toBe('c1ccccc1c2ccccc2');
+  });
+
+  test('Ring repeat n=3 (terphenyl)', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const result = benzene.repeat(3, 1, 6);
+    expect(result.smiles).toBe('c1ccccc1c2ccccc2c3ccccc3');
+  });
+
+  test('Ring with substitutions repeat', () => {
+    const pyridine = Ring({ atoms: 'c', size: 6, substitutions: { 3: 'n' } });
+    const result = pyridine.repeat(2, 1, 6);
+    expect(result.smiles).toBe('c1cnccc1c2cnccc2');
+  });
+
+  test('repeat does not modify original', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    benzene.repeat(3, 1, 6);
+    expect(benzene.smiles).toBe('c1ccccc1');
+    expect(benzene.ringNumber).toBe(1);
+  });
+
+  test('repeat throws for n < 1', () => {
+    const ethylene = Linear(['C', 'C']);
+    expect(() => ethylene.repeat(0, 1, 2)).toThrow('Repeat count n must be an integer >= 1');
+  });
+
+  test('repeat throws for invalid leftId', () => {
+    const ethylene = Linear(['C', 'C']);
+    expect(() => ethylene.repeat(2, 0, 2)).toThrow('leftId must be a positive integer');
+  });
+
+  test('repeat throws for invalid rightId', () => {
+    const ethylene = Linear(['C', 'C']);
+    expect(() => ethylene.repeat(2, 1, 0)).toThrow('rightId must be a positive integer');
+  });
+
+  test('Molecule repeat', () => {
+    const unit = Molecule([Linear(['C']), Ring({ atoms: 'c', size: 6 })]);
+    const dimer = unit.repeat(2, 1, 1);
+    expect(dimer.type).toBe('molecule');
+    expect(dimer.smiles).toBe('Cc1ccccc1Cc2ccccc2');
+  });
+
+  test('functional API repeat()', () => {
+    const ethylene = Linear(['C', 'C']);
+    const result = repeat(ethylene, 3, 1, 2);
+    expect(result.smiles).toBe('CCCCCC');
+  });
+});
+
+describe('fusedRepeat()', () => {
+  test('fusedRepeat n=1 returns ring clone', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const result = benzene.fusedRepeat(1, 4);
+    expect(result.smiles).toBe('c1ccccc1');
+    expect(result.type).toBe('ring');
+  });
+
+  test('fusedRepeat n=2 (naphthalene)', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const result = benzene.fusedRepeat(2, 4);
+    expect(result.type).toBe('fused_ring');
+    expect(result.rings).toHaveLength(2);
+  });
+
+  test('fusedRepeat n=3 (anthracene)', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const result = benzene.fusedRepeat(3, 4);
+    expect(result.type).toBe('fused_ring');
+    expect(result.rings).toHaveLength(3);
+  });
+
+  test('fusedRepeat does not modify original', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    benzene.fusedRepeat(3, 4);
+    expect(benzene.smiles).toBe('c1ccccc1');
+    expect(benzene.type).toBe('ring');
+  });
+
+  test('fusedRepeat throws for non-ring', () => {
+    expect(() => fusedRepeat(Linear(['C', 'C']), 2, 4)).toThrow('fusedRepeat requires a Ring node');
+  });
+
+  test('fusedRepeat throws for n < 1', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    expect(() => benzene.fusedRepeat(0, 4)).toThrow('Repeat count n must be an integer >= 1');
+  });
+
+  test('fusedRepeat throws for invalid offset', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    expect(() => benzene.fusedRepeat(2, 0)).toThrow('Fusion offset must be a positive integer');
+  });
+
+  test('functional API fusedRepeat()', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const result = fusedRepeat(benzene, 2, 4);
+    expect(result.type).toBe('fused_ring');
+    expect(result.rings).toHaveLength(2);
+  });
+
+  test('fusedRepeat with substitutions', () => {
+    const ring = Ring({ atoms: 'C', size: 6, substitutions: { 3: 'N' } });
+    const result = ring.fusedRepeat(2, 4);
+    expect(result.type).toBe('fused_ring');
+    expect(result.rings).toHaveLength(2);
+  });
+});
+
+describe('linearMirror()', () => {
+  test('simple chain mirror (diethyl ether)', () => {
+    const half = Linear(['C', 'C', 'O']);
+    const result = half.mirror();
+    expect(result.smiles).toBe('CCOCC');
+  });
+
+  test('default pivot is last atom', () => {
+    const half = Linear(['C', 'C', 'C', 'N']);
+    const result = half.mirror();
+    expect(result.smiles).toBe('CCCNCCC');
+  });
+
+  test('explicit pivot in the middle', () => {
+    const chain = Linear(['C', 'C', 'C', 'O', 'C']);
+    const result = chain.mirror(4);
+    expect(result.smiles).toBe('CCCOCCC');
+  });
+
+  test('single atom mirror returns clone', () => {
+    const single = Linear(['O']);
+    const result = single.mirror();
+    expect(result.smiles).toBe('O');
+  });
+
+  test('two atoms mirror (pivot at 2)', () => {
+    const two = Linear(['C', 'O']);
+    const result = two.mirror();
+    expect(result.smiles).toBe('COC');
+  });
+
+  test('mirrors bonds correctly', () => {
+    const half = Linear(['C', 'C', 'O'], ['=']);
+    const result = half.mirror();
+    expect(result.smiles).toBe('C=COC=C');
+  });
+
+  test('mirrors multiple bond types', () => {
+    const half = Linear(['C', 'C', 'N', 'O'], ['=', '#']);
+    const result = half.mirror();
+    expect(result.smiles).toBe('C=C#NON#C=C');
+  });
+
+  test('mirrors attachments with ring renumbering', () => {
+    const half = Linear(['C', 'C', 'O']).attach(
+      1,
+      Ring({ atoms: 'c', size: 6 }),
+    );
+    const result = half.mirror();
+    expect(result.smiles).toBe('C(c1ccccc1)COCC(c2ccccc2)');
+  });
+
+  test('does not modify original', () => {
+    const half = Linear(['C', 'C', 'O']);
+    half.mirror();
+    expect(half.smiles).toBe('CCO');
+  });
+
+  test('throws for invalid pivotId', () => {
+    const chain = Linear(['C', 'C', 'O']);
+    expect(() => chain.mirror(0)).toThrow();
+    expect(() => chain.mirror(4)).toThrow();
+  });
+
+  test('functional API linearMirror()', () => {
+    const half = Linear(['C', 'C', 'O']);
+    const result = linearMirror(half);
+    expect(result.smiles).toBe('CCOCC');
+  });
+});
+
+describe('moleculeMirror()', () => {
+  test('ABA triblock copolymer', () => {
+    const A = Linear(['C', 'C']);
+    const B = Ring({ atoms: 'c', size: 6 });
+    const AB = Molecule([A, B]);
+    const result = AB.mirror();
+    expect(result.smiles).toBe('CCc1ccccc1CC');
+  });
+
+  test('ABCBA from ABC', () => {
+    const block = Molecule([
+      Linear(['C', 'C']),
+      Ring({ atoms: 'c', size: 6 }),
+      Linear(['O']),
+    ]);
+    const result = block.mirror();
+    expect(result.smiles).toBe('CCc1ccccc1Oc2ccccc2CC');
+  });
+
+  test('default pivot is last component', () => {
+    const mol = Molecule([Linear(['C']), Linear(['N']), Linear(['O'])]);
+    const result = mol.mirror();
+    expect(result.smiles).toBe('CNONC');
+  });
+
+  test('explicit pivot at component 0 returns clone of single', () => {
+    const mol = Molecule([Linear(['C']), Linear(['N'])]);
+    const result = mol.mirror(0);
+    expect(result.smiles).toBe('C');
+    expect(result.components).toHaveLength(1);
+  });
+
+  test('explicit pivot at middle component', () => {
+    const mol = Molecule([Linear(['C']), Linear(['N']), Linear(['O'])]);
+    const result = mol.mirror(1);
+    expect(result.smiles).toBe('CNC');
+  });
+
+  test('does not modify original', () => {
+    const mol = Molecule([Linear(['C']), Linear(['N'])]);
+    mol.mirror();
+    expect(mol.smiles).toBe('CN');
+    expect(mol.components).toHaveLength(2);
+  });
+
+  test('throws for invalid pivotComponent', () => {
+    const mol = Molecule([Linear(['C']), Linear(['N'])]);
+    expect(() => mol.mirror(-1)).toThrow();
+    expect(() => mol.mirror(2)).toThrow();
+  });
+
+  test('functional API moleculeMirror()', () => {
+    const mol = Molecule([Linear(['C']), Ring({ atoms: 'c', size: 6 })]);
+    const result = moleculeMirror(mol);
+    expect(result.smiles).toBe('Cc1ccccc1C');
+  });
+});
+
+describe('ringMirror()', () => {
+  test('mirrors substitution (pyrimidine from pyridine)', () => {
+    const pyridine = Ring({
+      atoms: 'c',
+      size: 6,
+      substitutions: { 2: 'n' },
+    });
+    const result = pyridine.mirror(1);
+    // pos 2 mirrors to pos 6 around pivot 1
+    expect(result.substitutions).toEqual({ 2: 'n', 6: 'n' });
+  });
+
+  test('mirrors attachment to symmetric position', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const mono = benzene.attach(2, Linear(['C']));
+    const result = mono.mirror(1);
+    // pos 2 mirrors to pos 6 around pivot 1
+    expect(result.attachments[2]).toHaveLength(1);
+    expect(result.attachments[6]).toHaveLength(1);
+  });
+
+  test('meta substitution pattern via mirror', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const mono = benzene.attach(2, Linear(['C']));
+    const result = mono.mirror(3);
+    // pos 2 mirrors to pos 4 around pivot 3
+    expect(result.smiles).toBe('c1c(C)cc(C)cc1');
+  });
+
+  test('attachment at pivot stays (no duplication)', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const mono = benzene.attach(1, Linear(['C']));
+    const result = mono.mirror(1);
+    // pos 1 is the pivot, mirrors to self → no duplicate
+    expect(result.attachments[1]).toHaveLength(1);
+  });
+
+  test('default pivot is 1', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const mono = benzene.attach(2, Linear(['C']));
+    const result = mono.mirror();
+    // default pivot=1, pos 2 mirrors to pos 6
+    expect(result.attachments[2]).toHaveLength(1);
+    expect(result.attachments[6]).toHaveLength(1);
+  });
+
+  test('ring renumbering in mirrored attachments', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const mono = benzene.attach(2, Ring({ atoms: 'c', size: 5 }));
+    const result = mono.mirror(1);
+    // Attachment at pos 2 has ring with ringNumber=1
+    // Mirrored attachment at pos 6 should have ringNumber=2 (shifted)
+    const origAtt = result.attachments[2][0];
+    const mirrorAtt = result.attachments[6][0];
+    expect(origAtt.ringNumber).toBe(1);
+    expect(mirrorAtt.ringNumber).toBe(2);
+  });
+
+  test('does not modify original', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const mono = benzene.attach(2, Linear(['C']));
+    mono.mirror(1);
+    expect(mono.attachments[6]).toBeUndefined();
+  });
+
+  test('throws for invalid pivotId', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    expect(() => benzene.mirror(0)).toThrow();
+    expect(() => benzene.mirror(7)).toThrow();
+  });
+
+  test('functional API ringMirror()', () => {
+    const benzene = Ring({ atoms: 'c', size: 6 });
+    const mono = benzene.attach(2, Linear(['C']));
+    const result = ringMirror(mono, 3);
+    expect(result.smiles).toBe('c1c(C)cc(C)cc1');
+  });
+});

package/src/method-attachers.js

@@ -29,6 +29,11 @@ import {
   moleculeConcat,
   moleculeGetComponent,
   moleculeReplaceComponent,
+  repeat,
+  fusedRepeat,
+  linearMirror,
+  moleculeMirror,
+  ringMirror,
 } from './manipulation.js';
 
 /**
@@ -72,6 +77,15 @@ export function attachRingMethods(node) {
     addSequentialRings(seqRings, options) {
       return fusedRingAddSequentialRings(this, seqRings, options);
     },
+    repeat(n, leftId, rightId) {
+      return repeat(this, n, leftId, rightId);
+    },
+    fusedRepeat(n, offset) {
+      return fusedRepeat(this, n, offset);
+    },
+    mirror(pivotId) {
+      return ringMirror(this, pivotId);
+    },
     toObject() {
       const result = {
         type: this.type,
@@ -109,6 +123,12 @@ export function attachLinearMethods(node) {
     concat(other) {
       return linearConcat(this, other);
     },
+    repeat(n, leftId, rightId) {
+      return repeat(this, n, leftId, rightId);
+    },
+    mirror(pivotId) {
+      return linearMirror(this, pivotId);
+    },
     clone() {
       return deepCloneLinear(this);
     },
@@ -148,6 +168,12 @@ export function attachMoleculeMethods(node) {
     replaceComponent(index, newComponent) {
       return moleculeReplaceComponent(this, index, newComponent);
     },
+    repeat(n, leftId, rightId) {
+      return repeat(this, n, leftId, rightId);
+    },
+    mirror(pivotComponent) {
+      return moleculeMirror(this, pivotComponent);
+    },
     clone() {
       return deepCloneMolecule(this);
     },
@@ -190,6 +216,9 @@ export function attachFusedRingMethods(node) {
     concat(other) {
       return fusedRingConcat(this, other);
     },
+    repeat(n, leftId, rightId) {
+      return repeat(this, n, leftId, rightId);
+    },
     clone() {
       return deepCloneFusedRing(this);
     },

package/src/node-creators.js

@@ -88,6 +88,7 @@ export function createFusedRingNode(rings, options = {}) {
       const atomValueMap = new Map();
       const bondMap = new Map();
       const ringOrderMap = new Map();
+      const branchIdMap = new Map();
 
       // Extract ring nodes from metadata - only extract core data fields, not methods
       const extractedRings = metadata.rings.map((ringMeta) => ringMeta.ring);
@@ -141,6 +142,7 @@ export function createFusedRingNode(rings, options = {}) {
               if (atom.value !== undefined) atomValueMap.set(atom.position, atom.value);
               if (atom.bond !== undefined) bondMap.set(atom.position, atom.bond);
               if (atom.rings !== undefined) ringOrderMap.set(atom.position, atom.rings);
+              if (atom.branchId !== undefined) branchIdMap.set(atom.position, atom.branchId);
             });
           }
 
@@ -163,6 +165,7 @@ export function createFusedRingNode(rings, options = {}) {
       node.metaAtomValueMap = atomValueMap;
       node.metaBondMap = bondMap;
       if (ringOrderMap.size > 0) node.metaRingOrderMap = ringOrderMap;
+      if (branchIdMap.size > 0) node.metaBranchIdMap = branchIdMap;
     }
 
     // Support standalone atoms format (atoms that are not part of any ring)
@@ -198,6 +201,10 @@ export function createFusedRingNode(rings, options = {}) {
         if (atom.depth !== undefined) node.metaBranchDepthMap.set(atom.position, atom.depth);
         if (atom.value !== undefined) node.metaAtomValueMap.set(atom.position, atom.value);
         if (atom.bond !== undefined) node.metaBondMap.set(atom.position, atom.bond);
+        if (atom.branchId !== undefined) {
+          if (!node.metaBranchIdMap) node.metaBranchIdMap = new Map();
+          node.metaBranchIdMap.set(atom.position, atom.branchId);
+        }
         if (atom.attachments) {
           if (!node.metaSeqAtomAttachments) node.metaSeqAtomAttachments = new Map();
           node.metaSeqAtomAttachments.set(atom.position, atom.attachments);

package/src/parser/ast-builder.js

@@ -236,19 +236,34 @@ export function buildAST(atoms, ringBoundaries) {
     return Molecule([]);
   }
 
-  const mainChainRings = ringBoundaries.filter((r) => r.branchDepth === 0);
+  // Include rings that are on the main chain (branchDepth 0) or that have
+  // any positions on the main chain (depth 0 atoms in their path)
+  const mainChainRings = ringBoundaries.filter(
+    (r) => r.branchDepth === 0
+      || r.positions.some((pos) => atoms[pos].branchDepth === 0),
+  );
 
-  const mainChainPositions = new Set();
+  const knownPositions = new Set();
   mainChainRings.forEach((r) => {
-    r.positions.forEach((pos) => mainChainPositions.add(pos));
+    r.positions.forEach((pos) => knownPositions.add(pos));
   });
 
-  const bridgeRings = ringBoundaries.filter((r) => {
-    if (r.branchDepth === 0) return false;
-    return r.positions.some((pos) => mainChainPositions.has(pos));
-  });
+  // Iteratively discover bridge rings — rings that share atoms with already-known positions
+  const includedRings = new Set(mainChainRings.map((r) => r.ringNumber));
+  let foundNew = true;
+  while (foundNew) {
+    foundNew = false;
+    ringBoundaries.forEach((r) => {
+      if (includedRings.has(r.ringNumber)) return;
+      if (r.positions.some((pos) => knownPositions.has(pos))) {
+        includedRings.add(r.ringNumber);
+        r.positions.forEach((pos) => knownPositions.add(pos));
+        foundNew = true;
+      }
+    });
+  }
 
-  const ringsToGroup = [...mainChainRings, ...bridgeRings];
+  const ringsToGroup = ringBoundaries.filter((r) => includedRings.has(r.ringNumber));
   const fusedGroups = groupFusedRings(ringsToGroup);
 
   const atomToGroup = new Map();

package/src/parser/ring-group-builder.js

@@ -87,7 +87,12 @@ export function buildSingleRingNodeWithContext(
     const ringBranchDepth = ringAtoms[0]?.branchDepth ?? 0;
     excludedPositions = new Set();
     ringBoundaries.forEach((rb) => {
-      if (rb.branchDepth === ringBranchDepth) {
+      // Exclude rings at the same branch depth OR rings that have any position
+      // at this depth (cross-depth rings like ring 2 in C1C(C1)(C2)CC2)
+      const hasAtomAtDepth = rb.positions.some(
+        (pos) => atoms[pos].branchDepth === ringBranchDepth,
+      );
+      if (rb.branchDepth === ringBranchDepth || hasAtomAtDepth) {
         rb.positions.forEach((pos) => excludedPositions.add(pos));
       }
     });
@@ -144,6 +149,7 @@ export function buildSingleRingNodeWithContext(
           if (hasVaryingDepths) {
             node.metaIsSibling = !ringPathBranchIdsAfter.has(group.branchId);
           }
+          node.metaBranchId = group.branchId;
 
           return node;
         },
@@ -167,6 +173,7 @@ export function buildSingleRingNodeWithContext(
   ringNode.metaEnd = ring.end;
   ringNode.metaBranchDepths = ringAtoms.map((a) => a.branchDepth);
   ringNode.metaParentIndices = ringAtoms.map((a) => a.parentIndex);
+  ringNode.metaBranchIds = ringAtoms.map((a) => a.branchId);
 
   // Store leading bond if the first ring atom has a bond
   const firstRingAtom = ringAtoms[0];
@@ -305,14 +312,16 @@ function buildMetadataMaps(positions, atoms) {
   const parentIndexMap = new Map();
   const atomValueMap = new Map();
   const bondMap = new Map();
+  const branchIdMap = new Map();
   positions.forEach((pos) => {
     branchDepthMap.set(pos, atoms[pos].branchDepth);
     parentIndexMap.set(pos, atoms[pos].parentIndex);
     atomValueMap.set(pos, atoms[pos].rawValue);
     bondMap.set(pos, atoms[pos].bond);
+    branchIdMap.set(pos, atoms[pos].branchId);
   });
   return {
-    branchDepthMap, parentIndexMap, atomValueMap, bondMap,
+    branchDepthMap, parentIndexMap, atomValueMap, bondMap, branchIdMap,
   };
 }
 
@@ -390,6 +399,7 @@ function assembleFusedRingNode(
     fusedNode.metaParentIndexMap = maps.parentIndexMap;
     fusedNode.metaAtomValueMap = maps.atomValueMap;
     fusedNode.metaBondMap = maps.bondMap;
+    fusedNode.metaBranchIdMap = maps.branchIdMap;
 
     // Include sequential ring positions
     seqRingNodes.forEach((seqRing) => {
@@ -401,6 +411,7 @@ function assembleFusedRingNode(
           maps.parentIndexMap.set(pos, atoms[pos].parentIndex);
           maps.atomValueMap.set(pos, atoms[pos].rawValue);
           maps.bondMap.set(pos, atoms[pos].bond);
+          maps.branchIdMap.set(pos, atoms[pos].branchId);
         }
       });
     });
@@ -426,6 +437,7 @@ function assembleFusedRingNode(
   fusedNode.metaParentIndexMap = maps.parentIndexMap;
   fusedNode.metaAtomValueMap = maps.atomValueMap;
   fusedNode.metaBondMap = maps.bondMap;
+  fusedNode.metaBranchIdMap = maps.branchIdMap;
 
   // Ring order map — tracks which ring markers appear at each position
   const ringOrderMap = new Map();

package/src/parser/ring-utils.js

@@ -90,10 +90,25 @@ export function collectRingPath(
   const innerRings = findInnerFusedRings(startIdx, endIdx, atoms, branchDepth, closedRings);
   const endAtom = atoms[endIdx];
   const ringEntersDeepBranch = endAtom && endAtom.branchDepth > branchDepth;
+  const ringExitsToShallowerDepth = endAtom && endAtom.branchDepth < branchDepth;
   const ringPathBranchIds = ringEntersDeepBranch
     ? traceRingPathBranchIds(endAtom, branchDepth, atoms)
     : new Set();
 
+  // When ring exits to a shallower depth, trace from start atom to find branch IDs
+  // that contain the start, and also include atoms at the shallower end depth
+  const exitBranchIds = new Set();
+  if (ringExitsToShallowerDepth) {
+    let traceAtom = atoms[startIdx];
+    while (traceAtom && traceAtom.branchDepth > endAtom.branchDepth) {
+      if (traceAtom.branchId !== null) {
+        exitBranchIds.add(traceAtom.branchId);
+      }
+      const parentIdx = traceAtom.parentIndex;
+      traceAtom = parentIdx !== null ? atoms[parentIdx] : null;
+    }
+  }
+
   let idx = startIdx;
   while (idx <= endIdx) {
     const atom = atoms[idx];
@@ -105,6 +120,19 @@ export function collectRingPath(
       if (innerRing) {
         positions.push(idx);
         idx = innerRing.end;
+      } else if (ringExitsToShallowerDepth) {
+        // For rings that exit to shallower depth:
+        // Include atoms at the start's branch context OR at the end's depth
+        const inStartBranch = atom.branchDepth === branchDepth
+          && (branchDepth === 0 || atom.branchId === branchId);
+        const inExitBranch = exitBranchIds.has(atom.branchId);
+        const atEndDepth = atom.branchDepth === endAtom.branchDepth
+          && (endAtom.branchDepth === 0
+            || isInSameBranchContext(atom, endAtom, atoms));
+        if (inStartBranch || inExitBranch || atEndDepth) {
+          positions.push(idx);
+        }
+        idx += 1;
       } else {
         const startAtom = atoms[startIdx];
         if (shouldIncludeAtomInRing(

package/test-integration/__snapshots__/adjuvant-analgesics.test.js.snap

@@ -458,7 +458,7 @@ exports[`Carbamazepine Integration Test generates valid code via toCode() 1`] =
 export const v2 = Ring({ atoms: 'C', size: 7, ringNumber: 2, offset: 3, bonds: [null, null, '=', null, '=', null, null], leadingBond: '=' });
 export const v3 = v2.substitute(7, 'N');
 export const v4 = Ring({ atoms: 'C', size: 6, ringNumber: 3, bonds: ['=', null, '=', null, '=', null] });
-export const v5 = FusedRing({ metadata: { rings: [{ ring: v1, start: 0, end: 5, atoms: [{ position: 0, depth: 0, value: 'C', rings: [1, 1] }, { position: 1, depth: 0, value: 'C', bond: '=', rings: [1] }, { position: 2, depth: 0, value: 'C', rings: [1] }, { position: 3, depth: 0, value: 'C', bond: '=', rings: [2, 1, 2] }, { position: 4, depth: 0, value: 'C', rings: [1, 2] }, { position: 5, depth: 1, value: 'C', bond: '=', rings: [1] }] }, { ring: v3, start: 3, end: 14, atoms: [{ position: 3, depth: 0, value: 'C', bond: '=', rings: [2, 1, 2] }, { position: 4, depth: 0, value: 'C', rings: [1, 2] }, { position: 6, depth: 0, value: 'C', rings: [2] }, { position: 7, depth: 0, value: 'C', bond: '=', rings: [2] }, { position: 8, depth: 0, value: 'C', rings: [3, 3, 2] }, { position: 13, depth: 0, value: 'C', bond: '=', rings: [3, 2] }, { position: 14, depth: 0, value: 'N', rings: [2] }] }, { ring: v4, start: 8, end: 13, atoms: [{ position: 8, depth: 0, value: 'C', rings: [3, 3, 2] }, { position: 9, depth: 0, value: 'C', bond: '=', rings: [3] }, { position: 10, depth: 0, value: 'C', rings: [3] }, { position: 11, depth: 0, value: 'C', bond: '=', rings: [3] }, { position: 12, depth: 0, value: 'C', rings: [3] }, { position: 13, depth: 0, value: 'C', bond: '=', rings: [3, 2] }] }] } });
+export const v5 = FusedRing({ metadata: { rings: [{ ring: v1, start: 0, end: 5, atoms: [{ position: 0, depth: 0, value: 'C', rings: [1, 1] }, { position: 1, depth: 0, value: 'C', bond: '=', rings: [1] }, { position: 2, depth: 0, value: 'C', rings: [1] }, { position: 3, depth: 0, value: 'C', bond: '=', rings: [2, 1, 2] }, { position: 4, depth: 0, value: 'C', rings: [1, 2] }, { position: 5, depth: 1, value: 'C', bond: '=', rings: [1], branchId: 9 }] }, { ring: v3, start: 3, end: 14, atoms: [{ position: 3, depth: 0, value: 'C', bond: '=', rings: [2, 1, 2] }, { position: 4, depth: 0, value: 'C', rings: [1, 2] }, { position: 6, depth: 0, value: 'C', rings: [2] }, { position: 7, depth: 0, value: 'C', bond: '=', rings: [2] }, { position: 8, depth: 0, value: 'C', rings: [3, 3, 2] }, { position: 13, depth: 0, value: 'C', bond: '=', rings: [3, 2] }, { position: 14, depth: 0, value: 'N', rings: [2] }] }, { ring: v4, start: 8, end: 13, atoms: [{ position: 8, depth: 0, value: 'C', rings: [3, 3, 2] }, { position: 9, depth: 0, value: 'C', bond: '=', rings: [3] }, { position: 10, depth: 0, value: 'C', rings: [3] }, { position: 11, depth: 0, value: 'C', bond: '=', rings: [3] }, { position: 12, depth: 0, value: 'C', rings: [3] }, { position: 13, depth: 0, value: 'C', bond: '=', rings: [3, 2] }] }] } });
 export const v6 = Linear(['C', 'N']);
 export const v7 = Linear(['O'], ['=']);
 export const v8 = v6.attach(1, v7);