stspeck unexpected behaviour with widget click

.gitignore

@@ -26,3 +26,6 @@ node_modules
 
 # Users Environment Variables
 .lock-wscript
+
+#Jupyter Checkpoints
+.ipynb_checkpoints

LICENSE

@@ -1,25 +1,29 @@
-This is free and unencumbered software released into the public domain.
+BSD 3-Clause License
 
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
+Copyright (c) 2025-2026, Daniel Mejia (Denphi)
+All rights reserved.
 
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
 
-For more information, please refer to <http://unlicense.org>
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
 
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

LICENSE-SPECK

@@ -0,0 +1,32 @@
+This license covers the original Speck renderer by wwwtyro
+(https://github.com/wwwtyro/speck), on which ipyspeck and stspeck are based.
+Speck is released into the public domain; the changes and additions in this
+repository are licensed under the BSD 3-Clause License (see LICENSE).
+
+------------------------------------------------------------------------------
+
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org>
+

README.md

@@ -1,58 +1,166 @@
-# Speck
+# ipyspeck & stspeck
 
-Speck is a molecule renderer with the goal of producing figures that are as attractive as they are practical. Express your molecule clearly _and_ with style.
+Publication-quality molecular graphics for **Jupyter** and **Streamlit**: ambient occlusion,
+protein and nucleic-acid cartoons, molecular surfaces (optionally glass-like), glossy and
+metallic materials, shadows, fog, macro depth of field and high-resolution export.
+Built on [Speck](https://github.com/wwwtyro/speck) by wwwtyro.
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/wwwtyro/speck/gh-pages/static/screenshots/demo-2.png">
-</p>
+![ipyspeck 0.8](https://raw.githubusercontent.com/denphi/speck/master/media/banner.jpg)
+
+[![ipyspeck on PyPI](https://img.shields.io/pypi/v/ipyspeck?label=ipyspeck)](https://pypi.org/project/ipyspeck/)
+[![stspeck on PyPI](https://img.shields.io/pypi/v/stspeck?label=stspeck)](https://pypi.org/project/stspeck/)
+[![Python](https://img.shields.io/pypi/pyversions/ipyspeck)](https://pypi.org/project/ipyspeck/)
+[![Live demo](https://img.shields.io/badge/demo-denphi.github.io%2Fspeck-2f6fe0)](https://denphi.github.io/speck/)
 
 ## Try it live
 
-Try speck out live in your browser here: http://wwwtyro.github.io/speck/
+**[denphi.github.io/speck](https://denphi.github.io/speck/)** runs the same viewer in your browser. Load
+any PDB ID, biological assembly (`1STM-assembly1`) or AlphaFold model, adjust every setting from the
+sidebar (including the background), export a PNG, copy the settings as Python, or click a gallery image to
+open that scene.
+Links can open a structure or a scene directly:
+[`?q=4HHB`](https://denphi.github.io/speck/?q=4HHB),
+[`?q=Q8W3K0`](https://denphi.github.io/speck/?q=Q8W3K0) (AlphaFold),
+[`?example=gold_macro`](https://denphi.github.io/speck/?example=gold_macro).
 
-## Features
+## Quick start
+
+**Jupyter** (Notebook 6, JupyterLab 3 and 4; ipywidgets 7 and 8)
 
-#### Ambient Occlusion
+```bash
+pip install ipyspeck
+```
 
-Ambient occlusion provides much more information about molecule structure than simple direct lighting. It's incredibly useful for large and small molecule viewing alike. Easily Speck's most important feature.
+```python
+from ipyspeck import Speck
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/wwwtyro/speck/gh-pages/static/screenshots/demo-9.png">
-</p>
+w = Speck.from_pdb_id("4HHB", cartoonColor="chain", surface=True, surfaceOpacity=0.3,
+                      highlight={"resName": "HEM"})
+w.apply_preset("cover")              # default, matte, glossy, toon, cover, metal, glass
+w.save_image("hemoglobin.png", width=3000)
+```
 
-#### Pixel-perfect atoms and bonds
+**Streamlit**
 
-Speck renders atoms and bonds not with polygons, but with imposters. This means you can zoom in as close as you like and surfaces remain smooth, not faceted.
+```bash
+pip install stspeck
+```
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/wwwtyro/speck/gh-pages/static/screenshots/demo-0.png">
-</p>
+```python
+import stspeck
 
-#### Depth-aware outlines
+stspeck.speck(**stspeck.fetch_alphafold("Q8W3K0"), preset="cover", height=500)
+```
 
-Speck can render atom outlines that are depth-aware. Instead of making your molecule appear to be a collection of flat circles, depth-aware outlines provide cues to the viewer that convey information about the molecular structure.
+Structures load from PDB, mmCIF, SDF / MOL or XYZ files, RCSB (as mmCIF, so even ribosomes load, or as whole biological assemblies), AlphaFold DB, MD trajectories (MDTraj, MDAnalysis), ASE, RDKit or pymatgen. See the package
+READMEs for every setting: [ipyspeck](jupyter/README.md) · [stspeck](streamlit/README.md).
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/wwwtyro/speck/gh-pages/static/screenshots/demo-5.png">
-</p>
+## Videos
 
-#### Depth of field
+<a href="media/videos/kinase_tour.mp4"><img src="media/videos/kinase_tour.gif" width="480" alt="A guided tour of ABL kinase with imatinib"/></a>
 
-Render a more attractive figure while simultaneously drawing your viewer's eye to a region you want to highlight.
+A one-minute guided tour of ABL kinase with the leukemia drug imatinib (PDB 1IEP): the two lobes, the
+hinge, the gatekeeper Thr315, the DFG motif and the P-loop, each highlighted and captioned, then the drug
+([full video](media/videos/kinase_tour.mp4)). It is written as a list of stops, so the same
+[notebook](jupyter/example/videos/07_guided_tour.ipynb) tours any protein:
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/wwwtyro/speck/gh-pages/static/screenshots/demo-1.png">
-</p>
+```python
+stops = [("The hinge", {"chain": "A", "resSeq": [316, 317, 318]}, "Met318 hydrogen-bonds the drug"),
+         ("The gatekeeper, Thr315", {"chain": "A", "resSeq": 315}, "T315I causes drug resistance")]
+film = [shots.visit(site, 6, title=name, subtitle=why, color="#ff9f1c") for name, site, why in stops]
+w.save_video("tour.mp4", film)
+```
 
-#### Mix and match rendering options
+Simpler videos are one line (`w.save_video("movie.mp4", "tour")`) or the clapperboard button in the
+viewer; see the [video notebooks](jupyter/example/videos).
 
-Speck goes to great lengths to decouple rendering options, so that you have the flexibility to present your data in the most clear and attractive way.
+## Gallery
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/wwwtyro/speck/gh-pages/static/screenshots/demo-3.png">
-  <img src="https://raw.githubusercontent.com/wwwtyro/speck/gh-pages/static/screenshots/demo-6.png">
-  <img src="https://raw.githubusercontent.com/wwwtyro/speck/gh-pages/static/screenshots/demo-4.png">
-  <img src="https://raw.githubusercontent.com/wwwtyro/speck/gh-pages/static/screenshots/demo-7.png">
-  <img src="https://raw.githubusercontent.com/wwwtyro/speck/gh-pages/static/screenshots/demo-8.png">
-</p>
+<table>
+<tr>
+<td width="33%"><a href="https://denphi.github.io/speck/?example=gold_macro"><img src="https://raw.githubusercontent.com/denphi/speck/master/media/gallery/gold_macro.jpg" width="100%"/></a></td>
+<td width="33%"><a href="https://denphi.github.io/speck/?example=hemoglobin_glass"><img src="https://raw.githubusercontent.com/denphi/speck/master/media/gallery/hemoglobin_glass.jpg" width="100%"/></a></td>
+<td width="33%"><a href="https://denphi.github.io/speck/?example=alphafold"><img src="https://raw.githubusercontent.com/denphi/speck/master/media/gallery/alphafold.jpg" width="100%"/></a></td>
+</tr>
+<tr>
+<td width="33%"><a href="https://denphi.github.io/speck/?example=heme_macro"><img src="https://raw.githubusercontent.com/denphi/speck/master/media/gallery/heme_macro.jpg" width="100%"/></a></td>
+<td width="33%"><a href="https://denphi.github.io/speck/?example=crispr_cas9"><img src="https://raw.githubusercontent.com/denphi/speck/master/media/gallery/crispr_cas9.jpg" width="100%"/></a></td>
+<td width="33%"><a href="https://denphi.github.io/speck/?example=perovskite"><img src="https://raw.githubusercontent.com/denphi/speck/master/media/gallery/perovskite.jpg" width="100%"/></a></td>
+</tr>
+</table>
+
+All 41 images: [ipyspeck gallery](jupyter/README.md#gallery). Each one has a notebook that reproduces
+it exactly, with the same settings and camera: [jupyter/example/gallery](jupyter/example/gallery/). Click an
+image above to open that scene in the live demo.
+
+## Features
 
+- **Representations**: atoms and bonds (ball and stick, space filling, licorice), cartoons with
+  secondary structure from the file or computed from backbone H-bonds, solvent-excluded surfaces,
+  unit cells, trajectories
+- **Lighting**: ambient occlusion, shadows from a key light, depth fog, rim light, outlines,
+  highlight roll-off
+- **Materials**: specular, gloss and metallic (optionally only on metal atoms)
+- **Depth of field**: a macro-lens model (blur grows with depth and zoom); `dofFocus` keeps a selection sharp
+- **Coloring**: element, secondary structure, chain, rainbow, AlphaFold pLDDT, or any color; highlight
+  and ghost any atom selection
+- **Output**: supersampled PNGs up to 4096 px, turntable and trajectory animations (GIF, MP4)
+- **Videos**: ready-made videos in one line (`w.save_video("movie.mp4", "tour")`) or from the viewer's
+  video button: spin, rock, orbit, ligand tour, focus pull, cut open, trajectories; or your own
+  storyboard of shots and keyframes. Flicker-free MP4 made in the browser, up to 4K
+  ([examples](jupyter/example/videos))
+- **Interface**: toolbar with styles, cartoon / surface / ligand toggles, views and snapshot; camera
+  synced with Python
+
+## Repository layout
+
+| Path | What it is |
+|---|---|
+| [`core/`](core/) | Shared renderer (WebGL) and `SpeckViewer`, used by everything below. No npm dependencies. |
+| [`jupyter/`](jupyter/) | **ipyspeck**: Python package and JupyterLab / Notebook extension ([README](jupyter/README.md), [changelog](jupyter/CHANGELOG.md)) |
+| [`jupyter/example/`](jupyter/example/) | Notebooks: `showcase.ipynb`, `alphafold.ipynb`, and one notebook per gallery image in `gallery/` |
+| [`streamlit/`](streamlit/) | **stspeck**: Streamlit component ([README](streamlit/README.md), [changelog](streamlit/CHANGELOG.md)) |
+| [`site/`](site/) | Source of the live demo; builds into [`docs/`](docs/), served by GitHub Pages |
+| [`media/`](media/) | Banner and gallery images used by the READMEs and the demo |
+| `src/`, `static/`, `index.html`, `react.html`, `build/`, `ipyspeck.ipynb` | The original Speck web app and early ipyspeck examples, kept for reference. The current React example is [`docs/react.html`](https://denphi.github.io/speck/react.html). |
+
+## Compatibility
+
+| | Supported and tested |
+|---|---|
+| Python | 3.8, 3.9, 3.10 (3.8+) |
+| Jupyter | Classic Notebook 6, JupyterLab 3 and 4, with ipywidgets 7 or 8 |
+| Streamlit | 1.20+ (tested 1.40, 1.50, 1.64) |
+| Browsers | WebGL 1: Chrome, Firefox, Safari, Edge |
+
+## Development
+
+Both packages build `core/` first, so a change there reaches Jupyter, Streamlit and the demo.
+
+```bash
+# ipyspeck
+cd jupyter && npm install && npm run build   # core, TypeScript, notebook and lab extensions
+npm test                                     # model unit tests
+pip install -e .
+
+# stspeck
+cd streamlit/frontend && npm install && npm run build
+cd .. && pip install -e .
+
+# demo site (writes docs/)
+cd site && npm install && npm run build
+```
+
+Releases: bump the version in `jupyter/pyproject.toml`, `jupyter/package.json`,
+`jupyter/ipyspeck/_version.py` (and the `^x.y.z` module version in `speck.py`),
+`streamlit/pyproject.toml`, `streamlit/stspeck/__init__.py`; run `npm run build:prod` in
+`jupyter/`; build with `uv build` (or `python -m build`) in each package; upload with `twine`.
+Rebuild the demo site (`cd site && npm run build`) so its title and header show the new version, which
+comes from `jupyter/package.json`.
+
+## Credits and license
+
+- ipyspeck, stspeck and the rest of this repository are by [Daniel Mejia (denphi)](https://github.com/denphi),
+  under the [BSD 3-Clause License](LICENSE).
+- They are based on [Speck](https://github.com/wwwtyro/speck) by wwwtyro, which is in the public domain
+  ([`LICENSE-SPECK`](LICENSE-SPECK)). The original demo is at http://wwwtyro.github.io/speck/.

build/index.js

@@ -3,6 +3,7 @@ const speckSystem = require('../src/system.js');
 const speckView = require('../src/view.js');
 const speckInteractions = require('../src/interactions.js');
 const speckPresetViews = require('../src/presets.js');
+const speckMain = require('../src/main.js');
 
 module.exports = {
     speckRenderer,

core/.gitignore

@@ -0,0 +1 @@
+lib/

core/README.md

@@ -0,0 +1,18 @@
+# Speck core
+
+The renderer and viewer shared by the two Python packages in this repository:
+
+- `jupyter/` — **ipyspeck**, the Jupyter widget (ipywidgets 7 and 8)
+- `streamlit/` — **stspeck**, the Streamlit component
+
+`src/*.js` is the WebGL renderer (atoms, bonds, cartoon, surface, ambient occlusion,
+shadows, materials...), and `src/viewer.ts` is `SpeckViewer`, the framework-independent
+interactive viewer (toolbar, camera, trajectories, export). Each package adapts
+`SpeckViewer` to its host through a small `ViewerHost` interface. `css/speck.css`
+styles the viewer.
+
+Both packages build this folder first (`tsc -p ../core`), which writes `lib/`; nothing
+here has npm dependencies.
+
+The renderer derives from [Speck](https://github.com/wwwtyro/speck) by wwwtyro (public domain,
+`../LICENSE-SPECK`); this repository's changes are under the BSD 3-Clause License (`../LICENSE`).

core/build-worker.js

@@ -0,0 +1,30 @@
+// Bundles src/parse-worker.js and the parsers it requires into one script and
+// writes it to lib/worker-source.js as a string, so every build (JupyterLab,
+// Notebook 6, Streamlit, the demo site) can start the worker from a Blob with
+// no bundler-specific worker support. Run after tsc: node core/build-worker.js
+const fs = require('fs');
+const path = require('path');
+
+const src = path.join(__dirname, 'src');
+const modules = {};
+function add(name) {
+  const file = name.endsWith('.js') ? name : name + '.js';
+  if (file in modules) return;
+  const code = fs.readFileSync(path.join(src, file), 'utf8');
+  modules[file] = code;
+  for (const m of code.matchAll(/require\(["']\.\/([\w-]+(?:\.js)?)["']\)/g)) add(m[1]);
+}
+add('parse-worker.js');
+
+const body = Object.entries(modules)
+  .map(([file, code]) => JSON.stringify(file) + ': function (module, exports, require) {\n' + code + '\n}')
+  .join(',\n');
+const bundle =
+  '(function () {\nvar defs = {\n' + body + '\n};\nvar cache = {};\n' +
+  'function req(name) { var f = /\\.js$/.test(name) ? name : name + ".js"; f = f.replace(/^\\.\\//, "");\n' +
+  '  if (cache[f]) return cache[f].exports; var m = cache[f] = {exports: {}}; defs[f](m, m.exports, req); return m.exports; }\n' +
+  'req("parse-worker.js");\n})();\n';
+fs.mkdirSync(path.join(__dirname, 'lib'), { recursive: true });
+fs.writeFileSync(path.join(__dirname, 'lib', 'worker-source.js'),
+  '// Generated by core/build-worker.js; do not edit.\nmodule.exports = ' + JSON.stringify(bundle) + ';\n');
+console.log('worker-source.js:', Object.keys(modules).join(', '), '(' + bundle.length + ' bytes)');