lhasa-ligand-builder 0.1.0 → 0.2.1

package/README.md

@@ -1,21 +1,111 @@
 # LhasaReact
 
-Moorhen's frontend for Lhasa - web version of Coot's ligand builder
+Frontend for Lhasa - Moorhen's ligand builder: a React + WebAssembly version of Layla (Coot's ligand builder).
 
 ## Installation / embedding
 
-NPM package is coming soon.
-Before that happens, you have to do the build yourself.
+There is an experimental [`lhasa-ligand-builder`](https://www.npmjs.com/package/lhasa-ligand-builder) package.
 
-## How to build and run
+### Quick start
+
+You can install the package with:
+
+```bash
+npm install lhasa-ligand-builder
+```
+
+Then, embed Lhasa via the `LhasaEmbedder` component:
+
+```tsx
+import { LhasaEmbedder } from 'lhasa-ligand-builder'
+import 'lhasa-ligand-builder/style.css'
+
+function App() {
+  return <LhasaEmbedder assetsBaseUrl="/lhasa-assets/" />
+}
+```
+
+### Asset setup
+
+Lhasa requires several runtime assets (`lhasa.js`, `lhasa.wasm`, `Components-inchikey.ich`, and the `icons/` directory) to be served by your web server. Use one of the bundler plugins below to handle this automatically, or copy the assets manually.
+
+#### Vite
+
+```js
+// vite.config.js
+import lhasaCopyAssets from 'lhasa-ligand-builder/lhasa-vite-plugin'
+
+export default {
+  plugins: [lhasaCopyAssets()],
+}
+```
+
+During development, the plugin serves assets via middleware. In production builds, it copies them into your output directory under `lhasa-assets/`.
+
+#### Webpack
+
+```js
+// webpack.config.js
+const LhasaCopyAssetsPlugin = require('lhasa-ligand-builder/lhasa-webpack-plugin')
+
+module.exports = {
+  plugins: [new LhasaCopyAssetsPlugin()],
+  devServer: {
+    static: [LhasaCopyAssetsPlugin.devServerStatic()],
+  },
+}
+```
+
+#### Plugin options
+
+Both plugins accept an options object:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `outputPath` | `'lhasa-assets'` | Sub-path in the build output where assets are placed. |
+| `assets` | All entries | Array of asset names to copy: `'lhasa.js'`, `'lhasa.wasm'`, `'Components-inchikey.ich'`, `'icons'`. |
+
+#### Manual copy (fallback)
+
+If you're not using Vite or Webpack, copy the assets from `node_modules/lhasa-ligand-builder/dist/assets/` to your public directory (e.g. `public/lhasa-assets/`).
+
+### Cross-origin isolation
+
+Lhasa's WASM module uses `SharedArrayBuffer`, which requires your page to be served with these HTTP headers:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+Without these headers, the WASM module will fail to load. 
+During development with Vite, the bundled `vite-plugin-cross-origin-isolation` plugin handles this automatically.
+
+### Advanced: using `LhasaComponent` directly
+
+If you need full control over WASM loading (e.g. you already have a `MainModule` instance), use `LhasaComponent` directly:
+
+```tsx
+import { LhasaComponent } from 'lhasa-ligand-builder'
+import 'lhasa-ligand-builder/style.css'
+
+// `lhasaModule` is a MainModule instance you've initialized yourself
+<LhasaComponent
+  Lhasa={lhasaModule}
+  icons_path_prefix="/path/to/icons"
+  data_path_prefix="/path/to/data/"
+/>
+```
+
+## Building from source
 
 LhasaReact can be used standalone, outside of Moorhen.
 
 Lhasa is part of [Coot](https://github.com/pemsley/coot) and you need to compile the C++ WebAssembly module first.
 
-NOTE: All build scripts are Unix scripts. On Windows, you might need to use WSL or MinGW's shell (if it works with Emscripten?)
+NOTE: All build scripts are Unix scripts. On Windows, you may need WSL.
 
-### Building WebAssembly module
+### Building the WebAssembly module
 
 #### Tools you will need
 
@@ -29,13 +119,22 @@ The build procedure is very much like [Moorhen](https://github.com/moorhen-coot/
 
 * Run `get_sources` (download C++ dependencies)
 * Run `initial_build.sh` to build all the necessary dependencies using Emscripten
-* Run `build_lhasa.sh` to build Lhasa WebAssembly module
+* Run `build_lhasa.sh` to build the Lhasa WebAssembly module
 * Copy `lhasa.js`, `lhasa.worker.js` (if it exists) and `lhasa.wasm` from `Coot/lhasa/lhbuild/` to `LhasaReact/public`
 
-### Running LhasaReact
+### Running LhasaReact locally
+
+After building and copying the WebAssembly module:
+
+```bash
+npm install
+npm run dev
+```
+
+### Building the library
 
-After you had built and copied the WebAssembly module, you can launch LhasaReact (you'll need Node.JS / npm):
+```bash
+npm run build:lib
+```
 
-* Get JS dependencies: `npm install`
-* Run `npx vite serve`
-* Done!
+This produces `dist/` with the ESM bundle, CSS, type declarations, and all WASM/icon/data assets.

package/bundler_plugins/utils.mjs

@@ -0,0 +1,15 @@
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Absolute path to the package's dist/assets/ directory. */
+export const ASSETS_DIR = resolve(__dirname, '..', 'dist', 'assets');
+
+/** Top-level entries to copy from dist/assets/. */
+export const ASSET_ENTRIES = [
+  'lhasa.js',
+  'lhasa.wasm',
+  'Components-inchikey.ich',
+  'icons',
+];

package/bundler_plugins/vite.mjs

@@ -0,0 +1,80 @@
+import { cpSync, existsSync, createReadStream, statSync, mkdirSync } from 'fs';
+import { resolve, extname } from 'path';
+import { ASSETS_DIR, ASSET_ENTRIES } from './utils.mjs';
+
+const MIME_TYPES = {
+  '.js': 'application/javascript',
+  '.wasm': 'application/wasm',
+  '.ich': 'application/octet-stream',
+  '.svg': 'image/svg+xml',
+};
+
+/**
+ * Vite plugin that copies Lhasa assets into the build output
+ * and serves them during development.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.outputPath='lhasa-assets'] Sub-path within the build output where assets are placed.
+ * @param {string[]} [options.assets] Which asset entries to include. Defaults to all.
+ * @returns {import('vite').Plugin}
+ */
+export default function lhasaCopyAssets(options = {}) {
+  const outputPath = options.outputPath ?? 'lhasa-assets';
+  const assetFilter = options.assets ?? ASSET_ENTRIES;
+  let resolvedOutDir;
+
+  return {
+    name: 'lhasa-copy-assets',
+
+    configResolved(config) {
+      resolvedOutDir = config.build.outDir;
+    },
+
+    // Dev server: serve assets directly from dist/assets/ via middleware
+    configureServer(server) {
+      const urlPrefix = '/' + outputPath;
+
+      server.middlewares.use((req, res, next) => {
+        if (!req.url || !req.url.startsWith(urlPrefix + '/')) {
+          return next();
+        }
+
+        const relativePath = req.url.slice(urlPrefix.length + 1);
+        const filePath = resolve(ASSETS_DIR, relativePath);
+
+        // Prevent path traversal outside assets dir
+        if (!filePath.startsWith(ASSETS_DIR)) {
+          return next();
+        }
+
+        if (!existsSync(filePath) || statSync(filePath).isDirectory()) {
+          return next();
+        }
+
+        const ext = extname(filePath);
+        res.setHeader('Content-Type', MIME_TYPES[ext] || 'application/octet-stream');
+        createReadStream(filePath).pipe(res);
+      });
+    },
+
+    // Production build: copy assets into the output directory
+    closeBundle() {
+      if (!resolvedOutDir) return;
+
+      const destDir = resolve(resolvedOutDir, outputPath);
+      mkdirSync(destDir, { recursive: true });
+
+      for (const entry of assetFilter) {
+        const src = resolve(ASSETS_DIR, entry);
+        const dest = resolve(destDir, entry);
+        if (!existsSync(src)) {
+          console.warn(`[lhasa-copy-assets] Asset not found: ${src}`);
+          continue;
+        }
+        cpSync(src, dest, { recursive: true });
+      }
+
+      console.log(`[lhasa-copy-assets] Copied assets to ${destDir}`);
+    },
+  };
+}

package/bundler_plugins/webpack.cjs

@@ -0,0 +1,83 @@
+const path = require('path');
+const fs = require('fs');
+
+const ASSETS_DIR = path.resolve(__dirname, '..', 'dist', 'assets');
+
+const ASSET_ENTRIES = [
+  'lhasa.js',
+  'lhasa.wasm',
+  'Components-inchikey.ich',
+  'icons',
+];
+
+/**
+ * Webpack plugin that copies Lhasa assets into the build output.
+ *
+ * @example
+ * // webpack.config.js
+ * const LhasaCopyAssetsPlugin = require('lhasa-ligand-builder/lhasa-webpack-plugin');
+ * module.exports = {
+ *   plugins: [new LhasaCopyAssetsPlugin()],
+ *   devServer: {
+ *     static: [LhasaCopyAssetsPlugin.devServerStatic()],
+ *   },
+ * };
+ */
+class LhasaCopyAssetsPlugin {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.outputPath='lhasa-assets'] Sub-path within output.path where assets are placed.
+   * @param {string[]} [options.assets] Which asset entries to include. Defaults to all.
+   */
+  constructor(options = {}) {
+    this.outputPath = options.outputPath || 'lhasa-assets';
+    this.assets = options.assets || ASSET_ENTRIES;
+  }
+
+  apply(compiler) {
+    const pluginName = 'LhasaCopyAssetsPlugin';
+
+    compiler.hooks.afterEmit.tapAsync(pluginName, (compilation, callback) => {
+      const outputDir = compilation.outputOptions.path;
+      const destDir = path.resolve(outputDir, this.outputPath);
+
+      try {
+        fs.mkdirSync(destDir, { recursive: true });
+
+        for (const entry of this.assets) {
+          const src = path.resolve(ASSETS_DIR, entry);
+          const dest = path.resolve(destDir, entry);
+          if (!fs.existsSync(src)) {
+            compilation.warnings.push(
+              new Error(`[${pluginName}] Asset not found: ${src}`)
+            );
+            continue;
+          }
+          fs.cpSync(src, dest, { recursive: true });
+        }
+
+        console.log(`[${pluginName}] Copied assets to ${destDir}`);
+      } catch (err) {
+        compilation.errors.push(err);
+      }
+
+      callback();
+    });
+  }
+
+  /**
+   * Returns a devServer.static entry for webpack-dev-server
+   * so assets are served during development.
+   *
+   * @param {string} [outputPath='lhasa-assets']
+   * @returns {{ directory: string, publicPath: string }}
+   */
+  static devServerStatic(outputPath = 'lhasa-assets') {
+    return {
+      directory: ASSETS_DIR,
+      publicPath: '/' + outputPath,
+    };
+  }
+}
+
+module.exports = LhasaCopyAssetsPlugin;

package/dist/Lhasa.d.ts

@@ -0,0 +1,19 @@
+import { MainModule } from './types';
+export interface LhasaComponentProps {
+    Lhasa: MainModule | any;
+    show_top_panel?: boolean;
+    show_footer?: boolean;
+    icons_path_prefix?: string;
+    rdkit_molecule_pickle_list?: {
+        pickle: string;
+        id: string;
+    }[];
+    name_of_host_program?: string;
+    smiles_callback?: (internal_id: number, id_from_prop: string | null, smiles: string) => void;
+    bansu_endpoint?: string | undefined;
+    data_path_prefix?: string;
+    dark_mode?: boolean;
+    max_width?: number | null;
+    max_height?: number | null;
+}
+export declare function LhasaComponent({ Lhasa, show_top_panel, show_footer, icons_path_prefix, rdkit_molecule_pickle_list, name_of_host_program, smiles_callback, bansu_endpoint, data_path_prefix, dark_mode, max_width, max_height }: LhasaComponentProps): import("react/jsx-runtime").JSX.Element;

package/dist/LhasaEmbedder.d.ts

@@ -0,0 +1,10 @@
+import { LhasaComponentProps } from './Lhasa';
+export interface LhasaEmbedderProps extends Omit<LhasaComponentProps, 'Lhasa'> {
+    /** Base URL where lhasa.js, lhasa.wasm, icons/, and Components-inchikey.ich are served from. */
+    assetsBaseUrl?: string;
+    /** Custom loading indicator. Defaults to a simple "Loading Lhasa..." div. */
+    loadingComponent?: React.ReactNode;
+    /** Custom error display. Receives the Error object. */
+    errorComponent?: (error: Error) => React.ReactNode;
+}
+export declare function LhasaEmbedder({ assetsBaseUrl, loadingComponent, errorComponent, icons_path_prefix, data_path_prefix, ...lhasaProps }: LhasaEmbedderProps): import("react/jsx-runtime").JSX.Element | null;