smiles-js 1.1.0 → 2.0.0

package/API.md

@@ -21,6 +21,7 @@ Create ring structures with substitutions and attachments.
 | `substitutions` | `object` | `{}` | Position -> atom substitutions |
 | `attachments` | `object` | `{}` | Position -> attachment list |
 | `bonds` | `array` | `[]` | Bond types between atoms |
+| `branchDepths` | `number[]` | `null` | Per-atom branch depth (for rings that cross branch boundaries) |
 
 ```javascript
 // Simple benzene
@@ -61,7 +62,7 @@ const propene = Linear(['C', 'C', 'C'], [null, '=']);
 // Ethanol with hydroxyl
 const ethyl = Linear(['C', 'C']);
 const hydroxyl = Linear(['O']);
-const ethanol = ethyl.attach(hydroxyl, 2);
+const ethanol = ethyl.attach(2, hydroxyl);
 ```
 
 ### `FusedRing(rings)`
@@ -107,7 +108,7 @@ All manipulation methods are **immutable** -- they return new nodes and never mo
 const benzene = Ring({ atoms: 'c', size: 6 });
 
 // Attach substituent at position
-const toluene = benzene.attach(Linear(['C']), 1);
+const toluene = benzene.attach(1, Linear(['C']));
 
 // Substitute atom at position
 const pyridine = benzene.substitute(5, 'n');
@@ -117,20 +118,20 @@ const triazine = benzene.substituteMultiple({ 1: 'n', 3: 'n', 5: 'n' });
 
 // Fuse with another ring (offset = shared atom count)
 const ring2 = Ring({ atoms: 'C', size: 6 });
-const naphthalene = benzene.fuse(ring2, 2);
+const naphthalene = benzene.fuse(2, ring2);
 
 // Clone
 const benzeneClone = benzene.clone();
 ```
 
-#### `ring.attach(attachment, position, options?)`
+#### `ring.attach(position, attachment, options?)`
 
 Attach a node to the ring at a 1-indexed position.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `attachment` | `object` | Node to attach |
 | `position` | `number` | 1-indexed ring position |
+| `attachment` | `object` | Node to attach |
 | `options.sibling` | `boolean` | If set, marks the attachment as sibling (true) or inline (false) |
 
 #### `ring.substitute(position, newAtom)`
@@ -141,7 +142,7 @@ Replace the atom at position with a different atom symbol.
 
 Replace multiple atoms. `substitutionMap` is `{ position: atomSymbol }`.
 
-#### `ring.fuse(otherRing, offset, options?)`
+#### `ring.fuse(offset, otherRing, options?)`
 
 Fuse this ring with another ring. `offset` is how many positions into this ring the other ring starts.
 
@@ -156,7 +157,7 @@ const butane = Linear(['C', 'C', 'C', 'C']);
 
 // Attach branch at position
 const methyl = Linear(['C']);
-const branched = butane.attach(methyl, 2);
+const branched = butane.attach(2, methyl);
 
 // Concatenate chains
 const hexane = butane.concat(Linear(['C', 'C']));
@@ -168,7 +169,7 @@ const isobutane = butane.branchAt({ 2: methyl });
 const decorated = butane.branch(2, methyl, Linear(['O']));
 ```
 
-#### `linear.attach(attachment, position)`
+#### `linear.attach(position, attachment)`
 
 Attach a node at a 1-indexed position.
 
@@ -208,10 +209,10 @@ const combined = mol.concat(Molecule([Ring({ atoms: 'c', size: 6 })]));
 ### FusedRing Methods
 
 ```javascript
-const fused = ring1.fuse(ring2, 4);
+const fused = ring1.fuse(4, ring2);
 
 // Add another ring to the fused system
-const triple = fused.addRing(ring3, 8);
+const triple = fused.addRing(8, ring3);
 
 // Get a specific ring by number
 const r = fused.getRing(1);
@@ -220,20 +221,45 @@ const r = fused.getRing(1);
 const modified = fused.substituteInRing(1, 3, 'N');
 
 // Attach to a specific ring
-const decorated = fused.attachToRing(1, Linear(['O']), 4);
+const decorated = fused.attachToRing(1, 4, Linear(['O']));
 
 // Renumber rings
 const renumbered = fused.renumber(10);
 
-// Add sequential continuation rings
+// Add sequential continuation rings with depths and chain atoms
 const withSeq = fused.addSequentialRings([ring3, ring4], {
-  atomAttachments: { 25: [Linear(['O'], ['='])] }
+  depths: [1, 2],
+  chainAtoms: [
+    { atom: 'C', depth: 2, position: 'before' },
+    { atom: 'C', depth: 2, position: 'after', attachments: [Linear(['O'], ['='])] },
+  ]
 });
 
 // Add attachment to a sequential atom position
 const withAtt = fused.addSequentialAtomAttachment(25, Linear(['O']));
 ```
 
