From 0a880efa72a84d8a06fdac83a74880a6f47f2bf4 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 23 Sep 2026 17:54:20 +0000
Subject: [PATCH 1/5] Initial plan


From ddde1c141e727c12eee8bfb9c240ebed70089b48 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 23 Sep 2026 18:03:34 +0000
Subject: [PATCH 2/5] feat: add ESM and CJS module builds for bundler support

---
 .changeset/esm-module-exports.md | 10 ++++++
 docs/developer-guide.md          |  2 +-
 esbuild.config.js                | 55 ++++++++++++++++++++++++++------
 packages/utils/package.json      | 15 ++++++++-
 packages/yasgui/package.json     | 16 +++++++++-
 packages/yasqe/package.json      | 16 +++++++++-
 packages/yasr/package.json       | 16 +++++++++-
 7 files changed, 116 insertions(+), 14 deletions(-)
 create mode 100644 .changeset/esm-module-exports.md

diff --git a/.changeset/esm-module-exports.md b/.changeset/esm-module-exports.md
new file mode 100644
index 00000000..50ac5b3d
--- /dev/null
+++ b/.changeset/esm-module-exports.md
@@ -0,0 +1,10 @@
+---
+"@matdata/yasgui-utils": minor
+"@matdata/yasqe": minor
+"@matdata/yasr": minor
+"@matdata/yasgui": minor
+---
+
+Ship ES module and CommonJS builds so the packages can be imported by bundlers (Vite/webpack/esbuild) and Node.
+
+Each package now builds three bundles: an ES module (`*.mjs`), a CommonJS module (`*.cjs`) and the existing browser global IIFE (`*.min.js`). The `package.json` of every package exposes them through `main` (CommonJS), `module` (ESM), `unpkg`/`jsdelivr` (browser global) and a conditional `exports` map with `import`, `require`, `types` and `default` entries. This makes the documented `import Yasgui from "@matdata/yasgui"` usage work in module bundlers, while `<script src=".../build/yasgui.min.js">` keeps exposing the global.
diff --git a/docs/developer-guide.md b/docs/developer-guide.md
index 612a8a40..710a95aa 100644
--- a/docs/developer-guide.md
+++ b/docs/developer-guide.md
@@ -452,7 +452,7 @@ const yasgui = new Yasgui(document.getElementById('yasgui'), {
 ### CommonJS
 
 ```javascript
-const Yasgui = require('@matdata/yasgui');
+const Yasgui = require('@matdata/yasgui').default;
 require('@matdata/yasgui/build/yasgui.min.css');
 
 const yasgui = new Yasgui(document.getElementById('yasgui'));
diff --git a/esbuild.config.js b/esbuild.config.js
index de7de4ce..9fef5af7 100644
--- a/esbuild.config.js
+++ b/esbuild.config.js
@@ -93,8 +93,29 @@ const commonConfig = {
   },
 };
 
+// Rename the CSS output emitted by a build to the canonical `<name>.min.css`.
+function extractCss(result, name) {
+  if (!result.metafile) return;
+  const cssOutput = Object.keys(result.metafile.outputs).find((o) => o.endsWith(".css"));
+  if (cssOutput && fs.existsSync(cssOutput)) {
+    fs.renameSync(cssOutput, `build/${name}.min.css`);
+  }
+}
+
+// Remove the CSS (and its sourcemap) emitted by a build. The ESM/CJS bundles
+// import the same styles as the IIFE build, so a single `<name>.min.css` is kept.
+function removeExtraCss(result) {
+  if (!result.metafile) return;
+  for (const output of Object.keys(result.metafile.outputs)) {
+    if (output.endsWith(".css") || output.endsWith(".css.map")) {
+      if (fs.existsSync(output)) fs.rmSync(output);
+    }
+  }
+}
+
 async function buildPackage(name, entryPoint, globalName) {
-  const result = await esbuild.build({
+  // IIFE build: exposes a browser global (e.g. `window.Yasgui`) for <script> usage.
+  const iifeResult = await esbuild.build({
     ...commonConfig,
     entryPoints: [entryPoint],
     outfile: `build/${name}.min.js`,
@@ -107,15 +128,31 @@ async function buildPackage(name, entryPoint, globalName) {
       js: `if (typeof ${globalName} !== 'undefined' && ${globalName}?.default) { ${globalName} = ${globalName}.default; }`,
     },
   });
+  extractCss(iifeResult, name);
 
-  // Extract CSS if any was bundled
-  if (result.metafile) {
-    const outputs = Object.keys(result.metafile.outputs);
-    const cssOutput = outputs.find((o) => o.endsWith(".css"));
-    if (cssOutput && fs.existsSync(cssOutput)) {
-      fs.renameSync(cssOutput, `build/${name}.min.css`);
-    }
-  }
+  // ESM build: consumed by bundlers (vite/webpack/esbuild) and Node via `import`.
+  // Uses the `.mjs` extension so it is always treated as an ES module.
+  const esmResult = await esbuild.build({
+    ...commonConfig,
+    entryPoints: [entryPoint],
+    outfile: `build/${name}.mjs`,
+    format: "esm",
+    platform: "browser",
+    metafile: true,
+  });
+  removeExtraCss(esmResult);
+
+  // CJS build: consumed by Node's `require`. Uses the `.cjs` extension so it is
+  // always treated as CommonJS regardless of the nearest package.json `type`.
+  const cjsResult = await esbuild.build({
+    ...commonConfig,
+    entryPoints: [entryPoint],
+    outfile: `build/${name}.cjs`,
+    format: "cjs",
+    platform: "browser",
+    metafile: true,
+  });
+  removeExtraCss(cjsResult);
 }
 
 async function buildTypeDeclarations() {
diff --git a/packages/utils/package.json b/packages/utils/package.json
index fdf21183..6d4ed237 100644
--- a/packages/utils/package.json
+++ b/packages/utils/package.json
@@ -2,8 +2,21 @@
   "name": "@matdata/yasgui-utils",
   "version": "4.6.1",
   "description": "Shared utilities for MatGUI (formerly Yasgui) packages.",
-  "main": "build/utils.min.js",
+  "main": "build/utils.cjs",
+  "module": "build/utils.mjs",
+  "unpkg": "build/utils.min.js",
+  "jsdelivr": "build/utils.min.js",
   "types": "build/ts/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/ts/src/index.d.ts",
+      "import": "./build/utils.mjs",
+      "require": "./build/utils.cjs",
+      "default": "./build/utils.mjs"
+    },
+    "./build/*": "./build/*",
+    "./package.json": "./package.json"
+  },
   "license": "MIT",
   "author": "Triply <info@triply.cc>",
   "homepage": "https://github.com/Matdata-eu/Yasgui",
diff --git a/packages/yasgui/package.json b/packages/yasgui/package.json
index 91940caa..a81f0c66 100644
--- a/packages/yasgui/package.json
+++ b/packages/yasgui/package.json
@@ -2,8 +2,22 @@
   "name": "@matdata/yasgui",
   "description": "MatGUI: a modern SPARQL query editor and results viewer for knowledge graphs and linked data (formerly Yasgui).",
   "version": "4.6.1",
-  "main": "build/yasgui.min.js",
+  "main": "build/yasgui.cjs",
+  "module": "build/yasgui.mjs",
+  "unpkg": "build/yasgui.min.js",
+  "jsdelivr": "build/yasgui.min.js",
   "types": "build/ts/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/ts/src/index.d.ts",
+      "import": "./build/yasgui.mjs",
+      "require": "./build/yasgui.cjs",
+      "default": "./build/yasgui.mjs"
+    },
+    "./build/yasgui.min.css": "./build/yasgui.min.css",
+    "./build/*": "./build/*",
+    "./package.json": "./package.json"
+  },
   "license": "MIT",
   "author": "Triply <info@triply.cc>",
   "homepage": "https://github.com/Matdata-eu/Yasgui",
diff --git a/packages/yasqe/package.json b/packages/yasqe/package.json
index 26293cfc..f4b6f462 100644
--- a/packages/yasqe/package.json
+++ b/packages/yasqe/package.json
@@ -2,8 +2,22 @@
   "name": "@matdata/yasqe",
   "description": "MatGUI query editor: a modern SPARQL query editor (formerly Yasgui/YASQE).",
   "version": "4.6.1",
-  "main": "build/yasqe.min.js",
+  "main": "build/yasqe.cjs",
+  "module": "build/yasqe.mjs",
+  "unpkg": "build/yasqe.min.js",
+  "jsdelivr": "build/yasqe.min.js",
   "types": "build/ts/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/ts/src/index.d.ts",
+      "import": "./build/yasqe.mjs",
+      "require": "./build/yasqe.cjs",
+      "default": "./build/yasqe.mjs"
+    },
+    "./build/yasqe.min.css": "./build/yasqe.min.css",
+    "./build/*": "./build/*",
+    "./package.json": "./package.json"
+  },
   "license": "MIT",
   "author": "Triply <info@triply.cc>",
   "homepage": "https://github.com/Matdata-eu/Yasgui",
diff --git a/packages/yasr/package.json b/packages/yasr/package.json
index 0c200721..0d73d2bc 100644
--- a/packages/yasr/package.json
+++ b/packages/yasr/package.json
@@ -2,8 +2,22 @@
   "name": "@matdata/yasr",
   "description": "MatGUI results viewer: a modern SPARQL result set viewer (formerly Yasgui/YASR).",
   "version": "4.6.1",
-  "main": "build/yasr.min.js",
+  "main": "build/yasr.cjs",
+  "module": "build/yasr.mjs",
+  "unpkg": "build/yasr.min.js",
+  "jsdelivr": "build/yasr.min.js",
   "types": "build/ts/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/ts/src/index.d.ts",
+      "import": "./build/yasr.mjs",
+      "require": "./build/yasr.cjs",
+      "default": "./build/yasr.mjs"
+    },
+    "./build/yasr.min.css": "./build/yasr.min.css",
+    "./build/*": "./build/*",
+    "./package.json": "./package.json"
+  },
   "license": "MIT",
   "author": "Triply <info@triply.cc>",
   "homepage": "https://github.com/Matdata-eu/Yasgui",

From b4d77c89657ff342dc437ea1cda10c1b7b445bfb Mon Sep 17 00:00:00 2001
From: Mathias Vanden Auweele <mathias@matdata.eu>
Date: Wed, 23 Sep 2026 21:50:18 +0200
Subject: [PATCH 3/5] chore: added tests for package consumption

---
 test/unit/package-consumption-test.ts | 208 ++++++++++++++++++++++++++
 1 file changed, 208 insertions(+)
 create mode 100644 test/unit/package-consumption-test.ts

diff --git a/test/unit/package-consumption-test.ts b/test/unit/package-consumption-test.ts
new file mode 100644
index 00000000..36bd3bff
--- /dev/null
+++ b/test/unit/package-consumption-test.ts
@@ -0,0 +1,208 @@
+import * as chai from "chai";
+import { describe, it, before, after } from "mocha";
+import { execSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+const expect = chai.expect;
+
+// process.cwd() is the repo root when mocha is invoked via the package scripts.
+const repoRoot = process.cwd();
+
+/**
+ * Regression tests for issue #185: verify that the npm package produced for
+ * @matdata/yasgui can be consumed by real JavaScript tooling.
+ *
+ * The tests intentionally go through `npm pack` so they exercise the same
+ * artifact that a user receives from the npm registry, not a direct source
+ * import.
+ */
+describe("Package consumption: @matdata/yasgui published artifact (regression #185)", function () {
+  let tmpDir: string;
+  let packageDir: string; // the "package/" directory unpacked from the tarball
+
+  before(function () {
+    this.timeout(60_000);
+
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "yasgui-pkg-test-"));
+    const packDest = path.join(tmpDir, "pack");
+    fs.mkdirSync(packDest);
+
+    execSync(`npm pack --pack-destination "${packDest}"`, {
+      cwd: path.join(repoRoot, "packages", "yasgui"),
+      stdio: "pipe",
+    });
+
+    const tarballs = fs.readdirSync(packDest).filter((f) => f.endsWith(".tgz"));
+    if (tarballs.length !== 1) {
+      throw new Error(`Expected exactly 1 tarball in pack dest, found: ${JSON.stringify(tarballs)}`);
+    }
+    const tarball = path.join(packDest, tarballs[0]);
+
+    // npm pack always places extracted content under a "package/" sub-directory.
+    execSync(`tar -xzf "${tarball}" -C "${tmpDir}"`);
+    packageDir = path.join(tmpDir, "package");
+  });
+
+  after(function () {
+    if (tmpDir && fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  /** Copies the extracted package into a consumer directory's node_modules. */
+  function installPackageIntoConsumer(consumerDir: string): void {
+    const dest = path.join(consumerDir, "node_modules", "@matdata", "yasgui");
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.cpSync(packageDir, dest, { recursive: true });
+  }
+
+  // ── artifact structure ─────────────────────────────────────────────────────
+
+  it("tarball contains ESM, CJS and CSS build artifacts", () => {
+    const buildDir = path.join(packageDir, "build");
+    for (const file of ["yasgui.mjs", "yasgui.cjs", "yasgui.min.css"]) {
+      expect(fs.existsSync(path.join(buildDir, file)), `build/${file} must exist in the tarball`).to.be.true;
+    }
+  });
+
+  it("package.json exports['.'].import resolves to an existing file", () => {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageDir, "package.json"), "utf8"));
+    const importEntry: unknown = pkg?.exports?.["."]?.import;
+    expect(importEntry, "exports['.'].import must be a string").to.be.a("string");
+    expect(
+      fs.existsSync(path.join(packageDir, importEntry as string)),
+      `exports['.'].import path '${importEntry}' must exist in the package`,
+    ).to.be.true;
+  });
+
+  it("package.json exports['.'].require resolves to an existing file", () => {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageDir, "package.json"), "utf8"));
+    const requireEntry: unknown = pkg?.exports?.["."]?.require;
+    expect(requireEntry, "exports['.'].require must be a string").to.be.a("string");
+    expect(
+      fs.existsSync(path.join(packageDir, requireEntry as string)),
+      `exports['.'].require path '${requireEntry}' must exist in the package`,
+    ).to.be.true;
+  });
+
+  // ── ESM consumer ──────────────────────────────────────────────────────────
+
+  // Yasgui is a browser-only package (it accesses the DOM at module init time)
+  // so we cannot execute it in a plain Node.js process. Instead we verify that
+  // the `exports` field resolves the bare import `@matdata/yasgui` to the .mjs
+  // build — the exact mapping that was broken in issue #185. The Vite test
+  // below covers end-to-end bundler consumption including the default export.
+  it("ESM: `import '@matdata/yasgui'` resolves via exports field to the .mjs build", function () {
+    const consumerDir = path.join(tmpDir, "esm-consumer");
+    fs.mkdirSync(consumerDir, { recursive: true });
+    installPackageIntoConsumer(consumerDir);
+
+    fs.writeFileSync(
+      path.join(consumerDir, "package.json"),
+      JSON.stringify({ name: "esm-consumer", type: "module", version: "0.0.0" }),
+    );
+    // import.meta.resolve() checks the exports field without executing the module.
+    fs.writeFileSync(
+      path.join(consumerDir, "consumer.mjs"),
+      [
+        `const url = import.meta.resolve("@matdata/yasgui");`,
+        `if (!url.includes("yasgui.mjs"))`,
+        `  throw new Error("Expected .mjs resolution, got: " + url);`,
+        `console.log("ESM resolution OK:", url.split("/").pop());`,
+      ].join("\n"),
+    );
+
+    const out = execSync("node consumer.mjs", {
+      cwd: consumerDir,
+      encoding: "utf8",
+      stdio: "pipe",
+    });
+    expect(out.trim()).to.match(/^ESM resolution OK:/);
+  });
+
+  // ── CJS consumer ──────────────────────────────────────────────────────────
+
+  it("CJS: `require('@matdata/yasgui')` resolves via exports field to the .cjs build", function () {
+    const consumerDir = path.join(tmpDir, "cjs-consumer");
+    fs.mkdirSync(consumerDir, { recursive: true });
+    installPackageIntoConsumer(consumerDir);
+
+    fs.writeFileSync(
+      path.join(consumerDir, "package.json"),
+      JSON.stringify({ name: "cjs-consumer", version: "0.0.0" }),
+    );
+    // require.resolve() checks the exports field without executing the module.
+    fs.writeFileSync(
+      path.join(consumerDir, "consumer.cjs"),
+      [
+        `const resolved = require.resolve("@matdata/yasgui");`,
+        `if (!resolved.endsWith(".cjs"))`,
+        `  throw new Error("Expected .cjs resolution, got: " + resolved);`,
+        `console.log("CJS resolution OK:", resolved.split(/[\\/]/).pop());`,
+      ].join("\n"),
+    );
+
+    const out = execSync("node consumer.cjs", {
+      cwd: consumerDir,
+      encoding: "utf8",
+      stdio: "pipe",
+    });
+    expect(out.trim()).to.match(/^CJS resolution OK:/);
+  });
+
+  // ── Vite consumer ─────────────────────────────────────────────────────────
+
+  it("Vite: `vite build` succeeds when importing Yasgui and its CSS", function () {
+    this.timeout(90_000);
+    const consumerDir = path.join(tmpDir, "vite-consumer");
+    fs.mkdirSync(consumerDir, { recursive: true });
+    installPackageIntoConsumer(consumerDir);
+
+    fs.writeFileSync(
+      path.join(consumerDir, "package.json"),
+      JSON.stringify({ name: "vite-consumer", type: "module", version: "0.0.0" }),
+    );
+    fs.writeFileSync(
+      path.join(consumerDir, "main.js"),
+      [
+        `import Yasgui from "@matdata/yasgui";`,
+        `import "@matdata/yasgui/build/yasgui.min.css";`,
+        `export default Yasgui;`,
+      ].join("\n"),
+    );
+    fs.writeFileSync(
+      path.join(consumerDir, "vite.config.js"),
+      [
+        `export default {`,
+        `  build: {`,
+        `    lib: {`,
+        `      entry: "./main.js",`,
+        `      name: "TestApp",`,
+        `      fileName: "test-app",`,
+        `      formats: ["es"],`,
+        `    },`,
+        `    outDir: "./dist",`,
+        `  },`,
+        `  logLevel: "warn",`,
+        `};`,
+      ].join("\n"),
+    );
+
+    // Use the repo-local Vite via its entry script to avoid shell wrapper
+    // differences between platforms.
+    const nodeExec = process.execPath;
+    const viteScript = path.join(repoRoot, "node_modules", "vite", "bin", "vite.js");
+    execSync(`"${nodeExec}" "${viteScript}" build`, {
+      cwd: consumerDir,
+      encoding: "utf8",
+      stdio: "pipe",
+    });
+
+    const distJs = fs.existsSync(path.join(consumerDir, "dist"))
+      ? fs.readdirSync(path.join(consumerDir, "dist")).filter((f) => f.endsWith(".js"))
+      : [];
+    expect(distJs, "dist/ should contain at least one JS file after Vite build").to.have.length.greaterThan(0);
+  });
+});

From 0cb1839afef75fdfc28f30e26aa429bde56df6a4 Mon Sep 17 00:00:00 2001
From: Mathias Vanden Auweele <mathias@matdata.eu>
Date: Wed, 23 Sep 2026 22:16:25 +0200
Subject: [PATCH 4/5] Improve CSS extraction and renaming process

Refactor CSS extraction logic to handle renaming and sourcemaps more robustly.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 esbuild.config.js | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/esbuild.config.js b/esbuild.config.js
index 9fef5af7..f859d02d 100644
--- a/esbuild.config.js
+++ b/esbuild.config.js
@@ -97,8 +97,20 @@ const commonConfig = {
 function extractCss(result, name) {
   if (!result.metafile) return;
   const cssOutput = Object.keys(result.metafile.outputs).find((o) => o.endsWith(".css"));
-  if (cssOutput && fs.existsSync(cssOutput)) {
-    fs.renameSync(cssOutput, `build/${name}.min.css`);
+  if (!cssOutput || !fs.existsSync(cssOutput)) return;
+
+  const targetCss = `build/${name}.min.css`;
+  const sourceMap = `${cssOutput}.map`;
+  const targetMap = `${targetCss}.map`;
+
+  if (cssOutput !== targetCss) {
+    fs.renameSync(cssOutput, targetCss);
+    if (fs.existsSync(sourceMap)) fs.renameSync(sourceMap, targetMap);
+
+    // Keep the sourcemap reference consistent with the renamed file.
+    const css = fs.readFileSync(targetCss, "utf8");
+    const updated = css.replace(/sourceMappingURL=.*?\*\//, `sourceMappingURL=${path.basename(targetMap)} */`);
+    if (updated !== css) fs.writeFileSync(targetCss, updated);
   }
 }
 

From 7b443bc521f44172365186ff1f803ef1d21e9f35 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 23 Sep 2026 20:18:54 +0000
Subject: [PATCH 5/5] chore: update engines constraint to >=12 in yasqe and
 yasr package.json

Co-authored-by: MathiasVDA <15101339+MathiasVDA@users.noreply.github.com>
---
 packages/yasqe/package.json | 2 +-
 packages/yasr/package.json  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/yasqe/package.json b/packages/yasqe/package.json
index f4b6f462..92061dec 100644
--- a/packages/yasqe/package.json
+++ b/packages/yasqe/package.json
@@ -22,7 +22,7 @@
   "author": "Triply <info@triply.cc>",
   "homepage": "https://github.com/Matdata-eu/Yasgui",
   "engines": {
-    "node": ">= 8"
+    "node": ">= 12"
   },
   "keywords": [
     "JavaScript",
diff --git a/packages/yasr/package.json b/packages/yasr/package.json
index 0d73d2bc..fa93dddf 100644
--- a/packages/yasr/package.json
+++ b/packages/yasr/package.json
@@ -22,7 +22,7 @@
   "author": "Triply <info@triply.cc>",
   "homepage": "https://github.com/Matdata-eu/Yasgui",
   "engines": {
-    "node": ">= 8"
+    "node": ">= 12"
   },
   "keywords": [
     "JavaScript",