npm - @vizhub/runtime - Versions diffs - 0.2.0 → 0.3.0 - Mend

@vizhub/runtime 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/README.md +280 -128
package/dist/buildHTML.d.ts +14 -0
package/dist/buildHTML.js +67 -0
package/dist/common/packageJson.d.ts +1 -1
package/dist/common/virtualFileSystem.d.ts +1 -1
package/dist/determineRuntimeVersion.d.ts +2 -1
package/dist/index.d.ts +3 -14
package/dist/index.js +3 -67
package/dist/test/testInBrowser.d.ts +1 -2
package/dist/test/testStackTrace.d.ts +1 -1
package/dist/types.d.ts +0 -1
package/dist/utils/vizContentToFileCollection.d.ts +1 -2
package/dist/v2/computeBundleJSV2.d.ts +1 -1
package/dist/v2/getComputedIndexHtml.d.ts +1 -1
package/dist/v2/v2Build.d.ts +1 -1
package/dist/v3/cleanRollupErrorMessage.d.ts +4 -0
package/dist/v3/cleanRollupErrorMessage.js +9 -0
package/dist/v3/computeBundleJSV3.d.ts +1 -2
package/dist/v3/createVizContent.d.ts +1 -2
package/dist/v3/setupV3Runtime.d.ts +15 -0
package/dist/v3/setupV3Runtime.js +341 -0
package/dist/v3/v3Build.d.ts +1 -2
package/dist/v3/v3Build.js +1 -1
package/dist/v3/vizLoad.js +1 -1
package/dist/v4/index.d.ts +1 -1
package/package.json +12 -10

package/README.md CHANGED Viewed

@@ -9,6 +9,252 @@ A powerful, flexible runtime environment for executing code sandboxes in the bro
 `@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.
+## Runtime Versions
+The library automatically detects which runtime version to use based on the files provided:
+- **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
+| 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     |
+## V1 Runtime
+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.
+### How It Works
+In V1 runtime:
+- 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
+### Example Usage
+As a VizHub user, you simply need to create an `index.html` file containing your entire project:
+**index.html**
+```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>
+```
+V1 is ideal for simple demonstrations or when you want complete control over your HTML structure.
+## V2 Runtime
+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.
+### How It Works
+In V2 runtime:
+- 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
+### Example Usage
+As a VizHub user, you'll typically create:
+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
+**index.html**
+```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"));
+```
+**render.js**
+```javascript
+export function render(element) {
+  element.innerHTML = "<h1>Hello from V2 runtime!</h1>";
+}
+```
+**package.json**
+```json
+{
+  "dependencies": {
+    "d3": "7.8.5",
+    "react": "18.2.0",
+    "react-dom": "18.2.0"
+  }
+}
+```
+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).
+## V3 Runtime
+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.
+### How It Works
+In V3 runtime:
+- 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
+### State Management in V3
+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:
+- 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
+### The Problem: Re-using D3 Rendering Logic Across Frameworks
+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.
+### 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
+};
+```
+- **`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"));
+```
+**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**
@@ -42,84 +288,87 @@ npm install @vizhub/runtime
 ### Basic Usage
 ```javascript
-import { buildHTML } from '@vizhub/runtime';
-import { rollup } from 'rollup';
+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>'
-  }
+    "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!";'
+    "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
+  rollup,
 });
 // Use the generated HTML in an iframe
-const iframe = document.createElement('iframe');
+const iframe = document.createElement("iframe");
 iframe.srcdoc = html;
 document.body.appendChild(iframe);
 ```
-### Runtime Versions
-The library automatically detects which runtime version to use based on the files provided:
-- **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
 ### 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';
+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',
+      id: "viz-123",
       files: {
-        'file1': { name: 'index.js', text: 'export const value = 42;' }
-      }
-    }
+        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'
+    "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);'
+    "index.js":
+      'import { value } from "@username/my-viz"; console.log(value);',
   },
   rollup,
   vizCache,
-  vizId: 'current-viz-id',
+  vizId: "current-viz-id",
   slugCache,
