Add startup extensions for JavaScript kernels

Author: MUFFANUJ

README.md

@@ -40,6 +40,51 @@ The extension currently registers two JavaScript kernelspecs:
 
 Pick either kernel from the notebook kernel selector in JupyterLite.
 
+### Kernel startup extensions
+
+Frontend extensions can register startup work that runs before user code in
+both runtime modes. Use this to preload runtime modules and register comm
+targets without sending bootstrap code through `requestExecute`.
+
+```typescript
+import type { JupyterFrontEndPlugin } from '@jupyterlab/application';
+import { IJavaScriptKernelStartup } from '@jupyterlite/javascript-kernel';
+
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: 'my-extension:javascript-startup',
+  autoStart: true,
+  requires: [IJavaScriptKernelStartup],
+  activate: (app, startup) => {
+    const runtimeBootstrap = new URL(
+      './runtime-bootstrap.js',
+      import.meta.url
+    ).toString();
+    const lspCommTarget = new URL(
+      './lsp-comm-target.js',
+      import.meta.url
+    ).toString();
+
+    startup.registerStartupExtension({
+      id: 'my-extension:lsp',
+      modulePreloads: [runtimeBootstrap],
+      commTargets: [
+        {
+          targetName: 'my-extension:lsp',
+          module: lspCommTarget,
+          exportName: 'registerLspTarget'
+        }
+      ]
+    });
+  }
+};
+```
+
+Each `commTargets` entry imports the module in the kernel runtime and passes
+the exported handler to `Jupyter.comm.registerTarget(targetName, handler)`.
+The default export is used when `exportName` is omitted.
+Disposing a startup registration removes declared comm targets from active
+kernels; use an optional `deactivate` callback for extra cleanup.
+
 ### Worker mode limitations
 
 Web Workers do not expose DOM APIs. In `JavaScript (Web Worker)`, APIs such as `document`, direct element access, and other main-thread-only browser APIs are unavailable.

packages/javascript-kernel-extension/package.json

