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 dependencies are imported using the JSR protocol:

Molstar from JSR

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

Available exports from jsr:@zachcp/molstar:

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

Hono from JSR

import { Hono } from "jsr:@hono/hono@4";

Why JSR?

JSR (JavaScript Registry) provides native Deno/TypeScript support and works seamlessly in Val Town's runtime environment.

🏗️ Architecture

Backend (Hono from JSR)

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

import { Hono } from "jsr:@hono/hono@4";
import { renderToString } from "https://esm.sh/react-dom@18.2.0/server";

const app = new Hono();

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

app.get("/viewer", (c) => {
  const html = renderToString(ViewerApp());
  return c.html(html);
});

// ... 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:

✅ Backend routing with Hono from JSR
✅ TSX components for each app
✅ Shared types and metadata
✅ Viewer app fully functional with JSR imports
⏳ Docking viewer (scaffolded)
⏳ Mesoscale explorer (scaffolded)
⏳ MVS Stories (scaffolded)

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