asciichem 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f9929cd67fc49ac37896dce9ebc173306615fb08b704fd96ddfa14c09189afd
+  data.tar.gz: dc7bc12b0914610807bdd168f18b2e4b1e281519bbd5698a5c7e08d660b49d83
+SHA512:
+  metadata.gz: 13f7ec97ce27c022cfac8e9df9944ae9860c949d8bb8569995b113f846a4fb5a0052bf0d6def2374fcaa11b140187d5c38c73e8afb66b0ca77ff3f558f1a994a
+  data.tar.gz: 161b22b36e6eaeb599b7bbae7666c45574d2a17b4abf5127cdbc4fe9e3c8a558b8e8de00d0149c45a58bf4c062368fb79526ef70cdd9f10ad50a6d6cdd169982

data/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.3", "3.4"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rspec

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/tmp/
+/ruby/
+/.vscode/
+/.idea/
+*.gem

data/.rubocop.yml

@@ -0,0 +1,50 @@
+require:
+  - rubocop
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.3
+  Exclude:
+    - "pkg/**/*"
+    - "vendor/**/*"
+    - "coverage/**/*"
+
+# Parser grammars benefit from short methods; parslet DSL reads top-to-bottom.
+Metrics/MethodLength:
+  Max: 40
+  Exclude:
+    - "lib/asciichem/parser.rb"
+
+Metrics/ClassLength:
+  Max: 200
+  Exclude:
+    - "lib/asciichem/parser.rb"
+    - "lib/asciichem/transform.rb"
+
+# Specs read better with non-trivial blocks.
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+
+# Visitor dispatch methods are short by design.
+Style/Documentation:
+  Exclude:
+    - "lib/asciichem/formatter/*.rb"
+    - "lib/asciichem/model/*.rb"
+
+# CML extension modules are cohesive by design — splitting them
+# would harm readability. They each house one side-channel (atom
+# attributes, top-level elements, group preservation) plus the
+# four-method collect/inject/extract/restore cycle.
+Metrics/ModuleLength:
+  Exclude:
+    - "lib/asciichem/cml/extensions.rb"
+    - "lib/asciichem/cml/group_extensions.rb"
+
+# Short names for chemistry primitives (`el` for element, `iso`
+# for isotope) match the grammar's term set.
+Naming/MethodParameterName:
+  Exclude:
+    - "lib/asciichem/cml/group_extensions.rb"
+    - "lib/asciichem/transform.rb"

data/ARCHITECTURE.adoc

