Epic: gaps blocking the Atomify migration to lammps.js

[andeplane]

Atomify is migrating from its bundled custom LAMMPS wasm build to this package (branch lammps.js in the Atomify repo). The basics already work through an adapter (src/wasm/lammpsAdapter.ts): module load, runFile with an injected fix js/async, particle/box rendering from snapshots, pause via unresolved callback promise, cancel via promise rejection, speed via setAsyncStepFrequency, and FS-based file management. Verified in-browser: the Diffusion example renders 6750 atoms and runs; missing-package scripts fail with a readable error.

Every remaining gap is marked in the Atomify source with // TODO(lammps.js-<issue>) and tracked here:

Packaging / distribution

• Broken 1.3.1 tarball (missing dist/client.js, dist/worker.js, all .d.ts) — fixed by Guard npm publish against incomplete dist; bump version to 1.3.2 #50
• Package set: Atomify needs 13 more LAMMPS packages + 3 custom pair styles #59 Package set: 13 more LAMMPS packages + 3 custom pair styles (blocks most Atomify examples)
• Offer a separate .wasm artifact (non-SINGLE_FILE) distribution #61 Separate .wasm artifact option (SINGLE_FILE overhead)
• FS typings missing readdir and analyzePath #60 FS typings missing readdir/analyzePath

Simulation data & introspection

• Introspection API for computes, fixes and variables #51 Introspection API for computes/fixes/variables (plots — the biggest functional gap)
• Per-atom data access for computes and atom-style variables #52 Per-atom data access (per-atom coloring)
• Dynamic bonds: neighborlist-derived bonds with per-type-pair distance cutoffs #53 Dynamic bonds from neighborlist + per-type-pair distances
• syncBondsWrapped: bond endpoints are not minimum-imaged across periodic boundaries #54 syncBondsWrapped endpoints not minimum-imaged (rendering bug for periodic molecules)
• Box metadata: dimension (2D/3D) and wall fixes introspection #57 Box dimension (2D/3D) + wall fix introspection

Run control & status

• Run status and thermo metrics: progress, whichflag, spcpu, cpuremain, memory, generic getThermo #55 Run status/thermo metrics (progress, whichflag, spcpu, cpuremain, memory, generic getThermo)
• Expose LAMMPS errors: runScript/runFile fail silently #56 Structured error reporting (errors currently swallowed; also cancel-abort noise)
• Step callback for scripts whose run/minimize lives in an include file (global fix installation) #58 Step callback for include'd runs (install fix js/async globally like Atomify's old fix atomify)

Priority from Atomify's perspective: #59 (unblocks examples) → #51/#52 (plots & coloring) → #53/#54 (molecule rendering) → #56/#55 → #58 → #57 → #60/#61.

Where a fix needs a LAMMPS source patch (at least #51's FixAveTime access, possibly #53's neighborlist access and #58's pre-box fix), document each hunk in LAMMPS-patches.md (what + why) so they can be considered for upstream LAMMPS PRs later.

🤖 Generated with Claude Code

[andeplane]

Status update — every gap now has an open PR (stacked, in merge order):

PR	Fixes
#50	packaging guard + v1.3.2	✅ CI green
#63	#54 bond minimum-image	✅ CI green
#64	#56 error reporting (+ LAMMPS patch mechanism, LAMMPS-patches.md)	✅ CI green
#65	#55 run status/thermo	✅ CI green (review fix incoming: idle thermo poll must not poison the error slot)
#66	#57 box dimension + walls	✅ CI green
#67	#60 FS typings	✅ CI green
#68	#51 introspection API (+ FixAveTime patch)	✅ CI green (review fixes incoming: docs + stale-metadata on redefine)
#69	#52 per-atom data	✅ CI green (review fix incoming: shrink buffer on atom-count decrease)
#70	#53 dynamic bonds	✅ CI green
#71	#58 global js/async fix (+ modify.cpp patch)	✅ CI green (review fix incoming: wire installAsyncFix into client.runScriptAsync)
#72	#59 Atomify package set (PACKAGES=atomify)	✅ CI green

Only #61 (separate .wasm distribution) remains unimplemented — it's a packaging/distribution decision.

Atomify's lammps.js branch has been verified in-browser against the full stack (built locally with PACKAGES=atomify): Diffusion enumerates computes/variables/fixes with live scalars and plots MSD; SiC nanoparticle runs vashishta with 1338 distance-derived bonds rendered, live progress/steps-per-second/remaining-time; pause/resume/stop and script-error reporting all work.

🤖 Generated with Claude Code

[andeplane]

All gap PRs are merged (each reviewed by a subagent before merge; four review findings were fixed pre-merge: idle-thermo error-slot poisoning, per-atom buffer shrink, registry rebuild on style change + honest BufferView lifetime docs, and wiring installAsyncFix into runScriptAsync). #73 (the final PR) got a full green CI run on top of the merged stack.

Atomify's lammps.js branch was re-verified in-browser against the merged tree (built with PACKAGES=atomify): SiC nanoparticle runs vashishta with 1341 distance-derived bonds, live progress/steps-per-second/remaining-time; Diffusion enumerates computes/variables/fixes and plots MSD; full unit suites green on both repos (109 lammps.js / 430 Atomify).

Remaining:

• Release 1.4.0; run CI on pushes to master #74 — release 1.4.0 (+ ci.yml master fix). Blocked on npm trusted publishing: publishes fail with ENEEDAUTH because OIDC trusted publishing isn't configured for the package (this is also why the March 1.2.3 releases and the 1.3.2 attempt failed — the tarballs themselves were complete). Configure on npmjs.com → lammps.js → Settings → Trusted Publisher (repo lammps/lammps.js, workflow release.yml), then merge Release 1.4.0; run CI on pushes to master #74.
• Offer a separate .wasm artifact (non-SINGLE_FILE) distribution #61 separate .wasm distribution (optional)
• Decide on publishing an atomify-flavor build (PACKAGES=atomify, e.g. lammps.js-atomify)
• Follow-ups noted in review: ave/time final-average-only reads (needs the fix's internal nvalid), wall cutoff exposure (protected member)
• Atomify: repoint the file: dependency at the published version once 1.4.0 is on npm

🤖 Generated with Claude Code