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

Following the Val Town blog pattern with routes at the top level:

MolstarViewer/
├── index.tsx                    # Main Hono app (entry point)
├── routes/                      # Route handlers (return HTML directly)
│   ├── home.tsx                # Homepage listing all apps
│   ├── viewer.tsx              # Viewer route (returns HTML string)
│   ├── viewer/                 # Viewer-specific modules (if needed)
│   ├── docking-viewer.tsx      # Docking viewer route
│   ├── docking-viewer/         # Docking-specific modules (if needed)
│   ├── mesoscale-explorer.tsx  # Mesoscale route
│   ├── mesoscale-explorer/     # Mesoscale-specific modules (if needed)
│   ├── mvs-stories.tsx         # MVS stories route
│   └── styles/                 # CSS files
│       └── molstar.css         # Compiled Molstar styles
├── shared/                      # Shared types and utilities
│   ├── types.ts
│   └── README.md
├── utils/                       # Utility functions
└── README.md                    # This file

🛠️ Technology Stack

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

📦 JSR Imports

All dependencies are imported using the JSR protocol:

Molstar from JSR

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

Available exports from jsr:@zachcp/molstar:

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

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

Main Entry Point

The top-level index.tsx is the main Hono app that imports and mounts all routes:

/** @jsxImportSource https://esm.sh/react@18.2.0 */
import { Hono } from "jsr:@hono/hono@4";
import homeRoutes from "./routes/home.tsx";
import viewerRoute from "./routes/viewer.tsx";
// ... other routes

const app = new Hono();

app.onError((err, c) => {
  throw err; // Unwrap errors for debugging
});

app.route("/", homeRoutes);
app.route("/", viewerRoute);
// ... mount other routes

export default app.fetch;

Routes

Each route is a separate Hono app that returns HTML directly using template literals:

/** @jsxImportSource https://esm.sh/react@18.2.0 */
import { Hono } from "jsr:@hono/hono@4";
import { readFile } from "https://esm.town/v/std/utils@85-main/index.ts";

const app = new Hono();

app.get("/viewer", async (c) => {
  const molstarCss = await readFile("/routes/styles/molstar.css", import.meta.url);
  
  return c.html(`
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Mol* Viewer</title>
        <script src="https://esm.town/v/std/catch"></script>
        <style>${molstarCss}</style>
      </head>
      <body>
        <div id="molstar-container">Loading Mol* Viewer...</div>
        <script type="module">
          import { Viewer } from "jsr:@zachcp/molstar@5.3.17";
          
          window.addEventListener("DOMContentLoaded", async () => {
            const container = document.getElementById("molstar-container");
            if (container) {
              const viewer = await Viewer.create(container, {
                layoutIsExpanded: true,
                layoutShowControls: true,
              });
            }
          });
        </script>
      </body>
    </html>
  `);
});

export default app;

HTML Templates

Routes return HTML directly using JavaScript template literals
No React server-side rendering needed - simpler and faster
CSS is injected inline from compiled Molstar stylesheets
Client-side Molstar initialization happens via inline module scripts
JSR imports work perfectly in client-side <script type="module"> tags

🔧 Development

Current Status

The project is currently scaffolded with:

✅ Top-level route structure (Val Town blog style)
✅ Main Hono app in index.tsx
✅ Routes return HTML directly (no React SSR)
✅ Separate route files for each app
✅ Viewer app fully functional with JSR imports
✅ Compiled Molstar CSS integration
✅ No separate frontend/ or backend/ folders
⏳ Docking viewer (scaffolded)
⏳ Mesoscale explorer (scaffolded)
⏳ MVS Stories (scaffolded)

Key Implementation Details

Simple HTML Templates: Routes return HTML strings using template literals - no React SSR
CSS Handling: Molstar CSS is read from routes/styles/molstar.css and injected inline
Client-Side Initialization: Molstar viewer is initialized in browser using inline <script type="module">
JSR Imports: Work perfectly in client-side <script type="module"> tags
Error Handling: app.onError unwraps Hono errors to show full stack traces
Error Catching: Include https://esm.town/v/std/catch to capture client-side errors

Next Steps

Implement remaining apps:
- Docking Viewer: Load and compare docking results
- Mesoscale Explorer: Load mesoscale structures
- MVS Stories: Story navigation and playback
Add interactive controls for each viewer
Add loading states and error handling in UI
Implement app-specific features:
- Viewer: Load PDB structures by ID
- Add URL parameters for structure loading
- Add preset views and controls

📚 Resources

Mol* Website
Val Town Documentation
JSR Package Registry
Hono Framework
Val Town Blog Example - Structure inspiration

📝 Notes

Important Patterns

Routes use template literals to return HTML strings directly (no React)
JSR imports use the jsr: protocol (e.g., jsr:@zachcp/molstar@5.3.17)
Routes are separate Hono apps that get mounted in main index.tsx
All route logic lives in the routes/ folder
Client-side scripts use <script type="module"> for JSR imports
Molstar CSS is loaded server-side and injected inline via template literals

Val Town Specifics

No backend/ or frontend/ folders - everything colocated in routes/
Main entry point is index.tsx at project root
Routes and components live together in routes/ folder
Use readFile utility for reading project files
JSR imports work seamlessly in Val Town's Deno runtime

🤝 Contributing

When adding new features:

Create a new route file in routes/ (e.g., my-feature.tsx)
Route should return HTML using template literals with c.html()
Include <script type="module"> for client-side initialization
Mount the route in index.tsx with app.route("/", myFeatureRoute)
Keep shared types in shared/types.ts
Use JSR imports for Molstar dependencies in client-side scripts
Follow Val Town best practices from AGENTS.md

zcpbx

MolstarViewer