@vizhub/runtime 0.1.4 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Datavis Tech INC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,257 +1,303 @@
-# @vizhub-core/runtime
+# @vizhub/runtime
 
-The `@vizhub-core/runtime` package is a core component of the VizHub platform, responsible for executing and rendering visualizations in an isolated environment. It supports multiple runtime versions (V2 and V3) and provides a flexible system for handling dependencies, file transformations, and hot reloading.
+[![NPM version](https://img.shields.io/npm/v/@vizhub/runtime.svg)](https://www.npmjs.com/package/@vizhub/runtime)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Features
+A powerful, flexible runtime environment for executing code sandboxes in the browser. `@vizhub/runtime` powers [VizHub](https://vizhub.com/) and can be used to build similar interactive coding platforms.
 
-- **Source code to HTML transformation**: Converts source code to HTML with embedded scripts and styles, ready for rendering in a browser.
-- **File transformations**: Transforms various file types (e.g., JavaScript, CSS, CSV, Svelte) to be used in the runtime environment.
-- **Hot reloading**: Automatically reloads visualizations when files are updated, providing a smooth development experience.
-- **Dependency management**: Handles external dependencies via CDN and supports custom package configurations.
-- **Virtual file system**: Implements a virtual file system for handling imports and file loading within the runtime.
-- **Web Worker-based build system**: Uses Web Workers to offload the build process, ensuring a responsive UI during development.
-- **Multi-version runtime support**: Supports both V2 and V3 runtime environments, allowing for backward compatibility and future-proofing.
+## Overview
 
-## Installation
+`@vizhub/runtime` intelligently detects the appropriate runtime version based on the provided files and generates executable HTML that can be used within an iframe's `srcdoc` attribute. It handles everything from simple HTML/JS/CSS combinations to complex module bundling, dependency resolution, and cross-viz imports.
+
+## Key Features
+
+- **Multi-Version Runtime Support**
+
+  - **v1**: Simple HTML execution with fetch proxying
+  - **v2**: JavaScript bundling with Rollup, JSX support, and CDN-based dependency resolution
+  - **v3**: Advanced module bundling with Svelte support and cross-viz imports
+  - **v4**: Modern ES Modules with import maps for direct browser execution
+
+- **Comprehensive Tooling**
+
+  - **Bundling**: Seamless integration with Rollup for module bundling
+  - **Transpilation**: Support for JSX (v2) and Svelte components (v3)
+  - **Dependency Management**: Automatic resolution via CDNs (jsDelivr/unpkg)
+  - **Caching**: Efficient viz content and slug resolution caching
+  - **Debugging**: Sourcemap generation for improved debugging experience
 
-Install the package using npm:
+- **Advanced Capabilities**
+  - **Cross-Viz Imports**: Import code from other viz instances using `@username/vizIdOrSlug` syntax
+  - **Fetch Interception**: Handle cross-origin requests and authentication
+  - **File Type Support**: Process JS, JSX, CSS, CSV, JSON, and more
+
+## Installation
 
 ```bash
-npm install @vizhub-core/runtime
+npm install @vizhub/runtime
 ```
 
 ## Usage
 
-The `@vizhub-core/runtime` package is designed to be used within the VizHub platform but can also be utilized in other environments where isolated execution of visualizations is required.
-
-### Example
-
-Here's an example of how to use the runtime to compute the `srcdoc` for a visualization:
+### Basic Usage
 
 ```javascript
-import { expect, test } from "vitest";
-import { rollup } from "rollup";
-import { computeSrcDoc, createVizCache, VizCache } from "@vizhub/runtime";
-
-test("computeSrcDoc", async () => {
-  const content = {
-    files: {
-      "32748932": {
-        name: "index.js",
-        text: "export const main = (container) => container.innerHTML = 'Hello, world!';",
-      },
-    },
-  };
-
-  const vizCache: VizCache = createVizCache({
-    initialContents: [content],
-    handleCacheMiss: async () => {
-      return content;
-    },
-  });
-
-  const resolveSlug = async (slug: string) => {
-    throw new Error("Not implemented");
-  };
-
-  const getSvelteCompiler = async () => {
-    throw new Error("Not implemented");
-  };
-
-  const { initialSrcdoc, initialSrcdocError } = await computeSrcDoc({
-    rollup,
-    content,
-    vizCache,
-    resolveSlug,
-    getSvelteCompiler,
-  });
-
-  const randomID = initialSrcdoc.match(/viz-container-(\d+)/)?.[1];
-
-  const srcdocWithoutMapping = initialSrcdoc.replace(
-    /\/\/# sourceMappingURL=.*$/gm,
-    ""
-  );
-
-  expect(srcdocWithoutMapping).toEqual(`<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="utf-8">
-    <style>
-      body {
-        margin: 0;
-        overflow: hidden;
-      }
-      #viz-container-${randomID} {
-        height: 100vh;
-      }
-    </style>
-  </head>
-  <body>
-    <div id="viz-container-${randomID}"></div>
-    <script id="injected-script">(function(g,f){typeof exports==='object'&&typeof module!=='undefined'?f(exports):typeof define==='function'&&define.amd?define(['exports'],f):(g=typeof globalThis!=='undefined'?globalThis:g||self,f(g.Viz={}));})(this,(function(exports){'use strict';const main = (container) => container.innerHTML = 'Hello, world!';exports.main=main;}));
-
-
-    <script>
-      (() => {
-        let cleanup;
-        const render = () => {
-          const container = document.getElementById('viz-container-${randomID}');
-          typeof cleanup === 'function' && cleanup();
-          cleanup = Viz.main(container, { state: window.state, setState, writeFile });
-        };
-        const setState = (next) => {
-          window.state = next(window.state);
-          render();
-        };
-        const writeFile = (fileName, content) => {
-          parent.postMessage({ type: 'writeFile', fileName, content }, "*");
-        };
-        const run = () => {
-          try {
-            setState((state) => state || {});
-          } catch (error) {
-            console.error(error);
-            parent.postMessage({ type: 'runError', error }, "*");
-          }
-        }
-        run();
-        const runJS = (src) => {
-          document.getElementById('injected-script')?.remove();
-          const script = document.createElement('script');
-          script.textContent = src;
-          script.id = 'injected-script';
-          document.body.appendChild(script);
-          run();
-        };
-        const runCSS = (src, id) => {
-          const styleElementId = 'injected-style' + id;
-          let style = document.getElementById(styleElementId);
-          if (!style) {
-            style = document.createElement('style');
-            style.type = 'text/css';
-            style.id = styleElementId;
-            document.head.appendChild(style);
-          }
-          style.textContent = src;
-        };
-        onmessage = (message) => {
-          switch (message.data.type) {
-            case 'runJS':
-              runJS(message.data.src);
-              parent.postMessage({ type: 'runDone' }, "*");
-              break;
-            case 'runCSS':
-              runCSS(message.data.src, message.data.id);
-              break;
-            case 'ping':
-              parent.postMessage({ type: 'pong' }, "*");
-              break;
-            default:
-              break;
-          }
-        }
-      })();
-    </script>
-  </body>
-</html>`);
+import { buildHTML } from '@vizhub/runtime';
+import { rollup } from 'rollup';
+
+// Simple v1 runtime (HTML only)
+const html = await buildHTML({
+  files: {
+    'index.html': '<html><body><h1>Hello World</h1></body></html>'
+  }
 });
+
+// v2 runtime with bundling
+const html = await buildHTML({
+  files: {
+    'index.html': '<html><body><div id="root"></div><script src="bundle.js"></script></body></html>',
+    'index.js': 'import { message } from "./message"; console.log(message);',
+    'message.js': 'export const message = "Hello, bundled world!";'
+  },
+  rollup
+});
+
+// Use the generated HTML in an iframe
+const iframe = document.createElement('iframe');
+iframe.srcdoc = html;
+document.body.appendChild(iframe);
 ```
 
-You can use the generated HTML and run it as a standalone page or within an iframe to display the visualization.
+### Runtime Versions
 
-## API Documentation
+The library automatically detects which runtime version to use based on the files provided:
 
-### `computeSrcDoc`
+- **v1**: When only `index.html` is present
+- **v2**: When both `index.html` and `index.js` (or `index.jsx`) are present
+- **v3**: When only `index.js` is present (no `index.html`)
+- **v4**: When `index.html` contains ES module scripts with import maps
 
-Computes the `srcdoc` for a visualization based on its content and dependencies.
+### Advanced Usage: v3 Runtime with Cross-Viz Imports
 
-#### Parameters
+```javascript
+import { buildHTML, createVizCache, createSlugCache } from '@vizhub/runtime';
+import { rollup } from 'rollup';
+import { compile } from 'svelte/compiler';
+
+// Create caches for viz content and slug resolution
+const vizCache = createVizCache({
+  initialContents: [
+    {
+      id: 'viz-123',
+      files: {
+        'file1': { name: 'index.js', text: 'export const value = 42;' }
+      }
+    }
+  ],
+  handleCacheMiss: async (vizId) => {
+    // Fetch viz content from your backend
+    return await fetchVizContent(vizId);
+  }
+});
 
-- **`rollup`**: The Rollup instance used for bundling.
-- **`content`**: The content of the visualization, including files like `index.js` and `index.html`.
-- **`vizCache`**: A cache of visualizations used to resolve imports from other visualizations.
-- **`resolveSlug`**: A function to resolve slug-based imports to a viz ID.
-- **`getSvelteCompiler`**: A function to get the Svelte compiler.
+const slugCache = createSlugCache({
+  initialMappings: {
+    'username/my-viz': 'viz-123'
+  },
+  handleCacheMiss: async (slug) => {
+    // Resolve slug to vizId from your backend
+    return await resolveSlug(slug);
+  }
+});
 
-#### Returns
+// Build HTML with cross-viz imports
+const html = await buildHTML({
+  files: {
+    'index.js': 'import { value } from "@username/my-viz"; console.log(value);'
+  },
+  rollup,
+  vizCache,
+  vizId: 'current-viz-id',
+  slugCache,
+  getSvelteCompiler: async () => compile
+});
+```
 
-A promise that resolves to an object containing:
+## API Reference
 
-- **`initialSrcdoc`**: The computed `srcdoc` for the visualization.
-- **`initialSrcdocError`**: Any error that occurred during the computation.
+### buildHTML(options)
 
-### `createVizCache`
+Builds HTML that can be used as the `srcdoc` of an iframe.
 
-Creates a cache for visualizations, used to resolve imports from other visualizations.
+#### Options
 
-#### Parameters
+- **files**: `FileCollection` - A map of filenames to their contents
+- **rollup**: `(options: RollupOptions) => Promise<RollupBuild>` - Rollup function (required for v2, v3, v4)
+- **enableSourcemap**: `boolean` - Whether to include sourcemaps (default: true)
+- **vizCache**: `VizCache` - Cache for viz content (required for v3 with cross-viz imports)
+- **vizId**: `string` - ID of the current viz (required for v3 with cross-viz imports)
+- **slugCache**: `SlugCache` - Cache for slug resolution (optional for v3)
+- **getSvelteCompiler**: `() => Promise<SvelteCompiler>` - Function that returns Svelte compiler (optional for v3)
 
-- **`initialContents`**: An array of initial contents to populate the cache.
-- **`handleCacheMiss`**: A function called when a visualization is not found in the cache.
+### createVizCache(options)
 
-#### Returns
+Creates a cache for viz content.
 
-A `VizCache` object with the following methods:
+#### Options
 
-- **`get(vizId)`**: Retrieves the content of a visualization by its ID.
-- **`set(content)`**: Adds or updates the content of a visualization in the cache.
-- **`invalidate(vizId)`**: Invalidates the cache for a specific visualization.
+- **initialContents**: `VizContent[]` - Initial viz contents to populate the cache
+- **handleCacheMiss**: `(vizId: string) => Promise<VizContent>` - Function to handle cache misses
 
-### `setJSDOM`
+### createSlugCache(options)
 
-Sets the DOM parser for environments where the native `DOMParser` is not available (e.g., Node.js).
+Creates a cache for slug resolution.
 
-#### Parameters
+#### Options
 
-- **`JSDOM`**: The `JSDOM` instance to use for parsing HTML.
+- **initialMappings**: `Record<string, string>` - Initial slug to vizId mappings
+- **handleCacheMiss**: `(slug: string) => Promise<string>` - Function to handle cache misses
 
-### `cleanRollupErrorMessage`
+## Examples
 
-Cleans up Rollup error messages by removing unnecessary details like the viz ID.
+### v1: Simple HTML
+
+```javascript
+const html = await buildHTML({
+  files: {
+    'index.html': `
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <style>
+            body { font-family: sans-serif; }
+          </style>
+        </head>
+        <body>
+          <h1>Hello World</h1>
+          <script>
+            console.log('Hello from v1 runtime!');
+          </script>
+        </body>
+      </html>
+    `
+  }
+});
+```
 
-#### Parameters
+### v2: Bundled JavaScript
 
-- **`rawMessage`**: The raw error message from Rollup.
-- **`vizId`**: The ID of the visualization.
+```javascript
+const html = await buildHTML({
+  files: {
+    'index.html': `
+      <!DOCTYPE html>
+      <html>
+        <body>
+          <div id="root"></div>
+          <script src="bundle.js"></script>
+        </body>
+      </html>
+    `,
+    'index.js': `
+      import { render } from './render';
+      render(document.getElementById('root'));
+    `,
+    'render.js': `
+      export function render(element) {
+        element.innerHTML = '<h1>Hello from v2 runtime!</h1>';
+      }
+    `,
+    'package.json': JSON.stringify({
+      dependencies: {
+        'd3': '7.8.5'
+      }
+    })
+  },
+  rollup
+});
+```
 
-#### Returns
+### v4: ES Modules with Import Maps
 
-- A cleaned-up error message string.
+```javascript
+const html = await buildHTML({
+  files: {
+    'index.html': `
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <script type="importmap">
+            {
+              "imports": {
+                "utils": "./utils.js"
+              }
+            }
+          </script>
+        </head>
+        <body>
+          <div id="app"></div>
+          <script type="module" src="index.js"></script>
+        </body>
+      </html>
+    `,
+    'index.js': `
+      import { createApp } from 'utils';
+      createApp(document.getElementById('app'));
+    `,
+    'utils.js': `
+      export function createApp(element) {
+        element.innerHTML = '<h1>Hello from v4 runtime!</h1>';
+      }
+    `
+  },
+  rollup
+});
+```
 
 ## Development
 
-To contribute to the development of this package, follow these steps:
-
-### Clone the Repository
+### Setup
 
 ```bash
-git clone https://github.com/vizhub-core/vizhub3.git
-cd vizhub3
+git clone https://github.com/vizhub-core/vizhub-runtime.git
+cd vizhub-runtime
+npm install
 ```
 
-### Install Dependencies
+### Build
 
 ```bash
-npm install
+npm run build
 ```
 
-### Run Tests
-
-The package uses Vitest for testing. Run the tests with:
+### Test
 
 ```bash
-npm run test
+npm test
 ```
 
-### Build the Package
+Run specific tests:
 
-To build the package, use:
+```bash
+npx vitest run -t "should handle CSS imports"
+```
+
+### Type Checking
 
 ```bash
-npm run build
+npm run typecheck
 ```
 
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
 ## License
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the LICENSE file for details.

package/dist/common/packageJson.d.ts

@@ -0,0 +1,39 @@
+import { FileCollection } from "../types";
+export type Licence = string;
+export interface PackageJson {
+    dependencies?: {
+        [key: string]: string;
+    };
+    vizhub?: {
+        libraries?: {
+            [key: string]: VizHubLibraryConfig;
+        };
+    };
+    license?: Licence | {
+        type: string;
+    };
+}
+export interface Dependency {
+    name: string;
+    version: string;
+}
+export interface VizHubLibraryConfig {
+    path?: string;
+    global?: string;
+}
+export interface VizHubLibraryConfigs {
+    [key: string]: VizHubLibraryConfig;
+}
+export declare const packageJSON: (files: FileCollection) => PackageJson;
+export declare const dependencies: (files: FileCollection) => {
+    [key: string]: string;
+};
+export declare const getConfiguredLibraries: (files: FileCollection) => {
+    [key: string]: VizHubLibraryConfig;
+};
+export declare const dependencySource: ({ name, version }: Dependency, libraries: VizHubLibraryConfigs, cdn?: string) => string;
+export declare const getLicense: (files: FileCollection) => string | {
+    type: string;
+} | undefined;
+export declare const getConfiguredGlobals: (pkg: PackageJson) => Record<string, string>;
+export declare const getGlobals: (pkg: PackageJson) => Record<string, string>;

package/dist/common/packageJson.js

@@ -0,0 +1,71 @@
+const EMPTY_PKG_JSON = {
+    dependencies: {},
+    vizhub: {},
+    license: "MIT",
+};
+const DEBUG = false;
+export const packageJSON = (files) => {
+    const packageJsonText = files["package.json"];
+    DEBUG &&
+        console.log("[packageJSON] packageJsonText:", packageJsonText);
+    try {
+        const pkg = packageJsonText
+            ? JSON.parse(packageJsonText)
+            : EMPTY_PKG_JSON;
+        DEBUG &&
+            console.log("[packageJSON] pkg:", JSON.stringify(pkg, null, 2));
+        return pkg;
+    }
+    catch {
+        DEBUG &&
+            console.log("[packageJSON] Error parsing package.json");
+        return EMPTY_PKG_JSON;
+    }
+};
+export const dependencies = (files) => packageJSON(files).dependencies || {};
+export const getConfiguredLibraries = (files) => {
+    const vizhubConfig = packageJSON(files).vizhub || {};
+    return vizhubConfig.libraries || {};
+};
+export const dependencySource = ({ name, version }, libraries, cdn = "jsdelivr") => {
+    const path = libraries[name]
+        ? libraries[name].path || ""
+        : "";
+    const src = cdn === "jsdelivr"
+        ? `https://cdn.jsdelivr.net/npm/${name}@${version}${path}`
+        : `https://unpkg.com/${name}@${version}${path}`;
+    return src;
+};
+export const getLicense = (files) => {
+    const license = packageJSON(files).license;
+    if (typeof license === "object" &&
+        license !== null &&
+        "type" in license) {
+        return license.type;
+    }
+    return license || EMPTY_PKG_JSON.license;
+};
+export const getConfiguredGlobals = (pkg) => {
+    const libraries = pkg?.vizhub?.libraries;
+    if (libraries) {
+        return Object.entries(libraries).reduce((accumulator, [packageName, config]) => {
+            if (config.global) {
+                accumulator[packageName] = config.global;
+            }
+            return accumulator;
+        }, {});
+    }
+    return {};
+};
+const defaultGlobals = {
+    d3: "d3",
+    react: "React",
+    "react-dom": "ReactDOM",
+};
+export const getGlobals = (pkg) => {
+    const configuredGlobals = getConfiguredGlobals(pkg);
+    return {
+        ...defaultGlobals,
+        ...configuredGlobals,
+    };
+};

package/dist/common/packageJson.test.d.ts

@@ -0,0 +1 @@
+export {};