fix: split jquery import in widgets

Author: righ

packages/widgets/src/jquery-shim.ts

@@ -0,0 +1,16 @@
+// Side-effect-only module: seed `globalThis.jQuery` / `$` BEFORE any
+// downstream code (jquery-ui via @jupyter-widgets/controls/slider) tries
+// to detect them.
+//
+// ES module evaluation is post-order across the dep graph. By isolating
+// this in its own file and importing it FIRST in runtime.ts, jquery
+// itself + this body run to completion before @jupyter-widgets/html-manager
+// (and the jquery-ui graph it pulls) start evaluating. If we kept this
+// inline in runtime.ts, all `import` statements would hoist together and
+// the assignment below would race jquery-ui's init.
+// @ts-expect-error — jquery has no bundled .d.ts
+import jquery from 'jquery';
+
+const g = globalThis as unknown as { jQuery?: unknown; $?: unknown };
+if (!g.jQuery) g.jQuery = jquery;
+if (!g.$) g.$ = jquery;

packages/widgets/src/runtime.ts

@@ -1,16 +1,12 @@
 import type { CommProvider } from '@jupyter-kit/comm';
 
-// `@jupyter-widgets/controls` slider widgets transitively depend on
-// jquery-ui, which expects `jQuery` / `$` on the global scope at module
-// init. Browser bundlers don't auto-expose CJS-style globals, so we
-// must seed `globalThis` before the html-manager module loads (its
-// import graph reaches jquery-ui synchronously).
-// @ts-expect-error — jquery has no bundled .d.ts
-import jquery from 'jquery';
-const g = globalThis as unknown as { jQuery?: unknown; $?: unknown };
-if (!g.jQuery) g.jQuery = jquery;
-if (!g.$) g.$ = jquery;
-
+// MUST be imported before @jupyter-widgets/html-manager. The shim sets
+// `globalThis.jQuery` (required by jquery-ui's slider init, which
+// @jupyter-widgets/controls pulls in synchronously). ES module imports
+// hoist together within a file, so inlining the assignment here would
+// race html-manager's evaluation. Keeping it as a separate side-effect
+// import puts jquery + the assignment fully ahead in the eval order.
+import './jquery-shim';
 import { HTMLManager } from '@jupyter-widgets/html-manager';
 
 // Widget CSS is shipped with `@jupyter-widgets/controls` but html-manager only

packages/widgets/tsup.config.ts

@@ -1,12 +1,24 @@
 import { defineConfig } from 'tsup';
 
 export default defineConfig({
-  entry: ['src/index.ts', 'src/runtime.ts'],
+  // jquery-shim is a separate entry (rather than inlined into runtime.ts)
+  // so the consuming JS engine evaluates it as its own module — ES module
+  // post-order then guarantees `globalThis.jQuery = ...` completes before
+  // any html-manager import body (and the jquery-ui graph it pulls)
+  // begins evaluating. Inlining loses that ordering because all `import`s
+  // within a single file hoist above the body.
+  entry: ['src/index.ts', 'src/runtime.ts', 'src/jquery-shim.ts'],
   format: ['esm'],
   dts: true,
   sourcemap: true,
   clean: true,
   target: 'es2020',
+  // @jupyter-widgets/* and friends stay external — bundling them in
+  // surfaces esbuild's __require/__commonJS shims into the published dist,
+  // and those break in some browser scenarios (Proxy traps trip on init,
+  // Node-only branches throw). Downstream bundlers (Vite/webpack) handle
+  // the upstream CJS-flavoured ESM without our intervention; we only need
+  // to document the one Vite-specific config tweak (commonjsOptions).
   external: [
     '@jupyter-kit/core',
     '@jupyter-kit/comm',