Molstar Viewer Apps

A collection of Molstar molecular visualization applications built for Val Town, using JSR imports and TSX.

🚀 Quick Start

This Val serves four different Molstar visualization applications:

Viewer 🧬 - Standard Mol* viewer for visualizing molecular structures
Docking Viewer 🔬 - Specialized viewer for molecular docking results
Mesoscale Explorer 🔭 - Explore mesoscale biological structures
MVS Stories 📖 - Interactive molecular visualization stories

📁 Project Structure

MolstarViewer/
├── index.tsx                    # Main entry point (imports backend)
├── backend/                     # Server-side routing and logic
│   ├── index.tsx               # Hono app with routes
│   ├── routes/                 # Individual route handlers (future)
│   └── README.md
├── frontend/                    # Client-side TSX components
│   ├── apps/                   # Individual app components
│   │   ├── viewer.tsx
│   │   ├── docking-viewer.tsx
│   │   ├── mesoscale-explorer.tsx
│   │   └── mvs-stories.tsx
│   └── README.md
├── shared/                      # Shared types and utilities
│   ├── types.ts
│   └── README.md
├── viewer/                      # Original Molstar viewer source (reference)
├── docking-viewer/              # Original docking viewer source (reference)
├── mesoscale-explorer/          # Original mesoscale explorer source (reference)
├── mvs-stories/                 # Original MVS stories source (reference)
└── README.md                    # This file

🛠️ Technology Stack

Runtime: Val Town (Deno-based)
Framework: Hono for routing
UI: React 18.2.0 via esm.sh
Molstar: JSR package jsr:@zachcp/molstar@5.3.4
Language: TypeScript/TSX

📦 JSR Imports

All Molstar dependencies are imported using the JSR protocol:

import { Viewer } from "jsr:@zachcp/molstar@5.3.4";

Available exports from @zachcp/molstar:

. (main export)
./plugin-ui
./plugin
./plugin-state
./canvas3d
./data
./state
./task
./util

🏗️ Architecture

Backend (Hono)

The backend uses Hono for HTTP routing. Each route corresponds to a Molstar app:

app.get("/", (c) => {
  // Home page listing all apps
});

app.get("/viewer", (c) => {
  // Render Viewer app
});

app.get("/docking-viewer", (c) => {
  // Render Docking Viewer app
});

// ... etc

Frontend (TSX Components)

Each app is a self-contained TSX component that returns a complete HTML document:

Create val
/** @jsxImportSource https://esm.sh/react@18.2.0 */

export default function ViewerApp() {
  return (
    <html lang="en">
      <head>
        <meta charSet="UTF-8" />
        <title>Mol* Viewer</title>
      </head>
      <body>
        <div id="molstar-container" />
        <script type="module" dangerouslySetInnerHTML={{ __html: `
          import { Viewer } from "jsr:@zachcp/molstar@5.3.4";
          // Initialize viewer
        `}} />
      </body>
    </html>
  );
}

Shared Types

Common TypeScript interfaces and constants are defined in shared/types.ts for use across backend and frontend.

🔧 Development

Current Status

The project is currently scaffolded with:

✅ Basic routing structure
✅ Simple TSX components for each app
✅ Shared types and metadata
⏳ Molstar viewer initialization (in progress)
⏳ App-specific features (in progress)

Next Steps

Implement Molstar initialization in each app component
Add proper error handling and loading states
Style the apps with proper CSS
Add interactive controls for each viewer
Implement app-specific features:
- Viewer: Load PDB structures by ID
- Docking Viewer: Load and compare docking results
- Mesoscale Explorer: Load mesoscale structures
- MVS Stories: Story navigation and playback

📚 Resources

📝 Notes

All components use the /** @jsxImportSource https://esm.sh/react@18.2.0 */ pragma
JSR imports use the jsr: protocol (e.g., jsr:@zachcp/molstar@5.3.4)
Inline styles use React style objects with camelCase properties
Client-side scripts are injected using dangerouslySetInnerHTML
Code in shared/ must work in both server and browser environments

🤝 Contributing

When adding new features:

Keep backend routing logic in backend/
Keep TSX components in frontend/apps/
Keep shared types in shared/types.ts
Use JSR imports for Molstar dependencies
Follow Val Town best practices from AGENTS.md

zcpbx

MolstarViewer