+#### `fusedRing.addSequentialRings(rings, options?)`
+
+Add continuation rings to a fused ring system. Computes all position metadata internally.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `rings` | `Ring[]` | Array of sequential Ring nodes to add |
+| `options.depths` | `number[]` | Per-ring branch depth (e.g., `[1, 2, 1, 2]`) |
+| `options.chainAtoms` | `object[]` | Standalone atoms between rings (see below) |
+| `options.atomAttachments` | `object` | Legacy: position → attachment list map |
+
+**chainAtoms entries:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `atom` | `string` | Atom symbol (e.g., `'C'`, `'N'`, `'O'`) |
+| `depth` | `number` | Branch depth for this atom |
+| `position` | `'before'` \| `'after'` | Whether the atom appears before or after rings at its depth |
+| `bond` | `string` | Optional bond type (e.g., `'='`, `'#'`) |
+| `attachments` | `object[]` | Optional array of nodes attached to this atom |
+
 ---
 
 ## Parsing & Serialization
@@ -363,7 +389,7 @@ import {
 } from 'smiles-js/manipulation';
 
 const benzene = Ring({ atoms: 'c', size: 6 });
-const toluene = ringAttach(benzene, Linear(['C']), 1);
+const toluene = ringAttach(benzene, 1, Linear(['C']));
 ```
 
 ---
@@ -395,7 +421,7 @@ import RDKit from '@rdkit/rdkit';
 // Build molecule programmatically
 const benzene = Ring({ atoms: 'c', size: 6 });
 const methyl = Linear(['C']);
-const toluene = benzene.attach(methyl, 1);
+const toluene = benzene.attach(1, methyl);
 
 // Use with RDKit
 const rdkit = await RDKit.load();
@@ -435,9 +461,6 @@ Some complex molecules may have minor notation differences during round-trip:
 
 **Impact**: Low - Structure is preserved, only notation differs.
 
-### toCode() Limitation
+### toCode() Generated Code
 
-The `.toCode()` method has a limitation with certain sequential continuation patterns in very complex nested structures. This does NOT affect:
-- Parsing SMILES -> AST
-- Serializing AST -> SMILES
-- Round-trip fidelity
+The `.toCode()` method generates JavaScript constructor code that reconstructs the molecule. For molecules with sequential continuation rings (e.g., Telmisartan), the generated code uses `addSequentialRings()` with `depths` and `chainAtoms` options to produce clean structural API calls with no raw metadata assignments.

package/README.md

@@ -64,7 +64,7 @@ console.log(benzene.smiles);  // c1ccccc1
 
 // Add methyl group to make toluene
 const methyl = Linear(['C']);
-const toluene = benzene.attach(methyl, 1);
+const toluene = benzene.attach(1, methyl);
 console.log(toluene.smiles);  // c1(C)ccccc1
 
 // Create pyridine via substitution

package/docs/EXAMPLES.md

@@ -108,7 +108,7 @@ node docs/atorvastatin-named.js
 // Isopropyl group (substituent on pyrrole)
 const methyl1 = Linear(['C']);
 const ethyl = Linear(['C', 'C']);
-const isopropyl = ethyl.attach(methyl1, 2);
+const isopropyl = ethyl.attach(2, methyl1);
 
 // Central pyrrole ring (5-membered nitrogen heterocycle)
 const pyrroleRing = Ring({ atoms: 'c', size: 5 });
@@ -117,7 +117,7 @@ const pyrrole = pyrroleRing.substitute(5, 'n');
 // Dihydroxyheptanoic acid side chain (the "statin" pharmacophore)
 const heptanoicAcidChain = Linear(['C', 'C', 'C', 'C', 'C', 'C', 'C', 'O']);
 const hydroxyl1 = Linear(['O']);
-const statinSideChain = heptanoicAcidChain.attach(hydroxyl1, 3);
+const statinSideChain = heptanoicAcidChain.attach(3, hydroxyl1);
 ```
 
 ---

