smiles-js 2.0.3 → 2.1.0

package/API.md

@@ -190,6 +190,70 @@ Fuse this ring with another ring. `offset` is how many positions into this ring
 
 Return a deep copy of the ring.
 
+#### `ring.repeat(n, leftId, rightId)`
+
+Repeat the ring `n` times to build polymer chains. Each copy gets unique ring numbers automatically.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `n` | `number` | Number of repeating units (>= 1) |
+| `leftId` | `number` | 1-indexed left (incoming) attachment point |
+| `rightId` | `number` | 1-indexed right (outgoing) attachment point |
+
+```javascript
+// Biphenyl (two linked benzene rings)
+const benzene = Ring({ atoms: 'c', size: 6 });
+const biphenyl = benzene.repeat(2, 1, 6);
+console.log(biphenyl.smiles);  // c1ccccc1c2ccccc2
+
+// Terphenyl (three linked benzene rings)
+const terphenyl = benzene.repeat(3, 1, 6);
+console.log(terphenyl.smiles);  // c1ccccc1c2ccccc2c3ccccc3
+```
+
+#### `ring.fusedRepeat(n, offset)`
+
+Repeat a ring `n` times by fusing, creating acene-like edge-sharing systems (naphthalene, anthracene, tetracene).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `n` | `number` | Total number of rings (>= 1) |
+| `offset` | `number` | Fusion offset (number of shared atom positions between adjacent rings) |
+
+```javascript
+const benzene = Ring({ atoms: 'c', size: 6 });
+
+// Naphthalene (2 fused rings)
+const naphthalene = benzene.fusedRepeat(2, 4);
+
+// Anthracene (3 fused rings)
+const anthracene = benzene.fusedRepeat(3, 4);
+
+// Tetracene (4 fused rings)
+const tetracene = benzene.fusedRepeat(4, 4);
+```
+
+#### `ring.mirror(pivotId?)`
+
+Mirror a ring's attachments and substitutions to create symmetric patterns. The pivot defines the axis of symmetry on the ring.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pivotId` | `number` | `1` | 1-indexed ring position that serves as the symmetry axis |
+
+```javascript
+const benzene = Ring({ atoms: 'c', size: 6 });
+
+// meta-dimethylbenzene: attach at 2, mirror around pivot 3
+const mono = benzene.attach(2, Linear(['C']));
+const meta = mono.mirror(3);
+console.log(meta.smiles);  // c1c(C)cc(C)cc1
+
+// Symmetric nitrogen substitution
+const pyridine = Ring({ atoms: 'c', size: 6, substitutions: { 2: 'n' } });
+const diazine = pyridine.mirror(1);  // n at 2 and 6
+```
+
 ### Linear Methods
 
 ```javascript
@@ -225,6 +289,53 @@ Attach one or more branches at a position.
 
 Attach branches at multiple positions. `branchMap` is `{ position: node | [nodes] }`.
 
+#### `linear.repeat(n, leftId, rightId)`
+
+Repeat the linear chain `n` times to build polymer chains.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `n` | `number` | Number of repeating units (>= 1) |
+| `leftId` | `number` | 1-indexed left (incoming) attachment point |
+| `rightId` | `number` | 1-indexed right (outgoing) attachment point |
+
+```javascript
+// Polyethylene trimer
+const ethylene = Linear(['C', 'C']);
+const PE = ethylene.repeat(3, 1, 2);
+console.log(PE.smiles);  // CCCCCC
+
+// Polystyrene dimer
+const styrene = Linear(['C', 'C']).attach(2, Ring({ atoms: 'c', size: 6 }));
+const PS = styrene.repeat(2, 1, 2);
+console.log(PS.smiles);  // CC(c1ccccc1)CC(c2ccccc2)
+```
+
+#### `linear.mirror(pivotId?)`
+
+Mirror a linear chain around a pivot atom to create palindromic (A-B-A) patterns. The pivot atom appears once at the center.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pivotId` | `number` | `atoms.length` | 1-indexed pivot position (center of symmetry) |
+
+```javascript
+// Diethyl ether: mirror ethanol around the oxygen
+const chain = Linear(['C', 'C', 'O']);
+const ether = chain.mirror();  // pivot defaults to last atom
+console.log(ether.smiles);  // CCOCC
+
+// Symmetric alkene: mirror C=C around position 2
+const vinyl = Linear(['C', 'C'], ['=']);
+const symAlkene = vinyl.mirror(2);
+console.log(symAlkene.smiles);  // C=CC
+
+// With attachments: phenyl pendants are mirrored too
+const base = Linear(['C', 'C', 'C']).attach(1, Ring({ atoms: 'c', size: 6 }));
+const mirrored = base.mirror();
+console.log(mirrored.smiles);  // C(c1ccccc1)CCC(c2ccccc2)C
+```
+
 ### Molecule Methods
 
 ```javascript
@@ -244,6 +355,41 @@ const modified = mol.replaceComponent(0, Linear(['N', 'N']));
 
 // Concatenate molecules
 const combined = mol.concat(Molecule([Ring({ atoms: 'c', size: 6 })]));
+
+// Repeat the molecule as a polymer unit
+const unit = Molecule([Linear(['C']), Ring({ atoms: 'c', size: 6 })]);
+const dimer = unit.repeat(2, 1, 1);
+console.log(dimer.smiles);  // Cc1ccccc1Cc2ccccc2
+
+// Mirror molecule for ABA patterns
+const A = Linear(['C', 'C']);
+const B = Ring({ atoms: 'c', size: 6 });
+const AB = Molecule([A, B]);
+const ABA = AB.mirror();  // pivot defaults to last component
+console.log(ABA.smiles);  // CCc1ccccc1CC
+```
+
+#### `molecule.mirror(pivotComponent?)`
+
+Mirror a molecule's component sequence to create ABA or ABCBA patterns. The pivot component appears once at the center.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pivotComponent` | `number` | `components.length - 1` | 0-indexed pivot component (center of symmetry) |
+
+```javascript
+// ABA triblock: Linear-Ring-Linear
+const A = Linear(['C', 'C']);
+const B = Ring({ atoms: 'c', size: 6 });
+const AB = Molecule([A, B]);
+const ABA = AB.mirror();
+console.log(ABA.smiles);  // CCc1ccccc1CC
+
+// ABCBA pentablock
+const C = Linear(['N']);
+const ABC = Molecule([A, B, C]);
+const ABCBA = ABC.mirror();
+console.log(ABCBA.smiles);  // CCc1ccccc1NCCc2ccccc2CC... (mirrored)
 ```
 
 ### FusedRing Methods
