Changelog

All notable changes to the Molstar Viewer project will be documented in this file.

[2.0.0] - 2025-01-XX

Major Restructure - Val Town Native Architecture

Complete restructure of the project to use Val Town best practices with proper routing, TSX components, and JSR imports.

Added

New Project Structure
- backend/ - Hono-based routing and server logic
- frontend/apps/ - TSX components for each Molstar application
- shared/ - Shared TypeScript types and utilities
Four Molstar Applications
- /viewer - Standard Mol* viewer (fully ported)
- /docking-viewer - Docking viewer (scaffolded)
- /mesoscale-explorer - Mesoscale explorer (scaffolded)
- /mvs-stories - MVS Stories viewer (scaffolded)
Viewer App Features (fully ported from viewer/)
- Complete URL parameter support for configuration
- Load structures by PDB ID, EMDB ID, AlphaFold DB ID
- Load structures from custom URLs
- Snapshot loading (local and remote)
- MolViewSpec (MVS) support
- Custom rendering options (pixel scale, transparency, illumination)
- Provider selection (PDBe or RCSB)
- Debug and timing modes
- Error handling with user-friendly messages
JSR Integration
- All Molstar imports use JSR protocol: jsr:@zachcp/molstar@5.3.4
- Client-side module imports work directly in browser
Documentation
- Comprehensive README files in each directory
- URL parameter documentation for viewer app
- Architecture and development guides
- Example usage patterns

Changed

Import System
- Migrated from import * as Molstar from 'jsr:@zachcp/molstar' to proper named imports
- Changed from https://jsr.io/ URLs to jsr: protocol
- Now using: import { Viewer } from "jsr:@zachcp/molstar@5.3.4"
Application Entry Point
- index.tsx now imports and exports the Hono app from backend/index.tsx
- Centralized routing through Hono instead of individual endpoints
Component Architecture
- Each app is now a standalone TSX component returning full HTML
- Server-side rendering with renderToString
- Client-side hydration with module scripts

Technical Details

Backend (Hono)

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

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

Frontend (TSX)

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

export default function ViewerApp() {
  return (
    <html lang="en">
      <head>...</head>
      <body>
        <div id="app"></div>
        <script type="module" dangerouslySetInnerHTML={{ __html: `
          import { Viewer } from "jsr:@zachcp/molstar@5.3.4";
          // Initialize viewer
        `}} />
      </body>
    </html>
  );
}

Shared Types

Create val
export interface MolstarAppConfig {
  layoutIsExpanded?: boolean;
  layoutShowControls?: boolean;
  pdbProvider?: "pdbe" | "rcsb";
  // ... more options
}

Preserved

Original Source Code
- All original app directories preserved as reference:
  - viewer/ - Original viewer implementation
  - docking-viewer/ - Original docking viewer
  - mesoscale-explorer/ - Original mesoscale explorer
  - mvs-stories/ - Original MVS stories

Migration Status

✅ Viewer App - Fully ported with all features
- URL parameter parsing
- Multiple data loading methods
- Configuration options
- Error handling
⏳ Docking Viewer - Scaffolded (pending port)
⏳ Mesoscale Explorer - Scaffolded (pending port)
⏳ MVS Stories - Scaffolded (pending port)

Breaking Changes

URL Structure: Apps now accessed via routes (/viewer, /docking-viewer, etc.) instead of individual vals
Import Paths: JSR imports changed from https://jsr.io/ to jsr: protocol
Component Structure: Apps are now TSX components instead of standalone HTML files

Next Steps

Port docking-viewer functionality to frontend/apps/docking-viewer.tsx
Port mesoscale-explorer functionality to frontend/apps/mesoscale-explorer.tsx
Port mvs-stories functionality to frontend/apps/mvs-stories.tsx
Add CSS styling from original apps
Test all URL parameters and loading methods
Add example data and demos for each app

[1.0.0] - Previous

Original Structure

Single index.tsx with embedded HTML
Direct Molstar imports
Basic 1FAP structure viewer
React-based component structure

zcpbx

MolstarViewer