@@ -0,0 +1,239 @@
+= AsciiChem Architecture
+
+AsciiChem is an ASCII syntax for representing chemistry: atoms,
+molecules, bonds, reactions, electron configurations, and embedded
+mathematics. It parses text into a semantic model and renders the model
+to multiple output formats.
+
+This document is the durable reference for contributors. The
+https://www.asciichem.org[site] is the user-facing spec; this file is
+the implementation guide.
+
+== Layers
+
+```
+          ┌─────────────┐
+text ───► │   Grammar   │   parslet parser, flat-hash tree
+          └──────┬──────┘
+                 ▼
+          ┌─────────────┐
+          │  Transform  │   tree → model, with builder helpers
+          └──────┬──────┘
+                 ▼
+          ┌─────────────┐
+          │   Model     │   Formula, Atom, Molecule, Group, Bond,
+          │             │   Reaction, ElectronConfiguration,
+          │             │   EmbeddedMath, Text
+          └──────┬──────┘
+                 ▼
+          ┌──────────────────────────────────────────────┐
+          │  Formatter (visitor)                         │
+          │  ┌─────────┐ ┌──────┐ ┌───────┐ ┌─────┐ ┌───┐ │
+          │  │ Mathml  │ │ Text │ │ HTML  │ │ LaTeX │ … │ │
+          │  └─────────┘ └──────┘ └───────┘ └─────┘ └───┘ │
+          └──────────────────────────────────────────────┘
+                 ▼
+          output (string)
+```
+
+The model is the contract. Every formatter consumes the same tree; the
+parser and transform never reach past it.
+
+== The semantic fix
+
+The defining difference from AsciiMath is captured at the parser/model
+boundary, not in any one formatter.
+
+[cols="1,2,2"]
+|===
+| Input | AsciiMath | AsciiChem
+
+| `^14C`
+| `<msup><mi></mi><mn>14</mn></msup><mi>C</mi>` (empty base + sibling)
+| `Atom(element: "C", isotope: "14")` → `<msup><mi>C</mi><mn>14</mn></msup>`
+
+| `Ca^2+`
+| `<msup><mi>Ca</mi><mn>2+</mn></msup>` (charge as undifferentiated super)
+| `Atom(element: "Ca", charge: "2+")` → `<msup><mi>Ca</mi><mrow><mn>2</mn><mo>+</mo></mrow></msup>`
+
+| `1s^2 2s^2`
+| `msub/msup` soup, no orbital concept
+| `ElectronConfiguration(orbitals: [["1s","2"], ["2s","2"]])`
+|===
+
+The grammar enforces binding structurally. `prefixed_atom` consumes
+`^digits element` as a single unit; a bare `^digits` with no following
+element is rejected. The model carries the binding in a typed field.
+
+== Model classes
+
+[cols="1,3,3,3"]
+|===
+| Class | Role | Key fields | Invariants
+
+| `Formula`
+| Top-level container, root of every parse.
+| `nodes: Array<Node>`
+| `nodes` may be empty (e.g. parse error fallback).
+
+| `Atom`
+| A chemical atom.
+| `element: String`, `isotope: String?`, `subscript: String?`, `superscript: String?`, `charge: String?`, `oxidation_state: String?`
+| Exactly one of `{superscript, charge, oxidation_state}` is set; they are mutually exclusive views of the suffix super position.
+
+| `Molecule`
+| Ordered list of atoms/groups with optional stoichiometric coefficient.
+| `nodes: Array<Atom \| Group \| Bond \| ...>`, `coefficient: String?`
+| Multiplicity lives on inner atoms/groups, not on the molecule.
+
+| `Group`
+| Parenthesised sub-formula with outer multiplicity.
+| `nodes: Array`, `multiplicity: String?`, `bracket: :paren \| :square \| :brace`
+| Round-trip preserves bracket kind.
+
+| `Bond`
+| A bond between two adjacent nodes in a chain.
+| `kind: :single \| :Double \| :triple \| :wedge \| :hash \| :dative \| :wavy`
+| Endpoints are positional in the parent sequence.
+
+| `Reaction`
+| Reactants + arrow + products, with optional conditions.
+| `reactants: Array<Molecule>`, `products: Array<Molecule>`, `arrow: :forward \| :reverse \| :equilibrium \| :resonance`, `conditions: Conditions?`
+| Arrow kinds are exhaustive; adding a new kind is a single map entry.
+
+| `ElectronConfiguration`
+| Orbital occupancy plus optional term symbol.
+| `orbitals: Array<[orbital, occupancy]>`, `term_symbol: TermSymbol?`
+| Orbital labels match `^[0-9]+[spdfgh]$`.
+
+| `EmbeddedMath`
+| A Plurimath formula embedded in chemistry.
+| `formula: Plurimath::Math::Formula`, `source: String`
+| `source` is preserved verbatim for round-trip.
+
+| `Text`
+| Catch-all for runs not promoted to a typed node.
+| `content: String`
+| The grammar is total; unparseable fragments land here rather than failing.
+|===
+
+Every model class:
+
+* Inherits from `AsciiChem::Model::Node`.
+* Declares `value_attributes` returning the hash of fields that
+  participate in equality (avoids reflective instance variable access).
+* Implements `accept(visitor)` via the base class, which dispatches to
+  `visitor.visit_<snake_name>(self)`.
+
+== Extension points (OCP)
+
+The system is open for extension in three dimensions; each dimension
+requires edits in exactly one place.
+
+=== Adding a new construct
+
+1. Add a model class under `lib/asciichem/model/`, inheriting from
+   `Node`. Declare `value_attributes`.
+2. Add an autoload entry in `lib/asciichem/model.rb`.
+3. Add grammar productions in `lib/asciichem/grammar.rb`.
+4. Add a transform rule in `lib/asciichem/transform.rb`.
+5. Add `visit_<class>` methods to each formatter (the base class raises
+   `NotImplementedError` so gaps surface immediately).
+
+No existing model/parser/formatter code is modified.
+
+=== Adding a new output format
+
+1. Create `lib/asciichem/formatter/<name>.rb` with a class inheriting
+   from `AsciiChem::Formatter::Base`.
+2. Implement one `visit_<class>` method per model class.
+3. Add `autoload :<ClassCamel>, "asciichem/formatter/<name>"` to
+   `lib/asciichem/formatter.rb`.
+4. Optionally add `to_<name>` to `Model::Node`.
+
+The format is reachable via `AsciiChem::Formatter[<name>]` — no switch
+statement, no registry of instances. Adding the autoload entry is the
+only required change to an existing file.
+
+=== Adding a new arrow / bond / bracket kind
+
+Each enum (`Reaction::ARROWS`, `Bond::KINDS`, `Group#bracket`) is a
+constant hash. Adding a kind is a single entry; the formatter reads from
+the hash, not from a switch statement.
+
+== Plurimath interop
+
+Mathematics embedded in chemistry is delegated to
+{Plurimath}[https://github.com/plurimath/plurimath].
+
+* `EmbeddedMath` wraps a `Plurimath::Math::Formula`.
+* The grammar captures backtick-delimited runs as raw text and passes
+  them to `Plurimath::Asciimath.new(source).to_formula` at transform
+  time.
+* The MathML formatter calls the wrapped formula's `to_mathml` and
+  strips the outer `<math>` so the fragment slots into AsciiChem's
+  `<mrow>`.
+* The Text formatter emits the original backtick-delimited source
+  verbatim.
+
+AsciiChem does not reinvent math typography. Anywhere math appears in
+chemistry (rate laws, equilibrium constants, Arrhenius expressions),
+Plurimath handles it.
+
+== Glossary
+
+[cols="1,3"]
+|===
+| Term | Definition
+
+| Atom
+| A chemical atom with element symbol and optional isotope, charge,
+  oxidation state, or subscript multiplicity.
+
+| Molecule
+| An ordered sequence of atoms/groups plus an optional leading
+  stoichiometric coefficient.
+
+| Group
+| A parenthesised sub-formula with an outer multiplicity. Brackets
+  may be `()`, `[]`, or `{}`.
+
+| Bond
+| A connection between two adjacent nodes in a structural chain.
+  Single, double, triple, wedge, hash, dative, or wavy.
+
+| Reaction
+| A transformation with reactants, an arrow, and products, plus
+  optional conditions above/below the arrow.
+
+| ElectronConfiguration
+| A list of orbital/occupancy pairs plus an optional term symbol.
+
+| EmbeddedMath
+| A Plurimath formula embedded in chemistry text.
+
+| Prefix isotope
+| A mass number written before the element symbol, e.g. `^14C`. The
+  binding to the atom is the headline semantic fix over AsciiMath.
+
+| Stoichiometric coefficient
+| Leading digits on a molecule, e.g. the `2` in `2H_2O`.
+
+| Canonical form
+| The AsciiChem text that the Text formatter emits. Round-trip
+  conformance: `parse(s).to_text == s` for any canonical `s`.
+|===
+
+== Constraints honoured
+
+* No `require_relative` for internal code; `autoload` everywhere,
+  declared in the immediate parent namespace's file.
+* No `instance_variable_set` / `instance_variable_get`. Equality uses
+  declared `value_attributes`.
+* No `respond_to?` type checks. `is_a?` only.
+* No `send` to private methods. The visitor dispatch uses
+  `public_send` against public `visit_*` methods.
+* No `double()` in specs. Real instances or `Struct`s.
+* No hand-rolled model serialisation. The model is in-memory only;
+  rendering to MathML / HTML / etc. is one-way output via Nokogiri or
+  string building, not `(de)serialisation`.

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to AsciiChem are documented here.
+This project follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- Initial gem scaffold: autoload tree, version, errors.
+- Core model: `Formula`, `Atom`, `Molecule`, `Group`, `Bond`, `Reaction`,
+  `ElectronConfiguration`, `EmbeddedMath`, `Text`.
+- Parslet parser and transform for v1 constructs.
+- Formatters: MathML and Text (round-trip).
+- Thor-based CLI: `convert`, `roundtrip`, `version`.
+- Comprehensive RSpec suite with round-trip conformance.
+
+[Unreleased]: https://github.com/asciichem/asciichem-ruby/commits/main

data/CLAUDE.md

@@ -0,0 +1,318 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+The reference implementation of **AsciiChem** — an ASCII syntax for
+chemistry (atoms, molecules, bonds, reactions, electron
+configurations, embedded math). Parses text into a semantic model and
+renders the model to MathML, Text, HTML, LaTeX, SVG, and CML.
+
+Sister repo: `../asciichem.github.io` is the specification site. When
+a spec page describes syntax, the gem must implement it; when the gem
+adds a feature, a spec page must document it. The site's
+`TODO.impl/` directory tracks cross-repo work; this repo's
+`TODO.gem/` directory tracks gem-side work.
+
+## Why this exists (the semantic fix)
+
+AsciiMath is insufficient for chemistry: prefix superscripts/subscripts
+have no atom to bind to (AsciiMath forces a phantom `{}` carrier),
+and there's no native syntax for stoichiometric coefficients, reaction
+arrows, conditions, spectator ions, electron configurations, term
+symbols, or bonds. AsciiChem closes these gaps. The defining fix
+lives at the parser/model boundary: `^14C` parses as
+`Atom(element: "C", isotope: "14")` — the isotope binds to the atom,
+not to a phantom empty element.
+
+## Commands
+
+```bash
+bundle install                          # install dependencies (chemicalml 0.1.0 from rubygems)
+bundle exec rake spec                   # run the full spec suite
+bundle exec rspec spec/asciichem/cml/   # run specs in a directory
+bundle exec rspec -e "round-trips"      # run specs matching a name
+bundle exec rubocop                     # lint
+bundle exec rake build                  # build the gem into pkg/
+bundle exec ./exe/asciichem convert -i "H_2O" -t mathml  # smoke-test the CLI
+```
+
+The default `rake` task is `:spec`. RSpec is configured for
+randomised order, profile of the 10 slowest examples, and
+`spec/examples.txt` persistence. `config.warnings = true` — Ruby
+warnings fail the suite.
+
+## High-level architecture
+
+```
+text ─► Grammar (parslet) ─► Transform ─► AsciiChem::Model ─► Formatter (visitor)
+                                              │
+                                              ▼
+                                    ModelAdapter (bidirectional)
+                                              │
+                                              ▼
+                            Chemicalml::Model (canonical, in chemicalml gem)
+                                              │
+                                              ▼
+                            Chemicalml::Cml (CML wire, in chemicalml gem)
+```
+
+### Five layers, MECE
+
+1. **Grammar** (`lib/asciichem/grammar.rb`) — a Parslet parser.
+   Leaf rules return strings; `.as(:name)` is applied at the
+   combination site so the parse tree is a flat hash of named strings
+   wherever practical. The prefix-isotope binding (`^14C`) is enforced
+   *structurally*: `prefixed_atom` consumes `^digits element` as a
+   unit; a bare `^digits` with no following element is rejected.
+
+2. **Transform** (`lib/asciichem/transform.rb`) — a Parslet transform
+   that converts the flat parse tree into a tree of `Model::*`
+   instances. Minimal logic; the grammar encodes semantics, not the
+   transform. Builder classes (`AtomBuilder`, `ReactionBuilder`,
+   `CascadeBuilder`) keep constructor-call mapping readable.
+   `TextNormaliser.strip_quotes` removes the surrounding `"..."` from
+   quoted-text matches so the model never carries the delimiters; the
+   Text formatter re-adds them on output.
+
+3. **Model** (`lib/asciichem/model/`) — the semantic hub. Every
+   formatter consumes the same tree. Classes: `Formula`, `Atom`,
+   `Molecule`, `Group`, `Bond`, `Reaction`, `ReactionCascade`,
+   `ElectronConfiguration`, `EmbeddedMath`, `Text`. All inherit from
+   `Model::Node`, which provides structural equality (via
+   `value_attributes`), visitor dispatch (`accept`), and the
+   `to_<format>` shortcuts.
+
+   **Text syntax.** Free-form text uses `"..."` delimiters (matching
+   AsciiMath). Unquoted prose that isn't chemistry raises
+   `ParseError`; this is intentional — silently swallowing arbitrary
+   content as Text was a bug magnet. Embedded math uses backticks
+   (`` `...` ``) and is handled by a separate grammar rule.
+
+4. **Formatter** (`lib/asciichem/formatter/`) — one visitor per output
+   format. Each subclass of `Formatter::Base` implements one
+   `visit_<class>` method per `Model::*` class. Missing visits raise
+   `NotImplementedError` so gaps surface at first use, not silently.
+   Reachable via `Formatter[:name]` (triggers autoload).
+
+5. **ModelAdapter** (`lib/asciichem/model_adapter/`) — bridges
+   `AsciiChem::Model` and the canonical `Chemicalml::Model` (which
+   lives in the chemicalml gem). The adapter is bidirectional and
+   pure; no I/O. Composed with `Chemicalml::Cml::Translator` it
+   forms the AsciiChem ↔ CML pipeline.
+
+### Linter (opt-in)
+
+`lib/asciichem/linter/` is a separate pass that walks the model and
+reports chemistry errors. Checks self-register via
+`Linter::Base.register(:name)` inside their class body; the
+`Linter` module eagerly triggers every autoload at load time so
+registration runs before any API query.
+
+Built-in checks:
+
+- `BalanceCheck` — stoichiometric balance of reactions.
+- `BracketBalanceCheck` — group bracket consistency.
+- `ElementValidationCheck` — warns on element symbols not in the
+  periodic table (catches typos like `Hx`, `Cy`).
+- `IsotopeSanityCheck` — isotope mass ≥ atomic number.
+- `UnclosedRingCheck` — errors on ring closure digits with no
+  matching partner (`C1-C-C` is unmatched).
+- `ValenceCheck` — atom bond order + charge ≤ max valence.
+
+All element data (symbol, atomic number, max valence) is sourced
+from `AsciiChem::PeriodicTable` — the single source of truth.
+Adding a new field (covalent radius, common oxidation states) is
+one column on `Element` plus populating it; the linter picks it up
+automatically.
+
+### Ring closures (SMILES-style)
+
+Atoms can carry a digit suffix that opens or closes a ring:
+`C1-C-C-C-C-C1` is cyclohexane. The `Atom#ring_closures` field
+holds the digit string. `AsciiChem::RingBonds` is the single source
+of truth for the "find ring bond pairs" algorithm — Layout,
+ModelAdapter, and the UnclosedRingCheck linter all consume it.
+Multiple closures on one atom (`C12-C-C1-C2`) and fused rings are
+supported.
+
+### Layout (2D structural SVG)
+
+`lib/asciichem/layout.rb` converts a `Model::Molecule` into an elkrb
+graph, runs the layout algorithm, and returns positioned atoms + bonds.
+The `Formatter::StructuralSvg` visitor consumes the result. For
+molecules without bonds it falls back to the linear SVG formatter.
+
+Three MECE concerns inside Layout:
+
+- `MoleculeWalker` — walks the AsciiChem tree, assigns stable IDs,
+  produces a neutral atom+bond list. Pure; no elkrb dependency.
+- `GraphBuilder` — converts the walker's neutral list into an
+  elkrb `Graph::Graph` with proper nodes and edges.
+- `ResultExtractor` — maps elkrb's laid-out positions back onto the
+  walker's neutral list, producing a `Layout::Result`.
+
+Default algorithm is `layered` (Sugiyama-style hierarchical) for
+deterministic output across runs — essential for visual regression.
+`force` is available but may produce different output between runs.
+
+The `StructuralSvg` formatter uses a registry of bond-kind strategies
+(Procs). Adding a new bond style is one Proc + one registry entry;
+no edits to existing renderers.
+
+## Extension points (OCP)
+
+The system is open for extension in three dimensions; each dimension
+requires edits in exactly one place.
+
+- **New construct** — add a model class under `lib/asciichem/model/`,
+  autoload it from `lib/asciichem/model.rb`, add grammar productions
+  to `grammar.rb`, a transform rule in `transform.rb`, and a
+  `visit_<class>` method on each formatter.
+- **New output format** — create `lib/asciichem/formatter/<name>.rb`
+  subclassing `Formatter::Base`, implement one `visit_<class>` per
+  model class, and add the autoload to `lib/asciichem/formatter.rb`.
+  Optionally add `to_<name>` to `Model::Node`. The `Formatter[:name]`
+  lookup camelises snake_case names, so `:structural_svg` resolves
+  to `StructuralSvg`.
+- **New arrow / bond / bracket kind** — each enum
+  (`Reaction::ARROWS`, `Bond::KINDS`, `Group#bracket`) is a constant
+  hash. Adding a kind is a single entry; formatters read from the hash.
+  For SVG rendering, also add a strategy Proc to
+  `StructuralSvg::BondRenderer::RENDERERS`.
+- **New linter check** — subclass `Linter::Base`, call `register(:name)`
+  in the class body, implement `run(formula)`. The check self-registers
+  at file-load time; the `Linter` module eagerly triggers every
+  autoload so registration runs before any API query.
+- **New model class** — add the class under `lib/asciichem/model/`,
+  autoload from `lib/asciichem/model.rb`. Override `diagnostic_label`
+  if the default (snake-case → space-separated capitalized words)
+  isn't suitable. No edits to `Linter::Diagnostic` — it reads
+  `node.diagnostic_label` polymorphically.
+
+## CML and the canonical model
+
+`AsciiChem::Cml` provides bidirectional CML XML conversion via the
+chemicalml gem. The pipeline is:
+
+```
+AsciiChem::Model ↔ AsciiChem::ModelAdapter ↔ Chemicalml::Model
+                                                       ↑
+                                                       │
+                                            Chemicalml::Cml::Translator
+                                                       │
+                                                       ▼
+                                            Chemicalml::Cml::* (wire)
+                                                       │
+                                                       ▼
+                                                       XML
+                                                       │
+                                            AsciiChem::Cml::Extensions
+                                            (aci: namespace side-channel)
+```
+
+- `formula.to_cml` delegates to `AsciiChem::Cml.from_asciichem`.
+- `AsciiChem::Cml.parse(xml)` delegates to
+  `AsciiChem::Cml::Translator.to_asciichem`.
+- `chemicalml` requires `Chemicalml::Cml::Schema3.ensure_registered!`
+  before first wire-class use. `Cml::Translator` calls it lazily.
+
+### aci: extension namespace
+
+CML's standard wire format doesn't cover oxidation state, Lewis
+markers, electron configuration, embedded math, free-form text, or
+group structure. AsciiChem carries these through XML round-trip via
+an `aci:` (AsciiChem extension) namespace on the CML root. Three
+channels, one per scope:
+
+- **Atom attributes** (per-atom fields): `aci:<wire_name>` on
+  `<atom>` elements. Registry: `AsciiChem::Cml::Extensions::FIELDS`
+  (covers oxidation_state, lone_pairs, radical_electrons).
+- **Top-level elements** (standalone constructs):
+  `<aci:<element_name> position="N">...</aci:...>` children of
+  `<cml>`. Registry: `Extensions::TOP_LEVEL_HANDLERS` (covers
+  ElectronConfiguration, EmbeddedMath, Text). Position preserves
+  node ordering in the formula.
+- **Molecule-level elements** (structural concepts):
+  `<aci:group multiplicity="N" bracket="X" atomRefs="..."/>` children
+  of `<molecule>`. Managed by `AsciiChem::Cml::GroupExtensions`
+  (preserves AsciiChem Group nodes through the canonical-model
+  flattening). Bracket kinds mapped via frozen
+  `BRACKET_TO_WIRE` hash.
+
+Adding a new extension is one entry in the appropriate frozen
+registry. No other code changes. The `xmlns:aci` declaration appears
+only when at least one extension is present; plain atoms/molecules
+produce clean CML.
+
+The `ModelAdapter::ToCanonical::MoleculeWalker` records group
+membership during the canonical walk via a `GroupRecord` struct,
+exposed through `Translation#groups`. `IdRegistry::PREFIXES`
+includes `:group => "g"` so group IDs (`g1`, `g2`, ...) don't
+collide with atom/bond/molecule IDs.
+
+**Known limitations** (each guarded by a spec):
+- 3D coordinates, spectroscopy, polymer notation — out of scope for v0.2.
+
+See `TODO.gem/03-canonical-model-gaps.md` (all five canonical-model
+gaps now closed) and `TODO.gem/09-group-preservation.md` (Group
+preservation design).
+
+## Critical constraints (project-specific)
+
+The global `~/.claude/CLAUDE.md` is authoritative. Highlights that
+apply most directly here:
+
+- **Never use `require_relative`** for internal library code, and
+  never use path-based `require` for files inside `lib/asciichem/`.
+  Use Ruby `autoload`, declared in the immediate parent namespace's
+  file (e.g. `lib/asciichem/model.rb` autoloads `Model::Atom`).
+- **Never hand-roll serialization.** The model is in-memory only.
+  CML wire (de)serialization goes through `lutaml-model` in the
+  chemicalml gem. AsciiChem itself never writes a `to_h` / `from_h`
+  / `to_xml` / `from_xml` on a model class.
+- **No `double()` in specs.** Use real `Model::*` instances or
+  lightweight `Struct`s.
+- **No `send` to private methods, no `instance_variable_set` /
+  `instance_variable_get`, no `respond_to?` type checks.** Visitor
+  dispatch uses `public_send` against public `visit_*` methods.
+- **Never commit to `main`, never push tags, never push to `main`.**
+  Every change goes through a PR.
+- **Never add AI attribution** to commit messages, PR descriptions,
+  code comments, or changelog entries.
+
+## Specs and conformance
+
+- **Round-trip conformance** is the contract: `AsciiChem.parse(s).to_text == s`
+  for any canonical `s`. The Text formatter is the canonicaliser.
+- **Three-way round-trip** for CML: `parse(s).to_cml` →
+  `Cml.parse(...)` → `.to_text` equals `s`. See
+  `spec/asciichem/cml/cml_spec.rb` and the comprehensive case list
+  in `spec/integration/edge_cases_spec.rb`.
+- **Corpus fuzzing** at `spec/fuzz/corpus/` — 15 files exercising
+  edge cases. Every line must either parse or raise
+  `AsciiChem::ParseError` cleanly (no raw exceptions).
+- **Edge cases** in `spec/integration/edge_cases_spec.rb` — 60+
+  cases covering parser robustness (malformed inputs raise
+  ParseError cleanly), parser acceptance (every documented
+  construct), text and CML round-trip conformance, deterministic
+  output across runs, formatter registry, linter coverage, and
+  periodic-table coverage.
+- **Known limitations are spec'd.** Don't silently drop constructs on
+  round-trip; write a spec that documents the loss and link it to a
+  `TODO.gem/` item that will close the gap.
+
+## Performance
+
+Manual benchmarks at `benchmarks/benchmark.rb`. Run with
+`bundle exec ruby benchmarks/benchmark.rb`. Covers parse, text
+round-trip, MathML output, and CML round-trip. CI does not run
+benchmarks; they are a development-time regression check.
+
+## Releasing
+
+See `RELEASING.md` for the full release runbook. Short version:
+bump `lib/asciichem/version.rb`, update `CHANGELOG.md`, open a PR,
+merge, then (maintainer only) tag and `gem push`. Never push tags
+yourself.

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development do
+  gem "benchmark", "~> 0.4"
+  gem "benchmark-ips", "~> 2.14", require: false
+  gem "rake", "~> 13.2"
+  gem "rspec", "~> 3.13"
+  gem "rubocop", "~> 1.66", require: false
+  gem "simplecov", "~> 0.22", require: false
+end