package/docs/IMPLEMENTATION_ROADMAP.md

@@ -78,7 +78,7 @@ console.log(propane.smiles); // 'CCC'
 ```javascript
 const benzene = Ring({ atoms: 'c', size: 6 });
 const methyl = Linear(['C']);
-const toluene = benzene.attach(methyl, 1);
+const toluene = benzene.attach(1, methyl);
 console.log(toluene.smiles); // 'c1c(C)cccc1' or equivalent
 ```
 
@@ -197,7 +197,7 @@ const triazine = benzene.substituteMultiple({ 1: 'n', 3: 'n', 5: 'n' });
 
 const ring1 = Ring({ atoms: 'C', size: 10 });
 const ring2 = Ring({ atoms: 'C', size: 6 });
-const naphthalene = ring1.fuse(ring2, 2);
+const naphthalene = ring1.fuse(2, ring2);
 ```
 
 ---
@@ -387,7 +387,7 @@ console.log(fragment.toCode());
 // Output:
 // const linear1 = Linear(['C'])
 // const ring1 = Ring({ atoms: 'c', size: 6 })
-// const ring2 = ring1.attach(linear1, 4)
+// const ring2 = ring1.attach(4, linear1)
 ```
 
 ---

package/docs/PARSER_REFACTOR_PLAN.md

@@ -780,10 +780,10 @@ FusedRing.prototype.substituteInRing = function(ringNumber, position, newAtom) {
   return replaceRingInFusedSystem(this, ringNumber, updatedRing);
 };
 
