@vizhub/runtime 4.0.1 → 4.0.3

package/README.md

@@ -337,6 +337,88 @@ npm install @vizhub/runtime
 
 ### Basic Usage
 
+#### createRuntime(options)
+
+Creates a runtime environment that manages code execution in an iframe with worker-based build support.
+
+```typescript
+const runtime = createRuntime({
+  iframe: HTMLIFrameElement,
+  worker: Worker,
+  setBuildErrorMessage?: (error: string | null) => void,
+  getLatestContent?: (vizId: string) => Promise<VizContent | null>,
+  resolveSlugKey?: (slugKey: string) => Promise<string | null>,
+  writeFile?: (fileName: string, content: string) => void
+});
+```
+
+##### Options
+
+- **iframe**: `HTMLIFrameElement` - The iframe element where the viz will be rendered
+- **worker**: `Worker` - Web Worker instance that handles code building
+- **setBuildErrorMessage**: `(error: string | null) => void` - Optional callback for handling build errors
+- **getLatestContent**: `(vizId: string) => Promise<VizContent | null>` - Optional function to fetch viz content for cross-viz imports
+- **resolveSlugKey**: `(slugKey: string) => Promise<string | null>` - Optional function to resolve viz slugs to IDs
+- **writeFile**: `(fileName: string, content: string) => void` - Optional callback when code running in the iframe writes files
+
+##### Returns
+
+Returns a `VizHubRuntime` object with methods:
+
+- **run**: `(options: RunOptions) => void` - Executes code in the iframe
+  - **options.files**: `FileCollection` - Map of filenames to file contents
+  - **options.enableHotReloading**: `boolean` - Enable hot reloading (v3 runtime only)
+  - **options.enableSourcemap**: `boolean` - Enable source maps for debugging
+  - **options.vizId**: `string` - ID of current viz (required for v3)
+- **cleanup**: `() => void` - Removes event listeners from worker and iframe
+- **invalidateVizCache**: `(changedVizIds: string[]) => Promise<void>` - Invalidates cache for specified viz IDs
+
+##### Example
+
+```javascript
+import { createRuntime } from "@vizhub/runtime";
+import BuildWorker from "./buildWorker?worker";
+
+// Get iframe from DOM
+const iframe = document.getElementById("viz-iframe");
+
+// Create worker
+const worker = new BuildWorker();
+
+// Initialize runtime
+const runtime = createRuntime({
+  iframe,
+  worker,
+  setBuildErrorMessage: (error) => {
+    error && console.error("Build error:", error);
+  },
+  getLatestContent: async (vizId) => {
+    // Fetch viz content from your backend
+    return await fetchVizContent(vizId);
+  },
+  resolveSlugKey: async (slugKey) => {
+    // Resolve slug to vizId from your backend
+    return await resolveSlug(slugKey);
+  },
+});
+
+// Run code in the iframe
+runtime.run({
+  files: {
+    "index.js":
+      'console.log("Hello from VizHub runtime!");',
+  },
+  enableHotReloading: true,
+  enableSourcemap: true,
+  vizId: "example-viz",
+});
+
+// Clean up when done
+runtime.cleanup();
+```
+
+### Building HTML Only
+
 ```javascript
 import { build } from "@vizhub/runtime";
 import { rollup } from "rollup";

package/dist/build/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/build/build.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACzD,OAAO,EAGL,SAAS,EACT,cAAc,EAEd,QAAQ,EACT,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAUtC,eAAO,MAAM,KAAK,GAAU,oFAQzB;IAGD,KAAK,CAAC,EAAE,cAAc,CAAC;IAGvB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAQ1D,eAAe,CAAC,EAAE,OAAO,CAAC;IAI1B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAGpB,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,SAAS,CAAC,EAAE,SAAS,CAAC;IAGtB,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;CACnD,KAAG,OAAO,CAAC,WAAW,CAmItB,CAAC"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/build/build.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACzD,OAAO,EAGL,SAAS,EACT,cAAc,EAEd,QAAQ,EACT,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAUtC,eAAO,MAAM,KAAK,GAAU,oFAQzB;IAGD,KAAK,CAAC,EAAE,cAAc,CAAC;IAGvB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAQ1D,eAAe,CAAC,EAAE,OAAO,CAAC;IAI1B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAGpB,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,SAAS,CAAC,EAAE,SAAS,CAAC;IAGtB,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;CACnD,KAAG,OAAO,CAAC,WAAW,CAuItB,CAAC"}

package/dist/build/types.d.ts

@@ -1,6 +1,7 @@
 export type runtimeVersion = "v1" | "v2" | "v3" | "v4";
 export type BuildResult = {
     html: string;
+    runtimeVersion: runtimeVersion;
     css?: string;
     js?: string;
 };

package/dist/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/build/types.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAGvD,MAAM,MAAM,WAAW,GAAG;IAKxB,IAAI,EAAE,MAAM,CAAC;IAIb,GAAG,CAAC,EAAE,MAAM,CAAC;IAIb,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/build/types.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAGvD,MAAM,MAAM,WAAW,GAAG;IAKxB,IAAI,EAAE,MAAM,CAAC;IAGb,cAAc,EAAE,cAAc,CAAC;IAI/B,GAAG,CAAC,EAAE,MAAM,CAAC;IAIb,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC"}