iframe + web worker

Author: jtpio

README.md

@@ -29,6 +29,115 @@ To remove the extension, execute:
 pip uninstall jupyterlite-javascript-kernel
 ```
 
+## Runtime modes
+
+The extension currently registers two JavaScript kernelspecs:
+
+- `JavaScript`:
+  Runs code in a sandboxed `iframe`. Use this when your code needs browser DOM APIs like `document`, `window`, or canvas access through the page context.
+- `JavaScript (Worker)`:
+  Runs code in a dedicated Web Worker. Use this for stronger isolation and to avoid blocking the main UI thread.
+
+Pick either kernel from the notebook kernel selector in JupyterLite.
+
+### Worker mode limitations
+
+Web Workers do not expose DOM APIs. In `JavaScript (Worker)`, APIs such as `document`, direct element access, and other main-thread-only browser APIs are unavailable.
+
+### Import side effects in iframe mode
+
+In `JavaScript` (iframe mode), user code and imports execute in the runtime iframe scope.
+
+By default, module-level side effects stay in the runtime iframe. To intentionally affect the main page (`window.parent`), access it directly.
+
+Cell declarations like `var`, `let`, `const`, `function`, and `class` remain in the runtime scope. Host-page mutations happen when your code (or imported code) explicitly reaches `window.parent`.
+
+#### Example: canvas-confetti
+
+```javascript
+import confetti from 'canvas-confetti';
+
+const canvas = window.parent.document.createElement('canvas');
+Object.assign(canvas.style, {
+  position: 'fixed',
+  inset: '0',
+  width: '100%',
+  height: '100%',
+  pointerEvents: 'none',
+  zIndex: '2147483647'
+});
+window.parent.document.body.appendChild(canvas);
+
+const fire = confetti.create(canvas, { resize: true, useWorker: true });
+
+fire({ particleCount: 20, spread: 70 });
+```
+
+#### Example: p5.js
+
+```javascript
+import p5 from 'p5';
+
+const mount = window.parent.document.createElement('div');
+Object.assign(mount.style, {
+  position: 'fixed',
+  right: '16px',
+  bottom: '16px',
+  zIndex: '1000'
+});
+window.parent.document.body.appendChild(mount);
+
+const sketch = new p5(p => {
+  p.setup = () => {
+    p.createCanvas(120, 80);
+    p.noLoop();
+  };
+}, mount);
+```
+
+#### Can side effects be auto-detected and cleaned up?
+
+Partially, yes, but not perfectly. This project currently does not provide automatic side-effect cleanup for host-page mutations.
+
+Limits of automatic cleanup:
+
+- It will not reliably undo monkey-patched globals.
+- It will not automatically remove all event listeners or timers.
+- It cannot safely revert all stateful third-party module internals.
+
+### Enable or disable specific modes
+
+The two runtime modes are registered by separate plugins:
+
+- `@jupyterlite/javascript-kernel-extension:kernel-iframe`
+- `@jupyterlite/javascript-kernel-extension:kernel-worker`
+
+You can disable either one using `disabledExtensions` in `jupyter-config-data`.
+
+Disable worker mode:
+
+```json
+{
+  "jupyter-config-data": {
+    "disabledExtensions": [
+      "@jupyterlite/javascript-kernel-extension:kernel-worker"
+    ]
+  }
+}
+```
+
+Disable iframe mode:
+
+```json
+{
+  "jupyter-config-data": {
+    "disabledExtensions": [
+      "@jupyterlite/javascript-kernel-extension:kernel-iframe"
+    ]
+  }
+}
+```
+
 ## Contributing
 
 ### Development install

examples/magic-imports.ipynb

@@ -15,7 +15,9 @@
    "source": [
     "## Importing npm Packages\n",
     "\n",
-    "Just use standard ES module import syntax with a package name:"
+    "Just use standard ES module import syntax with a package name.\n",
+    "\n",
+    "For host-page visuals in iframe mode, target `window.parent` explicitly.\n"
    ]
   },
   {
@@ -26,12 +28,27 @@
    "source": [
     "import confetti from 'canvas-confetti';\n",
     "\n",
-    "// Fire some confetti!\n",
-    "confetti({\n",
+    "const canvas = window.parent.document.createElement('canvas');\n",
+    "Object.assign(canvas.style, {\n",
+    "    position: 'fixed',\n",
+    "    inset: '0',\n",
+    "    width: '100%',\n",
+    "    height: '100%',\n",
+    "    pointerEvents: 'none',\n",
+    "    zIndex: '2147483647'\n",
+    "});\n",
+    "window.parent.document.body.appendChild(canvas);\n",
+    "\n",
+    "const fire = confetti.create(canvas, {\n",
+    "    resize: true,\n",
+    "    useWorker: true\n",
+    "});\n",
+    "\n",
+    "fire({\n",
     "    particleCount: 100,\n",
     "    spread: 70,\n",
     "    origin: { y: 0.6 }\n",
-    "});"
+    "});\n"
    ]
   },
   {
@@ -218,4 +235,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}

examples/rich-output.ipynb

@@ -237,6 +237,55 @@
     "canvas2"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## DOM Elements\n",
+    "\n",
+    "HTMLElement and SVGElement instances should render as rich output:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "const card = document.createElement('div');\n",
+    "card.style.cssText = 'padding:12px;border:1px solid #dadada;border-radius:8px;background:#fffbe6;font-family:sans-serif;';\n",
+    "card.innerHTML = '<strong>DOM element test</strong><br/><span>Rendered from runtime iframe scope.</span>';\n",
+    "\n",
+    "card"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');\n",
+    "svg.setAttribute('width', '220');\n",
+    "svg.setAttribute('height', '80');\n",
+    "\n",
+    "const rect = document.createElementNS('http://www.w3.org/2000/svg', 'rect');\n",
+    "rect.setAttribute('width', '220');\n",
+    "rect.setAttribute('height', '80');\n",
+    "rect.setAttribute('rx', '10');\n",
+    "rect.setAttribute('fill', '#d9f2ff');\n",
+    "\n",
+    "const text = document.createElementNS('http://www.w3.org/2000/svg', 'text');\n",
+    "text.setAttribute('x', '16');\n",
+    "text.setAttribute('y', '46');\n",
+    "text.setAttribute('font-size', '20');\n",
+    "text.setAttribute('font-family', 'sans-serif');\n",
+    "text.textContent = 'SVG element test';\n",
+    "\n",
+    "svg.append(rect, text);\n",
+    "svg"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -361,4 +410,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}

packages/javascript-kernel-extension/src/index.ts

@@ -11,45 +11,91 @@ import type { IKernel } from '@jupyterlite/services';
 import { IKernelSpecs } from '@jupyterlite/services';
 
 import { JavaScriptKernel } from '@jupyterlite/javascript-kernel';
+import type { RuntimeMode } from '@jupyterlite/javascript-kernel';
 
 import jsLogo32 from '../style/icons/logo-32x32.png';
 
 import jsLogo64 from '../style/icons/logo-64x64.png';
 
 /**
- * A plugin to register the JavaScript kernel.
+ * Register a JavaScript kernelspec for a given runtime.
  */
-const kernel: JupyterFrontEndPlugin<void> = {
-  id: '@jupyterlite/javascript-kernel-extension:kernel',
-  autoStart: true,
-  requires: [IKernelSpecs],
-  activate: (app: JupyterFrontEnd, kernelspecs: IKernelSpecs) => {
-    kernelspecs.register({
+interface IRegisterKernelOptions {
+  name: string;
+  displayName: string;
+  runtime: RuntimeMode;
+}
+
+const registerKernel = (
+  kernelspecs: IKernelSpecs,
+  options: IRegisterKernelOptions
+) => {
+  const { name, displayName, runtime } = options;
+
+  kernelspecs.register({
+    spec: {
+      name,
+      display_name: displayName,
+      language: 'javascript',
+      argv: [],
       spec: {
-        name: 'javascript',
-        display_name: 'JavaScript',
-        language: 'javascript',
         argv: [],
-        spec: {
-          argv: [],
-          env: {},
-          display_name: 'JavaScript',
-          language: 'javascript',
-          interrupt_mode: 'message',
-          metadata: {}
-        },
-        resources: {
-          'logo-32x32': jsLogo32,
-          'logo-64x64': jsLogo64
+        env: {},
+        display_name: displayName,
+        language: 'javascript',
+        interrupt_mode: 'message',
+        metadata: {
+          runtime
         }
       },
-      create: async (options: IKernel.IOptions): Promise<IKernel> => {
-        return new JavaScriptKernel(options);
+      resources: {
+        'logo-32x32': jsLogo32,
+        'logo-64x64': jsLogo64
       }
+    },
+    create: async (options: IKernel.IOptions): Promise<IKernel> => {
+      return new JavaScriptKernel({
+        ...options,
+        runtime
+      } as JavaScriptKernel.IOptions);
+    }
+  });
+};
+
+/**
+ * Plugin registering the iframe JavaScript kernel.
+ */
+const kernelIFrame: JupyterFrontEndPlugin<void> = {
+  id: '@jupyterlite/javascript-kernel-extension:kernel-iframe',
+  autoStart: true,
+  requires: [IKernelSpecs],
+  activate: (app: JupyterFrontEnd, kernelspecs: IKernelSpecs) => {
+    void app;
+    registerKernel(kernelspecs, {
+      name: 'javascript',
+      displayName: 'JavaScript',
+      runtime: 'iframe'
+    });
+  }
+};
+
+/**
+ * Plugin registering the worker JavaScript kernel.
+ */
+const kernelWorker: JupyterFrontEndPlugin<void> = {
+  id: '@jupyterlite/javascript-kernel-extension:kernel-worker',
+  autoStart: true,
+  requires: [IKernelSpecs],
+  activate: (app: JupyterFrontEnd, kernelspecs: IKernelSpecs) => {
+    void app;
+    registerKernel(kernelspecs, {
+      name: 'javascript-worker',
+      displayName: 'JavaScript (Worker)',
+      runtime: 'worker'
     });
   }
 };
 
-const plugins: JupyterFrontEndPlugin<void>[] = [kernel];
+const plugins: JupyterFrontEndPlugin<void>[] = [kernelIFrame, kernelWorker];
 
 export default plugins;