-FusedRing.prototype.attachToRing = function(ringNumber, attachment, position) {
+FusedRing.prototype.attachToRing = function(ringNumber, position, attachment) {
   // Attach to a specific ring in the fused system
   const targetRing = this.getRing(ringNumber);
-  const updatedRing = targetRing.attach(attachment, position);
+  const updatedRing = targetRing.attach(position, attachment);
   return replaceRingInFusedSystem(this, ringNumber, updatedRing);
 };
 
@@ -832,7 +832,7 @@ Linear.prototype.branchAt = function(branchMap) {
   // branchMap: { position: branch, ... }
   let result = this;
   for (const [position, branchStructure] of Object.entries(branchMap)) {
-    result = result.attach(branchStructure, position);
+    result = result.attach(position, branchStructure);
   }
   return result;
 };
@@ -943,7 +943,7 @@ const methyl = Linear(['C']);
 console.log(methyl.smiles);  // 'C'
 
 // Combined structures
-const toluene = benzene.attach(methyl, 1);
+const toluene = benzene.attach(1, methyl);
 console.log(toluene.smiles);  // 'c1ccccc1C' or 'c1c(C)cccc1' (depending on serialization)
 
 // Fused ring SMILES
@@ -964,7 +964,7 @@ console.log(ring1.smiles);  // 'c1ccccc1'
 const linear1 = Linear(['C']);
 console.log(linear1.smiles);  // 'C'
 
-const molecule1 = ring1.attach(linear1, 1);
+const molecule1 = ring1.attach(1, linear1);
 console.log(molecule1.smiles);  // 'c1c(C)cccc1' (toluene)
 
 // Chained operations with SMILES inspection at each step
@@ -978,7 +978,7 @@ const step2 = step1.substitute(3, 'n');
 console.log('Step 2:', step2.smiles);  // 'c1nccncc1'
 
 const branch = Linear(['C', 'C']);
-const final = step2.attach(branch, 5);
+const final = step2.attach(5, branch);
 console.log('Final:', final.smiles);  // 'c1nccnc(CC)c1'
 ```
 
@@ -1005,7 +1005,7 @@ console.log('Final:', final.smiles);  // 'c1nccnc(CC)c1'
 // Create benzene and add methyl group
 const benzene = Ring({ atoms: 'c', size: 6 });
 const methyl = Linear(['C']);
-const toluene = benzene.attach(methyl, 1);
+const toluene = benzene.attach(1, methyl);
 
 // Create pyridine via substitution
 const pyridine = benzene.substitute(1, 'n');
@@ -1016,7 +1016,7 @@ const triazine = benzene.substituteMultiple({ 1: 'n', 3: 'n', 5: 'n' });
 // Fuse two rings
 const ring1 = Ring({ atoms: 'C', size: 10 });
 const ring2 = Ring({ atoms: 'C', size: 6 });
-const naphthalene = ring1.fuse(ring2, 2);
+const naphthalene = ring1.fuse(2, ring2);
 
 // ============================================
 // FUSED RING MANIPULATION
@@ -1034,10 +1034,10 @@ const substituted = benzimidazole
   .substituteInRing(1, 7, 'n');
 
 // Attach to specific ring in fused system
-const withMethyl = benzimidazole.attachToRing(1, Linear(['C']), 1);
+const withMethyl = benzimidazole.attachToRing(1, 1, Linear(['C']));
 
 // Add another ring to the fused system
-const expandedSystem = naphthalene.addRing(Ring({ atoms: 'C', size: 5 }), 8);
+const expandedSystem = naphthalene.addRing(8, Ring({ atoms: 'C', size: 5 }));
 
 // ============================================
 // LINEAR CHAIN MANIPULATION
@@ -1082,12 +1082,12 @@ const phenyl2 = Ring({ atoms: 'C', size: 6 });
 const carboxyl = Linear(['C'], ['=O', '-O']);
 
 // Fluent chaining
-const phenylWithCarboxyl = phenyl2.attach(carboxyl, 6);
-const biphenyl = phenyl1.attach(phenylWithCarboxyl, 6);
+const phenylWithCarboxyl = phenyl2.attach(6, carboxyl);
+const biphenyl = phenyl1.attach(6, phenylWithCarboxyl);
 const connector = Linear(['C', 'C']);
 const sideChain = connector.concat(biphenyl);
 
-const coreWithSideChain = benzimidazoleCore.attachToRing(1, sideChain, 9);
+const coreWithSideChain = benzimidazoleCore.attachToRing(1, 9, sideChain);
 
 // Final assembly using Molecule
 const telmisartan = Molecule([
@@ -1476,7 +1476,7 @@ console.log(toluene.toCode());
 // Output:
 // const linear1 = Linear(['C'])
 // const ring1 = Ring({ atoms: 'c', size: 6 })
-// const ring2 = ring1.attach(linear1, 4)
+// const ring2 = ring1.attach(4, linear1)
 ```
 
 **Decompiler Options:**
@@ -1493,7 +1493,7 @@ const options = {
 Fragment('c1ccc(C)cc1').toCode(options);
 // Output:
 // const myLinear1 = Linear(['C'])
-// const myRing1 = Ring({ atoms: 'c', size: 6 }).attach(myLinear1, 4)
+// const myRing1 = Ring({ atoms: 'c', size: 6 }).attach(4, myLinear1)
 ```
 
 **Example Outputs:**
@@ -1507,7 +1507,7 @@ Fragment('c1ccccc1').toCode();
 Fragment('c1ccc(C)cc1').toCode();
 // const linear1 = Linear(['C'])
 // const ring1 = Ring({ atoms: 'c', size: 6 })
-// const ring2 = ring1.attach(linear1, 4)
+// const ring2 = ring1.attach(4, linear1)
 
 // Pyridine: c1cccnc1
 Fragment('c1cccnc1').toCode();
@@ -1530,9 +1530,9 @@ Fragment('CCCc1ccccc1').toCode();
 Fragment('C(C(C))c1ccccc1').toCode();
 // const linear1 = Linear(['C'])
 // const linear2 = Linear(['C'])
-// const linear3 = linear1.attach(linear2, 1)
+// const linear3 = linear1.attach(1, linear2)
 // const linear4 = Linear(['C'])
-// const linear5 = linear3.attach(linear4, 1)
+// const linear5 = linear3.attach(1, linear4)
 // const ring1 = Ring({ atoms: 'c', size: 6 })
 // const molecule1 = Molecule([linear5, ring1])
 ```

package/docs/PRODUCTION_AUDIT.md

@@ -53,7 +53,7 @@ CCC  ✅
 **Status**: COMPLETE
 **Verification**:
 ```bash
-$ node -e "import {Ring, Linear} from './src/index.js'; const benzene = Ring({ atoms: 'c', size: 6 }); const methyl = Linear(['C']); const toluene = benzene.attach(methyl, 1); console.log(toluene.smiles);"
+$ node -e "import {Ring, Linear} from './src/index.js'; const benzene = Ring({ atoms: 'c', size: 6 }); const methyl = Linear(['C']); const toluene = benzene.attach(1, methyl); console.log(toluene.smiles);"
 c1(C)ccccc1  ✅
 ```
 - `Ring.prototype.attach()` works
@@ -228,7 +228,7 @@ const ring1 = Ring({ atoms: 'c', size: 6 });  ✅
 $ node -e "import {parse} from './src/index.js'; const toluene = parse('c1ccc(C)cc1'); console.log(toluene.toCode());"
 const ring1 = Ring({ atoms: 'c', size: 6 });
 const ring2 = Linear(['C']);
-const ring3 = ring1.attach(ring2, 4);  ✅
+const ring3 = ring1.attach(4, ring2);  ✅
 ```
 - All AST node types decompile correctly
 - Substitutions generate method calls
@@ -296,25 +296,25 @@ Ran 457 tests across 25 files. [163.00ms]
 - [x] Molecule(components)
 
 ### Ring Manipulation API ✅
-- [x] ring.attach(attachment, position)
+- [x] ring.attach(position, attachment)
 - [x] ring.substitute(position, newAtom)
 - [x] ring.substituteMultiple(substitutionMap)
-- [x] ring.fuse(otherRing, offset)
+- [x] ring.fuse(offset, otherRing)
 - [x] ring.concat(other)
 - [x] ring.clone()
 
 ### Linear Manipulation API ✅
-- [x] linear.attach(attachment, atomIndex)
+- [x] linear.attach(atomIndex, attachment)
 - [x] linear.concat(other)
 - [x] linear.branch(branchPoint, ...branches)
 - [x] linear.branchAt(branchMap)
 - [x] linear.clone()
 
 ### FusedRing Manipulation API ✅
-- [x] fusedRing.addRing(ring, offset)
+- [x] fusedRing.addRing(offset, ring)
 - [x] fusedRing.getRing(ringNumber)
 - [x] fusedRing.substituteInRing(ringNumber, position, newAtom)
-- [x] fusedRing.attachToRing(ringNumber, attachment, position)
+- [x] fusedRing.attachToRing(ringNumber, position, attachment)
 - [x] fusedRing.renumber(startNumber)
 - [x] fusedRing.concat(other)
 - [x] fusedRing.clone()

package/docs/TEST_DRIVE_RESULTS.md

@@ -215,8 +215,8 @@ const molecule2 = Ring({ atoms: 'c', size: 6 });
 ```javascript
 const propylChain = Linear(['C', 'C', 'C']);
 const benzeneRing = Ring({ atoms: 'c', size: 6 });
-const isopropylGroup = propylChain.attach(methylGroup, 2);
-const phenylAmide = benzeneRing.attach(amideLinker, 1);
+const isopropylGroup = propylChain.attach(2, methylGroup);
+const phenylAmide = benzeneRing.attach(1, amideLinker);
 ```
 
 ---

package/docs/atorvastatin-named.js

@@ -16,7 +16,7 @@ function log(...args) {
 // Isopropyl group (substituent on pyrrole)
 const methyl1 = Linear(['C']);
 const ethyl = Linear(['C', 'C']);
-const isopropyl = ethyl.attach(methyl1, 2);
+const isopropyl = ethyl.attach(2, methyl1);
 
 // Central pyrrole ring (5-membered nitrogen heterocycle)
 const pyrroleRing = Ring({ atoms: 'c', size: 5 });
@@ -25,31 +25,31 @@ const pyrrole = pyrroleRing.substitute(5, 'n');
 // Amide linker with phenyl group
 const amideLinker = Linear(['C', 'N']);
 const carbonyl = Linear(['O'], ['=']);
-const amide = amideLinker.attach(carbonyl, 1);
+const amide = amideLinker.attach(1, carbonyl);
 const phenylRing1 = Ring({ atoms: 'c', size: 6, ringNumber: 2 });
 const phenylAmide = Molecule([amide, phenylRing1]);
 
 // Attach amide-phenyl to pyrrole
-const pyrroleWithAmide = pyrrole.attach(phenylAmide, 2);
+const pyrroleWithAmide = pyrrole.attach(2, phenylAmide);
 
 // Second phenyl ring (position 3)
 const phenylRing2 = Ring({ atoms: 'c', size: 6, ringNumber: 3 });
-const pyrroleWithTwoPhenyls = pyrroleWithAmide.attach(phenylRing2, 3);
+const pyrroleWithTwoPhenyls = pyrroleWithAmide.attach(3, phenylRing2);
 
 // Fluorophenyl ring (position 4)
 const phenylRing3 = Ring({ atoms: 'c', size: 6, ringNumber: 4 });
 const fluorine = Linear(['F']);
-const fluorophenyl = phenylRing3.attach(fluorine, 4);
-const pyrroleCore = pyrroleWithTwoPhenyls.attach(fluorophenyl, 4);
+const fluorophenyl = phenylRing3.attach(4, fluorine);
+const pyrroleCore = pyrroleWithTwoPhenyls.attach(4, fluorophenyl);
 
 // Dihydroxyheptanoic acid side chain (the "statin" pharmacophore)
 const heptanoicAcidChain = Linear(['C', 'C', 'C', 'C', 'C', 'C', 'C', 'O']);
 const hydroxyl1 = Linear(['O']);
-const dihydroxyChain = heptanoicAcidChain.attach(hydroxyl1, 3);
+const dihydroxyChain = heptanoicAcidChain.attach(3, hydroxyl1);
 const hydroxyl2 = Linear(['O']);
-const trihydroxyChain = dihydroxyChain.attach(hydroxyl2, 5);
+const trihydroxyChain = dihydroxyChain.attach(5, hydroxyl2);
 const carboxylate = Linear(['O'], ['=']);
-const statinSideChain = trihydroxyChain.attach(carboxylate, 7);
+const statinSideChain = trihydroxyChain.attach(7, carboxylate);
 
 // Assemble complete molecule
 const atorvastatin = Molecule([isopropyl, pyrroleCore, statinSideChain]);

package/docs/esomeprazole-showcase.js

@@ -84,7 +84,7 @@ log('3️⃣  Methoxy groups:          2x', methoxyGroup1.smiles);
 // Sulfoxide linker
 const sulfoxideLinker = Linear(['S', 'C']);
 const sulfinylOxygen = Linear(['O'], ['=']);
-const sulfoxide = sulfoxideLinker.attach(sulfinylOxygen, 1);
+const sulfoxide = sulfoxideLinker.attach(1, sulfinylOxygen);
 log('4️⃣  Sulfoxide linker:       ', sulfoxide.smiles);
 
 // Dimethoxymethylpyridine

package/docs/readable-generated-code/{READABLE_GENERATED_CODE.md → 10_READABLE_GENERATED_CODE.md}

@@ -11,7 +11,7 @@ export const v2 = Ring({ atoms: 'C', size: 5, bonds: ['=', null, '=', null, null
 export const v3 = v2.substitute(2, 'N');
 export const v4 = v3.substitute(5, 'N');
 export const v5 = Ring({ atoms: 'C', size: 6, ringNumber: 2, offset: 2, bonds: ['=', null, '=', null, '=', null] });
-export const v6 = v4.fuse(v5, 2);
+export const v6 = v4.fuse(2, v5);
 
 // Unreadable garbage - what is any of this?
 v6.rings[0].metaPositions = [3, 4, 5, 10, 11];
@@ -102,7 +102,7 @@ export const v1 = Ring({ atoms: 'C', size: 5, bonds: ['=', null, '=', null, null
 export const v2 = v1.substitute(2, 'N');
 export const v3 = v2.substitute(5, 'N');
 export const v4 = Ring({ atoms: 'C', size: 6, ringNumber: 2, offset: 2, bonds: ['=', null, '=', null, '=', null] });
-export const v5 = v3.fuse(v4, 2);
+export const v5 = v3.fuse(2, v4);
 v5.rings[0].metaPositions = [3, 4, 5, 10, 11];
 v5.rings[0].metaStart = 3;
 v5.rings[0].metaEnd = 11;
@@ -119,7 +119,7 @@ export const v1 = Ring({ atoms: 'C', size: 5, bonds: ['=', null, '=', null, null
 export const v2 = v1.substitute(2, 'N');
 export const v3 = v2.substitute(5, 'N');
 export const v4 = Ring({ atoms: 'C', size: 6, ringNumber: 2, offset: 2, bonds: ['=', null, '=', null, '=', null] });
-export const v5 = v3.fuse(v4, 2);
+export const v5 = v3.fuse(2, v4);
 ```
 
 That's it. The `fuse()` method (and `FusedRing()` constructor) would call `layout()` internally, computing all the metadata automatically.
@@ -127,14 +127,14 @@ That's it. The `fuse()` method (and `FusedRing()` constructor) would call `layou
 For cases with sequential rings, we'd need a new API method:
 
 ```javascript
-export const v5 = v3.fuse(v4, 2);
+export const v5 = v3.fuse(2, v4);
 export const v6 = Ring({ atoms: 'C', size: 5, ringNumber: 5, bonds: ['=', null, '=', null, null] });
 export const v7 = v6.substitute(2, 'N');
 export const v8 = v7.substitute(5, 'N');
 export const v9 = v5.addSequentialRing(v8);
 
 // Or alternatively, pass sequential rings at construction time:
-export const v5 = v3.fuse(v4, 2, {
+export const v5 = v3.fuse(2, v4, {
   sequentialRings: [v8, v10, v11, v12],
   sequentialAtomAttachments: { 25: [v13] }
 });
@@ -212,7 +212,7 @@ export const v2 = Ring({ atoms: 'C', size: 5, bonds: ['=', null, '=', null, null
 export const v3 = v2.substitute(2, 'N');
 export const v4 = v3.substitute(5, 'N');
 export const v5 = Ring({ atoms: 'C', size: 6, ringNumber: 2, offset: 2, bonds: ['=', null, '=', null, '=', null], branchDepths: [0, 0, 1, 1, 2, 2] });
-export const v6 = v4.fuse(v5, 2);
+export const v6 = v4.fuse(2, v5);
 
 export const v7 = Ring({ atoms: 'C', size: 5, ringNumber: 5, bonds: ['=', null, '=', null, null] });
 export const v8 = v7.substitute(2, 'N');

package/docs/readable-generated-code/{AFTER_ACTION_REPORT.md → 40_AFTER_ACTION_REPORT.md}

@@ -30,7 +30,7 @@ export const v1 = Ring({ atoms: 'C', size: 5, bonds: ['=', null, '=', null, null
 export const v2 = v1.substitute(2, 'N');
 export const v3 = v2.substitute(5, 'N');
 export const v4 = Ring({ atoms: 'C', size: 6, ringNumber: 2, offset: 2 });
-export const v5 = v3.fuse(v4, 2);
+export const v5 = v3.fuse(2, v4);
 ```
 
 Done. No meta. The `fuse()` call computes everything internally via `layout()`.
@@ -42,7 +42,7 @@ Done. No meta. The `fuse()` call computes everything internally via `layout()`.
 export const v1 = Linear(['C', 'C', 'C']);
 export const v2 = Ring({ atoms: 'C', size: 5, ... });
 // ...
-export let v6 = v4.fuse(v5, 2);
+export let v6 = v4.fuse(2, v5);
 // ...
 v6 = v6.addSequentialRings([v9, v10, v11, v12], { atomAttachments: { 25: [v13] } });
 
@@ -135,9 +135,9 @@ Not everything is bad. Simple molecules produce perfectly readable code:
 ```javascript
 export const v1 = Linear(['C', 'C', 'N']);
 export const v2 = Ring({ atoms: 'c', size: 6 });
-export const v3 = v2.attach(v1, 3);
+export const v3 = v2.attach(3, v1);
 export const v4 = Linear(['O']);
-export const v5 = v3.attach(v4, 1);
+export const v5 = v3.attach(1, v4);
 export const v6 = Molecule([v5]);
 ```
 

package/docs/readable-generated-code/{UPDATED_PLAN.md → 50_UPDATED_PLAN.md}

@@ -165,7 +165,7 @@ For the simple path, the decompiler emits:
 const v1 = Ring({ atoms: 'C', size: 5, bonds: [...], branchDepths: [...] });
 const v2 = v1.substitute(2, 'N');
 const v3 = Ring({ atoms: 'C', size: 6, ringNumber: 2, offset: 2, ... });
-const v4 = v2.fuse(v3, 2);
+const v4 = v2.fuse(2, v3);
 ```
 
 No meta. The `branchDepths` option on Ring is structural (it's an input to the constructor, not computed metadata).
@@ -210,7 +210,7 @@ export const v2 = Ring({ atoms: 'C', size: 5, bonds: ['=', null, '=', null, null
 export const v3 = v2.substitute(2, 'N');
 export const v4 = v3.substitute(5, 'N');
 export const v5 = Ring({ atoms: 'C', size: 6, ringNumber: 2, offset: 2, bonds: ['=', null, '=', null, '=', null], branchDepths: [0, 0, 1, 1, 2, 2] });
-export const v6 = v4.fuse(v5, 2);
+export const v6 = v4.fuse(2, v5);
 // sequential rings become attachments or are added via addSequentialRings
 // ...
 // NO META LINES