@@ -276,6 +422,9 @@ const withSeq = fused.addSequentialRings([{ ring: ring3, depth: 1 }, { ring: rin
 
 // Add attachment to a sequential atom position
 const withAtt = fused.addSequentialAtomAttachment(25, Linear(['O']));
+
+// Repeat the fused ring system as a polymer unit
+const fusedDimer = fused.repeat(2, 1, 1);
 ```
 
 #### `fusedRing.addSequentialRings(rings, options?)`
@@ -431,10 +580,23 @@ import {
   moleculeConcat,
   moleculeGetComponent,
   moleculeReplaceComponent,
+  repeat,
+  fusedRepeat,
+  linearMirror,
+  moleculeMirror,
+  ringMirror,
 } from 'smiles-js/manipulation';
 
 const benzene = Ring({ atoms: 'c', size: 6 });
 const toluene = ringAttach(benzene, 1, Linear(['C']));
+
+// Polymer construction
+const biphenyl = repeat(benzene, 2, 1, 6);
+const naphthalene = fusedRepeat(benzene, 2, 4);
+
+// Mirror symmetry
+const chain = Linear(['C', 'C', 'O']);
+const ether = linearMirror(chain);  // CCOCC
 ```
 
 ---

package/README.md

@@ -16,6 +16,8 @@ Build complex molecules programmatically with an intuitive, composable API. Pars
 
 - **Parse complex SMILES** - Handles real-world pharmaceutical molecules (60-80+ characters)
 - **Programmatic construction** - Build molecules using composable Ring, Linear, and Molecule constructors
+- **Polymer construction** - Build repeating units with `.repeat()` and fused acene systems with `.fusedRepeat()`
+- **Mirror symmetry** - Create palindromic chains and ABA block patterns with `.mirror()`
 - **Round-trip fidelity** - Parse SMILES -> AST -> SMILES with structure preservation
 - **Code generation** - Auto-generate JavaScript construction code from SMILES strings
 - **Pharmaceutical validated** - Tested with Atorvastatin, Sildenafil, Ritonavir, and 30+ other drugs
@@ -85,6 +87,43 @@ const pyridine = benzene.substitute(5, 'n');
 console.log(pyridine.smiles);  // c1cccnc1
 ```
 
+### Build Polymers
+
+```javascript
+import { Ring, Linear } from 'smiles-js';
+
+// Polyethylene trimer: repeat ethylene unit 3 times
+const ethylene = Linear(['C', 'C']);
+const PE = ethylene.repeat(3, 1, 2);
+console.log(PE.smiles);  // CCCCCC
+
+// Polystyrene dimer: repeat styrene unit with phenyl branch
+const styrene = Linear(['C', 'C']).attach(2, Ring({ atoms: 'c', size: 6 }));
+const PS = styrene.repeat(2, 1, 2);
+console.log(PS.smiles);  // CC(c1ccccc1)CC(c2ccccc2)
+
+// Acene series via fused repeat
+const benzene = Ring({ atoms: 'c', size: 6 });
+const naphthalene = benzene.fusedRepeat(2, 4);  // 2 fused rings
+const anthracene = benzene.fusedRepeat(3, 4);   // 3 fused rings
+```
+
+### Mirror Symmetry
+
+```javascript
+import { Ring, Linear, Molecule } from 'smiles-js';
+
+// Diethyl ether: mirror C-C-O around oxygen
+const ether = Linear(['C', 'C', 'O']).mirror();
+console.log(ether.smiles);  // CCOCC
+
+// ABA triblock copolymer
+const A = Linear(['C', 'C']);
+const B = Ring({ atoms: 'c', size: 6 });
+const ABA = Molecule([A, B]).mirror();
+console.log(ABA.smiles);  // CCc1ccccc1CC
+```
+
 ### Generate Construction Code
 
 ```javascript

package/docs/MIRROR_PLAN.md

@@ -0,0 +1,204 @@
+# Plan: `.mirror()` API for Symmetric Molecule Construction
+
+## Motivation
+
+Many molecules and polymers are symmetric — their structure reads the same forwards and backwards around a central point. Building these today requires manually constructing both halves. A `.mirror()` method would let users define one half and automatically produce the symmetric whole.
+
+### Use Cases
+
+1. **ABA triblock copolymers** — The most common symmetric polymer architecture. Define the A and B blocks, get A-B-A automatically.
+2. **Palindromic linear chains** — e.g., `CCCOCCC` from `CCCO` mirrored at the O.
+3. **Symmetric branched molecules** — e.g., diethyl ether `CCOCC` from `CCO` mirrored.
+4. **Symmetric ring-bearing chains** — e.g., a chain with a ring in the center and identical arms on each side.
+5. **Dendrimers** — Symmetric branching structures built outward from a core.
+
+---
+
+## API Design
+
+### `linear.mirror(pivotId?)`
+
+Mirror a linear chain around a pivot atom to create a palindromic structure.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pivotId` | `number` | `atoms.length` | 1-indexed position of the pivot atom (included once in the output) |
+
+**Returns:** A new `Linear` (for simple chains) or `Molecule` (if attachments are present).
+
+**Behavior:** Takes atoms `[1..pivotId]`, then appends atoms `[pivotId-1..1]` in reverse. The pivot atom appears once in the center. Attachments on mirrored atoms are also mirrored.
+
+```javascript
+// Diethyl ether: CCO + mirror → CCOCC
+const half = Linear(['C', 'C', 'O']);
+const ether = half.mirror();            // pivot defaults to last atom (O)
+console.log(ether.smiles);              // CCOCC
+
+// Palindromic chain: CCCNCCC
+const half2 = Linear(['C', 'C', 'C', 'N']);
+const palindrome = half2.mirror();      // pivot at N (position 4)
+console.log(palindrome.smiles);         // CCCNCCC
+
+// Mirror at a specific pivot
+const chain = Linear(['C', 'C', 'C', 'O', 'C']);
+const mirrored = chain.mirror(4);       // pivot at O (position 4)
+console.log(mirrored.smiles);           // CCCOCCC
+// atoms [1,2,3,4] + reverse of [3,2,1] → C,C,C,O,C,C,C
+```
+
+### `ring.mirror(pivotId?)`
+
+Mirror a ring's attachments to create symmetric substitution patterns.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pivotId` | `number` | `1` | 1-indexed ring position that serves as the symmetry axis |
+
+**Returns:** A new `Ring` with attachments mirrored around the pivot.
+
+**Behavior:** For a ring with an attachment at position `p`, also adds the same attachment at the "mirror" position relative to the pivot. The mirror position for `p` around pivot `v` on a ring of size `s` is: `((2*v - p) mod s)`, adjusted to 1-indexed range.
+
+```javascript
+// Symmetric toluene → xylene (1,4-dimethylbenzene)
+const benzene = Ring({ atoms: 'c', size: 6 });
+const toluene = benzene.attach(1, Linear(['C']));
+const xylene = toluene.mirror(1);       // mirror around position 1
+// Attachment at position 1 stays, mirrored attachment appears at position 4
+console.log(xylene.smiles);             // c1(C)ccc(C)cc1
+```
+
+### `molecule.mirror(pivotComponent?)`
+
+Mirror a molecule's component sequence to create an ABA-like structure.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pivotComponent` | `number` | `components.length - 1` | 0-indexed component that serves as the center |
+
+**Returns:** A new `Molecule` with components mirrored.
+
+**Behavior:** Takes components `[0..pivot]`, then appends components `[pivot-1..0]` in reverse (with ring renumbering to avoid collisions).
+
+```javascript
+// ABA triblock copolymer
+const A = Linear(['C', 'C']);
+const B = Ring({ atoms: 'c', size: 6 });
+const AB = Molecule([A, B]);
+const ABA = AB.mirror();                 // pivot at last component (B)
+console.log(ABA.smiles);                 // CCc1ccccc1CC
+
+// More complex: A-B-C-B-A from A-B-C
+const block = Molecule([
+  Linear(['C', 'C']),
+  Ring({ atoms: 'c', size: 6 }),
+  Linear(['O']),
+]);
+const symmetric = block.mirror();        // pivot at last (O)
+console.log(symmetric.smiles);           // CCc1ccccc1Oc2ccccc2CC
+```
+
+### `fusedRing.mirror()`
+
+For fused rings, mirror could create a symmetric fused system by adding rings on both sides of the base. This is more complex and may be deferred to a later iteration.
+
+---
+
+## Functional API
+
+```javascript
+import {
+  linearMirror,
+  ringMirror,
+  moleculeMirror,
+} from 'smiles-js/manipulation';
+
+const half = Linear(['C', 'C', 'O']);
+const ether = linearMirror(half);         // CCOCC
+```
+
+---
+
+## Implementation Strategy
+
+### Phase 1: `linear.mirror(pivotId?)`
+
+The simplest and highest-value case. Pure atom/bond array manipulation.
+
+**Algorithm:**
+1. Validate `pivotId` is within `[1, atoms.length]`.
+2. Take `leftAtoms = atoms[0..pivotId-1]` (the left half including pivot).
+3. Take `rightAtoms = atoms[0..pivotId-2].reverse()` (the left half excluding pivot, reversed).
+4. Concatenate: `leftAtoms + rightAtoms`.
+5. Handle bonds: mirror the bond array similarly. Bond between atoms `i` and `i+1` maps to the corresponding mirrored position.
+6. Handle attachments: clone attachments from mirrored positions. Attachments at position `p` (where `p < pivotId`) also appear at the mirror position `2*pivotId - p`.
+
+**Files:**
+- `src/manipulation.js` — Add `linearMirror()` function
+- `src/method-attachers.js` — Attach `.mirror()` to Linear
+
+### Phase 2: `molecule.mirror(pivotComponent?)`
+
+Component-level mirroring for ABA block copolymers.
+
+**Algorithm:**
+1. Take `leftComponents = components[0..pivot]`.
+2. Take `rightComponents = components[0..pivot-1].reverse()`, each deep-cloned with shifted ring numbers.
+3. Return `Molecule([...leftComponents, ...rightComponents])`.
+
+**Files:**
+- `src/manipulation.js` — Add `moleculeMirror()` function (reuses `shiftRingNumbers` and `maxRingNumber` from the `repeat` implementation)
+- `src/method-attachers.js` — Attach `.mirror()` to Molecule
+
+### Phase 3: `ring.mirror(pivotId?)`
+
+Attachment-level mirroring for symmetric ring substitution patterns.
+
+**Algorithm:**
+1. For each attachment at position `p`, compute mirror position `mp = 2*pivotId - p` (mod ring size, 1-indexed).
+2. If `mp` doesn't already have the attachment, add it.
+3. Similarly mirror substitutions.
+
+**Files:**
+- `src/manipulation.js` — Add `ringMirror()` function
+- `src/method-attachers.js` — Attach `.mirror()` to Ring
+
+### Phase 4 (Future): `fusedRing.mirror()`
+
+Defer to a later iteration. FusedRing has complex position metadata that makes mirroring non-trivial.
+
+---
+
+## Edge Cases
+
+1. **Odd-length palindrome:** `mirror()` on `Linear(['C', 'O', 'C'])` with `pivotId=2` → `COCOC` (the pivot O appears once)
+2. **Single atom:** `Linear(['O']).mirror()` → `Linear(['O'])` (nothing to mirror)
+3. **Already symmetric:** Mirroring an already-symmetric molecule should produce the same result (idempotent on symmetric inputs)
+4. **Bonds in mirror:** Double bonds in the left half should appear in the mirrored right half at the corresponding position
+5. **Attachments with rings:** Mirrored ring attachments need unique ring numbers (reuse `shiftRingNumbers`)
+
+---
+
+## Test Plan
+
+### Unit Tests (`manipulation.test.js`)
+- `linear.mirror()` — simple chain, with pivot, with bonds, with attachments
+- `molecule.mirror()` — ABA, ABCBA, with rings
+- `ring.mirror()` — symmetric substitutions, symmetric attachments
+- Edge cases: n=1, already symmetric, single atom
+
+### Integration Tests (`test-integration/mirror.test.js`)
+- Diethyl ether: `CCO.mirror()` → `CCOCC`
+- ABA block copolymer with polystyrene/polyethylene blocks
+- Symmetric biphenyl-bridged molecule
+- Palindromic peptide-like chain
+
+---
+
+## Relationship to `.repeat()`
+
+`.mirror()` and `.repeat()` are complementary:
+- `.repeat(n, left, right)` — Produces **A-A-A-A** (homopolymer)
+- `.mirror()` — Produces **A-B-A** (symmetric structure)
+- Combined: `.repeat(2).mirror()` could produce **A-A-B-A-A** (repeated then mirrored)
+
+Together they cover the main polymer architectures: homopolymer, block copolymer, and symmetric block copolymer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smiles-js",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "A JavaScript library for building molecules using composable fragments",
   "type": "module",
   "main": "src/index.js",

package/scripts/coverage-summary.js

@@ -9,7 +9,7 @@ const projectRoot = join(__dirname, '..');
 
 const result = spawnSync('bun', ['test', '--coverage'], {
   encoding: 'utf-8',
-  cwd: projectRoot
+  cwd: projectRoot,
 });
 
 const output = (result.stdout || '') + (result.stderr || '');

package/src/codegen/branch-crossing-ring.js

@@ -76,14 +76,35 @@ export function buildBranchCrossingRingSMILES(ring, buildSMILES) {
 
     if (attachments[i] && attachments[i].length > 0) {
       if (hasInlineBranchAfter) {
-        // Delay attachments - output after inline branch closes back to this depth
-        const processedAttachments = attachments[i].map((att) => {
-          if (att.metaIsSibling !== undefined) {
-            return att;
+        // Determine the branchId of the inline continuation (next ring position)
+        const metaBranchIds = ring.metaBranchIds || [];
+        const inlineBranchId = i < size ? (metaBranchIds[i] || Infinity) : Infinity;
+
+        // Separate: siblings that come BEFORE the inline branch (emit now)
+        // vs siblings that come AFTER (delay), and non-siblings (delay)
+        const emitNow = [];
+        const delay = [];
+        attachments[i].forEach((att) => {
+          const isSibling = att.metaIsSibling !== undefined ? att.metaIsSibling : true;
+          if (!isSibling) {
+            delay.push(att);
+          } else if (att.metaBranchId !== undefined && att.metaBranchId < inlineBranchId) {
+            emitNow.push(att);
+          } else if (att.metaBeforeInline === true) {
+            emitNow.push(att);
+          } else {
+            // Default: delay sibling (beforeInline defaults to false)
+            delay.push({ ...att, metaIsSibling: true });
           }
-          return { ...att, metaIsSibling: true };
         });
-        pendingAttachments.set(i, { depth: posDepth, attachments: processedAttachments });
+        // Emit siblings that come before the inline branch
+        emitNow.forEach((attachment) => {
+          emitAttachment(parts, attachment, buildSMILES);
+        });
+        // Delay the rest
+        if (delay.length > 0) {
+          pendingAttachments.set(i, { depth: posDepth, attachments: delay });
+        }
       } else {
         // Output attachments immediately
         attachments[i].forEach((attachment) => {

package/src/codegen/interleaved-fused-ring.js

@@ -103,11 +103,33 @@ export function buildInterleavedFusedRingSMILES(fusedRing, buildSMILES) {
   // Pending attachments: depth -> attachment[]
   const pendingAttachments = new Map();
 
+  const branchIdMap = fusedRing.metaBranchIdMap || new Map();
+  let prevBranchId = null;
+
   allPositions.forEach((pos, idx) => {
     const entry = atomSequence[pos];
     if (!entry) return;
 
     const posDepth = branchDepthMap.get(pos) || 0;
+    const posBranchId = branchIdMap.get(pos);
+
+    // Detect sibling branch switch: same depth, different branch ID
+    // Need to close current branch and reopen a new one
+    if (posDepth > 0 && posDepth === depthRef.value && prevBranchId !== null
+        && posBranchId !== prevBranchId && posBranchId !== null) {
+      // Close the current branch and reopen
+      parts.push(')');
+      // Emit any pending attachments at the parent depth
+      const parentDepth = posDepth - 1;
+      if (pendingAttachments.has(parentDepth)) {
+        const attachmentsToOutput = pendingAttachments.get(parentDepth);
+        attachmentsToOutput.forEach((attachment) => {
+          emitAttachment(parts, attachment, buildSMILES);
+        });
+        pendingAttachments.delete(parentDepth);
+      }
+      parts.push('(');
+    }
 
     // Handle branch depth changes
     openBranches(parts, depthRef, posDepth);
@@ -164,6 +186,8 @@ export function buildInterleavedFusedRingSMILES(fusedRing, buildSMILES) {
         });
       }
     }
+
+    prevBranchId = posBranchId;
   });
 
   // Close any remaining open branches

package/src/decompiler.js

@@ -115,17 +115,38 @@ function generateAttachmentCode(ring, indent, nextVar, initialVar) {
   let currentVar = initialVar;
 
   if (ring.attachments && Object.keys(ring.attachments).length > 0) {
+    // Determine inline branchId for sibling ordering
+    const metaBranchIds = ring.metaBranchIds || [];
+    const normalizedDepths = ring.metaBranchDepths || [];
+
     Object.entries(ring.attachments).forEach(([pos, attachmentList]) => {
+      const posIdx = Number(pos) - 1; // 0-indexed
+      const nextIdx = posIdx + 1;
+      const posDepth = normalizedDepths[posIdx] || 0;
+      const nextDepth = nextIdx < normalizedDepths.length ? (normalizedDepths[nextIdx] || 0) : 0;
+      const hasInlineBranchAfter = nextDepth > posDepth;
+      const inlineBranchId = hasInlineBranchAfter ? (metaBranchIds[nextIdx] || Infinity) : Infinity;
+
       attachmentList.forEach((attachment) => {
         const attachResult = decompileChildNode(attachment, indent, nextVar);
         lines.push(attachResult.code);
 
         const newVar = nextVar();
         const isSibling = attachment.metaIsSibling;
+        const optParts = [];
         if (isSibling === true) {
-          lines.push(`${indent}const ${newVar} = ${currentVar}.attach(${pos}, ${attachResult.finalVar}, { sibling: true });`);
+          optParts.push('sibling: true');
+          // Encode beforeInline for sibling ordering in branch-crossing rings
+          // Only emit when true since false is the default
+          if (hasInlineBranchAfter && attachment.metaBranchId !== undefined
+              && attachment.metaBranchId < inlineBranchId) {
+            optParts.push('beforeInline: true');
+          }
         } else if (isSibling === false) {
-          lines.push(`${indent}const ${newVar} = ${currentVar}.attach(${pos}, ${attachResult.finalVar}, { sibling: false });`);
+          optParts.push('sibling: false');
+        }
+        if (optParts.length > 0) {
+          lines.push(`${indent}const ${newVar} = ${currentVar}.attach(${pos}, ${attachResult.finalVar}, { ${optParts.join(', ')} });`);
         } else {
           lines.push(`${indent}const ${newVar} = ${currentVar}.attach(${pos}, ${attachResult.finalVar});`);
         }
@@ -758,6 +779,7 @@ function decompileComplexFusedRing(fusedRing, indent, nextVar) {
     const atomValueMap = fusedRing.metaAtomValueMap || new Map();
     const bondMap = fusedRing.metaBondMap || new Map();
     const ringOrderMap = fusedRing.metaRingOrderMap;
+    const branchIdMap = fusedRing.metaBranchIdMap || new Map();
 
     // Helper to format a single atom entry with all available metadata
     function formatAtomEntry(pos) {
@@ -768,6 +790,9 @@ function decompileComplexFusedRing(fusedRing, indent, nextVar) {
       if (ringOrderMap && ringOrderMap.has(pos)) {
         parts.push(`rings: [${ringOrderMap.get(pos).join(', ')}]`);
       }
+      if (branchIdMap.has(pos) && branchIdMap.get(pos) !== null) {
+        parts.push(`branchId: ${branchIdMap.get(pos)}`);
+      }
       if (seqAtomAttachmentVarMap.has(pos)) {
         parts.push(`attachments: [${seqAtomAttachmentVarMap.get(pos).join(', ')}]`);
       }