@vizhub/runtime 0.1.4 → 0.3.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,455 @@
-# @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
-
-Install the package using npm:
+`@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.
 
-```bash
-npm install @vizhub-core/runtime
-```
+## Runtime Versions
 
-## Usage
+The library automatically detects which runtime version to use based on the files provided:
 
-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.
+- **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
 
-### Example
+| Feature               | **V1**            | **V2**                         | **V3**                            | **V4**                       |
+| --------------------- | ----------------- | ------------------------------ | --------------------------------- | ---------------------------- |
+| **When Used**         | Only `index.html` | `index.html` + `index.js/.jsx` | Only `index.js` (no `index.html`) | `index.html` with ES modules |
+| **`index.html`**      | User-provided     | User-provided                  | Auto-generated                    | User-provided                |
+| **ES Modules**        | ☐                 | ✅                             | ✅                                | ✅                           |
+| **UMD Libraries**     | ✅                | ✅                             | ✅                                | ☐                            |
+| **ESM Libraries**     | ☐                 | ☐                              | ☐                                 | ✅                           |
+| **JSX Support**       | ☐                 | ✅                             | ☐                                 | ✅                           |
+| **Svelte Support**    | ☐                 | ☐                              | ✅                                | ☐                            |
+| **Cross-Viz Imports** | ☐                 | ☐                              | ✅                                | ☐                            |
+| **State Management**  | ☐                 | ☐                              | ✅                                | ☐                            |
+| **Import from CSV**   | ☐                 | ☐                              | ✅                                | ☐                            |
+| **`fetch` proxy**     | ✅                | ✅                             | ☐                                 | ✅                           |
+| **Best For**          | Simple HTML demos | React with CDN deps            | Svelte / reusable D3              | Modern module-based apps     |
 
-Here's an example of how to use the runtime to compute the `srcdoc` for a visualization:
+## V1 Runtime
 
-```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!';",
-      },
-    },
-  };
+The V1 runtime is the simplest version, designed for basic HTML, CSS, and JavaScript projects. This runtime is automatically selected when your project contains only an `index.html` file.
 
-  const vizCache: VizCache = createVizCache({
-    initialContents: [content],
-    handleCacheMiss: async () => {
-      return content;
-    },
-  });
+### How It Works
 
-  const resolveSlug = async (slug: string) => {
-    throw new Error("Not implemented");
-  };
+In V1 runtime:
 
-  const getSvelteCompiler = async () => {
-    throw new Error("Not implemented");
-  };
+- Your `index.html` file is executed directly in the browser
+- You can include inline JavaScript and CSS within your HTML file
+- The runtime provides fetch request proxying to handle cross-origin requests
 
-  const { initialSrcdoc, initialSrcdocError } = await computeSrcDoc({
-    rollup,
-    content,
-    vizCache,
-    resolveSlug,
-    getSvelteCompiler,
-  });
+### Example Usage
 
-  const randomID = initialSrcdoc.match(/viz-container-(\d+)/)?.[1];
+As a VizHub user, you simply need to create an `index.html` file containing your entire project:
 
-  const srcdocWithoutMapping = initialSrcdoc.replace(
-    /\/\/# sourceMappingURL=.*$/gm,
-    ""
-  );
+**index.html**
 
-  expect(srcdocWithoutMapping).toEqual(`<!DOCTYPE html>
+```html
+<!DOCTYPE html>
 <html>
   <head>
-    <meta charset="utf-8">
     <style>
       body {
-        margin: 0;
-        overflow: hidden;
-      }
-      #viz-container-${randomID} {
-        height: 100vh;
+        font-family: sans-serif;
       }
     </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;}));
-
-
+    <h1>Hello World</h1>
     <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;
-          }
-        }
-      })();
+      console.log("Hello from V1 runtime!");
     </script>
   </body>
-</html>`);
-});
+</html>
 ```
 
-You can use the generated HTML and run it as a standalone page or within an iframe to display the visualization.
+V1 is ideal for simple demonstrations or when you want complete control over your HTML structure.
 
-## API Documentation
+## V2 Runtime
 
-### `computeSrcDoc`
+The V2 runtime introduces JavaScript bundling with Rollup, JSX support, and CDN-based dependency resolution. This runtime is automatically selected when your project contains both an `index.html` and an `index.js` (or `index.jsx`) file.
 
-Computes the `srcdoc` for a visualization based on its content and dependencies.
+### How It Works
 
-#### Parameters
+In V2 runtime:
 
