npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@citolab/pci-molecule-builder

v1.0.0-alpha.1

Published

build molecules from atoms and bonds, in 3D (ball-and-stick, VSEPR) or as a structural formula; scored on a canonical SMILES or by checks

Readme

@citolab/pci-molecule-builder

[!WARNING] Experimental (alpha). Just for inspiration. This PCI is a technical showcase, made by software developers without much knowledge of the subject it could be used for. Its content, terms and scoring have not been checked by subject experts or assessment specialists, and it has never been used in an assessment. It is offered as is, without any warranty.

A QTI 3 Portable Custom Interaction (PCI) in which the candidate builds a molecule from atoms: they add hydrogen, carbon, nitrogen, oxygen (and whatever else the author allows) from a palette, connect them with single, double and triple bonds and see the molecule as a 3D ball-and-stick model with a VSEPR shape (tetrahedral, trigonal, linear, bent), or as a structural formula. The response is the molecule as a canonical string, the same however and in whatever order it was drawn, so a QTI response processing can score it with match; or the PCI scores the author's checks itself. Made for chemistry in Dutch vmbo (nask2): H₂O, CO₂, CH₄, NH₃, O₂, C₂H₅OH. Made with tspci.

What it does

  • Atoms: H, C, N, O, F, Cl, Br, I, S and P, with their school valence (H 1, C 4, N 3, O 2, the halogens 1, S 2, P 3). The balls have the CPK colours and always the element's letter (in the palette, the 3D model and the structural formula), and the palette shows the number of bonds, so colour is never the only cue.
  • Building: a palette button (or the element's key: H, C, N, O, F, S, P, I, L for Cl, B for Br) adds the atom with a single bond to the selected atom; the selection stays, so C H H H H is methane. With nothing selected, or when the selected atom has no bond free, the atom comes on its own. Connect (or Space/Enter) and then the other atom (a click, or select it and Space) bonds two atoms; doing it again makes the bond double, triple, and removes it. A click on a bond does the same. Delete, Undo (Ctrl+Z) and Start again.
  • 3D model (three.js 0.180): positions from a VSEPR-like layout (src/geometry.ts): bond lengths from the covalent radii (shorter for double and triple bonds), the angle between two bonds from the electron domains around the atom (bonds and lone pairs from the valence electrons): 180° linear (CO₂, C₂H₂), 120° trigonal (C₂H₄, flat), 109.5° tetrahedral (CH₄), 107° pyramidal (NH₃), 104.5° bent (H₂O). Double bonds keep their substituents in one plane. The model turns with a drag (mouse, touch, pen), the arrow keys or the buttons; +/− and the wheel zoom, Home resets. A click (no drag) picks an atom or a bond by raycasting. A change of shape glides into place, or jumps with prefers-reduced-motion. Without WebGL the structural formula takes over with a message. The renderer and its WebGL context are freed when the view changes, the PCI is removed or leaves the page.
  • Structural formula (fully keyboard accessible): the atoms on a grid with their bonds as one, two or three lines. It is a listbox with the selected atom as its active descendant: the arrow keys go to the nearest atom in that direction, Shift + arrow moves the atom, Home/End the first and last atom. A screen reader hears every atom with its bonds ("C 1, carbon: single bond to C 2, single bond to H 3 …; 1 free bond"); a live status line tells every step. Drag an atom with the mouse to move it. Atoms get a place next to the atom they bond to (a chain to the right, hydrogens above, below and at the ends), as Dutch schools draw structural formulas.
  • Feedback (both can be switched off): the molecular formula as pupils learn it (NH₃, HCl, H₂O, H₂SO₄, NaOH; carbon compounds in Hill order: CH₄, CO₂, C₂H₆O), or in Hill order with data-formula-order="hill", and the free bonds per atom (a badge with the number on the atom, ! and "bonds too many" when there are too many). With an atom selected the shape around it and its bond angle, in the candidate's language (104,5° in Dutch).
  • Canonical string (src/molecule.ts, no imports, tested with npm test): formula:SMILES, the Hill formula (always Hill order, whatever the formula shown, so the response stays canonical: H3N:N for ammonia) and a canonical SMILES (H2O:O, CO2:O=C=O, C2H6O:CCO, C2H6O:COC). Hydrogens become counts on their atom; the atoms get a canonical labelling (partition refinement on element, hydrogens, degree and bonds; ties broken by trying each and keeping the smallest SMILES), so the drawing order, the atom numbers and the layout do not matter. Atoms with fewer hydrogens than their valence asks are written in brackets ([CH3], [OH]), separate parts are joined with ..
  • Authoring mode: the item author builds the correct molecule in the same builder, chooses the palette and the checks in the PCI itself (getAuthoringInstance), via "Configure…" ("Build the molecule…") in an authoring system that supports it (qti-construction, TAO with tspci-tao, the dev page), in three tabs: Correct molecule, Atoms in the palette and Checks (with ticks for what the correct molecule passes, its score and its correct response). validate() reports a missing molecule, an empty palette, a molecule with atoms that are not in the palette, and (with PCI scoring) no checks or a check the correct molecule fails, in the author's language.
  • Delivery: the candidate's molecule (atoms, bonds and their places in the structural formula) is saved as the item's state, with every step in the log, and restored. In review (status: "solution") the PCI shows the declared correct response, or else the author's molecule, read-only. Several interactions of this type on one page each get their own object.

What can be configured

Every setting is a data- attribute of the interaction, as text. dist/authoring.json describes them for authoring systems.

| setting | attribute | default | what | | ------------------------------ | -------------------- | ---------------------- | ------------------------------------------------------------- | | Instruction above the builder | data-prompt | build a water molecule | also part of the views' accessible names | | Molecule | data-molecule | empty: the example | written by the authoring mode, as JSON (below) | | Scoring | data-scoring | match | match: a string for match; pci: a record with the checks | | Show the molecular formula | data-show-formula | true | | | Show the free bonds per atom | data-show-valence | true | the badges on the atoms and the list of free bonds | | Order of the formula shown | data-formula-order | common | common: NH₃, HCl, H₂SO₄; hill: H₃N, ClH, H₂O₄S. Only what is shown: the response and the checks use Hill order | | View at the start | data-view | 3d | 3d or 2d (structural formula); both are always there | | Atoms at most | data-max-atoms | 24 | 2 to 60 | | Language | data-language | en | en or nl: the texts and numbers of the PCI |

{
  "elements": "H C O",
  "solution": "CCO",
  "checks": [
    { "type": "formula", "points": 1 },
    { "type": "valence", "points": 1 },
    { "type": "isomer", "different": true, "points": 2 },
    { "type": "bond", "order": 2, "a": "C", "b": "O", "count": 1, "points": 1 }
  ]
}
  • elements: the palette, symbols separated by spaces. Without it: H C N O.
  • solution: the correct molecule as SMILES (the authoring mode writes the canonical one). Without it: water.
  • checks: at most 8, each worth points (default 1); only used with data-scoring="pci".

| check | passes when | rubric line | | ----------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------ | | molecule | the canonical SMILES is the correct molecule's | "builds water" | | formula | the atoms are those of formula (C2H6O, CH3CH2OH, H₂O), or else of the correct molecule | "the right atoms" | | valence | every atom has exactly its number of bonds | "every atom has the right bonds" | | connected | everything is one molecule | "one molecule" | | isomer | the formula of formula (or the correct molecule), valences right, one molecule; with different, not the correct molecule itself | "an isomer of ethanol" | | bond | at least count bonds of order (1, 2, 3) between elements a and b (either may be left out) | "a double bond between C and O" |

Scoring

Two ways (authoring.json: "scoring": ["match_correct", "custom", "human"], "correctResponse": "properties").

match_correct (data-scoring="match", the default): the response is a string, formula:SMILES, which the item compares with its correct response. The registered object has getCorrectResponse(properties): the string of the author's molecule, so an authoring system can fill in the correct response and keep it in line. The authoring mode shows it too.

<qti-response-declaration identifier="RESPONSE" cardinality="single" base-type="string">
  <qti-correct-response><qti-value>H2O:O</qti-value></qti-correct-response>
</qti-response-declaration>
…
<qti-response-processing template="https://purl.imsglobal.org/spec/qti/v3p0/rptemplates/match_correct"/>

Want the formula only? Compare the part before the colon, for example with <qti-substring case-sensitive="true"> against H2O:, or use the PCI's checks.

custom (data-scoring="pci"): the PCI evaluates the author's checks and the response is a record:

| field | type | what | | -------------------- | --------- | ------------------------------------------------------------ | | score | integer | the points of the checks that pass | | maxscore | integer | the points of all checks | | correct | integer | 1 when every check passes (and there is at least one) | | check1 … check8 | integer | 1 or 0 per check, in the order of the checks | | formula | string | the Hill formula (C2H6O) | | smiles | string | the canonical SMILES (COC) | | molecule | string | the atoms (with their grid places) and bonds as JSON, for a rater |

<qti-response-declaration identifier="RESPONSE" cardinality="record"/>
<qti-outcome-declaration identifier="SCORE" cardinality="single" base-type="float">
  <qti-default-value><qti-value>0</qti-value></qti-default-value>
</qti-outcome-declaration>
…
<qti-response-processing>
  <qti-response-condition>
    <qti-response-if>
      <qti-not><qti-is-null>
        <qti-field-value field-identifier="score"><qti-variable identifier="RESPONSE"/></qti-field-value>
      </qti-is-null></qti-not>
      <qti-set-outcome-value identifier="SCORE">
        <qti-field-value field-identifier="score"><qti-variable identifier="RESPONSE"/></qti-field-value>
      </qti-set-outcome-value>
    </qti-response-if>
  </qti-response-condition>
</qti-response-processing>

Test single fields (check3 equal to 1) for your own rules, or compare smiles with qti-match. human: use the PCI without scoring, for a human rater (molecule has the whole drawing). Until the candidate adds an atom, getResponse() reports nothing.

State and response. getState() holds the molecule (and the log). setResponse and boundTo (without a state) read formula:SMILES, a SMILES, a molecule as JSON or a record (its molecule field, else smiles) and lay out a structural formula when there are no places. In status: "solution" the declared correct response is shown (a string, or a record value with the field molecule or smiles); without one, the author's molecule.

Known limits. No charges, isotopes, stereochemistry or aromatic SMILES (c1ccccc1; write benzene as C1=CC=CC=C1). Rings get a structural formula that is a chain with a long closing bond: move the atoms. Atoms with five or six bonds (PCl₅, SF₆) are only kept apart, not given exact angles. The tie-breaking search is capped, which only matters for large, very symmetric molecules.

Using it

npm install @citolab/pci-molecule-builder

| file | what | | ---------------------------------------------- | ------------------------------------------------------------------------- | | dist/index.js | the PCI (AMD module, everything bundled: the package has no dependencies) | | dist/authoring.json | settings, response, scoring and the authoring mode, for authoring systems | | dist/sbom.cdx.json | CycloneDX SBOM of the bundle | | dist/tao-pci-moleculeBuilder_<version>.zip | the PCI for TAO: Settings → Portable Custom Interactions → Add | | moleculeBuilder.svg, example.png | icon and screenshot |

In a QTI 3 item, with index.js at resources/pci/index.js of the package:

<qti-response-declaration identifier="RESPONSE" cardinality="single" base-type="string">
  <qti-correct-response><qti-value>C2H6O:CCO</qti-value></qti-correct-response>
</qti-response-declaration>
…
<qti-portable-custom-interaction response-identifier="RESPONSE" module="pci" custom-interaction-type-identifier="moleculeBuilder"
  data-language="nl" data-prompt="Bouw een molecuul ethanol, C₂H₅OH."
  data-molecule="{&quot;elements&quot;:&quot;H C O&quot;,&quot;solution&quot;:&quot;CCO&quot;}">
  <qti-interaction-modules>
    <qti-interaction-module id="pci" primary-path="../resources/pci/index"></qti-interaction-module>
  </qti-interaction-modules>
  <qti-interaction-markup></qti-interaction-markup>
</qti-portable-custom-interaction>

Source and the other examples: Citolab/tspci-examples.