API overview

Two first-class surfaces — same paint underneath.

API	Entry points	Role
Single molecule	mol / render / toSvg (JS, Python, Rust)	Imperative one-mol client
Declarative document	depict / render(doc)	Nested JSON; expanding toward full PictSpec

Chem scripts: Label markup.

Language	Autodoc
Python	mkdocstrings
JavaScript	TypeDoc
Rust	rustdoc

---

Single molecule

Flow: mol(source) → render(opts?) → Rendered → toSvg(scene).

Rendered.scene is editable JSON; call toSvg when you want a string. align_to accepts a prior Mol or Rendered (JS / Python) or a pose molblock (Rust).

JavaScriptPythonRust

import { xpict } from "@xenosite/xpict";

const benzene = xpict.mol("c1ccccc1");
const rendered = await xpict.render(benzene, {
  color: "#0b6e4f",
  atom_shade: [0, 0, 0.2, 0, 0, 0.9],
  weight: 1.0,
});
const svg = xpict.toSvg(rendered.scene);

const aligned = await xpict.render(xpict.mol("Cc1ccccc1"), {
  align_to: benzene,
});

const starred = await xpict.render(xpict.mol("*C"), {
  star_labels: ["$R_1$"],
});

from xpict import mol, render, to_svg

benzene = mol("c1ccccc1")
rendered = render(benzene, {
    "color": "#0b6e4f",
    "atom_shade": [0, 0, 0.2, 0, 0, 0.9],
    "weight": 1.0,
})
svg = to_svg(rendered.scene)

aligned = render(mol("Cc1ccccc1"), {"align_to": benzene})

starred = render(mol("*C"), {"star_labels": ["$R_1$"]})

use xpict::{mol, MolRenderOptions};

let mut benzene = mol("c1ccccc1")?;
let rendered = benzene.render(MolRenderOptions {
    color: Some("#0b6e4f".into()),
    atom_shade: Some(vec![0.0, 0.0, 0.2, 0.0, 0.0, 0.9]),
    ..Default::default()
})?;
let svg = rendered.to_svg();

`color`

Atom shading

Molecule 2 (`align_to`)

`star_labels` / CX

render options

Option	Effect
color	Backbone / label ink
atom_shade / bond_shade	Plot-dot shading scores (layout order)
star_labels	Labels for * atoms (encounter order); chem markup supported
weight	Ink weight relative to house (1.0); min 2/3 (Regular stem)
scale	Uniform diagram scale (1.0 = house size)
align_to	Pose of another mol (Mol / Rendered in JS & Python; molblock in Rust)
id	Optional molecule id on the paint ABI

When star_labels is omitted, CXSMILES |$…$| aliases apply by atom index.

---

Declarative document

Nested JSON: type: "mol" or type: "group" + children. Fields today: structure strings, id, color, shade, star_labels, scale, weight. Markush text uses star_labels (encounter order; chem markup OK) or CXSMILES aliases (|$R1;;;;;$|). A document rgroups key is not public yet.

This document model is a strict subset of future PictSpec and is being expanded as features graduate from xpict.future.

JavaScriptPythonRust

const [r] = await xpict.depict({
  type: "mol",
  smiles: "CCO",
  color: "#0b6e4f",
  shade: { atoms: [0.0, 0.2, 0.9], vmin: 0, vmax: 1 },
});
const svg = xpict.toSvg(r.scene);

const batch = await xpict.depict({
  type: "group",
  children: [
    { type: "mol", smiles: "*c1ccccc1Cl", star_labels: ["$R_1$"] },
    { type: "mol", smiles: "c1ccccc1O" },
  ],
});

from xpict import render

svg = render({
    "type": "mol",
    "smiles": "CCO",
    "color": "#0b6e4f",
    "shade": {"atoms": [0.0, 0.2, 0.9], "vmin": 0.0, "vmax": 1.0},
})

svg = render({
    "type": "group",
    "children": [
        {"type": "mol", "smiles": "*c1ccccc1Cl", "star_labels": ["$R_1$"]},
    ],
})

use xpict::{depict, DepictSpec, MolNode};

let out = depict(&DepictSpec::Group {
    id: None,
    children: vec![
        MolNode {
            smiles: Some("CCO".into()),
            color: Some("#0b6e4f".into()),
            ..Default::default()
        },
    ],
})?;
let svg = out[0].to_svg();

Ethanol

CX on a mol node

Contracts: DepictSpec / MolNode in xpict.contracts.depict — see Contracts.