-- **`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.
+- Your JavaScript files are bundled together using Rollup
+- Internally, a file named `bundle.js` is created
+- The `index.html` file references this `bundle.js` file
+- You can use ES6 modules to import/export code
+- JSX syntax is supported for React development
+- Dependencies listed in `package.json` are automatically resolved via CDNs (jsDelivr/unpkg)
+- The bundled JavaScript is referenced in your HTML file
 
-#### Returns
+### Example Usage
 
-A promise that resolves to an object containing:
+As a VizHub user, you'll typically create:
 
-- **`initialSrcdoc`**: The computed `srcdoc` for the visualization.
-- **`initialSrcdocError`**: Any error that occurred during the computation.
+1. An `index.html` file that references a `bundle.js` file
+2. An `index.js` (or `index.jsx`) file as your entry point
+3. Additional JavaScript modules as needed
+4. A `package.json` file to list dependencies
 
-### `createVizCache`
+**index.html**
 
-Creates a cache for visualizations, used to resolve imports from other visualizations.
+```html
+<!DOCTYPE html>
+<html>
+  <body>
+    <div id="root"></div>
+    <script src="bundle.js"></script>
+  </body>
+</html>
+```
+
+**index.js**
+
+```javascript
+import { render } from "./render";
+render(document.getElementById("root"));
+```
 
-#### Parameters
+**render.js**
 
-- **`initialContents`**: An array of initial contents to populate the cache.
-- **`handleCacheMiss`**: A function called when a visualization is not found in the cache.
+```javascript
+export function render(element) {
+  element.innerHTML = "<h1>Hello from V2 runtime!</h1>";
+}
+```
 
-#### Returns
+**package.json**
 
-A `VizCache` object with the following methods:
+```json
+{
+  "dependencies": {
+    "d3": "7.8.5",
+    "react": "18.2.0",
+    "react-dom": "18.2.0"
+  }
+}
+```
 
-- **`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.
+V2 is ideal for more complex projects that require modular JavaScript and external dependencies that provide UMD builds. Note that the V2 runtime does not support ESM builds for external dependencies (see V4 if you need this).
 
-### `setJSDOM`
+## V3 Runtime
 
-Sets the DOM parser for environments where the native `DOMParser` is not available (e.g., Node.js).
+The V3 runtime provides advanced module bundling with Svelte support and cross-viz imports. This runtime is automatically selected when your project contains an `index.js` file but no `index.html` file.
 
-#### Parameters
+### How It Works
 
-- **`JSDOM`**: The `JSDOM` instance to use for parsing HTML.
+In V3 runtime:
 
-### `cleanRollupErrorMessage`
+- Your JavaScript modules are bundled together using Rollup
+- A default HTML structure is automatically generated
+- Svelte components are supported
+- Cross-viz imports allow you to import code from other viz instances
+- The runtime provides a built-in state management system
 
-Cleans up Rollup error messages by removing unnecessary details like the viz ID.
+### State Management in V3
 
