smiles-js 2.0.3 → 2.2.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/docs/smiles.peggy

@@ -0,0 +1,215 @@
+// SMILES Grammar for Peggy (PEG parser generator for JavaScript)
+//
+// This grammar mirrors the tokenizer + buildAtomList two-pass architecture
+// in src/tokenizer.js and src/parser/smiles-parser-core.js.
+//
+// What this grammar produces:
+//   A concrete parse tree (token stream with structure). The codebase then
+//   does a second semantic pass (buildAST) to detect rings, fused rings,
+//   and attachments — that pass is stateful and cannot be expressed in PEG.
+//
+// Usage:
+//   npx peggy smiles.peggy                          # generates smiles.js
+//   npx peggy --format commonjs -o smiles.cjs smiles.peggy  # CommonJS
+//
+// Differences from OpenSMILES spec (matches codebase behavior):
+//   - Simple atoms accept ANY [A-Za-z] letter, not just the organic subset.
+//     The tokenizer (isAtomStart + parseSimpleAtom) only special-cases Br/Cl
+//     as two-letter atoms; everything else is a single letter.
+//   - Bracketed atoms capture raw content only (the codebase has a TODO for
+//     full isotope/chirality/hcount/charge/class parsing). The grammar DOES
+//     parse the sub-fields since it's trivial in PEG and useful for consumers.
+//   - Whitespace is silently skipped (tokenizer.js line 104).
+//   - Ring markers can be preceded by a bond (e.g. C=1CC=1 is legal SMILES).
+
+// ============================================================
+// Top-level: dot-separated components
+// Mirrors: tokenizer DOT token → buildAtomList skips DOT
+// ============================================================
+smiles
+  = _ head:chain tail:(_ "." _ chain)* _ {
+      const components = [head, ...tail.map(t => t[3])];
+      if (components.length === 1) return components[0];
+      return { type: "molecule", components };
+    }
+
+// ============================================================
+// Chain: sequence of atom_units with optional bonds between them
+// Mirrors: buildAtomList's linear scan — each ATOM token may be
+//          preceded by a BOND token, and followed by RING_MARKER
+//          and BRANCH_OPEN/CLOSE tokens.
+// ============================================================
+chain
+  = first:atom_unit rest:(_ bond? _ atom_unit)* {
+      const atoms = [first];
+      const bonds = [null];
+      for (const r of rest) {
+        bonds.push(r[1]);
+        atoms.push(r[3]);
+      }
+      return { type: "chain", atoms, bonds };
+    }
+
+// ============================================================
+// Atom unit: atom + ring markers + branches
+//
+// Mirrors the token consumption order in buildAtomList:
+//   ATOM → RING_MARKER* → (BRANCH_OPEN chain BRANCH_CLOSE)*
+//
+// Ring markers can carry their own bond (e.g. C=1...=1)
+// This is valid SMILES: the bond on a ring closure describes
+// the bond between the two ring-closure atoms.
+// ============================================================
+atom_unit
+  = atom:atom ring_bonds:(bond? ring_marker)* branches:branch* {
+      const rings = ring_bonds.map(rb => ({
+        bond: rb[0],
+        number: rb[1]
+      }));
+      return { atom, rings, branches };
+    }
+
+// ============================================================
+// Atoms
+//
+// Two forms, matching tokenizer.js:
+//   1. Bracketed: '[' ... ']'  (parseBracketedAtom, line 67)
+//   2. Simple: [A-Za-z*]       (parseSimpleAtom, line 39)
+// ============================================================
+atom
+  = bracketed_atom
+  / simple_atom
+
+// ----------------------------------------------------------
+// Bracketed atom: [isotope? element chirality? hcount? charge? class?]
+//
+// The codebase currently stores only { raw } (parseBracketedAtom, line 79).
+// We parse the sub-fields here since PEG makes it easy and consumers
+// can use them. The `raw` field preserves the full bracket text for
+// round-trip fidelity (matching token.value in the codebase).
+// ----------------------------------------------------------
+bracketed_atom
+  = "[" content:bracketed_content "]" {
+      return { type: "bracket_atom", ...content, raw: text() };
+    }
+
+bracketed_content
+  = isotope:isotope?
+    symbol:bracket_element
+    chirality:chirality?
+    hcount:hcount?
+    charge:charge?
+    atomClass:atom_class? {
+      return { isotope, symbol, chirality, hcount, charge, atomClass };
+    }
+
+// Isotope: digits before the element symbol
+// e.g. [13C], [2H]
+isotope
+  = digits:$[0-9]+ &[A-Za-z*] { return parseInt(digits, 10); }
+
+// Element inside brackets — can be aromatic two-letter (se, as),
+// aromatic single-letter, or any standard element symbol, or wildcard
+bracket_element
+  = aromatic_element
+  / element_symbol
+  / "*" { return "*"; }
+
+// Standard element symbol: uppercase letter + optional lowercase
+// e.g. C, Na, Fe, Zr
+element_symbol
+  = a:$[A-Z] b:$[a-z]? { return b ? a + b : a; }
+
+// Aromatic elements inside brackets
+// OpenSMILES: b, c, n, o, p, s, se, as
+aromatic_element
+  = "se" { return "se"; }
+  / "as" { return "as"; }
+  / c:[bcnops] { return c; }
+
+// Chirality: @ or @@ (the codebase doesn't parse extended forms like @TH1)
+chirality
+  = "@@" { return "@@"; }
+  / "@" { return "@"; }
+
+// Hydrogen count: H or H<digit>
+// e.g. [NH3+] has hcount=3, [C@H] has hcount=1
+hcount
+  = "H" n:$[0-9]? { return n ? parseInt(n, 10) : 1; }
+
+// Charge: +, -, +2, -1, ++, --
+// Ordered to try multi-char patterns before single-char
+charge
+  = "++" { return 2; }
+  / "--" { return -2; }
+  / "+" n:$[0-9]+ { return parseInt(n, 10); }
+  / "-" n:$[0-9]+ { return -parseInt(n, 10); }
+  / "+" { return 1; }
+  / "-" { return -1; }
+
+// Atom class: :<digits>
+// e.g. [C:1]
+atom_class
+  = ":" n:$[0-9]+ { return parseInt(n, 10); }
+
+// ----------------------------------------------------------
+// Simple (non-bracketed) atom
+//
+// Mirrors tokenizer.js parseSimpleAtom (line 39) + isAtomStart (line 31):
+//   isAtomStart accepts /[A-Za-z*]/
+//   parseSimpleAtom checks for two-letter Cl/Br first, then single char
+//
+// The codebase does NOT restrict to the OpenSMILES organic subset —
+// it accepts any letter as a valid atom. This is intentional for
+// permissive parsing. The semantic layer validates later.
+// ----------------------------------------------------------
+simple_atom
+  = symbol:simple_atom_symbol { return { type: "simple_atom", symbol }; }
+
+simple_atom_symbol
+  = "Br" { return "Br"; }
+  / "Cl" { return "Cl"; }
+  / c:[A-Za-z] { return c; }
+  / "*" { return "*"; }
+
+// ============================================================
+// Bonds
+//
+// Mirrors: BOND_SYMBOLS in tokenizer.js (line 19)
+//   new Set(['-', '=', '#', ':', '/', '\\'])
+// ============================================================
+bond
+  = b:[-=#:/\\] { return b; }
+
+// ============================================================
+// Ring markers
+//
+// Mirrors: tokenizer.js lines 138-160
+//   '%' + two digits → ring number 10-99
+//   single digit     → ring number 0-9
+// ============================================================
+ring_marker
+  = "%" d1:[0-9] d2:[0-9] { return parseInt(d1 + d2, 10); }
+  / d:[0-9] { return parseInt(d, 10); }
+
+// ============================================================
+// Branches (recursive)
+//
+// Mirrors: BRANCH_OPEN → (bond? chain) → BRANCH_CLOSE
+// in tokenizer.js lines 106-120 and buildAtomList lines 139-153
+//
+// A branch can start with a bond that applies to the first atom
+// of the branch chain (e.g. C(=O) means double bond to O).
+// ============================================================
+branch
+  = "(" _ b:bond? _ c:chain _ ")" {
+      return { type: "branch", bond: b, chain: c };
+    }
+
+// ============================================================
+// Whitespace (optional, skipped)
+//
+// Mirrors: tokenizer.js line 104 — /\s/ is skipped
+// ============================================================
+_ "whitespace"
+  = [ \t\n\r]*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smiles-js",
-  "version": "2.0.3",
+  "version": "2.2.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 || '');