-  getSvelteCompiler: async () => compile
+  getSvelteCompiler: async () => compile,
 });
 ```
@@ -157,103 +406,6 @@ Creates a cache for slug resolution.
 - **initialMappings**: `Record<string, string>` - Initial slug to vizId mappings
 - **handleCacheMiss**: `(slug: string) => Promise<string>` - Function to handle cache misses
-## Examples
-### 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>
-    `
-  }
-});
-```
-### v2: Bundled JavaScript
-```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
-});
-```
-### v4: ES Modules with Import Maps
-```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
 ### Setup

package/dist/buildHTML.d.ts ADDED Viewed

@@ -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>;

package/dist/buildHTML.js ADDED Viewed

@@ -0,0 +1,67 @@
+import { magicSandbox } from "magic-sandbox";
+import { determineRuntimeVersion } from "./determineRuntimeVersion";
+import { v2Build } from "./v2";
+import { v3Build } from "./v3";
+import { v4Build } from "./v4";
+import { createVizCache } from "./v3/vizCache";
+import { createVizContent } from "./v3/createVizContent";
+import { vizContentToFileCollection } from "./utils/vizContentToFileCollection";
+const DEBUG = false;
+export const buildHTML = async ({ files, rollup, enableSourcemap = true, vizCache, vizId, slugCache, getSvelteCompiler, }) => {
+    if (!files && !vizCache) {
+        throw new Error("Either files or vizCache is required");
+    }
+    if (!files && vizCache && !vizId) {
+        throw new Error("vizId is required when using vizCache");
+    }
+    if (!files && vizCache && vizId) {
+        files = vizContentToFileCollection(await vizCache.get(vizId));
+    }
+    if (!files) {
+        throw new Error("Upable to extract viz files");
+    }
+    const version = determineRuntimeVersion(files);
+    DEBUG && console.log("[buildHTML] version:", version);
+    if (version === "v1") {
+        return magicSandbox(files);
+    }
+    if (version === "v2") {
+        if (!rollup) {
+            throw new Error("Rollup is required for v2 runtime");
+        }
+        return magicSandbox(await v2Build({ files, rollup, enableSourcemap }));
+    }
+    if (version === "v3") {
+        if (!rollup) {
+            throw new Error("Rollup is required for v3 runtime");
+        }
+        if (!vizCache && !vizId) {
+            const vizContent = createVizContent(files);
+            vizId = vizContent.id;
+            vizCache = createVizCache({
+                initialContents: [vizContent],
+                handleCacheMiss: async () => {
+                    throw new Error("Cache miss handler not implemented");
+                },
+            });
+        }
+        if (!vizCache || !vizId) {
+            throw new Error("vizCache and vizId are required for v3 runtime");
+        }
+        return await v3Build({
+            files,
+            rollup,
+            vizCache,
+            vizId,
+            slugCache,
+            getSvelteCompiler,
+        });
+    }
+    if (version === "v4") {
+        if (!rollup) {
+            throw new Error("Rollup is required for v4 runtime");
+        }
+        return magicSandbox(await v4Build({ files, rollup, enableSourcemap }));
+    }
+    throw new Error(`Unsupported runtime version: ${version}`);
+};