@@ -41,7 +41,8 @@
   "dependencies": {
     "@jupyterlab/application": "^4.5.5",
     "@jupyterlite/javascript-kernel": "^0.4.0-alpha.4",
-    "@jupyterlite/services": "^0.7.0"
+    "@jupyterlite/services": "^0.7.0",
+    "@lumino/disposable": "^2.1.5"
   },
   "devDependencies": {
     "@jupyterlab/builder": "^4.5.5",
@@ -56,6 +57,9 @@
     "extension": true,
     "outputDir": "../../jupyterlite_javascript_kernel/labextension",
     "sharedPackages": {
+      "@jupyterlite/javascript-kernel": {
+        "singleton": true
+      },
       "@jupyterlite/services": {
         "bundled": false,
         "singleton": true

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

@@ -9,8 +9,13 @@ import {
 import type { IKernel } from '@jupyterlite/services';
 
 import { IKernelSpecs } from '@jupyterlite/services';
+import { DisposableDelegate } from '@lumino/disposable';
+import type { IDisposable } from '@lumino/disposable';
 
-import { JavaScriptKernel } from '@jupyterlite/javascript-kernel';
+import {
+  IJavaScriptKernelStartup,
+  JavaScriptKernel
+} from '@jupyterlite/javascript-kernel';
 import type { RuntimeMode } from '@jupyterlite/javascript-kernel';
 
 import jsLogo32 from '../style/icons/logo-32x32.png';
@@ -24,13 +29,14 @@ interface IRegisterKernelOptions {
   name: string;
   displayName: string;
   runtime: RuntimeMode;
+  startup: IJavaScriptKernelStartup;
 }
 
 const registerKernel = (
   kernelspecs: IKernelSpecs,
   options: IRegisterKernelOptions
 ) => {
-  const { name, displayName, runtime } = options;
+  const { name, displayName, runtime, startup } = options;
 
   kernelspecs.register({
     spec: {
@@ -54,26 +60,111 @@ const registerKernel = (
       }
     },
     create: async (options: IKernel.IOptions): Promise<IKernel> => {
-      return new JavaScriptKernel({
+      const kernel = new JavaScriptKernel({
         ...options,
-        runtime
+        runtime,
+        startupExtensions: startup.startupExtensions
       } as JavaScriptKernel.IOptions);
+      if (startup instanceof JavaScriptKernelStartup) {
+        startup.trackKernel(kernel);
+      }
+      return kernel;
     }
   });
 };
 
+/**
+ * In-memory registry for JavaScript kernel startup extensions.
+ */
+class JavaScriptKernelStartup implements IJavaScriptKernelStartup {
+  get startupExtensions(): readonly JavaScriptKernel.IStartupExtension[] {
+    return [...this._startupExtensions];
+  }
+
+  registerStartupExtension(
+    extension: JavaScriptKernel.IStartupExtension
+  ): IDisposable {
+    const existing = this._startupExtensions.findIndex(
+      item => item.id === extension.id
+    );
+
+    if (existing !== -1) {
+      throw new Error(
+        `JavaScript kernel startup extension "${extension.id}" is already registered`
+      );
+    }
+
+    this._startupExtensions.push(extension);
+    void Promise.all(
+      [...this._kernels].map(kernel => kernel.applyStartupExtension(extension))
+    ).catch(error => {
+      console.error(
+        `[javascript-kernel] Failed to apply startup extension "${extension.id}".`,
+        error
+      );
+    });
+
+    return new DisposableDelegate(() => {
+      const index = this._startupExtensions.indexOf(extension);
+      if (index !== -1) {
+        this._startupExtensions.splice(index, 1);
+        void Promise.all(
+          [...this._kernels].map(kernel =>
+            kernel.removeStartupExtension(extension)
+          )
+        ).catch(error => {
+          console.error(
+            `[javascript-kernel] Failed to remove startup extension "${extension.id}".`,
+            error
+          );
+        });
+      }
+    });
+  }
+
+  /**
+   * Track an active JavaScript kernel for late startup registrations.
+   */
+  trackKernel(kernel: JavaScriptKernel): void {
+    this._kernels.add(kernel);
+    const untrackKernel = (sender: JavaScriptKernel): void => {
+      this._kernels.delete(sender);
+      sender.disposed.disconnect(untrackKernel);
+    };
+    kernel.disposed.connect(untrackKernel);
+  }
+
+  private _startupExtensions: JavaScriptKernel.IStartupExtension[] = [];
+  private _kernels = new Set<JavaScriptKernel>();
+}
+
+/**
+ * Plugin providing the JavaScript kernel startup extension registry.
+ */
+const startupExtensions: JupyterFrontEndPlugin<IJavaScriptKernelStartup> = {
+  id: '@jupyterlite/javascript-kernel-extension:startup-extensions',
+  autoStart: true,
+  provides: IJavaScriptKernelStartup,
+  activate: () => new JavaScriptKernelStartup()
+};
+
 /**
  * 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) => {
+  requires: [IKernelSpecs, IJavaScriptKernelStartup],
+  activate: (
+    app: JupyterFrontEnd,
+    kernelspecs: IKernelSpecs,
+    startup: IJavaScriptKernelStartup
+  ) => {
     registerKernel(kernelspecs, {
       name: 'javascript',
       displayName: 'JavaScript (IFrame)',
-      runtime: 'iframe'
+      runtime: 'iframe',
+      startup
     });
   }
 };
@@ -84,16 +175,23 @@ const kernelIFrame: JupyterFrontEndPlugin<void> = {
 const kernelWorker: JupyterFrontEndPlugin<void> = {
   id: '@jupyterlite/javascript-kernel-extension:kernel-worker',
   autoStart: true,
-  requires: [IKernelSpecs],
-  activate: (app: JupyterFrontEnd, kernelspecs: IKernelSpecs) => {
+  requires: [IKernelSpecs, IJavaScriptKernelStartup],
+  activate: (
+    app: JupyterFrontEnd,
+    kernelspecs: IKernelSpecs,
+    startup: IJavaScriptKernelStartup
+  ) => {
     registerKernel(kernelspecs, {
       name: 'javascript-worker',
       displayName: 'JavaScript (Web Worker)',
-      runtime: 'worker'
+      runtime: 'worker',
+      startup
     });
   }
 };
 
-const plugins: JupyterFrontEndPlugin<void>[] = [kernelIFrame, kernelWorker];
+const plugins: Array<
+  JupyterFrontEndPlugin<IJavaScriptKernelStartup> | JupyterFrontEndPlugin<void>
+> = [startupExtensions, kernelIFrame, kernelWorker];
 
 export default plugins;

packages/javascript-kernel/package.json

@@ -47,6 +47,7 @@
     "@jupyterlab/nbformat": "^4.5.0",
     "@jupyterlite/services": "^0.7.0",
     "@lumino/coreutils": "^2.2.2",
+    "@lumino/disposable": "^2.1.5",
     "astring": "^1.9.0",
     "comlink": "^4.3.1",
     "meriyah": "^4.3.9"

packages/javascript-kernel/src/comm/manager.ts

@@ -76,6 +76,20 @@ export class CommManager {
     this._targets.set(targetName, handler);
   }
 
+  /**
+   * Whether a comm target handler is registered.
+   */
+  hasTarget(targetName: string): boolean {
+    return this._targets.has(targetName);
+  }
+
+  /**
+   * Remove a comm target handler registration.
+   */
+  unregisterTarget(targetName: string): void {
+    this._targets.delete(targetName);
+  }
+
   /**
    * Register a widget instance by comm ID.
    */

packages/javascript-kernel/src/executor.ts

@@ -292,6 +292,18 @@ export class JavaScriptExecutor {
     return lines.join('\n');
   }
 
+  /**
+   * Import a module using the executor's import source resolution.
+   */
+  async importModule(source: string): Promise<Record<string, any>> {
+    const importSource = this._transformImportSource(source);
+    const importFunction = this._createScopedFunction(
+      'source',
+      'return import(source);'
+    ) as (source: string) => Promise<Record<string, any>>;
+    return importFunction.call(this._globalScope, importSource);
+  }
+
   /**
    * Create a new empty code registry.
    */

packages/javascript-kernel/src/index.ts

@@ -9,3 +9,4 @@ export * from './runtime_backends';
 export * from './runtime_evaluator';
 export * from './comm';
 export * from './widgets';
+export * from './startup';