Feat: Convert Molstar Homepage Examples to Mol-view-spec/mol-views-stories

MOLSTAR_EXAMPLES_SUMMARY.md

@@ -0,0 +1,168 @@
+# Molstar Examples - Phase 1 Complete ✅
+
+## Summary
+
+Successfully completed **Phase 1** of the Molstar Interactive Examples implementation plan. All stub files and directory structure are now in place for 11 examples from molstar.org.
+
+## What Was Accomplished
+
+### ✅ Directory Structure
+Created complete folder hierarchy:
+```
+cli/examples/molstar-examples/
+├── README.md                    # Overview and documentation
+├── examples.yaml                # Metadata for all examples
+├── create-stubs.ts              # Stub generator script
+├── MOLSTAR_EXAMPLES_PLAN.md     # Implementation plan (in repo root)
+├── 1rb8-assembly/
+│   ├── story.yaml
+│   └── README.md
+├── alpha-orbitals/
+├── btub/
+├── cytochromes/
+├── gain-md/
+├── lighting/
+├── motor-hook/
+├── npc/
+├── sars-cov-2-virion/
+├── villin-md/
+└── zika-em/
+```
+
+### ✅ Metadata System
+Created `examples.yaml` with complete metadata for all 11 examples:
+- Title, description, type classification
+- Source URLs (molstar.org viewer links)
+- GitHub URLs for molx files and custom demos
+- DOI references and PDB IDs
+- Implementation tier classification
+- Status tracking
+
+### ✅ Stub Files
+Generated story.yaml and README.md for each example:
+- **story.yaml**: Minimal working story with placeholder scene
+- **README.md**: Investigation template with checklists
+
+### ✅ Documentation
+Created comprehensive README.md covering:
+- Overview of all examples
+- molx file format explanation
+- Implementation workflow
+- Tier-based organization
+- Resources and attribution
+
+### ✅ Key Discovery: molx Format
+Investigated molx file structure:
+- **ZIP archive** containing state.json + assets
+- **state.json** has transformation tree mapping to builder API
+- **Example extracted:** motor-hook.molx → identified transformers
+
+## Files Created
+
+| File | Purpose |
+|------|---------|
+| `examples.yaml` | Central metadata for all examples |
+| `README.md` | Main documentation |
+| `create-stubs.ts` | Automated stub generator |
+| `*/story.yaml` | Story stub for each example (11 files) |
+| `*/README.md` | Investigation template for each example (11 files) |
+
+**Total:** 25 new files created
+
+## Key Insights
+
+### molx File Structure
+```
+molx (ZIP) contains:
+  - state.json: Molstar plugin state with transformers
+  - assets/: Binary structure/volume data
+  - assets.json: Asset metadata
+```
+
+### Transformer Mapping
+| Molstar State | Builder API |
+|---------------|-------------|
+| `ms-plugin.download` | `builder.download()` |
+| `ms-plugin.parse-cif` | `.parse()` |
+| `ms-plugin.structure-component` | `.component()` |
+| `ms-plugin.structure-representation-3d` | `.representation()` |
+
+## Examples by Tier
+
+### Tier 1 (Simple) - 3 examples
+- motor-hook (7CGO) - Cryo-EM
+- 1rb8-assembly (1RB8) - Assembly  
+- zika-em - Structure + EM
+
+### Tier 2 (Medium) - 3 examples
+- cytochromes - Superposition
+- npc - Integrative structure
+- btub - Membrane system
+
+### Tier 3 (Complex) - 3 examples
+- gain-md - MD trajectory
+- villin-md - MD trajectory
+- sars-cov-2-virion - Coarse-grained
+
+### Tier 4 (Custom) - 2 examples
+- alpha-orbitals - Custom visualization
+- lighting - Render demo
+
+## Next Steps (Phase 2)
+
+Ready to begin implementation:
+
+1. **Download all molx files** from GitHub
+2. **Extract and analyze state.json** for each
+3. **Start with Tier 1** (motor-hook recommended)
+4. **Parse transformers** and map to builder API
+5. **Extract camera positions** from state
+6. **Implement first example** as reference
+
+### Recommended First Example
+**motor-hook** (Tier 1):
+- Already downloaded and extracted
+- Simple single structure (7CGO)
+- Standard representations
+- Good reference for pattern establishment
+
+## Resources
+
+### GitHub
+- molx files: https://github.com/molstar/molstar.github.io/tree/master/demos/states
+- Custom demos: https://github.com/molstar/molstar.github.io/tree/master/demos
+
+### Documentation
+- Implementation plan: `/MOLSTAR_EXAMPLES_PLAN.md`
+- Examples overview: `/cli/examples/molstar-examples/README.md`
+- Metadata: `/cli/examples/molstar-examples/examples.yaml`
+
+### Tools Created
+- Stub generator: `/cli/examples/molstar-examples/create-stubs.ts`
+
+## Timeline
+
+- **Phase 1 Started:** 2026-01-18
+- **Phase 1 Completed:** 2026-01-18
+- **Duration:** ~1 hour
+- **Next Phase:** Ready to begin Phase 2 (Investigation & Implementation)
+
+## Status Summary
+
+| Category | Status |
+|----------|--------|
+| Directory Structure | ✅ Complete |
+| Metadata File | ✅ Complete |
+| Stub Files | ✅ Complete (11 examples) |
+| Documentation | ✅ Complete |
+| molx Investigation | 🔄 Started (1 example) |
+| Implementation | ⏳ Not started |
+
+---
+
+**Phase 1 Success Criteria: ALL MET ✅**
+- [x] All 11 example folders created
+- [x] examples.yaml metadata file created  
+- [x] All stub story.yaml and README.md files created
+- [x] Main README documentation complete
+- [x] molx format investigated and documented

cli/examples/molstar-examples/1rb8-assembly/README.md

@@ -0,0 +1,50 @@
+# PhiX174 DNA Binding Protein Assembly
+
+## Description
+Annotated assembly of the phiX174 DNA binding protein (PDB id 1RB8).
+
+## Source
+- **Molstar URL:** https://molstar.org/viewer/?snapshot-url=https%3A%2F%2Fmolstar.org%2Fdemos%2Fstates%2F1rb8asm.molx&snapshot-url-type=molx
+- **molx file:** https://molstar.org/demos/states/1rb8asm.molx
+- **GitHub molx:** https://github.com/molstar/molstar.github.io/blob/master/demos/states/1rb8asm.molx
+
+- **Type:** Assembly Annotation
+- **Tier:** 1
+
+## References
+- **PDB ID:** 1RB8
+
+
+
+## Implementation Status
+- [ ] molx file downloaded and extracted
+- [ ] state.json parsed and analyzed
+- [ ] Data sources identified
+- [ ] Representations documented
+- [ ] Camera positions extracted
+- [ ] Builder API implementation completed
+- [ ] Educational content enhanced
+- [ ] Testing complete
+
+## Investigation Notes
+
+### molx Contents
+_To be filled after extraction_
+
+### Transformers Found
+_To be filled during Phase 2_
+
+### Data Sources
+_To be filled during Phase 2_
+
+### Visual Elements
+_To be filled during Phase 2_
+
+### Camera & Timing
+_To be filled during Phase 2_
+
+### Builder API Mapping
+_To be filled during Phase 2_
+
+## Notes
+Single assembly with annotations