package/dist/common/packageJson.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import { FileCollection } from "../types";
+import { FileCollection } from "@vizhub/viz-types";
 export type Licence = string;
 export interface PackageJson {
     dependencies?: {

package/dist/common/virtualFileSystem.d.ts CHANGED Viewed

@@ -1,3 +1,3 @@
+import { FileCollection } from "@vizhub/viz-types";
 import { Plugin } from "rollup";
-import { FileCollection } from "../types";
 export declare const virtualFileSystem: (files: FileCollection) => Plugin;

package/dist/determineRuntimeVersion.d.ts CHANGED Viewed

@@ -1,2 +1,3 @@
-import { FileCollection, runtimeVersion } from "./types";
+import { FileCollection } from "@vizhub/viz-types";
+import { runtimeVersion } from "./types";
 export declare const determineRuntimeVersion: (files: FileCollection) => runtimeVersion | null;

package/dist/index.d.ts CHANGED Viewed

@@ -1,14 +1,3 @@
-import { FileCollection } from "magic-sandbox";
-import type { RollupBuild, RollupOptions } from "rollup";
-import { VizCache } from "./v3/vizCache";
-import { SlugCache } from "./v3/slugCache";
-import { SvelteCompiler } from "./v3/transformSvelte";
-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>;
+export { buildHTML } from "./buildHTML";
+export { createVizCache, VizCache } from "./v3/vizCache";
+export { createSlugCache, SlugCache } from "./v3/slugCache";

package/dist/index.js CHANGED Viewed

@@ -1,67 +1,3 @@
-import { magicSandbox, } from "magic-sandbox";
-import { determineRuntimeVersion } from "./determineRuntimeVersion";
-import { v2Build } from "./v2";
-import { v3Build } from "./v3";
-import { v4Build } from "./v4";
-import { createVizCache } from "./v3/vizCache";
-import { createVizContent } from "./v3/createVizContent";
-import { vizContentToFileCollection } from "./utils/vizContentToFileCollection";
-const DEBUG = false;
-export const buildHTML = async ({ files, rollup, enableSourcemap = true, vizCache, vizId, slugCache, getSvelteCompiler, }) => {
-    if (!files && !vizCache) {
-        throw new Error("Either files or vizCache is required");
-    }
-    if (!files && vizCache && !vizId) {
-        throw new Error("vizId is required when using vizCache");
-    }
-    if (!files && vizCache && vizId) {
-        files = vizContentToFileCollection(await vizCache.get(vizId));
-    }
-    if (!files) {
-        throw new Error("Upable to extract viz files");
-    }
-    const version = determineRuntimeVersion(files);
-    DEBUG && console.log("[buildHTML] version:", version);
-    if (version === "v1") {
-        return magicSandbox(files);
-    }
-    if (version === "v2") {
-        if (!rollup) {
-            throw new Error("Rollup is required for v2 runtime");
-        }
-        return magicSandbox(await v2Build({ files, rollup, enableSourcemap }));
-    }
-    if (version === "v3") {
-        if (!rollup) {
-            throw new Error("Rollup is required for v3 runtime");
-        }
-        if (!vizCache && !vizId) {
-            const vizContent = createVizContent(files);
-            vizId = vizContent.id;
-            vizCache = createVizCache({
-                initialContents: [vizContent],
-                handleCacheMiss: async () => {
-                    throw new Error("Cache miss handler not implemented");
-                },
-            });
-        }
-        if (!vizCache || !vizId) {
-            throw new Error("vizCache and vizId are required for v3 runtime");
-        }
-        return await v3Build({
-            files,
-            rollup,
-            vizCache,
-            vizId,
-            slugCache,
-            getSvelteCompiler,
-        });
-    }
-    if (version === "v4") {
-        if (!rollup) {
-            throw new Error("Rollup is required for v4 runtime");
-        }
-        return magicSandbox(await v4Build({ files, rollup, enableSourcemap }));
-    }
-    throw new Error(`Unsupported runtime version: ${version}`);
-};
+export { buildHTML } from "./buildHTML";
+export { createVizCache } from "./v3/vizCache";
+export { createSlugCache } from "./v3/slugCache";

package/dist/test/testInBrowser.d.ts CHANGED Viewed

@@ -1,7 +1,6 @@
 import { Browser, Page } from "puppeteer";
-import { FileCollection } from "magic-sandbox";
 import { VizCache } from "../v3/vizCache";
-import { VizId } from "@vizhub/viz-types";
+import { FileCollection, VizId } from "@vizhub/viz-types";
 import { SlugCache } from "../v3/slugCache";
 import { SvelteCompiler } from "../v3/transformSvelte";
 export declare function testInBrowser({ browser, files, vizCache, slugCache, vizId, expectedLog, evaluateInBrowser, getSvelteCompiler, }: {

package/dist/test/testStackTrace.d.ts CHANGED Viewed

@@ -1,5 +1,5 @@
 import { Browser } from "puppeteer";
-import { FileCollection } from "magic-sandbox";
+import { FileCollection } from "@vizhub/viz-types";
 interface TestStackTraceOptions {
     browser: Browser;
     files: FileCollection;

package/dist/types.d.ts CHANGED Viewed

	@@ -1,2 +1 @@
1	- export { FileCollection } from "magic-sandbox";
2 1	export type runtimeVersion = "v1" \| "v2" \| "v3" \| "v4";

package/dist/utils/vizContentToFileCollection.d.ts CHANGED Viewed

@@ -1,5 +1,4 @@
-import type { VizContent } from "@vizhub/viz-types";
-import type { FileCollection } from "magic-sandbox";
+import type { FileCollection, VizContent } from "@vizhub/viz-types";
 /**
  * Converts VizContent format to FileCollection format
  * VizContent has files as {id: {name, text}} structure

package/dist/v2/computeBundleJSV2.d.ts CHANGED Viewed

@@ -1,5 +1,5 @@
-import { FileCollection } from "../types";
 import type { RollupBuild, RollupOptions } from "rollup";
+import { FileCollection } from "@vizhub/viz-types";
 export declare const computeBundleJSV2: ({ files, rollup, enableSourcemap, }: {
     files: FileCollection;
     rollup: (options: RollupOptions) => Promise<RollupBuild>;

package/dist/v2/getComputedIndexHtml.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
+import { FileCollection } from "@vizhub/viz-types";
 import type { JSDOM } from "jsdom";
-import { FileCollection } from "../types";
 export declare const setJSDOM: (JSDOMInstance: typeof JSDOM) => void;
 export declare const getComputedIndexHtml: (files: FileCollection) => string;

package/dist/v2/v2Build.d.ts CHANGED Viewed

@@ -1,5 +1,5 @@
-import { FileCollection } from "magic-sandbox";
 import type { RollupBuild, RollupOptions } from "rollup";
+import { FileCollection } from "@vizhub/viz-types";
 export declare const v2Build: ({ files, rollup, enableSourcemap, }: {
     files: FileCollection;
     rollup: (options: RollupOptions) => Promise<RollupBuild>;

package/dist/v3/cleanRollupErrorMessage.d.ts ADDED Viewed

@@ -0,0 +1,4 @@
+export declare const cleanRollupErrorMessage: ({ rawMessage, vizId, }: {
+    rawMessage: string;
+    vizId: string;
+}) => string;

package/dist/v3/cleanRollupErrorMessage.js ADDED Viewed

@@ -0,0 +1,9 @@
+// We want to remove the vizId from the error message
+// to make it more user-friendly.
+// Example error message before and after:
+// Before: "7f0b69fcb754479699172d1887817027/index.js (14:8): Expected ';', '}' or <eof>"
+// After: "./index.js (14:8): Expected ';', '}' or <eof>"
+export const cleanRollupErrorMessage = ({ rawMessage, vizId, }) => {
+    const regex = new RegExp(vizId, "g");
+    return rawMessage?.replace(regex, ".");
+};

package/dist/v3/computeBundleJSV3.d.ts CHANGED Viewed

@@ -1,7 +1,6 @@
-import { FileCollection } from "../types";
 import type { RollupBuild, RollupOptions } from "rollup";
 import { VizCache } from "./vizCache";
-import { VizId } from "@vizhub/viz-types";
+import { FileCollection, VizId } from "@vizhub/viz-types";
 import { SlugCache } from "./slugCache";
 import { SvelteCompiler } from "./transformSvelte";
 export declare const computeBundleJSV3: ({ files, rollup, enableSourcemap, vizCache, vizId, slugCache, getSvelteCompiler, }: {

package/dist/v3/createVizContent.d.ts CHANGED Viewed

@@ -1,5 +1,4 @@
-import { VizContent } from "@vizhub/viz-types";
-import { FileCollection } from "magic-sandbox";
+import { FileCollection, VizContent } from "@vizhub/viz-types";
 /**
  * Creates a VizContent object with the given files
  * @param files An object with file names as keys and file content as values

package/dist/v3/setupV3Runtime.d.ts ADDED Viewed

@@ -0,0 +1,15 @@
+import { VizContent, VizId } from "@vizhub/viz-types";
+export type V3Runtime = {
+    handleCodeChange: (content: VizContent) => void;
+    invalidateVizCache: (changedVizIds: Array<VizId>) => void;
+    resetSrcdoc: (changedVizIds: Array<VizId>) => void;
+};
+export declare const setupV3Runtime: ({ vizId, iframe, setSrcdocErrorMessage, getLatestContent, resolveSlugKey, writeFile, worker, }: {
+    vizId: VizId;
+    iframe: HTMLIFrameElement;
+    setSrcdocErrorMessage: (error: string | null) => void;
+    getLatestContent: (vizId: VizId) => Promise<VizContent>;
+    resolveSlugKey: (slugKey: string) => Promise<VizId>;
+    writeFile: (fileName: string, content: string) => void;
+    worker: Worker;
+}) => V3Runtime;

package/dist/v3/setupV3Runtime.js ADDED Viewed

@@ -0,0 +1,341 @@
+import { parseId } from "./parseId";
+import { cleanRollupErrorMessage } from "./cleanRollupErrorMessage";
+import { getFileText } from "@vizhub/viz-utils";
+// Flag for debugging.
+const debug = false;
+// Nothing happening.
+const IDLE = "IDLE";
+// An update has been enqueued
+// via requestAnimationFrame.
+const ENQUEUED = "ENQUEUED";
+// An update (build and run) is pending,
+// and the files have not changed.
+const PENDING_CLEAN = "PENDING_CLEAN";
+// An update (build and run) is pending,
+// and the files have changed
+// while this run is taking place.
+const PENDING_DIRTY = "PENDING_DIRTY";
+export const setupV3Runtime = ({ vizId, iframe, setSrcdocErrorMessage, getLatestContent, resolveSlugKey, writeFile, worker, }) => {
+    // Valid State Transitions:
+    //
+    //  * IDLE --> ENQUEUED
+    //    When the system is idle and files are changed.
+    //
+    //  * ENQUEUED --> PENDING_CLEAN
+    //    When the pending changes run.
+    //
+    //  * PENDING_CLEAN --> IDLE
+    //    When the pending update finishes running
+    //    and files were not changed in the mean time.
+    //
+    //  * PENDING_CLEAN --> PENDING_DIRTY
+    //    When files are changed while an update is pending.
+    //
+    //  * PENDING_DIRTY --> ENQUEUED
+    //    When the pending update finishes running
+    //    and files were changed in the mean time.
+    //
+    // When a build error happens, the state is set to IDLE.
+    // This is to prevent a build error from causing
+    // the whole system to stop working.
+    //
+    // Valid State Transitions (with build errors):
+    // TODO complete this section
+    let state = IDLE;
+    if (debug) {
+        setInterval(() => {
+            console.log("state", state);
+        }, 1000);
+    }
+    // Pending promise resolvers.
+    let pendingBuildPromise = null;
+    let pendingRunPromise = null;
+    // Logic around profiling build times.
+    const profileBuildTimes = debug;
+    let buildTimes = [];
+    const avg = (arr) => arr.reduce((a, b) => a + b, 0) / arr.length;
+    const n = 100;
+    // This runs when the build worker sends a message.
+    worker.addEventListener("message", async ({ data }) => {
+        const message = data;
+        // Handle 'buildResponse' messages.
+        // These are sent by the build worker in response
+        // to a 'buildRequest' message.
+        if (message.type === "buildResponse") {
+            const buildResult = message.buildResult;
+            const error = message.error;
+            if (profileBuildTimes && buildResult) {
+                buildTimes.push(buildResult.time);
+                // Every n times, log the rolling average.
+                if (buildTimes.length % n === 0) {
+                    console.log("Average build time: " +
+                        avg(buildTimes) +
+                        " ms");
+                    buildTimes = [];
+                }
+            }
+            // Regardless of whether the build succeeded or failed,
+            // resolve the pending build promise,
+            // so that the system remains responsive.
+            if (pendingBuildPromise) {
+                pendingBuildPromise(buildResult);
+                pendingBuildPromise = null;
+            }
+            if (error) {
+                setSrcdocErrorMessage(cleanRollupErrorMessage({
+                    rawMessage: error.message,
+                    vizId,
+                }));
+            }
+        }
+        // Handle 'contentRequest' messages.
+        // These are sent by the worker when it needs
+        // to get the content of a file, in order to
+        // populate its VizCache.
+        if (message.type === "contentRequest") {
+            const { vizId } = message;
+            const content = await getLatestContent(vizId);
+            const contentResponseMessage = {
+                type: "contentResponse",
+                vizId: message.vizId,
+                content,
+            };
+            if (debug) {
+                console.log("[v3 runtime] received contentRequest, sending contentResponse", contentResponseMessage);
+            }
+            // Send the content back to the worker.
+            worker.postMessage(contentResponseMessage);
+        }
+        // Handle 'resolveSlugRequest' messages.
+        // These are sent by the worker when it needs
+        // to resolve a slug import to a viz ID.
+        if (message.type === "resolveSlugRequest") {
+            const { slugKey } = message;
+            const resolveSlugResponseMessage = {
+                type: "resolveSlugResponse",
+                slugKey,
+                requestId: message.requestId,
+                vizId: await resolveSlugKey(slugKey),
+            };
+            if (debug) {
+                console.log("[v3 runtime] received resolveSlugRequest, sending resolveSlugResponse", resolveSlugResponseMessage);
+            }
+            // Send the viz ID back to the worker.
+            worker.postMessage(resolveSlugResponseMessage);
+        }
+        // Handle 'invalidateVizCacheResponse' messages.
+        // These are sent by the worker in response to
+        // an 'invalidateVizCacheRequest' message.
+        if (message.type === "invalidateVizCacheResponse") {
+            if (debug) {
+                console.log("[v3 runtime] received invalidateVizCacheResponse", message);
+            }
+            // Leverage existing infra for executing the hot reloading.
+            handleCodeChange();
+        }
+        if (message.type === "resetSrcdocResponse") {
+            const srcdoc = message.srcdoc;
+            const error = message.error;
+            if (error) {
+                setSrcdocErrorMessage(cleanRollupErrorMessage({
+                    rawMessage: error.message,
+                    vizId,
+                }));
+            }
+            else {
+                setSrcdocErrorMessage(null);
+                // Really reset the srcdoc!
+                // console.log('Really reset the srcdoc!');
+                if (srcdoc) {
+                    iframe.srcdoc = srcdoc;
+                }
+            }
+        }
+    });
+    // This runs when the IFrame sends a message.
+    window.addEventListener("message", ({ data }) => {
+        // Handle 'runDone' and 'runError' messages.
+        // These happen in response to sending a 'runJS' message.
+        if (data.type === "runDone" ||
+            data.type === "runError") {
+            // console.log('got ' + data.type);
+            if (pendingRunPromise) {
+                // TODO pass errors out for display
+                // pendingRunPromise(data as V3WindowMessage);
+                pendingRunPromise();
+                pendingRunPromise = null;
+            }
+        }
+        if (data.type === "runError") {
+            setSrcdocErrorMessage(data.error.message);
+        }
+        if (data.type === "writeFile") {
+            if (data.fileName && data.content) {
+                writeFile(data.fileName, data.content);
+            }
+        }
+    });
+    const handleCodeChange = () => {
+        if (state === IDLE) {
+            state = ENQUEUED;
+            update();
+        }
+        else if (state === PENDING_CLEAN) {
+            state = PENDING_DIRTY;
+        }
+    };
+    // This runs when one or more imported vizzes are changed.
+    const invalidateVizCache = (changedVizIds) => {
+        // Send a message to the worker to invalidate the cache.
+        const message = {
+            type: "invalidateVizCacheRequest",
+            changedVizIds,
+        };
+        worker.postMessage(message);
+    };
+    const profileHotReloadFPS = true;
+    let updateCount = 0;
+    if (profileHotReloadFPS) {
+        setInterval(() => {
+            if (debug && updateCount > 0) {
+                console.log(updateCount +
+                    " hot reload" +
+                    (updateCount !== 1 ? "s" : "") +
+                    " in the last second");
+            }
+            updateCount = 0;
+        }, 1000);
+    }
+    const build = () => {
+        return new Promise((resolve) => {
+            pendingBuildPromise = resolve;
+            const message = {
+                type: "buildRequest",
+                vizId,
+                enableSourcemap: true,
+            };
+            worker.postMessage(message);
+        });
+    };
+    // Builds and runs the latest files.
+    const update = async () => {
+        state = PENDING_CLEAN;
+        if (debug) {
+            console.log("update: before run");
+        }
+        // Build the code. This may fail and return `undefined`.
+        const buildResult = await build();
+        // If the build was successful, run the code.
+        if (buildResult !== undefined) {
+            await run(buildResult);
+        }
+        if (debug) {
+            console.log("update: after run");
+        }
+        updateCount++;
+        // TypeScript can't comprehend that `state`
+        // may change during the await calls above.
+        // @ts-ignore
+        if (state === PENDING_DIRTY) {
+            requestAnimationFrame(update);
+            state = ENQUEUED;
+        }
+        else {
+            state = IDLE;
+        }
+    };
+    let previousCSSFiles = [];
+    const run = (buildResult) => {
+        return new Promise((resolve) => {
+            const { src, warnings, cssFiles } = buildResult;
+            // Sanity check.
+            // At this point, since there were no errors,
+            // we expect there to be a `src` property.
+            // This should never happen, but log & error just in case!
+            if (src === undefined) {
+                if (debug) {
+                    console.log("[v3 runtime] src is undefined, but no errors!");
+                }
+                throw new Error("[v3 runtime] src is undefined, but no errors!");
+            }
+            // Set pendingRunPromise because at this point,
+            // we expect an asynchronous response when the run is done.
+            // The iframe should send either a `runDone` or `runError` message.
+            pendingRunPromise = resolve;
+            // Handle build warnings
+            if (warnings.length > 0) {
+                // TODO: Distinguish between warnings and errors in UI
+                setSrcdocErrorMessage(warnings
+                    .map((warning) => warning.message)
+                    .join("\n\n"));
+            }
+            else {
+                setSrcdocErrorMessage(null); // Clear error message if no warnings
+            }
+            if (iframe.contentWindow) {
+                // For each cssFiles
+                for (const cssFile of cssFiles) {
+                    const { vizId, fileName } = parseId(cssFile);
+                    getLatestContent(vizId).then((content) => {
+                        const src = getFileText(content, fileName);
+                        if (src === null) {
+                            // The file doesn't exist.
+                            // TODO surface this error to the user
+                            // in a nicer way than this.
+                            console.warn(`Imported CSS file ${fileName} doesn't exist.`);
+                            return;
+                        }
+                        // TODO only inject CSS if it has changed.
+                        const runCSSMessage = {
+                            type: "runCSS",
+                            id: cssFile,
+                            src,
+                        };
+                        if (debug) {
+                            console.log("runCSSMessage", runCSSMessage);
+                        }
+                        iframe.contentWindow?.postMessage(runCSSMessage, window.location.origin);
+                    });
+                }
+                // Detect which CSS files have been removed
+                // and remove them from the iframe.
+                const removedCSSFiles = previousCSSFiles.filter((id) => !cssFiles.includes(id));
+                previousCSSFiles = cssFiles;
+                if (debug) {
+                    console.log("removedCSSFiles", removedCSSFiles);
+                }
+                for (const id of removedCSSFiles) {
+                    const removeCSSMessage = {
+                        type: "runCSS",
+                        id,
+                        src: "",
+                    };
+                    iframe.contentWindow?.postMessage(removeCSSMessage, window.location.origin);
+                }
+                // Clear the console before each run.
+                console.clear();
+                const runJSMessage = {
+                    type: "runJS",
+                    src,
+                };
+                iframe.contentWindow.postMessage(runJSMessage, window.location.origin);
+            }
+        });
+    };
+    const resetSrcdoc = (changedVizIds) => {
+        state = IDLE;
+        pendingBuildPromise = null;
+        pendingRunPromise = null;
+        const message = {
+            type: "resetSrcdocRequest",
+            vizId,
+            changedVizIds,
+        };
+        worker.postMessage(message);
+    };
+    return {
+        handleCodeChange,
+        invalidateVizCache,
+        resetSrcdoc,
+    };
+};

package/dist/v3/v3Build.d.ts CHANGED Viewed

@@ -1,7 +1,6 @@
 import { RollupBuild, RollupOptions } from "rollup";
-import { FileCollection } from "../types";
 import { VizCache } from "./vizCache";
-import { VizId } from "@vizhub/viz-types";
+import { FileCollection, VizId } from "@vizhub/viz-types";
 import { SlugCache } from "./slugCache";
 import { SvelteCompiler } from "./transformSvelte";
 export declare const v3Build: ({ files, rollup, enableSourcemap, vizCache, vizId, slugCache, getSvelteCompiler, }: {

package/dist/v3/v3Build.js CHANGED Viewed

@@ -1,7 +1,7 @@
 import { computeBundleJSV3 } from "./computeBundleJSV3";
 import { htmlTemplate } from "./htmlTemplate";
 import { parseId } from "./parseId";
-import { getFileText } from "../utils/getFileText";
+import { getFileText } from "@vizhub/viz-utils";
 export const v3Build = async ({ files, rollup, enableSourcemap = true, vizCache, vizId, slugCache, getSvelteCompiler, }) => {
     const { src, cssFiles } = await computeBundleJSV3({
         files,

package/dist/v3/vizLoad.js CHANGED Viewed

@@ -1,5 +1,5 @@
 import { parseId } from "./parseId";
-import { getFileText } from "../utils/getFileText";
+import { getFileText } from "@vizhub/viz-utils";
 const debug = false;
 // Responsible for loading all imports and
 // tracking which CSS files are imported.

package/dist/v4/index.d.ts CHANGED Viewed

@@ -1,5 +1,5 @@
-import { FileCollection } from "magic-sandbox";
 import type { RollupBuild, RollupOptions } from "rollup";
+import { FileCollection } from "@vizhub/viz-types";
 /**
  * Build for v4 runtime
  */

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@vizhub/runtime",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Flexible runtime environment for data visualization sandboxes",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,28 +20,30 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "prettier": "prettier {*.*,**/*.*} --write"
+    "prettier": "prettier {*.*,**/*.*} --write",
+    "upgrade": "ncu -x svelte -u"
   },
   "keywords": [],
   "author": "",
   "license": "MIT",
   "devDependencies": {
     "@types/jsdom": "^21.1.7",
-    "@types/node": "^22.13.13",
+    "@types/node": "^22.14.0",
     "@types/uuid": "^10.0.0",
     "jsdom": "^26.0.0",
+    "npm-check-updates": "^17.1.16",
     "prettier": "^3.5.3",
-    "puppeteer": "^24.4.0",
-    "rollup": "^4.37.0",
+    "puppeteer": "^24.6.0",
+    "rollup": "^4.39.0",
     "sucrase": "^3.35.0",
     "svelte": "4.2.9",
-    "typescript": "^5.8.2",
-    "vitest": "^3.0.9"
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.1"
   },
   "dependencies": {
-    "@vizhub/viz-types": "^0.0.2",
-    "@vizhub/viz-utils": "^0.0.1",
-    "magic-sandbox": "^2.1.0",
+    "@vizhub/viz-types": "^0.1.0",
+    "@vizhub/viz-utils": "^0.1.0",
+    "magic-sandbox": "^2.2.0",
     "uuid": "^11.1.0"
   }
 }