-#### Parameters
+V3 runtime includes a built-in state management system via the [unidirectional-data-flow](https://www.npmjs.com/package/unidirectional-data-flow) package ([GitHub](https://github.com/vizhub-core/unidirectional-data-flow)). This provides React-like state management capabilities with:
 
-- **`rawMessage`**: The raw error message from Rollup.
-- **`vizId`**: The ID of the visualization.
+- A `main` entry point
+- A minimal state management system based on `state` and `setState`
+- Similar semantics to React's `useState` hook: `const [state, setState] = useState({})`
+- Automatic re-rendering when state changes
 
-#### Returns
+### The Problem: Re-using D3 Rendering Logic Across Frameworks
 
-- A cleaned-up error message string.
+While frameworks like React, Svelte, Vue, and Angular offer state management and DOM manipulation solutions, D3 excels in data transformation and visualization, particularly with axes, transitions, and behaviors (e.g. zoom, drag, and brush). These D3 features require direct access to the DOM, making it challenging to replicate them effectively within frameworks.
 
-## Development
+### The Solution: Unidirectional Data Flow
+
+Unidirectional data flow is a pattern that can be cleanly invoked from multiple frameworks. In this paradigm, a single function is responsible for updating the DOM or rendering visuals based on a single, central state. As the state updates, the function re-renders the visualization in an idempotent manner, meaning it can run multiple times without causing side effects. Here's what the entry point function looks like for a D3-based visualization that uses unidirectional data flow:
+
+**index.js**
+
+```js
+export const main = (container, { state, setState }) => {
+  // Your reusable D3-based rendering logic goes here
+};
+```
 
-To contribute to the development of this package, follow these steps:
+- **`container`**: A DOM element where the visualization will be rendered
+- **`state`**: An object representing the current state of the application, initially empty
+- **`setState`**: A function that updates the state using immutable update patterns
+
+Whenever `setState` is invoked, `main` re-executes with the new state, ensuring that the rendering logic is both dynamic and responsive.
+
+For cross-viz imports, you can reference other vizzes directly:
+
+**example-with-import.js**
+
+```javascript
+// Import from another viz using @username/vizIdOrSlug syntax
+import { someFunction } from "@username/my-other-viz";
+```
+
+V3 is ideal for modern JavaScript applications that benefit from automatic HTML structure generation and built-in state management. Additional features of V3 include:
+
+- **Cross-Viz Imports**: Import code from other viz instances using `@username/vizIdOrSlug` syntax
+- **Import from CSV**: Import CSV files directly into your viz
+
+## V4 Runtime
+
+The V4 runtime leverages modern ES Modules with import maps for direct browser execution. This runtime is automatically selected when your project's `index.html` contains ES module scripts with import maps.
+
+### How It Works
+
+In V4 runtime:
+
+- Native browser ES modules are used without bundling
+- Import maps allow you to specify module resolution directly in the browser
+- Module paths can be aliased for cleaner imports
+- External dependencies can be loaded directly from CDNs
+
+### Example Usage
+
+As a VizHub user, you'll create an `index.html` file with import maps and ES module scripts:
+
+**index.html**
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <script type="importmap">
+      {
+        "imports": {
+          "utils": "./utils.js",
+          "d3": "https://cdn.jsdelivr.net/npm/d3@7.8.5/+esm"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="index.js"></script>
+  </body>
+</html>
+```
+
+**index.js**
+
+```javascript
+import { createApp } from "utils";
+import * as d3 from "d3";
+
+createApp(document.getElementById("app"));
+```
 
-### Clone the Repository
+**utils.js**
+
+```javascript
+export function createApp(element) {
+  element.innerHTML = "<h1>Hello from V4 runtime!</h1>";
+}
+```
+
+V4 is ideal for modern browsers with native ES module support and when you want direct control over module resolution.
+
+## 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
+
+- **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
-git clone https://github.com/vizhub-core/vizhub3.git
-cd vizhub3
+npm install @vizhub/runtime
+```
+
+## Usage
+
+### Basic Usage
+
+```javascript
+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);
+```
+
+### Advanced Usage: v3 Runtime with Cross-Viz Imports
+
+```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);
+  },
+});
+
+const slugCache = createSlugCache({
+  initialMappings: {
+    "username/my-viz": "viz-123",
+  },
+  handleCacheMiss: async (slug) => {
+    // Resolve slug to vizId from your backend
+    return await resolveSlug(slug);
+  },
+});
+
+// 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,
+});
 ```
 
-### Install Dependencies
+## API Reference
+
+### buildHTML(options)
+
+Builds HTML that can be used as the `srcdoc` of an iframe.
+
+#### Options
+
+- **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)
+
+### createVizCache(options)
+
+Creates a cache for viz content.
+
+#### Options
+
+- **initialContents**: `VizContent[]` - Initial viz contents to populate the cache
+- **handleCacheMiss**: `(vizId: string) => Promise<VizContent>` - Function to handle cache misses
+
+### createSlugCache(options)
+
+Creates a cache for slug resolution.
+
+#### Options
+
+- **initialMappings**: `Record<string, string>` - Initial slug to vizId mappings
+- **handleCacheMiss**: `(slug: string) => Promise<string>` - Function to handle cache misses
+
+## Development
+
+### Setup
 
 ```bash
+git clone https://github.com/vizhub-core/vizhub-runtime.git
+cd vizhub-runtime
 npm install
 ```
 
-### Run Tests
+### Build
+
+```bash
+npm run build
+```
 
-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/buildHTML.d.ts

@@ -0,0 +1,14 @@
+import type { RollupBuild, RollupOptions } from "rollup";
+import { VizCache } from "./v3/vizCache";
+import { SlugCache } from "./v3/slugCache";
+import { SvelteCompiler } from "./v3/transformSvelte";
+import { FileCollection } from "@vizhub/viz-types";
+export declare const buildHTML: ({ files, rollup, enableSourcemap, vizCache, vizId, slugCache, getSvelteCompiler, }: {
+    files?: FileCollection;
+    rollup?: (options: RollupOptions) => Promise<RollupBuild>;
+    enableSourcemap?: boolean;
+    vizCache?: VizCache;
+    vizId?: string;
+    slugCache?: SlugCache;
+    getSvelteCompiler?: () => Promise<SvelteCompiler>;
+}) => Promise<string>;